hunter-engine

The domain-agnostic scout → gate → debate → mission engine shared by every "___ Hunter AI" — extracted from Crypto Hunter AI, the reference implementation. Crypto Hunter AI itself is not migrated to this package — it's live on a daily autonomous cron and stays on its own self-contained code. This package exists so that new Hunter engines (Collectible Hunter AI, Free Money Hunter AI, and beyond) don't each reimplement the ~80% of the pipeline that isn't domain-specific.

What's here

• spec.py — OpportunitySpec, the keystone record. Domain repos subclass it (their own type enum + extra fields) and pass their subclass to DataHub and run_scout via dependency injection.
• gate.py — Gate, the deterministic fail-closed trust boundary. Domain repos pass their own gate-hard checks via extra_checks.
• fetchers.py — RDAP domain-age lookup, generic across any web-sourced domain.
• explain.py — plain-English rejection/verification templates; domain repos extend the base template dict with their own gate-hard check's wording.
• scoring.py — the deterministic cost/time/risk/reward rubric.
• mission.py — profile-aware daily budget allocation (time + money).
• debate.py — Advocate/Skeptic/Strategist stance mechanism; never overrides the gate's verdict, only settle_debate's re-gate on new evidence can.
• store.py — DataHub, the SQLite store. Parameterized by spec_cls so each domain's own OpportunitySpec subclass round-trips correctly.
• roster.py — ROLE_ORDER only; each domain repo supplies its own roster list.
• agents/runtime.py — the Anthropic/OpenAI tool-calling loop (FnTool, run_agent, complete).
• agents/scouts.py — the Beat dataclass and run_scout() mechanism; each domain repo supplies its own BEATS dict and SPEC_SHAPE.

Two governing principles every consumer must preserve

• The arc is the validation, not every step. The gate fires at discrete points only — once on filing, again only via settle_debate if genuinely new evidence appears. Never continuously.
• What's gate-hard vs. debate-argued is decided per domain, by how deterministically checkable a given risk factor actually is. There is no universal split — each consuming engine makes this call for its own domain.

Built by MoreSalamander — "built by the engineer learning how to build it."