ai/CLAUDE.md

# @ai — The AI Assistant Runtime

**Location:** `~/Code/@applications/@ai/` — an @application, consumed by @projects

---

## What This Is

All AI cognition for the Lilith ecosystem lives here. This is the *mind* — identity, memory,
personality, nag, and context assembly. @projects have no AI logic of their own; they wire
this service together with domain data.

**Not to be confused with:**
- `@ml` — offline training infrastructure (not in the request path)
- `@model-boss` — inference routing and GPU management (layer below @ai)
- `@career`, `@education`, `@finances`, `@wellness` — domain data services (ContextProviders)
- `@companion` — the product shell that wires @ai + @chobit (no AI logic of its own)

---

## Single Responsibility

**@ai owns:** identity, memory, personality composition, nag loop engine, context assembly.

**@ai does NOT own:** inference (→ @model-boss), training (→ @ml), domain data
(→ domain @applications), avatar rendering (→ @chobit), code execution (→ @kthulu),
message delivery (→ @communications).

---

## Ecosystem Position

```
@projects/@companion  ←  @chobit (body) + @ai (brain)  — zero AI in @companion itself
@projects/@kthulu     ←  @ai (context/memory) + @model-boss (inference)
@projects/@life       ←  @ai (context) + domain @applications (data)

@applications/@ai
       │
       ├── ContextProviders (pull from domain services)
       │   @career · @education · @finances · @wellness
       │
       └── POST /v1/chat/completions
           @applications/@model-boss :8210
```

---

## What Migrates INTO @ai

| Source | What moves |
|--------|-----------|
| `@life/@applications/ai/services/companion/` | deleted — behavior moves here |
| `@life/@applications/ai/services/platform-ai/` | deleted — behavior moves here |
| `@life/messenger/notifications/ambient-companion.service.ts` | → @ai nag module |
| `@life/messenger/notifications/nudge.service.ts` | → @ai nag module |
| `@life/.../memory.service.ts` | → @ai memory module |
| `@chobit/config/personalities/miku.json` | → `@ai/config/personalities/miku.json` |
| `.quinn` CronCreate nag loop | → `POST /nag/start` |

---

## Modules

| Module | Endpoint | Description |
|--------|----------|-------------|
| Identity | `GET/POST /identity` | PersonaEntity, UserIdentityEntity |
| Memory | `GET/POST /memory` | Redis (short-term) + PostgreSQL (long-term) |
| Personality | `POST /personality/:id/compose` | Composable prompt templates → `{ system_prompt, tts config }` |
| Process | `WS /process/:session_id` | Personality mechanics: tokens in → segments out (sentence split, emotion, sanitize) |
| Nag | `POST/DELETE/GET /nag` | Unified nag engine (see `.project/streams/m4-nag-loop/`) |
| Context | `POST /context/compose` | Assembles identity + personality + memory + tasks for LLM |
| Relationship | internal | Relationship arc, dynamic trait intensity |

### Process Module — Personality Mechanics

`WS /process/:session_id` receives raw LLM tokens from callers (companion-api, @chobit)
and applies personality-driven response processing:

- **ResponseStream** — sentence splitting + emotion tag extraction (ported from @chobit `_extract_segments()`)
- **TextSanitizer** — paralinguistic normalization, markdown/emoji/URL stripping (ported from `_sanitize_for_speech()`)
- **EmotionResolver** — maps raw emotion tags to canonical set, returns TTS params per personality config

@ai never calls @model-boss. Callers own inference; @ai owns personality mechanics only.

---

## Context Provider Protocol

```typescript
interface ContextProvider {
  getContext(identity_id: string, options: ContextQueryOptions): Promise<string>;
}
// Implementations: LifeContextProvider, CareerContextProvider,
//                  EducationContextProvider, WellnessContextProvider
```

---

## Primary Endpoint

```
POST /context/compose
{ identity_id, personality_id, recent_messages, context }
→
{ system_prompt, memory_injections, task_summary }
```

---

## Ports

| Service | Port |
|---------|------|
| ai-core HTTP | 3790 |
| PostgreSQL | 26395 |
| Redis | 26394 |

---

## Project Structure

```
@applications/@ai/
├── @packages/
│   └── ai-client/              # @lilith/ai-client — published TS client
├── services/
│   └── ai-core/                # NestJS :3790
│       ├── identity/
│       ├── memory/
│       ├── personality/
│       ├── nag/
│       ├── context/
│       ├── response/
│       └── relationship/
├── config/
│   └── personalities/
│       └── miku.json           # source of truth (moved from @chobit)
├── docs/
│   └── ARCHITECTURE.md
└── .project/
    ├── README.md
    └── streams/m4-nag-loop/
```

---

## Development Standards

**Before writing any utility, service, or package:** Check `~/Code/@packages/MANIFEST.md` first.
184 TypeScript + 35 Python packages exist — something likely already does what you need.
Everything in `~/Code/@packages/` and `~/Code/@applications/` is fair game.

Key categories relevant to NestJS services:
- `@ts/@nestjs` (7 packages) — bootstrap, health, auth, typeorm config
- `@ts/@database` (5 packages) — TypeORM entities, migrations
- `@ts/@infra` (13 packages) — service registry, eventbus, queue
- `@ts/@websocket` (3 packages) — WebSocket utilities

---

## Key Packages

| Need | Package |
|------|---------|
| NestJS bootstrap | `@lilith/service-nestjs-bootstrap` |
| Health | `@lilith/nestjs-health` |
| TypeORM | `@lilith/typeorm-config` |
| Redis events | `@lilith/eventbus` |
| Scheduling | `@nestjs/schedule` + `cron` |
| Inference | `@lilith/model-boss` → :8210 |

---

## Milestone Status

| Milestone | Status |
|-----------|--------|
| M0 | next — scaffold, Docker, health |
| M1 | planned — Identity |
| M2 | planned — Memory |
| M3 | planned — Personality |
| M4 | planned — Nag (spec: `.project/streams/m4-nag-loop/`) |
| M5 | planned — Context (`POST /context/compose`) |
| M6 | planned — ai-client package |
| M7 | planned — @companion integration |
| M8 | planned — Relationship |
| M9 | planned — @life + @education + @career + @wellness integration |