duet-kit 0.1.0

package/README.md

@@ -0,0 +1,442 @@
+# duet-kit
+
+**Shared state for humans and AI.** A Zustand store that both can edit, with validation and an audit trail.
+
+## The Problem
+
+You're building a UI where humans and AI edit the same state—a configuration wizard with AI suggestions, a form where AI auto-fills based on conversation, an editor where AI can make changes alongside you.
+
+The AI needs:
+- Schema context to know what fields exist
+- Validation to prevent invalid edits  
+- A structured format to apply changes
+
+You end up writing boilerplate: prompt templates, JSON parsing, validation logic, error handling. Every team does this differently. You can absolutely build this yourself—duet-kit just makes it simpler.
+
+## The Solution
+
+**duet-kit** gives your Zustand store an LLM interface. One schema, two editors (human + AI), same validation rules. State changes are instant—no round-trip to a server.
+
+```typescript
+import { createDuet, field, z } from 'duet-kit'
+
+const useFormStore = createDuet('ContactForm', {
+  name: field(z.string().min(1), 'Full Name', ''),
+  email: field(z.string().email(), 'Email', ''),
+  company: field(z.string(), 'Company', ''),
+})
+
+// React UI uses it like any Zustand store
+const { data, set } = useFormStore()
+
+// LLM uses the attached bridge
+useFormStore.llm.getContext()                              // schema + current values for prompt
+useFormStore.llm.applyJSON('[{"op":"replace",...}]')       // JSON Patch from LLM
+useFormStore.llm.getFunctionSchema()                       // OpenAI function calling format
+useFormStore.llm.history()                                 // audit trail of all patches
+```
+
+## Features
+
+- **Zustand-based** — Works like any Zustand store. No new patterns to learn.
+- **Zod validation** — Schema defines both types and constraints. LLM edits are validated.
+- **JSON Patch (RFC 6902)** — Standard format for edits. Supports nested fields and LLM know it already.
+- **Audit trail** — Every patch logged with timestamp, source, and result.
+- **Drop-in ready** — `attachLLM()` adds capabilities to existing Zustand + Zod code.
+- **TypeScript** — Full type inference from your schema.
+
+## Install
+
+```bash
+npm install duet-kit
+```
+
+Peer dependencies: `react`, `zustand`, `zod`
+
+---
+
+## Quick Start
+
+```typescript
+import { createDuet, field, z } from 'duet-kit'
+
+// Define schema with nested fields
+const useStore = createDuet('TripBudget', {
+  destination: field(z.string().min(1), 'Destination', 'Tokyo'),
+  days: field(z.number().min(1).max(365), 'Duration', 7),
+  accommodation: field(
+    z.object({
+      type: z.enum(['hotel', 'airbnb', 'hostel']),
+      budgetPerNight: z.number().min(0),
+    }),
+    'Accommodation',
+    { type: 'hotel', budgetPerNight: 150 }
+  ),
+}, { persist: 'trip-data' })
+
+// React component
+function TripForm() {
+  const { data, set } = useStore()
+  
+  return (
+    <input 
+      value={data.destination}
+      onChange={e => set('destination', e.target.value)}
+    />
+  )
+}
+
+// LLM integration
+const result = useStore.llm.applyJSON(`[
+  { "op": "replace", "path": "/destination", "value": "Paris" },
+  { "op": "replace", "path": "/accommodation/type", "value": "airbnb" }
+]`)
+```
+
+---
+
+## Already Using Zustand + Zod?
+
+Add LLM capabilities without changing your existing code:
+
+```typescript
+import { create } from 'zustand'
+import { z } from 'zod'
+import { attachLLM } from 'duet-kit'
+
+// Your existing store (unchanged)
+const schema = z.object({
+  title: z.string(),
+  priority: z.number().min(1).max(5),
+})
+
+const useStore = create<z.infer<typeof schema>>()(() => ({
+  title: '',
+  priority: 1,
+}))
+
+// One line addition
+const llm = attachLLM(useStore, schema, { name: 'Task' })
+
+// Now available:
+llm.getContext()          // prompt context
+llm.applyJSON(...)        // apply LLM output
+llm.getFunctionSchema()   // OpenAI tools format
+llm.history()             // audit trail
+```
+
+No migration. No rewrites. Your store and schema stay exactly as they are.
+
+---
+
+## API Reference
+
+### `createDuet(name, fields, options?)`
+
+Creates a Zustand store with LLM bridge attached.
+
+```typescript
+const useStore = createDuet('FormName', {
+  fieldName: field(zodSchema, 'Label', defaultValue),
+}, {
+  persist: 'localStorage-key',  // optional localStorage persistence
+  transformContext: (ctx) => `Custom instructions...\n\n${ctx}`,  // customize LLM prompt
+  transformFunctionSchema: (schema) => ({ ...schema, description: 'Custom' }),  // customize function schema
+})
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `persist` | localStorage key for persistence (omit for in-memory only) |
+| `transformContext` | Transform the default `getContext()` output before returning |
+| `transformFunctionSchema` | Transform the default `getFunctionSchema()` output before returning |
+
+Returns a Zustand hook with `.llm` and `.schema` properties.
+
+### `field(schema, label, defaultValue)`
+
+```typescript
+field(z.string().min(1), 'Username', '')
+field(z.number().min(0).max(100), 'Score', 0)
+field(z.enum(['draft', 'published']), 'Status', 'draft')
+field(z.boolean(), 'Active', true)
+
+// Nested objects
+field(z.object({
+  street: z.string(),
+  city: z.string(),
+}), 'Address', { street: '', city: '' })
+```
+
+### `attachLLM(store, zodSchema, options?)`
+
+For existing Zustand stores:
+
+```typescript
+const llm = attachLLM(existingStore, existingSchema, {
+  name: 'SchemaName',
+  labels: { fieldName: 'Human Label' }
+})
+```
+
+---
+
+## Store API
+
+```typescript
+const { data, set, setMany, reset } = useStore()
+
+data.fieldName              // read
+set('fieldName', value)     // write single (returns success boolean)
+setMany({ a: 1, b: 2 })     // write multiple
+reset()                     // restore defaults
+```
+
+---
+
+## LLM Bridge API
+
+### `getContext()`
+
+Generates a prompt-ready string with schema and current values:
+
+```
+Schema: TripBudget
+Fields:
+  - destination (string, min: 1): Destination
+  - days (number, min: 1, max: 365): Duration
+  - accommodation (object): Accommodation
+
+Current Values:
+  destination: "Tokyo" (Destination)
+  days: 7 (Duration)
+  accommodation: {"type":"hotel","budgetPerNight":150} (Accommodation)
+
+To edit fields, respond with a JSON Patch array (RFC 6902):
+[{ "op": "replace", "path": "/destination", "value": "Paris" }]
+```
+
+### `applyJSON(jsonString, source?)`
+
+Parses and applies JSON Patch from LLM output:
+
+```typescript
+// Flat field
+const patch1 = '[{ "op": "replace", "path": "/budget", "value": 8000 }]'
+
+// Nested field
+const patch2 = '[{ "op": "replace", "path": "/accommodation/type", "value": "airbnb" }]'
+
+const result = useStore.llm.applyJSON(patch1)
+// or with source tracking
+const result = useStore.llm.applyJSON(patch1, 'llm')
+
+if (result.success) {
+  console.log(`Applied ${result.applied} operation(s)`)
+} else {
+  console.error(result.error)  // validation message
+}
+```
+
+Accepts both array format `[...]` and wrapped format `{ "patch": [...] }`.
+
+### `getFunctionSchema()`
+
+Returns OpenAI/Anthropic function calling format:
+
+```typescript
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [...],
+  tools: [{
+    type: 'function',
+    function: useStore.llm.getFunctionSchema()
+  }]
+})
+```
+
+### `history()`
+
+Returns the full audit trail of all patches:
+
+```typescript
+const history = useStore.llm.history()
+// [
+//   {
+//     id: "1",
+//     timestamp: 1703782800000,
+//     patch: [{ op: "replace", path: "/budget", value: 5000 }],
+//     source: "llm",
+//     result: { success: true, applied: 1 }
+//   }
+// ]
+```
+
+### `clearHistory()`
+
+Clears the patch history.
+
+### Other Methods
+
+| Method | Description |
+|--------|-------------|
+| `getCompactContext()` | Shorter context for token-constrained prompts |
+| `applyPatch(ops, source?)` | Apply `JsonPatchOp[]` directly (typed) |
+| `getCurrentValues()` | Get current store state |
+
+---
+
+## Nested Fields
+
+duet-kit supports nested objects using JSON Pointer paths:
+
+```typescript
+const useStore = createDuet('CRMLead', {
+  contact: field(z.object({
+    name: z.string(),
+    email: z.string().email(),
+    phone: z.string(),
+  }), 'Contact', { name: '', email: '', phone: '' }),
+  
+  company: field(z.object({
+    name: z.string(),
+    industry: z.enum(['tech', 'finance', 'healthcare']),
+  }), 'Company', { name: '', industry: 'tech' }),
+})
+
+// LLM can update nested fields directly
+useStore.llm.applyJSON(`[
+  { "op": "replace", "path": "/contact/name", "value": "Sarah Chen" },
+  { "op": "replace", "path": "/contact/email", "value": "sarah@acme.com" },
+  { "op": "replace", "path": "/company/name", "value": "Acme Corp" }
+]`)
+```
+
+---
+
+## Patch Log (Debugging)
+
+Every patch is logged for debugging. When an LLM makes unexpected changes or validation fails, you can inspect what happened:
+
+```typescript
+const history = useStore.llm.history()
+
+// [
+//   {
+//     id: "1",
+//     timestamp: 1703782800000,
+//     patch: [{ op: "replace", path: "/budget", value: 5000 }],
+//     source: "llm",
+//     result: { success: true, applied: 1 }
+//   },
+//   {
+//     id: "2", 
+//     timestamp: 1703782810000,
+//     patch: [{ op: "replace", path: "/budget", value: 99999999 }],
+//     source: "llm",
+//     result: { success: false, error: "Number must be at most 1000000" }
+//   }
+// ]
+
+// Tag the source for filtering
+useStore.llm.applyPatch([...], 'user')   // manual edit
+useStore.llm.applyPatch([...], 'llm')    // AI edit (default)
+useStore.llm.applyPatch([...], 'system') // webhook/automation
+
+useStore.llm.clearHistory()  // reset
+```
+
+This is a change log, not a full decision trace. It tells you *what* changed, not *why* (the input, reasoning, or context that led to the change). Useful for debugging and simple undo—not a replacement for proper audit infrastructure.
+
+---
+
+## Use Cases
+
+**Configuration wizards**: User sets options, AI suggests related settings, both iterate until "Create" is clicked. Draft state lives in the client until committed.
+
+**AI-assisted editors**: Human and AI editing together in real-time—proposals, quotes, documents. Like Google Docs, but one editor is an AI.
+
+**Chat-driven UI**: "Change the budget to $5000" → AI parses intent → validated state update → UI reflects instantly.
+
+**Agentic workflows**: AI agents that modify your app state autonomously, with validation guardrails and an audit trail of what changed.
+
+### When to use duet-kit
+
+Use it when human and AI are **editing shared state together in a live session**—especially draft state that doesn't exist in your database yet.
+
+If your architecture is "agent updates DB → client syncs later," you probably don't need this. duet-kit is for interactive, client-side state where both editors see changes immediately.
+
+---
+
+## TypeScript
+
+Types are inferred from your schema:
+
+```typescript
+const useStore = createDuet('User', {
+  name: field(z.string(), 'Name', ''),
+  age: field(z.number(), 'Age', 0),
+})
+
+const { data, set } = useStore()
+data.name   // string
+data.age    // number
+set('name', 123)  // TS error
+```
+
+---
+
+## Examples
+
+See [`examples/`](./examples) for working demos:
+
+### Trip Planner
+- Side-by-side human and AI editing the same state
+- Nested fields (accommodation type, budget per night)
+- Debug panel showing `.llm.getContext()`, `.llm.getFunctionSchema()`, `.llm.history()`
+
+### CRM Lead Entry
+- AI extracts structured data from natural language input
+- Voice input with Web Speech API (optional)
+- OpenAI integration (optional—works with mock LLM too)
+- Nested contact and company fields with validation
+- Full audit trail of AI changes
+
+```bash
+cd examples && npm install && npm run dev
+```
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                     Your App                         │
+│                                                      │
+│   React UI                      LLM / Voice / API    │
+│      │                                │              │
+│      │ set()                          │ applyJSON()  │
+│      ▼                                ▼              │
+│   ┌──────────────────────────────────────────────┐   │
+│   │              useFormStore                    │   │
+│   │                                              │   │
+│   │   Zustand      Zod         LLM Bridge        │   │
+│   │   (state)   (validation)   (context +        │   │
+│   │                             patch log)       │   │
+│   └──────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## Future
+
+I'm hoping state management libraries like Zustand offer this natively in the future. Until then, duet-kit fills the gap.
+
+---
+
+## License
+
+MIT

package/dist/attach.d.ts

@@ -0,0 +1,48 @@
+/**
+ * duet-kit - Drop-in LLM Bridge
+ *
+ * For users who already have Zustand and Zod in their codebase,
+ * this allows adding LLM capabilities without rewriting anything.
+ * Uses RFC 6902 JSON Patch format.
+ */
+import { z } from 'zod';
+import type { StoreApi, UseBoundStore } from 'zustand';
+import type { LLMBridge, SchemaFields } from './types';
+type ZodObjectSchema = z.ZodObject<z.ZodRawShape>;
+interface AttachOptions {
+    /** Name for the schema (used in LLM context) */
+    name?: string;
+    /** Human-readable labels for fields */
+    labels?: Record<string, string>;
+}
+/**
+ * Attach an LLM bridge to an existing Zustand store + Zod schema.
+ * Uses RFC 6902 JSON Patch format for edits.
+ *
+ * @example
+ * ```typescript
+ * // Your existing code (unchanged):
+ * const todoSchema = z.object({
+ *   title: z.string(),
+ *   completed: z.boolean(),
+ *   priority: z.number().min(1).max(5),
+ * });
+ *
+ * const useTodoStore = create<z.infer<typeof todoSchema>>()((set) => ({
+ *   title: '',
+ *   completed: false,
+ *   priority: 1,
+ * }));
+ *
+ * // Drop-in addition (one line):
+ * const todoLLM = attachLLM(useTodoStore, todoSchema);
+ *
+ * // Now you have full LLM capabilities:
+ * todoLLM.getContext()           // Generate context for prompts
+ * todoLLM.applyJSON('...')       // Apply JSON Patch
+ * todoLLM.getFunctionSchema()    // OpenAI function calling
+ * ```
+ */
+export declare function attachLLM<T extends ZodObjectSchema>(store: UseBoundStore<StoreApi<z.infer<T>>>, schema: T, options?: AttachOptions): LLMBridge<SchemaFields>;
+export {};
+//# sourceMappingURL=attach.d.ts.map

package/dist/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAA2B,SAAS,EAAa,YAAY,EAAgB,MAAM,SAAS,CAAC;AAEzG,KAAK,eAAe,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;AAElD,UAAU,aAAa;IACrB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,eAAe,EACjD,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAC1C,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,aAAkB,GAC1B,SAAS,CAAC,YAAY,CAAC,CA8LzB"}

package/dist/attach.js

@@ -0,0 +1,205 @@
+/**
+ * duet-kit - Drop-in LLM Bridge
+ *
+ * For users who already have Zustand and Zod in their codebase,
+ * this allows adding LLM capabilities without rewriting anything.
+ * Uses RFC 6902 JSON Patch format.
+ */
+import { z } from 'zod';
+/**
+ * Attach an LLM bridge to an existing Zustand store + Zod schema.
+ * Uses RFC 6902 JSON Patch format for edits.
+ *
+ * @example
+ * ```typescript
+ * // Your existing code (unchanged):
+ * const todoSchema = z.object({
+ *   title: z.string(),
+ *   completed: z.boolean(),
+ *   priority: z.number().min(1).max(5),
+ * });
+ *
+ * const useTodoStore = create<z.infer<typeof todoSchema>>()((set) => ({
+ *   title: '',
+ *   completed: false,
+ *   priority: 1,
+ * }));
+ *
+ * // Drop-in addition (one line):
+ * const todoLLM = attachLLM(useTodoStore, todoSchema);
+ *
+ * // Now you have full LLM capabilities:
+ * todoLLM.getContext()           // Generate context for prompts
+ * todoLLM.applyJSON('...')       // Apply JSON Patch
+ * todoLLM.getFunctionSchema()    // OpenAI function calling
+ * ```
+ */
+export function attachLLM(store, schema, options = {}) {
+    const name = options.name || 'State';
+    const labels = options.labels || {};
+    const shape = schema.shape;
+    const fieldIds = Object.keys(shape);
+    // Validate a single field value
+    const validateField = (field, value) => {
+        const fieldSchema = shape[field];
+        if (!fieldSchema) {
+            return { success: false, error: `Unknown field: ${field}` };
+        }
+        const result = fieldSchema.safeParse(value);
+        if (!result.success) {
+            return { success: false, error: result.error.errors[0]?.message || 'Invalid value' };
+        }
+        return { success: true, data: result.data };
+    };
+    // Get field description from Zod schema
+    const getFieldDescription = (fieldId) => {
+        const fieldSchema = shape[fieldId];
+        const parts = [];
+        if (fieldSchema instanceof z.ZodString)
+            parts.push('string');
+        else if (fieldSchema instanceof z.ZodNumber)
+            parts.push('number');
+        else if (fieldSchema instanceof z.ZodBoolean)
+            parts.push('boolean');
+        else if (fieldSchema instanceof z.ZodEnum) {
+            const values = fieldSchema._def.values;
+            parts.push(`enum: ${values.join(' | ')}`);
+        }
+        if (fieldSchema instanceof z.ZodNumber) {
+            const checks = fieldSchema._def.checks || [];
+            for (const check of checks) {
+                if (check.kind === 'min')
+                    parts.push(`min: ${check.value}`);
+                if (check.kind === 'max')
+                    parts.push(`max: ${check.value}`);
+            }
+        }
+        return parts.length > 0 ? `(${parts.join(', ')})` : '';
+    };
+    // Get default value for a field (current value as fallback)
+    const getDefaultValue = (fieldId) => {
+        return store.getState()[fieldId];
+    };
+    // History log for audit trail
+    const patchHistory = [];
+    let historyId = 0;
+    return {
+        applyPatch(patch, source = 'llm') {
+            const updates = {};
+            for (const op of patch) {
+                const fieldName = op.path.replace(/^\//, '').split('/')[0];
+                if (!fieldIds.includes(fieldName)) {
+                    const result = { success: false, error: `Unknown field: ${fieldName}` };
+                    patchHistory.push({ id: String(++historyId), timestamp: Date.now(), patch, source, result });
+                    return result;
+                }
+                if (op.op === 'remove') {
+                    updates[fieldName] = getDefaultValue(fieldName);
+                    continue;
+                }
+                if (op.op === 'replace' || op.op === 'add') {
+                    const result = validateField(fieldName, op.value);
+                    if (!result.success) {
+                        const editResult = { success: false, error: `Invalid value for ${fieldName}: ${result.error}` };
+                        patchHistory.push({ id: String(++historyId), timestamp: Date.now(), patch, source, result: editResult });
+                        return editResult;
+                    }
+                    updates[fieldName] = result.data;
+                }
+            }
+            store.setState(updates);
+            const result = { success: true, applied: patch.length };
+            patchHistory.push({ id: String(++historyId), timestamp: Date.now(), patch, source, result });
+            return result;
+        },
+        applyJSON(json, source = 'llm') {
+            try {
+                const parsed = JSON.parse(json);
+                if (Array.isArray(parsed)) {
+                    return this.applyPatch(parsed, source);
+                }
+                if (parsed.patch && Array.isArray(parsed.patch)) {
+                    return this.applyPatch(parsed.patch, source);
+                }
+                return { success: false, error: 'Expected JSON Patch array or { patch: [...] } format' };
+            }
+            catch (e) {
+                return { success: false, error: `JSON parse error: ${e.message}` };
+            }
+        },
+        history() {
+            return [...patchHistory];
+        },
+        clearHistory() {
+            patchHistory.length = 0;
+            historyId = 0;
+        },
+        getContext() {
+            const data = store.getState();
+            let context = `${name} Schema:\n`;
+            for (const id of fieldIds) {
+                const label = labels[id] || id;
+                const desc = getFieldDescription(id);
+                context += `  - ${id}: ${label} ${desc}\n`;
+            }
+            context += '\nCurrent Values:\n';
+            for (const id of fieldIds) {
+                const value = data[id];
+                const label = labels[id] || id;
+                context += `  ${id}: ${JSON.stringify(value)} (${label})\n`;
+            }
+            context += `
+To edit fields, respond with a JSON Patch array (RFC 6902):
+[{ "op": "replace", "path": "/fieldName", "value": newValue }]
+
+Examples:
+- Single edit: [{ "op": "replace", "path": "/${fieldIds[0] || 'field'}", "value": "newValue" }]
+- Multiple: [{ "op": "replace", "path": "/a", "value": 1 }, { "op": "replace", "path": "/b", "value": 2 }]`;
+            return context;
+        },
+        getCompactContext() {
+            const data = store.getState();
+            const values = Object.entries(data)
+                .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                .join(', ');
+            return `${name}: {${values}}\nJSON Patch: [{"op":"replace","path":"/field","value":x}]`;
+        },
+        getFunctionSchema() {
+            return {
+                name: `patch_${name.toLowerCase().replace(/\s+/g, '_')}`,
+                description: `Apply JSON Patch operations to ${name}. Uses RFC 6902 format.`,
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        patch: {
+                            type: 'array',
+                            description: 'JSON Patch operations (RFC 6902)',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    op: {
+                                        type: 'string',
+                                        enum: ['replace', 'add', 'remove'],
+                                        description: 'Operation type',
+                                    },
+                                    path: {
+                                        type: 'string',
+                                        description: `JSON Pointer to field. Valid paths: ${fieldIds.map(f => `/${f}`).join(', ')}`,
+                                    },
+                                    value: {
+                                        description: 'New value (required for replace/add)',
+                                    },
+                                },
+                                required: ['op', 'path'],
+                            },
+                        },
+                    },
+                    required: ['patch'],
+                },
+            };
+        },
+        getCurrentValues() {
+            return store.getState();
+        },
+    };
+}