@kairos-sdk/core 0.5.0 → 0.6.0

package/README.md

@@ -1,17 +1,17 @@
 # @kairos-sdk/core
 
-[![CI](https://github.com/Kruttz/kairos-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Kruttz/kairos-sdk/actions/workflows/ci.yml)
+[![CI](https://github.com/Kruttz/Kairos/actions/workflows/ci.yml/badge.svg)](https://github.com/Kruttz/Kairos/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@kairos-sdk/core)](https://www.npmjs.com/package/@kairos-sdk/core)
 [![npm downloads](https://img.shields.io/npm/dw/@kairos-sdk/core)](https://www.npmjs.com/package/@kairos-sdk/core)
 
-**Turn plain English into deployed n8n workflows — validated, corrected, and deployed in one call.**
+**Kairos is an AI workflow delivery engine for n8n. Give it a business context and it generates, validates, deploys, and documents a complete workflow pack — then learns from real executions and repairs over time.**
 
 ![Kairos SDK Demo](demo.gif)
 
-Kairos turns plain-English workflow descriptions into validated, deployable n8n workflow JSON. Use it as an **MCP server** (connect to Claude Code, Claude Desktop, or any MCP host — your LLM generates, Kairos validates and deploys, no Anthropic API key needed) or as a **TypeScript SDK** for programmatic control (calls Claude internally with a specialized prompt). Either way, workflows pass through a **34-rule structural validator** with automatic correction, and a local workflow library with **hybrid retrieval** (TF-IDF + node fingerprinting + outcome history + cluster reranking) injects past failure patterns into future generations. With a seeded template library, Kairos achieves **100% first-try structural validation pass rate** across 20 benchmark prompts (meaning the generated JSON is structurally valid on the first attempt — runtime behavior depends on your credentials and node configuration).
+Describe your business and Kairos builds a full suite of n8n automations: it plans the workflows, generates each one via Claude, validates every node and connection against **34 structural rules**, deploys to your n8n instance, and hands back a structured document covering credentials needed, data sources, assumptions made, open questions, and a test checklist. Use it as an **MCP server** (connect to Claude Code, Claude Desktop, or any MCP host — no Anthropic API key needed), a **TypeScript SDK**, or a **CLI**. With a seeded template library, Kairos achieves **100% first-try structural validation pass rate** across 20 benchmark prompts.
 
 ```ts
-import { Kairos } from '@kairos-sdk/core'
+import { Kairos, PackBuilder } from '@kairos-sdk/core'
 
 const kairos = new Kairos({
   anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
@@ -19,12 +19,20 @@ const kairos = new Kairos({
   n8nApiKey: process.env.N8N_API_KEY!,
 })
 
+// Build a single workflow
 const result = await kairos.build(
-  'Every morning at 9am, send a message to #daily-digest on Slack saying "Good morning team!"'
+  'Every morning at 9am, send a message to #daily-digest on Slack'
 )
-
-console.log(result.workflowId)      // deployed workflow ID
-console.log(result.credentialsNeeded) // what the user still needs to configure
+console.log(result.workflowId)       // deployed workflow ID
+console.log(result.credentialsNeeded) // what still needs configuring
+
+// Build a complete workflow pack from a business context
+const builder = new PackBuilder({ anthropicApiKey: process.env.ANTHROPIC_API_KEY!, kairos })
+const plan = await builder.plan('Homecare DME operations')
+const pack = await builder.build(plan)
+console.log(pack.workflows.map(w => w.name))  // all deployed workflow names
+console.log(pack.openQuestions)               // questions to answer before activating
+console.log(pack.testChecklist)               // how to verify each workflow
 ```
 
 ### What Kairos does and does not do
@@ -32,10 +40,12 @@ console.log(result.credentialsNeeded) // what the user still needs to configure
 | Kairos does | Kairos does not guarantee (yet) |
 |---|---|
 | Generates valid n8n workflow JSON | Perfect business logic |
-| Validates structure before deploy (34 rules) | Correct credentials |
-| Syncs node types from your live instance | Runtime success for every API |
-| Learns from prior successful builds | That every workflow matches intent perfectly |
-| Works through MCP, SDK, or CLI | Full replacement for human review |
+| Builds complete workflow packs from business context | Correct credentials or API configs |
+| Validates structure before deploy (34 rules) | Runtime success for every API |
+| Documents assumptions, open questions, and test steps | That every workflow matches intent perfectly |
+| Syncs node types from your live instance | Full replacement for human review |
+| Learns from prior builds and failures | Monitoring after deployment (coming soon) |
+| Works through MCP, SDK, or CLI | — |
 
 ---
 
@@ -111,12 +121,14 @@ This means Kairos works with **any LLM** — Claude, GPT, Gemini, Llama, or anyt
 | `kairos_validate` | Validates workflow JSON against 34 structural rules — returns errors and warnings |
 | `kairos_search` | Searches the local workflow library for similar past builds |
 | `kairos_sync` | Manually refresh the node catalog from your n8n instance (auto-runs on first `kairos_prompt` call) |
+| `kairos_patterns` | Returns pattern analysis — top failure rules, confidence scores, and improvement suggestions derived from build telemetry |
 
 #### Deployment tools
 
 | Tool | Description |
 |------|-------------|
 | `kairos_deploy` | Deploys validated workflow JSON to n8n (re-validates before deploying) |
+| `kairos_replace` | Replaces an existing n8n workflow with a new version — validates before updating, preserves workflow ID |
 | `kairos_list` | List all deployed workflows |
 | `kairos_get` | Get full workflow JSON by ID |
 | `kairos_activate` | Activate a workflow |
@@ -124,6 +136,13 @@ This means Kairos works with **any LLM** — Claude, GPT, Gemini, Llama, or anyt
 | `kairos_delete` | Delete a workflow |
 | `kairos_executions` | List recent executions with status |
 
+#### Library tools
+
+| Tool | Description |
+|------|-------------|
+| `kairos_library` | Browse or search the local Kairos workflow library — returns metadata, node counts, deploy history, and n8n workflow IDs |
+| `kairos_outcome` | Record build outcome against a library entry — feeds the pattern learning system with attempt counts, failed rules, and generation mode |
+
 ---
 
 ## Use as SDK
@@ -314,6 +333,36 @@ const result = await kairos.build(description, {
 
 ---
 
+### `new PackBuilder(options)` + `builder.plan()` + `builder.build()`
+
+Build a complete workflow pack from a plain-English business context.
+
+```ts
+import { Kairos, PackBuilder } from '@kairos-sdk/core'
+
+const kairos = new Kairos({ anthropicApiKey, n8nBaseUrl, n8nApiKey })
+const builder = new PackBuilder({ anthropicApiKey, kairos })
+
+// Step 1 — plan (LLM generates workflow list, assumptions, open questions)
+const plan = await builder.plan('Homecare DME business operations')
+console.log(plan.workflows)      // array of { name, description, purpose }
+console.log(plan.openQuestions)  // questions needing human answers before go-live
+
+// Step 2 — build (deploys each workflow, aggregates credentials and test steps)
+const pack = await builder.build(plan, {
+  dryRun: false,
+  activate: false,
+  onProgress: (wf, i, total) => console.log(`[${i+1}/${total}] ${wf.name}`),
+})
+
+console.log(pack.workflows)       // deployed results with workflowId and credentialsNeeded
+console.log(pack.allCredentials)  // deduped credential list across all workflows
+console.log(pack.sheetsColumns)   // Google Sheets required per sheet
+console.log(pack.testChecklist)   // per-workflow test steps
+```
+
+---
+
 ### Workflow management
 
 ```ts
@@ -412,11 +461,20 @@ try {
 Deploy workflows from the command line — no code required:
 
 ```bash
-# Generate and deploy
+# First-time setup (prompts for credentials, seeds template library, prints Claude Desktop config)
+kairos init
+
+# Generate and deploy a single workflow
 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
+# Generate a complete workflow pack from a business context
+kairos build-pack "Homecare DME business — patient onboarding, reorder reminders, social media"
+
+# Dry run — plan and validate without deploying
+kairos build-pack "E-commerce store operations" --dry-run
+
+# Skip confirmation prompt and build immediately
+kairos build-pack "Real estate agency operations" --yes
 
 # Seed library with n8n community templates
 kairos sync-templates --max 200
@@ -433,7 +491,64 @@ kairos deactivate <workflow-id>
 kairos delete <workflow-id> --confirm
 ```
 
-Set your credentials as environment variables:
+### What `build-pack` outputs
+
+After building, Kairos prints a structured document and saves a JSON file to `~/.kairos/packs/<name>.json`:
+
+```
+Homecare DME business — Workflow Pack
+══════════════════════════════════════
+
+Workflows Built (6/6)
+──────────────────────────────────────────────────
+  ✓ Weekly Social Media Content  [360Xba7BEQFQUw3v]
+    Generate and email 3 Facebook/Instagram posts for approval each Monday
+  ✓ Group Home Reorder Reminders  [g1Dx5hjTpV4FrkwH]
+    Email facility contacts when supplies are due for reorder
+  ✓ Monthly Newsletter  [lO8YxkDiaGkZiq76]
+    Send AI-generated newsletter to customer mailing list on the 1st
+  ✓ New Customer Welcome Sequence  [PrMj2DwVGfAo6VXq]
+    3-email onboarding sequence triggered by webhook on customer add
+  ✓ Annual Equipment Check-ins  [LZCIedaEnGNsKNRp]
+    Daily check for customers whose equipment delivery was ~1 year ago
+  ✓ Weekly Google Business Post  [IfxKaA1MYZ4Xs3eI]
+    Auto-post educational content to Google Business Profile each Monday
+
+Credentials Needed (connect once in n8n)
+──────────────────────────────────────────────────
+  □ Gmail OAuth2
+  □ Google Sheets OAuth2
+  □ Anthropic Claude API (HTTP Header Auth)
+  □ Google My Business OAuth2
+
+Google Sheets Required
+──────────────────────────────────────────────────
+  □ Facility Contacts: facility_name, contact_name, contact_email, product, reorder_frequency_weeks, last_order_date
+  □ Customer Mailing List: name, email
+
+Assumptions Made
+──────────────────────────────────────────────────
+  - Customer data is maintained in Google Sheets
+  - Gmail is the outbound email platform
+  - Owner approves social posts before publishing
+
+Open Questions (answer before activating)
+──────────────────────────────────────────────────
+  ? What email address should receive social media approval emails?
+  ? What is the brand voice / tone for posts and newsletters?
+  ? Should newsletters require approval before sending to the full list?
+
+Test Checklist
+──────────────────────────────────────────────────
+  Weekly Social Media Content
+    □ Trigger manually — verify approval email arrives with 3 posts
+  Group Home Reorder Reminders
+    □ Add a test row with last_order_date 30 days ago — verify reminder email
+  New Customer Welcome Sequence
+    □ POST {"customer_name":"Test","customer_email":"you@test.com","equipment_type":"wheelchair"} to webhook
+```
+
+Set your credentials as environment variables or run `kairos init`:
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...

package/dist/{chunk-KIFT5LA7.js → chunk-2ZHNO37N.js}

@@ -489,6 +489,7 @@ var N8nValidator = class {
     this.checkRule32(workflow, issues);
     this.checkRule33(workflow, issues);
     this.checkRule34(workflow, issues);
+    this.checkRule35(workflow, issues);
     if (Array.isArray(workflow.nodes)) {
       const nodeById = new Map(workflow.nodes.map((n) => [n.id, n.type]));
       for (const issue of issues) {
@@ -1061,6 +1062,43 @@ var N8nValidator = class {
       }
     }
   }
+  // Rule 35 (WARN): email-sending node with no duplicate-prevention signal
+  checkRule35(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const sendNodes = w.nodes.filter((node) => {
+      if (node.type === "n8n-nodes-base.gmail") {
+        const op = node.parameters?.["operation"];
+        return !op || op === "send" || op === "sendEmail" || op === "reply";
+      }
+      return node.type === "n8n-nodes-base.emailSend" || node.type === "n8n-nodes-base.sendEmail";
+    });
+    if (sendNodes.length === 0) return;
+    const workflowText = JSON.stringify(w).toLowerCase();
+    const IDEMPOTENCY_SIGNALS = [
+      "sent_at",
+      "last_sent",
+      "last_reminder",
+      "processed_at",
+      "already_sent",
+      "email_sent",
+      "notified_at",
+      "reminder_sent",
+      "contacted_at",
+      "dedupe",
+      "idempotent"
+    ];
+    const hasIdempotencySignal = IDEMPOTENCY_SIGNALS.some((s) => workflowText.includes(s));
+    if (!hasIdempotencySignal) {
+      for (const node of sendNodes) {
+        this.warn(
+          issues,
+          35,
+          `Node "${node.name}" sends email but no duplicate-prevention signal detected \u2014 add a sent_at timestamp field, a prior-send IF check, or a deduplication key to avoid repeat sends`,
+          node.id
+        );
+      }
+    }
+  }
   // Rule 34 (WARN): webhook path contains spaces, starts with slash, or looks like a full URL
   checkRule34(w, issues) {
     if (!Array.isArray(w.nodes)) return;
@@ -1242,7 +1280,7 @@ import { join as join4 } from "path";
 import { homedir as homedir3 } from "os";
 
 // src/validation/rule-metadata.ts
-var VALIDATOR_RULE_IDS = Array.from({ length: 34 }, (_, i) => i + 1);
+var VALIDATOR_RULE_IDS = Array.from({ length: 35 }, (_, i) => i + 1);
 var RULE_PIPELINE_STAGES = {
   1: "node_generation",
   2: "node_generation",
@@ -1277,7 +1315,8 @@ var RULE_PIPELINE_STAGES = {
   31: "node_generation",
   32: "node_generation",
   33: "node_generation",
-  34: "node_generation"
+  34: "node_generation",
+  35: "node_generation"
 };
 var RULE_EXAMPLES = {
   17: {
@@ -1327,6 +1366,10 @@ var RULE_EXAMPLES = {
   34: {
     bad: '"path": "/my webhook"',
     good: '"path": "my-webhook"'
+  },
+  35: {
+    bad: '"type": "n8n-nodes-base.gmail", "parameters": { "operation": "send" }  // no sent_at tracking',
+    good: 'Add a Set node after send that writes "sent_at": "={{ $now }}" back to the sheet, or an IF node that checks sent_at before sending'
   }
 };
 var RULE_MITIGATIONS = {
@@ -1363,7 +1406,8 @@ var RULE_MITIGATIONS = {
   31: "Add at least one condition to the if node \u2014 conditions.conditions array must be non-empty",
   32: "Add field assignments to the set node \u2014 assignments.assignments array must be non-empty for typeVersion 3.x",
   33: "Add at least one schedule rule to scheduleTrigger \u2014 rule.interval array must have at least one entry",
-  34: 'Webhook path must be a relative path without spaces, leading slashes, or protocol prefixes (e.g. "my-hook")'
+  34: 'Webhook path must be a relative path without spaces, leading slashes, or protocol prefixes (e.g. "my-hook")',
+  35: "Add duplicate-prevention to email-sending workflows: a sent_at timestamp field updated after each send, or an IF node that checks prior-send status before sending"
 };
 
 // src/telemetry/pattern-analyzer.ts
@@ -1421,7 +1465,7 @@ var PatternAnalyzer = class _PatternAnalyzer {
     this._cachedEvents = events;
     const starts = events.filter((e) => e.eventType === "build_start");
     const attempts = events.filter((e) => e.eventType === "generation_attempt");
-    const passed = attempts.filter(
+    const _passed = attempts.filter(
       (a) => a.data.validationPassed === true
     );
     const failed = attempts.filter(
@@ -2579,4 +2623,4 @@ export {
   buildSearchCorpus,
   FileLibrary
 };
-//# sourceMappingURL=chunk-KIFT5LA7.js.map
+//# sourceMappingURL=chunk-2ZHNO37N.js.map