@limo-labs/deity 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,519 @@
+# @limo-deity/core
+
+> **Deterministic orchestration runtime for AI agents with built-in checkpoint & resume capabilities.**
+
+[![npm version](https://img.shields.io/npm/v/@limo-deity/core.svg)](https://www.npmjs.com/package/@limo-deity/core)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node-20+-green.svg)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+
+## What is @limo-deity/core?
+
+The core runtime for building **long-running AI agents** with:
+
+- ✅ **Deterministic execution** — Reproducible results via checkpointing
+- ✅ **Automatic checkpoint & resume** — Crash-resistant workflows
+- ✅ **Schema + semantic validation** — Every output validated before proceeding
+- ✅ **Complete execution tracing** — Full logs for debugging and auditing
+- ✅ **Type-safe** — Full TypeScript support with Zod schemas
+- ✅ **Tool calling** — Built-in function calling loop
+- ✅ **Retry with feedback** — LLM self-correction via validation errors
+
+**Limo-Deity is NOT a prompt library.** It's an orchestration runtime that treats LLMs as controlled computation units within a deterministic workflow.
+
+---
+
+## Installation
+
+```bash
+npm install @limo-deity/core zod
+```
+
+**Requirements:**
+- Node.js ≥ 20.0.0
+- npm ≥ 9.0.0
+
+---
+
+## Quick Start
+
+### 1. Define a Component
+
+```typescript
+import { AgentComponent, ExecutionContext } from "@limo-deity/core";
+import { z } from "zod";
+
+const SummaryComponent: AgentComponent<
+  { text: string },
+  { summary: string; wordCount: number }
+> = {
+  id: "SummaryComponent",
+
+  inputSchema: z.object({
+    text: z.string().min(1)
+  }),
+
+  outputSchema: z.object({
+    summary: z.string(),
+    wordCount: z.number().int().positive(),
+  }),
+
+  buildPrompt(ctx: ExecutionContext<{ text: string }>) {
+    return [
+      {
+        role: "system",
+        content: "You are a summarization assistant. Output JSON only.",
+      },
+      {
+        role: "user",
+        content: `Summarize: ${ctx.inputs.text}\\n\\nJSON: { "summary": "...", "wordCount": 123 }`,
+      },
+    ];
+  },
+
+  validate(output) {
+    if (output.summary.length < 10) {
+      return { valid: false, errors: ["Summary too short"] };
+    }
+    return { valid: true };
+  },
+
+  retry: {
+    maxAttempts: 3,
+    feedbackOnError: true, // Auto-inject errors into retry prompts
+  },
+};
+```
+
+### 2. Create and Run a Workflow
+
+```typescript
+import {
+  defineWorkflow,
+  runWorkflow,
+  JsonFileStore,
+  FileTraceLogger,
+  CopilotAdapter,
+} from "@limo-deity/core";
+
+// Define workflow
+const workflow = defineWorkflow({
+  name: "text-summarization",
+  defaultModel: {
+    adapter: new CopilotAdapter({
+      githubToken: process.env.GITHUB_TOKEN,
+    }),
+    config: { temperature: 0 },
+  },
+  steps: [SummaryComponent],
+});
+
+// Set up infrastructure
+const store = new JsonFileStore("./checkpoints");
+const trace = new FileTraceLogger("./trace.jsonl");
+
+// Run workflow
+const result = await runWorkflow(
+  workflow,
+  { text: "Your input text here..." },
+  store,
+  trace
+);
+
+console.log(result.SummaryComponent.summary);
+```
+
+### 3. Checkpoint & Resume
+
+If the workflow crashes, simply re-run it:
+
+```typescript
+// Re-run the same workflow - it will resume from the last checkpoint
+const result = await runWorkflow(workflow, inputs, store, trace);
+```
+
+**Completed stages are skipped automatically** — only incomplete work is re-executed.
+
+---
+
+## Core Features
+
+### 🔄 Deterministic Execution
+
+- **Prompt hash invalidation** — Checkpoints auto-invalidate when component code changes
+- **Reproducible results** — Same checkpoints → same outputs
+- **No side effects** — Runtime controls all I/O
+
+### ✅ Validation Gates
+
+Every component output must pass:
+1. **Schema validation** (Zod) — Type checking
+2. **Semantic validation** (custom logic) — Business rules
+
+No stage completes without validation passing.
+
+### 🔧 Tool Calling
+
+Built-in function calling with automatic loop management:
+
+```typescript
+const component: AgentComponent<Input, Output> = {
+  // ... other fields ...
+
+  tools: [
+    {
+      name: "search_database",
+      description: "Search for information in the database",
+      inputSchema: z.object({ query: z.string() }),
+      async execute(input) {
+        return await database.search(input.query);
+      },
+    },
+  ],
+};
+```
+
+Runtime executes tool calls, LLM never has direct access.
+
+### 🔁 Retry with Feedback
+
+Failed validations automatically feed back into retry prompts:
+
+```typescript
+retry: {
+  maxAttempts: 3,
+  feedbackOnError: true,  // Default: true
+}
+```
+
+**Example feedback loop:**
+1. LLM outputs: `{ "summary": "Hi" }` ❌
+2. Validation fails: "Summary too short"
+3. Runtime automatically adds to next prompt:
+   ```
+   Previous attempt failed validation:
+   - Summary too short
+   Please correct your output.
+   ```
+4. LLM self-corrects → valid output ✅
+
+### 📝 Complete Tracing
+
+All execution logged to JSONL:
+
+```jsonl
+{"type":"stage_start","stageId":"SummaryComponent","timestamp":"..."}
+{"type":"llm_call","messages":[...],"timestamp":"..."}
+{"type":"llm_response","content":"...","timestamp":"..."}
+{"type":"validation_passed","output":{...},"timestamp":"..."}
+{"type":"stage_complete","stageId":"SummaryComponent","timestamp":"..."}
+```
+
+---
+
+## Architecture
+
+### High-Level Flow
+
+```
+User Components (AgentComponent<I, O>)
+    ↓
+Workflow Definition (defineWorkflow)
+    ↓
+Runtime Loop (runWorkflow)
+    ↓
+Execution per step:
+  1. Check checkpoint (skip if valid)
+  2. Build prompt (Message[])
+  3. Call LLM (with tools if declared)
+  4. Parse output (JSON extraction + Zod validation)
+  5. Semantic validation (custom logic)
+  6. Retry with error feedback (if validation fails)
+  7. Save checkpoint + trace
+    ↓
+State Store + Trace Logger
+```
+
+### Key Abstractions
+
+| Abstraction | Purpose |
+|-------------|---------|
+| `AgentComponent<I, O>` | User-defined workflow step |
+| `ExecutionContext<I>` | Runtime data available to a step |
+| `LLMAdapter` | LLM provider abstraction |
+| `StateStore` | Checkpoint storage interface |
+| `TraceLogger` | Execution log interface |
+| `Tool` | Function calling abstraction |
+
+---
+
+## LLM Adapters
+
+### Built-in Adapters
+
+#### GitHub Copilot
+
+```typescript
+import { CopilotAdapter } from "@limo-deity/core";
+
+const adapter = new CopilotAdapter({
+  githubToken: process.env.GITHUB_TOKEN,
+  model: "gpt-4o", // optional
+});
+```
+
+**Authentication**: GitHub token via device flow OAuth.
+
+#### OpenAI
+
+```typescript
+import { OpenAIAdapter } from "@limo-deity/core";
+
+const adapter = new OpenAIAdapter({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: "gpt-4o",
+});
+```
+
+### Custom Adapters
+
+Implement the `LLMAdapter` interface:
+
+```typescript
+import { LLMAdapter, LLMResponse, Message, Tool } from "@limo-deity/core";
+
+export class MyLLMAdapter implements LLMAdapter {
+  async generate(
+    messages: Message[],
+    tools?: Tool[],
+    config?: GenerationConfig
+  ): Promise<LLMResponse> {
+    // Your implementation
+    return {
+      content: "...",
+      toolCalls: [...], // optional
+    };
+  }
+}
+```
+
+---
+
+## API Overview
+
+### Core Functions
+
+```typescript
+// Define a workflow
+function defineWorkflow(config: WorkflowConfig): Workflow
+
+// Run a workflow
+function runWorkflow<I>(
+  workflow: Workflow,
+  inputs: I,
+  store: StateStore,
+  trace: TraceLogger,
+  conversation?: ConversationManager
+): Promise<Record<string, unknown>>
+
+// Parse and validate LLM output
+function parseOutput<T>(
+  response: string,
+  schema: ZodSchema<T>
+): { success: true; data: T } | { success: false; error: string }
+```
+
+### Core Types
+
+```typescript
+interface AgentComponent<I, O> {
+  id: string;
+  inputSchema: ZodSchema<I>;
+  outputSchema: ZodSchema<O>;
+  buildPrompt(ctx: ExecutionContext<I>): Message[];
+  validate(output: O, ctx: ExecutionContext<I>): ValidationResult;
+  tools?: Tool[];
+  retry?: RetryConfig;
+}
+
+interface ExecutionContext<I> {
+  inputs: I;
+  previousOutputs: Record<string, unknown>;
+  getOutput<T>(stageId: string): T;
+  store: StateStore;
+  trace: TraceLogger;
+}
+
+interface Message {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  toolCallId?: string;
+}
+
+interface ValidationResult {
+  valid: boolean;
+  errors?: string[];
+}
+```
+
+See [API Documentation](../../doc/API.md) for complete reference.
+
+---
+
+## Deity 2.0 Features
+
+### Tiered Memory System (Alpha)
+
+Automatic hot/warm/cold storage management:
+
+```typescript
+const workflow = defineWorkflow({
+  name: "my-workflow",
+  memoryConfig: 'production',  // Uses tiered memory
+  steps: [/* ... */],
+});
+```
+
+**Status**: POC complete, production integration in progress.
+
+See [Memory System Guide](../../doc/MEMORY_SYSTEM.md) for details.
+
+### Context Scoping (Alpha)
+
+Control which steps can access which data:
+
+```typescript
+const component: AgentComponent<I, O> = {
+  scope: ["Step1", "Step2"],  // Only access these steps
+  // ...
+};
+```
+
+**Status**: POC complete.
+
+See [Context System Guide](../../doc/CONTEXT_SYSTEM.md) for details.
+
+---
+
+## Examples
+
+### Multi-Step Workflow
+
+```typescript
+const workflow = defineWorkflow({
+  name: "research-pipeline",
+  defaultModel: { adapter: llm },
+  steps: [
+    IndexComponent,    // Step 1: Index repository
+    AnalyzeComponent,  // Step 2: Analyze code (uses Step 1 output)
+    ReportComponent,   // Step 3: Generate report (uses Step 1 & 2)
+  ],
+});
+```
+
+### Accessing Previous Outputs
+
+```typescript
+buildPrompt(ctx: ExecutionContext<Input>) {
+  // Type-safe access to previous step outputs
+  const indexData = ctx.getOutput<IndexOutput>("IndexComponent");
+
+  return [
+    {
+      role: "user",
+      content: `Analyze these files: ${indexData.files.join(", ")}`,
+    },
+  ];
+}
+```
+
+### Custom Validation
+
+```typescript
+validate(output: GraphOutput, ctx: ExecutionContext<Input>) {
+  const errors: string[] = [];
+
+  if (output.nodes.length === 0) {
+    errors.push("Graph has no nodes");
+  }
+
+  // Check references
+  const nodeIds = new Set(output.nodes.map(n => n.id));
+  for (const edge of output.edges) {
+    if (!nodeIds.has(edge.from)) {
+      errors.push(`Invalid edge: ${edge.from} does not exist`);
+    }
+  }
+
+  return errors.length > 0
+    ? { valid: false, errors }
+    : { valid: true };
+}
+```
+
+See [examples directory](../example-agent/) for complete working examples.
+
+---
+
+## Documentation
+
+- **[Main README](../../README.md)** — Project overview and quick start
+- **[Philosophy](../../doc/philosophy.md)** — Design principles and positioning
+- **[Design Document](../../doc/design.md)** — Technical specification
+- **[API Reference](../../doc/API.md)** — Complete API documentation
+- **[Best Practices](../../doc/BEST_PRACTICES.md)** — Production tips
+- **[Memory System](../../doc/MEMORY_SYSTEM.md)** — Tiered memory guide
+- **[Migration Guide](../../doc/MIGRATION_GUIDE.md)** — v1.x → v2.0 upgrade
+- **[CLAUDE.md](../../CLAUDE.md)** — AI assistant collaboration guide
+
+---
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+# Run tests once
+npm test
+
+# Watch mode
+npm run test:watch
+```
+
+### Cleaning
+
+```bash
+npm run clean
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT © Limo-Deity Contributors
+
+See [LICENSE](../../LICENSE) for details.
+
+---
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/Limo-Deity/Limo-Deity/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/Limo-Deity/Limo-Deity/discussions)
+- **Documentation**: [Full Docs](../../doc/)
+
+---
+
+**Built with ❤️ by the Limo-Deity community**

package/dist/src/component.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Message type for LLM communication.
+ * Supports system/user/assistant roles matching modern LLM APIs.
+ */
+export interface Message {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    /** Tool call ID this message is responding to (for role: "tool") */
+    toolCallId?: string;
+}
+/**
+ * Structured validation result with error details.
+ * Errors are used for trace logging and retry feedback.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/src/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/component.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB"}

package/dist/src/component.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=component.js.map

package/dist/src/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../src/component.ts"],"names":[],"mappings":""}

package/dist/src/context/context-scope.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Defines visibility rules for a context scope.
+ */
+export interface ContextScope {
+    /** Name of this scope (for debugging) */
+    name: string;
+    /** Stage IDs visible in this scope ("*" for all) */
+    visibleStages: string[] | "*";
+    /** Whether this scope can write to memory (default: true) */
+    canWrite?: boolean;
+}
+/**
+ * Access mode for memory operations.
+ */
+export type AccessMode = "read" | "write";
+/**
+ * Check if a stage ID is visible in a scope.
+ */
+export declare function isStageVisible(scope: ContextScope, stageId: string): boolean;
+/**
+ * Check if an access mode is allowed in a scope.
+ */
+export declare function isAccessAllowed(scope: ContextScope, mode: AccessMode): boolean;
+//# sourceMappingURL=context-scope.d.ts.map

package/dist/src/context/context-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-scope.d.ts","sourceRoot":"","sources":["../../../src/context/context-scope.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,aAAa,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAKT;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,UAAU,GACf,OAAO,CAKT"}

package/dist/src/context/context-scope.js

@@ -0,0 +1,19 @@
+/**
+ * Check if a stage ID is visible in a scope.
+ */
+export function isStageVisible(scope, stageId) {
+    if (scope.visibleStages === "*") {
+        return true;
+    }
+    return scope.visibleStages.includes(stageId);
+}
+/**
+ * Check if an access mode is allowed in a scope.
+ */
+export function isAccessAllowed(scope, mode) {
+    if (mode === "read") {
+        return true; // Reading is always allowed
+    }
+    return scope.canWrite !== false; // Writing allowed by default
+}
+//# sourceMappingURL=context-scope.js.map

package/dist/src/context/context-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-scope.js","sourceRoot":"","sources":["../../../src/context/context-scope.ts"],"names":[],"mappings":"AAiBA;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAmB,EACnB,OAAe;IAEf,IAAI,KAAK,CAAC,aAAa,KAAK,GAAG,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAmB,EACnB,IAAgB;IAEhB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC,CAAC,4BAA4B;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,6BAA6B;AAChE,CAAC"}

package/dist/src/context/memory-view.d.ts

@@ -0,0 +1,62 @@
+import type { TieredMemoryManager } from "../memory/tiered-memory.js";
+import type { ContextScope } from "./context-scope.js";
+/**
+ * Memory view with access control based on context scope.
+ * Wraps TieredMemoryManager and enforces visibility rules.
+ */
+export declare class MemoryView {
+    private memory;
+    private scope;
+    constructor(memory: TieredMemoryManager, scope: ContextScope);
+    /**
+     * Get a value from memory.
+     * Throws if the key's stage is not visible in this scope.
+     */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Set a value in memory.
+     * Throws if write access is not allowed or key's stage is not visible.
+     */
+    set<T>(key: string, value: T): Promise<void>;
+    /**
+     * Check if a key exists in memory.
+     * Throws if the key's stage is not visible in this scope.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a value from memory.
+     * Throws if write access is not allowed or key's stage is not visible.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Pin a key to prevent eviction.
+     * Throws if write access is not allowed or key's stage is not visible.
+     */
+    pin(key: string): Promise<void>;
+    /**
+     * Unpin a key.
+     * Throws if write access is not allowed or key's stage is not visible.
+     */
+    unpin(key: string): void;
+    /**
+     * Get the current scope.
+     */
+    getScope(): ContextScope;
+    /**
+     * Check if access to a key is allowed in this scope.
+     * Throws AccessDeniedError if access is not allowed.
+     */
+    private checkAccess;
+    /**
+     * Extract stage ID from a memory key.
+     * Assumes format "stage:StageId" or just "StageId".
+     */
+    private extractStageId;
+}
+/**
+ * Error thrown when access is denied due to scope restrictions.
+ */
+export declare class AccessDeniedError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=memory-view.d.ts.map

package/dist/src/context/memory-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-view.d.ts","sourceRoot":"","sources":["../../../src/context/memory-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,oBAAoB,CAAC;AAGnE;;;GAGG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,KAAK;gBADL,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,YAAY;IAG7B;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAKjD;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD;;;OAGG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxC;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC;;;OAGG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrC;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKxB;;OAEG;IACH,QAAQ,IAAI,YAAY;IAIxB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAmBnB;;;OAGG;IACH,OAAO,CAAC,cAAc;CAOvB;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B"}