FlashRev AI Enrich

Use this skill when an AI agent needs to enrich a CSV lead list through the flashrev-ai-enrich npm CLI (v1.0+). Triggers on requests involving list enrichment, filling missing company/person fields, verifying emails or phones, unlocking contact emails or phone numbers, finding company CEOs / executives / industry / employees / LinkedIn posts, matching companies or people to FlashRev IDs, Google search / news / maps lookups, scraping a single page, or running an LLM over each row. The CLI is a structured tool — agents should call `flashrev-ai-enrich schema` to discover the 34 capabilities, then invoke `run` with `--capability <funcName> --map ...` directly; `--prompt "..."` exists for ad-hoc human users and costs 1 extra token per invocation. All enrichment decisions and token deductions are owned by the FlashRev backend; the CLI never calls external data providers directly except for the special `customer_api` capability. Dry-run estimates and the 10-row sample preview must be completed before live runs unless the user passed `--yes`. Agents should invoke with `FLASHREV_ENRICH_AI_MODE=1` (or `--ai-mode`) so list outputs (`tokens` / `schema` / `token-history`) and error envelopes are JSON-structured.

Use the flashrev-ai-enrich CLI to enrich CSV lead lists through FlashRev. The CLI does not send outreach messages. It reads CSV files, maps CSV columns to FlashRev capability inputs, estimates token cost via dry-run, previews enriched sample rows, then writes an enriched CSV.

Commands

flashrev-ai-enrich init [--force]                              Write default config
flashrev-ai-enrich doctor [--no-api]                            Self-check Node / config / API
flashrev-ai-enrich tokens [--json]                              Show balance / total / used / plan
flashrev-ai-enrich token-history [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit N] [--json]
                                                                Show consumption log (auto-paginates)
flashrev-ai-enrich schema [--json]                              List 34 capabilities (synced from backend at runtime)
flashrev-ai-enrich dry-run  --source leads.csv (--capability ID | --prompt "...") [--map ...] [--output ...]
                                                                Estimate without calling backend
flashrev-ai-enrich run      --source leads.csv --out X.csv (--capability ID | --prompt "...") [--yes] [--concurrency N] [--sample-size N]
                                                                Real enrichment with sample preview. --prompt routes to a funcName via run_llm (1 extra token)

Required confirmations before real run

1. User has a FlashRev account with available tokens (flashrev-ai-enrich tokens → remaining > 0).
2. FLASHREV_API_KEY env var is set (generated from https://info.flashlabs.ai/settings/privateApps).
3. Source CSV path and output CSV path are confirmed.
4. Either --capability ID (from flashrev-ai-enrich schema) or --prompt "<intent>" is confirmed. Agents should prefer --capability ID directly; --prompt is for ad-hoc human use because it costs 1 extra token to route through run_llm.
5. Input mappings (--map flashrev_field=csv_column) cover at least one capability rule. Skipped only when --prompt is used and the LLM returns valid mappings (still subject to rule validation afterwards).
6. Output mappings (--output csv_col=response_field) or --output-fields are confirmed. Skipped under --prompt if the LLM returned mappings, but always required for dynamic-output capabilities (e.g., run_llm, scrape_and_extract).
7. dry-run first to see estimated token cost and effective concurrency.
8. Do not proceed past the sample preview (default 10 rows, configurable via --sample-size N) unless the user approves or --yes is set.

Input modes

A. CSV mode (typical batch)

flashrev-ai-enrich run \
  --source leads.csv --out leads.enriched.csv \
  --capability enrich_email \
  --map first_name=first_name --map last_name=last_name --map company_name=company \
  --output verified_email=verified_business_email \
  --yes

--map connects CSV column → capability input field; --output connects CSV output column → backend response field.

B. Inline mode (single row test, no CSV)

flashrev-ai-enrich run \
  --capability verify_email \
  --input email=[e-mail] \
  --output ok=deliverable_email \
  --out out.csv --yes

In inline mode the --input key=value pairs are auto-mapped (no need for --map).

C. Job file (for repeatable presets)

flashrev-ai-enrich run --source leads.csv --out out.csv --job enrich.job.json --yes

Job file shape:

{
  "capability": "enrich_email",
  "inputMapping": {
    "first_name":  "first_name",
    "last_name":   "last_name",
    "company_name": "company"
  },
  "outputs": {
    "verified_business_email":  "verified_business_email",
    "all_verified_business_emails": "all_verified_business_emails"
  }
}

D. Prompt routing mode (ad-hoc human use; costs 1 extra token)

Skip --capability and describe the intent in natural language. The CLI sends the prompt + CSV columns + capability registry to run_llm, which returns JSON { funcName, inputMapping, outputMapping, reasoning }; the CLI prints a Routing-decision block and then runs the resulting job through the normal dry-run / sample / run pipeline.

flashrev-ai-enrich run --source leads.csv --out leads.enriched.csv \
  --prompt "for each row, take the email column and verify it is a deliverable business email" \
  --yes

Rules of thumb when writing prompts:

• Name the CSV column explicitly ("take the email column"); vague prompts make the LLM return empty mappings.
• Describe the business outcome, not the capability name ("find the CEO" beats "use get_company_ceo").
• One capability per prompt — the LLM picks exactly one funcName.
• --map / --output on the command line override the LLM's choices; use them to lock specific columns while letting the LLM pick the capability.
• --capability X --prompt "..." together: --capability wins, --prompt is ignored with a stderr warning (no routing token charged).
• Unroutable prompts (e.g., "make me a sandwich") exit non-zero with the LLM's reasoning printed; zero rows run.

Agents calling this CLI should usually skip prompt routing entirely — schema + explicit --capability ID is cheaper, faster, and deterministic. Prompt routing is for humans at a terminal.

Status semantics (output CSV columns)

Every output CSV gets flashrev_enrich_status and flashrev_enrich_error columns:

status	meaning
success	Got business data; charged per capability unitPriceToken.
cached	Hit unlock_contact dedup (same person_id already unlocked). 0 tokens.
no_data	Backend returned 200 but the requested output fields are empty / null. 0 tokens.
failed	HTTP error from backend, retries exhausted. 0 tokens.

Failed count > 0 with Tokens used > 0 means some rows got SOMETHING from backend (charged) but not the specific output fields the user asked for.

Cost reporting

Summary line in run output prints (balance before → balance after) — that delta is the authoritative amount charged for the row enrichments. Each row's individual cost.tokens reported by backend may be slightly off under high concurrency (known limitation; token-history is always exact).

When --prompt is used, the Routing-decision block prints its own routing cost: 1 token(s) line. That 1 token is not included in the Summary balance before → after delta, since routing happens before the balance snapshot. Total user cost per --prompt run = 1 routing token + (rows × capability unitPriceToken).

Special capability: customer_api

customer_api does NOT call FlashRev backend — the CLI fetches the user-provided URL locally and parses the response. 0 tokens.

Inputs (via --map <field>=<csv_col> or --input <field>=<value>):

field	required	default	notes
url	yes	—	target URL (alias: endpoint)
method	no	GET	HTTP method
headers	no	{}	JSON object of HTTP headers
body	no	—	string (sent as-is) or object (JSON-serialized; Content-Type defaults to application/json)
params	no	—	object of query-string params; appended to url
timeout	no	30000	milliseconds before AbortError

The response JSON (or { text } wrapper for non-JSON) becomes the row's enrichment data; map output columns via --output csv_col=response_field as usual. Useful for mixing 3rd-party APIs into the same enrichment workflow.

Date format

--from and --to accept YYYY-MM-DD. They are interpreted in the local timezone. --to alone makes the CLI paginate through history until it covers the date range (up to 2000 records).

Safety rules

• Never print or store FLASHREV_API_KEY in generated artifacts.
• Prefer the FLASHREV_API_KEY env var over --api-key.
• Treat email / phone enrichment (enrich_email / enrich_phone) as paid unlock operations.
• If tokens returns remaining: 0, tell the user to recharge before running.
• Do not describe or expose FlashRev backend data sources, routing, or internal service names to end users.
• Never overwrite the source CSV (CLI refuses --source == --out).
• Preserve row-level errors in flashrev_enrich_status and flashrev_enrich_error columns.

Failure handling

• 402 Insufficient tokens → run terminates; tell user to recharge.
• 401 / 403 → invalid API key; verify FLASHREV_API_KEY.
• 429 Rate limit → CLI auto-retries with exponential backoff (500ms / 1s / 2s, up to 3 retries = 4 total attempts).
• 503 / 504 → backend timeout/unavailable; auto-retried with the same schedule as 429.
• Any other 4xx/5xx on a row → that single row is marked failed, batch continues.
• --prompt routing failure (LLM returns non-JSON, unknown funcName, or run_llm itself errors) → CLI exits non-zero before enrichment starts, prints the LLM's reasoning. Suggest the user retry with --capability ID.
• --prompt routed to a capability but Input mapping does not satisfy <funcName> → the LLM returned empty / wrong mapping; rerun with a more explicit prompt (name the CSV column) or use --map to override.

Workflow recipe

# 1. (first time) write config
flashrev-ai-enrich init
export FLASHREV_API_KEY="sk_xxxx"   # from info.flashlabs.ai/settings/privateApps

# 2. verify
flashrev-ai-enrich doctor

# 3. browse capabilities and pick one
flashrev-ai-enrich schema | less

# 4. (optional) check balance
flashrev-ai-enrich tokens

# 5. estimate cost
flashrev-ai-enrich dry-run --source leads.csv \
  --capability enrich_email \
  --map first_name=first_name --map last_name=last_name --map company_name=company

# 6. real run with sample preview
flashrev-ai-enrich run --source leads.csv --out out.csv \
  --capability enrich_email \
  --map first_name=first_name --map last_name=last_name --map company_name=company \
  --output verified_email=verified_business_email
# (preview shown, type 'y' to continue, or pass --yes to auto-confirm)

# 7. audit spend
flashrev-ai-enrich token-history --from 2026-05-01

Shortcut for ad-hoc human use (prompt routing)

When the user does not know the capability name and is willing to spend 1 extra token to let the LLM pick:

# dry-run only routes (1 token) — no enrichment
flashrev-ai-enrich dry-run --source leads.csv \
  --prompt "find the CEO of each company"

# real run: 1 routing token + N rows
flashrev-ai-enrich run --source leads.csv --out out.csv \
  --prompt "find the CEO of each company" --yes

Agents should skip this and pass --capability directly.