| name | search-company |
| description | Resolve company names, company descriptions, investor/funding filters, or vertical queries into canonical TurboPuffer company IDs for downstream people search. |
Search Company
Use this when the user asks for company search directly, or when they want the
company set behind a people search inspected first.
Examples:
/search-company database companies
/search-company series b fintech startups in california
/search-company companies backed by sequoia
Workflow
Fresh company resolution only: do not scan, discover, reuse, or resume prior
company search artifacts, state files, CSVs, JSONL, or manifests. Resolve the
company set from the user's current request every time.
- Decompose the request into the
role-search-filters company fields only:
company_names, company_semantic_queries, entity_types, sector_types,
funding/headcount filters, company geography, investor_names, and
resolved investors. Preserve set_id when the user provides one.
- Resolve set scoping before company resolution. If the user did not provide a
set_id, run resolve_set_operators without --set-id so it inherits
POWERPACKS_DEFAULT_SET_ID / POWERSET_DEFAULT_SET_ID, or falls back to the
logged-in operator's active personal set. Copy the returned operator_ids
into the company resolver payload. Do not pass the raw set UUID as
allowed_operator_ids.
- If
investor_names are present, run resolve_investors first and record or
copy the returned investor_urns into investors.
- Run
resolve_companies.
- Present the returned company count, sample companies, set scope, and the company IDs
artifact/state path when available.
- If the user wants people at those companies, pass
company_ids and
operator_ids into
search; for large company sets, use apply_prefilters so people
search batches company IDs instead of sending one giant company_id In [...].
Query Guidance
Use company_semantic_queries for vertical/domain intent, not just
sector_types. Coarse sectors are useful, but the resolver needs an explicit
sector strategy:
- Use
company_sector_strategy: "staged" by default for ambiguous domain
searches. This starts with sector-intersected semantic search and broadens if
the hard frontier is too small.
- Use
company_sector_strategy: "soft_union" when recall matters more than
precision or labels are known to be incomplete. This matches semantic results
OR sector-filter matches.
- Use
company_sector_strategy: "hard_filter" when the user explicitly wants
sector labels as a strict constraint.
- Use
company_sector_strategy: "semantic_only" when sector labels are too
noisy for the requested company domain.
Good:
{
"company_semantic_queries": [
"Companies building database systems, hosted databases, data storage engines, database infrastructure, SQL or NoSQL databases, or developer platforms for managing application data."
],
"sector_types": ["data"],
"company_sector_strategy": "staged",
"company_sector_min_results": 500
}
Bad:
{ "sector_types": ["data"] }
Commands
uv run --project . python packs/search/primitives/resolve_set_operators/resolve_set_operators.py \
--payload-json '<json>' \
--env-file .env
uv run --project . python packs/search/primitives/resolve_investors/resolve_investors.py \
--payload-json '<json>' \
--env-file .env
uv run --project . python packs/search/primitives/turbopuffer/turbopuffer_resolve_companies.py \
--payload-json '<json>' \
--env-file .env