discolike-python

discolike-python is the official Python SDK and CLI for the DiscoLike API, a business web search engine that indexes over 80 million business websites worldwide across 50 languages. The repository ships two packages: discolike (the SDK library) and discolike-cli (the terminal command-line interface, which depends on the SDK). Both require Python 3.10+. The SDK provides a typed client (Discolike) and an async counterpart (AsyncDiscolike) for interacting with DiscoLike's API. Core capabilities include discovering lookalike companies by ICP text, phrases, tech stack, geography, and 40+ other filters; counting segments before pulling them; matching messy company names (with optional phone, city, state) to domains in single or bulk CSV mode; enriching CSV domain lists with DiscoLike datasets; auto-segmenting domain lists; validating domain lists against ICP definitions; retrieving full company profiles with firmographics, scores, growth data, redirects, vendors, and subsidiaries; searching, looking up, matching, and discovering contacts at target companies; and running DiscoGen research over sets of domains with web search enabled. Authentication supports three methods: signup (opens an account from an email and name without a browser, with the owner confirming by email), OAuth login (browser-based PKCE authorization code flow with loopback redirect, or headless mode printing the URL), and API key (via environment variable DISCOLIKE_API_KEY, CLI config file, or explicit parameter). OAuth credentials refresh proactively within 60 seconds of expiry and once more after a 401. The client also supports bringing your own httpx2.Client or httpx2.AsyncClient. All request models are generated from the platform's OpenAPI spec and validated locally with Pydantic before any request is sent, so bad enum values or out-of-range numbers never cost a round trip. All responses are typed Pydantic models. Errors inherit from DiscolikeError with specific subclasses for authentication, plan access, not found, server, rate limit, validation, and API connection failures. Transient failures are retried automatically (3 attempts by default). Long-running bulk operations (match.bulk, segment, validate_icp, contacts.bulk_match) return a Job handle instead of blocking. Job.wait() blocks until completion, Job.status() polls without blocking, and Job.cancel() aborts. On DiscoGen-family jobs, the returned JobStatus carries warnings, estimated_cost, and cost_metadata including per-model usage and search provider entries. JobTimeoutError is a client-side wait limit only — the task keeps running server-side, so wait() can be called again to resume. The CLI mirrors the SDK's capabilities with commands for discover, count, match, extract, validate-icp, append, segment, signup, plus command groups for auth, company, contacts, discogen, queries, account, search-providers, and llm-providers. Results print as JSON to stdout by default, with --format table for human-readable output when stdout is a TTY. Async endpoints accept --wait to block until the job finishes, or return a task_id for polling. Exit codes are standardized: 0 success, 1 server error, 2 validation error, 3 authentication/plan error, 4 rate limited, 5 network error, 6 not found. The repository is structured as a uv workspace with two members: packages/discolike (the SDK) and packages/discolike-cli (the CLI). Development uses pytest for testing, ruff for linting, and a code generation script (scripts/gen_requests.py) to regenerate request models from the OpenAPI spec. The examples/ folder contains runnable scripts for common workflows including matching CRM contact exports to DiscoLike persona IDs with checkpointing and resume, bulk-finding work emails from a CSV, and discovering companies by ICP then enriching them with DiscoGen. The project is licensed under MIT.