368 lines
5.4 KiB
Markdown
368 lines
5.4 KiB
Markdown
# CharacterGarden – AI-Oriented Design Spec (Copilot-Ready)
|
||
|
||
## 0. Purpose
|
||
|
||
This document defines **hard contracts and system boundaries** for CharacterGarden.
|
||
|
||
Goal: enable an AI coding assistant (e.g. Copilot) to implement the system step-by-step without ambiguity.
|
||
|
||
Core principle:
|
||
|
||
> The application owns truth. The LLM only translates and narrates.
|
||
|
||
---
|
||
|
||
## 1. System Overview
|
||
|
||
### Pipeline
|
||
|
||
```
|
||
Prose Input
|
||
→ Intent Extraction
|
||
→ Canonical Actions
|
||
→ Truth Engine Validation
|
||
→ State Changes + Events
|
||
→ Memory Storage
|
||
→ Narration Output
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Core Contracts (STRICT)
|
||
|
||
### 2.1 Entity
|
||
|
||
```
|
||
Entity {
|
||
id: string
|
||
type: string
|
||
name: string
|
||
attributes: object
|
||
}
|
||
```
|
||
|
||
### 2.2 Action (Canonical)
|
||
|
||
```
|
||
Action {
|
||
actor: string (entity id)
|
||
verb: string (enum)
|
||
target?: string (entity id)
|
||
params?: object
|
||
}
|
||
```
|
||
|
||
Allowed verbs (MVP):
|
||
|
||
```
|
||
move, open, close, take, drop, use, inspect, speak
|
||
```
|
||
|
||
### 2.3 Validation Result
|
||
|
||
```
|
||
ValidationResult {
|
||
accepted: Action[]
|
||
rejected: { action: Action, reason: string }[]
|
||
state_changes: StateChange[]
|
||
}
|
||
```
|
||
|
||
### 2.4 State Change
|
||
|
||
```
|
||
StateChange {
|
||
entity_id: string
|
||
field: string
|
||
old_value: any
|
||
new_value: any
|
||
}
|
||
```
|
||
|
||
### 2.5 Event
|
||
|
||
```
|
||
Event {
|
||
id: string
|
||
turn: number
|
||
action: Action
|
||
result: "success" | "fail"
|
||
timestamp: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Truth Rules
|
||
|
||
1. Only the **Truth Engine** can modify world state
|
||
2. LLM output is NEVER directly trusted
|
||
3. Every state change must be traceable to an Event
|
||
4. Invalid actions must return explicit failure reasons
|
||
|
||
---
|
||
|
||
## 4. Memory Model
|
||
|
||
Memory is NOT a single blob.
|
||
|
||
### Types
|
||
|
||
#### 4.1 Turn
|
||
|
||
Raw input/output
|
||
|
||
#### 4.2 Event
|
||
|
||
Accepted or rejected actions
|
||
|
||
#### 4.3 Fact
|
||
|
||
Current world state (derived, not duplicated)
|
||
|
||
#### 4.4 Belief
|
||
|
||
```
|
||
Belief {
|
||
entity_id: string
|
||
claim: string
|
||
confidence: number
|
||
}
|
||
```
|
||
|
||
#### 4.5 Summary
|
||
|
||
Compressed narrative context
|
||
|
||
---
|
||
|
||
## 5. Services
|
||
|
||
### 5.1 App (Core Service)
|
||
|
||
Responsibilities:
|
||
|
||
* orchestrate turns
|
||
* call LLM (optional)
|
||
* run truth engine
|
||
* manage memory
|
||
|
||
Tech: Node.js (Express or Fastify)
|
||
|
||
---
|
||
|
||
### 5.2 Truth Engine (Module inside App)
|
||
|
||
Responsibilities:
|
||
|
||
* validate actions
|
||
* enforce rules
|
||
* apply state changes
|
||
* emit events
|
||
|
||
NO LLM USAGE
|
||
|
||
---
|
||
|
||
### 5.3 LLM Adapter (Optional)
|
||
|
||
Responsibilities:
|
||
|
||
* extract actions from prose
|
||
* resolve references
|
||
* generate narration
|
||
* summarize memory
|
||
|
||
Backend: Ollama
|
||
|
||
---
|
||
|
||
### 5.4 Frontend
|
||
|
||
Responsibilities:
|
||
|
||
* send input
|
||
* display output
|
||
* optionally inspect state/events
|
||
|
||
Minimal React or Vue app
|
||
|
||
---
|
||
|
||
## 6. Turn Flow (IMPLEMENT EXACTLY)
|
||
|
||
```
|
||
1. Receive user input (string)
|
||
2. Store raw turn
|
||
3. Extract actions (LLM or fallback parser)
|
||
4. Validate actions (truth engine)
|
||
5. Apply accepted changes
|
||
6. Store events
|
||
7. Generate narration
|
||
8. Return response
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Storage
|
||
|
||
### SQLite (MVP)
|
||
|
||
Tables:
|
||
|
||
* entities
|
||
* events
|
||
* turns
|
||
* beliefs
|
||
* summaries
|
||
|
||
File location:
|
||
|
||
```
|
||
/data/sqlite/app.db
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Docker Design
|
||
|
||
### Services
|
||
|
||
```
|
||
services:
|
||
app
|
||
frontend
|
||
ollama (optional)
|
||
```
|
||
|
||
### Principles
|
||
|
||
* No host dependencies beyond Docker
|
||
* Persist only `/data`
|
||
* Use `.env` for config
|
||
* No hidden setup scripts
|
||
|
||
---
|
||
|
||
## 9. Folder Structure
|
||
|
||
```
|
||
charactergarden/
|
||
docker-compose.yml
|
||
.env
|
||
app/
|
||
frontend/
|
||
data/
|
||
sqlite/
|
||
```
|
||
|
||
---
|
||
|
||
## 10. MVP Scope
|
||
|
||
STRICT LIMITS:
|
||
|
||
* 1–2 rooms
|
||
* ≤3 characters
|
||
* ≤10 actions
|
||
* no complex AI autonomy
|
||
* no multi-agent loops yet
|
||
|
||
---
|
||
|
||
## 11. Non-Goals (DO NOT BUILD YET)
|
||
|
||
* microservices
|
||
* distributed systems
|
||
* plugin frameworks
|
||
* advanced agent loops
|
||
* cloud dependencies
|
||
|
||
---
|
||
|
||
## 12. Development Workflow Rule
|
||
|
||
A root-level file named `thoughts.md` must exist and be maintained throughout development.
|
||
|
||
Purpose of `thoughts.md`:
|
||
|
||
* record current implementation status
|
||
* record the next planned steps
|
||
* record blockers, assumptions, and unresolved questions
|
||
* summarize architectural decisions already made
|
||
* preserve continuity across editor sessions or context loss
|
||
|
||
Rules for `thoughts.md`:
|
||
|
||
* update it after each meaningful implementation step
|
||
* keep entries concise and factual
|
||
* do not use it for chain-of-thought dumping or vague brainstorming
|
||
* use it as a project progress log and working memory
|
||
* when resuming work, review `thoughts.md` first before making changes
|
||
* when changing architecture, record what changed and why
|
||
* when a task is incomplete, note exactly what remains
|
||
|
||
Recommended structure:
|
||
|
||
```md
|
||
# thoughts.md
|
||
|
||
## Current Status
|
||
- what is implemented
|
||
- what is partially implemented
|
||
- what is broken or unverified
|
||
|
||
## Current Architecture Decisions
|
||
- key decisions and constraints
|
||
|
||
## Next Steps
|
||
- ordered checklist of immediate tasks
|
||
|
||
## Open Questions
|
||
- unresolved design or implementation questions
|
||
|
||
## Session Notes
|
||
- short dated notes describing recent progress
|
||
```
|
||
|
||
Copilot instruction:
|
||
|
||
> Before starting work, read `thoughts.md`. After completing any meaningful change, update `thoughts.md` to reflect current status, next steps, and any unresolved issues.
|
||
|
||
## 13. Development Order
|
||
|
||
1. Define entities + actions
|
||
2. Implement truth engine
|
||
3. Add SQLite persistence
|
||
4. Build API endpoints
|
||
5. Add minimal UI
|
||
6. Add LLM integration
|
||
|
||
---
|
||
|
||
## 14. Key Rule
|
||
|
||
> If the system works without an LLM, the architecture is correct.
|
||
|
||
---
|
||
|
||
## 15. Expected Behavior
|
||
|
||
* deterministic state
|
||
* explainable failures
|
||
* replayable sessions
|
||
* inspectable memory
|
||
|
||
---
|
||
|
||
## 16. Future Extensions (NOT NOW)
|
||
|
||
* branching timelines
|
||
* advanced belief systems
|
||
* multi-agent arbitration
|
||
* long-term memory compression
|
||
|
||
---
|
||
|
||
## END SPEC
|