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.

1. Inspect the available contract #

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 #

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 #

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:

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:

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.

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 #

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 for repeated cases and the workbench to inspect the full context and trace.

Other ways to build and call it #

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

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

The workbench drives the same framework through a copilot and a harness workspace. For Python embedding:

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 for runtime and trust requirements.