discolike-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: discolike-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Official CLI for the DiscoLike API
 Project-URL: Homepage, https://www.discolike.com
 Project-URL: Documentation, https://docs.discolike.com
@@ -17,17 +17,16 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: discolike==0.4.0
+Requires-Python: >=3.11
+Requires-Dist: discolike==0.5.0
 Requires-Dist: rich>=13.0
-Requires-Dist: typer>=0.12
+Requires-Dist: typer<0.28,>=0.26.1
 Description-Content-Type: text/markdown
 
 # discolike-cli
@@ -46,7 +45,7 @@ Or run it without installing:
 uvx --from discolike-cli discolike --help
 ```
 
-Requires Python 3.10+. Installing this package gives you the `discolike` command.
+Requires Python 3.11+. Installing this package gives you the `discolike` command.
 
 ## Authentication
 
@@ -67,7 +66,7 @@ discolike company data stripe.com
 discolike extract https://stripe.com/enterprise
 ```
 
-Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment` — plus `auth`, `bulk`, `company`, `contacts`, `discogen`, `queries`, `account`, `search-providers`, and `llm-providers` command groups.
+Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment` — plus `auth`, `bulk`, `company`, `contacts`, `discogen`, `prospecting`, `queries`, `account`, `search-providers`, and `llm-providers` command groups.
 
 ### Volume pulls
 
@@ -81,6 +80,26 @@ discolike bulk contacts  --domains-file companies.csv --per-company 10 --summary
 
 `companies` saves each page as an exclusion list (`<run-name>-round-N`) and excludes it from the next page; rerunning with the same `--out` resumes from the CSV. `contacts` slices the domain list at `10000 / per-company` domains per call and records finished slices in `<out>.checkpoint`. Both keep one call in flight under `--rate-limit` (default 10/min, the Pro rate on `/discover` and `/contacts`), retry on 429/5xx, and print a JSON summary at the end. Filters come from `--params-file`, `--param` and the common flags; the paging fields are managed for you.
 
+### Managed prospecting
+
+```bash
+discolike prospecting start --brief "Find 100 US logistics companies and 3 operations directors each" --idempotency-key logistics-1
+discolike prospecting start --brief "Find lookalikes of our customers and their CTOs" --customers-file customers.csv --idempotency-key seeded-1
+discolike prospecting wait RUN_ID
+# Review the proposed plan, then approve the exact version you saw:
+discolike prospecting approve RUN_ID --plan-version 1
+discolike prospecting list --limit 20
+discolike prospecting message RUN_ID --text "Make it 250 companies" --idempotency-key logistics-edit-1
+discolike prospecting status RUN_ID --events-after 12 --messages-after 8 --limit 100
+discolike prospecting cancel RUN_ID
+```
+
+`wait` returns on `proposed`, `needs_input`, `completed`, `failed`, or `cancelled`. A timeout stops polling only. Inspect status and stop reason; completion does not guarantee full coverage. Message replies arrive through `status --messages-after`; follow `next_message_seq` and `reply_pending`. A "segment these" request keeps `reply_pending` true until the segments message is posted, which can take more than an hour. If grouping stops without an outcome, the flag clears on its own after about 90 minutes.
+
+`start` and `approve` default to pausing at checkpoints, like the web chat: a pilot check on large lists (`pilot`), a search drifting off target (`tail_quality`), candidates running out short of the target (`short`), the target being met (`target_reached`), another round of companies when the ones checked yield too few contacts (`top_up`), and, on wave runs, the researched contacts found before their emails are looked up (`contacts_review`, asked with `--auto` too; contacts already in DiscoLike's database get their lookups during research, which approving the plan starts; picking "Find emails" by number sends the question's `seq`, which the API needs to accept it). Pass `--auto` to never pause (except at a `top_up` round that would pass a spending limit); a poor pilot is then sharpened once and the run continues with a notice, stopping with `pilot_failed` only if the re-pilot fit is still under 20%. If sharpening itself fails, the run continues on the original criteria. On a terminal, `wait` shows the question, any sample companies and numbered replies at a checkpoint, sends your pick or your own text, and keeps waiting. Without a terminal, or with `--no-input`, it prints the run on stdout, a `needs_input` envelope (`message`, `stop_reason`, `suggested_replies`, `sample`) on stderr, and exits 7; answer with `prospecting message --text "<reply>"` (add `--question-seq` with the question's `seq` to answer only that question) and run `wait` again.
+
+Omit `--target-companies` and `--contacts-per-company` to infer counts from the brief (fallback 1,000 and 3; up to 10 contacts per company). Explicit values override the text. `--deliverable accounts` returns the checked companies only, with no people; `--goal companies` takes `--target-companies` matching companies and works only those instead of adding rounds until the contact target is met. Both default to `leads`. `--max-candidates` and `--max-actions` are automatic when omitted or `0`; their maxima are 100,000 and 10,000. Targets allow up to 10,000 companies, status pages up to 500 rows, and lists up to 50 runs. Work caps do not cap provider charges.
+
 ### Conventions
 
 - Results print as JSON to stdout; errors print as JSON (`error`, `message`, `status_code`) to stderr.
@@ -99,6 +118,7 @@ discolike bulk contacts  --domains-file companies.csv --per-company 10 --summary
 | 4 | Rate limited |
 | 5 | Network error |
 | 6 | Not found |
+| 7 | Needs input: `prospecting wait` reached a checkpoint with no terminal to ask (or `--no-input`) |
 
 ## Links
 

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/README.md

@@ -14,7 +14,7 @@ Or run it without installing:
 uvx --from discolike-cli discolike --help
 ```
 
-Requires Python 3.10+. Installing this package gives you the `discolike` command.
+Requires Python 3.11+. Installing this package gives you the `discolike` command.
 
 ## Authentication
 
@@ -35,7 +35,7 @@ discolike company data stripe.com
 discolike extract https://stripe.com/enterprise
 ```
 
-Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment` — plus `auth`, `bulk`, `company`, `contacts`, `discogen`, `queries`, `account`, `search-providers`, and `llm-providers` command groups.
+Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment` — plus `auth`, `bulk`, `company`, `contacts`, `discogen`, `prospecting`, `queries`, `account`, `search-providers`, and `llm-providers` command groups.
 
 ### Volume pulls
 
@@ -49,6 +49,26 @@ discolike bulk contacts  --domains-file companies.csv --per-company 10 --summary
 
 `companies` saves each page as an exclusion list (`<run-name>-round-N`) and excludes it from the next page; rerunning with the same `--out` resumes from the CSV. `contacts` slices the domain list at `10000 / per-company` domains per call and records finished slices in `<out>.checkpoint`. Both keep one call in flight under `--rate-limit` (default 10/min, the Pro rate on `/discover` and `/contacts`), retry on 429/5xx, and print a JSON summary at the end. Filters come from `--params-file`, `--param` and the common flags; the paging fields are managed for you.
 
+### Managed prospecting
+
+```bash
+discolike prospecting start --brief "Find 100 US logistics companies and 3 operations directors each" --idempotency-key logistics-1
+discolike prospecting start --brief "Find lookalikes of our customers and their CTOs" --customers-file customers.csv --idempotency-key seeded-1
+discolike prospecting wait RUN_ID
+# Review the proposed plan, then approve the exact version you saw:
+discolike prospecting approve RUN_ID --plan-version 1
+discolike prospecting list --limit 20
+discolike prospecting message RUN_ID --text "Make it 250 companies" --idempotency-key logistics-edit-1
+discolike prospecting status RUN_ID --events-after 12 --messages-after 8 --limit 100
+discolike prospecting cancel RUN_ID
+```
+
+`wait` returns on `proposed`, `needs_input`, `completed`, `failed`, or `cancelled`. A timeout stops polling only. Inspect status and stop reason; completion does not guarantee full coverage. Message replies arrive through `status --messages-after`; follow `next_message_seq` and `reply_pending`. A "segment these" request keeps `reply_pending` true until the segments message is posted, which can take more than an hour. If grouping stops without an outcome, the flag clears on its own after about 90 minutes.
+
+`start` and `approve` default to pausing at checkpoints, like the web chat: a pilot check on large lists (`pilot`), a search drifting off target (`tail_quality`), candidates running out short of the target (`short`), the target being met (`target_reached`), another round of companies when the ones checked yield too few contacts (`top_up`), and, on wave runs, the researched contacts found before their emails are looked up (`contacts_review`, asked with `--auto` too; contacts already in DiscoLike's database get their lookups during research, which approving the plan starts; picking "Find emails" by number sends the question's `seq`, which the API needs to accept it). Pass `--auto` to never pause (except at a `top_up` round that would pass a spending limit); a poor pilot is then sharpened once and the run continues with a notice, stopping with `pilot_failed` only if the re-pilot fit is still under 20%. If sharpening itself fails, the run continues on the original criteria. On a terminal, `wait` shows the question, any sample companies and numbered replies at a checkpoint, sends your pick or your own text, and keeps waiting. Without a terminal, or with `--no-input`, it prints the run on stdout, a `needs_input` envelope (`message`, `stop_reason`, `suggested_replies`, `sample`) on stderr, and exits 7; answer with `prospecting message --text "<reply>"` (add `--question-seq` with the question's `seq` to answer only that question) and run `wait` again.
+
+Omit `--target-companies` and `--contacts-per-company` to infer counts from the brief (fallback 1,000 and 3; up to 10 contacts per company). Explicit values override the text. `--deliverable accounts` returns the checked companies only, with no people; `--goal companies` takes `--target-companies` matching companies and works only those instead of adding rounds until the contact target is met. Both default to `leads`. `--max-candidates` and `--max-actions` are automatic when omitted or `0`; their maxima are 100,000 and 10,000. Targets allow up to 10,000 companies, status pages up to 500 rows, and lists up to 50 runs. Work caps do not cap provider charges.
+
 ### Conventions
 
 - Results print as JSON to stdout; errors print as JSON (`error`, `message`, `status_code`) to stderr.
@@ -67,6 +87,7 @@ discolike bulk contacts  --domains-file companies.csv --per-company 10 --summary
 | 4 | Rate limited |
 | 5 | Network error |
 | 6 | Not found |
+| 7 | Needs input: `prospecting wait` reached a checkpoint with no terminal to ask (or `--no-input`) |
 
 ## Links
 

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/pyproject.toml

@@ -4,16 +4,16 @@ build-backend = "hatchling.build"
 
 [project]
 name = "discolike-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Official CLI for the DiscoLike API"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 authors = [{ name = "DiscoLike", email = "support@discolike.com" }]
 dependencies = [
-  "discolike==0.4.0",
-  "typer>=0.12",
+  "discolike==0.5.0",
+  "typer>=0.26.1,<0.28",
   "rich>=13.0",
 ]
 keywords = ["discolike", "cli", "business-data", "enrichment"]
@@ -21,7 +21,6 @@ classifiers = [
   "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/src/discolike_cli/_help.py

@@ -74,6 +74,9 @@ Exit codes:
   4  rate_limited       HTTP 429; wait "retry_after" seconds, then retry
   5  network_error      could not reach the API
   6  not_found          HTTP 404
+  7  needs_input        `prospecting wait` stopped at a checkpoint with no terminal to ask
+                        (or --no-input): the run is on stdout, the question and
+                        "suggested_replies" in the stderr envelope
 
 Environment:
   {ENV_API_KEY}   API key; overrides the config file written by `discolike auth login`.

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/src/discolike_cli/_output.py

@@ -43,6 +43,7 @@ EXIT_CODES: dict[type, int] = {
     NotFoundError: 6,
 }
 DEFAULT_EXIT_CODE = 1
+NEEDS_INPUT_EXIT_CODE = 7
 
 # Stable, snake_case error codes for agents and scripts to branch on. The class
 # name in `error` is kept for backwards compatibility; `code` is the contract.
@@ -82,7 +83,7 @@ class SupportsWait(Protocol):
     task_id: str
     task_family: str
 
-    def wait(self, *, timeout: float, on_poll: Callable[[_JobStatusLike], None] | None = None) -> _JobStatusLike: ...
+    def wait(self, *, max_wait: float, on_poll: Callable[[_JobStatusLike], None] | None = None) -> _JobStatusLike: ...
 
 
 def _normalize(data: Any) -> Any:  # noqa: ANN401 -- accepts arbitrary JSON-serializable CLI output data
@@ -203,5 +204,5 @@ def run_job(job: SupportsWait, *, wait: bool, timeout: float, fmt: str | None =
     def _on_poll(status: _JobStatusLike) -> None:
         sys.stderr.write(f"progress: {status.progress}%\n")
 
-    final = job.wait(timeout=timeout, on_poll=_on_poll)
+    final = job.wait(max_wait=timeout, on_poll=_on_poll)
     emit(final.results if final.results is not None else final.to_dict(), fmt=fmt)

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/src/discolike_cli/auth.py

@@ -4,8 +4,8 @@ import json
 import secrets
 import sys
 import webbrowser
+from datetime import UTC
 from datetime import datetime
-from datetime import timezone
 from typing import Any
 from typing import NoReturn
 from urllib.parse import urlparse
@@ -88,7 +88,7 @@ def _offer_signup(ctx: typer.Context) -> None:
 
 
 def _iso(epoch_seconds: float) -> str:
-    return datetime.fromtimestamp(epoch_seconds, tz=timezone.utc).isoformat()
+    return datetime.fromtimestamp(epoch_seconds, tz=UTC).isoformat()
 
 
 def _global_key_source(ctx: typer.Context) -> str:

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/src/discolike_cli/bulk.py

@@ -382,8 +382,8 @@ def _persona_ids_in(path: pathlib.Path) -> set[str]:
 
 
 ICP_PROMPT_HELP = "Natural-language ICP prompt used to derive contact filters."
-SUMMARY_HELP = "Filter by profile summary text (semantic search); ranks who comes back per company."
-NEGATE_SUMMARY_HELP = "Exclude contacts matching this summary description."
+SUMMARY_HELP = "Match profile summary text: every word of any one term, in any order. Quote a multi-word term to keep it together, prefix + to require it. Ranks who comes back per company."
+NEGATE_SUMMARY_HELP = "Exclude contacts whose profile summary contains every word of any one term, in any order."
 HAS_EMAIL_HELP = "Only contacts with an email address (on by default)."
 
 

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/src/discolike_cli/contacts.py

@@ -30,8 +30,8 @@ WAIT_HELP = "Block until the job finishes, streaming progress to stderr."
 TIMEOUT_HELP = "Max seconds to wait with --wait."
 PARAM_HELP = "Extra key=value query parameter forwarded to the SDK (repeatable)."
 JOBSTART_DATE_HELP = "Job start date filter: min date or 'min,max' range, e.g. 2025-01-01 or 2025-01-01,2025-06-30."
-SUMMARY_HELP = "Filter by profile summary text (semantic search)."
-NEGATE_SUMMARY_HELP = "Exclude contacts matching this summary description."
+SUMMARY_HELP = "Match profile summary text: every word of any one term, in any order. Quote a multi-word term to keep it together, prefix + to require it."
+NEGATE_SUMMARY_HELP = "Exclude contacts whose profile summary contains every word of any one term, in any order."
 NAME_HELP = "Filter by contact name (partial match supported)."
 SKILLS_HELP = "Filter by skill (repeatable)."
 FILTER_STATE_HELP = "Filter by company state/region (repeatable)."

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/src/discolike_cli/discogen.py

@@ -44,7 +44,7 @@ TASK_ID_HELP = "Task ID returned when the job was started."
 app = typer.Typer(help="Run DiscoGen research jobs and check status of or cancel any async task (see --family)")
 
 
-class TaskFamily(str, enum.Enum):
+class TaskFamily(enum.StrEnum):
     discogen = "discogen"
     bulkmatch = "bulkmatch"
     contactmatch = "contactmatch"

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/src/discolike_cli/email.py

@@ -71,7 +71,7 @@ def _fetch_batch_snapshot(batch: EmailBatch) -> EmailBatchResults:
     """Fetch the batch results once, whether or not the batch has finished."""
     snapshot: dict[str, EmailBatchResults] = {}
     try:
-        return batch.results(timeout=0, on_poll=lambda results: snapshot.update(latest=results))
+        return batch.results(max_wait=0, on_poll=lambda results: snapshot.update(latest=results))
     except JobTimeoutError:
         return snapshot["latest"]
 
@@ -101,7 +101,7 @@ def find_command(
     if not wait:
         emit({"job_id": job.job_id, "hint": f"poll with: discolike email job {job.job_id}"})
         return
-    emit(job.wait(timeout=timeout, on_poll=_job_status_to_stderr), fmt=fmt)
+    emit(job.wait(max_wait=timeout, on_poll=_job_status_to_stderr), fmt=fmt)
 
 
 @app.command("find-batch")
@@ -136,7 +136,7 @@ def find_batch_command(
     if not wait:
         emit({"batch_id": batch.batch_id, "hint": f"fetch with: discolike email results {batch.batch_id}"})
         return
-    emit(batch.results(timeout=timeout, on_poll=_batch_progress_to_stderr), fmt=fmt)
+    emit(batch.results(max_wait=timeout, on_poll=_batch_progress_to_stderr), fmt=fmt)
 
 
 @app.command("results")
@@ -156,7 +156,7 @@ def results_command(
         raise typer.BadParameter(f"--kind must be one of: {', '.join(EMAIL_KINDS)}")
     batch = get_client(ctx).email.batch(batch_id, kind=kind)  # type: ignore[arg-type]
     if wait:
-        emit(batch.results(timeout=timeout, on_poll=_batch_progress_to_stderr), fmt=fmt)
+        emit(batch.results(max_wait=timeout, on_poll=_batch_progress_to_stderr), fmt=fmt)
         return
     emit(_fetch_batch_snapshot(batch), fmt=fmt)
 
@@ -175,6 +175,6 @@ def job_command(
 
     job = get_client(ctx).email.job(job_id)
     if wait:
-        emit(job.wait(timeout=timeout, on_poll=_job_status_to_stderr), fmt=fmt)
+        emit(job.wait(max_wait=timeout, on_poll=_job_status_to_stderr), fmt=fmt)
         return
     emit(job.status(), fmt=fmt)

{discolike_cli-0.4.0 → discolike_cli-0.5.0}/src/discolike_cli/main.py

@@ -5,7 +5,7 @@ from importlib.metadata import version as package_version
 from typing import Any
 
 import typer
-from typer._click.exceptions import Abort
+from typer import Abort
 from typer._click.exceptions import ClickException
 from typer._click.exceptions import NoArgsIsHelpError
 from typer._click.exceptions import UsageError
@@ -23,6 +23,7 @@ from discolike_cli import discover
 from discolike_cli import email
 from discolike_cli import enrich
 from discolike_cli import match
+from discolike_cli import prospecting
 from discolike_cli import providers
 from discolike_cli import queries
 from discolike_cli import signup
@@ -85,6 +86,7 @@ app.add_typer(contacts.app, name="contacts")
 app.add_typer(discogen.app, name="discogen")
 app.add_typer(email.app, name="email")
 app.add_typer(queries.app, name="queries")
+app.add_typer(prospecting.app, name="prospecting")
 app.add_typer(account.app, name="account")
 app.add_typer(providers.search_providers_app, name="search-providers")
 app.add_typer(providers.llm_providers_app, name="llm-providers")