ocpipe 0.1.0 → 0.2.1

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,13 +1,6 @@
-# DSTS
-
 <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>
+  <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>
 
 <div align="center">
@@ -20,315 +13,48 @@ Signature  →  Predict  →  Module  →  Pipeline
 
 </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
-
 ```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.',
+// Define a signature
+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),
-  },
-  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)
-  }
-
-  async forward(input, ctx) {
-    const result = await this.predictor.execute(input, ctx)
-    return result.data  // Types inferred from ParseIntent
-  }
-}
-```
-
-**Module** - For complex modules with multiple predictors or transformed outputs:
-
-```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
+// Run in a pipeline
 const pipeline = new Pipeline({
-  name: 'code-review',
-  defaultModel: { providerID: 'anthropic', modelID: 'claude-sonnet-4-5' },
-  defaultAgent: 'general',
+  name: 'hello-world',
+  defaultModel: { providerID: 'anthropic', modelID: 'claude-haiku-4-5' },
+  defaultAgent: 'code',
   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)
+const result = await pipeline.run(module(Greet), { name: 'World' })
+console.log(result.data.greeting)  // "Hello, World! It's wonderful to meet you!"
 ```
 
-### State Management
-
-DSTS automatically checkpoints state after each step:
-
-```typescript
-import { createBaseState, extendBaseState } from 'dsts'
+## Install
 
-// 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 add ocpipe zod
 ```
 
-## Why Not ChainOfThought or ReAct?
-
-Unlike DSPy, DSTS does not provide `ChainOfThought` or `ReAct` variants. This is intentional:
-
-- **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
+Requires [Bun](https://bun.sh) and [OpenCode](https://opencode.ai) CLI.
 
-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.
+[MIT](./LICENSE)

package/example/correction.ts

@@ -14,9 +14,9 @@
  *   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({

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.2.1",
+  "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",
@@ -29,20 +29,27 @@
     "bun": ">=1.0.0"
   },
   "peerDependencies": {
-    "zod": "^3.24.0"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
+    "bun-types": "^1.3.5",
     "typescript": "^5.0.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.0.0"
   },
   "scripts": {
     "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}

@@ -6,7 +6,7 @@
 
 import { spawn } 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'
 
 /** runAgent executes an OpenCode agent with a prompt, streaming output in real-time. */

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

@@ -5,8 +5,7 @@
  *
  * @example
  * ```typescript
- * import { signature, field, SignatureModule, Pipeline } from './dsts/index.js'
- * import { z } from 'zod'
+ * import { signature, field, module, Pipeline, createBaseState } from 'ocpipe'
  *
  * // Define a signature
  * const ParseIntent = signature({
@@ -20,18 +19,6 @@
  *   },
  * })
  *
- * // Create a module (types inferred from signature)
- * class IntentParser extends SignatureModule<typeof ParseIntent> {
- *   constructor() {
- *     super(ParseIntent)
- *   }
- *
- *   async forward(input, ctx) {
- *     const result = await this.predictor.execute(input, ctx)
- *     return result.data
- *   }
- * }
- *
  * // Run in a pipeline
  * const pipeline = new Pipeline({
  *   name: 'my-workflow',
@@ -41,7 +28,7 @@
  *   logDir: './logs',
  * }, createBaseState)
  *
- * const result = await pipeline.run(new IntentParser(), { description: 'Hello world' })
+ * const result = await pipeline.run(module(ParseIntent), { description: 'Hello world' })
  * ```
  */
 
@@ -53,7 +40,7 @@ export { Predict } from './predict.js'
 export type { PredictConfig } from './predict.js'
 
 // Module base class
-export { Module, SignatureModule } from './module.js'
+export { Module, SignatureModule, module } from './module.js'
 
 // Pipeline orchestrator
 export { Pipeline } from './pipeline.js'

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

@@ -10,6 +10,7 @@ import type {
   InferOutputs,
   SignatureDef,
 } from './types.js'
+export type { ExecutionContext } from './types.js'
 import { Predict, type PredictConfig } from './predict.js'
 
 /** Module is the abstract base class for composable workflow units. */
@@ -48,3 +49,22 @@ export abstract class SignatureModule<
     this.predictor = this.predict(sig, config)
   }
 }
+
+/** SimpleModule is a SignatureModule that just executes the predictor. */
+class SimpleModule<S extends SignatureDef<any, any>> extends SignatureModule<S> {
+  constructor(sig: S, config?: PredictConfig) {
+    super(sig, config)
+  }
+
+  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>>(
+  sig: S,
+  config?: PredictConfig,
+): Module<InferInputs<S>, InferOutputs<S>> {
+  return new SimpleModule(sig, config)
+}

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

@@ -4,7 +4,7 @@
  * Extracts and validates LLM responses using JSON or field marker formats.
  */
 
-import { z } from 'zod'
+import { z } from 'zod/v4'
 import type { FieldConfig, FieldError, TryParseResult } from './types.js'
 
 /** JSON Patch operation (RFC 6902). */

package/src/paths.ts

@@ -0,0 +1,4 @@
+import { join } from 'path'
+
+export const PROJECT_ROOT = import.meta.dirname
+export const TMP_DIR = join(PROJECT_ROOT, '.tmp')

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

@@ -4,7 +4,7 @@
  * Executes a signature by generating a prompt, calling OpenCode, and parsing the response.
  */
 
-import { z } from 'zod'
+import { z } from 'zod/v4'
 import type {
   CorrectionConfig,
   CorrectionMethod,

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

@@ -4,7 +4,7 @@
  * Signatures declare input/output contracts for LLM interactions using Zod for validation.
  */
 
-import { z } from 'zod'
+import { z } from 'zod/v4'
 import type { FieldConfig, SignatureDef } from './types.js'
 
 /** signature creates a new signature definition. */

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

@@ -4,7 +4,7 @@
  * Core type definitions for the Declarative Self-Improving TypeScript SDK.
  */
 
-import type { z } from 'zod'
+import type { z } from 'zod/v4'
 
 // ============================================================================
 // Model Configuration