@kairos-sdk/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Krutman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# @kairos-sdk/core
+
+**Turn plain English into deployed n8n workflows.**
+
+Kairos is a TypeScript SDK that takes a natural-language description of an automation, calls Claude to generate valid n8n workflow JSON, runs it through a 19-rule validator with an automatic correction loop, and deploys it to your n8n instance via REST API — all in a single `build()` call.
+
+```ts
+import { Kairos } from '@kairos-sdk/core'
+
+const kairos = new Kairos({
+  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
+  n8nBaseUrl: 'https://your-instance.app.n8n.cloud',
+  n8nApiKey: process.env.N8N_API_KEY!,
+})
+
+const result = await kairos.build(
+  'Every morning at 9am, send a message to #daily-digest on Slack saying "Good morning team!"'
+)
+
+console.log(result.workflowId)      // deployed workflow ID
+console.log(result.credentialsNeeded) // what the user still needs to configure
+```
+
+---
+
+## Installation
+
+```bash
+npm install @kairos-sdk/core @anthropic-ai/sdk
+```
+
+`@anthropic-ai/sdk` is a peer dependency — install it alongside Kairos.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- An [Anthropic API key](https://console.anthropic.com)
+- An n8n instance with API access enabled (Cloud or self-hosted)
+
+---
+
+## Quick Start
+
+```ts
+import { Kairos } from '@kairos-sdk/core'
+
+const kairos = new Kairos({
+  anthropicApiKey: 'sk-ant-...',
+  n8nBaseUrl: 'https://your-instance.app.n8n.cloud',
+  n8nApiKey: 'your-n8n-api-key',
+})
+
+// Dry run — generates and validates but does not deploy
+const preview = await kairos.build(
+  'Receive a webhook, call an external API, and store the result in Google Sheets',
+  { dryRun: true }
+)
+
+console.log(preview.name)               // workflow name Claude chose
+console.log(preview.generationAttempts) // 1–3 (correction loop)
+console.log(preview.credentialsNeeded)  // services that need credentials configured
+
+// Live deploy
+const deployed = await kairos.build(
+  'Receive a webhook, call an external API, and store the result in Google Sheets'
+)
+
+console.log(deployed.workflowId) // now live in n8n
+```
+
+---
+
+## How It Works
+
+1. **Generate** — Kairos sends your description to Claude with a detailed system prompt and forces a `generate_workflow` tool call, producing structured n8n workflow JSON.
+2. **Validate** — The workflow is checked against 19 rules covering node structure, connection integrity, forbidden fields, trigger presence, AI connection direction, and more.
+3. **Correct** — If validation fails, Kairos automatically sends the issues back to Claude and retries (up to 3 attempts, with tighter temperature on the final try).
+4. **Strip** — Forbidden server-assigned fields (`id`, `createdAt`, `updatedAt`, etc.) are stripped before deployment.
+5. **Deploy** — The validated workflow is posted to your n8n instance via REST API.
+
+---
+
+## API Reference
+
+### `new Kairos(options)`
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `anthropicApiKey` | `string` | ✓ | Anthropic API key |
+| `n8nBaseUrl` | `string` | ✓ | Base URL of your n8n instance |
+| `n8nApiKey` | `string` | ✓ | n8n API key |
+| `model` | `string` | | Claude model to use (default: `claude-sonnet-4-6`) |
+| `logger` | `ILogger` | | Custom logger (default: silent) |
+| `telemetry` | `boolean \| string` | | Enable JSONL telemetry logging (`true` for default dir, or a path) |
+| `library` | `IWorkflowLibrary` | | Workflow library for RAG (default: `NullLibrary`) |
+
+---
+
+### `kairos.build(description, options?)`
+
+Generates and optionally deploys a workflow from a plain-English description.
+
+```ts
+const result = await kairos.build(description, {
+  dryRun: false,   // set true to skip deployment
+  name: 'My Workflow', // override the generated name
+})
+```
+
+**Returns `BuildResult`:**
+
+```ts
+{
+  workflowId: string | null  // null on dry run
+  name: string
+  generationAttempts: number  // 1–3
+  activationRequired: boolean // true if workflow needs manual activation
+  credentialsNeeded: Array<{
+    service: string
+    credentialType: string
+    description: string
+  }>
+  dryRun: boolean
+}
+```
+
+---
+
+### Workflow management
+
+```ts
+// List all workflows
+const workflows = await kairos.list()
+
+// Get a specific workflow
+const workflow = await kairos.get(workflowId)
+
+// Update a workflow from a new description
+const updated = await kairos.update(workflowId, 'new description')
+
+// Activate / deactivate
+await kairos.activate(workflowId)
+await kairos.deactivate(workflowId)
+
+// Delete (requires explicit confirmation)
+await kairos.delete(workflowId, { confirm: true })
+```
+
+---
+
+### Executions
+
+```ts
+// List recent executions for a workflow
+const executions = await kairos.executions(workflowId, { limit: 20 })
+
+// Get a specific execution with full details
+const detail = await kairos.execution(executionId)
+```
+
+---
+
+### Tags
+
+```ts
+const tags = await kairos.listTags()
+const newTag = await kairos.createTag('production')
+await kairos.tag(workflowId, [newTag.id])
+await kairos.untag(workflowId, [newTag.id])
+```
+
+---
+
+## Error Handling
+
+All errors extend `KairosError` so you can catch them at different levels of specificity:
+
+```ts
+import {
+  KairosError,
+  GenerationError,
+  ValidationError,
+  ApiError,
+  GuardError,
+} from '@kairos-sdk/core'
+
+try {
+  await kairos.build('...')
+} catch (err) {
+  if (err instanceof ValidationError) {
+    // Claude failed to produce a valid workflow after 3 attempts
+    for (const issue of err.issues) {
+      console.error(`[Rule ${issue.rule}] ${issue.message}`)
+    }
+  } else if (err instanceof GenerationError) {
+    // Anthropic API call failed (auth, quota, timeout)
+    console.error(err.message, err.cause)
+  } else if (err instanceof ApiError) {
+    // n8n returned a 4xx/5xx
+    console.error(`n8n error ${err.statusCode}:`, err.message)
+  } else if (err instanceof KairosError) {
+    // Any other SDK error
+    console.error(err.message)
+  }
+}
+```
+
+| Error class | When it's thrown |
+|---|---|
+| `GenerationError` | Anthropic API call failed |
+| `ResponseParseError` | Claude responded but produced no usable tool call |
+| `ValidationError` | Workflow failed 19-rule validation after max retries |
+| `ProviderError` | Network/auth failure talking to n8n |
+| `ApiError` | n8n returned a 4xx or 5xx (carries `.statusCode`) |
+| `GuardError` | `delete()` called without `{ confirm: true }` |
+
+---
+
+## CLI
+
+Deploy workflows from the command line — no code required:
+
+```bash
+# Generate and deploy
+kairos build "Every morning at 9am, send a Slack digest to #daily-updates"
+
+# Dry run only
+kairos build "Monitor a webhook and log payloads" --dry-run
+
+# Manage workflows
+kairos list
+kairos get <workflow-id>
+kairos activate <workflow-id>
+kairos deactivate <workflow-id>
+kairos delete <workflow-id> --confirm
+```
+
+Set your credentials as environment variables:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+export N8N_BASE_URL=https://your-instance.app.n8n.cloud
+export N8N_API_KEY=your-n8n-key
+```
+
+---
+
+## Telemetry
+
+Enable telemetry to log every generation attempt, validation result, and token usage to JSONL:
+
+```ts
+const kairos = new Kairos({
+  anthropicApiKey: '...',
+  n8nBaseUrl: '...',
+  n8nApiKey: '...',
+  telemetry: true, // writes to ~/.kairos/telemetry/
+})
+```
+
+Or specify a custom directory:
+
+```ts
+telemetry: '/path/to/telemetry/dir'
+```
+
+Each event includes timestamp, session ID, token counts, validation issues, and duration — useful for benchmarking and analyzing the correction loop.
+
+For CLI usage, set `KAIROS_TELEMETRY=true` in your environment.
+
+---
+
+## Workflow Library (RAG)
+
+Kairos includes a file-based workflow library that stores successful generations and uses them as few-shot examples for future builds:
+
+```ts
+import { Kairos, FileLibrary } from '@kairos-sdk/core'
+
+const kairos = new Kairos({
+  anthropicApiKey: '...',
+  n8nBaseUrl: '...',
+  n8nApiKey: '...',
+  library: new FileLibrary(), // stores in ~/.kairos/library/
+})
+```
+
+Every successful `build()` is saved automatically. Over time, the library improves generation quality by providing relevant examples to Claude — a self-improving few-shot learning system.
+
+---
+
+## Custom Logger
+
+```ts
+const kairos = new Kairos({
+  anthropicApiKey: '...',
+  n8nBaseUrl: '...',
+  n8nApiKey: '...',
+  logger: {
+    debug: (msg, meta) => console.debug(msg, meta),
+    info: (msg, meta) => console.info(msg, meta),
+    warn: (msg, meta) => console.warn(msg, meta),
+    error: (msg, meta) => console.error(msg, meta),
+  },
+})
+```
+
+---
+
+## Supported n8n Node Types
+
+Kairos knows about 60+ n8n nodes out of the box, including:
+
+- **Triggers:** Webhook, Schedule, Chat, Manual, Email, GitHub, Telegram
+- **Core:** HTTP Request, Set, If, Switch, Merge, Code, Wait
+- **Apps:** Slack, Gmail, Google Sheets, Notion, Airtable, GitHub, Telegram
+- **Data:** PostgreSQL, Redis, S3, Execute SQL
+- **AI (LangChain):** Agent, OpenAI Chat Model, Anthropic Claude Model, Buffer Memory, Tool Workflow, Vector Store Retriever
+
+---
+
+## License
+
+MIT — © 2026 Jordan Krutman