aimarket-signal-hunt

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.

🌐 English · Русский · Español · Français · 中文 · Glossary

_{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.

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

Documentation in five languages

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/—.

The game reaches the Hub only at SIGNAL_HUNT_HUB_URL (compose default: http://hub:9083). That hostname is the Compose service alias on signal_hunt_internal. Recreating the hub with bare docker run / security rename-swaps that drop com.docker.compose.service=hub leaves the public nginx path (127.0.0.1:9084) healthy while every live round fails. Always recreate via ./scripts/deploy.sh or docker compose --env-file .env up -d hub. Deploy and ./scripts/verify.sh assert game→hub DNS, /ready, and a real /api/v1/rounds/live.

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

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

Which compose files a deployment is made of belongs in .env as COMPOSE_FILE, not in a command someone has to remember — see .env.example. Behind a host nginx the set must include docker-compose.nginx-edge.yml, which is the only place the hub's 127.0.0.1:9084:9083 publish is declared; recreate the hub without it and the container runs healthy on its internal network while every /ai-market path answers 502.

Never replace signal-hunt-hub-1 outside Compose. A container that keeps the name but loses the hub DNS alias makes /health report status=degraded / hub_manifest.reachable=false, /ready return 503, and live rounds fail — even when curl https://hunt.modelmarket.dev/ai-market/v2/manifest still works via nginx.

Logs:

docker compose 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