# 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}`