pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/prompt-compiler/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": [
+      "node"
+    ],
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "noUnusedLocals": false,
+    "noUnusedParameters": false
+  },
+  "include": [
+    "src/**/*"
+  ]
+}

package/packages/provider-adapter-sdk/README.md

@@ -0,0 +1,221 @@
+# Provider Adapter SDK
+
+A comprehensive SDK for building, testing, and registering AI provider adapters.
+
+## Features
+
+- **Fluent Builder API**: Create adapters with a clean, chainable interface
+- **Lifecycle Management**: Initialize, activate, and teardown adapters
+- **Health Checks**: Automatic health monitoring for adapters
+- **Testing Utilities**: Built-in testing framework for adapters
+- **Registry**: Centralized management of multiple adapters
+- **Error Handling**: Comprehensive error parsing and quota detection
+
+## Installation
+
+```bash
+npm install @pi/provider-adapter-sdk
+```
+
+## Quick Start
+
+### Creating an Adapter
+
+```typescript
+import {
+  AdapterBuilder,
+  type ProviderRequest,
+  type ProviderResponse,
+} from "@pi/provider-adapter-sdk";
+
+const adapter = new AdapterBuilder("My Provider")
+  .id("my-provider")
+  .name("My Custom AI Provider")
+  .models("myai/model-x", "myai/model-y")
+  .capabilities("code", "review")
+  .rateLimits({
+    requestsPerMinute: 60,
+    tokensPerMinute: 100000,
+  })
+  .invoke(async (request: ProviderRequest): Promise<ProviderResponse> => {
+    // Your API call here
+    const response = await fetch("https://api.example.com/v1/completions", {
+      method: "POST",
+      body: JSON.stringify({
+        model: request.model,
+        messages: request.messages,
+      }),
+    });
+    return response.json();
+  })
+  .parseError((error) => ({
+    quotaExceeded: error.code === "QUOTA_EXCEEDED",
+    rateLimited: error.status === 429,
+    timeout: error.status === 408,
+    serverError: error.status >= 500,
+    clientError: error.status >= 400 && error.status < 500,
+  }))
+  .build();
+```
+
+### Using the Registry
+
+```typescript
+import { AdapterRegistry } from "@pi/provider-adapter-sdk";
+
+const registry = new AdapterRegistry();
+
+// Register adapter
+await registry.register(adapter, {
+  async onInit() {
+    console.log("Adapter initialized");
+  },
+});
+
+// Invoke adapter
+const result = await registry.invoke("my-provider", {
+  model: "myai/model-x",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+
+// List adapters
+const adapters = registry.listAdapters();
+console.log(`Registered ${adapters.length} adapters`);
+```
+
+### Testing Adapters
+
+```typescript
+import { AdapterTester } from "@pi/provider-adapter-sdk";
+
+const tester = new AdapterTester(adapter, {
+  mockResponses: true,
+  testInvocation: true,
+  testQuotaDetection: true,
+  testErrorParsing: true,
+  testHealthCheck: true,
+});
+
+const report = await tester.runAllTests();
+
+console.log(`Tests: ${report.summary.passed}/${report.summary.total} passed`);
+```
+
+## API Reference
+
+### AdapterBuilder
+
+Fluent API for creating provider adapters.
+
+```typescript
+new AdapterBuilder(name?: string)
+  .id(id: string)              // Required: unique adapter ID
+  .name(name: string)           // Required: display name
+  .models(...models: string[])  // Required: supported models
+  .defaultModel(model: string)  // Default model
+  .capabilities(...caps)        // Capabilities (code, review, etc.)
+  .rateLimits(limits)           // Rate limit configuration
+  .maxTokens(model, tokens)     // Max tokens per model
+  .invoke(fn)                   // Required: invocation function
+  .parseError(fn)               // Error parser function
+  .healthCheck(fn)              // Health check function
+  .build()                      // Build the adapter
+```
+
+### AdapterRegistry
+
+Central registry for managing adapters.
+
+```typescript
+const registry = new AdapterRegistry({
+  autoHealthCheck: true,
+  healthCheckInterval: 30000,
+});
+
+// Methods
+await registry.register(adapter, lifecycle?);
+await registry.unregister(id);
+registry.getAdapter(id);
+registry.listAdapters();
+registry.listByCapability(capability);
+await registry.invoke(id, request);
+await registry.healthCheck(id);
+await registry.healthCheckAll();
+registry.getStats();
+```
+
+### AdapterTester
+
+Testing utilities for adapters.
+
+```typescript
+const tester = new AdapterTester(adapter, config);
+
+await tester.runAllTests();
+await tester.testBasicInvocation(request);
+await tester.testQuotaDetection();
+await tester.testErrorParsing();
+await tester.testHealthCheck();
+tester.generateMockResponses();
+```
+
+## Capabilities
+
+Supported provider capabilities:
+
+- `code` - Code generation
+- `review` - Code review
+- `plan` - Planning
+- `test` - Test generation
+- `e2e` - End-to-end testing
+- `refactor` - Code refactoring
+- `analysis` - Code analysis
+- `debug` - Debugging assistance
+
+## Error Handling
+
+The SDK provides comprehensive error parsing:
+
+```typescript
+const analysis = adapter.parseError(error);
+// analysis.quotaExceeded - Quota exceeded
+// analysis.rateLimited - Rate limited
+// analysis.timeout - Request timed out
+// analysis.serverError - Server error
+// analysis.clientError - Client error
+```
+
+## Migration Guide
+
+### From Old Adapter Pattern
+
+If you're migrating from the old adapter pattern:
+
+```typescript
+// Old pattern
+class MyAdapter extends BaseProviderAdapter {
+  readonly id = "my-provider";
+  async invoke(request) { ... }
+}
+
+// New pattern (recommended)
+const adapter = new AdapterBuilder("My Provider")
+  .id("my-provider")
+  .models("my-model")
+  .invoke(async (request) => { ... })
+  .build();
+```
+
+## Examples
+
+See `examples/custom-adapter.ts` for complete examples:
+
+- Basic adapter creation
+- Registry usage
+- Adapter testing
+- Error handling
+- Migration from existing adapters
+
+## License
+
+MIT

package/packages/provider-adapter-sdk/dist/builder.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Provider Adapter SDK - Builder
+ *
+ * Fluent API for creating provider adapters.
+ */
+import type { AdapterResult, AdapterBuilderConfig, ErrorAnalysis, HealthCheckResult, InvokeFunction, ErrorParserFunction, HealthCheckFunction, RateLimitConfig, ProviderCapability, ProviderRequest, ProviderResponse } from "./types.js";
+/**
+ * Builder class for creating provider adapters
+ */
+export declare class AdapterBuilder {
+    private _id;
+    private _name;
+    private _models;
+    private _capabilities;
+    private _rateLimits;
+    private _defaultModel;
+    private _maxTokens;
+    private _invokeFn;
+    private _errorParserFn;
+    private _healthCheckFn;
+    constructor(name?: string);
+    /**
+     * Set the adapter ID
+     */
+    id(id: string): AdapterBuilder;
+    /**
+     * Set the adapter name
+     */
+    name(name: string): AdapterBuilder;
+    /**
+     * Set supported models
+     */
+    models(...models: string[]): AdapterBuilder;
+    /**
+     * Set default model (if different from first model)
+     */
+    defaultModel(model: string): AdapterBuilder;
+    /**
+     * Set capabilities
+     */
+    capabilities(...capabilities: ProviderCapability[]): AdapterBuilder;
+    /**
+     * Set rate limits
+     */
+    rateLimits(limits: RateLimitConfig): AdapterBuilder;
+    /**
+     * Set token limits per model
+     */
+    maxTokens(model: string, tokens: number): AdapterBuilder;
+    /**
+     * Set the invoke function (required)
+     */
+    invoke(fn: InvokeFunction): AdapterBuilder;
+    /**
+     * Set the complete function (alias for invoke)
+     */
+    complete(fn: (prompt: string, options?: Record<string, unknown>) => Promise<ProviderResponse>): AdapterBuilder;
+    /**
+     * Set custom error parser
+     */
+    parseError(fn: ErrorParserFunction): AdapterBuilder;
+    /**
+     * Set health check function
+     */
+    healthCheck(fn: HealthCheckFunction): AdapterBuilder;
+    /**
+     * Validate and build the adapter
+     */
+    build(): BuiltAdapter;
+}
+/**
+ * Configuration for BuiltAdapter
+ */
+interface BuiltAdapterConfig {
+    id: string;
+    name: string;
+    models: string[];
+    capabilities: ProviderCapability[];
+    rateLimits: RateLimitConfig;
+    defaultModel: string;
+    maxTokens: Record<string, number>;
+    invokeFn: InvokeFunction;
+    errorParserFn: ErrorParserFunction;
+    healthCheckFn?: HealthCheckFunction;
+}
+/**
+ * Built adapter instance
+ */
+export declare class BuiltAdapter {
+    readonly id: string;
+    readonly name: string;
+    private readonly _models;
+    private readonly _capabilities;
+    private readonly _rateLimits;
+    private readonly _defaultModel;
+    private readonly _maxTokens;
+    private readonly _invokeFn;
+    private readonly _errorParserFn;
+    private readonly _healthCheckFn?;
+    constructor(config: BuiltAdapterConfig);
+    /**
+     * Get supported models
+     */
+    getModels(): string[];
+    /**
+     * Get capabilities
+     */
+    getCapabilities(): ProviderCapability[];
+    /**
+     * Get rate limits
+     */
+    getRateLimits(): RateLimitConfig;
+    /**
+     * Check if model is supported
+     */
+    supportsModel(model: string): boolean;
+    /**
+     * Get default model
+     */
+    getDefaultModel(): string;
+    /**
+     * Get max tokens for a model
+     */
+    getMaxTokens(model?: string): number;
+    /**
+     * Invoke the adapter
+     */
+    invoke(request: ProviderRequest): Promise<AdapterResult>;
+    /**
+     * Parse an error
+     */
+    parseError(error: unknown): ErrorAnalysis;
+    /**
+     * Health check
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Convert to adapter info for registry
+     */
+    toConfig(): AdapterBuilderConfig;
+}
+/**
+ * Create a new provider builder
+ */
+export declare function createProviderBuilder(name: string): AdapterBuilder;
+export {};
+//# sourceMappingURL=builder.d.ts.map

package/packages/provider-adapter-sdk/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}