autotouch-cli 0.2.22__tar.gz → 0.2.23__tar.gz

{autotouch_cli-0.2.22 → autotouch_cli-0.2.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.22
+Version: 0.2.23
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -207,6 +207,12 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- CRM data model expectations for `add_to_crm`:
+  - Lead identity/dedupe expects `linkedin_url` + `company_domain` (clean domain format).
+  - `company_domain` is required; `company_name` is a display hint applied to the linked Company record.
+  - Leads link to companies via `company_id`; canonical company name lives on the Company document.
+  - Canonical lead contact fields are arrays (`email_addresses[]`, `phone_numbers[]`); legacy scalar fields may exist but are fallback only.
+  - Reference: `docs/data/leads.md`, `docs/data/companies.md`.
 - Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
@@ -243,6 +249,9 @@ If path A is missing, continue to B/C before declaring `not_found`.
 JSON split note:
 - Optional by default.
 - Use only when downstream filters/mappings need stable flat keys.
+- If source columns are JSON enrichments, run with `--wait` and confirm terminal job status before splitting.
+- CLI behavior: `columns projections` emits preflight warnings when a JSON enrichment source appears unrun/unverified.
+- Warning output contract: when warnings exist, JSON output is wrapped as `{ "event": "projections.created_with_warnings", "warnings": [...], "result": <api_response> }`.
 
 Reference:
 - `docs/research-table/guides/context-first-sequence-playbook.md`

{autotouch_cli-0.2.22 → autotouch_cli-0.2.23}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.22
+Version: 0.2.23
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -207,6 +207,12 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- CRM data model expectations for `add_to_crm`:
+  - Lead identity/dedupe expects `linkedin_url` + `company_domain` (clean domain format).
+  - `company_domain` is required; `company_name` is a display hint applied to the linked Company record.
+  - Leads link to companies via `company_id`; canonical company name lives on the Company document.
+  - Canonical lead contact fields are arrays (`email_addresses[]`, `phone_numbers[]`); legacy scalar fields may exist but are fallback only.
+  - Reference: `docs/data/leads.md`, `docs/data/companies.md`.
 - Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
@@ -243,6 +249,9 @@ If path A is missing, continue to B/C before declaring `not_found`.
 JSON split note:
 - Optional by default.
 - Use only when downstream filters/mappings need stable flat keys.
+- If source columns are JSON enrichments, run with `--wait` and confirm terminal job status before splitting.
+- CLI behavior: `columns projections` emits preflight warnings when a JSON enrichment source appears unrun/unverified.
+- Warning output contract: when warnings exist, JSON output is wrapped as `{ "event": "projections.created_with_warnings", "warnings": [...], "result": <api_response> }`.
 
 Reference:
 - `docs/research-table/guides/context-first-sequence-playbook.md`

{autotouch_cli-0.2.22 → autotouch_cli-0.2.23}/docs/research-table/reference/autotouch-cli-pypi.md

@@ -198,6 +198,12 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- CRM data model expectations for `add_to_crm`:
+  - Lead identity/dedupe expects `linkedin_url` + `company_domain` (clean domain format).
+  - `company_domain` is required; `company_name` is a display hint applied to the linked Company record.
+  - Leads link to companies via `company_id`; canonical company name lives on the Company document.
+  - Canonical lead contact fields are arrays (`email_addresses[]`, `phone_numbers[]`); legacy scalar fields may exist but are fallback only.
+  - Reference: `docs/data/leads.md`, `docs/data/companies.md`.
 - Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
@@ -234,6 +240,9 @@ If path A is missing, continue to B/C before declaring `not_found`.
 JSON split note:
 - Optional by default.
 - Use only when downstream filters/mappings need stable flat keys.
+- If source columns are JSON enrichments, run with `--wait` and confirm terminal job status before splitting.
+- CLI behavior: `columns projections` emits preflight warnings when a JSON enrichment source appears unrun/unverified.
+- Warning output contract: when warnings exist, JSON output is wrapped as `{ "event": "projections.created_with_warnings", "warnings": [...], "result": <api_response> }`.
 
 Reference:
 - `docs/research-table/guides/context-first-sequence-playbook.md`

{autotouch_cli-0.2.22 → autotouch_cli-0.2.23}/pyproject.toml

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

{autotouch_cli-0.2.22 → autotouch_cli-0.2.23}/scripts/smart_table_cli.py

@@ -57,6 +57,14 @@ TERMINAL_JOB_STATUSES = {
     "failed",
     "completed_with_errors",
 }
+NON_TERMINAL_JOB_STATUSES = {
+    "queued",
+    "distributing",
+    "processing",
+    "running",
+    "pending",
+}
+PROJECTION_READINESS_SAMPLE_SIZE = 50
 CONFIG_ENV_KEY = "AUTOTOUCH_CONFIG_PATH"
 CONFIG_DIR_NAME = "autotouch"
 CONFIG_FILE_NAME = "config.json"
@@ -256,6 +264,7 @@ RUN_SOP_GUIDE: Dict[str, Any] = {
         "For add_to_crm, generate payload from columns recipe before create/update.",
         "Keep unprocessedOnly enabled unless you intentionally reprocess rows.",
         "Treat bulk job state as source of truth: queued/distributing/processing are non-terminal; completed/partial/error/cancelled are terminal.",
+        "For JSON enrichment columns, run with --wait and verify terminal status before creating projection splits.",
         "Always inspect raw outputs before summary counts; parse by column dataType (json vs scalar).",
         "When summarizing enrichment outputs, parse by key precedence (phone: mobile_number -> phone_numbers[0].number -> primary_phone; email: response -> email -> work_email).",
     ],
@@ -1028,6 +1037,224 @@ def _resolve_column_key(
     sys.exit(1)
 
 
+def _extract_columns_list(columns_raw: Any) -> List[Dict[str, Any]]:
+    if isinstance(columns_raw, list):
+        return [col for col in columns_raw if isinstance(col, dict)]
+    if isinstance(columns_raw, dict):
+        candidates = columns_raw.get("columns") or columns_raw.get("items") or columns_raw.get("data") or []
+        if isinstance(candidates, list):
+            return [col for col in candidates if isinstance(col, dict)]
+    return []
+
+
+def _extract_jobs_list(jobs_raw: Any) -> List[Dict[str, Any]]:
+    if isinstance(jobs_raw, list):
+        return [job for job in jobs_raw if isinstance(job, dict)]
+    if isinstance(jobs_raw, dict):
+        candidates = jobs_raw.get("jobs") or jobs_raw.get("items") or jobs_raw.get("data") or []
+        if isinstance(candidates, list):
+            return [job for job in candidates if isinstance(job, dict)]
+    return []
+
+
+def _is_json_enrichment_column(column: Dict[str, Any]) -> bool:
+    kind = str(column.get("kind") or "").strip().lower()
+    data_type = str(column.get("dataType") or column.get("data_type") or "").strip().lower()
+    return kind == "enrichment" and data_type == "json"
+
+
+def _projection_recommended_run_command(table_id: str, column_id: str) -> str:
+    return (
+        f"autotouch columns run --table-id {table_id} --column-id {column_id} "
+        "--scope all --show-estimate --wait --output json"
+    )
+
+
+def _projection_preflight_warn(
+    *,
+    code: str,
+    column: Dict[str, Any],
+    reason: str,
+    recommended_next_command: str,
+    latest_job_status: Optional[str] = None,
+    column_status: Optional[str] = None,
+    sample_rows_scanned: Optional[int] = None,
+    sample_non_empty_values: Optional[int] = None,
+) -> Dict[str, Any]:
+    warning: Dict[str, Any] = {
+        "code": code,
+        "severity": "warning",
+        "source_column_id": str(column.get("id") or column.get("_id") or ""),
+        "source_column_key": str(column.get("key") or ""),
+        "source_column_label": str(column.get("label") or column.get("key") or ""),
+        "reason": reason,
+        "recommended_next_command": recommended_next_command,
+    }
+    if latest_job_status:
+        warning["latest_job_status"] = latest_job_status
+    if column_status:
+        warning["column_status"] = column_status
+    if sample_rows_scanned is not None:
+        warning["sample_rows_scanned"] = int(sample_rows_scanned)
+    if sample_non_empty_values is not None:
+        warning["sample_non_empty_values"] = int(sample_non_empty_values)
+    return warning
+
+
+def _print_projection_preflight_warnings(warnings: List[Dict[str, Any]]) -> None:
+    if not warnings:
+        return
+    print(
+        f"WARNING: projection preflight found {len(warnings)} source column(s) that may not be ready yet.",
+        file=sys.stderr,
+    )
+    for warning in warnings:
+        col_label = warning.get("source_column_label") or warning.get("source_column_key") or warning.get("source_column_id")
+        col_id = warning.get("source_column_id") or "unknown"
+        reason = warning.get("reason") or "source may be unprocessed"
+        print(f"WARNING: [{warning.get('code')}] {col_label} ({col_id}): {reason}", file=sys.stderr)
+        cmd = warning.get("recommended_next_command")
+        if cmd:
+            print(f"         Recommended: {cmd}", file=sys.stderr)
+
+
+def _build_projection_preflight_warnings(
+    *,
+    table_id: str,
+    payload: Dict[str, Any],
+    base_url: str,
+    token: str,
+    use_x_api_key: bool,
+    timeout: int,
+    verbose: bool,
+) -> List[Dict[str, Any]]:
+    items = payload.get("items")
+    if not isinstance(items, list) or not items:
+        return []
+
+    source_ids: List[str] = []
+    seen: set[str] = set()
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        raw_source = item.get("sourceColumnId") or item.get("source_column_id")
+        source_id = str(raw_source or "").strip()
+        if not source_id or source_id in seen:
+            continue
+        seen.add(source_id)
+        source_ids.append(source_id)
+    if not source_ids:
+        return []
+
+    columns_raw = _request_api(
+        "GET",
+        f"/api/tables/{table_id}/columns",
+        base_url=base_url,
+        token=token,
+        use_x_api_key=use_x_api_key,
+        timeout=timeout,
+        verbose=verbose,
+    )
+    columns = _extract_columns_list(columns_raw)
+    by_id: Dict[str, Dict[str, Any]] = {}
+    for col in columns:
+        cid = str(col.get("id") or col.get("_id") or "").strip()
+        if cid:
+            by_id[cid] = col
+
+    warnings: List[Dict[str, Any]] = []
+    rows_sample: Optional[List[Dict[str, Any]]] = None
+    jobs_cache: Dict[str, Optional[Dict[str, Any]]] = {}
+
+    for source_id in source_ids:
+        source_col = by_id.get(source_id)
+        if not source_col or not _is_json_enrichment_column(source_col):
+            continue
+
+        source_col_id = str(source_col.get("id") or source_col.get("_id") or source_id)
+        source_key = str(source_col.get("key") or "").strip()
+        recommended_next = _projection_recommended_run_command(table_id, source_col_id)
+
+        latest_job = jobs_cache.get(source_col_id)
+        if source_col_id not in jobs_cache:
+            jobs_raw = _request_api(
+                "GET",
+                "/api/bulk-jobs",
+                base_url=base_url,
+                token=token,
+                use_x_api_key=use_x_api_key,
+                params={"table_id": table_id, "column_id": source_col_id, "limit": 1},
+                timeout=timeout,
+                verbose=verbose,
+            )
+            jobs = _extract_jobs_list(jobs_raw)
+            latest_job = jobs[0] if jobs else None
+            jobs_cache[source_col_id] = latest_job
+
+        latest_job_status = str((latest_job or {}).get("status") or "").strip().lower()
+        if latest_job_status in NON_TERMINAL_JOB_STATUSES:
+            warnings.append(
+                _projection_preflight_warn(
+                    code="source_job_not_terminal",
+                    column=source_col,
+                    reason=f"latest run status is '{latest_job_status}' (not terminal)",
+                    recommended_next_command=recommended_next,
+                    latest_job_status=latest_job_status,
+                    column_status=str(source_col.get("status") or "").strip().lower() or None,
+                )
+            )
+            continue
+        if latest_job_status in TERMINAL_JOB_STATUSES:
+            continue
+
+        has_run_metadata = bool(
+            source_col.get("lastRunAt")
+            or source_col.get("last_run_at")
+            or source_col.get("lastJobId")
+            or source_col.get("last_job_id")
+        )
+        if has_run_metadata:
+            continue
+
+        if rows_sample is None:
+            rows_page_raw = _request_api(
+                "GET",
+                f"/api/tables/{table_id}/rows",
+                base_url=base_url,
+                token=token,
+                use_x_api_key=use_x_api_key,
+                params={"page_size": PROJECTION_READINESS_SAMPLE_SIZE},
+                timeout=timeout,
+                verbose=verbose,
+            )
+            if not isinstance(rows_page_raw, dict):
+                rows_sample = []
+            else:
+                candidate_rows = rows_page_raw.get("rows") or []
+                rows_sample = [row for row in candidate_rows if isinstance(row, dict)] if isinstance(candidate_rows, list) else []
+
+        sample_count = 0
+        if source_key:
+            sample_count = sum(1 for row in (rows_sample or []) if _is_processed_cell_value(row.get(source_key)))
+        if sample_count > 0:
+            continue
+
+        warnings.append(
+            _projection_preflight_warn(
+                code="source_unrun_or_empty",
+                column=source_col,
+                reason="source JSON enrichment has no terminal run evidence and sampled values are empty",
+                recommended_next_command=recommended_next,
+                latest_job_status=latest_job_status or None,
+                column_status=str(source_col.get("status") or "").strip().lower() or None,
+                sample_rows_scanned=len(rows_sample or []),
+                sample_non_empty_values=sample_count,
+            )
+        )
+
+    return warnings
+
+
 def _is_processed_cell_value(value: Any) -> bool:
     if value is None:
         return False
@@ -2226,7 +2453,7 @@ def cmd_capabilities(args: argparse.Namespace) -> None:
         basic_types_str = ", ".join(str(t) for t in basic_types) if isinstance(basic_types, list) else "text/json"
         print(f"basic : {basic_types_str} (JSON requires dataType=json)")
         print("")
-        print("Tip: use `autotouch columns projections` + formatter columns for JSON pipeline chaining.")
+        print("Tip: for JSON enrichment columns, run with `--wait` and verify terminal status before `autotouch columns projections`.")
         return
 
     _print_json(data, compact=args.compact)
@@ -3343,6 +3570,18 @@ def cmd_columns_projections(args: argparse.Namespace) -> None:
     if not isinstance(payload, dict):
         print("ERROR: projection create requires --data-json/--data-file with a JSON object", file=sys.stderr)
         sys.exit(2)
+
+    preflight_warnings = _build_projection_preflight_warnings(
+        table_id=args.table_id,
+        payload=payload,
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_projection_preflight_warnings(preflight_warnings)
+
     data = _request_api(
         "POST",
         f"/api/tables/{args.table_id}/columns/projections",
@@ -3353,6 +3592,16 @@ def cmd_columns_projections(args: argparse.Namespace) -> None:
         timeout=args.timeout,
         verbose=args.verbose,
     )
+    if preflight_warnings:
+        _print_json(
+            {
+                "event": "projections.created_with_warnings",
+                "warnings": preflight_warnings,
+                "result": data,
+            },
+            compact=args.compact,
+        )
+        return
     _print_json(data, compact=args.compact)