autotouch-cli 0.2.31__tar.gz → 0.2.32__tar.gz

{autotouch_cli-0.2.31/autotouch_cli.egg-info → autotouch_cli-0.2.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.31
+Version: 0.2.32
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -515,8 +515,8 @@ autotouch columns create --table-id <TABLE_ID> --data-file <payload.json>
 ```
 
 Recommendation:
-- For provider-backed workflow columns, start with `autotouch columns recipe`:
-  `add_to_crm`, `sync_to_table`, `add_to_sequence`.
+- For provider-backed or generated columns, start with `autotouch columns recipe`.
+- Built-in recipe types now include `formatter`, `llm_enrichment`, `email_finder`, `phone_finder`, `lead_finder`, `add_to_crm`, `sync_to_table`, and `add_to_sequence`.
 - Email/phone enrichment does not require creating `add_to_crm` first.
 - `add_to_crm` is an optional, non-billable export action.
 
@@ -781,6 +781,7 @@ Notes:
 Add-to-Leads note: `companyDomain` is required; LinkedIn is optional. Each row still needs at least one usable hard identity signal (LinkedIn, email, or phone). Names and location fields are metadata only for this flow. Run is non-billable.
 If `companyDomain` is missing in the table, derive or enrich that domain column first, then rerun `add_to_crm`.
 Queued lifecycle: the CLI/API accepts the run immediately, then the backend hands off `ops -> data_io` for execution.
+Creating `add_to_crm` after upstream email/phone/lead columns already finished does not replay those older updates. In that case, run `add_to_crm` explicitly or rerun the upstream source column.
 
 CRM data model expectations (recommended before `add_to_crm`):
 - Lead identity/dedupe expects `company_domain` plus one usable hard identity signal. `linkedin_url` is a strong optional signal, not a requirement.
@@ -819,6 +820,14 @@ CRM data model expectations (recommended before `add_to_crm`):
 Notes:
 - Single-destination mode uses `destinationTableId` + `columnMappings`.
 - Router mode is also supported with `config.routes[]` (top-to-bottom matching, first hit wins, default route catches unmatched rows).
+- Route conditions are evaluated against the parent/source row, not against each list item.
+- `autoRun: "onSourceUpdate"` means dependency-driven runs from source row inserts/updates. Saving the column does not backfill existing rows for `sync_to_table`; use an explicit column run/backfill when needed.
+- List mode uses `syncMode: "list"` with `listSourceColumnId` and optional `listPath` (default `items`) to expand a canonical JSON payload like `{ "items": [...], "reasoning": "..." }`.
+- In list mode:
+  - `sourceScope: "item"` maps fields from each `items[]` object.
+  - `sourceScope: "row"` maps fields from the parent/source row.
+  - Explicit item mappings are still recommended for renamed fields such as `name -> full_name`.
+- Blank placeholder list items are skipped and do not create destination rows.
 
 ### 8) `add_to_sequence`
 
@@ -844,10 +853,33 @@ Notes:
 - `sourceLeadColumn` must be the source column key that stores lead IDs (for example `add_to_leads` or another lead-id column key from `lead_finder` output), not the provider name `add_to_crm`.
 - `sequenceId` is the target sequence workflow ID.
 - The target sequence must already be `ACTIVE` for real enrollment. Table `add_to_sequence` runs and direct `POST /api/sequences/{id}/enroll` share the same activation check.
+- Common tail order after contact rows or lead IDs exist is `email_finder -> add_to_crm -> create/activate sequence -> add_to_sequence`.
+- Creating `add_to_sequence` after lead IDs already exist does not replay those older updates. In that case, run `add_to_sequence` explicitly or rerun the lead-id source column.
 - `add_to_sequence` runs auto-attach `research_context.source_table_id` (and table name when available). Field selection stays implicit so sequence drafts/audience resolve favorites from current starred columns by default.
 - Star/favorite the highest-signal fields so callers can see them quickly in the sidecar during live call workflows.
 - The same favorite set is also the default AI drafting context when explicit `fieldIds` are not provided.
 
+## Example pipeline: LLM items -> contacts table -> leads -> sequence
+
+Use this when an LLM column returns canonical JSON like `{ "items": [...] }` and each item should become a contact row.
+This is an example pattern, not the default recommendation for all person discovery.
+Use `lead_finder` first when the goal is explicit buyer/lead discovery with clear role targeting at scale.
+Use agent `llm_enrichment` when the workflow needs custom research output, website-discovered contacts, or low-coverage / hard-to-find cases.
+
+1. Create the source table and import company rows.
+2. Create the LLM enrichment column that outputs `items[]`.
+3. Create `sync_to_table` in `list` mode:
+   - set `listSourceColumnId` to the LLM column ID
+   - keep item fields on `sourceScope: "item"`
+   - keep parent company metadata on `sourceScope: "row"`
+4. Run or wait for `sync_to_table` so the destination contacts table has rows.
+5. On the destination contacts table, create and run `email_finder`.
+6. Create `add_to_crm` on that same destination contacts table.
+7. If email finder already finished before `add_to_crm` existed, run `add_to_crm` explicitly.
+8. Create the target sequence and set it `ACTIVE`.
+9. Create `add_to_sequence` with `sourceLeadColumn` set to the lead-id column key, usually `add_to_leads`.
+10. If leads already existed before `add_to_sequence` was created, run `add_to_sequence` explicitly.
+
 ## Common workflow
 
 ```bash
@@ -1159,6 +1191,7 @@ Agent expectations:
 - `column_types` tells you which column types are runnable and which are non-billable transforms (`json_split`, `formatter_formula`).
 - `filtering` describes valid scope/filter semantics for estimate/run.
 - `automation.auto_run` describes supported auto-run modes + config field names.
+- `automation.providers` exposes provider-specific setup contracts, save-time backfill behavior, dispatch strategy, and recipe type names for formatter/LLM/finders/action columns.
 - `execution_policies.llm.output_contract` describes output behavior by mode:
   - `agent` => JSON-oriented structured output
   - `basic` => text or JSON (`dataType=json` for structured JSON output)

{autotouch_cli-0.2.31 → autotouch_cli-0.2.32}/autotouch_cli/cli.py

@@ -34,6 +34,10 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
 import requests
+from autotouch_shared.provider_registry import (
+    get_recipe_contract,
+    recipe_types,
+)
 
 try:
     from pymongo import MongoClient  # type: ignore
@@ -82,186 +86,24 @@ SETUP_BANNER = r"""
                          AI CLI SETUP
 """
 
-COLUMN_RECIPE_TYPES = [
-    "email_finder",
-    "phone_finder",
-    "lead_finder",
-    "llm_enrichment",
-    "add_to_crm",
-    "sync_to_table",
-    "add_to_sequence",
-]
+COLUMN_RECIPE_TYPES = recipe_types()
 
-COLUMN_CREATE_RECIPES: Dict[str, Dict[str, Any]] = {
-    "email_finder": {
-        "key": "work_email",
-        "label": "Work Email",
-        "kind": "enrichment",
-        "dataType": "json",
-        "origin": "email_finder",
-        "autoRun": "never",
-        "config": {
-            "provider": "smart_email_finder",
-            "strategy": "cost_optimized",
-            "lookupStrategy": "linkedin",
-            "linkedinOnly": True,
-            "enableProfileFallback": False,
-            "linkedinUrl": "linkedin_url",
-        },
-    },
-    "phone_finder": {
-        "key": "mobile_phone",
-        "label": "Mobile Phone",
-        "kind": "enrichment",
-        "dataType": "json",
-        "origin": "phone_finder",
-        "autoRun": "never",
-        "config": {
-            "provider": "smart_phone_finder",
-            "firstName": "first_name",
-            "lastName": "last_name",
-            "company": "company",
-            "linkedinUrl": "linkedin_url",
-        },
-    },
-    "lead_finder": {
-        "key": "lead_contacts",
-        "label": "Lead Contacts",
-        "kind": "enrichment",
-        "dataType": "json",
-        "origin": "ai",
-        "autoRun": "never",
-        "config": {
-            "provider": "lead_finder",
-            "sourceMode": "bulk_companies",
-            "companyDomain": "domain",
-            "strictness": "flexible_roles",
-            "storeAsLeads": True,
-            "autoEnrichEmails": True,
-            "autoEnrichPhones": False,
-            "jobTitles": ["Head of Sales", "VP Sales"],
-            "locations": ["United States"],
-            "maxResults": 10,
-        },
-    },
-    "llm_enrichment": {
-        "key": "company_research",
-        "label": "Company Research",
-        "kind": "enrichment",
-        "dataType": "json",
-        "origin": "ai",
-        "autoRun": "never",
-        "config": {
-            "instructions": "Research the company in this row and return JSON with icp_fit, summary, and risks.",
-            "mode": "agent",
-            "temperature": 0.7,
-            "batchSize": 50,
-            "promptSource": "generated",
-            "useCompanyContext": True,
-            "structuredOutput": True,
-            "useAutoSchema": True,
-        },
-    },
-    "add_to_crm": {
-        "key": "add_to_leads",
-        "label": "Add to Leads",
-        "kind": "enrichment",
-        "dataType": "json",
-        "origin": "manual",
-        "autoRun": "onSourceUpdate",
-        "config": {
-            "provider": "add_to_crm",
-            "leadSource": "research_table_export",
-            "fieldMappings": {
-                "mode": "single",
-                "linkedinUrl": "linkedin_url",
-                "companyDomain": "domain",
-                "firstName": "first_name",
-                "lastName": "last_name",
-                "title": "title",
-                "companyName": "company",
-                "emailAddresses": [{"column": "work_email", "type": "work"}],
-                "phoneNumbers": [{"column": "mobile_phone", "type": "mobile"}],
-            },
-            "sourceColumns": [
-                "linkedin_url",
-                "domain",
-                "first_name",
-                "last_name",
-                "title",
-                "company",
-                "work_email",
-                "mobile_phone",
-            ],
-        },
-    },
-    "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]] = {
-    "email_finder": [
-        "For non-LinkedIn lookup, use lookupStrategy=domain/company with firstName+lastName+domain/company fields.",
-    ],
-    "phone_finder": [
-        "You can use linkedinUrl or email/workEmail/personalEmail inputs.",
-    ],
-    "lead_finder": [
-        "Add more targeting keys as needed (jobFunctions, seniorities, keywords, excludeKeywords, skills).",
-    ],
-    "llm_enrichment": [
-        "Recommended default for agent mode: provide instructions and let the API compile the runnable prompt.",
-        "Generated agent-mode prompts always include company/requester context.",
-        "Basic mode stays manual-prompt-first; write the prompt directly from the user goal/preferences.",
-        "Runtime only injects values for placeholders the prompt explicitly references.",
-        "Manual/basic prompts should use explicit placeholders like {{company_name}}, {{domain}}, or {{user_value_proposition}} when those values are needed.",
-        "Agent mode is JSON-oriented.",
-        "Basic mode can be text or JSON; JSON requires dataType=json.",
-    ],
-    "add_to_crm": [
-        "companyDomain is required; LinkedIn is optional.",
-        "Include at least one usable hard-identity mapping such as LinkedIn, email, or phone.",
-        "If companyDomain is missing in the table, derive or enrich that domain column first.",
-        "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 the source column key that stores lead IDs (for example add_to_leads), not the provider name add_to_crm.",
-        "Set sequenceId to the target workflow sequence ID.",
-        "The target sequence must already be ACTIVE for real enrollment.",
-    ],
-}
+def _build_column_recipe_catalog() -> Tuple[Dict[str, Dict[str, Any]], Dict[str, List[str]]]:
+    recipes: Dict[str, Dict[str, Any]] = {}
+    notes: Dict[str, List[str]] = {}
+    for recipe_type in COLUMN_RECIPE_TYPES:
+        contract = get_recipe_contract(recipe_type)
+        if not contract:
+            continue
+        payload = contract.recipe_payload_copy()
+        if isinstance(payload, dict):
+            recipes[recipe_type] = payload
+        notes[recipe_type] = contract.recipe_notes_list()
+    return recipes, notes
+
+
+COLUMN_CREATE_RECIPES, COLUMN_RECIPE_NOTES = _build_column_recipe_catalog()
 
 SEQUENCE_RECIPE_TYPES = [
     "create",
@@ -3589,6 +3431,8 @@ def cmd_capabilities(args: argparse.Namespace) -> None:
         output_contract = llm.get("output_contract") if isinstance(llm.get("output_contract"), dict) else {}
         agent_contract = output_contract.get("agent") if isinstance(output_contract.get("agent"), dict) else {}
         basic_contract = output_contract.get("basic") if isinstance(output_contract.get("basic"), dict) else {}
+        automation = data.get("automation") if isinstance(data.get("automation"), dict) else {}
+        providers = automation.get("providers") if isinstance(automation.get("providers"), dict) else {}
 
         print(f"API version : {_as_display(data.get('api_version'))}")
         print(f"Base URL    : {_as_display(data.get('base_url'))}")
@@ -3612,7 +3456,13 @@ def cmd_capabilities(args: argparse.Namespace) -> None:
         basic_types = basic_contract.get("supported_data_types")
         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)")
+        if providers:
+            print("")
+            print("Provider setup")
+            print("--------------")
+            print(", ".join(sorted(str(name) for name in providers.keys())))
         print("")
+        print("Tip: inspect automation.providers in JSON output for provider-specific setup contracts.")
         print("Tip: for JSON enrichment columns, run with `--wait` and verify terminal status before `autotouch columns projections`.")
         return
 

autotouch_cli-0.2.31/docs/research-table/reference/autotouch-cli.md → autotouch_cli-0.2.32/autotouch_cli.egg-info/PKG-INFO

@@ -1,3 +1,12 @@
+Metadata-Version: 2.4
+Name: autotouch-cli
+Version: 0.2.32
+Summary: Autotouch Smart Table CLI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+
 # Autotouch CLI Reference (`autotouch`)
 
 This page documents the installable CLI for the Smart Table developer API.
@@ -506,8 +515,8 @@ autotouch columns create --table-id <TABLE_ID> --data-file <payload.json>
 ```
 
 Recommendation:
-- For provider-backed workflow columns, start with `autotouch columns recipe`:
-  `add_to_crm`, `sync_to_table`, `add_to_sequence`.
+- For provider-backed or generated columns, start with `autotouch columns recipe`.
+- Built-in recipe types now include `formatter`, `llm_enrichment`, `email_finder`, `phone_finder`, `lead_finder`, `add_to_crm`, `sync_to_table`, and `add_to_sequence`.
 - Email/phone enrichment does not require creating `add_to_crm` first.
 - `add_to_crm` is an optional, non-billable export action.
 
@@ -772,6 +781,7 @@ Notes:
 Add-to-Leads note: `companyDomain` is required; LinkedIn is optional. Each row still needs at least one usable hard identity signal (LinkedIn, email, or phone). Names and location fields are metadata only for this flow. Run is non-billable.
 If `companyDomain` is missing in the table, derive or enrich that domain column first, then rerun `add_to_crm`.
 Queued lifecycle: the CLI/API accepts the run immediately, then the backend hands off `ops -> data_io` for execution.
+Creating `add_to_crm` after upstream email/phone/lead columns already finished does not replay those older updates. In that case, run `add_to_crm` explicitly or rerun the upstream source column.
 
 CRM data model expectations (recommended before `add_to_crm`):
 - Lead identity/dedupe expects `company_domain` plus one usable hard identity signal. `linkedin_url` is a strong optional signal, not a requirement.
@@ -810,6 +820,14 @@ CRM data model expectations (recommended before `add_to_crm`):
 Notes:
 - Single-destination mode uses `destinationTableId` + `columnMappings`.
 - Router mode is also supported with `config.routes[]` (top-to-bottom matching, first hit wins, default route catches unmatched rows).
+- Route conditions are evaluated against the parent/source row, not against each list item.
+- `autoRun: "onSourceUpdate"` means dependency-driven runs from source row inserts/updates. Saving the column does not backfill existing rows for `sync_to_table`; use an explicit column run/backfill when needed.
+- List mode uses `syncMode: "list"` with `listSourceColumnId` and optional `listPath` (default `items`) to expand a canonical JSON payload like `{ "items": [...], "reasoning": "..." }`.
+- In list mode:
+  - `sourceScope: "item"` maps fields from each `items[]` object.
+  - `sourceScope: "row"` maps fields from the parent/source row.
+  - Explicit item mappings are still recommended for renamed fields such as `name -> full_name`.
+- Blank placeholder list items are skipped and do not create destination rows.
 
 ### 8) `add_to_sequence`
 
@@ -835,10 +853,33 @@ Notes:
 - `sourceLeadColumn` must be the source column key that stores lead IDs (for example `add_to_leads` or another lead-id column key from `lead_finder` output), not the provider name `add_to_crm`.
 - `sequenceId` is the target sequence workflow ID.
 - The target sequence must already be `ACTIVE` for real enrollment. Table `add_to_sequence` runs and direct `POST /api/sequences/{id}/enroll` share the same activation check.
+- Common tail order after contact rows or lead IDs exist is `email_finder -> add_to_crm -> create/activate sequence -> add_to_sequence`.
+- Creating `add_to_sequence` after lead IDs already exist does not replay those older updates. In that case, run `add_to_sequence` explicitly or rerun the lead-id source column.
 - `add_to_sequence` runs auto-attach `research_context.source_table_id` (and table name when available). Field selection stays implicit so sequence drafts/audience resolve favorites from current starred columns by default.
 - Star/favorite the highest-signal fields so callers can see them quickly in the sidecar during live call workflows.
 - The same favorite set is also the default AI drafting context when explicit `fieldIds` are not provided.
 
+## Example pipeline: LLM items -> contacts table -> leads -> sequence
+
+Use this when an LLM column returns canonical JSON like `{ "items": [...] }` and each item should become a contact row.
+This is an example pattern, not the default recommendation for all person discovery.
+Use `lead_finder` first when the goal is explicit buyer/lead discovery with clear role targeting at scale.
+Use agent `llm_enrichment` when the workflow needs custom research output, website-discovered contacts, or low-coverage / hard-to-find cases.
+
+1. Create the source table and import company rows.
+2. Create the LLM enrichment column that outputs `items[]`.
+3. Create `sync_to_table` in `list` mode:
+   - set `listSourceColumnId` to the LLM column ID
+   - keep item fields on `sourceScope: "item"`
+   - keep parent company metadata on `sourceScope: "row"`
+4. Run or wait for `sync_to_table` so the destination contacts table has rows.
+5. On the destination contacts table, create and run `email_finder`.
+6. Create `add_to_crm` on that same destination contacts table.
+7. If email finder already finished before `add_to_crm` existed, run `add_to_crm` explicitly.
+8. Create the target sequence and set it `ACTIVE`.
+9. Create `add_to_sequence` with `sourceLeadColumn` set to the lead-id column key, usually `add_to_leads`.
+10. If leads already existed before `add_to_sequence` was created, run `add_to_sequence` explicitly.
+
 ## Common workflow
 
 ```bash
@@ -1150,6 +1191,7 @@ Agent expectations:
 - `column_types` tells you which column types are runnable and which are non-billable transforms (`json_split`, `formatter_formula`).
 - `filtering` describes valid scope/filter semantics for estimate/run.
 - `automation.auto_run` describes supported auto-run modes + config field names.
+- `automation.providers` exposes provider-specific setup contracts, save-time backfill behavior, dispatch strategy, and recipe type names for formatter/LLM/finders/action columns.
 - `execution_policies.llm.output_contract` describes output behavior by mode:
   - `agent` => JSON-oriented structured output
   - `basic` => text or JSON (`dataType=json` for structured JSON output)

{autotouch_cli-0.2.31 → autotouch_cli-0.2.32}/autotouch_cli.egg-info/SOURCES.txt

@@ -7,6 +7,8 @@ autotouch_cli.egg-info/dependency_links.txt
 autotouch_cli.egg-info/entry_points.txt
 autotouch_cli.egg-info/requires.txt
 autotouch_cli.egg-info/top_level.txt
+autotouch_shared/__init__.py
+autotouch_shared/provider_registry.py
 docs/research-table/reference/autotouch-cli.md
 tests/test_column_prompt_compiler.py
 tests/test_contactout_custom.py

autotouch_cli-0.2.32/autotouch_cli.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+autotouch_cli
+autotouch_shared

autotouch_cli-0.2.32/autotouch_shared/__init__.py

@@ -0,0 +1 @@
+"""Shared Autotouch contracts and metadata."""