vi/docs/CORE.md

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.

from core import config

nats_url = config.nats_url

logger.py

Structured logging with service context.

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.

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.

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.

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.

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.

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.

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}