feat(interpreter): implement hybrid intent resolution with LLM and deterministic fallback
- 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>
This commit is contained in:
161
thoughts.md
161
thoughts.md
@@ -1,89 +1,88 @@
|
||||
# thoughts.md
|
||||
|
||||
## Current Status (clean-break)
|
||||
- Backend is running the new contract-native API shape:
|
||||
- `GET /api/state` -> `{ worldState, turns }`
|
||||
- `POST /api/turn` -> `{ rawText, actions, validation, worldState }`
|
||||
- Runtime blocker is resolved:
|
||||
- old SQLite schema conflict (`turns.raw_text`) was fixed by wiping old DB state
|
||||
- stale legacy files removed from backend source tree:
|
||||
- `app/src/types.ts`
|
||||
- `app/src/latentEntities.ts`
|
||||
- `app/src/llmAdapter.ts`
|
||||
- Door/key MVP smoke checks pass:
|
||||
- `open door` before key -> `locked_requires_key`
|
||||
- `take key` -> success
|
||||
- `open door` after key -> success
|
||||
- Scene-entry support added:
|
||||
- `introduce` is now a first-class action
|
||||
- rooms can declare `is_joinable`
|
||||
- characters can declare `is_social`
|
||||
- successful introduction moves a character from offstage into the actor's current room
|
||||
- `introduce` can also create a new social character when the named target does not already exist
|
||||
## Documentation Sync
|
||||
|
||||
## Architecture Now
|
||||
- Core contracts in `app/src/contracts/`:
|
||||
- `action.ts`
|
||||
- `validation.ts`
|
||||
- `turn.ts`
|
||||
- `entity.ts`
|
||||
- `world.ts`
|
||||
- Deterministic truth engine:
|
||||
- `app/src/truthEngine.ts` with `validateActions(actions, worldState)`
|
||||
- Ordered turn pipeline:
|
||||
- `app/src/turns/processTurn.ts` parse -> validate -> apply -> persist
|
||||
- World mutation:
|
||||
- `app/src/world/applyActions.ts`
|
||||
- Persistence:
|
||||
- `app/src/db.ts` with tables `turns`, `actions`, `validation_results`, `entities`, `world_states`
|
||||
- App seed domain:
|
||||
- `app/src/app.ts` door/key world (`room_start`, `room_exit`, `room_offstage`, `player`, `groundskeeper`, `door_1`, `key_1`)
|
||||
- Implementation plan refreshed in Implementation_plan.md to match current codebase state.
|
||||
- Next executable phase is Phase 1: Intent Interpreter Boundary Hardening.
|
||||
|
||||
## Scene Entry Rules
|
||||
- `introduce` validates against deterministic affordances:
|
||||
- target must exist
|
||||
- target must be a character
|
||||
- target must have `is_social: true`
|
||||
- actor must be in a valid room
|
||||
- room must have `is_joinable: true`
|
||||
- target must not already be in that room
|
||||
- If no existing target entity is resolved but a character name is present, `introduce` may create a new character directly into the current room.
|
||||
## Current Snapshot (April 2026)
|
||||
|
||||
## Character Description (NEW)
|
||||
- `describe` action adds traits to characters:
|
||||
- Syntax: `"describe the merchant as shrewd and quick"`
|
||||
- Traits are stored in `character.attributes.traits[]`
|
||||
- Multi-sentence support: `"introduce a merchant. describe the merchant as shrewd and quick."`
|
||||
- Validation rules:
|
||||
- target character must exist (or will be created by introduce in same turn)
|
||||
- actor and target must be in same room (for existing targets)
|
||||
- supports forward-reference to entities created in the same turn
|
||||
- Multi-action parsing:
|
||||
- Sentences split on `/[.!?]+/`
|
||||
- Each sentence becomes a separate action
|
||||
- Validation accounts for entities created by introduce actions in the same turn
|
||||
- On success:
|
||||
- target location becomes the actor's location
|
||||
- `in_scene` is set to `true`
|
||||
- `last_introduced_by` is recorded
|
||||
- newly created characters default to `type: character`, `is_social: true`, `in_scene: true`
|
||||
### What is now working
|
||||
|
||||
## New Endpoint
|
||||
- Added `POST /api/reset` in `app/src/index.ts`
|
||||
- App-level reset implementation in `app/src/app.ts`
|
||||
- DB wipe support in `app/src/db.ts`
|
||||
- Verified reset behavior:
|
||||
- returns `{ worldState, turns }`
|
||||
- `turns` is empty after reset
|
||||
- `player` and `key_1` return to `room_start`
|
||||
- Rulebook-driven validation is active and editable through API/frontend.
|
||||
- Character authorization rules are in place (actorIdIn / actorNameIn).
|
||||
- take supports createIfMissing, gated by rulebook permissions.
|
||||
- transfer action is live with ownership + recipient + location validation.
|
||||
- Turn processing now goes through a dedicated turn manager layer.
|
||||
- Intent interpreter contract exists with resolved / needs_clarification / rejected statuses.
|
||||
- Interpreter envelopes are persisted per turn and surfaced to the UI timeline.
|
||||
- LLM resolver now calls an HTTP model backend (Ollama-compatible) with hybrid deterministic fallback.
|
||||
- Rulebooks now include a version field with backward-compatible DB migration.
|
||||
|
||||
## Frontend Migration Notes
|
||||
- `frontend/src/App.tsx` migrated to consume new backend contracts.
|
||||
- Removed dependencies on old fields (`narration`, `events`, `beliefs`, `summaries`, `parser_feedback`).
|
||||
- Turn submit flow now refreshes snapshot via `GET /api/state` after `POST /api/turn`.
|
||||
- Reset call now sends JSON body/content-type to satisfy Fastify media-type validation.
|
||||
### Confirmed via containerized validation
|
||||
|
||||
## Remaining Checks
|
||||
1. Frontend build pass completed in container (`docker compose exec frontend npm run build`).
|
||||
2. Validate inspector UX manually against the door/key plus introduce flow.
|
||||
3. Expand parser coverage only within current clean MVP domain.
|
||||
- Backend build passes in Docker:
|
||||
- docker compose run --rm app npm run build
|
||||
- Frontend build passes in Docker:
|
||||
- docker compose run --rm frontend npm run build
|
||||
- Host Node build is intentionally not relied on.
|
||||
|
||||
## Architecture Feedback
|
||||
|
||||
### Good decisions worth keeping
|
||||
|
||||
1. Rulebook externalization
|
||||
- Pulling edge-case logic out of hardcoded truth engine branches was the right move.
|
||||
- It now supports editable policy without code deployment.
|
||||
|
||||
2. Explicit authorization checks in rules
|
||||
- Authorization for creation-style actions now belongs to policy, not parser guesswork.
|
||||
- This aligns with deterministic governance.
|
||||
|
||||
3. Introducing transfer as first-class action
|
||||
- This avoids overloading take semantics and keeps intent/action boundaries cleaner.
|
||||
|
||||
4. Turn manager seam
|
||||
- processTurn delegating to a turn manager creates a stable orchestration point for interpreter upgrades.
|
||||
|
||||
### Risks / cleanup still needed
|
||||
|
||||
1. Frontend contract drift risk
|
||||
- App.tsx has historically duplicated blocks during rapid edits.
|
||||
- Keep one canonical component and avoid append-style merges.
|
||||
|
||||
2. Interpreter observability depth
|
||||
- Interpreter traces are persisted, but aggregate analytics/counters are still missing.
|
||||
|
||||
3. Rulebook migration strategy
|
||||
- Existing DBs may hold older rulebooks missing new action rule sets.
|
||||
- Need explicit upgrade path/versioning.
|
||||
|
||||
## Path Forward (Next 3 Iterations)
|
||||
|
||||
### Iteration 1: LLM adapter hardening
|
||||
|
||||
- Harden prompt + response schema handling for model drift and malformed JSON.
|
||||
- Add environment-specific model/timeouts and failure policy guidance.
|
||||
- Add tests covering unavailable model backend and malformed payload fallback.
|
||||
|
||||
### Iteration 2: Traceability + observability
|
||||
|
||||
- Surface interpreter status in frontend turn log.
|
||||
- Add reason-code analytics counters for failed validations and unresolved intents.
|
||||
|
||||
### Iteration 3: Rulebook lifecycle and test harness
|
||||
|
||||
- Add policy packs (creation, transfer, social).
|
||||
- Add Docker-run integration tests for:
|
||||
- unauthorized createIfMissing
|
||||
- authorized createIfMissing
|
||||
- transfer success/failure matrix
|
||||
- clarification path for ambiguous/unrecognized input
|
||||
|
||||
## Operating Guidance
|
||||
|
||||
- Keep all build/test checks containerized.
|
||||
- Treat interpreter as replaceable adapter behind a stable contract.
|
||||
- Keep truth engine deterministic and side-effect free.
|
||||
- Keep mutation logic pure relative to validated actions only.
|
||||
|
||||
Reference in New Issue
Block a user