autotouch-cli 0.2.18__tar.gz → 0.2.20__tar.gz

{autotouch_cli-0.2.18 → autotouch_cli-0.2.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.18
+Version: 0.2.20
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -163,6 +163,38 @@ Notes:
 - `add_to_sequence` requires:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
+  - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+
+If you create custom `llm_enrichment` schemas:
+- Use strict field-map schema shape (no root `type/properties` wrapper).
+- Arrays must be explicit `{"type":"array","items":...}`.
+- Avoid legacy/list schema values like `["string"]` or `[{...}]`.
+- Prefer snake_case schema keys in payloads: `response_schema`, `user_schema`, `use_auto_schema`.
+
+## Parse enrichment outputs safely (important for agents)
+
+Use a layered rule:
+
+1. Always inspect raw outputs first (sample at least 3 rows).
+2. Parse by column `dataType`:
+   - `json`: use key precedence below.
+   - scalar types (`text`, `number`, `date`, `boolean`, `email`, `url`): parse direct value (no JSON key paths).
+3. Only then publish found/missing counts.
+
+Do not rely on a single key for JSON outputs.
+
+- Phone extraction precedence: `mobile_number` -> `phone_numbers[0].number` -> `primary_phone`
+- Email extraction precedence: `response` -> `email` -> `work_email`
+
+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.
+
+Reference:
+- `docs/research-table/guides/context-first-sequence-playbook.md`
+- `docs/research-table/reference/runbooks/context-first-sequence.json`
 
 ## Recommended ICP buyer discovery pattern
 
@@ -195,6 +227,72 @@ Important:
 - These workflow routes support `actorUserId` query parameter.
 - External sequence validation rules (manual vs automated vs AI draft constraints) are documented in the workflow reference above.
 
+### Sequence step types and rules (quick reference)
+
+Supported step kinds:
+- `EMAIL`
+- `CALL`
+- `LINKEDIN`
+- `LINKEDIN_CONNECT`
+- `LINKEDIN_MESSAGE`
+- `CUSTOM`
+
+Email send modes:
+- `AUTOMATED`
+- `MANUAL`
+
+External API validation rules:
+- First email step cannot be reply (`first_email_reply_not_allowed`).
+- Bulk mode cannot include manual email steps (`bulk_manual_email_not_allowed`).
+- `aiDraft` is only allowed on manual-capable steps:
+  - `CALL`, `CUSTOM`, `LINKEDIN`, `LINKEDIN_CONNECT`, `LINKEDIN_MESSAGE`
+  - `EMAIL` only when `emailSendMode=MANUAL`
+- `defaultAppendSignature` (sequence-level, optional) sets default signature behavior for email steps.
+- `steps[].appendSignature` (step-level, optional) overrides signature behavior per email step.
+
+Runtime behavior:
+- `EMAIL + AUTOMATED` is sent by scheduler/provider flow.
+- Manual/non-automated steps are created as Tasks for rep execution.
+
+Minimal mixed-step example:
+
+```json
+{
+  "name": "Outbound v1",
+  "sourceTableId": "tbl_123",
+  "defaultAppendSignature": true,
+  "steps": [
+    {
+      "id": "s1",
+      "kind": "EMAIL",
+      "emailSendMode": "AUTOMATED",
+      "emailIsReply": false,
+      "appendSignature": true,
+      "subjectTemplate": "Quick intro",
+      "bodyTemplate": "Hi {{first_name}}, ..."
+    },
+    {
+      "id": "s2",
+      "kind": "CALL",
+      "waitDays": 2,
+      "aiDraft": true
+    },
+    {
+      "id": "s3",
+      "kind": "EMAIL",
+      "waitDays": 4,
+      "emailSendMode": "MANUAL",
+      "emailIsReply": false,
+      "appendSignature": false,
+      "aiDraft": true
+    }
+  ]
+}
+```
+
+Canonical contract:
+- `docs/platform/external-workflows-api.md`
+
 ## Outbound webhook subscriptions
 
 Use webhook subscriptions to receive customer-facing event notifications.

{autotouch_cli-0.2.18 → autotouch_cli-0.2.20}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.18
+Version: 0.2.20
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -163,6 +163,38 @@ Notes:
 - `add_to_sequence` requires:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
+  - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+
+If you create custom `llm_enrichment` schemas:
+- Use strict field-map schema shape (no root `type/properties` wrapper).
+- Arrays must be explicit `{"type":"array","items":...}`.
+- Avoid legacy/list schema values like `["string"]` or `[{...}]`.
+- Prefer snake_case schema keys in payloads: `response_schema`, `user_schema`, `use_auto_schema`.
+
+## Parse enrichment outputs safely (important for agents)
+
+Use a layered rule:
+
+1. Always inspect raw outputs first (sample at least 3 rows).
+2. Parse by column `dataType`:
+   - `json`: use key precedence below.
+   - scalar types (`text`, `number`, `date`, `boolean`, `email`, `url`): parse direct value (no JSON key paths).
+3. Only then publish found/missing counts.
+
+Do not rely on a single key for JSON outputs.
+
+- Phone extraction precedence: `mobile_number` -> `phone_numbers[0].number` -> `primary_phone`
+- Email extraction precedence: `response` -> `email` -> `work_email`
+
+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.
+
+Reference:
+- `docs/research-table/guides/context-first-sequence-playbook.md`
+- `docs/research-table/reference/runbooks/context-first-sequence.json`
 
 ## Recommended ICP buyer discovery pattern
 
@@ -195,6 +227,72 @@ Important:
 - These workflow routes support `actorUserId` query parameter.
 - External sequence validation rules (manual vs automated vs AI draft constraints) are documented in the workflow reference above.
 
+### Sequence step types and rules (quick reference)
+
+Supported step kinds:
+- `EMAIL`
+- `CALL`
+- `LINKEDIN`
+- `LINKEDIN_CONNECT`
+- `LINKEDIN_MESSAGE`
+- `CUSTOM`
+
+Email send modes:
+- `AUTOMATED`
+- `MANUAL`
+
+External API validation rules:
+- First email step cannot be reply (`first_email_reply_not_allowed`).
+- Bulk mode cannot include manual email steps (`bulk_manual_email_not_allowed`).
+- `aiDraft` is only allowed on manual-capable steps:
+  - `CALL`, `CUSTOM`, `LINKEDIN`, `LINKEDIN_CONNECT`, `LINKEDIN_MESSAGE`
+  - `EMAIL` only when `emailSendMode=MANUAL`
+- `defaultAppendSignature` (sequence-level, optional) sets default signature behavior for email steps.
+- `steps[].appendSignature` (step-level, optional) overrides signature behavior per email step.
+
+Runtime behavior:
+- `EMAIL + AUTOMATED` is sent by scheduler/provider flow.
+- Manual/non-automated steps are created as Tasks for rep execution.
+
+Minimal mixed-step example:
+
+```json
+{
+  "name": "Outbound v1",
+  "sourceTableId": "tbl_123",
+  "defaultAppendSignature": true,
+  "steps": [
+    {
+      "id": "s1",
+      "kind": "EMAIL",
+      "emailSendMode": "AUTOMATED",
+      "emailIsReply": false,
+      "appendSignature": true,
+      "subjectTemplate": "Quick intro",
+      "bodyTemplate": "Hi {{first_name}}, ..."
+    },
+    {
+      "id": "s2",
+      "kind": "CALL",
+      "waitDays": 2,
+      "aiDraft": true
+    },
+    {
+      "id": "s3",
+      "kind": "EMAIL",
+      "waitDays": 4,
+      "emailSendMode": "MANUAL",
+      "emailIsReply": false,
+      "appendSignature": false,
+      "aiDraft": true
+    }
+  ]
+}
+```
+
+Canonical contract:
+- `docs/platform/external-workflows-api.md`
+
 ## Outbound webhook subscriptions
 
 Use webhook subscriptions to receive customer-facing event notifications.

{autotouch_cli-0.2.18 → autotouch_cli-0.2.20}/docs/research-table/reference/autotouch-cli-pypi.md

@@ -154,6 +154,38 @@ Notes:
 - `add_to_sequence` requires:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
+  - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+
+If you create custom `llm_enrichment` schemas:
+- Use strict field-map schema shape (no root `type/properties` wrapper).
+- Arrays must be explicit `{"type":"array","items":...}`.
+- Avoid legacy/list schema values like `["string"]` or `[{...}]`.
+- Prefer snake_case schema keys in payloads: `response_schema`, `user_schema`, `use_auto_schema`.
+
+## Parse enrichment outputs safely (important for agents)
+
+Use a layered rule:
+
+1. Always inspect raw outputs first (sample at least 3 rows).
+2. Parse by column `dataType`:
+   - `json`: use key precedence below.
+   - scalar types (`text`, `number`, `date`, `boolean`, `email`, `url`): parse direct value (no JSON key paths).
+3. Only then publish found/missing counts.
+
+Do not rely on a single key for JSON outputs.
+
+- Phone extraction precedence: `mobile_number` -> `phone_numbers[0].number` -> `primary_phone`
+- Email extraction precedence: `response` -> `email` -> `work_email`
+
+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.
+
+Reference:
+- `docs/research-table/guides/context-first-sequence-playbook.md`
+- `docs/research-table/reference/runbooks/context-first-sequence.json`
 
 ## Recommended ICP buyer discovery pattern
 
@@ -186,6 +218,72 @@ Important:
 - These workflow routes support `actorUserId` query parameter.
 - External sequence validation rules (manual vs automated vs AI draft constraints) are documented in the workflow reference above.
 
+### Sequence step types and rules (quick reference)
+
+Supported step kinds:
+- `EMAIL`
+- `CALL`
+- `LINKEDIN`
+- `LINKEDIN_CONNECT`
+- `LINKEDIN_MESSAGE`
+- `CUSTOM`
+
+Email send modes:
+- `AUTOMATED`
+- `MANUAL`
+
+External API validation rules:
+- First email step cannot be reply (`first_email_reply_not_allowed`).
+- Bulk mode cannot include manual email steps (`bulk_manual_email_not_allowed`).
+- `aiDraft` is only allowed on manual-capable steps:
+  - `CALL`, `CUSTOM`, `LINKEDIN`, `LINKEDIN_CONNECT`, `LINKEDIN_MESSAGE`
+  - `EMAIL` only when `emailSendMode=MANUAL`
+- `defaultAppendSignature` (sequence-level, optional) sets default signature behavior for email steps.
+- `steps[].appendSignature` (step-level, optional) overrides signature behavior per email step.
+
+Runtime behavior:
+- `EMAIL + AUTOMATED` is sent by scheduler/provider flow.
+- Manual/non-automated steps are created as Tasks for rep execution.
+
+Minimal mixed-step example:
+
+```json
+{
+  "name": "Outbound v1",
+  "sourceTableId": "tbl_123",
+  "defaultAppendSignature": true,
+  "steps": [
+    {
+      "id": "s1",
+      "kind": "EMAIL",
+      "emailSendMode": "AUTOMATED",
+      "emailIsReply": false,
+      "appendSignature": true,
+      "subjectTemplate": "Quick intro",
+      "bodyTemplate": "Hi {{first_name}}, ..."
+    },
+    {
+      "id": "s2",
+      "kind": "CALL",
+      "waitDays": 2,
+      "aiDraft": true
+    },
+    {
+      "id": "s3",
+      "kind": "EMAIL",
+      "waitDays": 4,
+      "emailSendMode": "MANUAL",
+      "emailIsReply": false,
+      "appendSignature": false,
+      "aiDraft": true
+    }
+  ]
+}
+```
+
+Canonical contract:
+- `docs/platform/external-workflows-api.md`
+
 ## Outbound webhook subscriptions
 
 Use webhook subscriptions to receive customer-facing event notifications.

{autotouch_cli-0.2.18 → autotouch_cli-0.2.20}/pyproject.toml

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

{autotouch_cli-0.2.18 → autotouch_cli-0.2.20}/scripts/smart_table_cli.py

@@ -51,6 +51,7 @@ TERMINAL_JOB_STATUSES = {
     "completed",
     "partial",
     "error",
+    "timed_out",
     "cancelled",
     "failed",
     "completed_with_errors",
@@ -246,16 +247,22 @@ COLUMN_RECIPE_NOTES: Dict[str, List[str]] = {
 RUN_SOP_GUIDE: Dict[str, Any] = {
     "title": "Credit-safe enrichment SOP",
     "rules": [
+        "Use --output json for automation; avoid parsing human-format output.",
         "Filter first before running billable columns.",
         "Estimate first with the same payload you plan to run.",
         "Start with a small firstN pilot before scaling.",
         "For exact bounded batches, prefer run-next with a small count.",
         "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.",
+        "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).",
     ],
     "clarifications": [
         "Email/phone enrichment does not require add_to_crm.",
         "add_to_crm is an optional export action to Leads CRM (non-billable).",
+        "For custom LLM schemas, use strict field-map shape (no root type/properties wrapper; arrays must use {type:\"array\",items:...}).",
+        "Do not report not_found from a single missing key when fallback keys exist.",
     ],
     "default_run_payload": {
         "scope": "filtered",