SignalSniper

SignalSniper is a staged-spend lead qualification engine that buys just enough external signal to decide whether a target account is worth pursuing.

Why It Matters

Most outbound systems either spray generic enrichment everywhere or force a human to manually inspect accounts one at a time. SignalSniper takes a different approach: it starts cheap, escalates only when the evidence justifies the spend, and leaves behind a replayable artifact trail that explains what happened.

That makes it useful as a demo repo because it shows three things clearly:

• how a budget-aware agent can gate spend
• how confidence progresses across sequential checks
• how to preserve a defensible audit trail instead of emitting one opaque score

Staged Spend Model

Each account moves through a small decision pipeline:

1. exa_sanity confirms the company has a real web footprint.
2. exa_hiring and exa_funding run in parallel to test for strong market activity.
3. apollo_enrich pulls structured company facts and applies the ICP gate.
4. exa_pricing and exa_tech are only used as tie-breakers when confidence is in the middle band.
5. apollo_revops runs only for already-qualified accounts to find a plausible buyer or operator.

Every action has a known cost and a known confidence lift. If a paid step fails, the run records the failure and continues where it can without silently corrupting the budget trail.

Demo Mode vs Live Mode

--dry-run is the safe demo path. It never spends real money and uses deterministic dry-run profiles so the same input plus the same --seed produces the same artifact set.

Live mode calls AgentCash-backed providers. It includes retries, explicit error events, budget refunds on failed calls, and per-run artifacts so failures are inspectable after the fact.

Architecture

The repo is intentionally small, but the responsibilities are now separated:

• signalsniper/agent.py: top-level pipeline orchestration and run summaries
• signalsniper/executor.py: staged action machine and confidence progression
• signalsniper/providers/: external request body construction and AgentCash execution
• signalsniper/core/: deterministic hashing, artifact paths, reasoning grounding, canonicalization
• signalsniper/demo/: dry-run fixtures and replay payload generation
• artifacts/runs/<run_id>/: generated leads, ledger, replay payload, summary, and event stream

Setup

Requirements:

• Python 3.11+
• uv recommended
• Node.js only if you want to exercise live AgentCash calls

Install dependencies:

uv sync

Copy the environment template if you want live reasoning or live paid-provider execution:

cp .env.example .env

Run A Dry Demo

uv run signalsniper run --dry-run --domain stripe.com --budget 0.15 --run-id demo-stripe --seed 7

Or seed a fuller funnel:

uv run signalsniper run --dry-run --icp icp-5-companies.json --max 10 --run-id demo-batch --seed 7

Outputs are written under artifacts/runs/<run_id>/ by default. Old runs are preserved unless you delete them manually.

Replay Artifacts

Each run writes:

• leads.json
• ledger.json
• events.jsonl
• summary.json
• replay.json

The committed root replay.html is a lightweight viewer for the generated replay.json. Open it in a browser and either:

• let it load artifacts/latest/replay.json, or
• paste a custom path with ?src=artifacts/runs/<run_id>/replay.json

Current Limitations

• Live provider execution still depends on external services and network availability.
• Candidate deduping is practical rather than exhaustive; it collapses obvious sibling variants, not full corporate identity graphs.
• The demo replay is intentionally simple HTML, not a full web app.
• Confidence lifts are still policy-driven constants; they are transparent and testable, but not learned from historical outcomes.