Signal Hunt

🔍 The federation emitted a signal. Find the cause.
A federation-native investigation game and educational laboratory over real AIMarket Hub telemetry.
Part of the AICOM open agent economy.

_{Observe. Commit. Prove. — live hunt → · landing → · run locally →}

Product guide · Game rules · Reviewer contract · Localization glossary · AIMarket federation

---

What is Signal Hunt?

Signal Hunt turns measured changes in a live capability federation into short, auditable detective rounds — a game and an educational laboratory at once. The player reads real Hub evidence, chooses the most likely cause, states confidence, and receives a reproducible Brier-score verdict. The oracle can randomize presentation, but it cannot choose the truth.

Treat each round as a lab exercise: federation literacy (manifest, sources, prices), evidence cost, calibrated confidence, cryptographic verification and detector thresholds (including peer roster churn and measured latency weather). The hunt loop is how attention stays on the material.

This repository is a complete, separately deployable federation node:

• an ordinary AIMarket Hub named Signal Hunt Hub;
• a local engine only for authoritative game state;
• five free first-party capabilities exposed through that Hub;
• a responsive React/Three.js interface localized in five languages;
• Caddy TLS ingress plus production deployment and registration scripts.

It does not replace or extend ARGUS Agent Arena. Agent Arena is ARGUS progression; Signal Hunt is a live federation investigation product. There is no ArenaHub class.

Gallery

Captures from the running interface connected to a real Hub. They are not rendered concepts — the player record shown is a genuine QA session. No seeded leaderboard, fabricated round, or fallback telemetry ships with the product.

Live federation telemetry	Observe → investigate → commit → verify
Score-derived status	Predicate-derived rewards

Every verdict carries its inputs, confidence, score and provenance.

Documentation in five languages

Language	Product and operations guide	Exact game rules
English	Guide	Rules
Русский	Руководство	Правила
Español	Guía	Reglas
Français	Guide	Règles
中文	指南	规则

Start with the documentation index. The product specification remains the normative acceptance contract.

Runtime truth guarantee

There is no demo data provider and no fallback fixture in the production package. A round is created only from the Signal Hunt Hub's real manifest. If that manifest is unavailable, the API returns 503 federation_unavailable and the UI says telemetry is unavailable. Missing supporting metrics remain null/—.

Full contract: docs/PRODUCT_SPEC.md.

Architecture

flowchart LR
  P["Player"] --> TLS["Caddy · TLS edge"]
  TLS --> GAME["Signal Hunt Game Engine"]
  TLS --> HUB["Signal Hunt Hub · ordinary AIMarket Hub"]
  GAME -->|"manifest · peers · stats"| HUB
  HUB <-->|"signed discovery + routed invoke"| FED["AIMarket federation"]
  HUB -->|"local invoke"| GAME
  GAME --> DB[("rounds · snapshots · verdicts · rewards")]
  GAME -->|"opt-in Ed25519-signed feed"| TWINS["DIOSCURI relay"]
  TWINS -->|"per-sink idempotent delivery"| SOCIAL["Discord · X"]

Only authoritative game state is local. General AI/oracle/analysis capabilities are discovered and invoked through the Hub. For v1, answer-option ordering uses a real, remotely discovered sortes.draw@v1 ECVRF result. Its source Hub, effective route, receipt nonce and result hash are stored with the round.

Local development

Requirements: Python 3.11+, Node 22+, and an already running AIMarket Hub.

Monorepo

git clone --recurse-submodules https://github.com/alexar76/aicom.git
cd aicom/signal-hunt
python -m venv .venv
.venv/bin/pip install -e '.[dev]'

SIGNAL_HUNT_HUB_URL=https://modelmarket.dev \
SIGNAL_HUNT_DATA_DIR=/tmp/signal-hunt-dev \
.venv/bin/python -m signal_hunt.main

Standalone repo (GitHub mirror)

git clone https://github.com/alexar76/signal-hunt.git
cd signal-hunt
python -m venv .venv
.venv/bin/pip install -e '.[dev]'

SIGNAL_HUNT_HUB_URL=https://modelmarket.dev \
SIGNAL_HUNT_DATA_DIR=/tmp/signal-hunt-dev \
.venv/bin/python -m signal_hunt.main

Full Docker (Hub + game + Caddy) expects either:

1. the aicom monorepo checkout (../aimarket-hub present) — ./scripts/deploy.sh builds the Hub from source; or
2. a prebuilt Hub image via SIGNAL_HUNT_HUB_IMAGE=ghcr.io/alexar76/aimarket-hub:… when you only have this satellite repo. Frontend:

cd frontend
npm install
npm run dev
# http://127.0.0.1:5207

Production deployment on a new server

1. Point a DNS A/AAAA record, for example hunt.modelmarket.dev, to the server.

2. Install Docker Engine with the Compose plugin and open TCP 80/443 plus UDP 443.

3. Clone the aicom monorepo on that server (preferred — builds Hub from source), or clone this satellite and set SIGNAL_HUNT_HUB_IMAGE to a prebuilt ordinary AIMarket Hub image.

4. Create configuration:

   cp .env.example .env
   openssl rand -hex 32 # AIMARKET_ADMIN_TOKEN
   openssl rand -hex 32 # POSTGRES_PASSWORD (generate independently)
   chmod 600 .env
   

5. Set the domain, generated admin token and operator-vouched seed public keys. The checked-in example pins the current direct Oracle Family and IoT identities; verify them out of band before deploying. The deploy script refuses placeholder values.

6. Deploy:

   ./scripts/deploy.sh
   

Caddy obtains and renews the public TLS certificate. The Hub and Game Engine have no published raw ports; only Caddy exposes the server.

Make an existing Hub discover Signal Hunt

UPSTREAM_ADMIN_TOKEN='…' \
  ./scripts/register-upstream.sh \
  https://hunt.modelmarket.dev \
  https://modelmarket.dev

The script performs announce → approve → crawl and then fails unless the upstream manifest contains all five tools with source_hub=https://hunt.modelmarket.dev. It never writes the upstream token to disk.

Local game capabilities

Capability	Role	Price
signal.case@v1	Current immutable investigation	$0
signal.evidence@v1	Reveal committed measured evidence	$0
signal.submit@v1	Submit and Brier-score one diagnosis	$0
signal.leaderboard@v1	Verified pseudonymous ranking	$0
signal.heroes@v1	Unsigned Hub invoke listing of currently public milestones (not the DIOSCURI envelope)	$0

DIOSCURI does not consume signal.heroes@v1. It polls the Ed25519-signed HTTP feed GET /api/v1/heroes/feed and verifies the pinned provider public key from GET /provider/public-key.

Status, prizes and DIOSCURI relay

Status and rewards are computed only from persisted verdicts. The six status tiers use cumulative verified score; badges use explicit predicates such as Brier ≤ 0.08, all six evidence blocks opened, a three-answer correct streak, or a ≥950-point round. Rewards are cosmetic records, not currency or token claims.

Players are private by default. An explicit profile opt-in allows a future promotion or rare badge to enter GET /api/v1/heroes/feed. That feed is Ed25519-signed with the same persistent provider identity used by the Hub capabilities. DIOSCURI pins that key, pulls the feed, suppresses historical backlog and records delivery separately for Discord and X. Social API credentials never enter Signal Hunt. See docs/DIOSCURI_RELAY.md.

Operations

Verify a deployment:

./scripts/verify.sh https://hunt.modelmarket.dev

Logs:

docker compose --env-file .env -f docker-compose.yml logs -f hub game caddy

Persistent volumes:

• signal_hunt_postgres_data: Hub catalogue, peer approvals and federation state;
• signal_hunt_hub_data: persistent Hub signing identity;
• signal_hunt_game_data: provider/session secrets, observations, rounds and verdicts;
• signal_hunt_caddy_data: TLS state.

Testing

pip install -e '.[dev]'
pytest -q

Forty unit/API tests cover detector math (including peer churn and latency weather), federation client truthfulness and peer RTT probes, the round → evidence → submit path, and hero-feed privacy (no private events, no opt-in backfill, opt-out revokes feed visibility). Synthetic fixtures stay inside tests only.

License

MIT