CreatorStack Lead Agent

A reproducible prospect-research pipeline that turns supplied, reviewable public-source signals into CSV and Markdown artifacts while keeping production qualification policy private.

This repository is a sanitized demonstration. Every included person and organization is fictional, no contact details are shipped, and the workflow stops before outreach.

Why it exists

Lead research often mixes discovery, unsupported inference, scoring, and outreach into one opaque automation. CreatorStack Lead Agent separates those concerns:

1. Load documented public-source records or fixtures.
2. Validate every record and its source URL.
3. Pass validated evidence through a replaceable ScoringPolicy boundary.
4. Optionally use a local model to summarize supplied evidence, never to infer qualification or intent.
5. Export evidence and source links for human review.

Quick start

Requires Python 3.11 or newer.

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

lead-agent \
  --fixture examples/fixtures/sample-prospects.json \
  --output outputs/sample

The command creates prospects.csv and prospects.md. Run pytest -q to validate the same deterministic path used in CI.

Optional local-model explanation

With Ollama running locally:

lead-agent \
  --fixture examples/fixtures/sample-prospects.json \
  --output outputs/with-explanations \
  --ollama-model qwen2.5:7b

The model receives only the visible record, review status, and evidence boundary. Its summary is supplementary and does not qualify the prospect.

Private policy boundary

The public PublicDemoPolicy checks only whether labeled evidence exists and routes every complete record to human review. It deliberately contains no production weights, role values, purchase-intent inference, or competitive qualification heuristics. A private implementation can satisfy the ScoringPolicy protocol without changing fixture validation or output contracts.

Ethical-use boundary

• Use public business information, consented data, or fictional fixtures.
• Do not collect sensitive personal traits or bypass access controls.
• Preserve source URLs and review the evidence manually.
• Respect site terms, privacy law, opt-outs, and reasonable request rates.
• Do not automate messages from this project. Outputs are research drafts only.

The sample is not a claim of real prospect quality or campaign performance. It demonstrates contracts, provenance, a private-policy interface, reproducibility, and human approval boundaries.

Architecture

supplied fixture records → validation → private policy boundary → review records
                                                       └─ optional local summary
review records → CSV + Markdown → human review → separate approved workflow

License

MIT. See CONTRIBUTING.md before proposing a new data source.