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

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

@@ -0,0 +1,237 @@
+/**
+ * Provider Adapter SDK - Types
+ *
+ * Core types for building provider adapters.
+ */
+/**
+ * SDK version for compatibility checks
+ */
+export declare const SDK_VERSION = "1.0.0";
+/**
+ * Provider capability
+ */
+export type ProviderCapability = "code" | "review" | "plan" | "test" | "e2e" | "refactor" | "analysis" | "debug";
+/**
+ * Provider request
+ */
+export interface ProviderRequest {
+    model: string;
+    messages: ProviderMessage[];
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+}
+/**
+ * Provider message
+ */
+export interface ProviderMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/**
+ * Provider response
+ */
+export interface ProviderResponse {
+    content: string;
+    usage?: {
+        input: number;
+        output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        cost?: number;
+    };
+    model?: string;
+    finishReason?: "stop" | "length" | "content_filter" | "error";
+    error?: string;
+}
+/**
+ * Rate limit configuration for providers
+ */
+export interface RateLimitConfig {
+    requestsPerMinute?: number;
+    tokensPerMinute?: number;
+    tokensPerDay?: number;
+    concurrentRequests?: number;
+}
+/**
+ * Adapter version information
+ */
+export interface AdapterVersion {
+    sdk: string;
+    minRuntime?: string;
+    capabilities: ProviderCapability[];
+}
+/**
+ * Quota signal extracted from error responses
+ */
+export interface QuotaSignal {
+    exhausted: boolean;
+    resetsAt?: string;
+    retryAfterMs?: number;
+    usedPercentage?: number;
+    remainingTokens?: number;
+}
+/**
+ * Error analysis result from adapter
+ */
+export interface ErrorAnalysis {
+    quotaExceeded: boolean;
+    rateLimited: boolean;
+    timeout: boolean;
+    serverError: boolean;
+    clientError: boolean;
+    quotaSignal?: QuotaSignal;
+    message?: string;
+    code?: string;
+}
+/**
+ * Adapter invocation result with quota signals
+ */
+export interface AdapterResult {
+    response: ProviderResponse;
+    quotaSignal?: QuotaSignal;
+    retryable: boolean;
+    latencyMs?: number;
+}
+/**
+ * Configuration for creating an adapter via Builder
+ */
+export interface AdapterBuilderConfig {
+    id: string;
+    name: string;
+    models?: string[];
+    capabilities?: ProviderCapability[];
+    rateLimits?: RateLimitConfig;
+    defaultModel?: string;
+    maxTokens?: Record<string, number>;
+}
+/**
+ * Invoke function signature for custom adapters
+ */
+export type InvokeFunction = (request: ProviderRequest) => Promise<ProviderResponse>;
+/**
+ * Error parser function signature
+ */
+export type ErrorParserFunction = (error: unknown) => ErrorAnalysis;
+/**
+ * Health check function signature
+ */
+export type HealthCheckFunction = () => Promise<HealthCheckResult>;
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    healthy: boolean;
+    latencyMs?: number;
+    message?: string;
+    timestamp: string;
+}
+/**
+ * Lifecycle hooks for adapter management
+ */
+export interface AdapterLifecycle {
+    onInit?: () => Promise<void>;
+    onHealthCheck?: HealthCheckFunction;
+    onTeardown?: () => Promise<void>;
+}
+/**
+ * Adapter metadata for registry listing
+ */
+export interface AdapterInfo {
+    id: string;
+    name: string;
+    version?: AdapterVersion;
+    capabilities: ProviderCapability[];
+    models: string[];
+    registeredAt: string;
+    state: AdapterState;
+    lastHealthCheck?: HealthCheckResult;
+}
+/**
+ * Adapter state in registry
+ */
+export type AdapterState = "registered" | "initializing" | "ready" | "error" | "unavailable";
+/**
+ * Test result from AdapterTester
+ */
+export interface TestResult {
+    name: string;
+    passed: boolean;
+    duration: number;
+    message?: string;
+    error?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Full test report from AdapterTester
+ */
+export interface TestReport {
+    adapterId: string;
+    timestamp: string;
+    results: TestResult[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        duration: number;
+    };
+    overall: "passed" | "failed" | "partial";
+}
+/**
+ * Test configuration
+ */
+export interface TestConfig {
+    testInvocation?: boolean;
+    testQuotaDetection?: boolean;
+    testErrorParsing?: boolean;
+    testHealthCheck?: boolean;
+    testRateLimiting?: boolean;
+    mockResponses?: boolean;
+    timeout?: number;
+}
+/**
+ * Mock response for testing
+ */
+export interface MockResponse {
+    request: ProviderRequest;
+    response: ProviderResponse;
+    delayMs?: number;
+}
+/**
+ * Compatibility check result
+ */
+export interface CompatibilityResult {
+    compatible: boolean;
+    issues: string[];
+    warnings: string[];
+}
+/**
+ * Registry events
+ */
+export interface RegistryEvents {
+    onAdapterRegistered: (adapter: AdapterInfo) => void;
+    onAdapterUnregistered: (adapterId: string) => void;
+    onAdapterStateChanged: (adapterId: string, state: AdapterState) => void;
+    onHealthCheckFailed: (adapterId: string, result: HealthCheckResult) => void;
+}
+/**
+ * Provider adapter interface
+ */
+export interface ProviderAdapter {
+    name: string;
+    provider?: string;
+    config?: Record<string, unknown>;
+    complete: (prompt: string, options?: Record<string, unknown>) => Promise<ProviderResponse>;
+    streaming?: (prompt: string, options?: Record<string, unknown>) => AsyncGenerator<StreamEvent>;
+    embed?: (input: string) => Promise<number[]>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Stream event from streaming response
+ */
+export interface StreamEvent {
+    type: "content" | "done" | "error";
+    content?: string;
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AAInC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC3B,MAAM,GACN,QAAQ,GACR,MAAM,GACN,MAAM,GACN,KAAK,GACL,UAAU,GACV,UAAU,GACV,OAAO,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,gBAAgB,GAAG,OAAO,CAAC;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAID;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,OAAO,EAAE,eAAe,KACpB,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,aAAa,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,YAAY,CAAC;IACpB,eAAe,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACrB,YAAY,GACZ,cAAc,GACd,OAAO,GACP,OAAO,GACP,aAAa,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE;QACR,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,mBAAmB,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IACpD,qBAAqB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,qBAAqB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACxE,mBAAmB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC5E;AAID;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,EAAE,CACT,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,CACX,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,cAAc,CAAC,WAAW,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf"}

package/packages/provider-adapter-sdk/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Provider Adapter SDK - Types
+ *
+ * Core types for building provider adapters.
+ */
+// ─── SDK Version ────────────────────────────────────────────────────────────
+/**
+ * SDK version for compatibility checks
+ */
+export const SDK_VERSION = "1.0.0";
+//# sourceMappingURL=types.js.map

package/packages/provider-adapter-sdk/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC"}

package/packages/provider-adapter-sdk/examples/custom-adapter.ts

@@ -0,0 +1,353 @@
+/**
+ * Provider Adapter SDK - Examples
+ *
+ * This file demonstrates how to use the Provider Adapter SDK
+ * to create, test, and register custom AI provider adapters.
+ */
+
+import {
+	AdapterBuilder,
+	AdapterRegistry,
+	AdapterTester,
+	type ProviderRequest,
+	type ProviderResponse,
+} from "../src/index.js";
+
+// ─── Example 1: Creating a Simple Custom Adapter ─────────────────────────────
+
+/**
+ * Example of creating a custom provider adapter
+ */
+async function createCustomAdapter() {
+	// Create an adapter using the fluent builder API
+	const myAdapter = new AdapterBuilder("My Custom AI")
+		.id("my-custom-ai")
+		.name("My Custom AI Provider")
+		.models("myai/model-x", "myai/model-y", "myai/model-z")
+		.capabilities("code", "review", "analysis")
+		.rateLimits({
+			requestsPerMinute: 60,
+			tokensPerMinute: 100000,
+		})
+		.defaultModel("myai/model-x")
+		.maxTokens("myai/model-x", 32768)
+		.maxTokens("myai/model-y", 65536)
+		.invoke(async (request: ProviderRequest): Promise<ProviderResponse> => {
+			// In production, this would call your actual API
+			console.log(`Calling API with model: ${request.model}`);
+
+			// Simulate API call
+			const response = await fetch(
+				"https://api.myai.example.com/v1/completions",
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						// "Authorization": `Bearer ${process.env.MYAI_API_KEY}`
+					},
+					body: JSON.stringify({
+						model: request.model,
+						messages: request.messages,
+						temperature: request.temperature,
+						max_tokens: request.maxTokens,
+					}),
+				},
+			);
+
+			if (!response.ok) {
+				const error = await response.text();
+				throw new Error(`API Error: ${response.status} - ${error}`);
+			}
+
+			const data = await response.json();
+			return {
+				content: data.choices[0]?.message?.content || "",
+				model: request.model,
+				finishReason: data.choices[0]?.finish_reason || "stop",
+				usage: {
+					input: data.usage?.prompt_tokens || 0,
+					output: data.usage?.completion_tokens || 0,
+					cost: data.usage?.total_tokens
+						? data.usage.total_tokens * 0.00001
+						: 0,
+				},
+			};
+		})
+		.parseError((error: unknown) => {
+			const e = error as Record<string, unknown>;
+			const msg = String(e.message ?? "");
+			const status = Number(e.status ?? e.statusCode ?? 0);
+
+			return {
+				quotaExceeded: status === 429 || msg.includes("quota"),
+				rateLimited: status === 429,
+				timeout: status === 408 || msg.includes("timeout"),
+				serverError: status >= 500 && status < 600,
+				clientError: status >= 400 && status < 500,
+				message: msg,
+			};
+		})
+		.healthCheck(async () => {
+			try {
+				const start = Date.now();
+				const response = await fetch("https://api.myai.example.com/health", {
+					method: "GET",
+					signal: AbortSignal.timeout(5000),
+				});
+				return {
+					healthy: response.ok,
+					latencyMs: Date.now() - start,
+					message: response.ok ? "OK" : "Service unavailable",
+					timestamp: new Date().toISOString(),
+				};
+			} catch {
+				return {
+					healthy: false,
+					message: "Health check failed",
+					timestamp: new Date().toISOString(),
+				};
+			}
+		})
+		.build();
+
+	return myAdapter;
+}
+
+// ─── Example 2: Using the Registry ───────────────────────────────────────────
+
+/**
+ * Example of using the adapter registry
+ */
+async function useRegistry() {
+	// Create registry
+	const registry = new AdapterRegistry({
+		autoHealthCheck: true,
+		healthCheckInterval: 30000,
+		healthCheckTimeout: 5000,
+	});
+
+	// Create an adapter
+	const adapter = await createCustomAdapter();
+
+	// Register with lifecycle hooks
+	await registry.register(adapter, {
+		async onInit() {
+			console.log(`Initializing adapter: ${adapter.id}`);
+			// Setup connections, load config, etc.
+		},
+		async onTeardown() {
+			console.log(`Tearing down adapter: ${adapter.id}`);
+			// Cleanup resources, close connections, etc.
+		},
+	});
+
+	// List all adapters
+	const allAdapters = registry.listAdapters();
+	console.log(`Registered adapters: ${allAdapters.length}`);
+
+	// List by capability
+	const codeAdapters = registry.listByCapability("code");
+	console.log(`Code-capable adapters: ${codeAdapters.length}`);
+
+	// Invoke adapter
+	const result = await registry.invoke(adapter.id, {
+		model: "myai/model-x",
+		messages: [
+			{ role: "system", content: "You are a helpful assistant." },
+			{ role: "user", content: "Hello!" },
+		],
+		temperature: 0.7,
+		maxTokens: 500,
+	});
+
+	console.log(`Response: ${result.response.content}`);
+
+	// Health check
+	const health = await registry.healthCheck(adapter.id);
+	console.log(`Health: ${health.healthy ? "OK" : "FAIL"}`);
+
+	// Get stats
+	const stats = registry.getStats();
+	console.log(`Total adapters: ${stats.total}`);
+	console.log(`Ready adapters: ${stats.byState.ready}`);
+
+	// Cleanup
+	await registry.unregister(adapter.id);
+}
+
+// ─── Example 3: Testing Adapters ────────────────────────────────────────────
+
+/**
+ * Example of testing an adapter
+ */
+async function testAdapter() {
+	// Create adapter
+	const adapter = await createCustomAdapter();
+
+	// Create tester
+	const tester = new AdapterTester(adapter, {
+		testInvocation: true,
+		testQuotaDetection: true,
+		testErrorParsing: true,
+		testHealthCheck: true,
+		testRateLimiting: false,
+		mockResponses: true, // Use mock mode for testing
+		timeout: 10000,
+	});
+
+	// Add custom mock responses
+	tester.addMockResponse({
+		request: {
+			model: "myai/model-x",
+			messages: [{ role: "user", content: "Test" }],
+		},
+		response: {
+			content: "This is a mock response",
+			model: "myai/model-x",
+			finishReason: "stop",
+			usage: {
+				input: 10,
+				output: 20,
+				cost: 0.001,
+			},
+		},
+	});
+
+	// Generate default mock responses
+	tester.generateMockResponses();
+
+	// Run all tests
+	const report = await tester.runAllTests();
+
+	console.log("Test Report:");
+	console.log(`  Adapter: ${report.adapterId}`);
+	console.log(`  Overall: ${report.overall}`);
+	console.log(
+		`  Results: ${report.summary.passed}/${report.summary.total} passed`,
+	);
+	console.log(`  Duration: ${report.summary.duration}ms`);
+
+	for (const result of report.results) {
+		const status = result.passed ? "✓" : "✗";
+		console.log(
+			`    ${status} ${result.name}: ${result.message || result.error}`,
+		);
+	}
+
+	// Run individual tests
+	const invocationResult = await tester.testBasicInvocation({
+		model: "myai/model-x",
+		messages: [{ role: "user", content: "Hello" }],
+	});
+	console.log(`Invocation test: ${invocationResult.passed ? "PASS" : "FAIL"}`);
+
+	const errorResult = await tester.testErrorParsing();
+	console.log(`Error parsing test: ${errorResult.passed ? "PASS" : "FAIL"}`);
+
+	return report;
+}
+
+// ─── Example 4: Error Handling ────────────────────────────────────────────────
+
+/**
+ * Example of error handling
+ */
+async function errorHandling() {
+	const adapter = await createCustomAdapter();
+
+	try {
+		// Try to invoke with unsupported model
+		const result = await adapter.invoke({
+			model: "unsupported-model",
+			messages: [{ role: "user", content: "Test" }],
+		});
+
+		if (result.response.error) {
+			console.log(`API Error: ${result.response.error}`);
+		}
+
+		if (result.retryable) {
+			console.log("Request is retryable");
+		}
+	} catch (error) {
+		const analysis = adapter.parseError(error);
+		console.log("Error Analysis:");
+		console.log(`  Quota Exceeded: ${analysis.quotaExceeded}`);
+		console.log(`  Rate Limited: ${analysis.rateLimited}`);
+		console.log(`  Timeout: ${analysis.timeout}`);
+		console.log(`  Server Error: ${analysis.serverError}`);
+		console.log(`  Client Error: ${analysis.clientError}`);
+	}
+}
+
+// ─── Example 5: Migration from Existing Adapters ─────────────────────────────
+
+/**
+ * Example of migrating an existing adapter
+ */
+async function migrateExistingAdapter() {
+	// This shows how to migrate from the old adapter pattern
+	// to the new SDK pattern
+
+	const migratedAdapter = new AdapterBuilder("Legacy Provider")
+		.id("legacy-provider")
+		.name("Legacy Provider (Migrated)")
+		.models("legacy/model-v1", "legacy/model-v2")
+		.capabilities("code", "review")
+		.rateLimits({
+			requestsPerMinute: 30,
+			tokensPerDay: 1000000,
+		})
+		.invoke(async (request: ProviderRequest) => {
+			// Your existing invocation logic here
+			return {
+				content: "Legacy response",
+				model: request.model,
+				finishReason: "stop",
+			};
+		})
+		// Keep existing error parsing logic
+		.parseError((error: unknown) => {
+			// Your existing error parsing logic
+			return {
+				quotaExceeded: false,
+				rateLimited: false,
+				timeout: false,
+				serverError: false,
+				clientError: false,
+			};
+		})
+		.build();
+
+	console.log(`Migrated adapter: ${migratedAdapter.id}`);
+	return migratedAdapter;
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+	console.log("Provider Adapter SDK Examples\n");
+
+	console.log("1. Creating a custom adapter...");
+	const adapter = await createCustomAdapter();
+	console.log(
+		`   Created: ${adapter.id} with ${adapter.getModels().length} models`,
+	);
+
+	console.log("\n2. Testing the adapter...");
+	await testAdapter();
+
+	console.log("\n3. Testing error handling...");
+	await errorHandling();
+
+	console.log("\n4. Using the registry...");
+	// await useRegistry(); // Uncomment to run full registry example
+
+	console.log("\n5. Migration example...");
+	await migrateExistingAdapter();
+
+	console.log("\n✓ All examples completed!");
+}
+
+// Run examples
+main().catch(console.error);

package/packages/provider-adapter-sdk/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@pi/provider-adapter-sdk",
+  "version": "0.6.3-beta.13",
+  "description": "SDK for building, testing, and registering AI provider adapters",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "provider",
+    "adapter",
+    "ai",
+    "sdk"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}