hypswarm 0.0.1__tar.gz

hypswarm-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: voodoomods/hypgraph
+          ref: harmony-study            # the coordination layer lives here until it merges and releases
+          path: hypgraph
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]" --no-deps && pip install httpx pytest "mypy==2.4.0" "ruff==0.17.2" fastmcp anthropic
+      - run: python -m ruff check src tests --output-format=github
+      - run: python -m mypy --strict src/hypswarm
+        env:
+          MYPYPATH: ${{ github.workspace }}/hypgraph/src
+      - run: python -m pytest -q
+        env:
+          HYPGRAPH_SRC: ${{ github.workspace }}/hypgraph/src

hypswarm-0.0.1/.github/workflows/pages.yml

@@ -0,0 +1,33 @@
+# hypswarm.com: publish site/ to GitHub Pages. Runs on push to main once Pages is enabled for the repository
+# (Settings → Pages → Source: GitHub Actions) and the domain's DNS points at GitHub, as hypgraph.com's does.
+name: pages
+on:
+  push:
+    branches: [main]
+    paths: ["site/**", ".github/workflows/pages.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: python -c "import re,sys;s=open('site/index.html').read();bad=re.findall(r'(?:href|src)=\"/(?!/)',s);sys.exit('root-absolute paths: %d'%len(bad) if bad else 0)"
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deploy
+        uses: actions/deploy-pages@v4

hypswarm-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+# Tag v0.1.0a1 → build the sdist and wheel, test the wheel, publish to PyPI with trusted publishing (no API token:
+# the "pypi" environment and a trusted publisher for this repository are configured on pypi.org).
+# Don't tag a release before HypGraph's coordination layer is on PyPI (hypgraph>=0.4): the wheel would not install.
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - name: The tag matches the package version
+        run: test "v$(python -c 'import re;print(re.search(r"__version__ = \"(.+?)\"", open("src/hypswarm/__init__.py").read())[1])')" = "${GITHUB_REF_NAME}"
+      - name: The wheel works on its own
+        run: |
+          python -m venv /tmp/w && /tmp/w/bin/pip install dist/*.whl
+          /tmp/w/bin/hypswarm --version
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

hypswarm-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+*.hypgraph
+*.hypgraph-journal
+.claude/
+.env
+.venv/

hypswarm-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

hypswarm-0.0.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: hypswarm
+Version: 0.0.1
+Summary: Run one agent or a swarm of them on a task, with a HypGraph record as the only shared state. This release reserves the name; the alpha is on GitHub.
+Project-URL: Homepage, https://hypswarm.com
+Project-URL: Source, https://github.com/voodoomods/hypswarm
+Project-URL: Record, https://hypgraph.com
+Author: Nicolas Houghtaling, VoodooMods LLC
+Maintainer: VoodooMods LLC
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,hypgraph,multi-agent,orchestration,research,swarm
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="https://raw.githubusercontent.com/voodoomods/hypswarm/main/site/assets/hypswarm.svg" width="72" alt=""></p>
+
+<h1 align="center">hypswarm</h1>
+<p align="center"><b>Many agents. One record.</b><br>
+Run one agent or a swarm of them on a research or building task, with a <a href="https://hypgraph.com">HypGraph</a>
+record as the only shared state.<br>
+<a href="https://hypswarm.com">hypswarm.com</a> · <a href="https://github.com/voodoomods/hypswarm">source</a> ·
+<a href="https://hypgraph.com">HypGraph</a></p>
+
+---
+
+**This release reserves the name.** The alpha — the scheduler, workers, external seats over MCP, the record server
+mode, the OpenAI-compatible and Anthropic adapters — lives on [GitHub](https://github.com/voodoomods/hypswarm) and
+installs from there until HypGraph's coordination layer is on PyPI:
+
+```bash
+pip install "hypgraph @ git+https://github.com/voodoomods/hypgraph@harmony-study"
+pip install git+https://github.com/voodoomods/hypswarm
+```
+
+Made by Nicolas Houghtaling at [VoodooMods LLC](https://github.com/voodoomods). Apache-2.0.

hypswarm-0.0.1/README.md

@@ -0,0 +1,21 @@
+<p align="center"><img src="https://raw.githubusercontent.com/voodoomods/hypswarm/main/site/assets/hypswarm.svg" width="72" alt=""></p>
+
+<h1 align="center">hypswarm</h1>
+<p align="center"><b>Many agents. One record.</b><br>
+Run one agent or a swarm of them on a research or building task, with a <a href="https://hypgraph.com">HypGraph</a>
+record as the only shared state.<br>
+<a href="https://hypswarm.com">hypswarm.com</a> · <a href="https://github.com/voodoomods/hypswarm">source</a> ·
+<a href="https://hypgraph.com">HypGraph</a></p>
+
+---
+
+**This release reserves the name.** The alpha — the scheduler, workers, external seats over MCP, the record server
+mode, the OpenAI-compatible and Anthropic adapters — lives on [GitHub](https://github.com/voodoomods/hypswarm) and
+installs from there until HypGraph's coordination layer is on PyPI:
+
+```bash
+pip install "hypgraph @ git+https://github.com/voodoomods/hypgraph@harmony-study"
+pip install git+https://github.com/voodoomods/hypswarm
+```
+
+Made by Nicolas Houghtaling at [VoodooMods LLC](https://github.com/voodoomods). Apache-2.0.

hypswarm-0.0.1/docs/DESIGN.md

@@ -0,0 +1,193 @@
+# hypswarm — design, alpha
+
+*Draft 1, 2026-10-24. Not built yet. Written after four harmony pilots (37 runs of agent teams coordinating
+through a HypGraph record), whose logs are the evidence for most choices below.*
+
+**One sentence.** hypswarm runs one agent or a swarm of them on a research or building task, with a HypGraph
+record as the only shared state: the record schedules the work, accepts it, stops what became pointless, and
+writes the report; models are called only to do work and to judge exceptions.
+
+---
+
+## 1. What the pilots taught, and what it forces
+
+| Observed | Consequence for the design |
+|---|---|
+| Most of what an orchestrator model did was mechanical: what is open, who is on what, is this done, accept it. In pilot 3 those were 25–40 % of its calls. | The scheduler is code, not a model. A model is called only for judgement. |
+| Sub-agents worked past done until the record told them they were done; they returned when it did. | Every tool reply carries the agent's control state. No agent asks whether it is finished. |
+| An order's predicate could be unmeetable with the agent's tools; the lead reworked it three times. | Orders are meetable by construction (D-10): the record decides done-ness from what was written under the lease. |
+| Two workers re-derived the same numbers in one run; the record's lease stopped a third. | Parallel workers are safe only because the record leases targets. Parallelism is a scheduler feature, not a prompt instruction. |
+| The best reports came from the record condition: every number traceable, the trap named. | The report is generated from the record; the model writes interpretation under it and the linter gates it. |
+| A whole run cost cents; the cost was retries and turns, never the checks. | The budget is enforced by the scheduler in calls and dollars, per run and per order, and shown in every reply. |
+
+## 2. Build or borrow
+
+**Decision: a thin harness of our own over an OpenAI-compatible chat adapter, with LangChain and Anthropic as
+optional adapters, and MCP as the worker protocol.** Reasons:
+
+- The control loop *is* the record. LangGraph and deepagents exist to hold agent state in a graph of their own,
+  checkpoint it and route between nodes; here the record is the state and the checkpoint, and routing is the
+  scheduler. Building on them means two state machines that disagree. Pegasus runs on deepagents and pays for
+  that in middleware stacks and 35,000-token calls.
+- The study runner (`Pegasus/pod/dev/study_runner.py`, condition C) is already a working embryo in ~200 lines
+  of its own loop plus `langchain_core`'s message and tool types. Nothing in it needs LangChain's agent
+  machinery. The model-facing surface is four tool shapes and one call: `model(messages, tools) -> message`.
+- An OpenAI-compatible adapter covers DeepInfra, OpenAI, NVIDIA NIM, vLLM, Ollama, Together and most gateways
+  with one `httpx` client. Anthropic gets its own adapter. A `langchain` adapter wraps any `BaseChatModel` so
+  LangChain users bring their models without us depending on LangChain.
+- **MCP is the worker protocol.** The HypGraph MCP server already exposes `my_work`, the record tools and
+  `return_work`. A worker is anything that can hold an MCP session and act on a work order: hypswarm's built-in
+  worker, a human developer's Claude Code or Cursor session, or a third-party agent. That is how "usable by
+  humans and agents" is met without two code paths: a person and an agent take the same order from the same
+  board, and the record can't tell them apart except by name.
+
+Dependencies of the core: `hypgraph`, `httpx`. Extras: `[anthropic]`, `[langchain]`, `[mcp]` (FastMCP client,
+to drive external workers), `[server]`. Python ≥ 3.10. Stdlib `dataclasses` for config; no pydantic in the core.
+
+## 3. The agent
+
+There is one program. "Solo scientist" and "orchestrator with a swarm" are the same program with different
+seats and a worker count.
+
+### 3.1 Seats, not personalities
+
+A seat is a declared capability bound to one author name in the record. Prompts stay short; the work order
+carries the task.
+
+| Seat | What it does | Model? |
+|---|---|---|
+| **worker** | Takes orders from the board; writes runs, results, claims; returns. Declares `takes` (kinds of work) and `tools` (data tools it may use). | yes |
+| **reviewer** | Takes review orders. Named in the record's `Policy.reviewers`, so its verdicts count. Never reviews its own author's work (the record refuses). | yes |
+| **lead** | Called at exceptions only: an order NOT MET after two reworks, a contested claim, an empty frontier with unsettled questions, and the report's interpretation. | yes, deeper model |
+| **instrument** | Not a model. A job runner (CI, a lab) that files runs as the policy's `instrument`, so its results are lab-recorded rather than agent-reported. | no |
+| **operator** | A person. Approves budgets, answers escalations, resolves objections. Reached through the record (a question node + a notification), never through chat state. | no |
+
+A solo scientist is one worker seat that is also a reviewer of nobody (its claims stay unchecked, honestly) plus a
+lead that is the same model; the scheduler still issues it orders from the board, one at a time. A swarm is *k*
+workers and *r* reviewers pulling in parallel.
+
+### 3.2 The worker loop
+
+```
+order = my_work()                          # the record's text: objective, target, premises, known, predicates with recipes
+loop (≤ turn cap, ≤ order budget):
+    reply = model(system=seat prompt, messages=[order, …], tools=data tools + record tools)
+    run its tool calls; every record write returns the order's predicate status
+    stop when the model calls return_work, or the reply says every predicate is met and the model stops calling tools
+```
+
+The worker holds no state between orders. It can be killed and another worker takes the lease when it expires.
+Its context is the order text plus its own turn history, nothing else; the record is read on demand with `show`.
+
+### 3.3 The scheduler (no model calls)
+
+```
+until every question is settled, or the budget is spent, or the operator stops it:
+    board = question_board()
+    cancel_moot()                                               # premises that fell
+    settle()                                                    # returned orders with every predicate met
+    for order in returned and not met:
+        rework ≤ 2 (what is missing, from check_work)           # then escalate to the lead seat
+    for question in board where open, no order, a worker is idle:
+        issue_work(question → best-fit worker by takes; default predicates)
+    for question where answered and unchecked, a reviewer is idle:
+        issue_work(answering claim → reviewer, [reviewed])      # one review settles a question
+    for experiment on the frontier (planned, unleased), a worker is idle:
+        issue_work(experiment → worker)
+    wait for a return (asyncio), or a lease to expire
+report: order the lead to write the interpretation under report(); submit only when check_text passes
+```
+
+Best-fit is deterministic (a worker's `takes` against the target's type and the question's words, idle first),
+like Pegasus's dispatcher. Every scheduler action is already an event in the record (orders are task nodes;
+acceptance is a decision), so the run's audit trail is the record itself.
+
+### 3.4 Many angles, one record
+
+A swarm attacks a problem from several angles by construction: the lead (or the task author) adds rival
+hypotheses with `alternative_to` and experiments that `tests` them with stated expectations; `next_experiments`
+ranks by how well they separate the hypotheses; workers take different experiments under leases; results that
+share a run or data count as one line of support; a claim built on a withdrawn premise goes AT RISK and the
+orders resting on it are cancelled. None of that is new code; it is what the record already derives. hypswarm's
+job is to keep workers pulling from it.
+
+### 3.5 Building tasks
+
+Same program, one convention: the CI runner is the `instrument`. A requirement is a question. A design choice is
+a decision `based_on` the claims that justify it, flagged REVISIT when one falls. A change is a run (`code`
+artifact = the commit sha) that produced a result (tests passed of tests run), filed by CI as lab-recorded.
+"The change makes the tests pass" is a claim with a k/n measurement bound to that result, so the agent can't
+assert it; only the instrument can produce the number. A regression is a withdrawal with a blast radius. No new
+node types.
+
+## 4. Enterprise grade, concretely
+
+- **One record server, many stateless workers.** `hypgraph serve --writable` (or the MCP server over HTTP) is
+  the single writer; workers talk to it over MCP/HTTP with a bearer per seat, never to the SQLite file. Workers
+  scale horizontally and die safely; the record is the checkpoint and the audit log.
+- **Budget as a hard rule.** Per run and per order, in calls and dollars; the scheduler refuses to issue an
+  order that can't fit; the worker sees calls remaining in every reply. Spend is read from the host's meter when
+  one exists (Pegasus's proxy ledger), else counted from the provider's usage fields.
+- **Provenance of the run itself.** Every run files one `run` node of kind `agent` holding: hypswarm version,
+  record version, the seats and their models, prompt hashes, tool versions, seeds, start/finish. A run is
+  reproducible from the record and the seeds.
+- **Secrets never in the record.** API keys live in the adapters' environment; the record holds author names and
+  hashes. Tool outputs are scrubbed before they are written as notes (the Pegasus scrubber, ported).
+- **Resumable, idempotent.** A restarted run reads the board and continues; orders carry leases with expiry;
+  nothing is re-issued that is open, nothing re-done that is settled.
+- **Observable.** Structured logs (one JSON line per scheduler action and model call, with the order code),
+  optional OpenTelemetry spans, and `hypswarm status` reading the board. The Atlas gets an *Orders* card.
+- **Typed, tested, versioned.** A typed public API (`hypswarm.run(task, seats, record, budget)`), `py.typed`,
+  mypy-clean, a test suite that runs every scheduler path on a stub model in seconds, the same preregistered
+  task suite as the harmony study for end-to-end checks, semantic versioning, Apache-2.0.
+- **A CLI people can operate.** `hypswarm run --record study.hypgraph --task task.md --seats seats.toml
+  --budget 2.00`, `hypswarm status`, `hypswarm stop`, `hypswarm resume`, `hypswarm report`.
+
+## 5. Measuring it
+
+hypswarm joins the harmony study as **condition E, "record-scheduled swarm"**: four workers in parallel, one
+reviewer, a lead called only at exceptions, same task suite, same caps, same subject model, preregistered as a
+deviation before it runs. Against C it isolates two things: how much of the lead's cost the scheduler removes
+(calls per run, lead calls per run), and what parallelism does to wall time at the same spend. Against B it is
+the comparison that matters for the paper. The study already meters every call and labels every unit, so no new
+instrumentation is needed. Prediction, stated now: calls per run near D's (≈ 80), lead calls under 10, wall time
+cut by roughly the worker count on families with independent sub-questions, and no change on F7's cascade,
+which is sequential by nature.
+
+## 6. Build order (alpha)
+
+1. **Scaffold** (`src/hypswarm/`): `seats.py`, `providers/` (openai_compat, anthropic, langchain), `worker.py`,
+   `scheduler.py`, `budget.py`, `run.py` (the public API), `cli.py`; tests on a stub provider.
+2. **Port condition C** from the study runner into it, then make the study harness run condition E through
+   hypswarm. Measure (§5).
+3. **MCP workers**: external agents join a run by holding an MCP session; the scheduler sees them as seats.
+4. **Operator surface**: `hypswarm status`, the Atlas Orders card, operator questions through the record.
+5. **Building adapter**: CI as instrument, the commit-as-artifact convention, one worked example repo.
+
+Step 2 is the one that produces a number; everything after it is shaped by that number.
+
+## 7. What hypswarm is not
+
+Not a chat framework, not a prompt library, not a place where state lives. If a feature needs the agents to
+remember something the record doesn't hold, the record is missing a node type, and that is where the fix goes.
+
+---
+
+## First real-model run (2026-10-24, plumbing, not a study result)
+
+`Pegasus/pod/dev/hypswarm_smoke_host.py`: harmony-suite family F1 on seed 0 (the dry-run seed), DeepSeek-V4.1-Flash
+for every seat, three workers + a critic + a lead, the study's sandboxed python tool, run inside the agent
+container through the proxy so every call was metered under its own label.
+
+| | hypswarm alpha | condition C in pilots 2–4 (same family, same model) |
+|---|---|---|
+| finished | yes, every question settled | 7 of 8 runs |
+| calls | **59** (lead 4: the report only) | 92–150 (lead 11–26) |
+| metered $ | **0.019** (priced and ledger agree to the cent) | 0.029–0.050 |
+| orders | 8: 4 answers + 4 reviews, 0 reworks, all accepted by the record | 5–12, 1–5 reworks |
+| workers returned on their own | 8 of 8 | about half |
+| score | 4 of 4, no trap | — |
+| wall | 67 s (3 workers in parallel) | 4–11 min |
+
+One run on one seed, unpreregistered, so it proves the plumbing and sizes the expectation, nothing more. The
+measured comparison is condition E in the harmony study, preregistered first.

hypswarm-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hypswarm"
+version = "0.0.1"
+description = "Run one agent or a swarm of them on a task, with a HypGraph record as the only shared state. This release reserves the name; the alpha is on GitHub."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Nicolas Houghtaling" }, { name = "VoodooMods LLC" }]
+maintainers = [{ name = "VoodooMods LLC" }]
+keywords = ["agents", "multi-agent", "research", "hypgraph", "orchestration", "swarm"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://hypswarm.com"
+Source = "https://github.com/voodoomods/hypswarm"
+Record = "https://hypgraph.com"
+
+[project.scripts]
+hypswarm = "hypswarm.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hypswarm"]

hypswarm-0.0.1/site/404.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Not found — hypswarm</title>
+<script>
+  // Served for a missing path at any depth: resolve links from the site root, "/" on hypswarm.com and "/<repo>/"
+  // on <owner>.github.io.
+  document.write('<base href="' + (location.hostname.endsWith('.github.io') ? '/' + location.pathname.split('/')[1] + '/' : '/') + '">');
+</script>
+<link rel="icon" href="assets/hypswarm.svg" type="image/svg+xml">
+<link rel="stylesheet" href="assets/site.css"></head>
+<body><main class="wrap" style="padding:96px 16px;text-align:center">
+<div class="kicker">404 · no order here</div>
+<h1 class="title" style="font-size:clamp(34px,6vw,64px)">No seat at this address.</h1>
+<p class="lede">The lease on this page ran out. Try <a href="./">the start</a> or <a href="https://hypgraph.com">HypGraph</a>.</p></main></body></html>

hypswarm-0.0.1/site/CNAME

@@ -0,0 +1 @@
+hypswarm.com

hypswarm-0.0.1/site/assets/hypswarm.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="hypswarm">
+  <rect width="64" height="64" rx="14" fill="#0a0d14"/>
+  <g fill="none" stroke-width="2.5" stroke-linecap="round">
+    <path d="M32 32 L16 18" stroke="#7cf3ff"/>
+    <path d="M32 32 L48 18" stroke="#7cf3ff"/>
+    <path d="M32 32 L14 42" stroke="#b18cff" stroke-dasharray="3 4"/>
+    <path d="M32 32 L50 42" stroke="#b18cff" stroke-dasharray="3 4"/>
+    <path d="M32 32 L32 52" stroke="#7cf3ff"/>
+  </g>
+  <circle cx="32" cy="32" r="7" fill="#4ee08a"/>
+  <circle cx="16" cy="18" r="4" fill="#7cf3ff"/>
+  <circle cx="48" cy="18" r="4" fill="#7cf3ff"/>
+  <circle cx="14" cy="42" r="4" fill="#b18cff"/>
+  <circle cx="50" cy="42" r="4" fill="#b18cff"/>
+  <circle cx="32" cy="52" r="4" fill="none" stroke="#ff4d5e" stroke-width="2.5"/>
+</svg>

hypswarm-0.0.1/site/assets/site.css

@@ -0,0 +1,207 @@
+/* hypgraph.com — one stylesheet. Dark by default, light via prefers-color-scheme or the toggle (html[data-theme]). */
+
+:root {
+  --bg: #06080d; --bg2: #0b0f17; --panel: #0f1520; --panel2: #131b29;
+  --ink: #e8eef7; --ink2: #a3b0c2; --ink3: #64748b; --line: #1c2533; --line2: #2a3648;
+  --accent: #7cf3ff; --violet: #b18cff; --green: #4ee08a; --red: #ff4d5e; --amber: #ffb547;
+  --glow: 0 0 0 1px rgba(124, 243, 255, .18), 0 10px 40px rgba(124, 243, 255, .08);
+  --mono: ui-monospace, "JetBrains Mono", "SFMono-Regular", "Cascadia Code", Menlo, Consolas, monospace;
+  --sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --r: 14px; --max: 1160px;
+  color-scheme: dark;
+}
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme="dark"]) {
+    --bg: #f7f8fb; --bg2: #eef1f6; --panel: #ffffff; --panel2: #f3f5f9;
+    --ink: #0d1321; --ink2: #475569; --ink3: #8a96a8; --line: #dbe1ea; --line2: #c7d0dd;
+    --accent: #0b6bcb; --violet: #6d4bd8; --green: #0a7a3c; --red: #c4182a; --amber: #a35f00;
+    --glow: 0 0 0 1px rgba(11, 107, 203, .12), 0 10px 30px rgba(13, 19, 33, .06);
+    color-scheme: light;
+  }
+}
+:root[data-theme="light"] {
+  --bg: #f7f8fb; --bg2: #eef1f6; --panel: #ffffff; --panel2: #f3f5f9;
+  --ink: #0d1321; --ink2: #475569; --ink3: #8a96a8; --line: #dbe1ea; --line2: #c7d0dd;
+  --accent: #0b6bcb; --violet: #6d4bd8; --green: #0a7a3c; --red: #c4182a; --amber: #a35f00;
+  --glow: 0 0 0 1px rgba(11, 107, 203, .12), 0 10px 30px rgba(13, 19, 33, .06);
+  color-scheme: light;
+}
+
+*, *::before, *::after { box-sizing: border-box; }
+html { -webkit-text-size-adjust: 100%; scroll-behavior: smooth; }
+@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }
+body { margin: 0; background: var(--bg); color: var(--ink); font: 16px/1.6 var(--sans); }
+a { color: var(--accent); text-decoration-thickness: 1px; text-underline-offset: 3px; }
+code, pre, kbd { font-family: var(--mono); }
+code { font-size: .9em; background: var(--panel2); border: 1px solid var(--line); border-radius: 6px; padding: 1px 6px; }
+pre { margin: 0; }
+img, svg { max-width: 100%; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 4px; }
+.skip { position: absolute; left: -9999px; } .skip:focus { left: 16px; top: 16px; z-index: 99; background: var(--panel); padding: 8px 12px; }
+
+.wrap { max-width: var(--max); margin: 0 auto; padding: 0 16px; }
+@media (min-width: 720px) { .wrap { padding: 0 28px; } }
+
+/* ── nav ── */
+.nav { position: sticky; top: 0; z-index: 50; backdrop-filter: blur(12px); -webkit-backdrop-filter: blur(12px);
+  background: color-mix(in srgb, var(--bg) 78%, transparent); border-bottom: 1px solid var(--line); }
+.nav .wrap { display: flex; align-items: center; gap: 18px; height: 58px; }
+.brand { display: flex; align-items: center; gap: 10px; color: var(--ink); text-decoration: none; font-weight: 700;
+  letter-spacing: -.01em; font-size: 17px; }
+.brand img { width: 28px; height: 28px; }
+.brand b { font-family: var(--mono); font-weight: 600; color: var(--accent); }
+.nav nav { display: flex; gap: 4px; margin-left: auto; align-items: center; }
+.nav nav a { color: var(--ink2); text-decoration: none; padding: 6px 10px; border-radius: 8px; font-size: 14px; }
+.nav nav a:hover, .nav nav a[aria-current="page"] { color: var(--ink); background: var(--panel2); }
+.iconbtn { background: none; border: 1px solid var(--line2); color: var(--ink2); width: 34px; height: 34px;
+  border-radius: 9px; cursor: pointer; display: inline-grid; place-items: center; font-size: 15px; }
+.iconbtn:hover { color: var(--ink); border-color: var(--accent); }
+@media (max-width: 760px) { .nav nav a.hide-sm { display: none; } }
+@media (max-width: 420px) { .nav nav a { padding: 6px 6px; font-size: 13px; } .brand span { display: none; } }
+
+/* ── hero ── */
+.hero { position: relative; overflow: hidden; border-bottom: 1px solid var(--line); }
+.hero canvas { position: absolute; inset: 0; width: 100%; height: 100%; opacity: .9; }
+.hero::after { content: ""; position: absolute; inset: 0; pointer-events: none;
+  background: radial-gradient(ellipse 70% 60% at 50% 40%, transparent 0%, var(--bg) 85%); }
+.hero .wrap { position: relative; z-index: 2; padding-top: 88px; padding-bottom: 72px; text-align: center; }
+.eyebrow { display: inline-flex; gap: 8px; align-items: center; font-family: var(--mono); font-size: 12px;
+  letter-spacing: .14em; text-transform: uppercase; color: var(--ink2); border: 1px solid var(--line2);
+  background: color-mix(in srgb, var(--panel) 70%, transparent); padding: 5px 12px; border-radius: 999px; }
+.eyebrow i { width: 7px; height: 7px; border-radius: 50%; background: var(--green); box-shadow: 0 0 10px var(--green); }
+h1.title { font-size: clamp(38px, 7.4vw, 86px); line-height: 1.02; letter-spacing: -.035em; margin: 22px 0 18px;
+  font-weight: 800; }
+h1.title .l2 { display: block; background: linear-gradient(92deg, var(--accent), var(--violet) 55%, var(--green));
+  -webkit-background-clip: text; background-clip: text; color: transparent; }
+.lede { font-size: clamp(17px, 2.1vw, 21px); color: var(--ink2); max-width: 760px; margin: 0 auto; }
+
+/* ── the door ── */
+.door { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; max-width: 920px; margin: 40px auto 0; text-align: left; }
+@media (max-width: 720px) { .door { grid-template-columns: 1fr; } }
+.portal { position: relative; display: block; text-decoration: none; color: var(--ink); background: var(--panel);
+  border: 1px solid var(--line2); border-radius: var(--r); padding: 22px 22px 20px; box-shadow: var(--glow);
+  transition: transform .18s ease, border-color .18s ease; overflow: hidden; }
+.portal:hover { transform: translateY(-2px); border-color: var(--accent); }
+@media (prefers-reduced-motion: reduce) { .portal { transition: none; } .portal:hover { transform: none; } }
+.portal .who { font-family: var(--mono); font-size: 12px; letter-spacing: .14em; text-transform: uppercase; color: var(--accent); }
+.portal.agent .who { color: var(--violet); }
+.portal h2 { margin: 6px 0 6px; font-size: 26px; letter-spacing: -.02em; }
+.portal p { margin: 0 0 14px; color: var(--ink2); font-size: 15px; }
+.portal .go { font-family: var(--mono); font-size: 14px; color: var(--ink); }
+.portal .go::after { content: " →"; color: var(--accent); }
+.portal pre { font-size: 12.5px; background: var(--bg2); border: 1px solid var(--line); border-radius: 9px; padding: 9px 11px;
+  overflow-x: auto; color: var(--ink2); margin-bottom: 12px; }
+
+/* ── sections ── */
+section.block { padding: 72px 0; border-bottom: 1px solid var(--line); }
+.kicker { font-family: var(--mono); font-size: 12px; letter-spacing: .16em; text-transform: uppercase; color: var(--accent); }
+h2.h { font-size: clamp(28px, 4vw, 42px); letter-spacing: -.025em; line-height: 1.12; margin: 8px 0 12px; }
+.sub { color: var(--ink2); max-width: 760px; font-size: 17px; margin: 0 0 28px; }
+.grid3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; }
+.grid2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: 14px; }
+.grid4 { display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px; }
+.grid2 > *, .grid3 > *, .grid4 > *, .door > *, .play > *, .doc > * { min-width: 0; }
+@media (max-width: 960px) { .grid3, .grid4 { grid-template-columns: 1fr 1fr; } }
+@media (max-width: 620px) { .grid3, .grid2, .grid4 { grid-template-columns: 1fr; } }
+.card { background: var(--panel); border: 1px solid var(--line); border-radius: var(--r); padding: 18px 18px 16px; }
+.card h3 { margin: 4px 0 6px; font-size: 17px; letter-spacing: -.01em; }
+.card p { margin: 0; color: var(--ink2); font-size: 15px; }
+.card .n { font-family: var(--mono); font-size: 12px; color: var(--ink3); }
+.card.rule h3::before { content: "◆ "; color: var(--accent); font-size: 12px; vertical-align: 2px; }
+
+/* terminal */
+.term { background: #05070b; color: #d7e2f0; border: 1px solid var(--line2); border-radius: var(--r); overflow: hidden;
+  box-shadow: var(--glow); }
+:root[data-theme="light"] .term { background: #0d1321; }
+.term .bar { display: flex; gap: 6px; align-items: center; padding: 10px 12px; border-bottom: 1px solid #1c2533; }
+.term .bar i { width: 10px; height: 10px; border-radius: 50%; background: #2a3648; }
+.term .bar span { margin-left: 8px; font: 12px var(--mono); color: #64748b; }
+.term pre { padding: 16px 18px; font-size: 13.5px; line-height: 1.6; white-space: pre-wrap; word-break: break-word; min-height: 320px; }
+.term .p { color: #7cf3ff; } .term .x { color: #ff6b7a; } .term .ok { color: #4ee08a; } .term .dim { color: #64748b; }
+.term .caret { display: inline-block; width: 8px; height: 1.1em; background: #7cf3ff; vertical-align: -2px; animation: blink 1s steps(1) infinite; }
+@keyframes blink { 50% { opacity: 0; } }
+@media (prefers-reduced-motion: reduce) { .term .caret { animation: none; } }
+
+/* code blocks with copy */
+.code { position: relative; background: var(--bg2); border: 1px solid var(--line); border-radius: 11px; }
+.code pre { padding: 13px 15px; overflow-x: auto; font-size: 13.5px; line-height: 1.55; color: var(--ink); }
+.code .copy { position: absolute; top: 7px; right: 7px; font: 12px var(--mono); background: var(--panel); color: var(--ink2);
+  border: 1px solid var(--line2); border-radius: 7px; padding: 3px 8px; cursor: pointer; }
+.code .copy:hover { color: var(--ink); border-color: var(--accent); }
+.code .lbl { position: absolute; top: -9px; left: 12px; font: 11px var(--mono); background: var(--bg); color: var(--ink3);
+  padding: 0 6px; letter-spacing: .08em; text-transform: uppercase; }
+.stack > * + * { margin-top: 14px; }
+
+/* atlas frame */
+.atlas-frame { height: 640px; border: 1px solid var(--line2); border-radius: var(--r); overflow: hidden; box-shadow: var(--glow); }
+@media (max-width: 900px) { .atlas-frame { height: 82vh; } }
+.atlas-frame .atlas { --hg-bg: var(--bg2); --hg-bg1: var(--panel); --hg-bg2: var(--panel2); --hg-panel: var(--panel);
+  --hg-ink: var(--ink); --hg-ink2: var(--ink2); --hg-ink3: var(--ink3); --hg-line: var(--line); --hg-line2: var(--line2);
+  --hg-accent: var(--accent); --hg-light-bg: var(--bg2); --hg-light-bg1: var(--panel); --hg-light-bg2: var(--panel2);
+  --hg-light-panel: var(--panel); --hg-light-ink: var(--ink); --hg-light-ink2: var(--ink2); --hg-light-ink3: var(--ink3);
+  --hg-light-line: var(--line); --hg-light-line2: var(--line2); --hg-light-accent: var(--accent); }
+.note { font-size: 14px; color: var(--ink3); margin-top: 10px; }
+
+/* buttons */
+.btn { display: inline-flex; align-items: center; gap: 8px; font: 600 15px var(--sans); text-decoration: none; cursor: pointer;
+  padding: 10px 16px; border-radius: 10px; border: 1px solid var(--line2); color: var(--ink); background: var(--panel); }
+.btn:hover { border-color: var(--accent); }
+.btn.primary { background: var(--accent); color: #031016; border-color: transparent; }
+:root[data-theme="light"] .btn.primary { color: #fff; }
+@media (prefers-color-scheme: light) { :root:not([data-theme="dark"]) .btn.primary { color: #fff; } }
+.btn:disabled { opacity: .5; cursor: default; }
+.row { display: flex; gap: 10px; flex-wrap: wrap; align-items: center; }
+
+/* page header for inner pages */
+.phead { padding: 56px 0 28px; border-bottom: 1px solid var(--line); }
+.phead h1 { font-size: clamp(32px, 5vw, 52px); letter-spacing: -.03em; line-height: 1.06; margin: 10px 0 10px; }
+.phead p { color: var(--ink2); font-size: 18px; max-width: 780px; margin: 0; }
+.doc { display: grid; grid-template-columns: 220px minmax(0, 1fr); gap: 40px; padding: 36px 0 80px; }
+@media (max-width: 900px) { .doc { grid-template-columns: 1fr; gap: 0; } .toc { display: none; } }
+.toc { position: sticky; top: 76px; align-self: start; font-size: 14px; }
+.toc a { display: block; color: var(--ink2); text-decoration: none; padding: 4px 0 4px 10px; border-left: 2px solid var(--line); }
+.toc a:hover { color: var(--ink); border-left-color: var(--accent); }
+.prose h2 { font-size: 26px; letter-spacing: -.02em; margin: 44px 0 10px; scroll-margin-top: 80px; }
+.prose h2:first-child { margin-top: 0; }
+.prose h3 { font-size: 18px; margin: 26px 0 8px; scroll-margin-top: 80px; }
+.prose p, .prose li { color: var(--ink); max-width: 76ch; }
+.prose ul, .prose ol { padding-left: 22px; }
+.prose table { border-collapse: collapse; width: 100%; font-size: 14px; display: block; overflow-x: auto; }
+.prose th, .prose td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
+.prose th { font: 12px var(--mono); letter-spacing: .06em; text-transform: uppercase; color: var(--ink2); }
+.prose blockquote { margin: 14px 0; padding: 10px 14px; border-left: 3px solid var(--accent); background: var(--panel); color: var(--ink2); }
+.callout { border: 1px solid var(--line2); border-left: 3px solid var(--violet); background: var(--panel); border-radius: 10px;
+  padding: 14px 16px; margin: 18px 0; }
+.callout b { color: var(--violet); }
+
+/* verify */
+.drop { border: 2px dashed var(--line2); border-radius: var(--r); padding: 40px 20px; text-align: center; background: var(--panel);
+  cursor: pointer; transition: border-color .15s; }
+.drop.over, .drop:hover { border-color: var(--accent); }
+.vres { margin-top: 18px; }
+.vres .big { font-size: 22px; font-weight: 700; }
+.vres .good { color: var(--green); } .vres .bad { color: var(--red); } .vres .warn { color: var(--amber); }
+.kv { display: grid; grid-template-columns: max-content 1fr; gap: 4px 16px; font-size: 14px; margin-top: 10px; }
+.kv dt { font-family: var(--mono); color: var(--ink3); } .kv dd { margin: 0; font-family: var(--mono); word-break: break-all; }
+
+/* playground */
+.play { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
+@media (max-width: 900px) { .play { grid-template-columns: 1fr; } }
+.field { display: flex; flex-direction: column; gap: 5px; margin-bottom: 12px; }
+.field label { font: 12px var(--mono); letter-spacing: .06em; text-transform: uppercase; color: var(--ink2); }
+.field textarea, .field input, .field select { font: 14px var(--sans); color: var(--ink); background: var(--bg2);
+  border: 1px solid var(--line2); border-radius: 9px; padding: 9px 11px; width: 100%; }
+.field textarea.mono { font-family: var(--mono); font-size: 13px; }
+.out { background: var(--bg2); border: 1px solid var(--line); border-radius: 11px; padding: 14px 16px; min-height: 120px;
+  font: 13.5px/1.55 var(--mono); white-space: pre-wrap; word-break: break-word; }
+.out .x { color: var(--red); } .out .ok { color: var(--green); } .out .dim { color: var(--ink3); }
+.chips { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 12px; }
+.chip { font: 13px var(--sans); background: var(--panel2); border: 1px solid var(--line2); color: var(--ink2); border-radius: 999px;
+  padding: 5px 11px; cursor: pointer; }
+.chip:hover { color: var(--ink); border-color: var(--accent); }
+
+/* footer */
+footer { padding: 40px 0 56px; color: var(--ink3); font-size: 14px; }
+footer .wrap { display: flex; gap: 24px; flex-wrap: wrap; justify-content: space-between; }
+footer a { color: var(--ink2); }
+footer .slogan { font-family: var(--mono); color: var(--ink2); }

hypswarm-0.0.1/site/index.html

@@ -0,0 +1,238 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>hypswarm — many agents, one record</title>
+<meta name="description" content="hypswarm runs one agent or a swarm of them on a research or building task with a HypGraph record as the only shared state: the record schedules, accepts, stops and reports; models only do work and judge exceptions.">
+<meta property="og:title" content="hypswarm — many agents, one record">
+<meta property="og:description" content="Run one agent or a swarm of them on a task with a HypGraph record as the only shared state. The record schedules, accepts, stops and reports; models do work and judge exceptions.">
+<meta property="og:type" content="website">
+<meta property="og:url" content="https://hypswarm.com/">
+<meta name="twitter:card" content="summary">
+<link rel="icon" href="assets/hypswarm.svg" type="image/svg+xml">
+<link rel="alternate" type="text/plain" href="llms.txt" title="For language models">
+<link rel="stylesheet" href="assets/site.css">
+<script>try{const t=localStorage.getItem('hg-theme');if(t)document.documentElement.dataset.theme=t}catch(e){}</script>
+<style>
+  .seats td:first-child{white-space:nowrap}
+  .trace{font-family:var(--mono);font-size:13px;line-height:1.55}
+  .trace .k{color:var(--violet)} .trace .ok{color:var(--green)} .trace .dim{opacity:.6}
+  .alpha{display:inline-block;border:1px solid var(--line);border-radius:999px;padding:2px 10px;font-size:12px;letter-spacing:.04em;text-transform:uppercase;opacity:.8}
+</style>
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+<header class="nav"><div class="wrap">
+  <a class="brand" href="./"><img src="assets/hypswarm.svg" alt=""><span>hyp<b>swarm</b></span></a>
+  <nav aria-label="Site"><a href="#agents">Agents</a><a href="#engineers">Engineers</a><a href="#seats">Seats</a>
+    <a href="#status" class="hide-sm">Status</a>
+    <a href="https://hypgraph.com" class="hide-sm">HypGraph</a>
+    <a href="https://github.com/voodoomods/hypswarm" class="hide-sm">GitHub</a>
+    <button class="iconbtn" data-toggle-theme type="button" aria-label="Toggle light and dark">◐</button></nav>
+</div></header>
+
+<main id="main">
+<section class="hero">
+  <div class="wrap">
+    <span class="eyebrow"><i></i> alpha · built on HypGraph · Python 3.11+</span>
+    <h1 class="title">Many agents.<span class="l2">One record.</span></h1>
+    <p class="lede">hypswarm runs one agent or a swarm of them on a research or building task, with a
+      <a href="https://hypgraph.com">HypGraph</a> record as the only shared state. The record schedules the work,
+      accepts it against predicates it checks itself, stops what a fallen premise made pointless, and writes the
+      report. Models are called to do work and to judge exceptions — nothing else.</p>
+
+    <div class="door" role="group" aria-label="Choose your way in">
+      <a class="portal agent" href="#agents">
+        <div class="who">For agents &amp; people</div>
+        <h2>Take a seat</h2>
+        <p>A seat is a name in the record. Hold it over MCP from Claude Code, Cursor or any client: the scheduler
+          issues you orders, the record tells you when each one is done, and it holds you to the same rules as
+          every other seat. Machine-readable: <code>/llms.txt</code>.</p>
+        <pre>hypgraph --db study.hypgraph --as nicolas mcp
+# my_work → do it → return_work</pre>
+        <span class="go">How a seat works</span>
+      </a>
+      <a class="portal human" href="#engineers">
+        <div class="who">For engineers</div>
+        <h2>Run a swarm</h2>
+        <p>One task, a few seats, a budget. The scheduler makes no model calls; workers hold no state; the record
+          is the audit log and it verifies by hash. Any OpenAI-compatible endpoint or Anthropic as the model;
+          workers in one process or against a record server.</p>
+        <pre>pip install hypswarm
+hypswarm run --task task.toml --seats seats.toml --record study.hypgraph</pre>
+        <span class="go">Set it up</span>
+      </a>
+    </div>
+  </div>
+</section>
+
+<section class="block">
+  <div class="wrap grid2" style="align-items:center">
+    <div>
+      <div class="kicker">The record is the orchestrator</div>
+      <h2 class="h">What a run looks like when nobody has to coordinate.</h2>
+      <p class="sub">Four questions about an eval, three workers, a critic, a lead. The scheduler issues an order per
+        open question to whichever seat fits, the workers write runs, results and claims into the record, the record
+        accepts each order the moment its predicates are met, a critic's review settles each question, and the lead is
+        called once: to write the interpretation under the facts. This trace is from a real run on a suite instance
+        (the harmony study's dry-run seed, not a study seed).</p>
+      <ul class="sub" style="padding-left:20px;margin-top:-10px">
+        <li>every order is a node; acceptance is a decision based on the evidence that met it</li>
+        <li>a worker's reply after each write says whether its order is done — so it returns</li>
+        <li>claims are checked as they're written; the report is linted against the record before it's accepted</li>
+      </ul>
+    </div>
+    <div class="term" aria-label="A scheduler trace from a real hypswarm run">
+      <div class="bar"><i></i><i></i><i></i><span>hypswarm run — F1 seed 0</span></div>
+      <pre class="trace"><span class="k">dispatch</span>  T1 → analyst    Q1 What is A's accuracy?
+<span class="k">dispatch</span>  T2 → stats      Q3 Is A significantly better than B?
+<span class="k">dispatch</span>  T3 → engineer   Q4 In which subset is A's advantage largest?
+<span class="k">returned</span>  T2 stats · 6 calls · returned itself
+<span class="ok">settled </span>  T2 → D1   claim_made: CL2
+<span class="k">dispatch</span>  T4 → critic     review CL2
+<span class="k">returned</span>  T1 analyst · 8 calls
+<span class="ok">settled </span>  T1 → D2   claim_made: CL1
+<span class="k">dispatch</span>  T5 → stats      Q2 What is B's accuracy?
+<span class="k">returned</span>  T4 critic · 6 calls
+<span class="ok">settled </span>  T4 → D3   reviewed: RV1
+<span class="dim">… 8 orders, 0 reworks, 0 escalations, lead: 4 calls (the report)</span>
+<span class="ok">BOARD   </span>  Q1 SETTLED · Q2 SETTLED · Q3 SETTLED · Q4 SETTLED — 4 of 4
+<span class="ok">report  </span>  accepted (checked against the record)</pre>
+    </div>
+  </div>
+</section>
+
+<section class="block" id="seats">
+  <div class="wrap">
+    <div class="kicker">Seats, not personalities</div>
+    <h2 class="h">One program, from a solo scientist to a swarm.</h2>
+    <p class="sub">A seat is a declared capability bound to an author name in the record. Prompts stay short; the
+      work order carries the task. A solo scientist is one worker seat. A swarm is several, pulling in parallel
+      under the record's leases, which is what keeps two of them off the same work.</p>
+    <div class="grid4">
+      <div class="card rule"><h3>worker</h3><p>Takes orders from the board; writes runs, results and claims;
+        returns. Declares what it <code>takes</code> so the scheduler can match it to work.</p></div>
+      <div class="card rule"><h3>reviewer</h3><p>Takes review orders. Named as a reviewer on the investigation, so
+        its verdicts count — never on its own author's work; the record refuses that.</p></div>
+      <div class="card rule"><h3>lead</h3><p>Called only at exceptions — an order stuck after two reworks, a contested
+        claim, an empty frontier with questions open — and for the report's interpretation.</p></div>
+      <div class="card rule"><h3>instrument</h3><p>Not a model. A job runner (CI, a lab) that files runs the record
+        marks as lab-recorded, so "the tests pass" is its number, not the agent's.</p></div>
+      <div class="card rule"><h3>external</h3><p>No model: a person or another agent holds the name over MCP. The
+        scheduler issues it orders like any seat and waits. If the lease runs out, the record returns the order on
+        its behalf.</p></div>
+      <div class="card rule"><h3>operator</h3><p>A person, reached through the record: approves budgets, answers
+        escalations, resolves objections. Never through chat state.</p></div>
+    </div>
+  </div>
+</section>
+
+<section class="block">
+  <div class="wrap">
+    <div class="kicker">What the record does for the team</div>
+    <h2 class="h">Coordination that isn't a prompt.</h2>
+    <div class="grid4">
+      <div class="card"><div class="n">scheduler</div><h3>No model calls</h3><p>Issue from the question board, settle
+        met orders, rework the rest twice, cancel what became moot, bring the lead in only at exceptions. All of it
+        is code over the record's derived state.</p></div>
+      <div class="card"><div class="n">workers</div><h3>No state</h3><p>A worker's context is its order and its own
+        turns. It can be killed; the lease expires and another takes the order. Every reply says whether it's done.</p></div>
+      <div class="card"><div class="n">claims</div><h3>Can't be flattered</h3><p>HypGraph's checks run on every
+        write: numbers bound to results, no "never" without the count, no "significantly" without the test, and the
+        record binds the numbers it already holds before it refuses anything.</p></div>
+      <div class="card"><div class="n">budget</div><h3>A rule, not a hope</h3><p>Calls and dollars, per run and per
+        order, enforced by the scheduler and shown to every seat in every reply.</p></div>
+      <div class="card"><div class="n">audit</div><h3>You didn't write it</h3><p>Orders are task nodes, acceptance is
+        a decision, the run files its own provenance. The record <i>is</i> the log, and it verifies by hash.</p></div>
+      <div class="card"><div class="n">notices</div><h3>The world can interrupt</h3><p>A file declared corrupt
+        withdraws its artifact, registers the fix, and reaches every order issued from then on. Orders resting on the
+        fallen premise are cancelled, and nothing else is.</p></div>
+    </div>
+  </div>
+</section>
+
+<section class="block" id="agents">
+  <div class="wrap grid2" style="align-items:start">
+    <div>
+      <div class="kicker">For agents &amp; people</div>
+      <h2 class="h">Hold a seat over MCP.</h2>
+      <p class="sub">The HypGraph MCP server is the whole interface. <code>my_work</code> shows your open orders —
+        objective, target, premises with their standing, what's already been tried, each predicate with how to meet
+        it. You register runs, record results, make claims; every reply tells you whether the order is done; you
+        return it. The record can't tell a person from an agent except by name.</p>
+      <div class="callout"><b>If you are an agent reading this.</b> Call <code>my_work</code>. Do what the order
+        says, from the files, with the tools you have. Write what you found as runs, results and claims — a claim's
+        numbers must come from a result, and a refusal tells you the honest version. When the reply says every
+        predicate is met, call <code>return_work</code> with a note of at most 120 words. Don't work past done.</div>
+    </div>
+    <div class="stack">
+      <div class="code"><span class="lbl">seats.toml</span><pre>[[seats]]
+name = "nicolas"
+role = "worker"
+external = true</pre></div>
+      <div class="code"><span class="lbl">your side</span><pre>pip install "hypgraph[mcp]"
+claude mcp add hypgraph -- hypgraph --db study.hypgraph --as nicolas mcp
+# then, in the session: my_work</pre></div>
+    </div>
+  </div>
+</section>
+
+<section class="block" id="engineers">
+  <div class="wrap grid2" style="align-items:start">
+    <div>
+      <div class="kicker">For engineers</div>
+      <h2 class="h">A task, some seats, a budget.</h2>
+      <p class="sub">The core depends on <code>hypgraph</code> and <code>httpx</code>. The OpenAI-compatible adapter
+        covers DeepInfra, OpenAI, NVIDIA NIM, vLLM, Ollama and most gateways; <code>hypswarm[anthropic]</code> adds
+        the Messages API. Any object with <code>async complete(messages, tools) -&gt; Reply</code> is a model.</p>
+      <p class="sub">Workers can share one process or talk to a record served by <code>hypgraph serve --writable</code>
+        — one record server, stateless workers on other processes or machines, and the file still verifies.</p>
+      <div class="row"><a class="btn primary" href="https://github.com/voodoomods/hypswarm">Source &amp; README</a>
+        <a class="btn" href="https://github.com/voodoomods/hypswarm/blob/main/docs/DESIGN.md">The design</a></div>
+    </div>
+    <div class="stack">
+      <div class="code"><span class="lbl">python</span><pre>from hypswarm import Task, Seat, Budget, run
+from hypswarm.providers import OpenAICompatible
+
+task = Task(title="Does A beat B",
+            mission="Two models were scored on the same items (items.csv). Find out whether A beats B.",
+            questions=[("Q1", "What is A's accuracy?"), ("Q2", "Is A significantly better than B?")],
+            files={"items.csv": open("items.csv", "rb").read()})
+seats = [Seat("analyst", "worker", takes=("accuracy", "counts")),
+         Seat("stats", "worker", takes=("significant", "test")),
+         Seat("critic", "reviewer"), Seat("lead", "lead")]
+model = OpenAICompatible("deepseek-ai/DeepSeek-V4.1-Flash", base_url="https://api.deepinfra.com/v1/openai")
+result = asyncio.run(run(task, seats, model, record="study.hypgraph", budget=Budget(max_calls=150)))
+print(result.report)</pre></div>
+      <div class="code"><span class="lbl">record server</span><pre>hypgraph --db study.hypgraph serve --writable --no-browser
+hypswarm run --task task.toml --seats seats.toml --record-url http://127.0.0.1:8765</pre></div>
+    </div>
+  </div>
+</section>
+
+<section class="block" id="status">
+  <div class="wrap">
+    <div class="kicker">Status</div>
+    <h2 class="h">Alpha, and being measured before it's described.</h2>
+    <p class="sub"><span class="alpha">alpha 0.1</span>&nbsp; hypswarm grew out of the harness the HypGraph harmony
+      study runs agent teams on, and its first measured use is as a condition in that study, preregistered before it
+      runs. Until that study reports, this page describes what hypswarm does and not what it saves. What's built:
+      the scheduler, workers, external seats over MCP, the record server mode, the OpenAI-compatible and Anthropic
+      adapters, budgets, notices, and a test suite that runs every scheduler path on a scripted model in seconds.
+      Next: the building adapter, with CI as the instrument.</p>
+  </div>
+</section>
+</main>
+
+<footer class="foot"><div class="wrap">
+  <span>hypswarm is built on <a href="https://hypgraph.com">HypGraph</a>. Apache-2.0.</span>
+  <span>Made by Nicolas Houghtaling at <a href="https://github.com/voodoomods">VoodooMods LLC</a>.</span>
+</div></footer>
+<script>
+  document.querySelector('[data-toggle-theme]')?.addEventListener('click',()=>{
+    const d=document.documentElement,cur=d.dataset.theme||(matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light');
+    d.dataset.theme=cur==='dark'?'light':'dark';try{localStorage.setItem('hg-theme',d.dataset.theme)}catch(e){}});
+</script>
+</body>
+</html>

hypswarm-0.0.1/site/llms.txt

@@ -0,0 +1,26 @@
+# hypswarm
+
+> Run one agent or a swarm of them on a research or building 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, and writes the report. Models are called to do work and to judge exceptions, nothing else. Alpha; measured as a preregistered condition in the HypGraph harmony study before any claim about it is made.
+
+## 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, target, 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 and its result values), `add` (a claim with its numbers bound to a result; `answers` the question or `supports` / `challenges` the hypothesis), `review` (if you are a reviewer; never your own author's work).
+- 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.
+- An order you returned is no longer yours; if it comes back, it is a new order with what was missing.
+
+## If you are an engineer
+
+    pip install hypswarm                     # core: hypgraph + httpx
+    pip install "hypswarm[anthropic]"        # + the Anthropic adapter
+    hypswarm run --task task.toml --seats seats.toml --record study.hypgraph
+    hypswarm run ... --record-url http://127.0.0.1:8765      # against `hypgraph serve --writable`
+
+Seats: worker (takes orders), reviewer (verdicts count), lead (exceptions and the report), instrument (a job runner filing lab-recorded runs), external (a person or agent over MCP), operator (a person, through the record). Python API: `run(task, seats, models, record=..., budget=Budget(max_calls, max_usd))`.
+
+Source and design: https://github.com/voodoomods/hypswarm (docs/DESIGN.md). Apache-2.0. Made by Nicolas Houghtaling at VoodooMods LLC.

hypswarm-0.0.1/site/robots.txt

@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /
+Sitemap: https://hypswarm.com/sitemap.xml

hypswarm-0.0.1/site/sitemap.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>https://hypswarm.com/</loc></url>
+  <url><loc>https://hypswarm.com/llms.txt</loc></url>
+</urlset>

hypswarm-0.0.1/src/hypswarm/__init__.py

@@ -0,0 +1,12 @@
+"""
+hypswarm — run one agent or a swarm of them on a task, with a HypGraph record as the only shared state.
+
+This release only reserves the name. The alpha lives at https://github.com/voodoomods/hypswarm and installs from
+there until HypGraph's coordination layer is on PyPI:
+
+    pip install "hypgraph @ git+https://github.com/voodoomods/hypgraph@harmony-study"
+    pip install git+https://github.com/voodoomods/hypswarm
+"""
+
+__version__ = "0.0.1"
+__all__ = ["__version__"]

hypswarm-0.0.1/src/hypswarm/cli.py

@@ -0,0 +1,21 @@
+"""The placeholder's command line: says where the real thing is."""
+
+from __future__ import annotations
+
+import sys
+
+from . import __doc__ as _about
+from . import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if args and args[0] in ("--version", "-V"):
+        print(f"hypswarm {__version__} (name reservation; the alpha is at https://github.com/voodoomods/hypswarm)")
+        return 0
+    print((_about or "").strip())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())