# Quickstart

Build a summarizer whose output must be valid JSON with a nonempty `summary`.
Construction, validation, and the dry-run need no model API key. The final run
does. Start with the [1.3.0 installation](/install).

## 1. Inspect the available contract

```bash
hiveloom schema --json
hiveloom catalog tools --json
hiveloom catalog validators --json
```

The catalog includes installed extensions. Inspect it before choosing a
builtin; MCP tools are discovered separately from declared servers.

## 2. Create the harness and its output check

```bash
hiveloom init ./summarizer --name summarizer \
  --task 'Summarize the supplied text. Return only a JSON object with a nonempty "summary" string.' \
  --json

mkdir -p ./summarizer/schemas
cat > ./summarizer/schemas/output.json <<'JSON'
{
  "type": "object",
  "properties": {"summary": {"type": "string", "minLength": 1}},
  "required": ["summary"],
  "additionalProperties": false
}
JSON

hiveloom add validator --builtin output_schema \
  --schema-file schemas/output.json --dir ./summarizer --json
hiveloom set loop.require_verification true --dir ./summarizer --json

printf '%s\n' 'The library extended its opening hours after residents requested evening access.' \
  > ./summarizer/notes.txt
hiveloom validate ./summarizer --json
```

Use `init`, `add`, `set`, and `remove` to change `harness.yaml`; each mutation
validates and rolls back on error. Schema and code assets are ordinary files.
This example supplies the text directly, so it needs no file-reading tool.

## 3. Inspect the first request without a model call

```bash
hiveloom run ./summarizer --input-file ./summarizer/notes.txt --dry-run --json
```

Check the prompt, input, tools, and limits in the result. `--input-file` reads
file contents; `--input-text` sends literal text. Use these explicit forms
instead of legacy `--input`, which infers whether a value is a path.

Dry-run makes no model call. If a harness declares MCP servers, it still
contacts them to discover tools; this example declares none.

## 4. Make a real run

The default executor uses the `claude` provider:

```bash
export ANTHROPIC_API_KEY=sk-...
hiveloom run ./summarizer --input-file ./summarizer/notes.txt --json
```

To use another provider, inspect its catalog and set the model atomically:

```bash
hiveloom models openai --json
hiveloom set model openai/gpt-6-luna --dir ./summarizer --json
# Export OPENAI_API_KEY, then repeat the run above.
```

The JSON result contains status, output, verification verdicts, cost, and run
identity. Invalid output produces retry feedback while turns remain; an
unresolved failure is reported explicitly. The schema checks shape and a
nonempty field. It does not check that the summary is faithful to the input;
add a task-specific check when that is an acceptance requirement.

| Exit code | Meaning |
|---|---|
| `0` | Success |
| `1` | Verification failed |
| `2` | Guardrail halt |
| `3` | Invalid spec or request |
| `4` | Runtime failure |

Scripts should check both the exit code and JSON outcome before consuming an
answer as a success.

## 5. Read the evidence before changing the harness

```bash
hiveloom stats ./summarizer --json
hiveloom trace <run_id> --verify --json
hiveloom signal ./summarizer --json
```

`signal` locates failure patterns without a model call. One run is not enough
to establish an improvement. Use a [local evaluation](/evaluating) for repeated
cases and [the workbench](/workbench) to inspect the full context and trace.

| Next step | Command or guide |
|---|---|
| Draft a change for review | `hiveloom evolve ./summarizer --propose --json` |
| Review the queue | `hiveloom proposals list ./summarizer --json` |
| Inspect a proposal | `hiveloom proposals show ./summarizer <proposal_id> --json` |
| Explicitly apply it | `hiveloom proposals apply ./summarizer <proposal_id> --yes --json` |
| Assess subsequent runs | `hiveloom assess ./summarizer --json` |
| Measure keep-or-revert changes against an eval | [Signal-driven evolution](/signal-driven-evolution) |
| Run improvement across multiple rounds | [Research programs](/research); requires an eval or concepts charter |
| Re-enter a failure at a model call | [Journal and forks](/journal) |

## Other ways to build and call it

Model-driven construction uses a separate proposing model and may incur cost:

```bash
hiveloom generate 'Summarize supplied text as JSON with a nonempty summary.' \
  -o ./generated-summarizer --json
```

The [workbench](/workbench) drives the same framework through a copilot and a
harness workspace. For Python embedding:

```python
from hiveloom import run_harness

result = run_harness(
    "./summarizer",
    "The library now opens in the evening.",
    literal_input=True,
)
print(result.status, result.output)
```

Expose finished harnesses as MCP tools with `hiveloom mcp serve`, serve them
over HTTP, or package them for another machine. See [Deploying and
evolving](/deploying-and-evolving) for runtime and trust requirements.