AdaMAST documentation¶

On this page you will install AdaMAST and generate your first failure-mode taxonomy: a catalog of the ways your agent actually fails, learned from its own traces. The process requires two commands and one provider credential.

AdaMAST builds failure-mode taxonomies from agent traces (recorded task transcripts), checks that independent annotators can apply them consistently, and reuses the result for evaluation or runtime guidance. The documentation runs from the smallest standalone workflow to the most involved integration; you do not need Codex, Claude Code, or an agent harness to generate a taxonomy or judge a trace.

📦 Install AdaMAST¶

Requires Python 3.10 or newer.

Install from PyPI:
```
pip install adamast
```
Verify the installation (this performs no model calls):
```
adamast --help
python -m adamast.examples
adamast validate adamast-examples/traces.jsonl
```
The second command copies the bundled example files into ./adamast-examples/ so they work from any install.

The validation command reports the trace count, detected formats, input files, and empty trajectories.

Make it yours

The standard installation already includes the OpenAI adapter used in the first example. Anthropic, Google, and AWS Bedrock are optional provider installs; see Providers and models. Source and contributor installations are kept in the installation reference.

🧪 Generate your first taxonomy¶

Set one provider credential. This example uses OpenAI; the same workflow supports Anthropic, Google, and AWS Bedrock:
```
export OPENAI_API_KEY="..."
```

Run generation on the bundled example traces:

adamast generate \
  --provider openai \
  --model gpt-5-nano \
  --traces adamast-examples/traces.jsonl \
  --output ./taxonomy-run \
  --view

That one command runs the whole pipeline:

flowchart LR
    A["🧾 Normalize<br/>the traces"] --> B["✍️ Draft the A/B/C<br/>failure taxonomy"]
    B --> C["🤝 Four-annotator<br/>agreement process"]
    C --> D["📁 Auditable<br/>artifact bundle"]
    D --> E["🔎 Read-only browser<br/>field guide"]

Make it yours	Read
Bring your own trace data	Prepare traces
Your trace file already validates	Go directly to Generate a taxonomy
Use Anthropic, Google, or AWS Bedrock instead of OpenAI	Providers and models

🧭 Choose a workflow¶

Level	Goal	Start with
01 · Foundation	Generate and agreement-check a standalone taxonomy from completed traces	Prepare traces
02 · Evaluation	Apply a taxonomy to new traces or select a specialized judge	Judge traces
03 · Adaptive runtime	Accumulate traces and refine the active taxonomy over time	Runtime overview
04 · Host integration	Install the adaptive runtime into Codex or Claude Code	Codex or Claude Code

🧠 Core concepts¶

Three workflows appear throughout the docs:

Name	Meaning
Generation	The standalone starting point: take completed traces, create a taxonomy, and run the full inter-annotator agreement layer.
Judging	Applies an existing taxonomy to new evidence. The default judge returns every validated, evidence-backed failure code a trace supports, or none at all; other modes and judges cover single-code classification, mapping, coverage, taxonomy quality, calibration, and causal reflection.
Adaptive runtime	Everything above, added on top of a live agent: records new traces as you work, keeps a taxonomy active at task boundaries, and regenerates or refines it when thresholds are reached.

The full glossary (taxonomy, trace, checkpoint, judge, program) lives in Choose a workflow.

📚 What to read next¶

Question	Read
Which input shapes are accepted, and what is the canonical normalized record?	Trace formats
How do the four annotators, Fleiss kappa, coverage, and `review_required` results work?	Agreement gate
How do I set credentials and pick models for OpenAI, Anthropic, Google, and Bedrock?	Providers and models
What are `taxonomy.json`, the manifest, the intermediate artifacts, and the browser field guide?	Taxonomy outputs

The research method and evaluation are described in Fantastic Adaptive Taxonomies and How to Use Them.

Continue with Prepare traces to start Level 01, or with Choose a workflow if you want the full map first.