@hotmeshio/long-tail 0.1.7 → 0.1.8

package/docs/api/sdk/yaml-workflows.md

@@ -0,0 +1,408 @@
+# lt.yamlWorkflows
+
+Manage YAML workflow lifecycle: create, deploy, invoke, version, and schedule cron jobs.
+
+## list
+
+List YAML workflows with optional filtering and pagination.
+
+```typescript
+const result = await lt.yamlWorkflows.list({ status: 'active', app_id: 'longtail', limit: 20 });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | `string` | No | Lifecycle filter (`draft`, `deployed`, `active`, `archived`) |
+| `graph_topic` | `string` | No | Filter by HotMesh subscription topic |
+| `app_id` | `string` | No | Filter by namespace (MCP server name) |
+| `search` | `string` | No | Free-text search across name/description |
+| `source_workflow_id` | `string` | No | Filter by source execution trace ID |
+| `set_id` | `string` | No | Filter by compositional set membership |
+| `limit` | `number` | No | Max rows to return |
+| `offset` | `number` | No | Pagination offset |
+
+**Returns:** `LTApiResult<YamlWorkflow[]>`
+
+**Auth:** Not required
+
+---
+
+## create
+
+Compile an execution trace into a new YAML workflow draft via the LLM-based generator.
+
+```typescript
+const result = await lt.yamlWorkflows.create({
+  workflow_id: 'wf_abc',
+  task_queue: 'v1',
+  workflow_name: 'screenshot_analyze',
+  name: 'screenshot_analyze_store',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflow_id` | `string` | Yes | ID of the source execution trace to compile from |
+| `task_queue` | `string` | Yes | HotMesh task queue the source execution ran on |
+| `workflow_name` | `string` | Yes | Type name of the source workflow |
+| `name` | `string` | Yes | Tool name for the new workflow (no dashes) |
+| `description` | `string` | No | Human-readable description passed to the generator |
+| `app_id` | `string` | No | Target namespace (defaults to `"longtail"`) |
+| `subscribes` | `string` | No | Explicit subscription topic override |
+| `tags` | `string[]` | No | Additional tags merged with auto-derived tags |
+| `compilation_feedback` | `string` | No | Natural-language feedback to steer the LLM compilation |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## createDirect
+
+Create a YAML workflow directly from user-supplied YAML content (no compilation).
+
+```typescript
+const result = await lt.yamlWorkflows.createDirect({
+  name: 'my_tool',
+  yaml_content: yamlString,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Tool name (sanitized to lowercase alphanumeric, periods, dashes, underscores) |
+| `description` | `string` | No | Human-readable description |
+| `yaml_content` | `string` | Yes | Raw HotMesh YAML definition |
+| `input_schema` | `object` | No | JSON Schema describing the workflow's input (defaults to `{}`) |
+| `activity_manifest` | `any[]` | No | List of activity declarations (defaults to `[]`) |
+| `tags` | `string[]` | No | Classification tags (defaults to `[]`) |
+| `app_id` | `string` | No | Target namespace (defaults to `"longtail"`) |
+| `graph_topic` | `string` | No | Subscription topic override (defaults to sanitized name) |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## getAppIds
+
+Retrieve all distinct app_id namespaces that have at least one YAML workflow.
+
+```typescript
+const result = await lt.yamlWorkflows.getAppIds({});
+```
+
+**Parameters:** None (pass `{}`).
+
+**Returns:** `LTApiResult<{ app_ids: string[] }>`
+
+**Auth:** Not required
+
+---
+
+## get
+
+Fetch a single YAML workflow by its primary key.
+
+```typescript
+const result = await lt.yamlWorkflows.get({ id: 'uuid-here' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow record |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## update
+
+Partially update a YAML workflow record.
+
+```typescript
+const result = await lt.yamlWorkflows.update({ id: 'uuid-here', name: 'new_name', tags: ['updated'] });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to update |
+| `[key]` | `any` | No | Any mutable workflow field (name, description, yaml_content, tags, etc.) |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## regenerate
+
+Re-compile an existing YAML workflow from its original execution trace.
+
+```typescript
+const result = await lt.yamlWorkflows.regenerate({
+  id: 'uuid-here',
+  compilation_feedback: 'Add error handling for the upload step',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to regenerate |
+| `task_queue` | `string` | No | Override the task queue (otherwise resolved from source task) |
+| `compilation_feedback` | `string` | No | Natural-language feedback to steer the re-compilation |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## delete
+
+Permanently delete a YAML workflow record. Only draft or archived workflows can be deleted.
+
+```typescript
+const result = await lt.yamlWorkflows.delete({ id: 'uuid-here' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to delete |
+
+**Returns:** `LTApiResult<{ deleted: true }>`
+
+**Auth:** Not required
+
+---
+
+## deploy
+
+Deploy a YAML workflow and all sibling workflows sharing its app_id namespace.
+
+```typescript
+const result = await lt.yamlWorkflows.deploy({ id: 'uuid-here' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to deploy |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## activate
+
+Activate a previously deployed YAML workflow and its app_id siblings.
+
+```typescript
+const result = await lt.yamlWorkflows.activate({ id: 'uuid-here' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to activate |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## invoke
+
+Invoke an active YAML workflow, executing its DAG pipeline.
+
+```typescript
+const result = await lt.yamlWorkflows.invoke({
+  id: 'uuid-here',
+  data: { url: 'https://example.com' },
+  sync: true,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to invoke |
+| `data` | `any` | No | Input payload passed to the workflow's entry point |
+| `sync` | `boolean` | No | When true, block until the workflow completes and return its output |
+| `timeout` | `number` | No | Max milliseconds to wait when `sync` is true |
+| `execute_as` | `string` | No | Override identity for the execution context |
+
+**Returns:** `LTApiResult<any>`
+
+**Auth:** Optional (userId forwarded to invoke service when provided)
+
+---
+
+## archive
+
+Archive a YAML workflow, removing it from active service.
+
+```typescript
+const result = await lt.yamlWorkflows.archive({ id: 'uuid-here' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to archive |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## getVersionHistory
+
+Retrieve the version history for a YAML workflow.
+
+```typescript
+const result = await lt.yamlWorkflows.getVersionHistory({ id: 'uuid-here', limit: 10 });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow |
+| `limit` | `number` | No | Max versions to return (default 20) |
+| `offset` | `number` | No | Pagination offset (default 0) |
+
+**Returns:** `LTApiResult<VersionSnapshot[]>`
+
+**Auth:** Not required
+
+---
+
+## getVersionSnapshot
+
+Retrieve a specific version snapshot of a YAML workflow.
+
+```typescript
+const result = await lt.yamlWorkflows.getVersionSnapshot({ id: 'uuid-here', version: 3 });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow |
+| `version` | `number` | Yes | 1-based version number to retrieve |
+
+**Returns:** `LTApiResult<VersionSnapshot>`
+
+**Auth:** Not required
+
+---
+
+## getYamlContent
+
+Retrieve the raw YAML content for a workflow, optionally at a specific version.
+
+```typescript
+const result = await lt.yamlWorkflows.getYamlContent({ id: 'uuid-here' });
+const result = await lt.yamlWorkflows.getYamlContent({ id: 'uuid-here', version: 2 });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow |
+| `version` | `number` | No | Version number; when omitted, returns the current content |
+
+**Returns:** `LTApiResult<string>`
+
+**Auth:** Not required
+
+---
+
+## setCronSchedule
+
+Set or update the cron schedule for a YAML workflow.
+
+```typescript
+const result = await lt.yamlWorkflows.setCronSchedule({
+  id: 'uuid-here',
+  cron_schedule: '0 * * * *',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to schedule |
+| `cron_schedule` | `string` | Yes | Cron expression (e.g. `"0 * * * *"`) |
+| `cron_envelope` | `any` | No | Payload passed to each scheduled invocation |
+| `execute_as` | `string` | No | Identity override for scheduled executions |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## clearCronSchedule
+
+Remove the cron schedule from a YAML workflow.
+
+```typescript
+const result = await lt.yamlWorkflows.clearCronSchedule({ id: 'uuid-here' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | UUID of the workflow to unschedule |
+
+**Returns:** `LTApiResult<YamlWorkflow>`
+
+**Auth:** Not required
+
+---
+
+## getCronStatus
+
+List all YAML workflows that have a cron schedule, with their live timer status.
+
+```typescript
+const result = await lt.yamlWorkflows.getCronStatus({});
+```
+
+**Parameters:** None (pass `{}`).
+
+**Returns:** `LTApiResult<{ schedules: Array<{ id, name, graph_topic, app_id, cron_schedule, execute_as, active }> }>`
+
+**Auth:** Not required

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",