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