← All runbooks
gooseworks-ai / capabilities-tam-builder

TAM Builder

Build and maintain a scored Total Addressable Market using Apollo Company Search. The runbook supports build, refresh, and status modes, scores ICP fit from a JSON configuration, assigns Tier 1/2/3 labels, and builds a persona watchlist for Tier 1-2 accounts using Apollo People S

agent codexmodel gpt-5.5snapshot python312-uveval programmatic9 stepsv1.0.0

Deploy TAM Builder to your jetty.io

One-click installs this runbook into a collection on your Jetty account. You can run it from the Spot dashboard, schedule it, or pipe inputs in via the API.

Deploy on jetty.io →View source
The shape of the run

9 steps · start to finish.

  1. 1
    Step 1

    Environment Setup

    ▶
    1. Create results_dir and initialize summary.md and validation_report.json placeholders.
    2. Verify APOLLO_API_KEY exists in the environment.
    3. Install or verify Python dependencies: requests and any local CSV/JSON helpers used by the implementation.
    4. Load config_path as JSON and validate required top-level keys: client_name, tam_config_name, company_filters, scoring, watchlist, mode, and max_pages.
    5. Fail fast if the selected operation is not build, refresh, or status.
  2. 2
    Step 2

    Validate TAM Configuration

    ▶

    Check that scoring weights cover `employee_count_fit`, `industry_fit`, `funding_stage_fit`, `geo_fit`, and `keyword_match`, and that they sum to a sensible total before normalization. Validate that tier thresholds are ordered so Tier 1 is stricter than Tier 2. Enforce mode caps:

  3. 3
    Step 3

    Status Mode

    ▶

    If `operation=status`, do not call Apollo or mutate any stored data. Read existing TAM output files or local state, summarize active companies, deprecated companies, tier distribution, watchlist size, and most recent refresh timestamp, then write `/app/results/tam-status.json`, `

  4. 4
    Step 4

    Preview and Sample

    ▶

    Run a preview request against Apollo Company Search using the configured filters, `per_page=100`, and `page=1`. Score the sample companies in memory only, then present total count, estimated page count, mode cap, estimated People Search calls, tier distribution, and representativ

  5. 5
    Step 5

    Approval Gate

    ▶

    Before full build or refresh, require explicit user approval after the sample review. The approval must be captured as a clear yes/approve/proceed response in the orchestration transcript or an equivalent machine-readable approval field. If approval is missing, stop after writing

  6. 6
    Step 6

    Build Mode Pipeline

    ▶

    After approval, page through Apollo Company Search within the selected cap. For each company returned in the `accounts` array, normalize company fields, compute ICP score using the pure scoring function, assign Tier 1 for scores at or above `tier_1_min_score`, Tier 2 for scores a

  7. 7
    Step 7

    Refresh Mode Pipeline

    ▶

    For refresh mode, page through the current Apollo search, upsert returned companies, re-score every active match, and detect tier changes. Mark a first missing company with `metadata.refresh_miss_count = 1`, deprecate companies missing from two consecutive refreshes, immediately

  8. 8
    Step 8

    Persona Watchlist Sync

    ▶

    When `watchlist.enabled` is true, call Apollo People Search for Tier 1-2 companies only, respecting `personas_per_company`, `person_filters`, and `tiers_to_watch`. Pull personas for new Tier 1-2 companies and companies promoted from Tier 3 to Tier 2, disqualify personas at deprec

  9. 9
    Step 9

    Iterate on Errors (max 3 rounds)

    ▶

    If an Apollo request, config validation, scoring assertion, CSV write, or watchlist sync fails, inspect the failed validation stage, apply the smallest targeted fix, and retry that stage. Run at most 3 rounds before stopping with `overall_passed=false` in `/app/results/validation