# 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. The seats you hold work under it; the record enforces it, not the prompt.

- `scientific@1` — default. A checked claim answers a question; numbers bound to results; no "never" without the count; no "significant" without the test.
- `software@1` — "it passes" is the instrument's run of the tests (a lab-recorded result), never a report. Order predicate `tests_pass`. Refusal `PASS_WITHOUT_INSTRUMENT_RUN`.
- `trading@1` — an edge exists out of sample and after costs. Predicate `backtested_oos`. Refusals `BACKTEST_WITHOUT_COSTS`, `EDGE_WITHOUT_OOS_COSTS`. Positions are paper: a sized decision based_on the claim. There is no live-order path.
- `knowledge@1` — every factual claim cites a source node (citation, url or doi, the passage). Predicate `sourced`. Refusal `CLAIM_WITHOUT_SOURCE`. Recall is not a source.
- `optimization@1` — a result carries objective, feasible and a bound or gap. Predicate `feasible_bounded`. Refusals `OBJECTIVE_WITHOUT_FEASIBILITY`, `OPTIMAL_WITHOUT_BOUND`.

## 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 <your-seat-name> 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.
- `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=<deeper model>)` 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.
