ocpipe 0.3.0 → 0.3.2

package/README.md

@@ -1,5 +1,6 @@
 <p align="center"><strong>ocpipe</strong></p>
-<p align="center">SDK for LLM pipelines with <a href="https://github.com/sst/opencode">OpenCode</a> and <a href="https://zod.dev">Zod</a>.</p>
+<p align="center">Build LLM pipelines with <a href="https://github.com/sst/opencode">OpenCode</a> and <a href="https://zod.dev">Zod</a>.</p>
+<p align="center">Inspired by <a href="https://github.com/stanfordnlp/dspy">DSPy</a>.</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/ocpipe"><img alt="npm" src="https://img.shields.io/npm/v/ocpipe?style=flat-square" /></a>
   <a href="https://github.com/s4wave/ocpipe/actions"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/s4wave/ocpipe/tests.yml?style=flat-square&branch=master" /></a>
@@ -7,20 +8,25 @@
 
 ---
 
+- **Type-safe** Define inputs and outputs with Zod schemas
+- **Modular** Compose modules into complex pipelines
+- **Checkpoints** Resume from any step
+- **Multi-model** Works with 75+ providers through OpenCode
+- **Auto-correction** Fixes schema mismatches automatically
+
 ### Quick Start
 
+```bash
+bun add ocpipe
+```
+
 ```typescript
 import { signature, field, module, Pipeline, createBaseState } from 'ocpipe'
 
 const Greet = signature({
   doc: 'Generate a friendly greeting for the given name.',
-  inputs: {
-    name: field.string('The name of the person to greet'),
-  },
-  outputs: {
-    greeting: field.string('A friendly greeting message'),
-    emoji: field.string('An appropriate emoji for the greeting'),
-  },
+  inputs: { name: field.string('The name of the person to greet') },
+  outputs: { greeting: field.string('A friendly greeting message') },
 })
 
 const pipeline = new Pipeline(
@@ -28,26 +34,20 @@ const pipeline = new Pipeline(
     name: 'hello-world',
     defaultModel: { providerID: 'anthropic', modelID: 'claude-haiku-4-5' },
     defaultAgent: 'code',
-    checkpointDir: './ckpt',
-    logDir: './logs',
   },
   createBaseState,
 )
 
 const result = await pipeline.run(module(Greet), { name: 'World' })
-console.log(result.data.greeting) // "Hello, World! It's wonderful to meet you!"
-```
-
-### Installation
+console.log(result.data.greeting)
 
-```bash
-bun init
-bun add ocpipe
+// Extract types from signatures
+import { InferInputs, InferOutputs } from 'ocpipe'
+type GreetIn = InferInputs<typeof Greet> // { name: string }
+type GreetOut = InferOutputs<typeof Greet> // { greeting: string }
 ```
 
-OpenCode CLI is bundled — run `bun run opencode` or use your system `opencode` if installed (preferred).
-
-See [example/](./example) for a complete example.
+OpenCode CLI is bundled — run `bun run opencode` or use your system `opencode` if installed.
 
 ### Documentation
 
@@ -55,6 +55,10 @@ See [example/](./example) for a complete example.
 - [Design](./DESIGN.md) - Architecture and concepts
 - [Contributing](./CONTRIBUTING.md) - Development setup
 
+<!-- This code has been tested on animals. They didn't understand it either. -->
+
 ---
 
-**Join the OpenCode community** [Discord](https://opencode.ai/discord) | follow on [X.com](https://x.com/opencode)
+[Discord](https://discord.gg/opencode) · [OpenCode](https://github.com/sst/opencode)
+
+<sub>An [Aperture Robotics](https://github.com/aperturerobotics) project.</sub>

package/example/correction.ts

@@ -1,11 +1,11 @@
 /**
  * Auto-correction example.
  *
- * Demonstrates DSTS's automatic schema correction.
+ * Demonstrates ocpipe's automatic schema correction.
  * This example uses a schema with specific field names that LLMs
  * sometimes get wrong (e.g., "type" instead of "issue_type").
  *
- * DSTS supports two correction methods:
+ * ocpipe supports two correction methods:
  * - 'json-patch' (default): RFC 6902 JSON Patch, no external dependencies
  * - 'jq': jq-style expressions, requires jq binary installed
  *

package/example/index.ts

@@ -1,7 +1,7 @@
 /**
  * Hello World example runner.
  *
- * Demonstrates running a DSTS module in a pipeline.
+ * Demonstrates running an ocpipe module in a pipeline.
  */
 
 import { Pipeline, createBaseState } from '../src/index.js'

package/llms.txt

@@ -0,0 +1,200 @@
+# ocpipe
+
+> ocpipe is a TypeScript library for building type-safe LLM pipelines with OpenCode and Zod. Inspired by DSPy, it provides modular, checkpointable workflows with automatic schema correction.
+
+Important notes:
+
+- Requires Bun runtime and OpenCode CLI installed and configured
+- Uses Zod v4 for schema validation
+- Unlike DSPy, does NOT provide ChainOfThought or ReAct - OpenCode agents already handle reasoning and tool access
+- Session continuity is maintained by default across pipeline steps
+
+## Core Concepts
+
+ocpipe separates concerns into three layers:
+- **Signatures**: Declare input/output contracts (the "what")
+- **Modules**: Compose predictors with execution logic (the "how")
+- **Pipelines**: Orchestrate execution with checkpointing and retries (the "when")
+
+## Quick Start
+
+```bash
+bun add ocpipe zod
+```
+
+```typescript
+import { signature, field, module, Pipeline, createBaseState } from 'ocpipe'
+
+const Greet = signature({
+  doc: 'Generate a friendly greeting for the given name.',
+  inputs: { name: field.string('The name of the person to greet') },
+  outputs: { greeting: field.string('A friendly greeting message') },
+})
+
+const pipeline = new Pipeline(
+  {
+    name: 'hello-world',
+    defaultModel: { providerID: 'anthropic', modelID: 'claude-haiku-4-5' },
+    defaultAgent: 'code',
+    checkpointDir: './ckpt',
+    logDir: './logs',
+  },
+  createBaseState,
+)
+
+const result = await pipeline.run(module(Greet), { name: 'World' })
+console.log(result.data.greeting)
+```
+
+## Field Helpers
+
+- `field.string(desc?)` - String field
+- `field.number(desc?)` - Number field
+- `field.boolean(desc?)` - Boolean field
+- `field.array(itemType, desc?)` - Array with Zod item type
+- `field.object(shape, desc?)` - Object with Zod shape
+- `field.enum(values, desc?)` - Enum from const array
+- `field.optional(field)` - Optional wrapper
+- `field.nullable(field)` - Nullable wrapper
+- `field.custom(zodType, desc?)` - Custom Zod type
+
+## Docs
+
+- [Getting Started](https://github.com/s4wave/ocpipe/blob/master/GETTING_STARTED.md): Tutorial with examples for building hello world and extending with multiple modules
+- [Design](https://github.com/s4wave/ocpipe/blob/master/DESIGN.md): Architecture, core concepts, and advanced patterns
+- [README](https://github.com/s4wave/ocpipe/blob/master/README.md): Quick start and feature overview
+
+## Source Files
+
+- [src/index.ts](https://github.com/s4wave/ocpipe/blob/master/src/index.ts): Main exports - signature, field, module, Pipeline, Predict, state helpers, parsing utilities
+- [src/signature.ts](https://github.com/s4wave/ocpipe/blob/master/src/signature.ts): Signature definition and field helpers using Zod
+- [src/module.ts](https://github.com/s4wave/ocpipe/blob/master/src/module.ts): Module, SignatureModule, and simple module() factory
+- [src/pipeline.ts](https://github.com/s4wave/ocpipe/blob/master/src/pipeline.ts): Pipeline orchestrator with checkpointing, retries, and sub-pipelines
+- [src/predict.ts](https://github.com/s4wave/ocpipe/blob/master/src/predict.ts): Predict class - prompt generation, LLM execution, response parsing, auto-correction
+- [src/types.ts](https://github.com/s4wave/ocpipe/blob/master/src/types.ts): TypeScript interfaces - ModelConfig, ExecutionContext, SignatureDef, PipelineConfig, etc.
+- [src/agent.ts](https://github.com/s4wave/ocpipe/blob/master/src/agent.ts): OpenCode CLI integration - runAgent(), session management
+- [src/parsing.ts](https://github.com/s4wave/ocpipe/blob/master/src/parsing.ts): JSON extraction, Zod validation, JSON Patch and jq-style correction
+- [src/state.ts](https://github.com/s4wave/ocpipe/blob/master/src/state.ts): State management - createBaseState(), createSessionId(), extendBaseState()
+- [src/testing.ts](https://github.com/s4wave/ocpipe/blob/master/src/testing.ts): MockAgentBackend, createMockContext(), generateMockOutputs() for unit testing
+
+## Examples
+
+- [example/index.ts](https://github.com/s4wave/ocpipe/blob/master/example/index.ts): Hello world pipeline runner
+- [example/signature.ts](https://github.com/s4wave/ocpipe/blob/master/example/signature.ts): Greet signature definition
+- [example/module.ts](https://github.com/s4wave/ocpipe/blob/master/example/module.ts): Greeter SignatureModule implementation
+- [example/correction.ts](https://github.com/s4wave/ocpipe/blob/master/example/correction.ts): Auto-correction demonstration
+
+## Key Types
+
+```typescript
+interface PipelineConfig {
+  name: string
+  defaultModel: { providerID: string; modelID: string }
+  defaultAgent: string
+  checkpointDir: string
+  logDir: string
+  retry?: { maxAttempts: number; onParseError?: boolean }
+  timeoutSec?: number
+}
+
+interface SignatureDef<I, O> {
+  doc: string      // Instructions for the LLM
+  inputs: I        // Record<string, FieldConfig>
+  outputs: O       // Record<string, FieldConfig>
+}
+
+interface FieldConfig<T extends z.ZodType = z.ZodType> {
+  type: T          // Zod type for validation
+  desc?: string    // Description for prompt generation
+}
+```
+
+## Patterns
+
+### Simple Module (one signature)
+```typescript
+const result = await pipeline.run(module(MySignature), inputs)
+```
+
+### Custom Module Class
+```typescript
+class MyModule extends SignatureModule<typeof MySignature> {
+  constructor() { super(MySignature) }
+  async forward(input, ctx) {
+    const result = await this.predictor.execute(input, ctx)
+    return result.data
+  }
+}
+```
+
+### Multi-Predictor Module
+```typescript
+class ComplexModule extends Module<InputType, OutputType> {
+  private step1 = this.predict(Signature1)
+  private step2 = this.predict(Signature2, { agent: 'specialist' })
+  
+  async forward(input, ctx) {
+    const r1 = await this.step1.execute(input, ctx)
+    const r2 = await this.step2.execute({ data: r1.data }, ctx)
+    return { result: r2.data.output, metadata: r1.data }
+  }
+}
+```
+
+### Session Control
+```typescript
+// New session for this step
+await pipeline.run(module, input, { newSession: true })
+
+// Model override for this step
+await pipeline.run(module, input, { 
+  model: { providerID: 'anthropic', modelID: 'claude-opus-4-5' } 
+})
+```
+
+### Checkpointing
+```typescript
+// Resume from checkpoint
+const resumed = await Pipeline.loadCheckpoint(config, sessionId)
+
+// List available checkpoints
+const files = await Pipeline.listCheckpoints(config)
+```
+
+### Auto-Correction Configuration
+```typescript
+// Default: json-patch with 3 rounds
+super(MySignature)
+
+// Custom configuration
+super(MySignature, {
+  correction: {
+    method: 'json-patch',  // or 'jq' (requires jq binary)
+    maxFields: 5,
+    maxRounds: 3,
+  }
+})
+
+// Disable correction
+super(MySignature, { correction: false })
+```
+
+### Testing Without LLM
+```typescript
+import { MockAgentBackend, createMockContext } from 'ocpipe'
+import { vi } from 'vitest'
+
+const mock = new MockAgentBackend()
+mock.addJsonResponse({ greeting: 'Hello!', emoji: ':wave:' })
+
+vi.mock('./agent.js', () => ({ runAgent: mock.createRunner() }))
+
+const ctx = createMockContext()
+const result = await predictor.execute({ name: 'Test' }, ctx)
+```
+
+## Optional
+
+- [CONTRIBUTING.md](https://github.com/s4wave/ocpipe/blob/master/CONTRIBUTING.md): Development setup and contribution guidelines
+- [src/integration.test.ts](https://github.com/s4wave/ocpipe/blob/master/src/integration.test.ts): Integration tests showing real usage patterns
+- [src/parsing.test.ts](https://github.com/s4wave/ocpipe/blob/master/src/parsing.test.ts): Tests for JSON parsing and correction logic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocpipe",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "SDK for LLM pipelines with OpenCode and Zod",
   "type": "module",
   "main": "src/index.ts",
@@ -35,12 +35,18 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "bun-types": "^1.3.5",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
+    "jiti": "^2.6.1",
     "prettier": "^3.7.4",
     "typescript": "^5.0.0",
+    "typescript-eslint": "^8.50.1",
     "vitest": "^4.0.0"
   },
   "scripts": {
+    "lint": "eslint .",
     "format": "bun run prettier --write .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
@@ -55,6 +61,11 @@
   "files": [
     "src/",
     "!src/*.test.ts",
-    "example/"
+    "example/",
+    "llms.txt",
+    "README.md",
+    "LICENSE",
+    "GETTING_STARTED.md",
+    "DESIGN.md"
   ]
 }

package/src/.tmp/ocpipe-integration-test/mood-analysis_20251231_092022.json

@@ -0,0 +1,55 @@
+{
+  "sessionId": "20251231_092022",
+  "startedAt": "2025-12-31T09:20:22.199Z",
+  "phase": "init",
+  "steps": [
+    {
+      "stepName": "MoodAnalyzer",
+      "timestamp": "2025-12-31T09:20:25.808Z",
+      "result": {
+        "data": {
+          "mood": "happy",
+          "keywords": [
+            "happy",
+            "so",
+            "today"
+          ]
+        },
+        "stepName": "MoodAnalyzer",
+        "duration": 3608,
+        "sessionId": "ses_48c4aa762ffeP1pxFsOURK4cw2",
+        "model": {
+          "providerID": "github-copilot",
+          "modelID": "grok-code-fast-1"
+        },
+        "attempt": 1
+      }
+    },
+    {
+      "stepName": "ResponseSuggester",
+      "timestamp": "2025-12-31T09:20:30.186Z",
+      "result": {
+        "data": {
+          "suggestion": "That's wonderful! What's making you so happy today?"
+        },
+        "stepName": "ResponseSuggester",
+        "duration": 4377,
+        "sessionId": "ses_48c4aa762ffeP1pxFsOURK4cw2",
+        "model": {
+          "providerID": "github-copilot",
+          "modelID": "grok-code-fast-1"
+        },
+        "attempt": 1
+      }
+    }
+  ],
+  "subPipelines": [],
+  "inputText": "I am so happy today!",
+  "opencodeSessionId": "ses_48c4aa762ffeP1pxFsOURK4cw2",
+  "mood": "happy",
+  "keywords": [
+    "happy",
+    "so",
+    "today"
+  ]
+}

package/src/agent.ts

@@ -1,5 +1,5 @@
 /**
- * DSTS SDK OpenCode agent integration.
+ * ocpipe OpenCode agent integration.
  *
  * Wraps the OpenCode CLI for running LLM agents with session management.
  */

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
- * DSTS: Declarative Self-Improving TypeScript
+ * ocpipe: LLM pipelines with OpenCode and Zod.
  *
- * A DSPy-inspired SDK for building LLM workflow pipelines with OpenCode.
+ * Inspired by DSPy.
  *
  * @example
  * ```typescript

package/src/module.ts

@@ -1,11 +1,12 @@
 /**
- * DSTS SDK Module base class.
+ * ocpipe Module base class.
  *
  * Modules encapsulate logical units of work that use one or more Predictors.
  */
 
 import type {
   ExecutionContext,
+  FieldConfig,
   InferInputs,
   InferOutputs,
   SignatureDef,
@@ -13,17 +14,22 @@ import type {
 export type { ExecutionContext } from './types.js'
 import { Predict, type PredictConfig } from './predict.js'
 
+type AnySignature = SignatureDef<
+  Record<string, FieldConfig>,
+  Record<string, FieldConfig>
+>
+
 /** Module is the abstract base class for composable workflow units. */
 export abstract class Module<I, O> {
-  private predictors: Predict<any>[] = []
+  private predictors: Predict<AnySignature>[] = []
 
   /** predict creates and registers a Predict instance for a signature. */
-  protected predict<S extends SignatureDef<any, any>>(
+  protected predict<S extends AnySignature>(
     sig: S,
     config?: PredictConfig,
   ): Predict<S> {
     const p = new Predict(sig, config)
-    this.predictors.push(p)
+    this.predictors.push(p as Predict<AnySignature>)
     return p
   }
 
@@ -31,15 +37,16 @@ export abstract class Module<I, O> {
   abstract forward(input: I, ctx: ExecutionContext): Promise<O>
 
   /** getPredictors returns all registered predictors (for future optimization). */
-  getPredictors(): Predict<any>[] {
+  getPredictors(): Predict<AnySignature>[] {
     return this.predictors
   }
 }
 
 /** SignatureModule is a Module whose types are derived from a Signature. */
-export abstract class SignatureModule<
-  S extends SignatureDef<any, any>,
-> extends Module<InferInputs<S>, InferOutputs<S>> {
+export abstract class SignatureModule<S extends AnySignature> extends Module<
+  InferInputs<S>,
+  InferOutputs<S>
+> {
   protected readonly sig: S
   protected readonly predictor: Predict<S>
 
@@ -51,9 +58,7 @@ export abstract class SignatureModule<
 }
 
 /** SimpleModule is a SignatureModule that just executes the predictor. */
-class SimpleModule<
-  S extends SignatureDef<any, any>,
-> extends SignatureModule<S> {
+class SimpleModule<S extends AnySignature> extends SignatureModule<S> {
   constructor(sig: S, config?: PredictConfig) {
     super(sig, config)
   }
@@ -67,7 +72,7 @@ class SimpleModule<
 }
 
 /** module creates a simple Module from a Signature (syntactic sugar). */
-export function module<S extends SignatureDef<any, any>>(
+export function module<S extends AnySignature>(
   sig: S,
   config?: PredictConfig,
 ): Module<InferInputs<S>, InferOutputs<S>> {