autotouch-cli 0.2.46__tar.gz → 0.2.48__tar.gz

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.46
+Version: 0.2.48
 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
@@ -146,9 +146,18 @@ For automation or agent-driven setup, use:
 - `autotouch sequences ...` and `autotouch tasks ...` for sequence/task workflows
 - `pip install 'autotouch-cli[mongo]'` if you need the Mongo-backed `status` / `watch` commands
 
+## LLM Columns
+
+For `llm_enrichment` in `agent` mode, the recommended path is:
+- provide `config.instructions`
+- let the API compile the runnable prompt
+- keep `config.useAutoSchema = true`
+
+Only send `user_schema` / `response_schema` when you intentionally want to override the generated schema and keep it aligned yourself. The installed recipe surface at `autotouch columns recipe --type llm_enrichment` follows this contract.
+
 ## Docs
 
-- Full CLI reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/reference/autotouch-cli.md
-- Agent playbook: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/guides/autotouch-cli-agent-playbook.md
-- Tables/API reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/reference/tables-api.md
-- Authentication/scopes: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/platform/authentication.md
+- Full CLI reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/reference/autotouch-cli.md
+- Agent playbook: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/guides/autotouch-cli-agent-playbook.md
+- Tables/API reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/reference/tables-api.md
+- Authentication/scopes: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/platform/authentication.md

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/README.md

@@ -121,9 +121,18 @@ For automation or agent-driven setup, use:
 - `autotouch sequences ...` and `autotouch tasks ...` for sequence/task workflows
 - `pip install 'autotouch-cli[mongo]'` if you need the Mongo-backed `status` / `watch` commands
 
+## LLM Columns
+
+For `llm_enrichment` in `agent` mode, the recommended path is:
+- provide `config.instructions`
+- let the API compile the runnable prompt
+- keep `config.useAutoSchema = true`
+
+Only send `user_schema` / `response_schema` when you intentionally want to override the generated schema and keep it aligned yourself. The installed recipe surface at `autotouch columns recipe --type llm_enrichment` follows this contract.
+
 ## Docs
 
-- Full CLI reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/reference/autotouch-cli.md
-- Agent playbook: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/guides/autotouch-cli-agent-playbook.md
-- Tables/API reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/reference/tables-api.md
-- Authentication/scopes: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/platform/authentication.md
+- Full CLI reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/reference/autotouch-cli.md
+- Agent playbook: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/guides/autotouch-cli-agent-playbook.md
+- Tables/API reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/reference/tables-api.md
+- Authentication/scopes: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/platform/authentication.md

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_cli/cli.py

@@ -1091,8 +1091,7 @@ def _normalize_run_payload(args: argparse.Namespace) -> Dict[str, Any]:
     if filters is not None:
         payload["filters"] = filters
 
-    if getattr(args, "unprocessed_only", False):
-        payload["unprocessedOnly"] = True
+    payload["unprocessedOnly"] = bool(getattr(args, "unprocessed_only", True))
 
     return payload
 
@@ -3559,11 +3558,20 @@ def _add_run_scope_arguments(parser: argparse.ArgumentParser) -> None:
         type=int,
         help="First N rows (for scope=firstN). Use with --unprocessed-only to process the next rows without reruns",
     )
-    parser.add_argument(
+    run_mode = parser.add_mutually_exclusive_group()
+    run_mode.add_argument(
         "--unprocessed-only",
+        dest="unprocessed_only",
         action="store_true",
-        help="Only process rows without values (recommended with scope=firstN)",
+        help="Only process rows without values (default)",
+    )
+    run_mode.add_argument(
+        "--include-processed",
+        dest="unprocessed_only",
+        action="store_false",
+        help="Include rows that already have output",
     )
+    parser.set_defaults(unprocessed_only=True)
     parser.add_argument("--filters-json", help="JSON object for scope=filtered")
     parser.add_argument("--filters-file", help="Path to JSON file for scope=filtered")
     parser.add_argument("--data-json", help="Explicit RunRequest payload JSON (overrides scope flags)")

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_cli/commands/auth.py

@@ -30,19 +30,16 @@ def cmd_auth_check(args: argparse.Namespace, *, runtime: AuthCommandRuntime) ->
     token = runtime.resolve_token(args.token, required=True)
     body = runtime.request_api(
         "GET",
-        "/api/capabilities",
+        "/api/auth/check",
         base_url=args.base_url,
         token=token,
         use_x_api_key=args.use_x_api_key,
         timeout=args.timeout,
         verbose=args.verbose,
     )
-    output = {
-        "ok": True,
-        "base_url": runtime.api_url(args.base_url),
-        "api_version": body.get("api_version") if isinstance(body, dict) else None,
-        "auth_header_mode": "x-api-key" if args.use_x_api_key else "authorization",
-    }
+    output = dict(body) if isinstance(body, dict) else {"ok": True}
+    output["base_url"] = runtime.api_url(args.base_url)
+    output["auth_header_mode"] = "x-api-key" if args.use_x_api_key else "authorization"
     runtime.print_json(output, args.compact)
 
 
@@ -363,7 +360,11 @@ def register_auth_subcommands(
     auth = subparsers.add_parser("auth", help="Auth helpers")
     auth_sub = auth.add_subparsers(dest="auth_cmd", required=True)
 
-    pa = auth_sub.add_parser("check", help="Validate token against /api/capabilities")
+    pa = auth_sub.add_parser(
+        "check",
+        help="Validate the current token/session and show granted scopes",
+        description="Validate the current token/session against the API and show granted scopes for developer API keys.",
+    )
     add_api_common_arguments(pa)
     pa.set_defaults(func=handlers["check"])
 

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_cli/commands/cells.py

@@ -85,7 +85,11 @@ def register_cells_subcommands(
     add_api_common_arguments(get_parser)
     get_parser.set_defaults(func=handlers["get"])
 
-    patch_parser = cells_sub.add_parser("patch", help="Patch cells in batch")
+    patch_parser = cells_sub.add_parser(
+        "patch",
+        help="Patch cells in batch",
+        description="Patch cells in batch. Use column key strings in updates[].key; this payload does not accept columnId.",
+    )
     patch_parser.add_argument("--table-id", required=True)
     patch_parser.add_argument("--updates-json", help="JSON list or {updates:[...]} object")
     patch_parser.add_argument("--updates-file", help="Path to JSON file with updates payload")

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_cli/commands/columns.py

@@ -273,9 +273,11 @@ def cmd_columns_run_next(args: argparse.Namespace, *, runtime: ColumnCommandRunt
             sys.exit(3)
         return
 
-    payload: Dict[str, Any] = {"scope": "subset", "rowIds": row_ids}
-    if args.unprocessed_only:
-        payload["unprocessedOnly"] = True
+    payload: Dict[str, Any] = {
+        "scope": "subset",
+        "rowIds": row_ids,
+        "unprocessedOnly": bool(args.unprocessed_only),
+    }
 
     context = {
         "mode": "run-next",
@@ -327,7 +329,14 @@ def register_columns_subcommands(
     add_api_common_arguments(pcc)
     pcc.set_defaults(func=handlers["create"])
 
-    pcu = col_sub.add_parser("update", help="Update a column")
+    pcu = col_sub.add_parser(
+        "update",
+        help="Update a column",
+        description=(
+            "Update a column definition. Nested config keys merge into the existing config, "
+            "so partial config patches are supported."
+        ),
+    )
     pcu.add_argument("--table-id", required=True)
     pcu.add_argument("--column-id", required=True)
     pcu.add_argument("--data-json", help="ColumnUpdate payload JSON")

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_cli/data/CLI_REFERENCE.md

@@ -1,6 +1,6 @@
 # Autotouch CLI Reference
 
-Generated from the installed parser for `autotouch-cli` `0.2.46`.
+Generated from the installed parser for `autotouch-cli` `0.2.48`.
 Manifest schema version: `2`.
 
 ## Output Modes
@@ -71,7 +71,9 @@ Register an account/org and return a developer key
 
 #### `autotouch auth check`
 
-Validate token against /api/capabilities
+Validate the current token/session and show granted scopes
+
+Validate the current token/session against the API and show granted scopes for developer API keys.
 
 - Auth: `developer_key_or_user_session`
 - Stability: `stable`
@@ -505,6 +507,8 @@ Get one cell with value/status/metadata
 
 Patch cells in batch
 
+Patch cells in batch. Use column key strings in updates[].key; this payload does not accept columnId.
+
 - Auth: `developer_key_or_user_session`
 - Stability: `stable`
 - Destructive: `no`
@@ -691,7 +695,8 @@ Estimate a column run
                                   --column-id COLUMN_ID
                                   [--scope {all,subset,row,firstN,filtered}]
                                   [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]
-                                  [--first-n FIRST_N] [--unprocessed-only]
+                                  [--first-n FIRST_N] [--unprocessed-only |
+                                  --include-processed]
                                   [--filters-json FILTERS_JSON]
                                   [--filters-file FILTERS_FILE]
                                   [--data-json DATA_JSON]
@@ -708,7 +713,8 @@ Estimate a column run
   - `--row-id` (kind=string): Single row ID for scope=row
   - `--row-ids` (kind=list): Row IDs for subset scope (or a single row when scope=row)
   - `--first-n` (kind=integer): First N rows (for scope=firstN). Use with --unprocessed-only to process the next rows without reruns
-  - `--unprocessed-only` (kind=boolean; when omitted=False; when present=True): Only process rows without values (recommended with scope=firstN)
+  - `--unprocessed-only` (kind=boolean; when omitted=True; when present=True): Only process rows without values (default)
+  - `--include-processed` (kind=boolean; when omitted=True; when present=False): Include rows that already have output
   - `--filters-json` (kind=json; input=json): JSON object for scope=filtered
   - `--filters-file` (kind=file; input=file): Path to JSON file for scope=filtered
   - `--data-json` (kind=json; input=json): Explicit RunRequest payload JSON (overrides scope flags)
@@ -842,7 +848,8 @@ Run a column
   - `autotouch columns run [-h] --table-id TABLE_ID --column-id COLUMN_ID
                              [--scope {all,subset,row,firstN,filtered}]
                              [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]
-                             [--first-n FIRST_N] [--unprocessed-only]
+                             [--first-n FIRST_N] [--unprocessed-only |
+                             --include-processed]
                              [--filters-json FILTERS_JSON]
                              [--filters-file FILTERS_FILE]
                              [--data-json DATA_JSON] [--data-file DATA_FILE]
@@ -864,7 +871,8 @@ Run a column
   - `--row-id` (kind=string): Single row ID for scope=row
   - `--row-ids` (kind=list): Row IDs for subset scope (or a single row when scope=row)
   - `--first-n` (kind=integer): First N rows (for scope=firstN). Use with --unprocessed-only to process the next rows without reruns
-  - `--unprocessed-only` (kind=boolean; when omitted=False; when present=True): Only process rows without values (recommended with scope=firstN)
+  - `--unprocessed-only` (kind=boolean; when omitted=True; when present=True): Only process rows without values (default)
+  - `--include-processed` (kind=boolean; when omitted=True; when present=False): Include rows that already have output
   - `--filters-json` (kind=json; input=json): JSON object for scope=filtered
   - `--filters-file` (kind=file; input=file): Path to JSON file for scope=filtered
   - `--data-json` (kind=json; input=json): Explicit RunRequest payload JSON (overrides scope flags)
@@ -1021,6 +1029,8 @@ Template syntax:
 
 Update a column
 
+Update a column definition. Nested config keys merge into the existing config, so partial config patches are supported.
+
 - Auth: `developer_key_or_user_session`
 - Stability: `stable`
 - Destructive: `no`
@@ -2845,8 +2855,8 @@ Alias for: columns run
   - `autotouch run [-h] --table-id TABLE_ID --column-id COLUMN_ID
                      [--scope {all,subset,row,firstN,filtered}]
                      [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]
-                     [--first-n FIRST_N] [--unprocessed-only]
-                     [--filters-json FILTERS_JSON]
+                     [--first-n FIRST_N] [--unprocessed-only |
+                     --include-processed] [--filters-json FILTERS_JSON]
                      [--filters-file FILTERS_FILE] [--data-json DATA_JSON]
                      [--data-file DATA_FILE] [--show-estimate] [--dry-run]
                      [--max-credits MAX_CREDITS] [--allow-unknown-max]
@@ -2864,7 +2874,8 @@ Alias for: columns run
   - `--row-id` (kind=string): Single row ID for scope=row
   - `--row-ids` (kind=list): Row IDs for subset scope (or a single row when scope=row)
   - `--first-n` (kind=integer): First N rows (for scope=firstN). Use with --unprocessed-only to process the next rows without reruns
-  - `--unprocessed-only` (kind=boolean; when omitted=False; when present=True): Only process rows without values (recommended with scope=firstN)
+  - `--unprocessed-only` (kind=boolean; when omitted=True; when present=True): Only process rows without values (default)
+  - `--include-processed` (kind=boolean; when omitted=True; when present=False): Include rows that already have output
   - `--filters-json` (kind=json; input=json): JSON object for scope=filtered
   - `--filters-file` (kind=file; input=file): Path to JSON file for scope=filtered
   - `--data-json` (kind=json; input=json): Explicit RunRequest payload JSON (overrides scope flags)

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_cli/data/cli-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.46",
+  "version": "0.2.48",
   "manifest_schema_version": 2,
   "entry_points": {
     "autotouch": "autotouch_cli.cli:main",
@@ -653,8 +653,8 @@
       ],
       "aliases": [],
       "group": "auth",
-      "help": "Validate token against /api/capabilities",
-      "description": null,
+      "help": "Validate the current token/session and show granted scopes",
+      "description": "Validate the current token/session against the API and show granted scopes for developer API keys.",
       "notes": null,
       "required_flags": [],
       "positionals": [],
@@ -12613,7 +12613,7 @@
       "aliases": [],
       "group": "cells",
       "help": "Patch cells in batch",
-      "description": null,
+      "description": "Patch cells in batch. Use column key strings in updates[].key; this payload does not accept columnId.",
       "notes": null,
       "required_flags": [
         "--table-id"
@@ -13403,7 +13403,7 @@
       "aliases": [],
       "group": "columns",
       "help": "Update a column",
-      "description": null,
+      "description": "Update a column definition. Nested config keys merge into the existing config, so partial config patches are supported.",
       "notes": null,
       "required_flags": [
         "--table-id",
@@ -14340,17 +14340,31 @@
         {
           "dest": "unprocessed_only",
           "required": false,
-          "help": "Only process rows without values (recommended with scope=firstN)",
+          "help": "Only process rows without values (default)",
           "kind": "boolean",
           "action": "store_true",
           "nargs": 0,
-          "default_when_omitted": false,
+          "default_when_omitted": true,
           "value_when_present": true,
           "flags": [
             "--unprocessed-only"
           ],
           "takes_value": false
         },
+        {
+          "dest": "unprocessed_only",
+          "required": false,
+          "help": "Include rows that already have output",
+          "kind": "boolean",
+          "action": "store_false",
+          "nargs": 0,
+          "default_when_omitted": true,
+          "value_when_present": false,
+          "flags": [
+            "--include-processed"
+          ],
+          "takes_value": false
+        },
         {
           "dest": "filters_json",
           "required": false,
@@ -14656,6 +14670,13 @@
         }
       ],
       "mutually_exclusive_groups": [
+        {
+          "required": false,
+          "options": [
+            "--unprocessed-only",
+            "--include-processed"
+          ]
+        },
         {
           "required": false,
           "options": [
@@ -14688,7 +14709,7 @@
       },
       "availability": null,
       "examples": [
-        "autotouch columns run [-h] --table-id TABLE_ID --column-id COLUMN_ID\n                             [--scope {all,subset,row,firstN,filtered}]\n                             [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]\n                             [--first-n FIRST_N] [--unprocessed-only]\n                             [--filters-json FILTERS_JSON]\n                             [--filters-file FILTERS_FILE]\n                             [--data-json DATA_JSON] [--data-file DATA_FILE]\n                             [--show-estimate] [--dry-run]\n                             [--max-credits MAX_CREDITS] [--allow-unknown-max]\n                             [--wait] [--quiet-wait]\n                             [--poll-interval POLL_INTERVAL]\n                             [--wait-timeout WAIT_TIMEOUT] [--fail-on-error]\n                             [--fail-on-partial] [--base-url BASE_URL]\n                             [--token TOKEN] [--use-x-api-key]\n                             [--timeout TIMEOUT]\n                             [--output {json,ndjson,human}] [--compact]\n                             [--select SELECT | --json-pointer JSON_POINTER]\n                             [--verbose]"
+        "autotouch columns run [-h] --table-id TABLE_ID --column-id COLUMN_ID\n                             [--scope {all,subset,row,firstN,filtered}]\n                             [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]\n                             [--first-n FIRST_N] [--unprocessed-only |\n                             --include-processed]\n                             [--filters-json FILTERS_JSON]\n                             [--filters-file FILTERS_FILE]\n                             [--data-json DATA_JSON] [--data-file DATA_FILE]\n                             [--show-estimate] [--dry-run]\n                             [--max-credits MAX_CREDITS] [--allow-unknown-max]\n                             [--wait] [--quiet-wait]\n                             [--poll-interval POLL_INTERVAL]\n                             [--wait-timeout WAIT_TIMEOUT] [--fail-on-error]\n                             [--fail-on-partial] [--base-url BASE_URL]\n                             [--token TOKEN] [--use-x-api-key]\n                             [--timeout TIMEOUT]\n                             [--output {json,ndjson,human}] [--compact]\n                             [--select SELECT | --json-pointer JSON_POINTER]\n                             [--verbose]"
       ],
       "stability": "stable",
       "handler": "cmd_columns_run"
@@ -15396,17 +15417,31 @@
         {
           "dest": "unprocessed_only",
           "required": false,
-          "help": "Only process rows without values (recommended with scope=firstN)",
+          "help": "Only process rows without values (default)",
           "kind": "boolean",
           "action": "store_true",
           "nargs": 0,
-          "default_when_omitted": false,
+          "default_when_omitted": true,
           "value_when_present": true,
           "flags": [
             "--unprocessed-only"
           ],
           "takes_value": false
         },
+        {
+          "dest": "unprocessed_only",
+          "required": false,
+          "help": "Include rows that already have output",
+          "kind": "boolean",
+          "action": "store_false",
+          "nargs": 0,
+          "default_when_omitted": true,
+          "value_when_present": false,
+          "flags": [
+            "--include-processed"
+          ],
+          "takes_value": false
+        },
         {
           "dest": "filters_json",
           "required": false,
@@ -15577,6 +15612,13 @@
         }
       ],
       "mutually_exclusive_groups": [
+        {
+          "required": false,
+          "options": [
+            "--unprocessed-only",
+            "--include-processed"
+          ]
+        },
         {
           "required": false,
           "options": [
@@ -15608,7 +15650,7 @@
       },
       "availability": null,
       "examples": [
-        "autotouch columns estimate [-h] --table-id TABLE_ID\n                                  --column-id COLUMN_ID\n                                  [--scope {all,subset,row,firstN,filtered}]\n                                  [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]\n                                  [--first-n FIRST_N] [--unprocessed-only]\n                                  [--filters-json FILTERS_JSON]\n                                  [--filters-file FILTERS_FILE]\n                                  [--data-json DATA_JSON]\n                                  [--data-file DATA_FILE]\n                                  [--base-url BASE_URL] [--token TOKEN]\n                                  [--use-x-api-key] [--timeout TIMEOUT]\n                                  [--output {json,ndjson,human}] [--compact]\n                                  [--select SELECT |\n                                  --json-pointer JSON_POINTER] [--verbose]"
+        "autotouch columns estimate [-h] --table-id TABLE_ID\n                                  --column-id COLUMN_ID\n                                  [--scope {all,subset,row,firstN,filtered}]\n                                  [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]\n                                  [--first-n FIRST_N] [--unprocessed-only |\n                                  --include-processed]\n                                  [--filters-json FILTERS_JSON]\n                                  [--filters-file FILTERS_FILE]\n                                  [--data-json DATA_JSON]\n                                  [--data-file DATA_FILE]\n                                  [--base-url BASE_URL] [--token TOKEN]\n                                  [--use-x-api-key] [--timeout TIMEOUT]\n                                  [--output {json,ndjson,human}] [--compact]\n                                  [--select SELECT |\n                                  --json-pointer JSON_POINTER] [--verbose]"
       ],
       "stability": "stable",
       "handler": "cmd_columns_estimate"
@@ -31080,17 +31122,31 @@
         {
           "dest": "unprocessed_only",
           "required": false,
-          "help": "Only process rows without values (recommended with scope=firstN)",
+          "help": "Only process rows without values (default)",
           "kind": "boolean",
           "action": "store_true",
           "nargs": 0,
-          "default_when_omitted": false,
+          "default_when_omitted": true,
           "value_when_present": true,
           "flags": [
             "--unprocessed-only"
           ],
           "takes_value": false
         },
+        {
+          "dest": "unprocessed_only",
+          "required": false,
+          "help": "Include rows that already have output",
+          "kind": "boolean",
+          "action": "store_false",
+          "nargs": 0,
+          "default_when_omitted": true,
+          "value_when_present": false,
+          "flags": [
+            "--include-processed"
+          ],
+          "takes_value": false
+        },
         {
           "dest": "filters_json",
           "required": false,
@@ -31396,6 +31452,13 @@
         }
       ],
       "mutually_exclusive_groups": [
+        {
+          "required": false,
+          "options": [
+            "--unprocessed-only",
+            "--include-processed"
+          ]
+        },
         {
           "required": false,
           "options": [
@@ -31427,7 +31490,7 @@
       },
       "availability": null,
       "examples": [
-        "autotouch run [-h] --table-id TABLE_ID --column-id COLUMN_ID\n                     [--scope {all,subset,row,firstN,filtered}]\n                     [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]\n                     [--first-n FIRST_N] [--unprocessed-only]\n                     [--filters-json FILTERS_JSON]\n                     [--filters-file FILTERS_FILE] [--data-json DATA_JSON]\n                     [--data-file DATA_FILE] [--show-estimate] [--dry-run]\n                     [--max-credits MAX_CREDITS] [--allow-unknown-max]\n                     [--wait] [--quiet-wait] [--poll-interval POLL_INTERVAL]\n                     [--wait-timeout WAIT_TIMEOUT] [--fail-on-error]\n                     [--fail-on-partial] [--base-url BASE_URL] [--token TOKEN]\n                     [--use-x-api-key] [--timeout TIMEOUT]\n                     [--output {json,ndjson,human}] [--compact]\n                     [--select SELECT | --json-pointer JSON_POINTER]\n                     [--verbose]"
+        "autotouch run [-h] --table-id TABLE_ID --column-id COLUMN_ID\n                     [--scope {all,subset,row,firstN,filtered}]\n                     [--row-id ROW_ID] [--row-ids [ROW_IDS ...]]\n                     [--first-n FIRST_N] [--unprocessed-only |\n                     --include-processed] [--filters-json FILTERS_JSON]\n                     [--filters-file FILTERS_FILE] [--data-json DATA_JSON]\n                     [--data-file DATA_FILE] [--show-estimate] [--dry-run]\n                     [--max-credits MAX_CREDITS] [--allow-unknown-max]\n                     [--wait] [--quiet-wait] [--poll-interval POLL_INTERVAL]\n                     [--wait-timeout WAIT_TIMEOUT] [--fail-on-error]\n                     [--fail-on-partial] [--base-url BASE_URL] [--token TOKEN]\n                     [--use-x-api-key] [--timeout TIMEOUT]\n                     [--output {json,ndjson,human}] [--compact]\n                     [--select SELECT | --json-pointer JSON_POINTER]\n                     [--verbose]"
       ],
       "stability": "stable",
       "handler": "cmd_columns_run"

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_cli/templates.py

@@ -665,13 +665,16 @@ CELL_SCHEMA_TYPES = ["patch_updates"]
 CELL_SCHEMAS = {
     "patch_updates": {
         "updates": [
-            {"rowId": "<ROW_ID>", "columnId": "<COLUMN_ID>", "value": "New value"},
-            {"rowId": "<ROW_ID_2>", "columnId": "<COLUMN_ID>", "value": 42},
+            {"rowId": "<ROW_ID>", "key": "status", "value": "New value"},
+            {"rowId": "<ROW_ID_2>", "key": "score", "value": 42},
         ]
     }
 }
 CELL_SCHEMA_NOTES = {
-    "patch_updates": ["cells patch accepts a bare list too; this schema uses the explicit updates[] wrapper."],
+    "patch_updates": [
+        "cells patch accepts a bare list too; this schema uses the explicit updates[] wrapper.",
+        "Use column key strings in updates[].key; the API does not accept columnId here.",
+    ],
 }
 
 

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.46
+Version: 0.2.48
 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
@@ -146,9 +146,18 @@ For automation or agent-driven setup, use:
 - `autotouch sequences ...` and `autotouch tasks ...` for sequence/task workflows
 - `pip install 'autotouch-cli[mongo]'` if you need the Mongo-backed `status` / `watch` commands
 
+## LLM Columns
+
+For `llm_enrichment` in `agent` mode, the recommended path is:
+- provide `config.instructions`
+- let the API compile the runnable prompt
+- keep `config.useAutoSchema = true`
+
+Only send `user_schema` / `response_schema` when you intentionally want to override the generated schema and keep it aligned yourself. The installed recipe surface at `autotouch columns recipe --type llm_enrichment` follows this contract.
+
 ## Docs
 
-- Full CLI reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/reference/autotouch-cli.md
-- Agent playbook: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/guides/autotouch-cli-agent-playbook.md
-- Tables/API reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/research-table/reference/tables-api.md
-- Authentication/scopes: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.46/docs/platform/authentication.md
+- Full CLI reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/reference/autotouch-cli.md
+- Agent playbook: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/guides/autotouch-cli-agent-playbook.md
+- Tables/API reference: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/research-table/reference/tables-api.md
+- Authentication/scopes: https://github.com/nicolonic/autotouch_main/blob/autotouch-cli-v0.2.48/docs/platform/authentication.md

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/autotouch_shared/provider_registry.py

@@ -30,6 +30,7 @@ class ResearchTableProviderContract:
     key: str
     display_name: str
     kind: str
+    behavior_class: str = "standard_enrichment"
     provider_aliases: Tuple[str, ...] = ()
     origin_aliases: Tuple[str, ...] = ()
     recipe_type: Optional[str] = None
@@ -39,6 +40,7 @@ class ResearchTableProviderContract:
     setup_contract: Dict[str, Any] = field(default_factory=dict)
     execution_policy: Optional[AutoRunExecutionPolicy] = None
     dispatch_strategy: str = "bulk_queue"
+    readiness_strategy: Optional[str] = None
     save_time_entrypoint: Optional[str] = None
     is_action_provider: bool = False
     composition_contract: Dict[str, Any] = field(default_factory=dict)
@@ -72,10 +74,12 @@ class ResearchTableProviderContract:
         payload: Dict[str, Any] = {
             "display_name": self.display_name,
             "kind": self.kind,
+            "behavior_class": self.behavior_class,
             "recipe_type": self.recipe_type,
             "provider_aliases": list(self.provider_aliases or ()),
             "origin_aliases": list(self.origin_aliases or ()),
             "dispatch_strategy": self.dispatch_strategy,
+            "readiness_strategy": self.readiness_strategy,
             "action_provider": bool(self.is_action_provider),
             "setup_contract": deepcopy(self.setup_contract),
             "composition_contract": deepcopy(self.composition_contract),
@@ -271,6 +275,7 @@ _ADD_TO_SEQUENCE_POLICY = AutoRunExecutionPolicy(
     force_rerun=False,
     respect_existing_done=True,
     default_batch_size=50,
+    batch_size_env="ADD_TO_SEQUENCE_BATCH_SIZE",
 )
 
 _HTTP_REQUEST_POLICY = AutoRunExecutionPolicy(
@@ -293,6 +298,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         key="formatter",
         display_name="Formatter",
         kind="formatter",
+        behavior_class="formatter",
         recipe_type="formatter",
         recipe_payload={
             "key": "engagement_statement",
@@ -343,6 +349,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         key="llm",
         display_name="LLM Enrichment",
         kind="enrichment",
+        behavior_class="standard_enrichment",
         provider_aliases=_llm_provider_values(),
         recipe_type="llm_enrichment",
         recipe_payload={
@@ -365,8 +372,10 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         },
         recipe_notes=(
             "Recommended default for agent mode: provide instructions and let the API compile the runnable 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.prompt/advancedPrompt before execution.",
+            "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.",
@@ -431,10 +440,10 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
                 "generated": {
                     "instructions_field": "config.instructions",
                     "prompt_source": "generated",
-                    "materialized_prompt_fields": ["config.prompt", "config.advancedPrompt"],
+                    "materialized_prompt_fields": ["config.advancedPrompt"],
                 },
                 "manual": {
-                    "prompt_field": "config.prompt",
+                    "prompt_field": "config.advancedPrompt",
                     "prompt_source": "manual",
                 },
             },
@@ -477,13 +486,14 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             ],
         },
         execution_policy=_LLM_POLICY,
-        dispatch_strategy="llm_scheduler",
+        dispatch_strategy="bulk_queue",
         save_time_entrypoint="provider_save_hook",
     ),
     ResearchTableProviderContract(
         key="email_finder",
         display_name="Email Finder",
         kind="enrichment",
+        behavior_class="standard_enrichment",
         provider_aliases=("smart_email_finder", "email_validator", "email_finder"),
         origin_aliases=("email_finder",),
         recipe_type="email_finder",
@@ -552,6 +562,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         key="phone_finder",
         display_name="Phone Finder",
         kind="enrichment",
+        behavior_class="standard_enrichment",
         provider_aliases=("smart_phone_finder", "phone_validator", "phone_finder"),
         origin_aliases=("phone_finder",),
         recipe_type="phone_finder",
@@ -626,6 +637,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         key="lead_finder",
         display_name="Lead Finder",
         kind="enrichment",
+        behavior_class="standard_enrichment",
         provider_aliases=("lead_finder",),
         recipe_type="lead_finder",
         recipe_payload={
@@ -706,6 +718,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         key="add_to_crm",
         display_name="Add to Leads",
         kind="enrichment",
+        behavior_class="action_enrichment",
         provider_aliases=("add_to_crm",),
         recipe_type="add_to_crm",
         recipe_payload={
@@ -794,12 +807,14 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             ],
         },
         execution_policy=_ADD_TO_CRM_POLICY,
+        readiness_strategy="add_to_crm",
         is_action_provider=True,
     ),
     ResearchTableProviderContract(
         key="sync_to_table",
         display_name="Sync to Table",
         kind="enrichment",
+        behavior_class="action_enrichment",
         provider_aliases=("sync_to_table",),
         recipe_type="sync_to_table",
         recipe_payload={
@@ -904,12 +919,14 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         },
         execution_policy=_SYNC_TO_TABLE_POLICY,
         dispatch_strategy="sync_to_table_prefilter",
+        readiness_strategy="sync_to_table",
         is_action_provider=True,
     ),
     ResearchTableProviderContract(
         key="add_to_sequence",
         display_name="Add to Sequence",
         kind="enrichment",
+        behavior_class="action_enrichment",
         provider_aliases=("add_to_sequence",),
         recipe_type="add_to_sequence",
         recipe_payload={
@@ -972,12 +989,14 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             ],
         },
         execution_policy=_ADD_TO_SEQUENCE_POLICY,
+        readiness_strategy="add_to_sequence",
         is_action_provider=True,
     ),
     ResearchTableProviderContract(
         key="http_request",
         display_name="HTTP Request",
         kind="enrichment",
+        behavior_class="standard_enrichment",
         provider_aliases=("http_request",),
         recipe_type="http_request",
         recipe_payload={
@@ -998,7 +1017,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         },
         recipe_notes=(
             "Use {{column_key}} placeholders in config.url, config.headers, and config.body to reference row values.",
-            "Use {{secrets.name}} to resolve a workspace secret or active org integration credential by provider slug.",
+            "Use {{secrets.name}} to resolve a workspace secret by name.",
             "body can be null, a string template, or an object whose values are templated and sent as JSON.",
             "The stored cell value is the parsed response body (JSON or text), not the full transport envelope.",
             "Preview the resolved request with `autotouch columns test-http-request --table-id <TABLE_ID> --data-file column.json` before creating or running the column.",
@@ -1038,7 +1057,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         composition_contract={
             "consumes": {
                 "kind": "row_data",
-                "shape": "{{column_key}} templates resolved from row cell values plus optional {{secrets.name}} org credentials",
+                "shape": "{{column_key}} templates resolved from row cell values plus optional {{secrets.name}} workspace secrets",
             },
             "produces": {
                 "kind": "json",
@@ -1308,7 +1327,7 @@ def validate_column_provider_contract(
             raise ProviderContractValidationError(
                 "invalid_field",
                 "http_request config.headers must be an object when provided.",
-                hint="Set config.headers to a JSON object such as {\"Authorization\": \"Bearer {{secrets.provider}}\"}.",
+                hint="Set config.headers to a JSON object such as {\"Authorization\": \"Bearer {{secrets.openai_api_key}}\"}.",
             )
         body = cfg.get("body")
         if body is not None and not isinstance(body, (str, dict)):
@@ -1355,3 +1374,74 @@ def automation_workflow_blueprints() -> Dict[str, Dict[str, Any]]:
 
 def action_provider_keys() -> Tuple[str, ...]:
     return tuple(contract.key for contract in _PROVIDER_CONTRACTS if contract.is_action_provider)
+
+
+def behavior_class_keys(behavior_class: str) -> Tuple[str, ...]:
+    normalized = _normalize(behavior_class)
+    return tuple(
+        contract.key
+        for contract in _PROVIDER_CONTRACTS
+        if _normalize(contract.behavior_class) == normalized
+    )
+
+
+def orchestrated_runtime_provider_keys(*, include_formatter: bool = False) -> Tuple[str, ...]:
+    providers: List[str] = []
+    for contract in _PROVIDER_CONTRACTS:
+        policy = contract.execution_policy
+        if not policy:
+            continue
+        normalized_behavior = _normalize(contract.behavior_class)
+        if normalized_behavior == "formatter":
+            if include_formatter:
+                providers.append(policy.orchestrator_provider)
+            continue
+        if contract.key == "llm":
+            providers.extend(["gemini", "xai"])
+            continue
+        providers.append(policy.orchestrator_provider)
+    return tuple(dict.fromkeys(provider for provider in providers if provider))
+
+
+def resolve_provider_behavior_class(
+    column: Dict[str, Any],
+    config: Optional[Dict[str, Any]],
+) -> Optional[str]:
+    contract = resolve_effective_provider_contract(column, config)
+    if not contract:
+        return None
+    return contract.behavior_class
+
+
+def should_resolve_managed_llm_model(
+    column: Dict[str, Any],
+    config: Optional[Dict[str, Any]],
+) -> bool:
+    contract = resolve_effective_provider_contract(column, config)
+    if not contract:
+        return False
+    return contract.key == "llm" and _normalize(column.get("origin")) == "ai"
+
+
+def resolve_runtime_orchestrator_provider(
+    column: Dict[str, Any],
+    config: Optional[Dict[str, Any]],
+) -> Optional[str]:
+    contract = resolve_effective_provider_contract(column, config)
+    if not contract or not contract.execution_policy:
+        return None
+    if _normalize(contract.behavior_class) == "formatter":
+        return None
+    if contract.key == "llm":
+        runtime_provider = _normalize((config or {}).get("provider"))
+        if runtime_provider in {"gemini", "xai"}:
+            return runtime_provider
+        return None
+    return contract.execution_policy.orchestrator_provider
+
+
+def uses_orchestrated_bulk_run(
+    column: Dict[str, Any],
+    config: Optional[Dict[str, Any]],
+) -> bool:
+    return resolve_runtime_orchestrator_provider(column, config) is not None

{autotouch_cli-0.2.46 → autotouch_cli-0.2.48}/pyproject.toml

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