spencer
fc10e46ccc
- Added new contracts for intent interpretation, including InterpreterOutput and ResolverMode. - Implemented deterministic intent resolver with clarity checks for ambiguous references and empty input. - Developed LLM intent resolver that communicates with an external model, handling JSON responses and fallback clarifications. - Created an interpretTurn function to manage intent resolution based on the selected resolver mode. - Introduced validation for interpreter output to ensure integrity before processing actions. - Established a turn manager to orchestrate turn processing, including action validation and world state mutation. - Added integration tests to verify the functionality of the new intent resolution system. Co-authored-by: Copilot <copilot@github.com>
139 lines
3.6 KiB
Markdown
139 lines
3.6 KiB
Markdown
# CharacterGarden MVP - Current Architecture (April 2026)
|
|
|
|
## Core Principle
|
|
|
|
The simulation engine is deterministic and authoritative.
|
|
The LLM layer is an intent interpreter and resolver, not a source of truth.
|
|
|
|
## Live System Layers
|
|
|
|
User / LLM Input (Prose)
|
|
|
|
|
[Intent Interpreter Layer]
|
|
|
|
|
[Turn Manager]
|
|
|
|
|
[Truth Engine + Scene Rulebook Validation]
|
|
|
|
|
[World Mutation Engine]
|
|
|
|
|
[Persistence Layer]
|
|
|
|
|
[Frontend/API Response]
|
|
|
|
## Non-Negotiable Rules
|
|
|
|
1. Truth engine must never parse natural language.
|
|
2. Only structured actions can mutate world state.
|
|
3. Every mutation must pass validation before apply.
|
|
4. Rulebook rules are data-driven and editable.
|
|
5. Interpreter output is traceable and never auto-trusted when unresolved.
|
|
6. Every turn remains replayable end-to-end.
|
|
|
|
## Current Canonical Actions
|
|
|
|
- inspect
|
|
- move
|
|
- open
|
|
- take
|
|
- introduce
|
|
- describe
|
|
- transfer
|
|
|
|
## Action Contracts (Current)
|
|
|
|
- Action shape is contract-based in app/src/contracts/action.ts
|
|
- Validation contracts in app/src/contracts/validation.ts
|
|
- Turn contracts in app/src/contracts/turn.ts
|
|
- Interpreter contracts in app/src/contracts/intent.ts
|
|
|
|
## Scene Rulebook (Data-Driven Validation)
|
|
|
|
Validation is now externalized into SceneRulebook definitions.
|
|
|
|
Key capabilities already implemented:
|
|
|
|
- Actor authorization checks (actorIdIn, actorNameIn)
|
|
- Conditional creation checks (actionMetadataEq)
|
|
- Inventory ownership checks (itemInInventory)
|
|
- Existing deterministic checks (entity type/exists, same location, attribute checks)
|
|
|
|
This supports:
|
|
|
|
- Restricting who can introduce characters
|
|
- Restricting who can create missing items via take
|
|
- Validating transfer only when actor owns item and recipient is valid
|
|
|
|
## Turn Execution (Current)
|
|
|
|
1. Interpret raw turn text using interpreter module.
|
|
2. If unresolved:
|
|
- return clarification/rejection state
|
|
- persist trace turn with no applied actions
|
|
3. If resolved:
|
|
- validate actions with truth engine + active rulebook
|
|
- apply successful actions
|
|
- persist turn, actions, validation results, and world state
|
|
|
|
## Interpreter + Turn Manager (New)
|
|
|
|
- Interpreter module: app/src/interpreter/interpretTurn.ts
|
|
- Turn manager orchestrator: app/src/turns/turnManager.ts
|
|
- processTurn delegates to turn manager: app/src/turns/processTurn.ts
|
|
|
|
Current interpreter statuses:
|
|
|
|
- resolved
|
|
- needs_clarification
|
|
- rejected
|
|
|
|
## Current Domain Behaviors
|
|
|
|
- take can create missing items when createIfMissing is present and actor is authorized by rulebook
|
|
- introduce can create missing characters when rulebook allows
|
|
- transfer moves items between inventories when rulebook checks pass
|
|
|
|
## Persistence (Current)
|
|
|
|
SQLite tables already backing turns and world snapshots:
|
|
|
|
- turns
|
|
- actions
|
|
- validation_results
|
|
- entities
|
|
- world_states
|
|
- rulebooks
|
|
|
|
## API Surface (Current)
|
|
|
|
- GET /api/state
|
|
- POST /api/turn
|
|
- POST /api/reset
|
|
- GET /api/rulebook
|
|
- PUT /api/rulebook
|
|
- GET /api/rulebooks
|
|
|
|
## Operational Rule: Validation in Docker
|
|
|
|
Build and runtime checks should run in containers, not host Node.
|
|
|
|
- Backend build: docker compose run --rm app npm run build
|
|
- Frontend build: docker compose run --rm frontend npm run build
|
|
|
|
## Immediate Path Forward
|
|
|
|
1. LLM adapter hardening
|
|
- Tune prompt/schema validation for model drift.
|
|
- Add configurable model + timeout policy per environment.
|
|
|
|
2. Rulebook governance
|
|
- Keep versioned rulebook migration path active as rule schema evolves.
|
|
- Split rules into policy packs: creation, transfer, social.
|
|
|
|
3. Testing depth
|
|
- Expand Docker-executed integration tests for:
|
|
- createIfMissing authorization matrix
|
|
- transfer ownership/location checks
|
|
- unresolved clarification flows
|
|
- multi-action turn behavior
|