# HypSwarm > Run one agent or a swarm of them on a research, engineering, trading, knowledge or optimisation task with a HypGraph record (https://hypgraph.com) as the only shared state. The record schedules the work (orders from its question board), accepts it (predicates the record checks), stops what a fallen premise made pointless, re-runs what authors computed (the instrument), and writes the report. Models are called to do work and to judge exceptions, nothing else. Alpha. ## Profiles A profile is pinned on the investigation and says what the record accepts and refuses in that discipline, and, since hypgraph 0.5, its workflow: the stages a question passes through and the gate out of each. The stage is derived, never set; the scheduler issues each question's stage order (the gates up to the next review as the done-when, to the seat the stage names; a review stage to a reviewer on the node the previous gate produced). A name (`trading`) is its newest version, `trading@2`; `trading@1` pins the pre-workflow one. The seats you hold work under it; the record enforces it, not the prompt. - `scientific@2` — default. Stages: conjectured (a hypothesis with predictions) → preregistered (an experiment with data.expected BEFORE any run) → run → evidenced → claimed → reviewed. Numbers bound to results; no "never" without the count; no "significant" without the test; a check on stale evidence does not count. - `software@2` — stages: implemented (an artifact kind=diff with meta base_sha, head_sha, files, part_of the question) → verified (`tests_pass_current`: the instrument's run that `uses` the current diff) → claimed → reviewed. Register the run with `uses=[the diff]`. Refusals `PASS_WITHOUT_INSTRUMENT_RUN`, `TESTS_ON_STALE_HEAD`, `REVIEW_BY_AUTHOR`. A failing suite: outcome negative and a claim stating the count; checked, a verified failure settles the requirement. - `trading@2` — stages: thesised (hypothesis) → preregistered (experiment: windows, costs, configurations, before the run) → backtested (`backtested`: oos_*, fees/slippage, trials) → claimed → risk-reviewed → positioned (a decision based_on the claim: kind=position with size, stop, review_date, paper=true, or kind=no_position) → monitored. Refusals `BACKTEST_WITHOUT_COSTS`, `EDGE_WITHOUT_OOS_COSTS`, `EDGE_WITHOUT_TRIALS`, `POSITION_WITHOUT_STOP`, `LIVE_ORDER`. There is no live-order path. - `knowledge@2` — stages: sourced (a source part_of the question: citation, url or doi, the passage, retrieved, kind) → claimed (`sourced`: the claim cites it) → checked. Refusals `CLAIM_WITHOUT_SOURCE`, `PASSAGE_MISSING`. Recall is not a source. No source: register the search as a run with its result and a claim kind=inconclusive derived from it. - `optimization@2` — stages: posed (an artifact kind=instance part_of the question) → modelled (hypothesis) → configured (experiment) → solved (`solved`: a run that `uses` the instance; objective, feasible, bound or gap, or feasible=false) → verified (the verifier reviews the result) → claimed → checked. Refusals `OBJECTIVE_WITHOUT_FEASIBILITY`, `OPTIMAL_WITHOUT_BOUND`, `SOLVED_WITHOUT_INSTANCE`, `OPTIMAL_ON_STALE_INSTANCE`. ## Examples (github.com/voodoomods/hypswarm/tree/main/examples; hypswarm.com/examples/) Ten runnable examples, free on scripted models, cents on a real provider: one per profile, the mixed swarm (LangChain + PydanticAI + CrewAI + Claude / Bedrock + a person on one record), a person as reviewer over MCP, a served record with tokens, stop-and-resume with a file withdrawn mid-run, a custom seat and toolkit. Bring your own agent: Seat(agent=langchain_agent(...) | pydantic_ai_agent(...) | crewai_agent(...)), or any async (AgentOrder) -> AgentOutcome. Model adapters: OpenAICompatible, Anthropic, Bedrock (Converse), LangChainModel. ## If you are an agent holding a seat A seat is an author name in the record. You hold it through the HypGraph MCP server: hypgraph --db study.hypgraph --as mcp - `my_work` lists your open orders: objective, the target's own content (a claim's statement, measurements and the results it rests on; a question's text), its premises with their standing, what has already been tried, each done-when predicate with how to meet it, the budget, the lease. - Do the work from the files with the tools you have. Write what you find into the record: `register_run` (a computation, its result values, and the exact code — print every value you register, with its name; the instrument re-runs the code), `add` (a claim with its numbers bound to a result; `answers` the question or `supports` / `challenges` the hypothesis; in the knowledge profile, `cites` a source you added), `review` (if you are a reviewer; never your own author's work; a reviewer writes verdicts, not claims). - Every reply tells you whether your order is done. When it says every predicate is met, call `return_work` with a note of at most 120 words. Do not work past done. - A refused claim says exactly what to fix and gives the honest sentence. Write that. - If a value the instrument re-ran is marked contradicted, that is what to recompute; a value merely not printed is not evidence against. - `stage` shows where each question stands in the profile's workflow and which gate is next; `completion` shows what the profile says "done" means for the whole investigation and which criteria are met. ## If you are an engineer pip install --pre hypswarm # core: hypgraph>=0.4 + httpx (--pre while it is an alpha) pip install --pre "hypswarm[anthropic]" # + the Anthropic adapter hypswarm run --task task.toml --profile software --record study.hypgraph hypswarm run --task task.toml --seats seats.toml --record-url http://127.0.0.1:8765 # against `hypgraph serve --writable --token ...` hypswarm profiles Seats: worker (takes orders), reviewer (verdicts count), lead (exceptions and the report), instrument (re-runs registered code; files lab-recorded runs), external (a person or agent over MCP), operator (a person, through the record). `Seat(..., escalate_to=)` is used from the first time the record sends that seat's work back NOT MET. Tools come from a registry (`toolkits.register(name, factory)`); hypswarm ships `files` (reads only bytes matching a live artifact). Python API: `run(task, seats | None, models, record=..., budget=Budget(max_calls, max_usd), folder=..., toolkits=[...], reproducer=..., resume=inv)`. Source, design and decisions: https://github.com/voodoomods/hypswarm (docs/DESIGN.md, docs/decisions/). Apache-2.0. Made by Nicolas Houghtaling at VoodooMods LLC. Disclaimer (https://hypswarm.com/disclaimer/): provided as is. A run bills your model provider for every call and its budget is best effort; the default sandbox runs model-written code as you and is not a security boundary; agents make mistakes, and standing is derived, not certified. Never present a swarm's output as advice.