autotouch-cli 0.2.60__tar.gz → 0.2.63__tar.gz

{autotouch_cli-0.2.60 → autotouch_cli-0.2.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.60
+Version: 0.2.63
 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
@@ -158,6 +158,11 @@ For `llm_enrichment` in `agent` mode, the recommended path is:
 
 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.
 
+Schema ownership rules:
+- Accepted generated schemas and explicit user schemas are the saved output contract.
+- Row execution must not add fields, rename fields, or replace a valid locked schema.
+- Agent-mode evidence/scored state decides which values may fill the schema; the finalizer formats those values and schema validation gates persistence.
+
 Prompt variables in authored prompts support nested JSON access:
 - Use flat row variables like `{{company_name}}` for scalar columns.
 - Use dotted placeholders like `{{linkedin_lookup.linkedin_url}}` when the source column stores JSON or stringified JSON.

{autotouch_cli-0.2.60 → autotouch_cli-0.2.63}/README.md

@@ -133,6 +133,11 @@ For `llm_enrichment` in `agent` mode, the recommended path is:
 
 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.
 
+Schema ownership rules:
+- Accepted generated schemas and explicit user schemas are the saved output contract.
+- Row execution must not add fields, rename fields, or replace a valid locked schema.
+- Agent-mode evidence/scored state decides which values may fill the schema; the finalizer formats those values and schema validation gates persistence.
+
 Prompt variables in authored prompts support nested JSON access:
 - Use flat row variables like `{{company_name}}` for scalar columns.
 - Use dotted placeholders like `{{linkedin_lookup.linkedin_url}}` when the source column stores JSON or stringified JSON.

{autotouch_cli-0.2.60 → autotouch_cli-0.2.63}/autotouch_cli/cli.py

@@ -125,6 +125,21 @@ from autotouch_cli.commands.search import (
     cmd_search_reviews as cmd_search_reviews_impl,
     cmd_search_similar_companies as cmd_search_similar_companies_impl,
 )
+from autotouch_cli.commands.agents import (
+    AgentCommandRuntime as AgentCommandHandlerRuntime,
+    cmd_agents_list as cmd_agents_list_impl,
+    cmd_agents_get as cmd_agents_get_impl,
+    cmd_agents_create as cmd_agents_create_impl,
+    cmd_agents_update as cmd_agents_update_impl,
+    cmd_agents_delete as cmd_agents_delete_impl,
+    cmd_agents_run as cmd_agents_run_impl,
+    cmd_agents_runs as cmd_agents_runs_impl,
+    cmd_agents_watch as cmd_agents_watch_impl,
+    cmd_agents_generate_persona as cmd_agents_generate_persona_impl,
+    cmd_agents_generate_topics as cmd_agents_generate_topics_impl,
+    cmd_agents_generate_job_signal as cmd_agents_generate_job_signal_impl,
+    cmd_agents_signals as cmd_agents_signals_impl,
+)
 from autotouch_cli.commands.sequences import (
     SequenceCommandRuntime as SequenceCommandHandlerRuntime,
     cmd_sequences_clone as cmd_sequences_clone_impl,
@@ -1164,6 +1179,17 @@ def _sequence_command_runtime() -> SequenceCommandHandlerRuntime:
     )
 
 
+def _agent_command_runtime() -> AgentCommandHandlerRuntime:
+    return AgentCommandHandlerRuntime(
+        resolve_token=_resolve_token,
+        request_api=_request_api,
+        print_json=lambda data, compact=False: _print_json(data, compact=compact),
+        load_json_input=_load_json_input,
+        api_url=_api_url,
+        default_timeout_seconds=DEFAULT_TIMEOUT_SECONDS,
+    )
+
+
 def _column_command_runtime() -> ColumnCommandHandlerRuntime:
     return ColumnCommandHandlerRuntime(
         resolve_token=_resolve_token,
@@ -1420,6 +1446,20 @@ _register("columns_run_next", cmd_columns_run_next_impl, _column_command_runtime
 _register("columns_stop", cmd_columns_stop_impl, _column_command_runtime)
 _register("columns_estimate", cmd_columns_estimate_impl, _column_command_runtime)
 
+# -- Agent commands --
+_register("agents_list", cmd_agents_list_impl, _agent_command_runtime)
+_register("agents_get", cmd_agents_get_impl, _agent_command_runtime)
+_register("agents_create", cmd_agents_create_impl, _agent_command_runtime)
+_register("agents_update", cmd_agents_update_impl, _agent_command_runtime)
+_register("agents_delete", cmd_agents_delete_impl, _agent_command_runtime)
+_register("agents_run", cmd_agents_run_impl, _agent_command_runtime)
+_register("agents_runs", cmd_agents_runs_impl, _agent_command_runtime)
+_register("agents_watch", cmd_agents_watch_impl, _agent_command_runtime)
+_register("agents_generate_persona", cmd_agents_generate_persona_impl, _agent_command_runtime)
+_register("agents_generate_topics", cmd_agents_generate_topics_impl, _agent_command_runtime)
+_register("agents_generate_job_signal", cmd_agents_generate_job_signal_impl, _agent_command_runtime)
+_register("agents_signals", cmd_agents_signals_impl, _agent_command_runtime)
+
 # -- Sequence commands --
 _register("sequences_list", cmd_sequences_list_impl, _sequence_command_runtime)
 _register("sequences_get", cmd_sequences_get_impl, _sequence_command_runtime)

autotouch_cli-0.2.63/autotouch_cli/commands/agents.py

@@ -0,0 +1,465 @@
+"""Scheduled agent CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, Sequence
+
+
+@dataclass(frozen=True)
+class AgentCommandRuntime:
+    resolve_token: Callable[[Optional[str], bool], Optional[str]]
+    request_api: Callable[..., Any]
+    print_json: Callable[[Any, bool], None]
+    load_json_input: Callable[..., Any]
+    api_url: Callable[[Optional[str]], str]
+    default_timeout_seconds: int
+
+
+# ---------------------------------------------------------------------------
+# CRUD
+# ---------------------------------------------------------------------------
+
+def cmd_agents_list(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    data = runtime.request_api(
+        "GET", "/api/agents",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_agents_get(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    data = runtime.request_api(
+        "GET", f"/api/agents/{args.agent_id}",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_agents_create(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+
+    if getattr(args, "from_file", None):
+        payload = runtime.load_json_input(args.from_file)
+    else:
+        payload: Dict[str, Any] = {}
+        if args.name:
+            payload["name"] = args.name
+        if args.target:
+            payload["targetType"] = args.target
+        if args.assigned_user:
+            payload["assignedUserId"] = args.assigned_user
+        if args.schedule_time:
+            tz = getattr(args, "schedule_tz", None) or "UTC"
+            payload["schedule"] = {"timezone": tz, "timeOfDay": args.schedule_time}
+        if getattr(args, "auto_find_email", False):
+            payload["autoFindEmail"] = True
+        if getattr(args, "auto_find_phone", False):
+            payload["autoFindPhone"] = True
+        if getattr(args, "auto_broaden", False):
+            payload["autoBroadenSearch"] = True
+        status = getattr(args, "status", None)
+        if status:
+            payload["status"] = status
+
+    # AI generation: generate persona, signals, and create in one shot
+    if getattr(args, "generate", False) and "personaConfig" not in payload:
+        target = payload.get("targetType", "LEADS")
+        sys.stderr.write(f"Generating persona for {target}...\n")
+        persona_data = runtime.request_api(
+            "POST", "/api/agents/generate-persona",
+            base_url=args.base_url, token=token,
+            use_x_api_key=args.use_x_api_key,
+            json={"targetType": target},
+            timeout=args.timeout, verbose=args.verbose,
+        )
+        persona = persona_data.get("persona") or persona_data.get("personaConfig") or {}
+        payload["personaConfig"] = persona
+        sys.stderr.write(f"  Persona generated: {json.dumps(persona, ensure_ascii=False)[:200]}...\n")
+
+        # Generate topics
+        sys.stderr.write("Generating topic suggestions...\n")
+        topic_data = runtime.request_api(
+            "POST", "/api/agents/generate-signal-topics",
+            base_url=args.base_url, token=token,
+            use_x_api_key=args.use_x_api_key,
+            json={"targetType": target, "personaConfig": persona},
+            timeout=args.timeout, verbose=args.verbose,
+        )
+        topics = topic_data.get("topics") or []
+        sys.stderr.write(f"  Topics: {topics}\n")
+
+        # Generate job signal
+        sys.stderr.write("Generating job signal config...\n")
+        job_data = runtime.request_api(
+            "POST", "/api/agents/generate-job-signal",
+            base_url=args.base_url, token=token,
+            use_x_api_key=args.use_x_api_key,
+            json={"targetType": target, "personaConfig": persona},
+            timeout=args.timeout, verbose=args.verbose,
+        )
+        job_titles = job_data.get("jobTitles") or []
+        job_keywords = job_data.get("keywords") or []
+        sys.stderr.write(f"  Job titles: {job_titles}\n")
+
+        # Assemble signals
+        signals = []
+        if topics:
+            signals.append({
+                "key": "linkedin-topic-post-engagement",
+                "config": {"topics": [{"id": "", "label": t, "trackingMode": "all"} for t in topics[:5]]},
+            })
+        if job_titles or job_keywords:
+            signals.append({
+                "key": "hiring-signals",
+                "config": {"jobTitles": job_titles, "keywords": job_keywords, "remoteOnly": False, "lookbackWindow": "7d"},
+            })
+
+        # News scan: derive buying trigger topics from persona
+        news_topics = ["raised funding", "new executive hire"]
+        industries = (persona.get("industries") or [])[:2]
+        if industries:
+            news_topics.append(f"expansion {industries[0]}")
+        signals.append({
+            "key": "news-scan",
+            "config": {"topics": news_topics, "lookback": "24h"},
+        })
+
+        if signals:
+            payload["selectedSignals"] = signals
+
+    data = runtime.request_api(
+        "POST", "/api/agents",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        json=payload,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_agents_update(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+
+    if getattr(args, "from_file", None):
+        payload = runtime.load_json_input(args.from_file)
+    else:
+        payload: Dict[str, Any] = {}
+        if getattr(args, "name", None):
+            payload["name"] = args.name
+        if getattr(args, "status", None):
+            payload["status"] = args.status
+        if getattr(args, "auto_find_email", None) is not None:
+            payload["autoFindEmail"] = args.auto_find_email
+        if getattr(args, "auto_find_phone", None) is not None:
+            payload["autoFindPhone"] = args.auto_find_phone
+        if getattr(args, "auto_broaden", None) is not None:
+            payload["autoBroadenSearch"] = args.auto_broaden
+
+    data = runtime.request_api(
+        "PATCH", f"/api/agents/{args.agent_id}",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        json=payload,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_agents_delete(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    data = runtime.request_api(
+        "PATCH", f"/api/agents/{args.agent_id}",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        json={"status": "DRAFT"},
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    sys.stderr.write(f"Agent {args.agent_id} deleted.\n")
+    runtime.print_json(data, args.compact)
+
+
+# ---------------------------------------------------------------------------
+# Run management
+# ---------------------------------------------------------------------------
+
+def cmd_agents_run(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    data = runtime.request_api(
+        "POST", f"/api/agents/{args.agent_id}/run-now",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_agents_runs(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    params = {"limit": max(1, int(getattr(args, "limit", 10) or 10))}
+    data = runtime.request_api(
+        "GET", f"/api/agents/{args.agent_id}/runs",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        params=params,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_agents_watch(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    """Trigger a run and poll until complete."""
+    token = runtime.resolve_token(args.token, required=True)
+
+    # Trigger
+    run_data = runtime.request_api(
+        "POST", f"/api/agents/{args.agent_id}/run-now",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    run_id = run_data.get("id", "")
+    sys.stderr.write(f"Run {run_id} queued. Watching...\n")
+
+    interval = max(5, int(getattr(args, "interval", 10) or 10))
+    max_wait = max(60, int(getattr(args, "max_wait", 1800) or 1800))
+    elapsed = 0
+
+    while elapsed < max_wait:
+        time.sleep(interval)
+        elapsed += interval
+
+        runs_data = runtime.request_api(
+            "GET", f"/api/agents/{args.agent_id}/runs",
+            base_url=args.base_url, token=token,
+            use_x_api_key=args.use_x_api_key,
+            params={"limit": 1},
+            timeout=args.timeout, verbose=args.verbose,
+        )
+        runs = runs_data.get("runs", [])
+        if not runs:
+            continue
+
+        latest = runs[0]
+        status = latest.get("status", "")
+        leads = latest.get("resultCounts", {}).get("leads", 0)
+        sys.stderr.write(f"  [{elapsed}s] {status} | leads={leads}\n")
+
+        if status in ("SUCCEEDED", "FAILED"):
+            runtime.print_json(latest, args.compact)
+            return
+
+    sys.stderr.write(f"Timed out after {max_wait}s. Run may still be in progress.\n")
+
+
+# ---------------------------------------------------------------------------
+# AI generation
+# ---------------------------------------------------------------------------
+
+def cmd_agents_generate_persona(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    payload: Dict[str, Any] = {"targetType": getattr(args, "target", "LEADS") or "LEADS"}
+
+    current = getattr(args, "current_config", None)
+    if current:
+        payload["currentPersonaConfig"] = runtime.load_json_input(current)
+
+    data = runtime.request_api(
+        "POST", "/api/agents/generate-persona",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        json=payload,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_agents_generate_topics(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    payload: Dict[str, Any] = {"targetType": getattr(args, "target", "LEADS") or "LEADS"}
+
+    persona = getattr(args, "persona", None)
+    if persona:
+        payload["personaConfig"] = runtime.load_json_input(persona)
+
+    current = getattr(args, "current_topics", None)
+    if current:
+        payload["currentTopics"] = [t.strip() for t in current.split(",") if t.strip()]
+
+    data = runtime.request_api(
+        "POST", "/api/agents/generate-signal-topics",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        json=payload,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_agents_generate_job_signal(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    payload: Dict[str, Any] = {"targetType": getattr(args, "target", "LEADS") or "LEADS"}
+
+    persona = getattr(args, "persona", None)
+    if persona:
+        payload["personaConfig"] = runtime.load_json_input(persona)
+
+    current_titles = getattr(args, "current_titles", None)
+    if current_titles:
+        payload["currentJobTitles"] = [t.strip() for t in current_titles.split(",") if t.strip()]
+
+    current_keywords = getattr(args, "current_keywords", None)
+    if current_keywords:
+        payload["currentKeywords"] = [k.strip() for k in current_keywords.split(",") if k.strip()]
+
+    data = runtime.request_api(
+        "POST", "/api/agents/generate-job-signal",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        json=payload,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+# ---------------------------------------------------------------------------
+# Skill packs / signals
+# ---------------------------------------------------------------------------
+
+def cmd_agents_signals(args: argparse.Namespace, *, runtime: AgentCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    data = runtime.request_api(
+        "GET", "/api/agents/skill-packs",
+        base_url=args.base_url, token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout, verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+def register_agents_subcommands(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+    *,
+    add_api_common_arguments: Callable[[argparse.ArgumentParser], None],
+    handlers: Dict[str, Callable[[argparse.Namespace], None]],
+) -> None:
+    pa = subparsers.add_parser("agents", help="Scheduled agent management")
+    agents_sub = pa.add_subparsers(dest="agents_cmd", required=True)
+
+    # -- list --
+    pal = agents_sub.add_parser("list", help="List all agents")
+    add_api_common_arguments(pal)
+    pal.set_defaults(func=handlers["list"])
+
+    # -- get --
+    pag = agents_sub.add_parser("get", help="Get one agent by id")
+    pag.add_argument("agent_id", help="Agent ID")
+    add_api_common_arguments(pag)
+    pag.set_defaults(func=handlers["get"])
+
+    # -- create --
+    pac = agents_sub.add_parser("create", help="Create a new agent")
+    pac.add_argument("--name", help="Agent name")
+    pac.add_argument("--target", choices=["LEADS", "COMPANIES"], help="Target type")
+    pac.add_argument("--assigned-user", dest="assigned_user", help="Assigned user ID")
+    pac.add_argument("--schedule-time", dest="schedule_time", help="Time of day (HH:MM)")
+    pac.add_argument("--schedule-tz", dest="schedule_tz", help="Timezone (default: UTC)")
+    pac.add_argument("--auto-find-email", dest="auto_find_email", action="store_true", default=False, help="Enable auto email finder")
+    pac.add_argument("--auto-find-phone", dest="auto_find_phone", action="store_true", default=False, help="Enable auto phone finder")
+    pac.add_argument("--auto-broaden", dest="auto_broaden", action="store_true", default=False, help="Enable auto broaden search")
+    pac.add_argument("--status", choices=["DRAFT", "ACTIVE", "PAUSED"], help="Initial status")
+    pac.add_argument("--from-file", dest="from_file", help="Path to JSON payload file")
+    pac.add_argument("--generate", action="store_true", help="Auto-generate persona, topics, and job signal config")
+    add_api_common_arguments(pac)
+    pac.set_defaults(func=handlers["create"])
+
+    # -- update --
+    pau = agents_sub.add_parser("update", help="Update an existing agent")
+    pau.add_argument("agent_id", help="Agent ID")
+    pau.add_argument("--name", help="New agent name")
+    pau.add_argument("--status", choices=["DRAFT", "ACTIVE", "PAUSED"], help="New status")
+    pau.add_argument("--auto-find-email", dest="auto_find_email", type=_bool_arg, default=None, help="Enable/disable auto email finder")
+    pau.add_argument("--auto-find-phone", dest="auto_find_phone", type=_bool_arg, default=None, help="Enable/disable auto phone finder")
+    pau.add_argument("--auto-broaden", dest="auto_broaden", type=_bool_arg, default=None, help="Enable/disable auto broaden search")
+    pau.add_argument("--from-file", dest="from_file", help="Path to JSON patch payload file")
+    add_api_common_arguments(pau)
+    pau.set_defaults(func=handlers["update"])
+
+    # -- delete --
+    pad = agents_sub.add_parser("delete", help="Delete an agent (sets status to DRAFT)")
+    pad.add_argument("agent_id", help="Agent ID")
+    add_api_common_arguments(pad)
+    pad.set_defaults(func=handlers["delete"])
+
+    # -- run --
+    par = agents_sub.add_parser("run", help="Trigger an immediate run")
+    par.add_argument("agent_id", help="Agent ID")
+    add_api_common_arguments(par)
+    par.set_defaults(func=handlers["run"])
+
+    # -- runs --
+    pars = agents_sub.add_parser("runs", help="List recent runs for an agent")
+    pars.add_argument("agent_id", help="Agent ID")
+    pars.add_argument("--limit", type=int, default=10, help="Max runs to return (default: 10)")
+    add_api_common_arguments(pars)
+    pars.set_defaults(func=handlers["runs"])
+
+    # -- watch --
+    paw = agents_sub.add_parser("watch", help="Trigger a run and poll until complete")
+    paw.add_argument("agent_id", help="Agent ID")
+    paw.add_argument("--interval", type=int, default=10, help="Poll interval in seconds (default: 10)")
+    paw.add_argument("--max-wait", dest="max_wait", type=int, default=1800, help="Max wait in seconds (default: 1800)")
+    add_api_common_arguments(paw)
+    paw.set_defaults(func=handlers["watch"])
+
+    # -- generate-persona --
+    pagp = agents_sub.add_parser("generate-persona", help="Generate ICP persona config via AI")
+    pagp.add_argument("--target", choices=["LEADS", "COMPANIES"], default="LEADS", help="Target type")
+    pagp.add_argument("--current-config", dest="current_config", help="Path to current persona config JSON")
+    add_api_common_arguments(pagp)
+    pagp.set_defaults(func=handlers["generate_persona"])
+
+    # -- generate-topics --
+    pagt = agents_sub.add_parser("generate-topics", help="Generate signal topic suggestions via AI")
+    pagt.add_argument("--target", choices=["LEADS", "COMPANIES"], default="LEADS", help="Target type")
+    pagt.add_argument("--persona", help="Path to persona config JSON")
+    pagt.add_argument("--current-topics", dest="current_topics", help="Comma-separated current topics")
+    add_api_common_arguments(pagt)
+    pagt.set_defaults(func=handlers["generate_topics"])
+
+    # -- generate-job-signal --
+    pagj = agents_sub.add_parser("generate-job-signal", help="Generate job signal config via AI")
+    pagj.add_argument("--target", choices=["LEADS", "COMPANIES"], default="LEADS", help="Target type")
+    pagj.add_argument("--persona", help="Path to persona config JSON")
+    pagj.add_argument("--current-titles", dest="current_titles", help="Comma-separated current job titles")
+    pagj.add_argument("--current-keywords", dest="current_keywords", help="Comma-separated current keywords")
+    add_api_common_arguments(pagj)
+    pagj.set_defaults(func=handlers["generate_job_signal"])
+
+    # -- signals --
+    pass_ = agents_sub.add_parser("signals", help="List available signal skill packs")
+    add_api_common_arguments(pass_)
+    pass_.set_defaults(func=handlers["signals"])
+
+
+def _bool_arg(v: str) -> bool:
+    """Parse boolean CLI argument values."""
+    if v.lower() in ("true", "1", "yes"):
+        return True
+    if v.lower() in ("false", "0", "no"):
+        return False
+    raise argparse.ArgumentTypeError(f"Expected true/false, got: {v}")

{autotouch_cli-0.2.60 → autotouch_cli-0.2.63}/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.60 → autotouch_cli-0.2.63}/autotouch_cli/data/CLI_REFERENCE.md

@@ -1,6 +1,6 @@
 # Autotouch CLI Reference
 
-Generated from the installed parser for `autotouch-cli` `0.2.60`.
+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.60 → autotouch_cli-0.2.63}/autotouch_cli/data/cli-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.60",
+  "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.60 → autotouch_cli-0.2.63}/autotouch_cli/parser.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import argparse
 from typing import Any, Callable, Dict, List, Optional
 
+from autotouch_cli.commands.agents import register_agents_subcommands
 from autotouch_cli.commands.auth import register_auth_subcommands
 from autotouch_cli.commands.cells import register_cells_subcommands
 from autotouch_cli.commands.columns import register_columns_subcommands
@@ -756,6 +757,26 @@ def build_parser(
         recipe_types=LINKEDIN_RECIPE_TYPES,
     )
 
+    # agents
+    register_agents_subcommands(
+        sub,
+        add_api_common_arguments=add_api,
+        handlers={
+            "list": commands["agents_list"],
+            "get": commands["agents_get"],
+            "create": commands["agents_create"],
+            "update": commands["agents_update"],
+            "delete": commands["agents_delete"],
+            "run": commands["agents_run"],
+            "runs": commands["agents_runs"],
+            "watch": commands["agents_watch"],
+            "generate_persona": commands["agents_generate_persona"],
+            "generate_topics": commands["agents_generate_topics"],
+            "generate_job_signal": commands["agents_generate_job_signal"],
+            "signals": commands["agents_signals"],
+        },
+    )
+
     # Backward-compatible aliases
     # run
     palias_run = sub.add_parser("run", help="Alias for: columns run")

{autotouch_cli-0.2.60 → autotouch_cli-0.2.63}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.60
+Version: 0.2.63
 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
@@ -158,6 +158,11 @@ For `llm_enrichment` in `agent` mode, the recommended path is:
 
 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.
 
+Schema ownership rules:
+- Accepted generated schemas and explicit user schemas are the saved output contract.
+- Row execution must not add fields, rename fields, or replace a valid locked schema.
+- Agent-mode evidence/scored state decides which values may fill the schema; the finalizer formats those values and schema validation gates persistence.
+
 Prompt variables in authored prompts support nested JSON access:
 - Use flat row variables like `{{company_name}}` for scalar columns.
 - Use dotted placeholders like `{{linkedin_lookup.linkedin_url}}` when the source column stores JSON or stringified JSON.

{autotouch_cli-0.2.60 → autotouch_cli-0.2.63}/autotouch_cli.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ autotouch_cli.egg-info/entry_points.txt
 autotouch_cli.egg-info/requires.txt
 autotouch_cli.egg-info/top_level.txt
 autotouch_cli/commands/__init__.py
+autotouch_cli/commands/agents.py
 autotouch_cli/commands/auth.py
 autotouch_cli/commands/cells.py
 autotouch_cli/commands/columns.py

{autotouch_cli-0.2.60 → autotouch_cli-0.2.63}/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")
 
@@ -211,7 +219,7 @@ _FORMATTER_POLICY = AutoRunExecutionPolicy(
 
 _LLM_POLICY = AutoRunExecutionPolicy(
     name="llm",
-    orchestrator_provider="gemini",
+    orchestrator_provider="llm",
     paid=True,
     force_rerun=False,
     respect_existing_done=True,
@@ -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.",
@@ -786,10 +795,10 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             },
         },
         recipe_notes=(
-            "companyDomain is required; LinkedIn is optional.",
+            "Strict mode requires `companyDomain`; 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.",
+            "Strict single-mode sync can use either a usable hard-identity mapping (LinkedIn, email, or phone) or mapped `firstName` / `lastName` values that create a provisional lead.",
+            "If `companyDomain` is missing in the table, derive or enrich that domain column first, or explicitly opt into `config.requireCompanyDomain=false` for LinkedIn-first sync.",
             "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.",
             "Sync to Leads is non-billable.",
@@ -803,7 +812,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             "requirements": {
                 "config_provider": "add_to_crm",
                 "field_mappings": "required",
-                "eligibility": "company domain plus at least one valid LinkedIn URL, email, or phone must resolve from mapped source columns",
+                "eligibility": "strict mode requires company domain plus either a usable hard identity signal (LinkedIn, email, or phone) or, in single mode, mapped firstName/lastName; LinkedIn-first mode requires linkedinUrl when companyDomain is optional",
             },
             "billing": {
                 "billable": False,
@@ -815,7 +824,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
             "primary_provider_value": "add_to_crm",
             "field_mappings_field": "config.fieldMappings",
             "source_columns_field": "config.sourceColumns",
-            "eligibility": "company domain plus at least one valid LinkedIn URL, email, or phone must resolve from mapped source columns",
+            "eligibility": "strict mode requires company domain plus either a usable hard identity signal (LinkedIn, email, or phone) or, in single mode, mapped firstName/lastName; LinkedIn-first mode requires linkedinUrl when companyDomain is optional",
             "replay_behavior": "source updates only; explicit run required to backfill older upstream results",
             "structured_source_mapping": {
                 "rule": "primitive columns map directly; structured columns use {column, path}",
@@ -830,7 +839,7 @@ _PROVIDER_CONTRACTS: Tuple[ResearchTableProviderContract, ...] = (
         composition_contract={
             "consumes": {
                 "kind": "crm_export_inputs",
-                "shape": "mapped source row values including company domain plus LinkedIn/email/phone identity; structured source columns use explicit {column, path} mappings to identify the exact field",
+                "shape": "mapped source row values including company domain plus hard identity or, in single mode, provisional firstName/lastName fallback; structured source columns use explicit {column, path} mappings to identify the exact field",
             },
             "produces": {
                 "kind": "lead_ids",
@@ -1357,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(
@@ -1549,7 +1590,7 @@ def orchestrated_runtime_provider_keys(*, include_formatter: bool = False) -> Tu
                 providers.append(policy.orchestrator_provider)
             continue
         if contract.key == "llm":
-            providers.extend(["gemini", "xai"])
+            providers.extend(["llm", "gemini", "xai"])
             continue
         providers.append(policy.orchestrator_provider)
     return tuple(dict.fromkeys(provider for provider in providers if provider))
@@ -1586,9 +1627,9 @@ def resolve_runtime_orchestrator_provider(
         return None
     if contract.key == "llm":
         runtime_provider = _normalize((config or {}).get("provider"))
-        if runtime_provider in {"gemini", "xai"}:
+        if runtime_provider in {"llm", "gemini", "xai"}:
             return runtime_provider
-        if runtime_provider in {"", "llm"}:
+        if not runtime_provider:
             return contract.execution_policy.orchestrator_provider
         return None
     return contract.execution_policy.orchestrator_provider

{autotouch_cli-0.2.60 → autotouch_cli-0.2.63}/pyproject.toml

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