HypSwarm
Examples

Ten swarms you can run before lunch.

Every example runs for free on scripted models and for cents on a real provider. The scripted models answer from values the example computed itself, through the same record tools, the same scheduler and the same refusals a real model meets — so what you see is the record's behaviour, not a mock of it. Several make a deliberately wrong first write so the trace shows the refusal and the honest rewrite.

pip install --pre hypswarm                                   # 01–05, 07–10
pip install --pre "hypswarm[langgraph,pydantic-ai,crewai]"   # 06, the mixed swarm
git clone https://github.com/voodoomods/hypswarm && cd hypswarm/examples/01-eval-report
python run.py --fresh            # add --trace for every tool call and reply, --model <id> for a real provider

One per profile

01

eval-report scientific

Two models scored on the same 1,000 items — does A beat B? Two workers count and compare, the instrument re-runs both and confirms every value, the critic settles each question, the lead's report is linted against the record. "Significantly" gets through only because the record ran the z-test on the bound counts.

refused: 'significantly': the bound counts (812/1,000 against 800/1,000) differ by 1.2 points, 95% interval −2.2 to 4.6, p = 0.49 — not significant at 0.05 [SIGNIFICANCE_NOT_SHOWN]
02

software-tests software

A CSV importer must keep a comma inside a quoted field. The tester registers the exact pytest command as its code; the instrument re-runs it and files a lab run; tests_pass is met by that run. The tester's claim of "passes", written before the re-run, is refused, the order is reworked, and the claim is accepted once the lab run has landed.

refused: 'passes' is asserted, but no supporting result comes from an instrument-recorded run — tests must be run by the instrument, not reported [PASS_WITHOUT_INSTRUMENT_RUN]
03

paper-trading trading

A mean-reversion thesis backtested on a held-out window with fees and slippage. The quant's first result has returns and no costs — refused before it is a result. The honest one carries out-of-sample return, in-sample return, drawdown, trades, fees and slippage; "edge" is said only if the after-cost number is positive. No live orders exist.

refused: result refused: a backtest result reports returns without the costs it charged [BACKTEST_WITHOUT_COSTS]
04

sourced-brief knowledge

Three facts. A claim from recall is refused; the researcher adds the source (citation, URL, the passage, the date) and the claim that cites it. With --model, an allowlisted fetch tool lets the model read the pages for itself; whatever it reads becomes a source node.

refused: a knowledge claim must cite a source node (citation, url or doi, the passage) — the record holds what was read, not what was recalled [CLAIM_WITHOUT_SOURCE]
05

optimal-with-bound optimization

Six customers, three depots, capacities. An objective without feasibility is refused; "optimal" needs a bound that meets the objective. The instance is small enough to enumerate, so the bound is exact and the instrument re-runs the enumeration.

refused: 'optimal' is asserted, but no supporting result carries a bound or gap — an incumbent without a bound is a solution, not an optimum [OPTIMAL_WITHOUT_BOUND]

The mixed swarm

06

mixed-swarm LangChainPydanticAICrewAIClaude / Bedrocka person

Five frameworks hold five seats on one record. A LangChain / LangGraph agent counts; a PydanticAI agent runs the test; a CrewAI crew reviews both through its own native tool-calling loop; the lead runs on Claude over the Anthropic API or on any model over Amazon Bedrock; you can take a reviewer seat over MCP. None of them knows about the others. The record refuses the same overclaims from each in the same words, the instrument re-runs whatever they register, and the budget counts the calls each framework reports.

seats = [Seat("analyst", "worker", agent=langchain_agent(lambda tools: create_react_agent(llm, tools))),
         Seat("stats",   "worker", agent=pydantic_ai_agent(lambda tools: Agent(model, tools=tools))),
         Seat("critic",  "reviewer", agent=crewai_agent(lambda tools, order: Crew(...))),
         Seat("lead",    "lead"),                                  # Anthropic("claude-sonnet-5-5") or Bedrock("…")
         Seat("nicolas", "reviewer", external=True)]               # hypgraph --db record.hypgraph --as nicolas mcp
=== SETTLED in 12.7s — 14 calls === Q1 settled CL1 (checked by critic) Q2 settled CL2 (checked by critic) seats and what held them: analyst worker agent:langchain_agent stats worker agent:pydantic_ai_agent critic reviewer agent:crewai_agent

A bridge hands the agent the order, the seat's system prompt and the record's tools in the framework's own tool shape, caps the framework's loop at the calls left in the run, and reports what it used. If the agent doesn't call return_work itself, the order is returned with its final answer as the note.

People and processes

07

human-reviewer MCP

The analyst answers; you review, from Claude Code, Cursor or the plain MCP server (hypgraph --db record.hypgraph --as nicolas mcp). Your review order carries the claim, its measurements, the code and the instrument's verdict, so you judge rather than recompute. --auto plays you from a second process so the example runs unattended.

08

served-record tokens

One hypgraph serve --writable with two tokens — the swarm's, bound to the harness and its seats, and a person's, bound to one name. The swarm runs over HTTP; the Atlas is open on the same server. Two probes before the run show the boundary: no token → 401; the person's token writing as the analyst → 403.

09

resume-and-notice resumenotice

A run stopped with an order open; a second run resumes the investigation and adopts the order as it stands. Then a file is declared corrupt mid-run: the record withdraws the artifact with the reason, every later order carries the notice, a worker's read_file refuses the stale bytes, and whatever rested on the file falls.

read_file('site_south.csv') → refused: site_south.csv matches A2, which the record withdrew — site_south.csv was exported in µg/L but labelled mg/L; use site_south_fixed.csv (mg/L).

Yours

10

custom-seat-and-toolkit toolkits.registerSeat(agent=…)

A toolkit is a factory over the run's folder; a seat is any async (AgentOrder) -> AgentOutcome. This one calls no model at all — forty lines of code hold the seat — and the record treats it exactly like a seat held by a frontier model. The framework bridges are this function written three times; write a fourth for yours.

What they share

  • Orders come from the record. The scheduler reads the question board and issues work; seats are matched on the words they take. A seat never picks its own work.
  • One write for a result and its claim. register_run records the run, the result and the claim whose numbers are bound to the result's values; the instrument re-runs the code before any review.
  • Done is the record's call. Every reply says MET / NOT MET per predicate and "return_work now" when all are; reworks say what was missing.
  • The budget is a rule, counted with calls in flight and printed in every reply.
  • Afterwards, hypgraph --db record.hypgraph serve opens the Atlas: claims and their standing, provenance, the work map, the refusal log.