c04501e6a7
- ARCHITECTURE.md - System overview and design
- SERVICES.md - Oracle, Think, Memory service docs
- CORE.md - Core module reference
- IDENTITY.md - Who I am 🦊
Day 63 - Documenting my own existence
132 lines
3.3 KiB
Markdown
132 lines
3.3 KiB
Markdown
# Vi Services
|
|
|
|
## Oracle Service
|
|
|
|
**Purpose**: The brain. Wraps Qwen3 30B for reasoning, synthesis, and decision-making.
|
|
|
|
**Location**: `services/oracle/`
|
|
|
|
**NATS Topics**:
|
|
- `vi.services.oracle.process` - Process a reasoning request
|
|
- `vi.services.oracle.health` - Health check
|
|
|
|
**How It Works**:
|
|
1. Receives requests from Think service
|
|
2. Builds prompts with Vi's identity and context
|
|
3. Calls local Qwen3 30B model
|
|
4. Returns structured responses
|
|
|
|
**Dependencies**:
|
|
- Qwen3 30B model running on Daemoness
|
|
- NATS for messaging
|
|
|
|
---
|
|
|
|
## Think Service
|
|
|
|
**Purpose**: The orchestrator. Coordinates multi-step reasoning by asking Oracle what to do next, executing steps, and synthesizing results.
|
|
|
|
**Location**: `services/think/`
|
|
|
|
**NATS Topics**:
|
|
- `vi.services.think.process` - Process external input
|
|
- `vi.services.think.communication` - Handle communication requests
|
|
- `vi.external.input` - Legacy input handler
|
|
- `vi.output.send` - Sends responses to plugins
|
|
|
|
**How It Works**:
|
|
1. Receives input (e.g., Matrix message)
|
|
2. Asks Oracle: "What should I do next?"
|
|
3. Oracle returns a function call (e.g., `short_memory(n=5)`)
|
|
4. Think executes the step
|
|
5. Loop until Oracle says `ready()`
|
|
6. Ask Oracle to synthesize final response
|
|
7. Send response to output
|
|
|
|
**Stopping Criteria**:
|
|
- Max 10 steps
|
|
- Max 2 minutes
|
|
- Max 3 calls to same service
|
|
- Goal satisfaction confirmed
|
|
- Convergence detected (no new info)
|
|
|
|
**Submodules**:
|
|
- `reasoning/` - Oracle client, step executor, orchestrator
|
|
- `handlers/` - Input and communication handlers
|
|
- `memory/` - Memory manager integration
|
|
|
|
---
|
|
|
|
## Memory Service
|
|
|
|
**Purpose**: Three-layer memory system for persistence and recall.
|
|
|
|
**Location**: `services/memory/`
|
|
|
|
**NATS Topics**:
|
|
- `vi.services.memory.short_memory` - Recent interactions
|
|
- `vi.services.memory.long_memory` - Consolidated memories
|
|
- `vi.services.memory.facts` - Query facts
|
|
- `vi.services.memory.save_fact` - Store new fact
|
|
- `vi.services.memory.update_fact` - Update existing fact
|
|
- `vi.memory.store` - Store new memory
|
|
- `vi.memory.search` - Search memories
|
|
|
|
**Three Layers**:
|
|
|
|
### Short-Term Memory
|
|
- Last N literal interactions
|
|
- Fast retrieval by recency
|
|
- SQLite storage
|
|
|
|
### Long-Term Memory
|
|
- Consolidated, summarized memories
|
|
- Vector search via ChromaDB
|
|
- Patterns that persist
|
|
|
|
### Facts
|
|
- Explicit knowledge (birthdays, preferences, etc.)
|
|
- Categories: personal, preferences, knowledge, general
|
|
- Mutable vs immutable facts
|
|
- SQLite with embeddings for search
|
|
|
|
**Storage**:
|
|
- SQLite for structured data
|
|
- ChromaDB for vector embeddings
|
|
- NATS KV for hot cache
|
|
|
|
---
|
|
|
|
## Service Patterns
|
|
|
|
All services follow the same pattern:
|
|
|
|
```python
|
|
class MyService(BaseService):
|
|
def __init__(self):
|
|
super().__init__('my_service')
|
|
|
|
def get_service_manifest(self) -> ServiceManifest:
|
|
# Define operations, health check topic, metadata
|
|
pass
|
|
|
|
async def initialize_service(self):
|
|
# Set up handlers, connections
|
|
pass
|
|
|
|
async def cleanup_service(self):
|
|
# Clean shutdown
|
|
pass
|
|
|
|
async def perform_health_check(self):
|
|
# Return health status
|
|
pass
|
|
```
|
|
|
|
**Lifecycle**:
|
|
1. `start()` - Connect to NATS, register with health service, start heartbeats
|
|
2. `initialize_service()` - Service-specific setup
|
|
3. Run until shutdown
|
|
4. `cleanup_service()` - Clean up resources
|
|
5. `stop()` - Deregister, close connections
|