autotouch-cli 0.2.59__tar.gz → 0.2.61__tar.gz

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.59
+Version: 0.2.61
 Summary: Autotouch Smart Table CLI
 Project-URL: Homepage, https://app.autotouch.ai
 Project-URL: Documentation, https://github.com/nicolonic/autotouch_main/tree/main/docs/research-table/reference

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/autotouch_cli/commands/columns.py

@@ -379,7 +379,22 @@ def register_columns_subcommands(
     add_api_common_arguments(pcl)
     pcl.set_defaults(func=handlers["list"])
 
-    pcc = col_sub.add_parser("create", help="Create a column")
+    pcc = col_sub.add_parser(
+        "create",
+        help="Create a column",
+        description=(
+            "Create a column from a ColumnCreate payload.\n"
+            "For llm_enrichment, there are two valid authoring paths:\n"
+            "- generated path: send config.instructions and let the API compile config.advancedPrompt\n"
+            "- manual path: send config.advancedPrompt directly when you want exact prompt control"
+        ),
+        epilog=(
+            "Recommended flow for llm_enrichment:\n\n"
+            "autotouch columns recipe --type llm_enrichment --output human\n\n"
+            "The runnable prompt is always config.advancedPrompt before execution."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     pcc.add_argument("--table-id", required=True)
     pcc.add_argument("--data-json", help="ColumnCreate payload JSON")
     pcc.add_argument("--data-file", help="ColumnCreate payload file path")

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/autotouch_cli/core/validation.py

@@ -55,8 +55,18 @@ def extract_add_to_crm_field_mappings(payload: Any) -> Optional[Dict[str, Any]]:
     return {}
 
 
-def inspect_add_to_crm_field_mappings(field_mappings: Dict[str, Any]) -> Dict[str, Any]:
-    mode = "multi" if str(field_mappings.get("mode") or "").strip().lower() == "multi" else "single"
+def inspect_add_to_crm_field_mappings(
+    field_mappings: Dict[str, Any],
+    *,
+    require_company_domain: bool = True,
+) -> Dict[str, Any]:
+    raw_mode = str(field_mappings.get("mode") or "").strip().lower()
+    if raw_mode == "array":
+        mode = "array"
+    elif raw_mode == "multi":
+        mode = "multi"
+    else:
+        mode = "single"
     required_missing: List[str] = []
     optional_missing: List[str] = []
 
@@ -75,12 +85,20 @@ def inspect_add_to_crm_field_mappings(field_mappings: Dict[str, Any]) -> Dict[st
             return True
         return False
 
+    if not require_company_domain and mode != "single":
+        required_missing.append("singleModeOnlyWhenCompanyDomainOptional")
+        return {
+            "mode": mode,
+            "required_missing": required_missing,
+            "optional_missing": optional_missing,
+        }
+
     if mode == "multi":
         common = field_mappings.get("common") if isinstance(field_mappings.get("common"), dict) else {}
         leads = field_mappings.get("leads") if isinstance(field_mappings.get("leads"), list) else []
 
         common_domain = str((common or {}).get("companyDomain") or field_mappings.get("companyDomain") or "").strip()
-        if not common_domain:
+        if require_company_domain and not common_domain:
             required_missing.append("common.companyDomain")
 
         has_lead_identity = False
@@ -95,10 +113,24 @@ def inspect_add_to_crm_field_mappings(field_mappings: Dict[str, Any]) -> Dict[st
                     optional_missing.append(f"leads[{idx}].{slot}")
         if not has_lead_identity:
             required_missing.append("leads[].identityFields")
+    elif mode == "array":
+        common = field_mappings.get("common") if isinstance(field_mappings.get("common"), dict) else {}
+        template = field_mappings.get("template") if isinstance(field_mappings.get("template"), dict) else {}
+        if require_company_domain and not str((common or {}).get("companyDomain") or "").strip():
+            required_missing.append("common.companyDomain")
+        if not str(field_mappings.get("sourceColumn") or "").strip():
+            required_missing.append("sourceColumn")
+        if not _has_identity_mapping(template):
+            required_missing.append("template.identityFields")
     else:
         company_domain_key = str(field_mappings.get("companyDomain") or "").strip()
-        if not company_domain_key:
+        if require_company_domain and not company_domain_key:
             required_missing.append("companyDomain")
+        if require_company_domain:
+            if not _has_identity_mapping(field_mappings):
+                required_missing.append("identityFields")
+        elif not str(field_mappings.get("linkedinUrl") or "").strip():
+            required_missing.append("linkedinUrl")
         if not _has_identity_mapping(field_mappings):
             required_missing.append("identityFields")
         for slot in ["firstName", "lastName", "title", "companyName"]:
@@ -116,6 +148,7 @@ def validate_add_to_crm_create_payload(payload: Dict[str, Any]) -> None:
     field_mappings = extract_add_to_crm_field_mappings(payload)
     if field_mappings is None:
         return
+    config = payload.get("config") if isinstance(payload.get("config"), dict) else {}
 
     kind_value = str(payload.get("kind") or "").strip().lower()
     if kind_value != "enrichment":
@@ -130,10 +163,24 @@ def validate_add_to_crm_create_payload(payload: Dict[str, Any]) -> None:
             "Tip: run `autotouch columns recipe --type add_to_crm`."
         )
 
-    issues = inspect_add_to_crm_field_mappings(field_mappings)
+    require_company_domain = config.get("requireCompanyDomain", True)
+    if not isinstance(require_company_domain, bool):
+        raise AutotouchInputError(
+            "add_to_crm config.requireCompanyDomain must be a boolean when provided."
+        )
+
+    issues = inspect_add_to_crm_field_mappings(
+        field_mappings,
+        require_company_domain=require_company_domain,
+    )
     required_missing = issues.get("required_missing") or []
     optional_missing = issues.get("optional_missing") or []
     if required_missing:
+        if "singleModeOnlyWhenCompanyDomainOptional" in required_missing:
+            raise AutotouchInputError(
+                "add_to_crm with config.requireCompanyDomain=false only supports single-mode fieldMappings. "
+                "Tip: map config.fieldMappings.linkedinUrl and keep mode='single' for LinkedIn-First Sync to Leads."
+            )
         missing = ", ".join(str(v) for v in required_missing)
         raise AutotouchInputError(
             f"add_to_crm fieldMappings missing required keys: {missing}. "
@@ -301,11 +348,20 @@ def run_precheck_for_add_to_crm(
     if field_mappings is None:
         return
 
-    issues = inspect_add_to_crm_field_mappings(field_mappings)
+    config = column.get("config") if isinstance(column.get("config"), dict) else {}
+    require_company_domain = config.get("requireCompanyDomain", True)
+    issues = inspect_add_to_crm_field_mappings(
+        field_mappings,
+        require_company_domain=bool(require_company_domain) if isinstance(require_company_domain, bool) else True,
+    )
     required_missing = issues.get("required_missing") or []
     optional_missing = issues.get("optional_missing") or []
 
     if required_missing:
+        if "singleModeOnlyWhenCompanyDomainOptional" in required_missing:
+            raise AutotouchInputError(
+                "add_to_crm column is misconfigured: config.requireCompanyDomain=false only supports single-mode fieldMappings for LinkedIn-First Sync to Leads."
+            )
         missing = ", ".join(str(v) for v in required_missing)
         raise AutotouchInputError(
             f"add_to_crm column is misconfigured (missing required mappings: {missing}). "

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/autotouch_cli/data/CLI_REFERENCE.md

@@ -1,6 +1,6 @@
 # Autotouch CLI Reference
 
-Generated from the installed parser for `autotouch-cli` `0.2.59`.
+Generated from the installed parser for `autotouch-cli` `0.2.61`.
 Manifest schema version: `2`.
 
 ## Output Modes
@@ -653,6 +653,11 @@ Column operations
 
 Create a column
 
+Create a column from a ColumnCreate payload.
+For llm_enrichment, there are two valid authoring paths:
+- generated path: send config.instructions and let the API compile config.advancedPrompt
+- manual path: send config.advancedPrompt directly when you want exact prompt control
+
 - Auth: `developer_key_or_user_session`
 - Stability: `stable`
 - Destructive: `no`
@@ -669,6 +674,15 @@ Create a column
                                 [--output {json,ndjson,human}] [--compact]
                                 [--select SELECT |
                                 --json-pointer JSON_POINTER] [--verbose]`
+- Notes:
+
+```text
+Recommended flow for llm_enrichment:
+
+autotouch columns recipe --type llm_enrichment --output human
+
+The runnable prompt is always config.advancedPrompt before execution.
+```
 - Options:
   - `--table-id` (required; kind=string)
   - `--data-json` (kind=json; input=json): ColumnCreate payload JSON

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/autotouch_cli/data/cli-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.59",
+  "version": "0.2.61",
   "manifest_schema_version": 2,
   "entry_points": {
     "autotouch": "autotouch_cli.cli:main",
@@ -14777,8 +14777,8 @@
       "aliases": [],
       "group": "columns",
       "help": "Create a column",
-      "description": null,
-      "notes": null,
+      "description": "Create a column from a ColumnCreate payload.\nFor llm_enrichment, there are two valid authoring paths:\n- generated path: send config.instructions and let the API compile config.advancedPrompt\n- manual path: send config.advancedPrompt directly when you want exact prompt control",
+      "notes": "Recommended flow for llm_enrichment:\n\nautotouch columns recipe --type llm_enrichment --output human\n\nThe runnable prompt is always config.advancedPrompt before execution.",
       "required_flags": [
         "--table-id"
       ],

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/autotouch_cli/templates.py

@@ -35,11 +35,11 @@ COLUMN_RECIPE_BASE_TYPES = tuple(recipe_types())
 COLUMN_RECIPE_ALIASES: Dict[str, Dict[str, Any]] = {
     "add_to_leads": {
         "canonical": "add_to_crm",
-        "key": "add_to_leads",
-        "label": "Add to Leads",
+        "key": "sync_to_leads",
+        "label": "Sync to Leads",
         "notes": [
-            "CLI alias for the canonical add_to_crm provider recipe.",
-            "Use this when the operator language is 'Add to Leads'. Internal provider/config names remain add_to_crm.",
+            "Legacy CLI alias for the canonical add_to_crm provider recipe.",
+            "Emits the standard Sync to Leads payload. Internal provider/config names remain add_to_crm.",
         ],
     },
     "sync_to_leads": {
@@ -47,8 +47,8 @@ COLUMN_RECIPE_ALIASES: Dict[str, Dict[str, Any]] = {
         "key": "sync_to_leads",
         "label": "Sync to Leads",
         "notes": [
-            "CLI alias for the canonical add_to_crm provider recipe.",
-            "Use this when the operator language is 'Sync to Leads'. Internal provider/config names remain add_to_crm.",
+            "Preferred CLI alias for the canonical add_to_crm provider recipe.",
+            "Emits the standard Sync to Leads payload. Internal provider/config names remain add_to_crm.",
         ],
     },
 }

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.59
+Version: 0.2.61
 Summary: Autotouch Smart Table CLI
 Project-URL: Homepage, https://app.autotouch.ai
 Project-URL: Documentation, https://github.com/nicolonic/autotouch_main/tree/main/docs/research-table/reference

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/autotouch_shared/provider_registry.py

@@ -158,6 +158,14 @@ def _mapping_text(value: Any) -> str:
     return _text(value)
 
 
+def _llm_advanced_prompt_text(config: Dict[str, Any]) -> str:
+    return (
+        _text(config.get("advancedPrompt"))
+        or _text(config.get("advanced_prompt"))
+        or _text(config.get("prompt"))
+    )
+
+
 def _llm_provider_values() -> Tuple[str, ...]:
     return ("llm", "gemini", "xai", "openai", "anthropic", "groq")
 
@@ -378,13 +386,14 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             },
         },
         recipe_notes=(
-            "Recommended default for agent mode: provide instructions and let the API compile the runnable prompt.",
+            "The runnable prompt is always config.advancedPrompt before execution.",
+            "Generated path: provide instructions and let the API compile config.advancedPrompt for you.",
+            "Manual path: write config.advancedPrompt directly when you want exact control over the final prompt.",
             "When the platform generates the runnable prompt from instructions, keep useAutoSchema=true unless you intentionally want to own the schema yourself.",
             "Do not send user_schema/response_schema in that default generated-prompt path; prompt/schema drift is possible if you later change the generated prompt but keep a frozen custom schema.",
             "Basic is for extraction, scoring, or classification using fields already in the row. Agent is for tasks that may need outside lookup or web research.",
             "Create/update always materializes the runnable prompt into config.advancedPrompt before execution.",
             "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.",
@@ -746,20 +755,21 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
     ),
     ResearchTableProviderContract(
         key="add_to_crm",
-        display_name="Add to Leads",
+        display_name="Sync to Leads",
         kind="enrichment",
         behavior_class="action_enrichment",
         provider_aliases=("add_to_crm",),
         recipe_type="add_to_crm",
         recipe_payload={
-            "key": "add_to_leads",
-            "label": "Add to Leads",
+            "key": "sync_to_leads",
+            "label": "Sync to Leads",
             "kind": "enrichment",
             "dataType": "json",
             "origin": "manual",
             "autoRun": "onSourceUpdate",
             "config": {
                 "provider": "add_to_crm",
+                "requireCompanyDomain": True,
                 "leadSource": "research_table_export",
                 "fieldMappings": {
                     "mode": "single",
@@ -786,18 +796,19 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         },
         recipe_notes=(
             "companyDomain is required; LinkedIn is optional.",
+            "Set `config.requireCompanyDomain=false` only for single-mode LinkedIn-first syncs. In that relaxed mode, `linkedinUrl` becomes required and multi/array mode stays unsupported.",
             "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.",
             "Primitive source columns map directly. If a mapped source column stores structured JSON, send an object with column + path, for example {\"column\": \"work_email\", \"path\": \"response\"} or {\"column\": \"mobile_phone\", \"path\": \"mobile_number\"}.",
             "For firstName and lastName, prefer authoritative structured source fields when available, for example {\"column\": \"linkedin_profile_lookup_raw\", \"path\": \"first_name\"} and {\"column\": \"linkedin_profile_lookup_raw\", \"path\": \"last_name\"}. Avoid mapping a combined full-name column directly unless that is an intentional fallback and you accept imperfect CRM data.",
-            "Add to CRM is optional and non-billable.",
-            "Creating add_to_crm after upstream email/phone/lead columns already finished does not replay those older source updates; run add_to_crm explicitly or rerun the upstream source column.",
+            "Sync to Leads is non-billable.",
+            "Creating Sync to Leads (`add_to_crm`) after upstream email/phone/lead columns already finished does not replay those older source updates; run Sync to Leads explicitly or rerun the upstream source column.",
         ),
         column_type={
             "type": "add_to_crm",
             "kind": "enrichment",
             "runnable": True,
-            "description": "Add eligible mapped rows into Leads CRM from research-table data.",
+            "description": "Sync eligible mapped rows into Leads from research-table data.",
             "requirements": {
                 "config_provider": "add_to_crm",
                 "field_mappings": "required",
@@ -806,7 +817,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             "billing": {
                 "billable": False,
                 "credits": 0,
-                "notes": "Add to Leads export does not consume credits.",
+                "notes": "Sync to Leads does not consume credits.",
             },
         },
         setup_contract={
@@ -971,14 +982,14 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             "config": {
                 "provider": "add_to_sequence",
                 "sequenceId": "<SEQUENCE_ID>",
-                "sourceLeadColumn": "add_to_leads",
+                "sourceLeadColumn": "sync_to_leads",
             },
         },
         recipe_notes=(
-            "sourceLeadColumn should reference the source column key that stores lead IDs (for example add_to_leads), not the provider name add_to_crm.",
+            "sourceLeadColumn should reference the source column key that stores lead IDs (for example sync_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.",
-            "Common tail order after contact rows or lead IDs exist is email_finder -> add_to_crm -> create/activate sequence -> add_to_sequence.",
+            "Common tail order after contact rows or lead IDs exist is email_finder -> Sync to Leads (`add_to_crm`) -> create/activate sequence -> add_to_sequence.",
             "Creating add_to_sequence after lead IDs already exist does not replay those older updates; run add_to_sequence explicitly or rerun the lead-id source column.",
         ),
         column_type={
@@ -1355,6 +1366,38 @@ def validate_column_provider_contract(
             )
         return contract
 
+    if contract.key == "llm":
+        prompt_source = _normalize(cfg.get("promptSource") or cfg.get("prompt_source"))
+        instructions = _text(cfg.get("instructions"))
+        advanced_prompt = _llm_advanced_prompt_text(cfg)
+
+        if prompt_source == "generated":
+            if not instructions:
+                raise ProviderContractValidationError(
+                    "missing_required_field",
+                    "Generated LLM prompt mode requires config.instructions.",
+                    hint="Use instructions for shorthand/high-level intent, or switch to config.promptSource='manual' and write config.advancedPrompt directly.",
+                )
+            return contract
+
+        if prompt_source == "manual":
+            if not advanced_prompt:
+                raise ProviderContractValidationError(
+                    "missing_required_field",
+                    "Manual LLM prompt mode requires config.advancedPrompt.",
+                    hint="Write config.advancedPrompt directly, or remove config.promptSource and supply config.instructions for the generated path.",
+                )
+            return contract
+
+        if instructions or advanced_prompt:
+            return contract
+
+        raise ProviderContractValidationError(
+            "missing_required_field",
+            "LLM enrichment columns require either config.instructions or config.advancedPrompt.",
+            hint="Use instructions for the generated path or write config.advancedPrompt directly for the manual path.",
+        )
+
     if contract.key == "add_to_sequence":
         if not _text(cfg.get("sequenceId")):
             raise ProviderContractValidationError(
@@ -1366,7 +1409,7 @@ def validate_column_provider_contract(
             raise ProviderContractValidationError(
                 "missing_required_field",
                 "add_to_sequence requires config.sourceLeadColumn.",
-                hint="Set sourceLeadColumn to the column key that stores lead IDs, usually add_to_leads.",
+                hint="Set sourceLeadColumn to the column key that stores lead IDs, usually sync_to_leads.",
             )
         return contract
 
@@ -1378,6 +1421,29 @@ def validate_column_provider_contract(
                 "add_to_crm requires config.fieldMappings.",
                 hint="Use `autotouch columns recipe --type add_to_crm`.",
             )
+        require_company_domain = cfg.get("requireCompanyDomain", True)
+        if not isinstance(require_company_domain, bool):
+            raise ProviderContractValidationError(
+                "invalid_field",
+                "add_to_crm config.requireCompanyDomain must be a boolean when provided.",
+                hint="Use true for the default strict mode or false for single-mode LinkedIn-first sync.",
+                detail={"requireCompanyDomain": require_company_domain},
+            )
+        if require_company_domain is False:
+            mode = _normalize(field_mappings.get("mode")) or "single"
+            if mode in {"multi", "array"}:
+                raise ProviderContractValidationError(
+                    "invalid_field",
+                    "add_to_crm config.requireCompanyDomain=false only supports single-mode fieldMappings.",
+                    hint="Use single-mode sync_to_leads with config.fieldMappings.linkedinUrl when companyDomain is optional.",
+                    detail={"mode": field_mappings.get("mode")},
+                )
+            if not _mapping_text(field_mappings.get("linkedinUrl")):
+                raise ProviderContractValidationError(
+                    "missing_required_field",
+                    "add_to_crm with config.requireCompanyDomain=false requires config.fieldMappings.linkedinUrl.",
+                    hint="Map a LinkedIn profile URL column when using LinkedIn-first sync_to_leads.",
+                )
         return contract
 
     if contract.key == "sync_to_table":

{autotouch_cli-0.2.59 → autotouch_cli-0.2.61}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "autotouch-cli"
-version = "0.2.59"
+version = "0.2.61"
 description = "Autotouch Smart Table CLI"
 readme = "README.md"
 requires-python = ">=3.9"