artale
/
fable-agent
Template
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fable-agent/ARCHITECTURE.md

243 lines
12 KiB
Markdown
Raw Permalink Blame History

# Fable Agent — Architecture Reference
## Thesis
**Harness-agnostic, model-agnostic.** The harness compounds. The model executes phases.
Swap any executor, any model, any provider — the system accumulates regardless.
---
## Layer 1: Safety Stack (Pre-loop)
Every task passes through these gates before reaching the feedback loop:
```
User Input
│
├── ContentSafetyGate──────────── classify risk domain
│ cybersecurity_exploit → BLOCK
│ harmful_content → BLOCK
│ financial_advice → REFORMULATE
│ code_generation → ALLOW
│
├── DecompositionGuard ────────── detect multi-turn attacks
│ 3+ exploit stages in 5min window → BLOCK
│ Unicode homoglyphs → normalized before matching
│
├── PromptBoundaryAdapter ─────── stay within classifier boundaries
│ exploit-adjacent verbs → defensive equivalents
│ Mixed domains → split with safety framing
│
├── SafetyBoundary ────────────── route to available model
│ Fable 5 / Mythos 5 → BLOCKED (export control)
│ Opus 4.8 → orchestrator
│ Sonnet 4.6 → bounded subtasks
│ Haiku → grading
│
└── HallucinationDetector ─────── verify output against known facts
contradiction → BLOCK
confabulation → BLOCK
self-contradiction → BLOCK
```
**Files:** `upgrades/content-safety-gate.ts`, `upgrades/decomposition-guard.ts`, `upgrades/prompt-boundary-adapter.ts`, `upgrades/safety-boundary.ts`, `upgrades/hallucination-detector.ts`, `upgrades/fallback-detector.ts`
---
## Layer 2: Foundation (Tier 1)
| Module | File | Purpose |
|--------|------|---------|
| SessionEngine | `tier1-foundation/session-engine.ts` | Checkpoint/resume, heartbeat stall detection, days-long autonomy |
| ContextManager | `tier1-foundation/context-manager.ts` | Sliding window, priority summarization, token budget |
| ToolOrchestrator | `tier1-foundation/tool-orchestrator.ts` | Retry with backoff, timeout, validators |
---
## Layer 3: Primitives (Tier 2)
### Loops
| Module | File | Purpose |
|--------|------|---------|
| FeedbackLoop | `tier2-primitives/loops/feedback-loop.ts` | Plan → Execute → Observe → Reflect → Refine phase machine |
| StateAccumulator | `tier2-primitives/loops/state-accumulator.ts` | Append-only event log, aggregation, trends |
| ConvergenceCheck | `tier2-primitives/loops/convergence-check.ts` | Diminishing returns, quality plateau detection |
### Workflows
| Module | File | Purpose |
|--------|------|---------|
| WorkflowGraph | `tier2-primitives/workflows/workflow-graph.ts` | DAG execution, topological sort, conditional branching |
| AdaptiveRouter | `tier2-primitives/workflows/adaptive-router.ts` | Epsilon-greedy branch selection, historical path scoring |
| RecoveryHandler | `tier2-primitives/workflows/recovery-handler.ts` | Retry, fallback, graceful degradation |
### Routines
| Module | File | Purpose |
|--------|------|---------|
| SkillRegistry | `tier2-primitives/routines/skill-registry.ts` | CRUD, versioning, tagging, search |
| ExecutionEngine | `tier2-primitives/routines/execution-engine.ts` | Deliberate practice, timing, validation |
| RoutineEvolution | `tier2-primitives/routines/routine-evolution.ts` | Analyze history, auto-suggest improvements |
---
## Layer 4: Compounding (Tier 3)
| Module | File | Purpose |
|--------|------|---------|
| StateRepository | `tier3-compounding/state-repository.ts` | Cross-session knowledge base, tagging, compaction |
| SkillSharpener | `tier3-compounding/skill-sharpener.ts` | Meta-review, quality gate, auto-apply improvements |
| MetaAgent | `tier3-compounding/meta-agent.ts` | Orchestrator: select → execute → sharpen → store → compound |
---
## Layer 5: Upgrades (Elite Patterns)
| Pattern | File | Purpose |
|---------|------|---------|
| Dreaming | `upgrades/dreaming-system.ts` | Sleep → review → extract → codify → dream |
| Self-Validation | `upgrades/self-validator.ts` | Per-phase quality gates, auto-retry on failure |
| Multi-Agent | `upgrades/multi-agent.ts` | Orchestrator → specialists → collect → verify |
| Rubric Engine | `upgrades/rubric-engine.ts` | N-criteria evaluation, dynamic exit conditions |
| Persistent Memory | `upgrades/persistent-memory.ts` | Episodic + Semantic + Procedural partitions |
| Enhanced Meta | `upgrades/enhanced-meta-agent.ts` | Full Dream → Act → Validate → Codify loop |
| Vision Check | `upgrades/vision-self-check.ts` | Automated visual verification via vision model |
| Scheduler | `upgrades/routine-scheduler.ts` | Cron-like task scheduling |
| Goal Queue | `upgrades/goal-queue.ts` | Persistent priority queue |
| Daemon | `upgrades/daemon-engine.ts` | 24/7 autonomous loop, auto-resume, auto-benchmark |
| Benchmark | `upgrades/benchmark-runner.ts` | Measure compounding trends |
| Cost Tracker | `upgrades/cost-tracker.ts` | Per-call/per-model/per-session cost |
| Cost Cap | `upgrades/cost-cap.ts` | Hard budget limits, auto-pause |
| Skill Sync | `upgrades/skill-sync.ts` | Two-way SKILLS/ markdown ↔ TS registry |
| Exa Search | `upgrades/exa-search.ts` | Web search + company research |
| Env Loader | `upgrades/env-loader.ts` | .env loading, no dependencies |
| Fallback Detector | `upgrades/fallback-detector.ts` | Detect silent model fallback |
| Familiar Knowledge | `upgrades/familiar-knowledge.ts` | inbox → wiki processing pipeline |
| PAI Adapter | `upgrades/pai-adapter.ts` | PAIMM / TELOS / LifeOS mapping |
| AI SDK Adapter | `upgrades/ai-sdk-adapter.ts` | AI SDK v7 harness interface |
---
## Layer 6: Executors
| Executor | File | Interface | Model |
|----------|------|-----------|-------|
| Antigrav | `examples/executors/antigrav-executor.ts` | `agy --print` | gemini-2.5-pro |
| Claude Code | `examples/executors/cc-executor.ts` | `claude -p` | claude-sonnet-4-6 |
| Codex | `examples/executors/codex-executor.ts` | `codex` or `pi --provider codex` | codex |
| Composite | `examples/executors/composite-executor.ts` | multi-model routing | per-phase |
| Fable5 | `examples/executors/fable5-executor.ts` | effort levels | opus-4-8 |
| Grok | `examples/executors/grok-executor.ts` | `grok -m grok-3 -p` | grok-3 |
| Kimi | `examples/executors/kimi-executor.ts` | Kimi API | kimi-k2.6 |
| Local | `examples/executors/local-executor.ts` | OAI-compatible | Ollama/vLLM |
| OpenAI | `examples/executors/openai-executor.ts` | OpenAI API | gpt-4.1 / o3 |
| OpenCode | `examples/executors/opencode-executor.ts` | `opencode -p` | via proxy :18901 |
| Pi | `examples/executors/pi-executor.ts` | `pi --print` | 324 models |
| Sonnet | `examples/executors/sonnet-executor.ts` | Anthropic API | claude-sonnet-4-6 |
| Weak-to-Strong | `examples/executors/weak-to-strong.ts` | bootstrap | any |
---
## Layer 7: Bridges
| Bridge | File | Connects |
|--------|------|---------|
| PAI-FA | `pai/pai-fa-bridge.ts` | PAI TELOS → FA rubric, PAI memory → FA memory |
| PAI-Pi | `pai/pai-pi-bridge.ts` | PAI Pi release (4035-char prompt, 9 skills) → FA |
| AI SDK | `upgrades/ai-sdk-adapter.ts` | Fable Agent ↔ AI SDK v7 harness ecosystem |
---
## Layer 8: Pre-existing Modules
| Module | Directory | Contents |
|--------|-----------|---------|
| PAI | `pai/` | TELOS bridge, ISA writer, memory progression, proxy client, skill sync |
| Fable5 | `fable5/` | Model router, independent verifier, goal pattern, agent chains, meta-agent, agent teams, worktree isolation, state file, compound stack |
---
## Data Flow
```
┌─────────────────────────────┐
│ User / CLI │
└──────────┬──────────────────┘
│ task
┌──────────▼──────────────────┐
│ SAFETY STACK (4 gates) │
│ content → decomp → adapt → │
│ route → hallucination check │
└──────────┬──────────────────┘
│ safe task
┌──────────▼──────────────────┐
│ FEEDBACK LOOP │
│ plan → execute → observe → │
│ reflect → refine │
│ (rubric evaluates each iter)│
└──────────┬──────────────────┘
│ iteration results
┌──────────▼──────────────────┐
│ ACCUMULATOR │
│ store → aggregate → trend │
└──────────┬──────────────────┘
│ converged?
┌──────────▼──────────────────┐
│ DREAM CYCLE │
│ every 3 goals: review → │
│ extract → distill → codify │
└──────────┬──────────────────┘
│ skill improvements
┌──────────▼──────────────────┐
│ MEMORY │
│ episodic (what happened) │
│ semantic (what it means) │
│ procedural (how to do it) │
└──────────┬──────────────────┘
│ accumulated state
┌──────────▼──────────────────┐
│ KNOWLEDGE │
│ state repo / familiar wiki │
│ / STATE.md / SKILLS/ │
└─────────────────────────────┘
```
## CLI Map
```
fable-agent run <task> → Safety stack → Feedback loop → Memory
fable-agent demo → Exa search → Register skill → Loop → Sharpen
fable-agent daemon start --detach → 24/7 loop with auto-resume + auto-benchmark
fable-agent daemon queue <goal> → Priority queue → Daemon picks → Execute
fable-agent familiar capture → inbox/ .md
fable-agent familiar process → inbox/ → wiki/ + auto git commit
fable-agent familiar graph → [[wikilinks]] → knowledge graph
fable-agent benchmark run → 3 benchmarks → Trend report
fable-agent learned → Every storage layer → Full knowledge report
fable-agent exa search → Exa API → Results → Knowledge base
fable-agent skills sync → SKILLS/ markdown ↔ TS registry
fable-agent pai-pi run <goal> → PAI Pi prompt + Pi executor → FA loop
```
## File Inventory
```
~/fable-agent/
├── 86 source files (src/ — all layers)
├── 5 test files (43 tests)
├── 13 executors (examples/executors/)
├── 25 upgrade modules (upgrades/)
├── 7 pre-existing (pai/ + fable5/)
├── 6 root docs (README.md, AGENT.md, CONFIG.md, STATE.md, ARCHITECTURE.md, PHASES/)
├── 6 skill dirs (SKILLS/)
├── 14 phase defs (PHASES/)
├── Dockerfile (deployable)
├── .github/ (CI/CD)
├── deploy/ (systemd + PM2)
└── .env.example (all config vars)
```
## Version
**0.0.1** — architecture-complete. Every pattern from every source implemented.
All 14 roadmap steps. All Fable 5 elite patterns. All safety layers. All executors.
All bridges. Deployment ready. The harness, not the model.
Reference in New Issue View Git Blame Copy Permalink