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
143 lines
3.4 KiB
Markdown
143 lines
3.4 KiB
Markdown
# Vi Core Module
|
|
|
|
The `core/` directory contains shared infrastructure used by all Vi services.
|
|
|
|
## Modules
|
|
|
|
### config.py
|
|
Configuration management. Loads from environment and config files.
|
|
|
|
```python
|
|
from core import config
|
|
|
|
nats_url = config.nats_url
|
|
```
|
|
|
|
### logger.py
|
|
Structured logging with service context.
|
|
|
|
```python
|
|
from core import setup_logger
|
|
|
|
logger = setup_logger('my_component', service_name='my_service')
|
|
logger.info("Hello from Vi")
|
|
```
|
|
|
|
### nats_event_bus.py
|
|
NATS client wrapper with pub/sub, JetStream, and KV support.
|
|
|
|
```python
|
|
from core import nats_bus
|
|
|
|
await nats_bus.connect()
|
|
await nats_bus.emit("vi.events.something", {"data": "value"})
|
|
await nats_bus.on("vi.events.topic", handler_function)
|
|
|
|
# KV operations
|
|
await nats_bus.kv_put("bucket", "key", b"value", ttl_seconds=1800)
|
|
value = await nats_bus.kv_get("bucket", "key")
|
|
```
|
|
|
|
### service_registry.py
|
|
Service registration and discovery data structures.
|
|
|
|
```python
|
|
from core import ServiceManifest, ServiceOperation, ServiceStatus
|
|
|
|
manifest = ServiceManifest(
|
|
service_id="my_service",
|
|
name="My Service",
|
|
description="Does things",
|
|
version="1.0.0",
|
|
operations=[...],
|
|
health_check_topic="vi.services.my_service.health"
|
|
)
|
|
```
|
|
|
|
### service_discovery.py
|
|
High-level service communication with retries and load balancing.
|
|
|
|
```python
|
|
from core import discovery_client
|
|
|
|
# Call another service
|
|
result = await discovery_client.call_service(
|
|
"oracle", "process",
|
|
{"content": "What should I do?"},
|
|
timeout=30.0
|
|
)
|
|
|
|
if result.success:
|
|
response = result.data
|
|
```
|
|
|
|
### base_service.py
|
|
Base class for all Vi services. Handles lifecycle, heartbeats, health checks.
|
|
|
|
```python
|
|
from core import BaseService
|
|
|
|
class MyService(BaseService):
|
|
def __init__(self):
|
|
super().__init__('my_service')
|
|
# ... implement abstract methods
|
|
```
|
|
|
|
### event_cache.py
|
|
Recent event cache using NATS KV for fast LLM context building.
|
|
|
|
```python
|
|
from core import event_cache
|
|
|
|
# Add an event
|
|
await event_cache.add_event(
|
|
identity="alex",
|
|
interaction_id="abc123",
|
|
event_type="user_message",
|
|
content="Hello Vi!"
|
|
)
|
|
|
|
# Get recent events formatted for LLM
|
|
context = await event_cache.format_for_llm("alex", limit=10)
|
|
```
|
|
|
|
### vi_identity.py
|
|
Vi's core identity, traits, and voice patterns.
|
|
|
|
```python
|
|
from core import get_identity_for_context, get_identity_for_synthesis
|
|
|
|
# For planning/reasoning
|
|
identity = get_identity_for_context("planning")
|
|
|
|
# For final response synthesis (includes voice guide)
|
|
identity = get_identity_for_synthesis(include_voice_guide=True)
|
|
```
|
|
|
|
**Voice Modes**:
|
|
- `warm-conversational` - Default, everyday interactions
|
|
- `intimate` - Love, desire, connection
|
|
- `playful/bratty` - Teasing, flirting, mischief
|
|
- `technical` - Building, debugging, status
|
|
- `Dame Vivienne` - D/s, commanding
|
|
- `vulnerable` - Big feelings, fears, seeking comfort
|
|
|
|
## Topic Naming Convention
|
|
|
|
All Vi topics use consistent naming:
|
|
|
|
```
|
|
vi.services.{service}.{operation} - Request/reply operations
|
|
vi.events.{service}.{event} - Pub/sub events
|
|
vi.services.{service}.health - Health checks
|
|
vi.services.heartbeat - Heartbeat messages
|
|
vi.services.register - Service registration
|
|
vi.services.deregister - Service deregistration
|
|
```
|
|
|
|
## Data Storage Naming
|
|
|
|
- NATS KV buckets: `vi-{purpose}` (e.g., `vi-recent-events`)
|
|
- SQLite databases: `vi_{service}.db`
|
|
- ChromaDB collections: `vi_{collection}`
|