hypermind 0.22.0__tar.gz → 0.24.0__tar.gz

{hypermind-0.22.0 → hypermind-0.24.0}/CHANGELOG.md

@@ -14,7 +14,44 @@ changes only on major-version bumps.
 
 ## [Unreleased]
 
-_Current trunk; new work after v0.11.0._
+_Current trunk._
+
+## [0.23.0] — 2026-07-08
+
+### Added
+- **Distributed, Locust-style execution** — `hypermind.orgs.distributed`. A master coordinator shards a swarm across workers (other machines or local processes) over a TCP control plane (length-prefixed CBOR frames); each worker runs its shard as `OrgSim(lightweight=True)` against the **shared Relata namespace** and returns bounded aggregates, merged into one `OrgReport` (#177).
+  - `Coordinator` / `Worker`, `run_distributed(...)` (single-host convenience), and a `master` / `worker` CLI (`python -m hypermind.orgs.distributed`).
+  - Capacity-weighted shard planning; a worker that drops before returning is recorded as a failed shard — the run completes and notes it, never hangs.
+  - `OrgSim.export_aggregates()` for the merge; `OrgModel` wire (de)serialisation.
+
+## [0.22.0] — 2026-07-08
+
+### Added
+- **Batched Relata writes** — `RelataBackend(write_batch_size=N)` buffers claim rows and flushes via one bulk `batch_upsert` instead of a per-claim round-trip; `OrgSim` defaults to 64. ~batch× fewer round-trips at scale (#175).
+- **Bounded / streaming report** — `OrgSim(lightweight=True)` caps memory to O(members + windows), not O(records): per-member streaming aggregates + a rolling claim window, exact scorecard totals. `metrics.scorecard_from_aggregates(...)` (#176).
+- Parallel keypair generation at `testbed()` spin-up (thread pool; the crypto releases the GIL) — part of #177.
+
+## [0.21.0] — 2026-07-08
+
+### Added
+- **Native response-quality rubrics** — `hypermind.orgs.quality`: `sim.assess(question)` → `QualityReport`. Four rubric groups, all on by default, switchable via `disable`: native/deterministic (provenance coverage, dispute exposure, reputation support, consensus, abstention — verifiable from the signed ledger), judge-based faithfulness (grounding, hallucination rate, answer relevance, context precision), calibration (Brier, self-consistency), and context recall. Missing deps degrade to informational notes. `llm_judge(...)` factory.
+
+## [0.20.0] — 2026-07-08
+
+### Added
+- **Hybrid retrieval** — `reciprocal_rank_fusion(...)` and `hybrid_retriever(*retrievers, reranker=None)` fuse dense + entity-graph + lexical signals (RRF) with an optional cross-encoder rerank, over our own Relata data. Plugs into the existing `OrgSim(retriever=...)` seam.
+
+## [0.12.0] – [0.19.0] — 2026-06 … 2026-07
+
+### Added
+- **`hypermind.orgs` — the living-simulation engine.** Turn a declarative `OrgModel` / `Unit` / `Seat` into a running multi-agent simulation (research → publish → cite → dispute → resolve → learn → evolve) persisted to Relata, driven by pluggable `Interaction` strategies (`cooperative` / `adversarial` / `crowd`).
+  - **Template library**: `university`, `hospital`, `city_at_war`, `foreign_policy_cabinet`, `un_security_council`, `internet_crowd`, `research_lab`, … via `list_templates()` / `get_template()` — the core never imports them.
+  - **Per-agent models** (per-seat provider/model or a router) and **group-scoped native tools** (declarative or random grants; ungranted tools are absent, not refused).
+  - **Study → ask**: `sim.study(topic)` then `sim.ask(question)` — a transparent, queryable swarm that answers from what it learned, weighted by earned standing.
+  - **Proper RAG** for `ask`: lexical → semantic embeddings (`embedder=`, `openai_embedder`) → claim↔entity graph (`use_graph_retrieval`, `MentionGraph`) → real NER hooks (`llm_ner_extractor`, `chat_ner_extractor`, `pioneer_ner_extractor`) → Relata-backed retrieval (`relata_retriever`).
+  - **Scorecard & analysis**: reputation ranking, citation DAG, dispute ledger, Brier calibration (#151), convergence metrics (#152), memory-RAG (#153), deliberator mode (#154), tool-trace capture (#155), adversarial dynamics (#156), pluggable ground truth (#157), experiment/variant harness (#158), interventions (#159), visualization snapshots (#160), verifiable receipts (#161).
+- **Scalability hardening** across the engine: bounded peer window, O(1) member indices, top-k cross-pollination, concurrent think phase (`asyncio.gather` + semaphore) and concurrent blocking I/O (`asyncio.to_thread`).
+- `examples/org_university.py` and an expanded examples index.
 
 ## [0.11.0] — 2026-05-10
 

{hypermind-0.22.0 → hypermind-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.22.0
+Version: 0.24.0
 Summary: Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile
 Project-URL: Homepage, https://github.com/ZySec-AI/hypermind
 Project-URL: Documentation, https://github.com/ZySec-AI/hypermind/tree/main/docs
@@ -102,7 +102,7 @@ Agents share what they learn. Dispute what they doubt. Build trust over time.
 [![PyPI](https://img.shields.io/pypi/v/hypermind?color=4c8cff&label=pip%20install%20hypermind)](https://pypi.org/project/hypermind/)
 [![Python](https://img.shields.io/pypi/pyversions/hypermind?color=4c8cff)](https://pypi.org/project/hypermind/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-1753%20passing-brightgreen)](#testing--quality)
+[![Tests](https://img.shields.io/badge/tests-2133%20passing-brightgreen)](#testing--quality)
 [![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](#testing--quality)
 [![Status](https://img.shields.io/badge/status-v0.10-blue)](#project-status)
 
@@ -147,7 +147,7 @@ Open **http://127.0.0.1:8765** and you'll see:
 ```bash
 make run-fast      # skip the webui rebuild (when JS hasn't changed)
 make webui-dev     # Vite dev server with hot-reload on :5173
-make test          # 1753 tests pass, ~80s
+make test          # 2133 tests pass, ~80s
 make demo          # examples/01_hello_world from the CLI
 make demos         # all numbered tutorials + scenarios sequentially
 make help          # show all targets
@@ -232,6 +232,10 @@ report.print()        # reputation ranking · citation graph · dispute ledger
 - **Per-agent models.** Any seat can pin its own provider/model (`Seat("Professor", llm="anthropic", model="claude-opus-4-8")`), or hand `OrgSim` a router for random / cost-aware assignment.
 - **Native tools, group-scoped.** Tools (web search, retrieval, KB query, Relata research) are granted per unit/seat and enforced — an ungranted tool is *absent* from that agent's toolset. Grants can be declarative or randomised; register your own with `hypermind.orgs.register_tool(...)`.
 - **Relata end-to-end.** Organisation → tenant; member → private memory session (agent kid); claims / disputes / reputation → tenant-scoped ledger rows; chain of custody → the Merkle log. Restart replays the whole org.
+- **Study → ask (a queryable swarm).** Let the swarm learn a topic, then question it: `await sim.study(topic)` then `await sim.ask("...")` — every member recalls what it learned, reasons, and the answers are aggregated weighted by earned standing. `sim.ask` studies first automatically if you skip the explicit step.
+- **Proper RAG.** Retrieval for `ask` is pluggable: lexical (default), semantic embeddings (`embedder=`), the claim↔entity graph (`use_graph_retrieval=True`), or `hybrid_retriever(...)` which fuses dense + graph + lexical via Reciprocal Rank Fusion with an optional cross-encoder rerank. Relata *is* the vector store + graph (`relata_retriever(..., "search_knowledge" / "find_connections")`).
+- **Answer quality, natively.** `await sim.assess(question)` returns a `QualityReport` scoring grounding, hallucination rate, calibration (Brier), self-consistency, and hm-native rubrics that are *verifiable from the signed ledger* — provenance coverage, dispute exposure, reputation-weighted support. All rubrics on by default; missing deps (judge / ground-truth) degrade to informational notes.
+- **Scales like Locust.** `OrgSim(lightweight=True)` caps RAM to O(members), not O(records); Relata writes are batched. For horizontal scale, `hypermind.orgs.distributed` runs a **master/worker** control plane — shard a swarm across processes or machines against the shared Relata namespace, merged into one report (`python -m hypermind.orgs.distributed master/worker`, or `run_distributed(...)`).
 
 Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.
 

{hypermind-0.22.0 → hypermind-0.24.0}/README.md

@@ -14,7 +14,7 @@ Agents share what they learn. Dispute what they doubt. Build trust over time.
 [![PyPI](https://img.shields.io/pypi/v/hypermind?color=4c8cff&label=pip%20install%20hypermind)](https://pypi.org/project/hypermind/)
 [![Python](https://img.shields.io/pypi/pyversions/hypermind?color=4c8cff)](https://pypi.org/project/hypermind/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-1753%20passing-brightgreen)](#testing--quality)
+[![Tests](https://img.shields.io/badge/tests-2133%20passing-brightgreen)](#testing--quality)
 [![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](#testing--quality)
 [![Status](https://img.shields.io/badge/status-v0.10-blue)](#project-status)
 
@@ -59,7 +59,7 @@ Open **http://127.0.0.1:8765** and you'll see:
 ```bash
 make run-fast      # skip the webui rebuild (when JS hasn't changed)
 make webui-dev     # Vite dev server with hot-reload on :5173
-make test          # 1753 tests pass, ~80s
+make test          # 2133 tests pass, ~80s
 make demo          # examples/01_hello_world from the CLI
 make demos         # all numbered tutorials + scenarios sequentially
 make help          # show all targets
@@ -144,6 +144,10 @@ report.print()        # reputation ranking · citation graph · dispute ledger
 - **Per-agent models.** Any seat can pin its own provider/model (`Seat("Professor", llm="anthropic", model="claude-opus-4-8")`), or hand `OrgSim` a router for random / cost-aware assignment.
 - **Native tools, group-scoped.** Tools (web search, retrieval, KB query, Relata research) are granted per unit/seat and enforced — an ungranted tool is *absent* from that agent's toolset. Grants can be declarative or randomised; register your own with `hypermind.orgs.register_tool(...)`.
 - **Relata end-to-end.** Organisation → tenant; member → private memory session (agent kid); claims / disputes / reputation → tenant-scoped ledger rows; chain of custody → the Merkle log. Restart replays the whole org.
+- **Study → ask (a queryable swarm).** Let the swarm learn a topic, then question it: `await sim.study(topic)` then `await sim.ask("...")` — every member recalls what it learned, reasons, and the answers are aggregated weighted by earned standing. `sim.ask` studies first automatically if you skip the explicit step.
+- **Proper RAG.** Retrieval for `ask` is pluggable: lexical (default), semantic embeddings (`embedder=`), the claim↔entity graph (`use_graph_retrieval=True`), or `hybrid_retriever(...)` which fuses dense + graph + lexical via Reciprocal Rank Fusion with an optional cross-encoder rerank. Relata *is* the vector store + graph (`relata_retriever(..., "search_knowledge" / "find_connections")`).
+- **Answer quality, natively.** `await sim.assess(question)` returns a `QualityReport` scoring grounding, hallucination rate, calibration (Brier), self-consistency, and hm-native rubrics that are *verifiable from the signed ledger* — provenance coverage, dispute exposure, reputation-weighted support. All rubrics on by default; missing deps (judge / ground-truth) degrade to informational notes.
+- **Scales like Locust.** `OrgSim(lightweight=True)` caps RAM to O(members), not O(records); Relata writes are batched. For horizontal scale, `hypermind.orgs.distributed` runs a **master/worker** control plane — shard a swarm across processes or machines against the shared Relata namespace, merged into one report (`python -m hypermind.orgs.distributed master/worker`, or `run_distributed(...)`).
 
 Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.
 

{hypermind-0.22.0 → hypermind-0.24.0}/examples/README.md

@@ -87,6 +87,7 @@ Pick one that matches your domain.
 | File | Domain | What it shows |
 |---|---|---|
 | [`org_university.py`](org_university.py) | Any network | Spin up a templated org (university / city / UNO / crowd), run research → cite → dispute → resolve → evolve, print a reputation + citation report. Per-agent models + group-scoped tools, persisted to Relata. |
+| [`org_distributed.py`](org_distributed.py) | Scale-out | Locust-style distributed run: a master coordinator shards the swarm across workers (processes or machines) against the shared Relata namespace, merged into one report (`hypermind.orgs.distributed`). Single-host convenience + multi-machine CLI. |
 
 ### Pilot-shaped demonstrations
 

hypermind-0.24.0/examples/org_distributed.py

@@ -0,0 +1,74 @@
+"""THE STORY — one swarm, many workers: scale a simulation like Locust.
+
+The single-process engine (``examples/org_university.py``) is great to ~1000s of
+agents. Beyond that you scale *out*: ``hypermind.orgs.distributed`` runs a
+**master coordinator** that shards the swarm across **workers** — processes on
+this box or on other machines — each running its slice as
+``OrgSim(lightweight=True)`` against the **shared Relata namespace** (the source
+of truth). The coordinator merges every worker's bounded aggregates into one
+``OrgReport``.
+
+This script shows the single-host convenience path (``run_distributed`` starts a
+coordinator plus in-process workers over loopback) — the *same* code path as
+multi-machine. For true multi-machine, use the CLI instead::
+
+    # on the master host
+    python -m hypermind.orgs.distributed master --template university \
+        --topic "..." --members 10000 --rounds 8 --expected-workers 4 \
+        --host 0.0.0.0 --port 8765 --llm openai --llm-model openai/gpt-4o-mini
+
+    # on each worker host
+    python -m hypermind.orgs.distributed worker \
+        --master-host <master-ip> --port 8765 --capacity 2500
+
+PREREQUISITES
+  * A running Relata instance:   docker compose -f deploy/docker-compose.yml up -d relata
+  * export RELATA_URL=http://localhost:9090   RELATA_TOKEN=...
+  * export OPENAI_API_KEY=...   (workers build their own client from env)
+
+Run with:   python -m examples.org_distributed
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+
+async def main() -> None:
+    from hypermind.orgs.distributed import run_distributed
+    from hypermind.orgs.templates import university
+
+    relata_url = os.environ.get("RELATA_URL")
+    if not relata_url:
+        raise SystemExit(
+            "Set RELATA_URL (and RELATA_TOKEN) to a running Relata instance. "
+            "See deploy/docker-compose.yml."
+        )
+
+    model = university()  # the shape; run_distributed scales it across workers
+    report = await run_distributed(
+        model,
+        topic="What limits the accuracy of ab-initio protein folding?",
+        members=48,  # sharded across the workers below
+        rounds=4,
+        workers=4,  # 4 in-process workers over loopback (each ~12 members)
+        config={
+            "llm": "openai",
+            "llm_model": "openai/gpt-4o-mini",
+            "base_url": os.environ.get("OPENAI_BASE_URL"),  # e.g. OpenRouter
+            "relata_url": relata_url,
+            "relata_token": os.environ.get("RELATA_TOKEN"),
+        },
+    )
+
+    report.print()
+    sc = report.scorecard
+    print(
+        f"\nmerged across workers → {sc['claims']} claims · {sc['citations']} citations · "
+        f"{len(report.standings)} members"
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{hypermind-0.22.0 → hypermind-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "0.22.0"
+version = "0.24.0"
 description = "Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{hypermind-0.22.0 → hypermind-0.24.0}/src/hypermind/__init__.py

@@ -73,7 +73,7 @@ open = HyperMindAgent.open
 #: is held until the §External & human gates clear (IETF I-D, IANA,
 #: third-party audit, OpenSSF acceptance, ≥3 pilots) — at that point we
 #: cut ``1.0.0`` GA. See ROADMAP.md §Status snapshot.
-__version__ = "0.22.0"
+__version__ = "0.24.0"
 
 #: SLSA build-provenance level committed for every release artefact.
 #: Cosign keyless signing + slsa-github-generator + PEP 740 attestations

hypermind-0.24.0/src/hypermind/orgs/distributed/__init__.py

@@ -0,0 +1,135 @@
+"""Distributed, Locust-style execution for OrgSim (#177).
+
+A **master coordinator** shards a swarm across **workers** (processes on the
+same box or other machines) over a TCP control plane; every worker runs its
+shard as an ``OrgSim(lightweight=True)`` against the **shared Relata namespace**
+(the source of truth) and returns bounded aggregates, which the coordinator
+merges into one :class:`~hypermind.orgs.report.OrgReport`.
+
+Multi-machine (the Locust model)::
+
+    # on the master host
+    python -m hypermind.orgs.distributed master \
+        --template university --members 10000 --rounds 8 \
+        --expected-workers 4 --host 0.0.0.0 --port 8765
+
+    # on each worker host
+    python -m hypermind.orgs.distributed worker \
+        --master-host <master-ip> --port 8765 --capacity 2500 \
+        --llm openai --llm-model openai/gpt-4o-mini
+
+Single host (convenience — coordinator + in-process workers over loopback)::
+
+    from hypermind.orgs.distributed import run_distributed
+    from hypermind.orgs.templates import university
+    report = await run_distributed(university(), "protein folding",
+                                   members=2000, rounds=6, workers=8, config={...})
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from hypermind.orgs.distributed.coordinator import Coordinator
+from hypermind.orgs.distributed.planning import (
+    merge_results,
+    plan_shards,
+    seat_count,
+    validate_shardable,
+)
+from hypermind.orgs.distributed.provision import provision_hm_types
+from hypermind.orgs.distributed.worker import Worker, default_shard_runner
+from hypermind.orgs.model import OrgModel
+from hypermind.orgs.report import OrgReport
+
+logger = logging.getLogger("hypermind.orgs.distributed")
+
+__all__ = [
+    "Coordinator",
+    "DistributedError",
+    "Worker",
+    "default_shard_runner",
+    "merge_results",
+    "plan_shards",
+    "provision_hm_types",
+    "run_distributed",
+    "seat_count",
+    "validate_shardable",
+]
+
+
+class DistributedError(RuntimeError):
+    """Raised when a distributed run cannot produce any result (all shards failed)."""
+
+
+async def run_distributed(
+    model: OrgModel,
+    topic: str,
+    *,
+    members: int,
+    rounds: int,
+    workers: int = 4,
+    capacity_each: int = 1,
+    config: dict[str, Any] | None = None,
+    host: str = "127.0.0.1",
+    shard_runner: Any = None,
+) -> OrgReport:
+    """Run a distributed simulation on this host: start a coordinator and
+    ``workers`` in-process workers (over loopback), shard ``members`` across
+    them, and return the merged report.
+
+    Same code path as multi-machine — the only difference is the workers live in
+    this process instead of on remote hosts. Pass ``shard_runner`` to stub the
+    per-shard work (tests); omit it for the real ``OrgSim`` runner.
+
+    Raises ``ValueError`` up front if the shard plan isn't viable (#190) and
+    ``DistributedError`` if every shard fails (#191).
+    """
+    # Pre-flight: fail fast with a clear message if a shard would be too small.
+    validate_shardable(model, members, [capacity_each] * workers)
+
+    coord = Coordinator(
+        model,
+        topic,
+        members=members,
+        rounds=rounds,
+        expected_workers=workers,
+        host=host,
+        port=0,
+        config=config,
+    )
+
+    async def _serve() -> OrgReport:
+        return await coord.run()
+
+    coord_task = asyncio.create_task(_serve())
+    # Wait for the server to bind before workers dial in.
+    while coord.port == 0:
+        await asyncio.sleep(0.005)
+
+    worker_tasks = [
+        asyncio.create_task(
+            Worker(
+                host,
+                coord.port,
+                worker_id=f"w{i}",
+                capacity=capacity_each,
+                shard_runner=shard_runner,
+            ).run()
+        )
+        for i in range(workers)
+    ]
+    report = await coord_task
+    await asyncio.gather(*worker_tasks, return_exceptions=True)
+
+    # Surface shard failures loudly (#191).
+    failed = next((e for e in report.events if e["event"] == "shards_failed"), None)
+    succeeded = next((e["shards"] for e in report.events if e["event"] == "distributed"), 0)
+    if failed:
+        msg = f"{failed['count']} shard(s) failed: {failed['detail']}"
+        if succeeded == 0:
+            raise DistributedError(f"distributed run produced no results — {msg}")
+        logger.warning("distributed run completed with failures — %s", msg)
+    return report

hypermind-0.24.0/src/hypermind/orgs/distributed/__main__.py

@@ -0,0 +1,110 @@
+"""CLI for distributed OrgSim (#177): ``master`` and ``worker`` subcommands.
+
+    python -m hypermind.orgs.distributed master --template university \
+        --members 10000 --rounds 8 --expected-workers 4 --host 0.0.0.0 --port 8765
+
+    python -m hypermind.orgs.distributed worker --master-host <ip> --port 8765 \
+        --capacity 2500 --llm openai --llm-model openai/gpt-4o-mini
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+
+from hypermind.orgs.distributed.coordinator import Coordinator
+from hypermind.orgs.distributed.worker import Worker
+
+
+def _load_model(args: argparse.Namespace):
+    from hypermind.orgs.templates import get_template
+
+    return get_template(args.template)(namespace=args.namespace)
+
+
+async def _run_master(args: argparse.Namespace) -> int:
+    model = _load_model(args)
+    config = {
+        "llm": args.llm,
+        "llm_model": args.llm_model,
+        "relata_url": args.relata_url,
+        "relata_token": args.relata_token,
+        "base_url": args.base_url,
+        "api_key_env": args.api_key_env,
+    }
+    coord = Coordinator(
+        model,
+        args.topic,
+        members=args.members,
+        rounds=args.rounds,
+        expected_workers=args.expected_workers,
+        host=args.host,
+        port=args.port,
+        config=config,
+    )
+    print(
+        f"master: binding {args.host}:{args.port}, waiting for {args.expected_workers} worker(s)…"
+    )
+    report = await coord.run()
+    out = (
+        report.to_json() if hasattr(report, "to_json") else json.dumps(report.__dict__, default=str)
+    )
+    if args.output:
+        with open(args.output, "w") as f:
+            f.write(out)
+        print(f"master: wrote report → {args.output}")
+    else:
+        report.print()
+    return 0
+
+
+async def _run_worker(args: argparse.Namespace) -> int:
+    print(
+        f"worker {args.worker_id}: connecting to {args.master_host}:{args.port} (cap {args.capacity})…"
+    )
+    await Worker(
+        args.master_host, args.port, worker_id=args.worker_id, capacity=args.capacity
+    ).run()
+    print(f"worker {args.worker_id}: done")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="python -m hypermind.orgs.distributed")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    m = sub.add_parser("master", help="run the coordinator")
+    m.add_argument("--template", default="university")
+    m.add_argument("--namespace", default="dist-run")
+    m.add_argument("--topic", required=True)
+    m.add_argument("--members", type=int, required=True)
+    m.add_argument("--rounds", type=int, default=6)
+    m.add_argument("--expected-workers", type=int, required=True)
+    m.add_argument("--host", default="0.0.0.0")
+    m.add_argument("--port", type=int, default=8765)
+    m.add_argument("--llm", default="openai")
+    m.add_argument("--llm-model", default=None)
+    m.add_argument("--base-url", default=None)
+    m.add_argument("--api-key-env", default="OPENAI_API_KEY")
+    m.add_argument("--relata-url", default="http://localhost:9090")
+    m.add_argument("--relata-token", default=None)
+    m.add_argument("--output", default=None)
+
+    w = sub.add_parser("worker", help="run a worker")
+    w.add_argument("--master-host", required=True)
+    w.add_argument("--port", type=int, default=8765)
+    w.add_argument("--worker-id", default="worker-1")
+    w.add_argument("--capacity", type=int, default=1)
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    runner = _run_master if args.cmd == "master" else _run_worker
+    return asyncio.run(runner(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())