autotouch-cli 0.2.10__tar.gz → 0.2.12__tar.gz

{autotouch_cli-0.2.10 → autotouch_cli-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.10
+Version: 0.2.12
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -145,6 +145,19 @@ Notes:
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
 
+## Recommended ICP buyer discovery pattern
+
+Use the dedicated guide:
+
+- `docs/research-table/guides/icp-buyer-discovery.md`
+
+This keeps quickstart short while documenting the full strategy:
+
+- when to use `lead_finder` vs agent research,
+- responsibility-based targeting (not exact title matching),
+- one-person-per-row output contract,
+- JSON split + downstream enrichment chaining.
+
 ## Create basic/manual fields (text, number, date, etc.)
 
 Use `kind=manual` for non-enrichment columns.
@@ -281,6 +294,10 @@ autotouch columns run-next \
 
 - Treat a run as started only when you receive `job_id`.
 - Treat a run as done only when `jobs get/watch` returns terminal status.
+- `columns run --wait` now emits structured progress events and includes:
+  - `job_id`
+  - `job_status_url`
+  - `watch_command`
 
 ```bash
 autotouch jobs get --job-id <JOB_ID> --output json
@@ -293,6 +310,25 @@ Terminal statuses:
 - `error`
 - `cancelled`
 
+Non-terminal statuses:
+- `queued`
+- `distributing`
+- `processing`
+
+Recommended status fields to inspect while waiting:
+- `processed_rows`
+- `error_rows`
+- `skipped_rows`
+- `total_rows`
+- `pending_batches`
+- `terminal_reason`
+
+CLI-protected failure statuses:
+- `not_found`
+- `unknown_not_found`
+
+If either failure status appears, treat the run as unconfirmed/inconsistent, verify row state, and rerun.
+
 ## Troubleshooting
 
 1. Import appears to run but rows are missing:

{autotouch_cli-0.2.10 → autotouch_cli-0.2.12}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.10
+Version: 0.2.12
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -145,6 +145,19 @@ Notes:
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
 
+## Recommended ICP buyer discovery pattern
+
+Use the dedicated guide:
+
+- `docs/research-table/guides/icp-buyer-discovery.md`
+
+This keeps quickstart short while documenting the full strategy:
+
+- when to use `lead_finder` vs agent research,
+- responsibility-based targeting (not exact title matching),
+- one-person-per-row output contract,
+- JSON split + downstream enrichment chaining.
+
 ## Create basic/manual fields (text, number, date, etc.)
 
 Use `kind=manual` for non-enrichment columns.
@@ -281,6 +294,10 @@ autotouch columns run-next \
 
 - Treat a run as started only when you receive `job_id`.
 - Treat a run as done only when `jobs get/watch` returns terminal status.
+- `columns run --wait` now emits structured progress events and includes:
+  - `job_id`
+  - `job_status_url`
+  - `watch_command`
 
 ```bash
 autotouch jobs get --job-id <JOB_ID> --output json
@@ -293,6 +310,25 @@ Terminal statuses:
 - `error`
 - `cancelled`
 
+Non-terminal statuses:
+- `queued`
+- `distributing`
+- `processing`
+
+Recommended status fields to inspect while waiting:
+- `processed_rows`
+- `error_rows`
+- `skipped_rows`
+- `total_rows`
+- `pending_batches`
+- `terminal_reason`
+
+CLI-protected failure statuses:
+- `not_found`
+- `unknown_not_found`
+
+If either failure status appears, treat the run as unconfirmed/inconsistent, verify row state, and rerun.
+
 ## Troubleshooting
 
 1. Import appears to run but rows are missing:

{autotouch_cli-0.2.10 → autotouch_cli-0.2.12}/docs/research-table/reference/autotouch-cli-pypi.md

@@ -136,6 +136,19 @@ Notes:
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
 
+## Recommended ICP buyer discovery pattern
+
+Use the dedicated guide:
+
+- `docs/research-table/guides/icp-buyer-discovery.md`
+
+This keeps quickstart short while documenting the full strategy:
+
+- when to use `lead_finder` vs agent research,
+- responsibility-based targeting (not exact title matching),
+- one-person-per-row output contract,
+- JSON split + downstream enrichment chaining.
+
 ## Create basic/manual fields (text, number, date, etc.)
 
 Use `kind=manual` for non-enrichment columns.
@@ -272,6 +285,10 @@ autotouch columns run-next \
 
 - Treat a run as started only when you receive `job_id`.
 - Treat a run as done only when `jobs get/watch` returns terminal status.
+- `columns run --wait` now emits structured progress events and includes:
+  - `job_id`
+  - `job_status_url`
+  - `watch_command`
 
 ```bash
 autotouch jobs get --job-id <JOB_ID> --output json
@@ -284,6 +301,25 @@ Terminal statuses:
 - `error`
 - `cancelled`
 
+Non-terminal statuses:
+- `queued`
+- `distributing`
+- `processing`
+
+Recommended status fields to inspect while waiting:
+- `processed_rows`
+- `error_rows`
+- `skipped_rows`
+- `total_rows`
+- `pending_batches`
+- `terminal_reason`
+
+CLI-protected failure statuses:
+- `not_found`
+- `unknown_not_found`
+
+If either failure status appears, treat the run as unconfirmed/inconsistent, verify row state, and rerun.
+
 ## Troubleshooting
 
 1. Import appears to run but rows are missing:

{autotouch_cli-0.2.10 → autotouch_cli-0.2.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "autotouch-cli"
-version = "0.2.10"
+version = "0.2.12"
 description = "Autotouch Smart Table CLI"
 readme = "docs/research-table/reference/autotouch-cli-pypi.md"
 requires-python = ">=3.9"

{autotouch_cli-0.2.10 → autotouch_cli-0.2.12}/scripts/smart_table_cli.py

@@ -1039,18 +1039,24 @@ def _execute_run_flow(
             output = run_data if context is None else {"context": context, "run": run_data}
             _print_json(output, compact=args.compact)
             sys.exit(1)
+        job_id = str(job_id)
+        status_url = f"{_api_url(args.base_url)}/api/bulk-jobs/{job_id}"
+        watch_command = f"autotouch jobs watch --job-id {job_id}"
         if not args.quiet_wait:
             _print_json(
                 {
-                    "job_id": str(job_id),
+                    "event": "run.wait_started",
+                    "job_id": job_id,
                     "status": "polling_started",
+                    "status_url": status_url,
+                    "watch_command": watch_command,
                     "hint": "polling /api/bulk-jobs/{job_id}",
                 },
                 compact=args.compact,
             )
 
         poll_result = _poll_job(
-            job_id=str(job_id),
+            job_id=job_id,
             base_url=args.base_url,
             token=token,
             use_x_api_key=args.use_x_api_key,
@@ -1064,10 +1070,17 @@ def _execute_run_flow(
         )
         final_job = poll_result.get("job") or {}
         timed_out = bool(poll_result.get("timed_out"))
+        final_status = str((final_job or {}).get("status") or "").lower()
         output = {
+            "event": "run.timed_out" if timed_out else "run.completed",
             "run": run_data,
             "estimate": estimate_data if args.show_estimate or args.max_credits is not None else None,
+            "job": final_job,
             "final_job": final_job,
+            "job_id": job_id,
+            "job_status_url": status_url,
+            "watch_command": watch_command,
+            "status": final_status,
             "timed_out": timed_out,
             "polls": int(poll_result.get("polls") or 0),
         }
@@ -1077,18 +1090,45 @@ def _execute_run_flow(
 
         if timed_out:
             sys.exit(4)
-        final_status = str((final_job or {}).get("status") or "").lower()
+        if final_status in {"not_found", "unknown_not_found"}:
+            print(
+                f"ERROR: job {job_id} disappeared before terminal status; verify row state and rerun if needed",
+                file=sys.stderr,
+            )
+            sys.exit(1)
         if args.fail_on_error and final_status in {"error", "cancelled"}:
             sys.exit(1)
         if args.fail_on_partial and final_status == "partial":
             sys.exit(1)
         return
 
+    job_id = run_data.get("job_id") or run_data.get("jobId")
+    status_url = None
+    watch_command = None
+    if job_id:
+        status_url = f"{_api_url(args.base_url)}/api/bulk-jobs/{job_id}"
+        watch_command = f"autotouch jobs watch --job-id {job_id}"
+
     output_any: Any = run_data
     if estimate_data is not None and args.show_estimate:
         output_any = {"estimate": estimate_data, "run": run_data}
     if context is not None:
         output_any = {"context": context, "result": output_any}
+    if isinstance(output_any, dict):
+        output_any = dict(output_any)
+        output_any.setdefault("event", "run.queued")
+        if job_id:
+            output_any.setdefault("job_id", str(job_id))
+            output_any["job_status_url"] = status_url
+            output_any["watch_command"] = watch_command
+    elif job_id:
+        output_any = {
+            "event": "run.queued",
+            "job_id": str(job_id),
+            "job_status_url": status_url,
+            "watch_command": watch_command,
+            "result": output_any,
+        }
     _print_json(output_any, compact=args.compact)
 
 
@@ -1266,8 +1306,11 @@ def _poll_job(
     polls = 0
     heartbeat_every_polls = 5
     max_consecutive_poll_errors = 6
+    max_not_found_grace_polls = max(3, int(20 // interval) + 1)
     consecutive_poll_errors = 0
+    not_found_polls = 0
     last_status: Optional[str] = None
+    last_job_doc: Optional[Dict[str, Any]] = None
     url = f"{_api_url(base_url)}/api/bulk-jobs/{job_id}"
     headers = _auth_headers(token, use_x_api_key=use_x_api_key)
 
@@ -1286,6 +1329,7 @@ def _poll_job(
             if print_updates and (consecutive_poll_errors == 1 or consecutive_poll_errors % 3 == 0):
                 _print_json(
                     {
+                        "event": "job.polling_error",
                         "job_id": job_id,
                         "status": "polling_error",
                         "polls": polls,
@@ -1314,6 +1358,7 @@ def _poll_job(
             if print_updates and (consecutive_poll_errors == 1 or consecutive_poll_errors % 3 == 0):
                 _print_json(
                     {
+                        "event": "job.polling_error",
                         "job_id": job_id,
                         "status": "polling_error",
                         "polls": polls,
@@ -1343,18 +1388,34 @@ def _poll_job(
 
         consecutive_poll_errors = 0
 
-        if response.status_code == 404 and not once:
-            job_doc = {
-                "job_id": job_id,
-                "status": "queued",
-                "provider": None,
-                "processed_rows": 0,
-                "total_rows": 0,
-                "error_rows": 0,
-                "credits_used": 0.0,
-                "billable": False,
-                "updated_at": None,
-            }
+        if response.status_code == 404:
+            not_found_polls += 1
+            if not once and last_job_doc is None and not_found_polls <= max_not_found_grace_polls:
+                job_doc = {
+                    "job_id": job_id,
+                    "status": "queued",
+                    "provider": None,
+                    "processed_rows": 0,
+                    "total_rows": 0,
+                    "error_rows": 0,
+                    "credits_used": 0.0,
+                    "billable": False,
+                    "updated_at": None,
+                    "not_found_polls": not_found_polls,
+                }
+            elif last_job_doc is not None:
+                unknown_job = dict(last_job_doc)
+                unknown_job["status"] = "unknown_not_found"
+                unknown_job["not_found_polls"] = not_found_polls
+                unknown_job["note"] = "job endpoint returned 404 before terminal status"
+                return {"job": unknown_job, "polls": polls, "timed_out": False}
+            else:
+                missing_job = {
+                    "job_id": job_id,
+                    "status": "not_found",
+                    "not_found_polls": not_found_polls,
+                }
+                return {"job": missing_job, "polls": polls, "timed_out": False}
         else:
             content_type = response.headers.get("content-type", "").lower()
             if "application/json" in content_type:
@@ -1377,9 +1438,14 @@ def _poll_job(
                 print(f"ERROR: unexpected bulk job response: {parsed_body}", file=sys.stderr)
                 sys.exit(1)
             job_doc = parsed_body
+            last_job_doc = job_doc
+            not_found_polls = 0
 
         status = str(job_doc.get("status") or "").lower()
         snapshot = _job_snapshot(job_doc)
+        snapshot["event"] = "job.progress"
+        snapshot["terminal"] = status in TERMINAL_JOB_STATUSES
+        snapshot["status_url"] = url
         snapshot["polls"] = polls
         snapshot["elapsed_seconds"] = int(max(0.0, time.monotonic() - started))
 
@@ -2545,8 +2611,10 @@ def cmd_jobs_watch(args: argparse.Namespace) -> None:
         return
 
     final_summary = {
+        "event": "job.timed_out" if timed_out else "job.completed",
         "job_id": final_job.get("job_id") or final_job.get("jobId") or args.job_id,
         "status": final_job.get("status"),
+        "job_status_url": f"{_api_url(args.base_url)}/api/bulk-jobs/{args.job_id}",
         "timed_out": timed_out,
         "polls": int(poll_result.get("polls") or 0),
     }