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

{autotouch_cli-0.2.28 → autotouch_cli-0.2.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.28
+Version: 0.2.31
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -21,7 +21,7 @@ Use this order when you are orienting in the CLI:
 2. Use the API endpoint -> CLI command map when translating an existing API workflow.
 3. Use `autotouch columns recipe` before creating provider-backed workflow columns.
 4. Use `autotouch jobs get` as the source of truth for async run state.
-5. Use `autotouch sequences ...` for sequence definitions, status changes, and direct enrollments; tasks still use raw HTTP.
+5. Use `autotouch sequences ...` for sequence definitions/enrollments and `autotouch tasks ...` for task queue work.
 
 ### Quick decision guide
 
@@ -39,17 +39,19 @@ Use this order when you are orienting in the CLI:
 | create/manage sequence definitions directly | `autotouch sequences recipe`, then `autotouch sequences create/update/activate` |
 | enroll leads directly into a sequence | `autotouch sequences enroll --sequence-id <SEQUENCE_ID> ...` |
 | enroll table rows into an existing sequence | `autotouch columns recipe --type add_to_sequence`, then `autotouch columns create` + `autotouch columns run` |
+| seed org context from a company website | `autotouch onboarding submit-domain --website acme.com` |
+| inspect or update org/personal value prop context | `autotouch org-context get/set`, `autotouch personal-context get/set`, `autotouch context resolved` |
 | create or update a CRM lead | `autotouch leads recipe --type create`, then `autotouch leads create` / `autotouch leads update` |
 | add email or phone contact info to a lead | `autotouch leads recipe --type contact_upsert`, then `autotouch leads upsert-contact-channels --lead-id <LEAD_ID> ...` |
 | bulk update lead status or owner | `autotouch leads update-status` / `autotouch leads reassign-owner` |
-| manage tasks directly | raw HTTP plus `docs/platform/external-workflows-api.md` |
+| manage tasks directly | `autotouch tasks query`, `autotouch tasks get`, `autotouch tasks update`, `autotouch tasks draft` |
 | query/filter CRM leads and attached research | `autotouch leads query` then `autotouch leads research` |
 
 ### Operating model
 
 - This file is the full CLI reference and the package readme published to PyPI.
 - The installed package gives you CLI entrypoints and package metadata; do not assume there is a separate installed docs directory.
-- Research-table APIs, sequence commands, and lead create/query/update operations are the primary CLI surface today; direct task management is still HTTP-first.
+- Research-table APIs, sequence commands, lead create/query/update operations, and public task-queue workflows are first-class CLI surface areas today.
 - For async operations, backend bulk-job state is authoritative; local terminal output is only a convenience layer.
 - For staged or cost-sensitive runs, estimate first and prefer filtered scopes plus `firstN` or `run-next`.
 
@@ -69,6 +71,13 @@ Developer keys and scopes are identical to raw API usage (`stk_...`, same scope
 autotouch auth set-key --api-key stk_... --base-url https://app.autotouch.ai
 autotouch auth check
 autotouch auth show
+autotouch auth whoami
+```
+
+For user/admin endpoints like onboarding, org context, and personal context, sign in with a user session too:
+
+```bash
+autotouch auth login --email ada@yourcompany.com
 ```
 
 Credentials are stored in `~/.config/autotouch/config.json` by default.
@@ -82,28 +91,46 @@ Developer key scope reference (including workflow scopes like `sequences:*` and
 If an agent/user does not have an account + developer key yet, bootstrap both in one call:
 
 ```bash
-curl -X POST "https://app.autotouch.ai/api/auth/agent-bootstrap" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "first_name": "Ada",
-    "last_name": "Lovelace",
-    "email": "ada@yourcompany.com",
-    "password": "use-a-strong-random-password",
-    "organization_name": "Your Company",
-    "key_name": "Agent bootstrap key"
-  }'
+autotouch auth bootstrap \
+  --first-name Ada \
+  --last-name Lovelace \
+  --email ada@yourcompany.com \
+  --password 'use-a-strong-random-password' \
+  --organization-name "Your Company" \
+  --save-key
 ```
 
-Then store the returned `apiKey`:
+Or pass a full payload file:
 
 ```bash
-autotouch auth set-key --api-key stk_... --base-url https://app.autotouch.ai
-autotouch auth check
+autotouch auth bootstrap --data-file bootstrap.json --save-key
 ```
 
 Notes:
 - New orgs created through signup/bootstrap start with `50` credits.
+- `--save-key` stores the returned `apiKey` and also signs in the same user so the saved config has both the developer key and the user session.
 - Identity linking is email-based: later human sign-in with the same normalized email maps to the same user/org.
+- `auth whoami` shows which user/org the saved session belongs to.
+
+## Onboarding and context
+
+Recommended setup for agent-mode LLM enrichment:
+
+```bash
+autotouch auth login --email ada@yourcompany.com
+autotouch onboarding submit-domain --website yourcompany.com
+autotouch org-context get
+autotouch personal-context get
+autotouch context resolved
+```
+
+Notes:
+- `submit-domain` seeds organization context from the company website.
+- `org-context set` is where you refine value proposition, ideal titles, buyer persona, user persona, and voice profile.
+- `personal-context set` is where you refine rep-specific title, territories, personal value proposition, and personal voice profile.
+- `context resolved` shows the effective requester context the enrichment/runtime layer will actually use after org + personal overrides.
+- Agent-mode prompt generation and compiled LLM enrichment prompts always include requester/company context.
+- Basic mode stays manual-prompt-first; write the prompt directly based on the user goal/preferences and include explicit placeholders when row data should be referenced.
 
 ## API endpoint -> CLI command map
 
@@ -170,7 +197,26 @@ Notes:
 | `POST /api/webhook-subscriptions/{subscription_id}/resume` | `autotouch webhooks subscriptions resume --subscription-id <SUBSCRIPTION_ID>` |
 | `POST /api/webhook-subscriptions/{subscription_id}/rotate-secret` | `autotouch webhooks subscriptions rotate-secret --subscription-id <SUBSCRIPTION_ID>` |
 | `POST /api/webhook-subscriptions/{subscription_id}/test` | `autotouch webhooks subscriptions test --subscription-id <SUBSCRIPTION_ID>` |
-| `POST /api/auth/agent-bootstrap` | HTTP-only bootstrap (no direct CLI wrapper yet) |
+| `POST /api/auth/agent-bootstrap` | `autotouch auth bootstrap --data-file bootstrap.json --save-key` |
+| `POST /api/auth/login` | `autotouch auth login --email ada@yourcompany.com` |
+| `POST /api/onboarding/submit-domain` | `autotouch onboarding submit-domain --website yourcompany.com` |
+| `GET /api/org/context` | `autotouch org-context get` |
+| `POST /api/org/context` | `autotouch org-context set --data-file org-context.json` |
+| `GET /api/onboarding/personal-context` | `autotouch personal-context get` |
+| `POST /api/onboarding/personal-context` | `autotouch personal-context set --data-file personal-context.json` |
+| `GET /api/llm/company-context` | `autotouch context resolved` |
+| `POST /api/task-queue/query` | `autotouch tasks query --data-file task-query.json` |
+| `POST /api/task-queue/query/count` | `autotouch tasks count --data-file task-query.json` |
+| `POST /api/task-queue/assignee-counts` | `autotouch tasks assignee-counts --data-file task-query.json` |
+| `GET /api/task-queue/{task_id}` | `autotouch tasks get --task-id <TASK_ID>` |
+| `GET /api/task-queue/stats/summary` | `autotouch tasks stats` |
+| `POST /api/task-queue/create` | `autotouch tasks create --data-file task-create.json --actor-user-id <USER_ID>` |
+| `PUT /api/task-queue/{task_id}` | `autotouch tasks update --task-id <TASK_ID> --data-file task-update.json --actor-user-id <USER_ID>` |
+| `DELETE /api/task-queue/{task_id}` | `autotouch tasks delete --task-id <TASK_ID> --actor-user-id <USER_ID>` |
+| `POST /api/task-queue/bulk-update` | `autotouch tasks bulk-update --data-file task-bulk-update.json --actor-user-id <USER_ID>` |
+| `POST /api/task-queue/bulk-delete` | `autotouch tasks bulk-delete --data-file task-bulk-delete.json --actor-user-id <USER_ID>` |
+| `POST /api/task-queue/{task_id}/draft` | `autotouch tasks draft --task-id <TASK_ID> --force --actor-user-id <USER_ID>` |
+| `POST /api/task-queue/{task_id}/email/schedule` | `autotouch tasks schedule-email --task-id <TASK_ID> --data-file schedule.json --actor-user-id <USER_ID>` |
 
 ## Delete column
 
@@ -188,7 +234,6 @@ autotouch columns delete --table-id <TABLE_ID> --column-id <COLUMN_ID> --yes
 ## Sequence commands
 
 The CLI now exposes the public Sequences endpoints under `autotouch sequences`.
-Tasks still use raw HTTP plus `docs/platform/external-workflows-api.md`.
 
 Common commands:
 - `autotouch sequences recipe --type create --out-file sequence.json`
@@ -215,7 +260,6 @@ Important contract notes:
 - `autotouch sequences enroll --wait` polls `/api/bulk-jobs/{job_id}` and preserves the API response `task_id` as the bulk job id.
 - Research-table `add_to_sequence` is still available through `autotouch columns create/update/run` and still targets an existing sequence.
 - Real enrollment requires the target sequence to be `ACTIVE` unless direct enroll uses `reviewOnly=true`.
-- Tasks remain HTTP-only.
 
 AI draft outputs:
 - Manual new email: subject + body
@@ -379,6 +423,60 @@ autotouch leads filters-metadata
 autotouch leads research-tables
 ```
 
+## Task commands
+
+The CLI now exposes the public task queue endpoints under `autotouch tasks`.
+
+Use this pattern:
+
+1. `autotouch tasks query` to page through tasks with the same `TaskQueryRequest` payload used by the API.
+2. `autotouch tasks get` when you need one fully hydrated task by id.
+3. `autotouch tasks create` for direct task creation from a JSON payload.
+4. `autotouch tasks update` / `autotouch tasks bulk-update` for task status, owner, due date, and content changes.
+5. `autotouch tasks draft` when you need just-in-time AI generation for a manual-capable task.
+6. `autotouch tasks schedule-email` to schedule or immediately send a personal/manual email task.
+7. `autotouch tasks delete` / `autotouch tasks bulk-delete` to soft-delete tasks by marking them skipped.
+
+Important contract notes:
+- Mutating task commands accept `--actor-user-id` for developer-key actor resolution.
+- Query/count/assignee-counts use the backend `TaskQueryRequest` JSON shape directly.
+- `draft` supports `--force` if you want to re-generate content even when a task already has content.
+- `schedule-email` expects the same payload as `POST /api/task-queue/{task_id}/email/schedule`.
+- AI draft outputs follow the same step behavior as sequences:
+  - manual new email: subject + body
+  - manual reply email: reply body
+  - LinkedIn connect: connection note
+  - LinkedIn message: message copy
+  - call: call script
+
+Examples:
+
+```bash
+autotouch tasks query --data-file task-query.json
+autotouch tasks count --data-file task-query.json
+autotouch tasks assignee-counts --data-file task-query.json
+```
+
+```bash
+autotouch tasks get --task-id <TASK_ID>
+autotouch tasks stats
+```
+
+```bash
+autotouch tasks create --data-file task-create.json --actor-user-id <USER_ID>
+autotouch tasks update --task-id <TASK_ID> --data-file task-update.json --actor-user-id <USER_ID>
+```
+
+```bash
+autotouch tasks draft --task-id <TASK_ID> --force --actor-user-id <USER_ID>
+autotouch tasks schedule-email --task-id <TASK_ID> --data-file schedule.json --actor-user-id <USER_ID>
+```
+
+```bash
+autotouch tasks bulk-update --data-file task-bulk-update.json --actor-user-id <USER_ID>
+autotouch tasks bulk-delete --data-file task-bulk-delete.json --actor-user-id <USER_ID>
+```
+
 ## Bulk job status contract (authoritative run state)
 
 Use bulk jobs as the source of truth for run lifecycle:
@@ -496,6 +594,8 @@ Recommendation:
 
 ### 4) `llm_enrichment`
 
+Recommended for `agent` mode: use `instructions` and let the API compile the runnable prompt. In `basic` mode, write the prompt directly and keep it tailored to the user goal/preferences.
+
 `llm-enrichment.json`:
 
 ```json
@@ -507,17 +607,48 @@ Recommendation:
   "origin": "ai",
   "autoRun": "never",
   "config": {
-    "prompt": "Research this company and return JSON with icp_fit, summary, and risks.",
+    "instructions": "Research the company in this row and return JSON with icp_fit, summary, and risks.",
     "mode": "agent",
     "temperature": 0.7,
     "batchSize": 50,
-    "promptSource": "manual",
+    "promptSource": "generated",
+    "useCompanyContext": true,
     "structuredOutput": true,
     "useAutoSchema": true
   }
 }
 ```
 
+Notes:
+- In `agent` mode, `instructions` is the recommended authoring surface.
+- The API compiles those instructions into the stored runnable prompt on create/update.
+- Company/requester context is always enabled for generated `agent`-mode prompts.
+- In `basic` mode, the recommended path is a hand-authored prompt. Use explicit placeholders like `{{company_name}}`, `{{domain}}`, or requester context placeholders from `autotouch context resolved` when the prompt should reference row/requester data.
+
+Prompt variables:
+- Row variables come from the current table row, for example `{{company_name}}`, `{{domain}}`, `{{first_name}}`, `{{linkedin_url}}`.
+- Requester/company-context variables come from onboarding + org/personal context, for example `{{user_company_name}}`, `{{user_value_proposition}}`, `{{buyer_persona}}`, `{{user_persona}}`.
+- The runtime only injects variables that the prompt explicitly references. If the prompt needs row/context data, include those `{{...}}` placeholders directly.
+- Use `autotouch context resolved` to inspect the requester/company-context variables available for the current user/session.
+
+Basic-mode example:
+
+```json
+{
+  "key": "fit_summary",
+  "label": "Fit Summary",
+  "kind": "enrichment",
+  "dataType": "text",
+  "origin": "ai",
+  "autoRun": "never",
+  "config": {
+    "mode": "basic",
+    "prompt": "Write a short fit summary for {{company_name}} (website {{domain}}) and explain why it matches {{user_value_proposition}}.",
+    "useCompanyContext": true
+  }
+}
+```
+
 If you provide a custom schema, use strict Schema V2 field-map shape:
 
 ```json
@@ -738,7 +869,7 @@ Sequence creation note:
 - The CLI can create/update/activate sequence definitions directly with `autotouch sequences ...`.
 - Research-table `add_to_sequence` columns and direct `autotouch sequences enroll` both target an existing sequence.
 - Real enrollment still requires that sequence to be `ACTIVE` unless direct enroll uses `reviewOnly=true`.
-- Tasks still use raw HTTP.
+- Downstream task queue work is available through `autotouch tasks ...`.
 
 ## Safe run patterns (`firstN` + `--unprocessed-only`)