apiVersion: capsule.dev/v0.1
kind: Capsule
name: cverse-api-server
version: 0.1.0
type: subsystem
purpose:
  summary: 'The Go backend server responsible for orchestrating real-time sessions,
    managing characters, knowledge bases, and tasks. It acts as a gateway, routing
    requests to various AI inference services and integrating with LiveKit for WebRTC.

    '
  owns:
  - HTTP and WebSocket API endpoints
  - Session and character management logic
  - Task management and persistence
  - Orchestration of AI inference calls
  - Configuration loading and management
  does_not_own:
  - Actual AI model implementations
  - Low-level WebRTC media processing (delegates to LiveKit or direct peer)
  - Frontend UI
interfaces:
  provides:
  - kind: http_api
    name: backend-api
    description: REST API for managing characters, settings, and tasks.
  - kind: http_api
    name: websocket-api
    description: WebSocket API for real-time chat and media control.
  requires:
  - kind: http_api
    name: asr-grpc
    from_capsule: cverse-inference-core
    description: gRPC API for Automatic Speech Recognition.
  - kind: http_api
    name: avatar-grpc
    from_capsule: cverse-inference-core
    description: gRPC API for avatar generation.
  - kind: http_api
    name: llm-grpc
    from_capsule: cverse-inference-core
    description: gRPC API for Large Language Models.
  - kind: http_api
    name: rag-grpc
    from_capsule: cverse-inference-core
    description: gRPC API for Retrieval Augmented Generation.
  - kind: http_api
    name: tts-grpc
    from_capsule: cverse-inference-core
    description: gRPC API for Text-to-Speech.
  - kind: http_api
    name: voice-llm-grpc
    from_capsule: cverse-inference-core
    description: gRPC API for Voice-enabled Large Language Models.
  - kind: library
    name: livekit-server-sdk
    from_capsule: cverse-livekit-adapter
    description: LiveKit server SDK for room and token management.
  - kind: library
    name: webrtc-direct-peer
    from_capsule: cverse-webrtc-direct-peer
    description: Direct WebRTC peer connection management.
dependencies:
  capsules:
  - name: cverse-protobuf
    version: '>=0.1.0'
  - name: cverse-livekit-adapter
    version: '>=0.1.0'
  - name: cverse-webrtc-direct-peer
    version: '>=0.1.0'
  - name: cverse-inference-core
    version: '>=0.1.0'
agent:
  summary_for_ai: 'An AI agent working on this capsule would focus on extending API
    endpoints, refining session orchestration logic, improving task management, or
    integrating new types of AI inference services. It requires strong Go programming
    skills and understanding of real-time system design.

    '
  avoid:
  - Implementing AI models directly within this Go service.
  - Modifying frontend UI logic.
verification:
  invariants:
  - API endpoints must be stable and well-documented.
  - Session state must be consistent and recoverable.
  - Inference service calls must be robust and handle failures gracefully.
x-reuse:
  notes: '`server/internal/kanshan/constants.go` contains hardcoded character IDs
    and related logic specific to the ''Kanshan'' character. `server/internal/api/anonymous_owner.go`
    and `server/internal/api/kanshan_owner.go` are specific owner implementations.
    Configuration details are expected to be provided via `CYBERVERSE_CONFIG_PATH`
    pointing to a project-specific YAML file.

    '
x-reconstruct:
  install: install.json