@rkarim08/sia 1.0.0

package/src/knowledge/templates.ts

@@ -0,0 +1,307 @@
+// Module: templates — .sia/templates/ loader and validator for knowledge authoring
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+export interface TemplateField {
+	description: string;
+	required: boolean;
+}
+
+export interface KnowledgeTemplate {
+	name: string;
+	kind: string;
+	fields: Record<string, TemplateField>;
+	tagsPrefix: string[];
+	autoRelate: boolean;
+}
+
+/**
+ * Load all templates from a .sia/templates/ directory.
+ * Templates are YAML files defining structured fields for knowledge entry.
+ *
+ * Returns a map of template name -> template definition.
+ */
+export function loadTemplates(siaDir: string): Map<string, KnowledgeTemplate> {
+	const templates = new Map<string, KnowledgeTemplate>();
+	const templatesDir = join(siaDir, "templates");
+
+	if (!existsSync(templatesDir)) {
+		return templates;
+	}
+
+	let entries: string[];
+	try {
+		entries = readdirSync(templatesDir);
+	} catch {
+		return templates;
+	}
+
+	for (const entry of entries) {
+		if (!entry.endsWith(".yaml") && !entry.endsWith(".yml")) {
+			continue;
+		}
+
+		const filePath = join(templatesDir, entry);
+		let content: string;
+		try {
+			content = readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const parsed = parseSimpleYaml(content);
+		const name = basename(entry).replace(/\.ya?ml$/, "");
+
+		const rawFields = parsed.fields as Record<string, Record<string, unknown>> | undefined;
+		const fields: Record<string, TemplateField> = {};
+
+		if (rawFields && typeof rawFields === "object") {
+			for (const [fieldName, fieldDef] of Object.entries(rawFields)) {
+				if (fieldDef && typeof fieldDef === "object") {
+					fields[fieldName] = {
+						description: String(fieldDef.description ?? ""),
+						required: fieldDef.required === true,
+					};
+				}
+			}
+		}
+
+		const rawTagsPrefix = parsed.tags_prefix;
+		let tagsPrefix: string[] = [];
+		if (Array.isArray(rawTagsPrefix)) {
+			tagsPrefix = rawTagsPrefix.map(String);
+		}
+
+		const template: KnowledgeTemplate = {
+			name,
+			kind: String(parsed.kind ?? ""),
+			fields,
+			tagsPrefix,
+			autoRelate: parsed.auto_relate === true,
+		};
+
+		templates.set(name, template);
+	}
+
+	return templates;
+}
+
+/**
+ * Validate properties against a template's required fields.
+ * Returns an array of error messages (empty if valid).
+ */
+export function validateTemplate(
+	template: KnowledgeTemplate,
+	properties: Record<string, unknown>,
+): string[] {
+	const errors: string[] = [];
+
+	for (const [fieldName, field] of Object.entries(template.fields)) {
+		if (!field.required) {
+			continue;
+		}
+
+		const value = properties[fieldName];
+		if (value === undefined || value === null || value === "") {
+			errors.push(`Missing required field "${fieldName}": ${field.description}`);
+		}
+	}
+
+	return errors;
+}
+
+/**
+ * Get a specific template by name.
+ * Returns undefined if not found.
+ */
+export function getTemplate(
+	templates: Map<string, KnowledgeTemplate>,
+	name: string,
+): KnowledgeTemplate | undefined {
+	return templates.get(name);
+}
+
+/**
+ * Simple YAML parser for template files.
+ * Handles the subset of YAML used by templates (flat and one-level nested objects).
+ *
+ * Supported syntax:
+ * - Top-level `key: value` pairs
+ * - Nested objects (2-space or tab indented)
+ * - Inline arrays `[item1, item2]`
+ * - Boolean values (true/false)
+ * - Quoted and unquoted string values
+ */
+function parseSimpleYaml(content: string): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	const lines = content.split("\n");
+
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i] as string;
+
+		// Skip empty lines and comments
+		if (line.trim() === "" || line.trim().startsWith("#")) {
+			i++;
+			continue;
+		}
+
+		// Top-level key: must start at column 0 (no indentation)
+		if (line[0] !== " " && line[0] !== "\t") {
+			const colonIdx = line.indexOf(":");
+			if (colonIdx === -1) {
+				i++;
+				continue;
+			}
+
+			const key = line.slice(0, colonIdx).trim();
+			const rawValue = line.slice(colonIdx + 1).trim();
+
+			if (rawValue === "") {
+				// This is a nested object — collect indented lines
+				const nested: Record<string, unknown> = {};
+				i++;
+				const nestedResult = parseNestedBlock(lines, i);
+				Object.assign(nested, nestedResult.data);
+				i = nestedResult.nextIndex;
+				result[key] = nested;
+			} else {
+				result[key] = parseValue(rawValue);
+				i++;
+			}
+		} else {
+			// Indented line at top level — skip (shouldn't happen in well-formed input)
+			i++;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Parse a block of indented lines as a nested object.
+ * Handles one-level nesting (fields with sub-properties).
+ */
+function parseNestedBlock(
+	lines: string[],
+	startIdx: number,
+): { data: Record<string, unknown>; nextIndex: number } {
+	const data: Record<string, unknown> = {};
+	let i = startIdx;
+
+	while (i < lines.length) {
+		const line = lines[i] as string;
+
+		// Empty line — continue (might be within the block)
+		if (line.trim() === "" || line.trim().startsWith("#")) {
+			i++;
+			continue;
+		}
+
+		// Check if this line is indented (part of the block)
+		if (line[0] !== " " && line[0] !== "\t") {
+			// Back at top level — stop
+			break;
+		}
+
+		const indent = getIndentLevel(line);
+		const trimmed = line.trim();
+
+		const colonIdx = trimmed.indexOf(":");
+		if (colonIdx === -1) {
+			i++;
+			continue;
+		}
+
+		const key = trimmed.slice(0, colonIdx).trim();
+		const rawValue = trimmed.slice(colonIdx + 1).trim();
+
+		if (rawValue === "") {
+			// Sub-nested object (second level)
+			const subNested: Record<string, unknown> = {};
+			i++;
+
+			while (i < lines.length) {
+				const subLine = lines[i] as string;
+				if (subLine.trim() === "" || subLine.trim().startsWith("#")) {
+					i++;
+					continue;
+				}
+
+				const subIndent = getIndentLevel(subLine);
+				if (subIndent <= indent) {
+					break;
+				}
+
+				const subTrimmed = subLine.trim();
+				const subColonIdx = subTrimmed.indexOf(":");
+				if (subColonIdx !== -1) {
+					const subKey = subTrimmed.slice(0, subColonIdx).trim();
+					const subRawValue = subTrimmed.slice(subColonIdx + 1).trim();
+					subNested[subKey] = parseValue(subRawValue);
+				}
+				i++;
+			}
+
+			data[key] = subNested;
+		} else {
+			data[key] = parseValue(rawValue);
+			i++;
+		}
+	}
+
+	return { data, nextIndex: i };
+}
+
+/** Determine the indentation level of a line (number of leading spaces/tabs). */
+function getIndentLevel(line: string): number {
+	let count = 0;
+	for (const ch of line) {
+		if (ch === " ") {
+			count++;
+		} else if (ch === "\t") {
+			count += 2;
+		} else {
+			break;
+		}
+	}
+	return count;
+}
+
+/** Parse a scalar or inline-array YAML value. */
+function parseValue(raw: string): unknown {
+	// Remove trailing comments
+	const commentIdx = raw.indexOf(" #");
+	const cleaned = commentIdx !== -1 ? raw.slice(0, commentIdx).trim() : raw;
+
+	// Boolean
+	if (cleaned === "true") return true;
+	if (cleaned === "false") return false;
+
+	// Null
+	if (cleaned === "null" || cleaned === "~") return null;
+
+	// Inline array: [item1, item2]
+	if (cleaned.startsWith("[") && cleaned.endsWith("]")) {
+		const inner = cleaned.slice(1, -1).trim();
+		if (inner === "") return [];
+		return inner.split(",").map((item) => parseValue(item.trim()));
+	}
+
+	// Quoted string
+	if (
+		(cleaned.startsWith('"') && cleaned.endsWith('"')) ||
+		(cleaned.startsWith("'") && cleaned.endsWith("'"))
+	) {
+		return cleaned.slice(1, -1);
+	}
+
+	// Number
+	if (/^-?\d+(\.\d+)?$/.test(cleaned)) {
+		return Number(cleaned);
+	}
+
+	// Plain string
+	return cleaned;
+}

package/src/llm/ai-sdk-adapter.ts

@@ -0,0 +1,46 @@
+import type { ProviderConfig } from "@/llm/provider-registry";
+
+/**
+ * Adapter that resolves a ProviderConfig to an actual AI SDK model
+ * and executes text generation.
+ *
+ * Falls back gracefully if the AI SDK or provider packages aren't available.
+ */
+export class AiSdkAdapter {
+	private config: ProviderConfig;
+
+	constructor(config: ProviderConfig) {
+		this.config = config;
+	}
+
+	async generate(prompt: string): Promise<string> {
+		const { generateText } = await import("ai");
+		const model = await this.resolveModel();
+		const result = await generateText({ model, prompt });
+		return result.text;
+	}
+
+	private async resolveModel() {
+		switch (this.config.provider) {
+			case "anthropic": {
+				const { anthropic } = await import("@ai-sdk/anthropic");
+				return anthropic(this.config.model);
+			}
+			case "openai": {
+				const { openai } = await import("@ai-sdk/openai");
+				return openai(this.config.model);
+			}
+			default:
+				throw new Error(`Unsupported AI SDK provider: ${this.config.provider}`);
+		}
+	}
+}
+
+/**
+ * Create an adapter from a ProviderConfig, or null if the provider is unsupported.
+ */
+export function createAdapter(config: ProviderConfig): AiSdkAdapter | null {
+	const supported = ["anthropic", "openai"];
+	if (!supported.includes(config.provider)) return null;
+	return new AiSdkAdapter(config);
+}

package/src/llm/config.ts

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { CaptureMode, OperationRole, ProviderConfig } from "./provider-registry";
+
+/** Full LLM configuration for Sia. */
+export interface SiaLlmConfig {
+	capture: {
+		mode: CaptureMode;
+		hookPort: number;
+	};
+	providers: Record<OperationRole, ProviderConfig>;
+	fallback: {
+		enabled: boolean;
+		chain: string[];
+		maxRetries: number;
+	};
+	costTracking: {
+		enabled: boolean;
+		budgetPerDay: number;
+	};
+}
+
+/** Get the built-in default config (hooks mode, Anthropic for summarize/validate). */
+export function getDefaultLlmConfig(): SiaLlmConfig {
+	return {
+		capture: {
+			mode: "hooks",
+			hookPort: 4521,
+		},
+		providers: {
+			summarize: { provider: "anthropic", model: "claude-sonnet-4" },
+			validate: { provider: "ollama", model: "qwen2.5-coder:7b" },
+			extract: { provider: "anthropic", model: "claude-haiku-4-5" },
+			consolidate: { provider: "anthropic", model: "claude-haiku-4-5" },
+		},
+		fallback: {
+			enabled: true,
+			chain: ["anthropic", "openai", "ollama"],
+			maxRetries: 3,
+		},
+		costTracking: {
+			enabled: true,
+			budgetPerDay: 5.0,
+		},
+	};
+}
+
+/**
+ * Load config from a YAML-like config file path, or return defaults.
+ * Currently supports a simple JSON config; full YAML support can be added later.
+ */
+export function loadLlmConfig(configPath?: string): SiaLlmConfig {
+	const defaults = getDefaultLlmConfig();
+
+	if (!configPath || !existsSync(configPath)) {
+		return defaults;
+	}
+
+	try {
+		const raw = readFileSync(configPath, "utf-8");
+		const parsed = JSON.parse(raw) as Partial<SiaLlmConfig>;
+		return mergeConfig(defaults, parsed);
+	} catch {
+		// If the file can't be parsed, return defaults
+		return defaults;
+	}
+}
+
+/** Deep-merge a partial config onto the defaults. */
+function mergeConfig(defaults: SiaLlmConfig, partial: Partial<SiaLlmConfig>): SiaLlmConfig {
+	return {
+		capture: {
+			...defaults.capture,
+			...(partial.capture ?? {}),
+		},
+		providers: {
+			...defaults.providers,
+			...(partial.providers ?? {}),
+		},
+		fallback: {
+			...defaults.fallback,
+			...(partial.fallback ?? {}),
+		},
+		costTracking: {
+			...defaults.costTracking,
+			...(partial.costTracking ?? {}),
+		},
+	};
+}

package/src/llm/cost-tracker.ts

@@ -0,0 +1,110 @@
+import type { OperationRole } from "./provider-registry";
+
+/** A single LLM API call record. */
+export interface CostEntry {
+	timestamp: number;
+	provider: string;
+	model: string;
+	role: OperationRole;
+	input_tokens: number;
+	output_tokens: number;
+	estimated_cost: number;
+}
+
+/**
+ * Per-call cost tracking with optional daily budget enforcement.
+ * Entries are kept in-memory; a future persistence layer can flush to the meta database.
+ */
+export class CostTracker {
+	private entries: CostEntry[] = [];
+	private readonly dailyBudget: number | undefined;
+
+	constructor(dailyBudget?: number) {
+		this.dailyBudget = dailyBudget;
+	}
+
+	/** Log a call and attach a timestamp. */
+	logCall(entry: Omit<CostEntry, "timestamp">): void {
+		this.entries.push({ ...entry, timestamp: Date.now() });
+	}
+
+	/** Get today's total spend (UTC day boundary). */
+	getTodaySpend(): number {
+		const todayStart = startOfDayUtc(Date.now());
+		return this.entries
+			.filter((e) => e.timestamp >= todayStart)
+			.reduce((sum, e) => sum + e.estimated_cost, 0);
+	}
+
+	/** Check if the daily budget has been exceeded. */
+	isBudgetExceeded(): boolean {
+		if (this.dailyBudget === undefined) return false;
+		return this.getTodaySpend() >= this.dailyBudget;
+	}
+
+	/** Get all entries, optionally filtered to those after a timestamp. */
+	getEntries(since?: number): CostEntry[] {
+		if (since === undefined) return [...this.entries];
+		return this.entries.filter((e) => e.timestamp >= since);
+	}
+
+	/**
+	 * Estimate cost in USD based on provider, model, and token counts.
+	 * Uses approximate per-million-token pricing.
+	 */
+	static estimateCost(
+		provider: string,
+		model: string,
+		inputTokens: number,
+		outputTokens: number,
+	): number {
+		// Local models are free
+		if (provider === "ollama" || provider === "local") {
+			return 0;
+		}
+
+		const rates = getCostRates(provider, model);
+		const inputCost = (inputTokens / 1_000_000) * rates.inputPerMillion;
+		const outputCost = (outputTokens / 1_000_000) * rates.outputPerMillion;
+		return inputCost + outputCost;
+	}
+}
+
+/** Returns UTC midnight for the given timestamp. */
+function startOfDayUtc(ts: number): number {
+	const d = new Date(ts);
+	d.setUTCHours(0, 0, 0, 0);
+	return d.getTime();
+}
+
+interface CostRates {
+	inputPerMillion: number;
+	outputPerMillion: number;
+}
+
+/** Approximate per-million-token pricing. */
+function getCostRates(provider: string, model: string): CostRates {
+	if (provider === "anthropic") {
+		if (model.includes("haiku")) {
+			return { inputPerMillion: 0.8, outputPerMillion: 4.0 };
+		}
+		if (model.includes("sonnet")) {
+			return { inputPerMillion: 3.0, outputPerMillion: 15.0 };
+		}
+		if (model.includes("opus")) {
+			return { inputPerMillion: 15.0, outputPerMillion: 75.0 };
+		}
+	}
+
+	if (provider === "openai") {
+		if (model.includes("gpt-4o-mini")) {
+			return { inputPerMillion: 0.15, outputPerMillion: 0.6 };
+		}
+		if (model.includes("gpt-4o")) {
+			return { inputPerMillion: 2.5, outputPerMillion: 10.0 };
+		}
+	}
+
+	// Fallback: generic cloud pricing
+	return { inputPerMillion: 1.0, outputPerMillion: 5.0 };
+}

package/src/llm/prompts/extraction.ts

@@ -0,0 +1,55 @@
+// src/llm/prompts/extraction.ts — Batch extraction prompt for api/hybrid capture mode
+
+/**
+ * Extraction prompt for api/hybrid capture mode.
+ * Used when hooks are unavailable (non-Claude-Code agents, CLI batch operations).
+ *
+ * Uses XML-delimited sections for cross-provider compatibility.
+ * Works across Claude, GPT, Gemini, and Ollama without modification.
+ */
+export function batchExtractionPrompt(
+	transcriptChunk: string,
+	context?: Array<{ name: string; type: string }>,
+): { system: string; user: string } {
+	const system = [
+		"<instructions>",
+		"Extract structured knowledge facts from the following development session transcript.",
+		"",
+		"For each fact, identify:",
+		"- Entity: the named concept, file, function, decision, or convention",
+		"- Type: Technology | File | Function | Decision | Convention | Bug | Pattern | Other",
+		"- Summary: a concise description of what is known about this entity",
+		"- Relationships: connections to other entities (optional)",
+		"",
+		"Guidelines:",
+		"- Extract only factual, reusable knowledge — skip transient reasoning steps.",
+		"- Focus on architectural decisions, naming conventions, API contracts, and technical patterns.",
+		"- Prefer specificity: 'uses bun:sqlite via SiaDb adapter' over 'uses a database'.",
+		"- Output valid JSON: { entities: Array<{ name: string, type: string, summary: string, related?: string[] }> }",
+		"</instructions>",
+	].join("\n");
+
+	const contextBlock = buildContextBlock(context);
+	const user = [
+		contextBlock,
+		"<transcript>",
+		transcriptChunk,
+		"</transcript>",
+		"",
+		"Extract all knowledge entities from the transcript above. Return JSON with an `entities` array.",
+	]
+		.filter(Boolean)
+		.join("\n");
+
+	return { system, user };
+}
+
+/** Build the context block if prior entities are provided. */
+function buildContextBlock(context?: Array<{ name: string; type: string }>): string {
+	if (!context || context.length === 0) return "";
+
+	const lines = context.map((e) => `- ${e.name} (${e.type})`).join("\n");
+	return ["<context>", "Known entities (avoid duplicating these):", lines, "</context>", ""].join(
+		"\n",
+	);
+}

package/src/llm/prompts/summarization.ts

@@ -0,0 +1,36 @@
+/**
+ * Prompt templates for community summarization (always-active LLM role).
+ */
+
+/**
+ * Build a system + user prompt pair for summarizing a community of entities.
+ * Used by the RAPTOR summarization pipeline and community detection.
+ */
+export function communitySummaryPrompt(
+	entityNames: string[],
+	entitySummaries: string[],
+): { system: string; user: string } {
+	const system = [
+		"You are Sia, a knowledge-graph memory system for software projects.",
+		"Your task is to produce a concise, coherent summary of a cluster of related knowledge entities.",
+		"",
+		"Guidelines:",
+		"- Write a single paragraph (2-5 sentences) that captures the common theme.",
+		"- Mention the most important entities by name.",
+		"- Focus on actionable information: decisions, conventions, patterns.",
+		"- Do NOT list entities — synthesize them into a narrative.",
+		"- Output valid JSON matching: { summary: string, key_entities: string[], confidence: number }",
+	].join("\n");
+
+	const entityBlock = entityNames
+		.map((name, i) => `### ${name}\n${entitySummaries[i] ?? "(no summary)"}`)
+		.join("\n\n");
+
+	const user = [
+		"Summarize the following community of knowledge entities:\n",
+		entityBlock,
+		"\nReturn JSON with: summary (coherent paragraph), key_entities (up to 10 most important names), confidence (0-1).",
+	].join("\n");
+
+	return { system, user };
+}

package/src/llm/prompts/validation.ts

@@ -0,0 +1,37 @@
+/**
+ * Prompt templates for fact validation (always-active LLM role).
+ */
+
+/**
+ * Build a system + user prompt pair for validating whether a stored fact
+ * is still correct given current code context.
+ */
+export function factValidationPrompt(
+	factContent: string,
+	codeContext: string,
+): { system: string; user: string } {
+	const system = [
+		"You are Sia, a knowledge-graph memory system for software projects.",
+		"Your task is to validate whether a previously stored fact is still accurate",
+		"given the current state of the codebase.",
+		"",
+		"Guidelines:",
+		"- Compare the fact against the provided code context.",
+		"- If the code confirms the fact, respond with action: 'confirm'.",
+		"- If the code contradicts the fact, respond with action: 'invalidate'.",
+		"- If you are unsure, respond with action: 'flag_for_review'.",
+		"- Output valid JSON matching: { is_valid: boolean, confidence: number, reasoning: string, action: 'confirm' | 'invalidate' | 'flag_for_review' }",
+	].join("\n");
+
+	const user = [
+		"## Stored Fact",
+		factContent,
+		"",
+		"## Current Code Context",
+		codeContext,
+		"",
+		"Is this fact still valid? Return JSON with: is_valid, confidence (0-1), reasoning, action.",
+	].join("\n");
+
+	return { system, user };
+}