← 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…

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…

  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…

  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…

  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…

  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…

  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…

  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…

  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…