ex-brain 0.1.1 → 0.2.0

package/README.md

@@ -65,6 +65,13 @@ ebrain timeline extract companies/river-ai
 ebrain search "some topic"
 ebrain query "some question"
 
+# AI-powered Q&A with LLM (RAG)
+ebrain query --llm "What is the main idea of River AI's product?"
+ebrain query --llm "What are Mario Zechner's main views on game development?"
+
+# Smart ingest: compile + timeline + entity links in one command
+ebrain smart-ingest companies/river-ai --file article.md
+
 # Start MCP Server (for AI tool integration)
 ebrain serve
 ```
@@ -82,12 +89,53 @@ Edit `~/.ebrain/settings.json`:
     "model": "...",
     "dimensions": 1024,
     "apiKey": "sk-..."
+  },
+  "llm": {
+    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "model": "qwen-plus",
+    "apiKey": "sk-..."
+  },
+  "extraction": {
+    "confidenceThreshold": 0.7   // Entity extraction confidence (0~1)
   }
 }
 ```
 
 Run `ebrain config` to view active configuration. See [docs/ebrain-cli.md](docs/ebrain-cli.md) for details.
 
+## AI Q&A (RAG)
+
+Ask natural language questions and get answers based on your knowledge base:
+
+```bash
+# Basic Q&A
+ex-brain query --llm "What is the main idea of River AI's product?"
+
+# Control context depth
+ebrain query --llm "What happened in Q4?" --context-limit 3
+```
+
+How it works:
+
+1. **Semantic Search** — Finds top matching pages for your question
+2. **Multi-Layer Context Collection** — Builds rich context from:
+   - **Page Content** — Compiled truth + timeline for each matched page
+   - **Raw Documents** — Original imported documents (via `raw set`)
+   - **Linked Pages** — Incoming and outgoing linked pages, filtered by semantic relevance to the question
+3. **LLM Synthesis** — Generates a sourced answer with `[[slug|title]]` citations
+
+Configure LLM in `~/.ebrain/settings.json`:
+
+```json
+{
+  "llm": {
+    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "model": "qwen-plus",
+    "apiKey": "sk-..."
+  }
+}
+```
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ex-brain",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "CLI personal knowledge base powered by seekdb",
   "module": "src/cli.ts",
   "type": "module",
@@ -29,6 +29,7 @@
     "@seekdb/openai": "1.2.0",
     "commander": "^14.0.3",
     "gray-matter": "^4.0.3",
+    "jsonrepair": "^3.13.3",
     "pinyin-pro": "^3.28.0",
     "seekdb": "^1.2.0",
     "yaml": "^2.8.3",

package/src/ai/compiler.ts

@@ -1,5 +1,7 @@
 import type { ResolvedLLM } from "../settings";
 import type { TimelineEntry } from "../types";
+import { callLLM, resolveApiKey } from "./llm-client";
+import { jsonrepair } from "jsonrepair";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -116,8 +118,7 @@ async function analyzeNewInfo(
   llm: ResolvedLLM,
 ): Promise<FactAnalysis> {
   const prompt = buildAnalysisPrompt(input);
-  
-  const resp = await callLLM(llm, prompt, 2048);
+  const resp = await callLLM(llm, prompt, 2048, COMPILER_SYSTEM_PROMPT);
   const parsed = parseAnalysisResponse(resp);
   
   return parsed;
@@ -174,8 +175,7 @@ async function smartMergeTruth(
   llm: ResolvedLLM,
 ): Promise<{ compiledTruth: string; changed: boolean; changeType: CompileResult["changeType"]; changeSummary: string }> {
   const prompt = buildMergePrompt(input, analysis);
-  
-  const resp = await callLLM(llm, prompt, 4096);
+  const resp = await callLLM(llm, prompt, 4096, COMPILER_SYSTEM_PROMPT);
   const result = parseMergeResponse(resp);
   
   return result;
@@ -192,7 +192,7 @@ async function extractTimelineFromInfo(
   // Only extract timeline for significant events
   if (analysis.infoType === "status_update" || analysis.infoType === "new_event") {
     const prompt = buildTimelinePrompt(input, analysis);
-    const resp = await callLLM(llm, prompt, 1024);
+    const resp = await callLLM(llm, prompt, 1024, COMPILER_SYSTEM_PROMPT);
     return parseTimelineResponse(resp, input.pageContext?.slug ?? "");
   }
   
@@ -276,7 +276,7 @@ Rewrite the compiled truth. Output ONLY JSON with this schema:
 {
   "compiledTruth": "the full rewritten compiled truth content (markdown format)",
   "changed": true|false,
-  "changeType": "update|replace|conflict|none",
+  "changeType": "append|update|replace|conflict|none",
   "changeSummary": "human-readable summary of what changed"
 }
 
@@ -338,45 +338,8 @@ Rules:
 // LLM Call
 // ---------------------------------------------------------------------------
 
-async function callLLM(llm: ResolvedLLM, prompt: string, maxTokens: number): Promise<string> {
-  const apiKey = resolveApiKey(llm);
-  if (!apiKey) return "";
-
-  const body = {
-    model: llm.model,
-    messages: [
-      { role: "system", content: "You are a knowledge compilation assistant. You analyze information, extract facts, and maintain structured compiled truth. Always output valid JSON. Be precise and factual." },
-      { role: "user", content: prompt },
-    ],
-    temperature: 0.1,
-    max_tokens: maxTokens,
-    enable_thinking: false,
-  };
-
-  try {
-    const resp = await fetch(
-      llm.baseURL.endsWith("/") ? llm.baseURL + "chat/completions" : llm.baseURL + "/chat/completions",
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
-        body: JSON.stringify(body),
-      },
-    );
-
-    if (!resp.ok) {
-      const text = await resp.text();
-      console.warn(`[compiler] LLM call failed (${resp.status}): ${text.slice(0, 200)}`);
-      return "";
-    }
-
-    const data = await resp.json();
-    return data.choices?.[0]?.message?.content?.trim() ?? "";
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    console.warn(`[compiler] LLM call error: ${msg}`);
-    return "";
-  }
-}
+// Use callLLM from llm-client module with custom system prompt
+const COMPILER_SYSTEM_PROMPT = "You are a knowledge compilation assistant. You analyze information, extract facts, and maintain structured compiled truth. Always output valid JSON. Be precise and factual.";
 
 // ---------------------------------------------------------------------------
 // Response Parsing
@@ -389,7 +352,9 @@ function parseAnalysisResponse(resp: string): FactAnalysis {
   }
 
   try {
-    const parsed = JSON.parse(match[0]) as Record<string, unknown>;
+    // Use jsonrepair to fix common LLM JSON issues
+    const repaired = jsonrepair(match[0]);
+    const parsed = JSON.parse(repaired) as Record<string, unknown>;
     
     const facts: ExtractedFact[] = [];
     const rawFacts = parsed.facts as unknown[] ?? [];
@@ -429,7 +394,9 @@ function parseMergeResponse(resp: string): { compiledTruth: string; changed: boo
   }
 
   try {
-    const parsed = JSON.parse(match[0]) as Record<string, unknown>;
+    // Use jsonrepair to fix common LLM JSON issues
+    const repaired = jsonrepair(match[0]);
+    const parsed = JSON.parse(repaired) as Record<string, unknown>;
     return {
       compiledTruth: String(parsed.compiledTruth ?? ""),
       changed: Boolean(parsed.changed),
@@ -451,7 +418,9 @@ function parseTimelineResponse(resp: string, pageSlug: string): TimelineEntry[]
   if (!match) return [];
 
   try {
-    const parsed = JSON.parse(match[0]) as unknown[];
+    // Use jsonrepair to fix common LLM JSON issues
+    const repaired = jsonrepair(match[0]);
+    const parsed = JSON.parse(repaired) as unknown[];
     const entries: TimelineEntry[] = [];
     
     for (const e of parsed) {
@@ -490,11 +459,7 @@ function normalizeChangeType(raw: string): CompileResult["changeType"] {
   return "none";
 }
 
-function resolveApiKey(llm: ResolvedLLM): string {
-  if (llm.apiKey) return llm.apiKey;
-  if (llm.apiKeyEnv) return process.env[llm.apiKeyEnv] ?? "";
-  return "";
-}
+// resolveApiKey is now imported from llm-client module
 
 function appendFact(current: string, newInfo: string, source: string): string {
   const timestamp = new Date().toISOString().slice(0, 10);

package/src/ai/entity-link.ts

@@ -1,4 +1,6 @@
-import { ResolvedLLM } from "../settings";
+import type { ResolvedLLM } from "../settings";
+import { callLLM, resolveApiKey, isLLMConfigured } from "./llm-client";
+import { jsonrepair } from "jsonrepair";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -75,10 +77,15 @@ const RELATION_TYPES = [
 /**
  * Use the configured LLM to extract entity relationships from text.
  * Returns a list of relations with relation type, confidence, and context.
+ * Filters out relations with confidence below the threshold (default: 0.7).
  */
 export async function extractRelations(
   content: string,
   llm: ResolvedLLM,
+  options?: {
+    /** Minimum confidence threshold (0-1). Relations below this are filtered out. Default: 0.7 */
+    confidenceThreshold?: number;
+  },
 ): Promise<ExtractionResult> {
   const trimmed = content.trim();
   if (!trimmed) return [];
@@ -91,65 +98,29 @@ export async function extractRelations(
     context = trimmed.slice(0, 4000) + "\n\n...\n\n" + trimmed.slice(-1000);
   }
 
-  const apiKey = resolveApiKey(llm);
-  if (!apiKey) return [];
-
-  const body = {
-    model: llm.model,
-    messages: [
-      {
-        role: "system",
-        content:
-          "You are a knowledge graph extraction assistant. " +
-          "Identify relationships between named entities. " +
-          "For each relationship, provide: from entity, to entity, relation type, confidence score, and exact context sentence. " +
-          `Allowed relation types: ${RELATION_TYPES}. ` +
-          "Output ONLY a JSON array. Schema: " +
-          '{ "type": "relation", "from": {"name": "...", "type": "..."}, ' +
-          '"to": {"name": "...", "type": "..."}, "relation": "...", "context": "...", "confidence": 0.9 }. ' +
-          "Output ONLY the JSON array. /no_think",
-      },
-      {
-        role: "user",
-        content: `Extract relationships from:\n\n${context}`,
-      },
-    ],
-    temperature: 0.1,
-    max_tokens: 1024,
-    enable_thinking: false,
-  };
+  if (!isLLMConfigured(llm)) return [];
 
-  try {
-    const resp = await fetch(
-      llm.baseURL.endsWith("/")
-        ? llm.baseURL + "chat/completions"
-        : llm.baseURL + "/chat/completions",
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${apiKey}`,
-        },
-        body: JSON.stringify(body),
-      },
-    );
-
-    if (!resp.ok) {
-      const text = await resp.text();
-      console.warn(
-        `[ebrain] Entity extraction failed (${resp.status}): ${text.slice(0, 200)}`,
-      );
-      return [];
-    }
+  const systemPrompt =
+    "You are a knowledge graph extraction assistant. " +
+    "Identify relationships between named entities. " +
+    "For each relationship, provide: from entity, to entity, relation type, confidence score, and exact context sentence. " +
+    `Allowed relation types: ${RELATION_TYPES}. ` +
+    "Output ONLY a JSON array. Schema: " +
+    '{ "type": "relation", "from": {"name": "...", "type": "..."}, ' +
+    '"to": {"name": "...", "type": "..."}, "relation": "...", "context": "...", "confidence": 0.9 }. ' +
+    "Output ONLY the JSON array. /no_think";
 
-    const data = await resp.json();
-    const raw = data.choices?.[0]?.message?.content?.trim();
-    if (!raw) return [];
+  const resp = await callLLM(llm, `Extract relationships from:\n\n${context}`, 1024, systemPrompt);
+  if (!resp) return [];
 
-    const match = raw.match(/\[[\s\S]*\]/);
-    if (!match) return [];
+  // Extract JSON array from response
+  const match = resp.match(/\[[\s\S]*\]/);
+  if (!match) return [];
 
-    const parsed = JSON.parse(match[0]) as unknown[];
+  try {
+    // Use jsonrepair to fix common LLM JSON issues (unterminated strings, etc.)
+    const repaired = jsonrepair(match[0]);
+    const parsed = JSON.parse(repaired) as unknown[];
     const relations: ExtractionResult = [];
 
     for (const item of parsed) {
@@ -175,7 +146,9 @@ export async function extractRelations(
       });
     }
 
-    return relations;
+    // Filter by confidence threshold (default 0.7)
+    const threshold = options?.confidenceThreshold ?? 0.7;
+    return relations.filter((r) => r.confidence >= threshold);
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
     console.warn(`[ebrain] Entity extraction error: ${msg}`);
@@ -219,8 +192,4 @@ export function normalizeRelationType(raw: string): RelationType {
   return "related_to";
 }
 
-function resolveApiKey(llm: ResolvedLLM): string {
-  if (llm.apiKey) return llm.apiKey;
-  if (llm.apiKeyEnv) return process.env[llm.apiKeyEnv] ?? "";
-  return "";
-}
+

package/src/ai/llm-client.ts

@@ -0,0 +1,291 @@
+/**
+ * Unified LLM Client Module
+ * 
+ * Provides centralized LLM calling functionality with:
+ * - Retry mechanism (exponential backoff, max 3 retries)
+ * - Error classification (APIError, TimeoutError, RateLimitError)
+ * - Timeout control
+ * - Unified API key resolution
+ */
+
+import type { ResolvedLLM } from "../settings";
+
+// ---------------------------------------------------------------------------
+// Error Classes
+// ---------------------------------------------------------------------------
+
+export class LLMError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode?: number,
+    public readonly retryable: boolean = false,
+  ) {
+    super(message);
+    this.name = "LLMError";
+  }
+}
+
+export class APIError extends LLMError {
+  constructor(message: string, statusCode?: number) {
+    super(message, "API_ERROR", statusCode, false);
+    this.name = "APIError";
+  }
+}
+
+export class TimeoutError extends LLMError {
+  constructor(message: string = "LLM request timed out") {
+    super(message, "TIMEOUT_ERROR", undefined, true);
+    this.name = "TimeoutError";
+  }
+}
+
+export class RateLimitError extends LLMError {
+  constructor(message: string = "Rate limit exceeded", retryAfter?: number) {
+    super(message, "RATE_LIMIT_ERROR", 429, true);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+  readonly retryAfter?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface LLMClientConfig {
+  /** Maximum number of retry attempts (default: 3) */
+  maxRetries?: number;
+  /** Base delay for exponential backoff in ms (default: 1000) */
+  baseDelay?: number;
+  /** Maximum delay cap in ms (default: 10000) */
+  maxDelay?: number;
+  /** Request timeout in ms (default: 60000) */
+  timeout?: number;
+}
+
+const DEFAULT_CONFIG: Required<LLMClientConfig> = {
+  maxRetries: 3,
+  baseDelay: 1000,
+  maxDelay: 10000,
+  timeout: 60000,
+};
+
+// ---------------------------------------------------------------------------
+// API Key Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve API key from LLM configuration.
+ * Checks direct apiKey first, then falls back to environment variable.
+ */
+export function resolveApiKey(llm: ResolvedLLM): string {
+  if (llm.apiKey) return llm.apiKey;
+  if (llm.apiKeyEnv) return process.env[llm.apiKeyEnv] ?? "";
+  return "";
+}
+
+/**
+ * Check if LLM is properly configured with an API key.
+ */
+export function isLLMConfigured(llm: ResolvedLLM): boolean {
+  return !!resolveApiKey(llm);
+}
+
+// ---------------------------------------------------------------------------
+// LLM Call with Retry
+// ---------------------------------------------------------------------------
+
+/**
+ * Call LLM with unified fetch, retry mechanism, error handling, and timeout.
+ * 
+ * @param llm - Resolved LLM configuration
+ * @param prompt - Prompt to send to the LLM
+ * @param maxTokens - Maximum tokens in response
+ * @param systemPrompt - Optional system prompt (default provided)
+ * @param config - Optional client configuration
+ * @returns Raw response text from LLM, or empty string on failure
+ */
+export async function callLLM(
+  llm: ResolvedLLM,
+  prompt: string,
+  maxTokens: number,
+  systemPrompt: string = "You are a helpful assistant. Always output valid JSON.",
+  config: LLMClientConfig = {},
+): Promise<string> {
+  const apiKey = resolveApiKey(llm);
+  if (!apiKey) {
+    return "";
+  }
+
+  const cfg = { ...DEFAULT_CONFIG, ...config };
+  const url = llm.baseURL.endsWith("/") 
+    ? llm.baseURL + "chat/completions" 
+    : llm.baseURL + "/chat/completions";
+
+  const body = {
+    model: llm.model,
+    messages: [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: prompt },
+    ],
+    temperature: 0.1,
+    max_tokens: maxTokens,
+    enable_thinking: false,
+  };
+
+  let lastError: LLMError | null = null;
+
+  for (let attempt = 0; attempt <= cfg.maxRetries; attempt++) {
+    try {
+      const response = await callWithTimeout(
+        fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify(body),
+        }),
+        cfg.timeout,
+      );
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        lastError = classifyError(response.status, text, response.statusText);
+        
+        // Don't retry for non-retryable errors
+        if (!lastError.retryable || attempt === cfg.maxRetries) {
+          console.warn(`[llm-client] LLM call failed after ${attempt + 1} attempt(s): ${lastError.message}`);
+          return "";
+        }
+        
+        const delay = calculateBackoff(attempt, cfg.baseDelay, cfg.maxDelay, (lastError as RateLimitError).retryAfter);
+        console.warn(`[llm-client] Retrying after ${delay}ms (attempt ${attempt + 1}/${cfg.maxRetries})`);
+        await sleep(delay);
+        continue;
+      }
+
+      const data = await response.json() as { choices?: Array<{ message?: { content?: string } }> };
+      return data.choices?.[0]?.message?.content?.trim() ?? "";
+      
+    } catch (error) {
+      // Classify the error
+      if (error instanceof TimeoutError) {
+        lastError = error;
+      } else if (error instanceof LLMError) {
+        lastError = error;
+      } else {
+        // Unknown error - wrap it
+        const msg = error instanceof Error ? error.message : String(error);
+        lastError = new APIError(`Unexpected error: ${msg}`);
+      }
+
+      // Don't retry if we've exhausted attempts
+      if (attempt === cfg.maxRetries) {
+        console.warn(`[llm-client] LLM call failed after ${attempt + 1} attempt(s): ${lastError.message}`);
+        return "";
+      }
+
+      // Check if error is retryable
+      if (!lastError.retryable) {
+        console.warn(`[llm-client] Non-retryable error: ${lastError.message}`);
+        return "";
+      }
+
+      const delay = calculateBackoff(attempt, cfg.baseDelay, cfg.maxDelay);
+      console.warn(`[llm-client] Retrying after ${delay}ms (attempt ${attempt + 1}/${cfg.maxRetries}): ${lastError.message}`);
+      await sleep(delay);
+    }
+  }
+
+  return "";
+}
+
+/**
+ * Classify HTTP error into appropriate error type.
+ */
+function classifyError(status: number, responseText: string, statusText: string): LLMError {
+  const truncatedText = responseText.slice(0, 200);
+  
+  switch (status) {
+    case 429:
+      // Try to extract retry-after from response
+      const retryAfterMatch = responseText.match(/retry[- ]?after["']?\s*[:=]\s*(\d+)/i);
+      const retryAfter = retryAfterMatch?.[1] ? parseInt(retryAfterMatch[1], 10) : undefined;
+      return new RateLimitError(`Rate limited: ${statusText} - ${truncatedText}`, retryAfter);
+    
+    case 408:
+    case 504:
+      return new TimeoutError(`Request timeout: ${statusText}`);
+    
+    case 500:
+    case 502:
+    case 503:
+      return new APIError(`Server error (${status}): ${truncatedText}`, status);
+    
+    default:
+      if (status >= 500) {
+        return new APIError(`Server error (${status}): ${truncatedText}`, status);
+      }
+      if (status >= 400) {
+        return new APIError(`Client error (${status}): ${truncatedText}`, status);
+      }
+      return new APIError(`HTTP error (${status}): ${truncatedText}`, status);
+  }
+}
+
+/**
+ * Calculate exponential backoff delay with jitter.
+ */
+function calculateBackoff(
+  attempt: number,
+  baseDelay: number,
+  maxDelay: number,
+  retryAfter?: number,
+): number {
+  // If server specified retry-after, use that
+  if (retryAfter && retryAfter > 0) {
+    return Math.min(retryAfter * 1000, maxDelay);
+  }
+  
+  // Exponential backoff: baseDelay * 2^attempt
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  
+  // Add jitter (±25%)
+  const jitter = exponentialDelay * 0.25 * (Math.random() * 2 - 1);
+  
+  return Math.min(Math.round(exponentialDelay + jitter), maxDelay);
+}
+
+/**
+ * Sleep for specified milliseconds.
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Wrap fetch with timeout using Promise.race.
+ */
+async function callWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  let timeoutId: NodeJS.Timeout;
+  
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new TimeoutError(`Request timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    clearTimeout(timeoutId!);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Re-export settings type for convenience
+// ---------------------------------------------------------------------------
+
+export type { ResolvedLLM } from "../settings";