autotouch-cli 0.2.17__tar.gz → 0.2.19__tar.gz

{autotouch_cli-0.2.17 → autotouch_cli-0.2.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.17
+Version: 0.2.19
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -140,6 +140,8 @@ Recipe-first flow (recommended):
 
 ```bash
 autotouch columns recipe --type add_to_crm --output human
+autotouch columns recipe --type sync_to_table --output human
+autotouch columns recipe --type add_to_sequence --output human
 ```
 
 Then create from the generated payload:
@@ -155,6 +157,44 @@ 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`.
+- `sync_to_table` supports both:
+  - single destination: `destinationTableId` + `columnMappings`
+  - router mode: `routes[]` (first matching route wins)
+- `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
 
@@ -187,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.17 → autotouch_cli-0.2.19}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.17
+Version: 0.2.19
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -140,6 +140,8 @@ Recipe-first flow (recommended):
 
 ```bash
 autotouch columns recipe --type add_to_crm --output human
+autotouch columns recipe --type sync_to_table --output human
+autotouch columns recipe --type add_to_sequence --output human
 ```
 
 Then create from the generated payload:
@@ -155,6 +157,44 @@ 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`.
+- `sync_to_table` supports both:
+  - single destination: `destinationTableId` + `columnMappings`
+  - router mode: `routes[]` (first matching route wins)
+- `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
 
@@ -187,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.17 → autotouch_cli-0.2.19}/docs/research-table/reference/autotouch-cli-pypi.md

@@ -131,6 +131,8 @@ Recipe-first flow (recommended):
 
 ```bash
 autotouch columns recipe --type add_to_crm --output human
+autotouch columns recipe --type sync_to_table --output human
+autotouch columns recipe --type add_to_sequence --output human
 ```
 
 Then create from the generated payload:
@@ -146,6 +148,44 @@ 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`.
+- `sync_to_table` supports both:
+  - single destination: `destinationTableId` + `columnMappings`
+  - router mode: `routes[]` (first matching route wins)
+- `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
 
@@ -178,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.17 → autotouch_cli-0.2.19}/pyproject.toml

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

{autotouch_cli-0.2.17 → autotouch_cli-0.2.19}/scripts/smart_table_cli.py

@@ -77,6 +77,8 @@ COLUMN_RECIPE_TYPES = [
     "lead_finder",
     "llm_enrichment",
     "add_to_crm",
+    "sync_to_table",
+    "add_to_sequence",
 ]
 
 COLUMN_CREATE_RECIPES: Dict[str, Dict[str, Any]] = {
@@ -181,6 +183,36 @@ COLUMN_CREATE_RECIPES: Dict[str, Dict[str, Any]] = {
             ],
         },
     },
+    "sync_to_table": {
+        "key": "sync_to_table",
+        "label": "Sync to Table",
+        "kind": "enrichment",
+        "dataType": "json",
+        "origin": "manual",
+        "autoRun": "onSourceUpdate",
+        "config": {
+            "provider": "sync_to_table",
+            "destinationTableId": "<DESTINATION_TABLE_ID>",
+            "columnMappings": [
+                {"sourceKey": "company", "destKey": "company"},
+                {"sourceKey": "domain", "destKey": "company_domain"},
+                {"sourceKey": "work_email", "destKey": "work_email"},
+            ],
+        },
+    },
+    "add_to_sequence": {
+        "key": "add_to_sequence",
+        "label": "Add to Sequence",
+        "kind": "enrichment",
+        "dataType": "json",
+        "origin": "manual",
+        "autoRun": "onSourceUpdate",
+        "config": {
+            "provider": "add_to_sequence",
+            "sequenceId": "<SEQUENCE_ID>",
+            "sourceLeadColumn": "add_to_leads",
+        },
+    },
 }
 
 COLUMN_RECIPE_NOTES: Dict[str, List[str]] = {
@@ -201,21 +233,35 @@ COLUMN_RECIPE_NOTES: Dict[str, List[str]] = {
         "LinkedIn URL + company domain mappings are required for eligibility.",
         "Add to CRM is optional and non-billable.",
     ],
+    "sync_to_table": [
+        "Use destinationTableId + columnMappings for single-destination sync.",
+        "Router mode is supported via config.routes[] (first matching route wins).",
+    ],
+    "add_to_sequence": [
+        "sourceLeadColumn should reference a column that stores lead IDs (for example add_to_crm or lead_finder output).",
+        "Set sequenceId to the target workflow sequence ID.",
+    ],
 }
 
 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",