ocpipe 0.2.1 → 0.3.1

package/README.md

@@ -1,60 +1,59 @@
-<div align="center">
-  <h3>OpenCode Pipeline</h3>
-  <p>SDK for LLM pipelines with <a href="https://opencode.ai">OpenCode</a> and <a href="https://zod.dev">Zod</a>.</p>
-</div>
+<p align="center"><strong>ocpipe</strong></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>
+</p>
 
-<div align="center">
+---
 
-```
-Signature  →  Predict  →  Module  →  Pipeline
-   │            │           │           │
- what        execute     compose    orchestrate
-```
+- **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
 
-</div>
+### Quick Start
+
+```bash
+bun add ocpipe
+```
 
 ```typescript
 import { signature, field, module, Pipeline, createBaseState } from 'ocpipe'
 
-// Define a signature
 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') },
 })
 
-// Run in a pipeline
-const pipeline = new Pipeline({
-  name: 'hello-world',
-  defaultModel: { providerID: 'anthropic', modelID: 'claude-haiku-4-5' },
-  defaultAgent: 'code',
-  checkpointDir: './ckpt',
-  logDir: './logs',
-}, createBaseState)
+const pipeline = new Pipeline(
+  {
+    name: 'hello-world',
+    defaultModel: { providerID: 'anthropic', modelID: 'claude-haiku-4-5' },
+    defaultAgent: 'code',
+  },
+  createBaseState,
+)
 
 const result = await pipeline.run(module(Greet), { name: 'World' })
-console.log(result.data.greeting)  // "Hello, World! It's wonderful to meet you!"
+console.log(result.data.greeting)
 ```
 
-## Install
-
-```bash
-bun add ocpipe zod
-```
+OpenCode CLI is bundled — run `bun run opencode` or use your system `opencode` if installed.
 
-Requires [Bun](https://bun.sh) and [OpenCode](https://opencode.ai) CLI.
-
-## Documentation
+### Documentation
 
 - [Getting Started](./GETTING_STARTED.md) - Tutorial with examples
 - [Design](./DESIGN.md) - Architecture and concepts
 - [Contributing](./CONTRIBUTING.md) - Development setup
 
-## License
+<!-- This code has been tested on animals. They didn't understand it either. -->
+
+---
+
+[Discord](https://discord.gg/opencode) · [OpenCode](https://github.com/sst/opencode)
 
-[MIT](./LICENSE)
+<sub>An [Aperture Robotics](https://github.com/aperturerobotics) project.</sub>

package/example/ckpt/hello-world_20251227_044217.json

@@ -0,0 +1,27 @@
+{
+  "sessionId": "20251227_044217",
+  "startedAt": "2025-12-27T04:42:17.756Z",
+  "phase": "init",
+  "steps": [
+    {
+      "stepName": "Greeter",
+      "timestamp": "2025-12-27T04:42:22.145Z",
+      "result": {
+        "data": {
+          "greeting": "Hello, World! Welcome!",
+          "emoji": "👋"
+        },
+        "stepName": "Greeter",
+        "duration": 4389,
+        "sessionId": "ses_4a1e2aaceffedog5Q2374azn79",
+        "model": {
+          "providerID": "anthropic",
+          "modelID": "claude-haiku-4-5"
+        },
+        "attempt": 1
+      }
+    }
+  ],
+  "subPipelines": [],
+  "opencodeSessionId": "ses_4a1e2aaceffedog5Q2374azn79"
+}

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
  *
@@ -15,7 +15,13 @@
  */
 
 import { z } from 'zod/v4'
-import { Pipeline, createBaseState, signature, field, SignatureModule } from '../src/index.js'
+import {
+  Pipeline,
+  createBaseState,
+  signature,
+  field,
+  SignatureModule,
+} from '../src/index.js'
 import type { CorrectionMethod, ExecutionContext } from '../src/types.js'
 
 // A signature with field names that LLMs often get wrong
@@ -28,9 +34,15 @@ IMPORTANT: Use the EXACT field names specified in the schema.`,
   },
   outputs: {
     // LLMs often return "type" instead of "issue_type"
-    issue_type: field.enum(['bug', 'feature', 'refactor', 'docs'] as const, 'Category of the issue'),
+    issue_type: field.enum(
+      ['bug', 'feature', 'refactor', 'docs'] as const,
+      'Category of the issue',
+    ),
     // LLMs often return "priority" instead of "severity"
-    severity: field.enum(['low', 'medium', 'high', 'critical'] as const, 'How severe is the issue'),
+    severity: field.enum(
+      ['low', 'medium', 'high', 'critical'] as const,
+      'How severe is the issue',
+    ),
     // LLMs often return "description" or "reason" instead of "explanation"
     explanation: field.string('Detailed explanation of the issue'),
     // LLMs often return just "tags" or "labels"
@@ -53,7 +65,8 @@ class IssueAnalyzer extends SignatureModule<typeof AnalyzeIssue> {
 
 async function main() {
   // Check for --jq flag
-  const method: CorrectionMethod = process.argv.includes('--jq') ? 'jq' : 'json-patch'
+  const method: CorrectionMethod =
+    process.argv.includes('--jq') ? 'jq' : 'json-patch'
 
   const pipeline = new Pipeline(
     {
@@ -72,7 +85,8 @@ async function main() {
   console.log('Watch the correction rounds fix schema mismatches.\n')
 
   const result = await pipeline.run(new IssueAnalyzer(method), {
-    description: 'The login button does not respond when clicked on mobile devices',
+    description:
+      'The login button does not respond when clicked on mobile devices',
   })
 
   console.log('\n=== Final Result ===')

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.2.1",
+  "version": "0.3.1",
   "description": "SDK for LLM pipelines with OpenCode and Zod",
   "type": "module",
   "main": "src/index.ts",
@@ -28,15 +28,26 @@
   "engines": {
     "bun": ">=1.0.0"
   },
+  "dependencies": {
+    "opencode-ai": "latest"
+  },
   "peerDependencies": {
     "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",
     "test:watch": "vitest",
@@ -50,6 +61,11 @@
   "files": [
     "src/",
     "!src/*.test.ts",
-    "example/"
+    "example/",
+    "llms.txt",
+    "README.md",
+    "LICENSE",
+    "GETTING_STARTED.md",
+    "DESIGN.md"
   ]
 }

package/src/agent.ts

@@ -1,14 +1,33 @@
 /**
- * DSTS SDK OpenCode agent integration.
+ * ocpipe OpenCode agent integration.
  *
  * Wraps the OpenCode CLI for running LLM agents with session management.
  */
 
-import { spawn } from 'child_process'
+import { spawn, execSync } from 'child_process'
 import { mkdir } from 'fs/promises'
 import { PROJECT_ROOT, TMP_DIR } from './paths.js'
 import type { RunAgentOptions, RunAgentResult } from './types.js'
 
+/** Check if opencode is available in system PATH */
+function hasSystemOpencode(): boolean {
+  try {
+    execSync('which opencode', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Get command and args to invoke opencode */
+function getOpencodeCommand(args: string[]): { cmd: string; args: string[] } {
+  if (hasSystemOpencode()) {
+    return { cmd: 'opencode', args }
+  }
+  // Fallback to bunx with ocpipe package (which has opencode-ai as dependency)
+  return { cmd: 'bunx', args: ['-p', 'ocpipe', 'opencode', ...args] }
+}
+
 /** runAgent executes an OpenCode agent with a prompt, streaming output in real-time. */
 export async function runAgent(
   options: RunAgentOptions,
@@ -23,14 +42,23 @@ export async function runAgent(
     `\n>>> OpenCode [${agent}] [${modelStr}] ${sessionInfo}: ${promptPreview}...`,
   )
 
-  const args = ['run', '--format', 'default', '--agent', agent, '--model', modelStr]
+  const args = [
+    'run',
+    '--format',
+    'default',
+    '--agent',
+    agent,
+    '--model',
+    modelStr,
+  ]
 
   if (sessionId) {
     args.push('--session', sessionId)
   }
 
   return new Promise((resolve, reject) => {
-    const proc = spawn('opencode', args, {
+    const opencodeCmd = getOpencodeCommand(args)
+    const proc = spawn(opencodeCmd.cmd, opencodeCmd.args, {
       cwd: PROJECT_ROOT,
       stdio: ['pipe', 'pipe', 'pipe'],
     })
@@ -116,23 +144,20 @@ async function exportSession(sessionId: string): Promise<string | null> {
 
   try {
     await mkdir(TMP_DIR, { recursive: true })
-    const proc = Bun.spawn(
-      [
-        'opencode',
-        'session',
-        'export',
-        sessionId,
-        '--format',
-        'json',
-        '-o',
-        tmpPath,
-      ],
-      {
-        cwd: PROJECT_ROOT,
-        stdout: 'pipe',
-        stderr: 'pipe',
-      },
-    )
+    const opencodeCmd = getOpencodeCommand([
+      'session',
+      'export',
+      sessionId,
+      '--format',
+      'json',
+      '-o',
+      tmpPath,
+    ])
+    const proc = Bun.spawn([opencodeCmd.cmd, ...opencodeCmd.args], {
+      cwd: PROJECT_ROOT,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
 
     await proc.exited
 

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,18 +58,21 @@ 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)
   }
 
-  async forward(input: InferInputs<S>, ctx: ExecutionContext): Promise<InferOutputs<S>> {
+  async forward(
+    input: InferInputs<S>,
+    ctx: ExecutionContext,
+  ): Promise<InferOutputs<S>> {
     return (await this.predictor.execute(input, ctx)).data
   }
 }
 
 /** 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>> {