@rkarim08/sia 1.0.0

package/src/llm/provider-registry.ts

@@ -0,0 +1,68 @@
+import type { AiSdkAdapter } from "@/llm/ai-sdk-adapter";
+
+/** Roles an LLM provider can fulfil within the Sia pipeline. */
+export type OperationRole = "extract" | "consolidate" | "summarize" | "validate";
+
+/** How raw knowledge enters the graph. */
+export type CaptureMode = "hooks" | "api" | "hybrid";
+
+/** Provider + model pair for a specific role. */
+export interface ProviderConfig {
+	provider: string; // "anthropic" | "openai" | "google" | "ollama"
+	model: string;
+}
+
+/**
+ * Registry that maps each OperationRole to a ProviderConfig.
+ * Determines which roles are active based on the current CaptureMode.
+ */
+export class ProviderRegistry {
+	private configs = new Map<OperationRole, ProviderConfig>();
+	private captureMode: CaptureMode = "hooks";
+
+	setCaptureMode(mode: CaptureMode): void {
+		this.captureMode = mode;
+	}
+
+	getCaptureMode(): CaptureMode {
+		return this.captureMode;
+	}
+
+	setProvider(role: OperationRole, config: ProviderConfig): void {
+		this.configs.set(role, config);
+	}
+
+	getProvider(role: OperationRole): ProviderConfig | undefined {
+		return this.configs.get(role);
+	}
+
+	/**
+	 * Whether a role is active given the current capture mode.
+	 * In hooks mode, extract and consolidate are dormant (handled by the host agent).
+	 * In api or hybrid mode, all roles are active.
+	 */
+	isRoleActive(role: OperationRole): boolean {
+		if (this.captureMode === "api") return true;
+		if (this.captureMode === "hooks") {
+			return role === "summarize" || role === "validate";
+		}
+		// hybrid: all active
+		return true;
+	}
+
+	/** Get all configured providers for diagnostics. */
+	getAll(): Map<OperationRole, ProviderConfig> {
+		return new Map(this.configs);
+	}
+
+	/**
+	 * Resolve an AiSdkAdapter for the given role, or null if no provider is
+	 * configured for that role or the provider is unsupported by the AI SDK.
+	 */
+	async adapt(role: OperationRole): Promise<AiSdkAdapter | null> {
+		const config = this.getProvider(role);
+		if (!config) return null;
+		const { createAdapter } = await import("@/llm/ai-sdk-adapter");
+		return createAdapter(config);
+	}
+}

package/src/llm/reliability.ts

@@ -0,0 +1,179 @@
+/** Configuration for the reliability wrapper. */
+export interface ReliabilityConfig {
+	maxRetries: number;
+	fallbackChain: string[];
+	circuitBreakerThreshold: number;
+	circuitBreakerWindowMs: number;
+}
+
+export interface CircuitBreakerOptions {
+	/** Failure ratio (0-1) that triggers the circuit to open. Default 0.5. */
+	threshold?: number;
+	/** Window in ms for tracking failures. Default 60000. */
+	windowMs?: number;
+	/** Minimum number of operations before the breaker can trip. Default 3. */
+	minSamples?: number;
+}
+
+/**
+ * Circuit breaker that tracks success/failure ratios and opens
+ * the circuit when the failure rate exceeds the configured threshold.
+ */
+export class CircuitBreaker {
+	private failures = 0;
+	private successes = 0;
+	private state: "closed" | "open" | "half-open" = "closed";
+	private lastFailureTime = 0;
+	private readonly threshold: number;
+	private readonly windowMs: number;
+	private readonly minSamples: number;
+
+	constructor(options?: CircuitBreakerOptions) {
+		this.threshold = options?.threshold ?? 0.5;
+		this.windowMs = options?.windowMs ?? 60000;
+		this.minSamples = options?.minSamples ?? 3;
+	}
+
+	/** Whether the circuit is open (rejecting calls). */
+	isOpen(): boolean {
+		if (this.state === "open") {
+			// Check if the window has expired — transition to half-open
+			if (Date.now() - this.lastFailureTime > this.windowMs) {
+				this.state = "half-open";
+				return false;
+			}
+			return true;
+		}
+		return false;
+	}
+
+	/** Record a successful operation. Closes the circuit if half-open. */
+	recordSuccess(): void {
+		this.successes++;
+		if (this.state === "half-open") {
+			this.state = "closed";
+		}
+	}
+
+	/** Record a failed operation. Opens the circuit if threshold exceeded and minimum samples met. */
+	recordFailure(): void {
+		this.failures++;
+		this.lastFailureTime = Date.now();
+		const total = this.failures + this.successes;
+		if (total >= this.minSamples && this.failures / total >= this.threshold) {
+			this.state = "open";
+		}
+	}
+
+	/** Reset all counters and close the circuit. */
+	reset(): void {
+		this.failures = 0;
+		this.successes = 0;
+		this.state = "closed";
+		this.lastFailureTime = 0;
+	}
+
+	/** Get diagnostic stats. */
+	getStats(): { state: string; failures: number; successes: number } {
+		// Refresh state check (window may have expired)
+		if (this.state === "open" && Date.now() - this.lastFailureTime > this.windowMs) {
+			this.state = "half-open";
+		}
+		return {
+			state: this.state,
+			failures: this.failures,
+			successes: this.successes,
+		};
+	}
+}
+
+/**
+ * Attempt to repair malformed JSON from LLM responses.
+ *
+ * LLMs sometimes produce JSON with:
+ * - Trailing commas in arrays/objects
+ * - Single quotes instead of double quotes
+ * - Unquoted property names
+ * - Missing closing brackets
+ * - Markdown code fences wrapping the JSON
+ *
+ * This handles the most common cases (~30% of malformed responses)
+ * without requiring a retry, saving both latency and cost.
+ */
+export function repairJson(text: string): string {
+	let s = text.trim();
+
+	// Strip markdown code fences: ```json ... ``` or ``` ... ```
+	s = s.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/, "");
+
+	// Strip leading/trailing whitespace again after fence removal
+	s = s.trim();
+
+	// Replace single quotes around keys/values with double quotes
+	// (only when they look like JSON — not inside string values)
+	s = s.replace(/(?<=[{[,:\s])'/g, '"').replace(/'(?=[}\],:\s])/g, '"');
+
+	// Remove trailing commas before } or ]
+	s = s.replace(/,\s*([}\]])/g, "$1");
+
+	// Try to close unclosed brackets (count openers vs closers)
+	const opens = (s.match(/\{/g) || []).length;
+	const closes = (s.match(/\}/g) || []).length;
+	for (let i = 0; i < opens - closes; i++) {
+		s += "}";
+	}
+	const openBrackets = (s.match(/\[/g) || []).length;
+	const closeBrackets = (s.match(/\]/g) || []).length;
+	for (let i = 0; i < openBrackets - closeBrackets; i++) {
+		s += "]";
+	}
+
+	return s;
+}
+
+/**
+ * Parse JSON with repair fallback. First tries JSON.parse directly.
+ * On failure, runs repairJson and retries. Returns parsed object or throws.
+ */
+export function parseJsonWithRepair<T>(text: string): T {
+	try {
+		return JSON.parse(text) as T;
+	} catch {
+		const repaired = repairJson(text);
+		return JSON.parse(repaired) as T;
+	}
+}
+
+/**
+ * Wrap an async operation with retry + circuit breaker.
+ * Returns the result or throws after all retries are exhausted.
+ */
+export async function withReliability<T>(
+	operation: () => Promise<T>,
+	breaker: CircuitBreaker,
+	maxRetries = 3,
+): Promise<T> {
+	if (breaker.isOpen()) {
+		throw new Error("Circuit breaker is open — request rejected");
+	}
+
+	let lastError: Error | undefined;
+
+	for (let attempt = 0; attempt < maxRetries; attempt++) {
+		try {
+			const result = await operation();
+			breaker.recordSuccess();
+			return result;
+		} catch (err) {
+			lastError = err instanceof Error ? err : new Error(String(err));
+			breaker.recordFailure();
+
+			// If the circuit just opened, stop retrying
+			if (breaker.isOpen()) {
+				break;
+			}
+		}
+	}
+
+	throw lastError ?? new Error("withReliability: all retries exhausted");
+}

package/src/llm/schemas.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+/**
+ * Unified extraction result schema.
+ * Used by BOTH hooks extractors AND LLM provider — same shape regardless of source.
+ */
+export const SiaExtractionResult = z.object({
+	entities: z.array(
+		z.object({
+			kind: z.enum(["Decision", "Convention", "Bug", "Solution", "Concept"]),
+			name: z.string().min(3).max(200),
+			content: z.string().min(10).max(2000),
+			confidence: z.number().min(0).max(1),
+			tags: z.array(z.string()).max(5),
+			relates_to: z.array(z.string()),
+		}),
+	),
+	_meta: z
+		.object({
+			source: z.enum(["hook", "llm", "claude-directive"]),
+			input_tokens: z.number().optional(),
+			output_tokens: z.number().optional(),
+		})
+		.optional(),
+});
+
+/** Consolidation decision for incoming vs existing entities. */
+export const SiaConsolidationResult = z.object({
+	decision: z.enum(["ADD", "UPDATE", "INVALIDATE", "NOOP"]),
+	target_id: z.string().nullable(),
+	reasoning: z.string().optional(),
+});
+
+/** Community or cluster summary result. */
+export const SiaSummaryResult = z.object({
+	summary: z.string().min(10).max(2000),
+	key_entities: z.array(z.string()).max(10),
+	confidence: z.number().min(0).max(1),
+});
+
+/** Fact validation result for freshness/correctness checks. */
+export const SiaValidationResult = z.object({
+	is_valid: z.boolean(),
+	confidence: z.number().min(0).max(1),
+	reasoning: z.string(),
+	action: z.enum(["confirm", "invalidate", "flag_for_review"]),
+});
+
+export type SiaExtractionResultType = z.infer<typeof SiaExtractionResult>;
+export type SiaConsolidationResultType = z.infer<typeof SiaConsolidationResult>;
+export type SiaSummaryResultType = z.infer<typeof SiaSummaryResult>;
+export type SiaValidationResultType = z.infer<typeof SiaValidationResult>;

package/src/mcp/freshness-annotator.ts

@@ -0,0 +1,69 @@
+// Module: freshness-annotator — Adds freshness state to MCP tool results.
+//
+// Wraps entity results with a freshness annotation so Claude knows
+// whether the source file has changed since the knowledge was captured.
+
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface FreshnessAnnotatedEntity {
+	[key: string]: unknown;
+	freshness: "fresh" | "stale" | "rotten" | "unknown";
+	freshness_note?: string;
+}
+
+/**
+ * Annotate an array of entity results with freshness state.
+ *
+ * For each entity with file_paths, checks if the source file's mtime
+ * is newer than the entity's updated_at timestamp. This is a lightweight
+ * check — not the full DirtyTracker pipeline.
+ */
+export async function annotateFreshness(
+	entities: Array<Record<string, unknown>>,
+	db: SiaDb | null,
+): Promise<FreshnessAnnotatedEntity[]> {
+	if (!db) {
+		return entities.map((e) => ({ ...e, freshness: "unknown" as const }));
+	}
+
+	const { statSync } = await import("node:fs");
+	const { resolve } = await import("node:path");
+
+	return entities.map((entity) => {
+		const filePaths = entity.file_paths as string | null;
+		if (!filePaths) {
+			return { ...entity, freshness: "unknown" as const };
+		}
+
+		try {
+			const paths = JSON.parse(filePaths) as string[];
+			if (paths.length === 0) {
+				return { ...entity, freshness: "unknown" as const };
+			}
+
+			const absPath = resolve(process.cwd(), paths[0]);
+			const fileMtime = statSync(absPath).mtimeMs;
+			const entityUpdated = (entity.updated_at as number) ?? (entity.created_at as number) ?? 0;
+
+			if (fileMtime <= entityUpdated) {
+				return { ...entity, freshness: "fresh" as const };
+			}
+
+			const staleDays = (fileMtime - entityUpdated) / (1000 * 60 * 60 * 24);
+			if (staleDays > 30) {
+				return {
+					...entity,
+					freshness: "rotten" as const,
+					freshness_note: `Source file changed ${Math.round(staleDays)} days after capture — verify before using`,
+				};
+			}
+			return {
+				...entity,
+				freshness: "stale" as const,
+				freshness_note: "Source file changed since capture — may need verification",
+			};
+		} catch {
+			return { ...entity, freshness: "unknown" as const };
+		}
+	});
+}