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

package/packages/provider-router/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@pi-harness/provider-router",
+  "version": "0.6.3-beta.13",
+  "description": "Enhanced Provider Router for pi-harness-runtime — intelligent routing with capabilities, costs, and quotas",
+  "type": "module",
+  "main": "./dist/provider-router.js",
+  "types": "./dist/provider-router.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/provider-router.js",
+      "types": "./dist/provider-router.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "pi",
+    "harness",
+    "runtime",
+    "provider",
+    "router",
+    "routing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "bun-types": "^1.0.0"
+  }
+}

package/packages/provider-router/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Provider Router Package (RFC-0054)
+ *
+ * Enhanced provider routing with capability, cost, and quota awareness.
+ *
+ * @example
+ * ```typescript
+ * import { createProviderRouter, DEFAULT_ROUTING_POLICY } from "@pi-harness/provider-router";
+ *
+ * const router = createProviderRouter();
+ *
+ * const decision = await router.selectProvider(task, context, {
+ *   preferCheapest: true,
+ *   requiredCapabilities: ["code_generation"],
+ * });
+ * ```
+ */
+
+// Types
+export type {
+	RoutingStrategy,
+	RoutingPolicy,
+	QuotaState,
+	RoutingContext,
+	RoutingOptions,
+	ProviderCandidate,
+	RoutingDecision,
+	ProviderRouter,
+	ProviderRouterEvent,
+	Latency,
+} from "./types.js";
+
+export { LATENCY_RANK } from "./types.js";
+
+// Router
+export {
+	EnhancedProviderRouter,
+	createProviderRouter,
+} from "./provider-router.js";
+
+// Policy
+export { DEFAULT_ROUTING_POLICY, createRoutingPolicy } from "./policy.js";
+
+// Strategies
+export {
+	applyStrategy,
+	calculateWeightedScore,
+	createDecision,
+} from "./strategies.js";

package/packages/provider-router/src/policy.ts

@@ -0,0 +1,50 @@
+/**
+ * Default Routing Policy (RFC-0054)
+ */
+
+import type { RoutingPolicy } from "./types.js";
+
+export const DEFAULT_ROUTING_POLICY: RoutingPolicy = {
+	defaultStrategy: "balanced",
+	costWeight: 30,
+	qualityWeight: 40,
+	latencyWeight: 20,
+	quotaWeight: 10,
+	fallbackProviders: ["anthropic", "openai"],
+	taskTypeOverrides: {
+		planning: "best_quality",
+		code_generation: "balanced",
+		code_review: "best_quality",
+		test_generation: "fastest",
+		e2e_testing: "quota_aware",
+		analysis: "best_quality",
+		refactoring: "balanced",
+		debugging: "fastest",
+		documentation: "cheapest",
+	},
+	providerPreferences: {
+		minimax: 20, // prefer cheaper options
+		openai: 0,
+		anthropic: 10,
+	},
+};
+
+/**
+ * Create a custom routing policy
+ */
+export function createRoutingPolicy(
+	overrides: Partial<RoutingPolicy>,
+): RoutingPolicy {
+	return {
+		...DEFAULT_ROUTING_POLICY,
+		...overrides,
+		taskTypeOverrides: {
+			...DEFAULT_ROUTING_POLICY.taskTypeOverrides,
+			...overrides.taskTypeOverrides,
+		},
+		providerPreferences: {
+			...DEFAULT_ROUTING_POLICY.providerPreferences,
+			...overrides.providerPreferences,
+		},
+	};
+}

package/packages/provider-router/src/provider-router.ts

@@ -1,42 +1,315 @@
-import type { ProviderSelection, RuntimeContext, RuntimeTask } from "../../types/src/runtime-types";
+/**
+ * Enhanced Provider Router (RFC-0054)
+ */
 
-export interface RoutingPolicy {
-  plannerProvider: string;
-  codeProviders: string[];
-  reviewProvider: string;
-  fallbackProviders: string[];
+import type {
+	ProviderCandidate,
+	ProviderRouter,
+	ProviderRouterEvent,
+	RoutingContext,
+	RoutingDecision,
+	RoutingOptions,
+	RoutingPolicy,
+	RoutingStrategy,
+} from "./types.js";
+import { DEFAULT_ROUTING_POLICY } from "./policy.js";
+import {
+	applyStrategy,
+	createDecision,
+	calculateWeightedScore,
+} from "./strategies.js";
+
+type EventHandler = (event: ProviderRouterEvent) => void;
+
+interface CandidateProvider {
+	providerId: string;
+	modelId: string;
+	estimatedCost?: number;
+	estimatedLatency?: "fast" | "medium" | "slow";
+	qualityScore?: number;
 }
 
-export class SimpleProviderRouter {
-  constructor(private readonly policy: RoutingPolicy) {}
+/**
+ * Enhanced Provider Router with capability and cost awareness
+ */
+export class EnhancedProviderRouter implements ProviderRouter {
+	private policy: RoutingPolicy;
+	private eventHandlers: Set<EventHandler> = new Set();
+
+	// Default providers for fallback
+	private defaultCandidates: CandidateProvider[] = [
+		{
+			providerId: "anthropic",
+			modelId: "claude-sonnet-4",
+			estimatedCost: 0.003, // $3/1M tokens average
+			estimatedLatency: "fast",
+			qualityScore: 90,
+		},
+		{
+			providerId: "openai",
+			modelId: "gpt-4o-mini",
+			estimatedCost: 0.0006,
+			estimatedLatency: "fast",
+			qualityScore: 82,
+		},
+		{
+			providerId: "minimax",
+			modelId: "MiniMax-Text-01",
+			estimatedCost: 0.0001,
+			estimatedLatency: "fast",
+			qualityScore: 75,
+		},
+		{
+			providerId: "google",
+			modelId: "gemini-1.5-flash",
+			estimatedCost: 0.00007,
+			estimatedLatency: "fast",
+			qualityScore: 78,
+		},
+	];
+
+	constructor(policy?: RoutingPolicy) {
+		this.policy = policy ?? DEFAULT_ROUTING_POLICY;
+	}
+
+	/**
+	 * Select the best provider for a task
+	 */
+	async selectProvider(
+		task: RoutingContext["task"],
+		context: RoutingContext,
+		options?: RoutingOptions,
+	): Promise<RoutingDecision> {
+		const candidates = this.buildCandidates(context, options);
+
+		// Filter candidates
+		const filtered = this.filterCandidates(candidates, context, options);
+
+		if (filtered.length === 0) {
+			this.emit({
+				type: "router.no_candidates",
+				taskId: task.id,
+				reason: "All candidates filtered out",
+			});
+
+			// Fallback to default
+			const fallback = this.policy.fallbackProviders[0];
+			const defaultCandidate =
+				this.defaultCandidates.find((c) => c.providerId === fallback) ??
+				this.defaultCandidates[0];
+
+			return createDecision(
+				{
+					providerId: defaultCandidate.providerId,
+					modelId: defaultCandidate.modelId,
+					capabilities: [],
+					estimatedCost: defaultCandidate.estimatedCost,
+					estimatedLatency: defaultCandidate.estimatedLatency ?? "medium",
+					qualityScore: defaultCandidate.qualityScore,
+					remainingQuotaPct:
+						context.quotaStates[defaultCandidate.providerId]?.remainingPct ?? 1,
+				},
+				`Fallback to ${defaultCandidate.providerId}`,
+			);
+		}
+
+		// Determine strategy
+		const strategy = this.determineStrategy(task, options);
+
+		// Apply strategy
+		const selected = applyStrategy(filtered, strategy, this.policy, options);
+
+		const decision = createDecision(
+			selected,
+			`Selected via ${strategy} strategy`,
+		);
+
+		this.emit({
+			type: "router.provider_selected",
+			taskId: task.id,
+			providerId: decision.providerId,
+			reason: decision.reason,
+		});
+
+		return decision;
+	}
+
+	/**
+	 * Select multiple providers
+	 */
+	async selectProviders(
+		task: RoutingContext["task"],
+		context: RoutingContext,
+		count: number,
+	): Promise<RoutingDecision[]> {
+		const candidates = this.buildCandidates(context);
+		const sorted = candidates.sort((a, b) => {
+			return (
+				calculateWeightedScore(b, this.policy) -
+				calculateWeightedScore(a, this.policy)
+			);
+		});
+
+		const selected = sorted.slice(0, count);
 
-  async selectProvider(task: RuntimeTask, context: RuntimeContext): Promise<ProviderSelection> {
-    const candidates = this.candidatesForTask(task);
+		return selected.map((c, i) =>
+			createDecision(c, `Ranked #${i + 1} for ${task.id}`),
+		);
+	}
 
-    for (const providerId of candidates) {
-      const state = context.providerStates[providerId] ?? "unknown";
-      if (state === "available" || state === "unknown") {
-        return {
-          providerId,
-          reason: `selected ${providerId} for task ${task.id}; state=${state}`,
-        };
-      }
-    }
+	/**
+	 * Get current routing policy
+	 */
+	getRoutingPolicy(): RoutingPolicy {
+		return { ...this.policy };
+	}
 
-    throw new Error(`No available provider for task ${task.id}`);
-  }
+	/**
+	 * Update routing policy
+	 */
+	setRoutingPolicy(policy: RoutingPolicy): void {
+		const oldPolicy = this.policy;
+		this.policy = policy;
 
-  private candidatesForTask(task: RuntimeTask): string[] {
-    const title = task.title.toLowerCase();
+		this.emit({
+			type: "router.policy_updated",
+			oldPolicy,
+			newPolicy: policy,
+		});
+	}
 
-    if (title.includes("plan") || title.includes("architecture")) {
-      return [this.policy.plannerProvider, ...this.policy.fallbackProviders];
-    }
+	/**
+	 * Subscribe to events
+	 */
+	onEvent(handler: EventHandler): () => void {
+		this.eventHandlers.add(handler);
+		return () => this.eventHandlers.delete(handler);
+	}
 
-    if (title.includes("review") || title.includes("diff")) {
-      return [this.policy.reviewProvider, ...this.policy.fallbackProviders];
-    }
+	/**
+	 * Build candidate list from context
+	 */
+	private buildCandidates(
+		context: RoutingContext,
+		options?: RoutingOptions,
+	): ProviderCandidate[] {
+		const candidates: ProviderCandidate[] = [];
+
+		// Add default candidates
+		for (const candidate of this.defaultCandidates) {
+			const providerState =
+				context.providerStates[candidate.providerId] ?? "unknown";
+			const quotaState = context.quotaStates[candidate.providerId];
+
+			// Skip disabled providers
+			if (providerState === "disabled") continue;
+
+			candidates.push({
+				providerId: candidate.providerId,
+				modelId: candidate.modelId,
+				capabilities: [], // Would be populated from capability registry
+				estimatedCost: candidate.estimatedCost,
+				estimatedLatency: candidate.estimatedLatency ?? "medium",
+				qualityScore: candidate.qualityScore,
+				remainingQuotaPct: quotaState?.remainingPct ?? 1,
+			});
+		}
+
+		return candidates;
+	}
+
+	/**
+	 * Filter candidates based on options and context
+	 */
+	private filterCandidates(
+		candidates: ProviderCandidate[],
+		context: RoutingContext,
+		options?: RoutingOptions,
+	): ProviderCandidate[] {
+		let filtered = [...candidates];
+
+		// Filter by cost
+		if (options?.maxCostPerTask) {
+			filtered = filtered.filter(
+				(c) => (c.estimatedCost ?? Infinity) <= options.maxCostPerTask!,
+			);
+		}
+
+		// Filter by quota
+		filtered = filtered.filter((c) => {
+			const quota = context.quotaStates[c.providerId];
+			return !quota || !quota.exhausted;
+		});
+
+		// Filter by provider state
+		filtered = filtered.filter((c) => {
+			const state = context.providerStates[c.providerId] ?? "unknown";
+			return state !== "disabled" && state !== "exhausted";
+		});
+
+		// Prefer providers
+		if (options?.preferProviders?.length) {
+			filtered.sort((a, b) => {
+				const aPreferred = options.preferProviders!.includes(a.providerId)
+					? 1
+					: 0;
+				const bPreferred = options.preferProviders!.includes(b.providerId)
+					? 1
+					: 0;
+				return bPreferred - aPreferred;
+			});
+		}
+
+		// Avoid providers
+		if (options?.avoidProviders?.length) {
+			filtered = filtered.filter(
+				(c) => !options.avoidProviders!.includes(c.providerId),
+			);
+		}
+
+		return filtered;
+	}
+
+	/**
+	 * Determine routing strategy for a task
+	 */
+	private determineStrategy(
+		task: RoutingContext["task"],
+		options?: RoutingOptions,
+	): RoutingStrategy {
+		// Check for explicit preferences
+		if (options?.preferCheapest) return "cheapest";
+		if (options?.preferFastest) return "fastest";
+		if (options?.preferHighestQuality) return "best_quality";
+
+		// Check task type override
+		if (this.policy.taskTypeOverrides[task.type]) {
+			return this.policy.taskTypeOverrides[task.type];
+		}
+
+		// Fall back to default
+		return this.policy.defaultStrategy;
+	}
+
+	/**
+	 * Emit an event
+	 */
+	private emit(event: ProviderRouterEvent): void {
+		for (const handler of this.eventHandlers) {
+			try {
+				handler(event);
+			} catch {
+				// Ignore handler errors
+			}
+		}
+	}
+}
 
-    return [...this.policy.codeProviders, ...this.policy.fallbackProviders];
-  }
+/**
+ * Create a new provider router
+ */
+export function createProviderRouter(
+	policy?: RoutingPolicy,
+): EnhancedProviderRouter {
+	return new EnhancedProviderRouter(policy);
 }

package/packages/provider-router/src/strategies.ts

@@ -0,0 +1,158 @@
+/**
+ * Routing Strategies (RFC-0054)
+ */
+
+import type {
+	ProviderCandidate,
+	RoutingDecision,
+	RoutingPolicy,
+	RoutingStrategy,
+} from "./types.js";
+import { LATENCY_RANK } from "./types.js";
+
+/**
+ * Apply a routing strategy to select the best candidate
+ */
+export function applyStrategy(
+	candidates: ProviderCandidate[],
+	strategy: RoutingStrategy,
+	policy: RoutingPolicy,
+	options?: { preferProviders?: string[] },
+): ProviderCandidate {
+	switch (strategy) {
+		case "cheapest":
+			return selectCheapest(candidates);
+
+		case "fastest":
+			return selectFastest(candidates);
+
+		case "best_quality":
+			return selectBestQuality(candidates);
+
+		case "balanced":
+			return selectBalanced(candidates, policy);
+
+		case "quota_aware":
+			return selectQuotaAware(candidates);
+
+		default:
+			return selectBalanced(candidates, policy);
+	}
+}
+
+/**
+ * Select the cheapest candidate
+ */
+function selectCheapest(candidates: ProviderCandidate[]): ProviderCandidate {
+	return candidates.reduce((cheapest, current) =>
+		(current.estimatedCost ?? Infinity) < (cheapest.estimatedCost ?? Infinity)
+			? current
+			: cheapest,
+	);
+}
+
+/**
+ * Select the fastest candidate
+ */
+function selectFastest(candidates: ProviderCandidate[]): ProviderCandidate {
+	return candidates.reduce((fastest, current) =>
+		LATENCY_RANK[current.estimatedLatency] <
+		LATENCY_RANK[fastest.estimatedLatency]
+			? current
+			: fastest,
+	);
+}
+
+/**
+ * Select the highest quality candidate
+ */
+function selectBestQuality(candidates: ProviderCandidate[]): ProviderCandidate {
+	return candidates.reduce((best, current) =>
+		(current.qualityScore ?? 0) > (best.qualityScore ?? 0) ? current : best,
+	);
+}
+
+/**
+ * Select based on weighted scoring
+ */
+function selectBalanced(
+	candidates: ProviderCandidate[],
+	policy: RoutingPolicy,
+): ProviderCandidate {
+	return candidates.reduce((best, current) => {
+		const scoreBest = calculateWeightedScore(best, policy);
+		const scoreCurrent = calculateWeightedScore(current, policy);
+		return scoreCurrent > scoreBest ? current : best;
+	});
+}
+
+/**
+ * Select based on quota availability
+ */
+function selectQuotaAware(candidates: ProviderCandidate[]): ProviderCandidate {
+	return candidates.reduce((best, current) => {
+		const quotaBest = best.remainingQuotaPct ?? 0;
+		const quotaCurrent = current.remainingQuotaPct ?? 0;
+		const costBest = best.estimatedCost ?? Infinity;
+		const costCurrent = current.estimatedCost ?? Infinity;
+		// Prefer high quota / low cost
+		const ratioBest = quotaBest / (costBest || 1);
+		const ratioCurrent = quotaCurrent / (costCurrent || 1);
+		return ratioCurrent > ratioBest ? current : best;
+	});
+}
+
+/**
+ * Calculate weighted score for a candidate
+ */
+export function calculateWeightedScore(
+	candidate: ProviderCandidate,
+	policy: RoutingPolicy,
+): number {
+	// Cost score (inverse - lower is better)
+	const maxReasonableCost = 1; // $1 per task
+	const costScore =
+		100 -
+		Math.min(((candidate.estimatedCost ?? 0) * 100) / maxReasonableCost, 100);
+
+	// Quality score (already 0-100)
+	const qualityScore = candidate.qualityScore ?? 50;
+
+	// Latency score (inverse)
+	const latencyScore = 100 - LATENCY_RANK[candidate.estimatedLatency] * 33;
+
+	// Quota score (0-100)
+	const quotaScore = (candidate.remainingQuotaPct ?? 1) * 100;
+
+	// Normalize weights
+	const totalWeight =
+		policy.costWeight +
+		policy.qualityWeight +
+		policy.latencyWeight +
+		policy.quotaWeight;
+
+	return (
+		(costScore * policy.costWeight +
+			qualityScore * policy.qualityWeight +
+			latencyScore * policy.latencyWeight +
+			quotaScore * policy.quotaWeight) /
+		totalWeight
+	);
+}
+
+/**
+ * Create a routing decision from a candidate
+ */
+export function createDecision(
+	candidate: ProviderCandidate,
+	reason: string,
+): RoutingDecision {
+	return {
+		providerId: candidate.providerId,
+		modelId: candidate.modelId,
+		reason,
+		estimatedCost: candidate.estimatedCost,
+		estimatedLatency: candidate.estimatedLatency,
+		confidence: candidate.qualityScore ? candidate.qualityScore / 100 : 0.8,
+	};
+}