account-fleet

account-fleet

Research and score target accounts with traceable source evidence. Quotes are checked against the source at exact character offsets. Scores and interpretations still need human review.

Account Fleet turns a description of the customers you want into a researched, scored shortlist. Every score comes with the exact sentence from the source that justifies it, so you can check the reasoning instead of trusting a summary. It runs on free or local AI models by default, narrows large lists in stages so you only pay attention to the best candidates, and keeps everything in a local file you own.

Canonical CLI is account-fleet. The harness-fleet and career-fleet distributions ship their own entry points from their own checkouts — install one fleet per environment.

Start here (no coding needed)

Copy and paste these one at a time. Nothing here needs an account, an API key, or any money.

1. Install. macOS/Linux: ./install.sh · Windows: powershell -ExecutionPolicy Bypass -File install.ps1 It makes its own private Python environment, sets up a workspace, and connects Claude Desktop or Cursor for you.

   Prefer a terminal one-liner to the installer? This puts the CLI on your PATH without cloning anything:

   uv tool install "git+https://github.com/NatesVibeCode/account-fleet"
   # or, without uv:  python3 -m pip install "git+https://github.com/NatesVibeCode/account-fleet"
   

   Do not use pip install account-fleet from PyPI: that entry is the retired free-fleet 0.2.4 build, which installs a free-fleet command and none of the current features.

2. See it work on ten bundled sample accounts, using a built-in fake model:

   mkdir my-workspace && cd my-workspace
   account-fleet setup
   account-fleet quickstart --demo --run-id demo-01
   

   Results land in runs/demo-01/ as a spreadsheet-friendly CSV plus a self-checking JSON packet.

3. Get free model access — about two minutes, no credit card needed: FREE-ACCESS.md. The demo uses a built-in fake model; real research needs one of these connected.

4. Ask your assistant. Restart Claude Desktop (or Cursor) and describe your ideal customer in plain words; the bundled account-fleet skill turns that into research, scoring, and a ranked shortlist with quotes.

Real research needs a model provider configured (free options included) and your own qualification criteria — see Quickstart below.

Which fleet do I want?

Every distribution shares one engine — typed claims, SQLite checkpoints, and character-exact quote verification — and ships the assistant skills below. Install one per environment.

New here? Install below → run the offline demo → then point the bundled skill at your own list. Skills land in <workspace>/.agents/skills/ — see Assistant skills.

Python 3.10+ is required. This is a command-line tool with an optional AI-assistant integration. It scores source text you supply; the CLI does not browse for companies or fetch job postings automatically. The bundled account-fleet skill guides a connected assistant through that research.

Install and try the offline demo below before running a real list. Real research requires a configured model provider and your own qualification criteria.

---

30-Second Example: Raw Accounts In → Scored, Grounded CSV Out

Suppose you have a list of target companies in accounts.csv:

company,careers_text
stripe.com,"We are hiring a Staff Engineer to lead migration off legacy v1 billing pipeline to Kafka..."
hyper_ai,"Looking for Senior Backend Engineer hitting latency limits at 50k QPS on Postgres cluster..."
pinecone.io,"Hiring Infrastructure Engineer scaling vector search across multi-tenant clusters..."

1. Initialize the account research preset and run

# Initialize the typed account-research preset (evidence checklist, identified_gap; score/fit_tier derived)
account-fleet init research-demo --preset account-research

# Process the accounts through free model routes (zero API spend)
account-fleet run research-demo --input accounts.csv --id-column company --text-column careers_text --run-id campaign-01

2. Export the top 25 ranked accounts

account-fleet export campaign-01 --format csv --sort-by score --desc --top 25 --rank --output ranked_accounts.csv

3. Output (ranked_accounts.csv)

rank,item_id,score,identified_gap,fit_tier,primary_quote_text
1,stripe.com,92,"Legacy billing migration",tier_1,"lead migration off legacy v1 billing pipeline to Kafka"

Illustrative values only; real exports also include source URLs, digests, and quote details. Set your ICP and scoring rubric in the task's TaskSpec — a preset plus a task JSON file, or the studio's scoring panel. An exact source quote proves the text exists, not that a company will buy your product.

---

Why You Can Trust the Output

Every output row is gated through deterministic checks before it is committed to SQLite. If any check fails, the batch rotates to the next route — nothing unverified is exported.

1. Deterministic Quote Verification: Cited quotes are checked against the raw source text at character-level precision and resolved to canonical [start, end] offsets. Sections with evidence terms also expose numbered candidate spans the worker cites by id instead of free-searching; verification recomputes the same span table, so offsets are code-owned. Fabricated or altered quotes fail grounding and trigger immediate route rotation. (This proves all cited quotes are verbatim source substrings; whether a claim is truly entailed by its quote remains model-generated.)
2. Closed JSON Schemas: Outputs adhere strictly to closed JSON Schemas defined in TaskSpec. Models cannot add fields, emit markdown, or drift out of schema.
3. Derived Scores and Tiers, Not Double Judgment: Scoring tasks collect an evidence-bound checklist of true/false answers, and the pipeline computes score (summed points, capped at 100), fit_tier (85+ → tier_1, 70+ → tier_2, 50+ → tier_3, else unfit), and passed. A mismatched derived value fails validation and rotates routes.
4. Weighted, Time-Decayed Evidence: Every true answer needs a supporting quote tagged with supports, and each answer scores its points scaled by source weight (configurable per-domain rules, longest match wins) and recency decay (per-item half-lives — hiring signals stale in weeks, company fundamentals in months). Untagged truth scores zero, so weak evidence can only lower a score, never inflate one.
5. Intelligent Route Scoring: Bayesian-smoothed scoring by verification rate, grounding accuracy, malformed-JSON rate, and latency — not round-robin. Best routes are tried first.
6. Non-Destructive Rate-Limit Handling: On 429 or 5xx, the route is cooled down and the batch is retried immediately on the next lane with 0 attempt burn.
7. Rescore Lineage, Not Overwrites: Fresh evidence arrives as new runs linked by parent_run_id; every verified record lands in score_history, and harness-fleet history ENTITY shows the score trajectory across rounds. Old scores are never rewritten — a stale 40 stays visible next to the new 85 and the evidence that moved it.
8. Zero-Price Circuit Breaker & Spend Ceilings: For zero-price runs, pricing is observed from provider receipts; a non-zero charge trips the breaker and disables the route. For paid runs, --max-request-cost enforces per-request caps. Cost ceilings fail closed on undeclared pricing.

Live proof: harness-fleet status <run_id> --watch streams batch progress and per-route Verified / Rate limits / Latency. Fabricated quotes show up instantly as grounding_failed and the next lane is tried.

---

Quickstart — 60-Second Demo (No API Keys)

Already installed with the one-click installer above? Jump to the account-fleet setup line. The steps below are the from-source path.

git clone https://github.com/NatesVibeCode/account-fleet.git
cd account-fleet
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .

# Run in your own workspace; output files are written in the current directory.
mkdir my-workspace
cd my-workspace
account-fleet setup
account-fleet quickstart --demo --run-id demo-01

# Outputs:
#   runs/demo-01/clean_packet.json   (self-validating packet)
#   runs/demo-01/clean_packet.csv    (flat CSV)

On Windows PowerShell, replace the two virtual-environment commands with py -m venv .venv and .venv\Scripts\Activate.ps1. If activation is restricted, run ..\.venv\Scripts\account-fleet.exe directly from my-workspace.

The demo uses synthetic scores for ten bundled sample accounts and makes no model API calls. It verifies installation and export, not research quality. Demo routes are excluded from real campaigns unless explicitly selected.

Real Workspace

mkdir my-workspace && cd my-workspace
account-fleet setup --workspace-root . --refresh-routes

For a real run, configure OpenCode with your own provider access, set OPENROUTER_API_KEY, or register a running local model, for example account-fleet routes add ollama/your-installed-model --provider ollama --free. Refreshing routes alone does not authenticate you. account-fleet doctor checks configuration; account-fleet test research-demo --input accounts.csv --id-column company --text-column careers_text --provider ollama tests a real batch before a large campaign.

Each named provider uses its own settings: OLLAMA_BASE_URL, LMSTUDIO_BASE_URL, GROQ_API_KEY, and so on. OPENAI_COMPATIBLE_BASE_URL and OPENAI_COMPATIBLE_API_KEY configure only --provider openai_compatible. Environment variables must be available to the process running the CLI or MCP server; .env files are not loaded automatically.

setup installs both the account-fleet research skill and the harness-fleet execution skill in the workspace's .agents/skills directory. Keep the virtual environment in place when using the generated MCP configuration. Install account-fleet and harness-fleet in separate environments: they share the harness_fleet Python package and compatibility commands.

Presets

Create typed tasks instantly with built-in presets:

harness-fleet init score-demo --preset score             # Evidence checklist + pipeline-derived 0-100 score
harness-fleet init filter-demo --preset filter           # Boolean qualification pass/fail gate
harness-fleet init account-demo --preset account-research # Evidence checklist + derived ICP score/tier + gap extraction
harness-fleet init triage-demo --preset triage           # Priority (high/medium/low) + reason
harness-fleet init classify-demo --preset classify       # Categorical labels + summary
harness-fleet init extract-demo --preset extract         # Named entities + summary
harness-fleet init summarize-demo --preset summarize     # Supported fact summaries

Validate and test before launching large runs:

# Validate task spec and input without making any API calls
harness-fleet validate score-demo --input input.jsonl

# Test a single real batch
harness-fleet test score-demo --input input.jsonl

---

Core Capabilities

1. CSV In / Scored, Ranked CSV Out

Directly process tabular data and export sorted, ranked deliverables with exact source quotes:

# Run on CSV specifying ID and text columns (or let harness-fleet auto-detect them)
harness-fleet run score-demo --input accounts.csv --run-id accts-01

# Export ranked deliverable: sorted by score descending, top 25, with 1-indexed rank column
harness-fleet export accts-01 --format csv --sort-by score --desc --top 25 --rank --output ranked_target_accounts.csv

2. The Compounding Filter (Chaining Layers)

Run multi-stage funnel filtering without running monolithic prompts or wasting model compute:

# Layer 1: Filter down to survivors
harness-fleet run l1-task --input 1000_candidates.csv --run-id l1
harness-fleet export l1 --format csv --filter '{"all": [{"field": "passed", "value": true}]}' --output l1_survivors.csv

# Layer 2: Only run on survivor IDs from Layer 1
harness-fleet run l2-task --input tech_docs.csv --only-ids l1_survivors.csv --run-id l2
harness-fleet export l2 --format csv --filter '{"all": [{"field": "passed", "value": true}]}' --output l2_survivors.csv

# Final Layer: Score survivors and rank top candidates
harness-fleet run l3-task --input gap_analysis.csv --only-ids l2_survivors.csv --run-id l3
harness-fleet export l3 --format csv --sort-by score --desc --top 25 --rank --output ranked_deliverable.csv

Filters compose deterministically at export — a ClaimFilter document with all clauses (AND), any branches (OR), and ops ==, !=, >=, <=, >, <, in, not_in:

harness-fleet export l3 --format csv \
  --filter '{"all": [{"field": "score", "op": ">=", "value": 70}, {"field": "passed", "value": true}]}' \
  --output qualified.csv

Discovery pre-filters mechanically too: fetch --title-include engineer --title-exclude manager --exclude-stack mainframe --min-chars 200.

2b. DAG Workflows (multi-stage funnels without CSV round-trips)

Each workflow is a DAG of typed nodes — run (one Engine campaign = one SQLite run), filter (deterministic ID sets from a run snapshot), export (packet/CSV). Edges carry IDs and run references in-process, so funnels keep full drill-through (offsets, digests) at every hop instead of degrading through CSV files:

{
  "name": "funnel",
  "nodes": [
    {"kind": "run", "id": "l1", "task": "filter-task", "input": "candidates.csv",
     "policy": {"allowed_routes": ["demo/fake"], "free_only": true}},
    {"kind": "filter", "id": "l1f", "from_run": "l1",
     "filter": {"all": [{"field": "passed", "value": true}]}, "top": 50},
    {"kind": "run", "id": "l2", "task": "score-task", "input": "docs.csv", "ids_from": ["l1f"]},
    {"kind": "export", "id": "out", "from_run": "l2", "format": "csv",
     "sort": {"field": "score"}, "top": 25, "rank": true}
  ]
}

harness-fleet dag --spec funnel.json --dry-run --json   # validate + print order
harness-fleet dag --spec funnel.json --dag-id campaign-01 --json

Node run IDs are deterministic (<dag-id>-<node-id>), so re-running resumes completed run nodes from SQLite while filter/export re-execute. Lineage (spec digest, run IDs, counts, artifacts) lands in runs/<dag-id>/dag.json. Cycles, unknown references, and wrong-kind edges fail closed at parse time.

3. Live Run Monitoring

Track queue progress, worker concurrency, and route-level metrics in real time:

harness-fleet status <run_id> --watch

Output:

============================================================
Run: triage-01  |  Task: customer-triage  |  Status: RUNNING
Progress: [=========================>              ] 62.5% (650/1040)
============================================================
Batches:
  Pending:    15
  Leased:      4
  Done:       65
  Failed:      0

Route Performance:
  openrouter:qwen/qwen-2.5-72b-instruct:free
    Attempts: 45 | Verified: 44 | Rate limits: 1 | Latency: 1.2s
  openrouter:meta-llama/llama-3.3-70b-instruct:free
    Attempts: 24 | Verified: 23 | Rate limits: 0 | Latency: 1.8s

3. Continuous Route Evaluation

Benchmark available routes against test datasets to determine which models excel at your specific task:

harness-fleet eval customer-triage --input test-samples.csv --id-column id --text-column comment

Output:

========================================================================================
Route Evaluation Benchmark
Task: customer-triage  |  Samples: 20
========================================================================================
Route                                      Success   Grounding   Score    Avg Latency
----------------------------------------------------------------------------------------
openrouter:qwen/qwen-2.5-72b-instruct:free   100.0%     100.0%    0.982          1.15s
openrouter:meta-llama/llama-3.3-70b-free      95.0%      90.0%    0.871          1.82s
opencode:llama3                               80.0%      85.0%    0.742          2.40s

Evaluation benchmarks automatically update route selection priors for subsequent runs.

4. Local Models & Generic OpenAI-Compatible Providers

Run bulk workloads completely locally with Ollama, LM Studio, vLLM, or fast cloud inference providers like Groq and Cerebras:

# Register your local or custom route in the catalog
harness-fleet routes add ollama/llama3.2:latest --provider ollama --free

# Or configure environment variables
export OPENAI_COMPATIBLE_BASE_URL="http://localhost:11434/v1"
export OPENAI_COMPATIBLE_API_KEY="ollama"
export OPENAI_COMPATIBLE_MODEL="llama3.2:latest"

# Run with local provider selection
harness-fleet run my-task --input data.csv --id-column id --text-column text --provider ollama

Endpoints on localhost or 127.0.0.1 are automatically marked free (cost = 0.0). For third-party cloud OpenAI-compatible endpoints, specify costs explicitly (--input-cost / --output-cost) or leave them as unknown-cost to prevent accidental misclassification.

5. Explicit Data & Privacy Policy

Enforce zero data retention (ZDR), prohibit provider data collection, limit request spend, and control upstream routing on a per-run basis:

harness-fleet run my-task \
  --input sensitive-data.jsonl \
  --zdr \
  --no-data-collection \
  --provider openrouter \
  --exclude-provider opencode \
  --openrouter-providers Anthropic,Together \
  --max-request-cost 0.05

You can pass --openrouter-providers as a comma-separated list or as repeatable --openrouter-provider flags.

---

Source Quality

Mechanical discover and fetch runs enforce a default 70% source-capture floor and report backend/query provenance for fetched records. Use --json for the source_quality report; lower the floor with --min-source-coverage 0 only for an intentional sparse-source audit.

SQLite Control Plane

harness-fleet uses SQLite in WAL mode with BEGIN IMMEDIATE atomic leases. If a worker crashes or a laptop closes, the run can be resumed seamlessly:

harness-fleet resume <run_id>

Free routes are used by default. A paid route approved in an earlier session must be requested again with --route <route-id>.

• Resumable: Batches are committed upon verification. Completed work is never repeated.
• Fault-Tolerant: Stale worker leases are automatically recovered after timeout.
• Concurrent: Multiple worker processes can safely lease batches simultaneously without collisions.
• Auditable: Every attempt, model receipt, cost observation, and verification failure is recorded immutably in inference_attempts.

---

Commands

Pass --json to any command for machine-readable JSON output. --free-only is the explicit zero-cost filter (replaces implicit max-cost=0 sentinel). Long documents are warned when truncated (partial slices).

---

Assistant skills (what installs where)

Skills are the playbooks your AI client reads to drive this CLI. account-fleet setup installs every skill this distribution bundles into <workspace>/.agents/skills/:

Each skill is plain markdown — a SKILL.md plus a references/ folder. Read them straight from this repo under skills/, or preview what setup would install:

account-fleet setup --workspace-root "$PWD" --dry-run --json

MCP Server

harness-fleet includes a Model Context Protocol (MCP) server for integration into Cursor, Claude Desktop, Antigravity, and other agent environments:

One-command install (recommended for GTM folks):

harness-fleet mcp install --workspace-root "$PWD"  # auto-detects Claude/Cursor, writes mcpServers entry
# Preview first
harness-fleet mcp install --dry-run --json
harness-fleet doctor --workspace-root "$PWD" --json  # verify
# Restart Claude/Cursor to load

Manual entry:

{
  "mcpServers": {
    "harness-fleet": {
      "command": "harness-fleet",
      "args": ["serve", "--workspace-root", "/absolute/path/to/workspace"]
    }
  }
}

---

Verification & Testing

Run the test suite:

pytest -q

All core components (Bayesian route scoring, SQLite control plane, rate limit cooldowns, OpenAI-compatible provider, CSV IO, real-time status monitoring, and route evals) are covered by automated unit and integration tests.

---

License

MIT. See LICENSE.

Migrating from free-fleet

Version 0.3.0 renames the free-fleet distribution to harness-fleet (the old bulk-lanes name is gone). Back up your database first, then:

free-fleet db backup free-fleet.db.bak  # back up with the OLD CLI first (SQLite backup API, WAL-safe)
mv free-fleet.db harness-fleet.db
account-fleet setup --workspace-root .   # re-installs the skill
account-fleet mcp install                # re-installs client configs

Old packets (free_fleet_v2 / bulk_lanes_v2) no longer read; re-export them from SQLite before upgrading. The FREE_FLEET_DB / BULK_LANES_DB / ACCOUNT_FLEET_DB variables are replaced by the single HARNESS_FLEET_DB. There is no downgrade path — restore your backup to go back.