Framework

Purpose

This page is the conceptual model that ties the lab together. It describes the 8 layers, the contracts between them, and the patterns that the lab's concrete components implement.

The 8 layers are introduced in System Architecture → The 8-layer model. This page is the deeper reference.

The pattern

The lab follows a layered orchestrator pattern with these properties:

• Each layer has a single responsibility.
• Each layer communicates with adjacent layers through a typed contract.
• Each layer is independently testable.
• The orchestrator is the only place that knows about multiple layers.

The pattern is a generalization of the research framework's structure (orchestrator, phases, schemas, adapters). The lab applies the same pattern at higher levels (user interface, coordination, agents).

Layer responsibilities

Layer 1: User Interface

The user interface is the natural-language channel between the user and the Coordinator. It has three responsibilities:

• Parse the user's natural-language request.
• Render the Coordinator's response for the user.
• Maintain the session (history, current task, in-flight requests).

The user interface does NOT decide what to do with the request. That is the Coordinator's job.

The user interface is implemented by the Coordinator's gateway and the framework's session layer.

Layer 2: Coordination

The Coordinator is the only layer that knows about multiple agents. Its responsibilities:

• Resolve the user's intent into one or more agent calls.
• Route the calls to the appropriate agents.
• Manage the session and the memory.
• Aggregate the results from multiple agents when the request spans multiple.
• Log every request and every response.

The Coordinator does NOT execute tasks. It is a router and a state manager.

Layer 3: Agent

Each agent is a specialized role with its own tools and its own lifecycle. The agents are:

• Coordinator — the main control agent.
• Coding Assistant — the implementation arm.
• Research Worker — the research specialist.
• Media Agent — the entertainment specialist.
• Web Agent — the browser automation capability.

An agent's responsibilities are:

• Execute the tasks it is given.
• Use the tools it is allowed to invoke.
• Return a structured result to the Coordinator.
• Log its actions for the audit trail.

An agent does NOT call other agents directly. All inter-agent communication goes through the Coordinator.

Layer 4: Framework

A framework is a domain-specific orchestrator. The lab has two:

• Research Framework — orchestrates the research phase DAG.
• Coding Sub-agent — orchestrates the code-writing flow (but the orchestration is minimal; the sub-agent does most of the work).

A framework's responsibilities:

• Decompose the agent's task into steps.
• Schedule the steps (sequential, parallel).
• Validate the inputs and outputs.
• Checkpoint the state between steps.
• Retry failed steps with backoff.

A framework does NOT talk to external services directly. It delegates to tools.

Layer 5: Tool

A tool is a typed, deterministic capability. The lab has dozens of tools, organized by category:

• Media tools — torrent-finder, subtitle-finder, etc.
• Research tools — search adapters, transcript APIs, etc.
• Web tools — the browser tool.
• Code tools — codex, git, npm, pytest.

A tool's responsibilities:

• Accept a typed input.
• Perform a deterministic action.
• Return a typed output.
• Log its invocation for the audit trail.

A tool does NOT reason about the user's intent. It does what it is told.

Layer 6: Adapter

An adapter translates a tool's generic request into a provider-specific format. The lab has adapters for:

• Search — Tavily, DuckDuckGo, Google.
• Video — YouTube Transcript, yt-dlp.
• Synthesis — Perplexity.

An adapter's responsibilities:

• Translate the tool's request to the provider's format.
• Authenticate with the provider.
• Handle the provider's rate limits.
• Translate the provider's response back to the tool's format.

An adapter does NOT reason about the request. It is a translator.

Layer 7: State

The state layer is where the lab remembers. The state includes:

• Long-term memory (MEMORY.md).
• Daily logs (memory/YYYY-MM-DD.md).
• Session state (in-memory + session files).
• Skill artifacts (SKILL.md, TOOL.md).
• Research artifacts (the framework's typed outputs).
• Audit trail (request journal, mission state).

The state layer's responsibilities:

• Persist data across sessions.
• Validate data on read and write.
• Expire data according to the retention policy.
• Provide the data to the layers that need it.

Layer 8: External

The external layer is everything the lab talks to:

• Model providers — for the Coordinator and the coding sub-agent.
• Search providers — for the research adapters.
• Streaming services — for the Media Agent.
• Devices — Cast devices, VLC hosts.

The external layer is not under the lab's control. The lab handles external failures through retries, fallbacks, and the audit trail.

Contracts between layers

Each contract between adjacent layers has:

• Direction (up, down, both).
• Format (JSON, function call, file I/O, etc.).
• Guarantee (at-most-once, at-least-once, synchronous, etc.).
• Validation (schema, type, range, etc.).

The contracts are documented in Data Flow → Boundaries and data.

Patterns

The lab reuses a small set of patterns:

Adapter pattern

The adapter pattern translates between a generic interface and a provider-specific one. The pattern appears in:

• The research framework's adapters (Tavily, DuckDuckGo, etc.).
• The Media Agent's Chromecast and VLC backends.
• The coding sub-agent's CLI invocation.

The adapter pattern is documented in External Providers.

Orchestrator pattern

The orchestrator pattern decomposes a complex task into steps, schedules them, and validates their results. The pattern appears in:

• The research framework's orchestrator.
• The Coordinator's intent resolver.

The orchestrator pattern is documented in Research Framework.

Tool pattern

The tool pattern wraps a deterministic capability in a typed interface. The pattern appears in:

• The lab's CLI tools (torrent-finder, etc.).
• The MCP adapters.
• The research adapters.

The tool pattern is documented in Tooling Layer.

Skill pattern

The skill pattern describes a capability in a markdown file. The pattern appears in:

• The Coordinator's skill loader.
• The coding sub-agent's skills.

The skill pattern is documented in Tool Spec.

Checkpoint pattern

The checkpoint pattern persists the state of a long-running task to disk. The pattern appears in:

• The research framework's mission state.
• The coding sub-agent's tool-a-research-init.

The checkpoint pattern is documented in Mission Lifecycle → Checkpointing.

Where the pattern shows up

The pattern reuse is what makes the lab coherent. A new component that follows the same pattern is easy to integrate; a new component that breaks the pattern is hard.

How to extend the lab

To extend the lab:

1. Add a tool. Implement a CLI or MCP adapter following the Tooling Layer pattern. Register the tool in the appropriate tools.json.
2. Add a domain tool to the research framework. Create a new package under docs/orchestrator/tools/ with the standard structure. Register it in the orchestrator.
3. Add an adapter. Implement an adapter following the External Providers pattern. Register it in the framework.
4. Add an agent. Create a new agent with its own gateway (if needed), its own tools, and its own context. Document the boundaries in Context Boundaries.
5. Add a pattern. Document the pattern in this page. Reference it from the existing pages.

The extension points are designed to be small and focused. Each extension should touch as few files as possible.

See also

• System Overview
• System Architecture
• Data Flow
• Tooling Layer
• External Providers
• Research Framework
• Context Boundaries