ocpipe 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christian Stewart <christian@aperture.us>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,334 +1,60 @@
-# DSTS
+<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">
+  <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">
-  <h3>Declarative Self-Improving TypeScript</h3>
-  <p>A DSPy-inspired SDK for building LLM workflow pipelines with <a href="https://opencode.ai">OpenCode</a>.</p>
-  <p>
-    <a href="https://github.com/s4wave/dsts">GitHub</a> |
-    <a href="https://github.com/s4wave/dsts/blob/main/GETTING_STARTED.md">Getting Started</a> |
-    <a href="https://github.com/s4wave/dsts/blob/main/LICENSE">MIT License</a>
-  </p>
-</div>
+---
 
-<div align="center">
-
-```
-Signature  →  Predict  →  Module  →  Pipeline
-   │            │           │           │
- what        execute     compose    orchestrate
-```
-
-</div>
-
-DSTS separates the **what** (Signatures declare input/output contracts), the **how** (Modules compose predictors), and the **when** (Pipelines orchestrate execution). This separation enables clean composition, rich debugging, and maintainable LLM workflow code.
-
-## Features
-
-- **Type-safe signatures** - Define input/output contracts with Zod schemas
-- **Automatic prompt generation** - Signatures become structured prompts
-- **JSON output parsing** - Automatic extraction and validation of JSON responses
-- **Session continuity** - Reuse OpenCode sessions across steps
-- **Checkpointing** - Automatic state persistence after each step
-- **Retry logic** - Configurable retries with parse error handling
-- **Sub-pipelines** - Compose complex workflows from smaller pieces
-- **Testing utilities** - Mock backends for unit testing
-
-## Quick Start
+### Quick Start
 
 ```typescript
-import { signature, field, SignatureModule, Pipeline, createBaseState } from 'dsts'
-import { z } from 'zod'
+import { signature, field, module, Pipeline, createBaseState } from 'ocpipe'
 
-// 1. Define a signature (the contract)
-const ParseIntent = signature({
-  doc: 'Parse user intent from a natural language description.',
+const Greet = signature({
+  doc: 'Generate a friendly greeting for the given name.',
   inputs: {
-    description: field.string('User description in natural language'),
+    name: field.string('The name of the person to greet'),
   },
   outputs: {
-    intent: field.string('Parsed intent category'),
-    confidence: field.number('Confidence score 0-1'),
-    keywords: field.array(z.string(), 'Extracted keywords'),
+    greeting: field.string('A friendly greeting message'),
+    emoji: field.string('An appropriate emoji for the greeting'),
   },
 })
 
-// 2. Create a module (the logic)
-class IntentParser extends SignatureModule<typeof ParseIntent> {
-  constructor() {
-    super(ParseIntent)
-  }
-
-  async forward(input, ctx) {
-    const result = await this.predictor.execute(input, ctx)
-    return result.data  // Full signature output
-  }
-}
-
-// 3. Run in a pipeline (the orchestration)
-const pipeline = new Pipeline({
-  name: 'my-workflow',
-  defaultModel: { providerID: 'anthropic', modelID: 'claude-sonnet-4-5' },
-  defaultAgent: 'general',
-  checkpointDir: './ckpt',
-  logDir: './logs',
-}, createBaseState)
-
-const result = await pipeline.run(new IntentParser(), { description: 'Hello world' })
-console.log(result.data.intent)
-```
-
-## Core Concepts
-
-### Signatures
-
-A Signature declares **what** an LLM interaction does - its inputs, outputs, and purpose. This is separate from *how* it executes.
-
-```typescript
-import { signature, field } from 'dsts'
-import { z } from 'zod'
-
-const AnalyzeCode = signature({
-  doc: 'Analyze code for potential issues and improvements.',
-  inputs: {
-    code: field.string('Source code to analyze'),
-    language: field.enum(['typescript', 'python', 'rust'] as const),
+const pipeline = new Pipeline(
+  {
+    name: 'hello-world',
+    defaultModel: { providerID: 'anthropic', modelID: 'claude-haiku-4-5' },
+    defaultAgent: 'code',
+    checkpointDir: './ckpt',
+    logDir: './logs',
   },
-  outputs: {
-    issues: field.array(z.object({
-      severity: z.enum(['error', 'warning', 'info']),
-      message: z.string(),
-      line: z.number(),
-    }), 'List of issues found'),
-    suggestions: field.array(z.string(), 'Improvement suggestions'),
-    score: field.number('Code quality score 0-100'),
-  },
-})
-```
-
-**Field helpers:**
-- `field.string(desc?)` - String field
-- `field.number(desc?)` - Number field
-- `field.boolean(desc?)` - Boolean field
-- `field.array(itemType, desc?)` - Array field
-- `field.object(shape, desc?)` - Object field
-- `field.enum(values, desc?)` - Enum field
-- `field.optional(field)` - Optional wrapper
-- `field.nullable(field)` - Nullable wrapper
-- `field.custom(zodType, desc?)` - Custom Zod type
-
-### Predict
-
-`Predict` is the bridge between a Signature (the contract) and OpenCode (the execution). It handles prompt generation, response parsing, and validation.
-
-```typescript
-import { Predict } from 'dsts'
-
-// Basic usage
-const predict = new Predict(AnalyzeCode)
-const result = await predict.execute({ code: '...', language: 'typescript' }, ctx)
-
-// With configuration
-const predict = new Predict(AnalyzeCode, {
-  agent: 'code-reviewer',      // Override default agent
-  model: { providerID: 'anthropic', modelID: 'claude-opus-4-5' },
-  newSession: true,            // Don't reuse existing session
-  template: (inputs) => `...`, // Custom prompt template
-})
-```
-
-**Output format:**
-
-The LLM is prompted to return a JSON object:
-```
-OUTPUT FORMAT:
-Return a JSON object with EXACTLY these field names and types.
-
-```json
-{
-  "issues": <array<object{severity, message, line}>>,  // List of issues found
-  "suggestions": <array<string>>,  // Improvement suggestions
-  "score": <number>  // Code quality score 0-100
-}
-```
-```
-
-### Module
-
-A Module encapsulates a logical unit of work that may use one or more Predictors. Modules can call other Modules, enabling composition.
-
-**SignatureModule** - For simple modules that wrap a single signature with pass-through types:
-
-```typescript
-import { SignatureModule } from 'dsts'
-
-class IntentParser extends SignatureModule<typeof ParseIntent> {
-  constructor() {
-    super(ParseIntent)
-  }
+  createBaseState,
+)
 
-  async forward(input, ctx) {
-    const result = await this.predictor.execute(input, ctx)
-    return result.data  // Types inferred from ParseIntent
-  }
-}
+const result = await pipeline.run(module(Greet), { name: 'World' })
+console.log(result.data.greeting) // "Hello, World! It's wonderful to meet you!"
 ```
 
-**Module** - For complex modules with multiple predictors or transformed outputs:
+### Installation
 
-```typescript
-import { Module } from 'dsts'
-
-class CodeAnalyzer extends Module<
-  { code: string; language: string },
-  { issues: Issue[]; score: number }
-> {
-  private analyze = this.predict(AnalyzeCode)
-  private suggest = this.predict(SuggestFixes, { agent: 'code-fixer' })
-
-  async forward(input: { code: string; language: string }, ctx: ExecutionContext) {
-    // First, analyze the code
-    const analysis = await this.analyze.execute(input, ctx)
-    
-    // If there are critical issues, get fix suggestions
-    if (analysis.data.issues.some(i => i.severity === 'error')) {
-      const fixes = await this.suggest.execute({
-        code: input.code,
-        issues: analysis.data.issues,
-      }, ctx)
-      
-      return {
-        issues: analysis.data.issues,
-        fixes: fixes.data.suggestions,
-        score: analysis.data.score,
-      }
-    }
-
-    return {
-      issues: analysis.data.issues,
-      score: analysis.data.score,
-    }
-  }
-}
-```
-
-### Pipeline
-
-Pipeline is the top-level orchestrator. It manages execution context, state, checkpointing, logging, and retry logic.
-
-```typescript
-import { Pipeline, createBaseState } from 'dsts'
-
-// Create pipeline with configuration
-const pipeline = new Pipeline({
-  name: 'code-review',
-  defaultModel: { providerID: 'anthropic', modelID: 'claude-sonnet-4-5' },
-  defaultAgent: 'general',
-  checkpointDir: './ckpt',
-  logDir: './logs',
-  retry: { maxAttempts: 2, onParseError: true },
-  timeoutSec: 300,
-}, createBaseState)
-
-// Run modules
-const result = await pipeline.run(new CodeAnalyzer(), {
-  code: sourceCode,
-  language: 'typescript',
-})
-
-// Run with step options
-const result = await pipeline.run(new CodeAnalyzer(), input, {
-  name: 'analyze-main',        // Custom step name
-  model: { providerID: 'anthropic', modelID: 'claude-opus-4-5' },  // Override model
-  newSession: true,            // Fresh session
-  retry: { maxAttempts: 3 },   // Override retry
-})
-
-// Access state
-console.log(pipeline.state.steps)        // Completed steps
-console.log(pipeline.getSessionId())     // Current OpenCode session
-
-// Resume from checkpoint
-const resumed = await Pipeline.loadCheckpoint(config, sessionId)
-```
-
-### State Management
-
-DSTS automatically checkpoints state after each step:
-
-```typescript
-import { createBaseState, extendBaseState } from 'dsts'
-
-// Basic state
-const state = createBaseState()
-// { sessionId, startedAt, phase, steps, subPipelines }
-
-// Extended state for your workflow
-interface MyState extends BaseState {
-  inputPath: string
-  results: AnalysisResult[]
-}
-
-const pipeline = new Pipeline(config, () => ({
-  ...createBaseState(),
-  inputPath: '/path/to/input',
-  results: [],
-}))
-```
-
-## Testing
-
-DSTS provides testing utilities for unit testing without hitting real LLMs:
-
-```typescript
-import { MockAgentBackend, createMockContext, generateMockOutputs } from 'dsts'
-import { vi } from 'vitest'
-
-// Create mock backend
-const mock = new MockAgentBackend()
-
-// Add mock responses
-mock.addJsonResponse({
-  intent: 'greeting',
-  confidence: 0.95,
-  keywords: ['hello', 'world'],
-})
-
-// Mock the agent module
-vi.mock('./agent.js', () => ({
-  runAgent: mock.createRunner(),
-}))
-
-// Create test context
-const ctx = createMockContext({
-  defaultModel: { providerID: 'anthropic', modelID: 'claude-sonnet-4-5' },
-})
-
-// Auto-generate mock outputs from schema
-const mockData = generateMockOutputs(ParseIntent.outputs)
+```bash
+bun init
+bun add ocpipe
 ```
 
-## Why Not ChainOfThought or ReAct?
-
-Unlike DSPy, DSTS does not provide `ChainOfThought` or `ReAct` variants. This is intentional:
+OpenCode CLI is bundled — run `bun run opencode` or use your system `opencode` if installed (preferred).
 
-- **OpenCode agents already do chain-of-thought reasoning** - they think before acting
-- **OpenCode agents already do ReAct** - they have access to tools and use them iteratively
-- **Adding these would duplicate functionality** and create confusion
+See [example/](./example) for a complete example.
 
-If you need tool access, configure your OpenCode agent appropriately. The agent handles the complexity; DSTS just structures the input/output contract.
+### Documentation
 
-## Requirements
-
-- [Bun](https://bun.sh) runtime
-- [OpenCode](https://opencode.ai) CLI installed and configured
-- [Zod](https://zod.dev) for schema validation
-
-## Installation
-
-```bash
-bun add dsts zod
-```
+- [Getting Started](./GETTING_STARTED.md) - Tutorial with examples
+- [Design](./DESIGN.md) - Architecture and concepts
+- [Contributing](./CONTRIBUTING.md) - Development setup
 
-## License
+---
 
-MIT - see [LICENSE](https://github.com/s4wave/dsts/blob/main/LICENSE) for details.
+**Join the OpenCode community** [Discord](https://opencode.ai/discord) | follow on [X.com](https://x.com/opencode)

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

@@ -14,9 +14,15 @@
  *   bun run example/correction.ts --jq         # Uses jq method
  */
 
-import { z } from 'zod'
-import { Pipeline, createBaseState, signature, field, SignatureModule } from '../index.js'
-import type { CorrectionMethod, ExecutionContext } from '../types.js'
+import { z } from 'zod/v4'
+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
 const AnalyzeIssue = signature({
@@ -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

@@ -4,7 +4,7 @@
  * Demonstrates running a DSTS module in a pipeline.
  */
 
-import { Pipeline, createBaseState } from '../index.js'
+import { Pipeline, createBaseState } from '../src/index.js'
 import { Greeter } from './module.js'
 
 async function main() {

package/example/module.ts

@@ -4,8 +4,8 @@
  * Wraps the Greet signature with execution logic.
  */
 
-import { SignatureModule } from '../index.js'
-import type { ExecutionContext } from '../types.js'
+import { SignatureModule } from '../src/index.js'
+import type { ExecutionContext } from '../src/types.js'
 import { Greet } from './signature.js'
 
 export class Greeter extends SignatureModule<typeof Greet> {

package/example/signature.ts

@@ -4,7 +4,7 @@
  * Defines the input/output contract for greeting generation.
  */
 
-import { signature, field } from '../index.js'
+import { signature, field } from '../src/index.js'
 
 export const Greet = signature({
   doc: 'Generate a friendly greeting for the given name.',

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "ocpipe",
-  "version": "0.1.0",
-  "description": "Declarative Self-Improving TypeScript - A DSPy-inspired SDK for building LLM workflow pipelines with OpenCode",
+  "version": "0.3.0",
+  "description": "SDK for LLM pipelines with OpenCode and Zod",
   "type": "module",
-  "main": "index.ts",
-  "types": "index.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/s4wave/dsts"
+    "url": "git+https://github.com/s4wave/ocpipe.git"
   },
-  "homepage": "https://github.com/s4wave/dsts",
+  "homepage": "https://github.com/s4wave/ocpipe",
   "bugs": {
-    "url": "https://github.com/s4wave/dsts/issues"
+    "url": "https://github.com/s4wave/ocpipe/issues"
   },
   "license": "MIT",
   "author": "s4wave",
@@ -28,21 +28,33 @@
   "engines": {
     "bun": ">=1.0.0"
   },
+  "dependencies": {
+    "opencode-ai": "latest"
+  },
   "peerDependencies": {
-    "zod": "^3.24.0"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
+    "bun-types": "^1.3.5",
+    "prettier": "^3.7.4",
     "typescript": "^5.0.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.0.0"
   },
   "scripts": {
+    "format": "bun run prettier --write .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "release": "npm run release:version && npm run release:commit",
+    "release:minor": "npm run release:version:minor && npm run release:commit",
+    "release:version": "npm version patch -m \"release: v%s\" --no-git-tag-version",
+    "release:version:minor": "npm version minor -m \"release: v%s\" --no-git-tag-version",
+    "release:commit": "git reset && git add package.json && git commit -s -m \"release: v$(node -p \"require('./package.json').version\")\" && git tag v$(node -p \"require('./package.json').version\")",
+    "release:publish": "git push && git push --tags && npm publish"
   },
   "files": [
-    "*.ts",
-    "!*.test.ts",
+    "src/",
+    "!src/*.test.ts",
     "example/"
   ]
 }

package/{agent.ts → src/agent.ts}

@@ -4,11 +4,30 @@
  * 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 { 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