# Using and training adapters

An adapter is a directory of files that an agent loads when it works on a task. Those files can contain instructions,
skills, tools, and role definitions. Training produces new versions of that directory from task feedback. The
agent's model weights are unchanged.

There are two workflows: **using an existing adapter** and **training an adapter**. You can use an adapter without
running the training system. For commands to try first, follow [Quick Start](../get-started/quickstart.md).

## See the two workflows

Switch views below. In the training view, select a component or use **Next** to follow one iteration. The arrows show
handoffs; the detail below the diagram explains what is passed and who owns the operation.

```{raw} html
:file: ../_includes/component-explorer.html
```

## At use time: what does an adapter look like?

The simplest adapter uses the built-in `prompt-only@1.0` template:

```text
adapter/
  adapter.yaml    declares the exports and which files may change
  ADAPTER.md      instructions given to the acting agent
  EVOLVER.md      explains the editable structure to the learner
  README.md      instructions for people
  CARD.md        provenance and evaluation results, added at the end of training
```

`ADAPTER.md` is every adapter's context for the acting agent (a fixed, required file). `EVOLVER.md` guides the learner; `CARD.md` records
where the adapter came from. Neither is automatically included in the acting agent's prompt.

For example, `ADAPTER.md` might say “check the unit and scale of each source figure before calculating.” This affects
behavior when the pipeline makes the text available to the agent. The file has no effect just by existing on disk.

### How does it reach the agent?

| Export | Codex deployment | Claude Code deployment | Custom pipeline |
|---|---|---|---|
| Context | A block in `AGENTS.md` | A block in `CLAUDE.md` | Read the context and include it in model messages. |
| Tools, when declared | MCP server configuration | MCP server configuration | Integrate the declared tools through a supported calling mechanism. |
| Roles and skills, when declared | Host files generated by the connector | Host files generated by the connector | Provide support for the exports the chosen adapter needs. |

`hermit deploy` prepares a workspace; it does not launch the acting agent. Context and skills are copied or
rendered at deployment, so redeploy after changing them. Generated tool-server configuration can reference the
original adapter directory, which must remain available.

For the exact source-to-host paths, managed instruction blocks, and the learner's editable working copy, see the
[Adapter file interface](adapter.md#acting-interface).

In OfficeQA, `examples/officeqa/utils/agent/agent.py` loads the adapter's context for each execution and passes it
to SkillOpt's rollout as the skill in the system prompt. The file tools, model choice, and tool-calling loop remain
defined in that agent. This particular integration consumes context only.

The Lean collaboration template has more exports: instructions, skills, and tools for sharing proof work. Its tools
also need Lean/Mathlib and per-run shared state. Packaging files as an adapter does not install these dependencies
or make every host support them automatically.

## At training time: who supplies what?

The framework trains through interfaces you provide. The task owner supplies the dataset and code that runs and
scores the agent. A template defines what is editable. An Evolver implements a learning method. The Trainer
coordinates their execution.

| Component | Supplied by | Responsibility |
|---|---|---|
| Task data and description | Task owner | Problems, train/validation/test splits, and a description of the objective. |
| **Pipeline** | Task owner | Run the acting agent on a task with an adapter; return the answer and available logs and usage. |
| **Judge** | Task owner | Score the answer and produce feedback. |
| **Template** | Template author | Supply starting files, declare exports and editable paths, and define validity checks. |
| **Evolver** | Learning-method author | Use the evidence to edit or select an adapter. |
| **Trainer** | Framework | Run batches, prepare evidence, invoke the Evolver, check edits, track budgets, and save versions and state. |

One person can supply several parts. They are separate so a new task can reuse a learning method, or several methods
can be compared on the same task and editable files.

### The pipeline runs the acting agent

```python
run(task, adapter) -> RunOutput
score(task, output) -> JudgeResult
```

The Trainer passes a task dictionary and an adapter path to `run`. The pipeline deploys the adapter as needed and
runs the acting agent. Its result includes an `output` for the judge, plus optional logs, messages, and usage. The
Trainer then calls `score` with that result.

The pipeline owns the host, model, number of acting agents, tools, and execution loop. The Trainer does not rewrite
this code. Training and evaluation call the same pipeline and judge. `adapter=None` runs without a harness adapter
and provides a baseline.

### The template defines the scope of learning

For `prompt-only@1.0`, the relevant manifest declarations are:

```yaml
exports:
  context: ADAPTER.md
structure:
  learnable:
    - path: ADAPTER.md
      format: {text: true, max_bytes: 40000}
  fixed:
    - EVOLVER.md
    - README.md
```

The Evolver can rewrite the instruction file. It cannot change the export declaration, edit fixed files, or add
files outside the learnable paths. The template remains the reference for checking later versions.

The template contains the starting instructions and their rules. An evolved adapter contains later instructions
plus the same fixed files. Training can start from the template or a previous adapter.

In `lean-collab@1.0`, instructions and skills are learnable while collaboration code stays fixed. A different template
could allow code edits and provide corresponding checks. “Training the harness” has a specific scope for each
template.

### The Evolver is the learner

The Evolver receives a working copy of the adapter, task information, results, adapter history, and its own
persistent state. It may rewrite instructions, run candidate experiments, keep a candidate pool, or return the
current adapter unchanged.

The built-in `gepa` and `skillopt` methods ask a model to rewrite Markdown using scored examples and test a rewrite
before keeping it. The `codex` and `claude` methods launch a learner agent to inspect material and edit files. The learner improves what future task executions
will consume; the acting agent solves those tasks. The two roles can use different models.

Template and Evolver are separate, but still need compatible capabilities. A method that only rewrites Markdown
will not automatically learn executable tools just because a template permits code changes.

## One iteration, with the actual handoffs

OfficeQA's smoke configuration runs four training questions in two batches. For the first batch:

1. **Trainer → pipeline.** Export the current adapter from Git and call `run(task, adapter)` for each question.
   The pipeline loads its instructions, calls the acting model, and returns answers and logs.
2. **Trainer → judge.** Call `score(task, output)`. Scores and feedback describe the adapter that ran this batch.
3. **Trainer → learning material.** Write inputs, outputs, judge results, and available trajectories under
   `learning_material/step_0001/`. Point `learning_material/current` at that directory.
4. **Trainer → Evolver.** Call `step(ctx)`. The learner reads the material and edits `ctx.workspace.adapter`.
   It returns a `StepResult` describing status and usage. The adapter itself is the directory left on disk.
5. **Trainer → specification check.** Run `check_spec`. For a specification violation, restore affected files from the
   template or previous adapter and check again. Repair can fall back to the previous version. An Evolver result
   marked failed or out of budget keeps the previous adapter.
6. **Trainer → Git and run records.** Commit changes and save the learner's state, report, usage, and check results.
   The accepted adapter is used for the next batch.

The Trainer calls `setup` before the first step and `finalize` at the end. The Evolver hands back one adapter per step
even if it compares many candidates internally. The Trainer handles common experiment machinery; the Evolver
decides how to update and select candidates.

Suppose an answer used figures in incompatible units. The learner could add a unit-checking instruction, and the
next batch would run with it. This is an illustrative update, not a measured OfficeQA result.

## Acceptance is different from improvement

`check_spec` checks fixed files, allowed paths, formats, export loading, and template-specific requirements. It does
not measure task performance. A valid edit can lower the score; the Trainer does not reject it for that reason.
The Evolver may validate candidates itself. The prompt-only method (a Codex session per step) does not test its
rewrite before returning it.

Step 1 and step 2 use different task batches. A higher score on step 2 alone does not show improvement: the questions
also changed. Run separate evaluations on the same held-out test split to compare `final`, the adapter the run started
from (`root`, or the `start_from` adapter when the config sets one, such as OfficeQA's `../utils/seed_adapter`), and
`none`; see [OfficeQA evaluation](../recipes/officeqa.md#check-train-evaluate).

`final` means the adapter selected by `finalize`, which defaults to the current adapter. It does not mean “the
highest-scoring checkpoint.” The framework does not automatically evaluate the final adapter or run baselines.

## What survives training, and what gets deployed?

| Item | Location | Used for |
|---|---|---|
| Adapter files | Git versions and the run's `checkout/` | Deployment or the starting point of a new run. |
| Learner state | `workspace/state/`, with per-step snapshots | Continuing the learning method, such as its search history or candidate pool. |
| Results and logs | `learning_material/` and run records | Learning, inspection, and experiment accounting. |
| Acting runtime state | Location chosen by the pipeline or adapter runtime | One execution's working data, such as a shared lemma library. |

A final adapter includes `CARD.md` with provenance and recorded evaluation results. Deployment needs the adapter
and the environment its exports depend on; it does not need the Evolver or its state. Starting a new training run
from that adapter starts fresh learner state. Resuming an unfinished run restores its saved state and progress.

A template may allow learned memories or examples inside the adapter. They then travel as adapter content.
Recording a trajectory during training alone does not make it part of the deployed package.

## Available in this version

Version 0.1.0 includes the `prompt-only`, `lean-collab`, `mwm`, `harness2-codex` and `continual-harness` templates and
the `codex`, `claude`, `gepa`, `skillopt`, `mwm`, `harness2_upstream` and `continual_harness` Evolvers. OfficeQA and CL-Bench (database, poker) provide end-to-end task integrations;
the Lean template can be deployed, but its complete training pipeline has not been migrated.

For detailed contracts, continue to [Adapter](adapter.md), [Evolver](evolver.md), [Trainer](trainer.md), or
[Task integration](task.md). To implement a method, see [Custom Evolver integration](custom-evolver.md).