@eucoder/rag 0.2.0

package/src/knowledge-graph.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect } from "vitest";
+import { KnowledgeGraphRag, InMemoryKnowledgeGraph } from "./knowledge-graph.js";
+import type { SearchHit } from "@eucode/indexer";
+import type {
+  Retriever,
+  EntityExtractor,
+  RelationExtractor,
+  Entity,
+  Relation,
+} from "./types.js";
+
+class MockRetriever implements Retriever {
+  async search(_query: string, topK: number): Promise<SearchHit[]> {
+    return [
+      {
+        id: "hit-1",
+        path: "src/user.ts",
+        startLine: 1,
+        endLine: 10,
+        text: "User class with authentication",
+        score: 0.9,
+      },
+      {
+        id: "hit-2",
+        path: "src/auth.ts",
+        startLine: 5,
+        endLine: 15,
+        text: "Authentication service",
+        score: 0.85,
+      },
+    ].slice(0, topK);
+  }
+}
+
+class MockEntityExtractor implements EntityExtractor {
+  async extract(_text: string): Promise<Entity[]> {
+    return [
+      {
+        id: "user",
+        name: "User",
+        type: "class",
+        properties: {},
+      },
+      {
+        id: "auth",
+        name: "Authentication",
+        type: "service",
+        properties: {},
+      },
+    ];
+  }
+}
+
+class MockRelationExtractor implements RelationExtractor {
+  async extract(_text: string, _entities: Entity[]): Promise<Relation[]> {
+    return [
+      {
+        id: "user-auth",
+        source: "user",
+        target: "auth",
+        type: "uses",
+        properties: {},
+      },
+    ];
+  }
+}
+
+describe("KnowledgeGraphRag", () => {
+  it("should extract entities and relations from search results", async () => {
+    const graph = new InMemoryKnowledgeGraph();
+    const kgRag = new KnowledgeGraphRag({
+      retriever: new MockRetriever(),
+      entityExtractor: new MockEntityExtractor(),
+      relationExtractor: new MockRelationExtractor(),
+      graph,
+    });
+
+    const result = await kgRag.search("authentication");
+
+    expect(result.entities.length).toBe(2);
+    expect(result.relations.length).toBe(1);
+    expect(result.citations.length).toBe(2);
+    expect(result.answer).toContain("Knowledge Graph");
+  });
+
+  it("should build graph context with connected entities", async () => {
+    const graph = new InMemoryKnowledgeGraph();
+    const kgRag = new KnowledgeGraphRag({
+      retriever: new MockRetriever(),
+      entityExtractor: new MockEntityExtractor(),
+      relationExtractor: new MockRelationExtractor(),
+      graph,
+      maxDepth: 2,
+    });
+
+    const result = await kgRag.search("user authentication");
+
+    expect(result.graphContext).toContain("User");
+    expect(result.graphContext).toContain("Authentication");
+    expect(result.graphContext).toContain("uses");
+  });
+
+  it("should persist entities in the graph across searches", async () => {
+    const graph = new InMemoryKnowledgeGraph();
+    const kgRag = new KnowledgeGraphRag({
+      retriever: new MockRetriever(),
+      entityExtractor: new MockEntityExtractor(),
+      relationExtractor: new MockRelationExtractor(),
+      graph,
+    });
+
+    await kgRag.search("first query");
+    await kgRag.search("second query");
+
+    expect(graph.entities.size).toBe(2);
+    expect(graph.relations.length).toBe(2);
+  });
+});
+
+describe("InMemoryKnowledgeGraph", () => {
+  it("should add and retrieve entities", () => {
+    const graph = new InMemoryKnowledgeGraph();
+    const entity: Entity = {
+      id: "test",
+      name: "Test",
+      type: "class",
+      properties: {},
+    };
+
+    graph.addEntity(entity);
+    const retrieved = graph.getEntity("test");
+
+    expect(retrieved).toEqual(entity);
+  });
+
+  it("should add and retrieve relations", () => {
+    const graph = new InMemoryKnowledgeGraph();
+    const relation: Relation = {
+      id: "rel1",
+      source: "a",
+      target: "b",
+      type: "uses",
+      properties: {},
+    };
+
+    graph.addRelation(relation);
+    const relations = graph.getRelations("a");
+
+    expect(relations.length).toBe(1);
+    expect(relations[0]).toEqual(relation);
+  });
+
+  it("should find connected entities", () => {
+    const graph = new InMemoryKnowledgeGraph();
+    
+    graph.addEntity({ id: "a", name: "A", type: "class", properties: {} });
+    graph.addEntity({ id: "b", name: "B", type: "class", properties: {} });
+    graph.addEntity({ id: "c", name: "C", type: "class", properties: {} });
+    
+    graph.addRelation({ id: "r1", source: "a", target: "b", type: "uses", properties: {} });
+    graph.addRelation({ id: "r2", source: "b", target: "c", type: "uses", properties: {} });
+
+    const connected = graph.getConnectedEntities("a", 1);
+    expect(connected.length).toBe(1);
+    expect(connected[0]?.id).toBe("b");
+
+    const connectedDeep = graph.getConnectedEntities("a", 2);
+    expect(connectedDeep.length).toBe(2);
+  });
+});

package/src/knowledge-graph.ts

@@ -0,0 +1,182 @@
+import type { SearchHit } from "@eucode/indexer";
+import type {
+  Entity,
+  Relation,
+  KnowledgeGraph,
+  KnowledgeGraphRagOptions,
+  KnowledgeGraphRagResult,
+  RagCitation,
+} from "./types.js";
+
+/**
+ * Implementazione base di Knowledge Graph in memoria
+ */
+export class InMemoryKnowledgeGraph implements KnowledgeGraph {
+  entities: Map<string, Entity> = new Map();
+  relations: Relation[] = [];
+
+  addEntity(entity: Entity): void {
+    this.entities.set(entity.id, entity);
+  }
+
+  addRelation(relation: Relation): void {
+    this.relations.push(relation);
+  }
+
+  getEntity(id: string): Entity | undefined {
+    return this.entities.get(id);
+  }
+
+  getRelations(entityId: string): Relation[] {
+    return this.relations.filter(
+      (r) => r.source === entityId || r.target === entityId
+    );
+  }
+
+  getConnectedEntities(entityId: string, depth: number = 1): Entity[] {
+    const visited = new Set<string>();
+    const result: Entity[] = [];
+
+    const traverse = (currentId: string, currentDepth: number) => {
+      if (currentDepth > depth || visited.has(currentId)) return;
+      visited.add(currentId);
+
+      const entity = this.getEntity(currentId);
+      if (entity && currentId !== entityId) {
+        result.push(entity);
+      }
+
+      if (currentDepth < depth) {
+        const relations = this.getRelations(currentId);
+        for (const rel of relations) {
+          const nextId = rel.source === currentId ? rel.target : rel.source;
+          traverse(nextId, currentDepth + 1);
+        }
+      }
+    };
+
+    traverse(entityId, 0);
+    return result;
+  }
+}
+
+/**
+ * Knowledge Graph RAG - Arricchisce i risultati con contesto da un grafo di conoscenza
+ */
+export class KnowledgeGraphRag {
+  private options: Required<KnowledgeGraphRagOptions>;
+
+  constructor(options: KnowledgeGraphRagOptions) {
+    this.options = {
+      topK: options.topK ?? 10,
+      maxDepth: options.maxDepth ?? 2,
+      ...options,
+    };
+  }
+
+  async search(query: string): Promise<KnowledgeGraphRagResult> {
+    // 1. Recupera risultati dal retriever
+    const hits = await this.options.retriever.search(query, this.options.topK);
+
+    // 2. Estrai entità dai risultati
+    const allText = hits.map((h) => h.text).join("\n");
+    const entities = await this.options.entityExtractor.extract(allText);
+
+    // 3. Aggiungi entità al grafo
+    entities.forEach((e) => this.options.graph.addEntity(e));
+
+    // 4. Estrai relazioni
+    const relations = await this.options.relationExtractor.extract(allText, entities);
+    relations.forEach((r) => this.options.graph.addRelation(r));
+
+    // 5. Arricchisci con contesto del grafo
+    const graphContext = this.buildGraphContext(entities);
+
+    // 6. Genera citazioni
+    const citations: RagCitation[] = hits.map((hit) => ({
+      path: hit.path,
+      startLine: hit.startLine,
+      endLine: hit.endLine,
+      text: hit.text,
+    }));
+
+    // 7. Costruisci risposta
+    const answer = this.buildAnswer(query, hits, entities, relations, graphContext);
+
+    return {
+      answer,
+      citations,
+      entities,
+      relations,
+      graphContext,
+    };
+  }
+
+  private buildGraphContext(entities: Entity[]): string {
+    const contextParts: string[] = [];
+
+    for (const entity of entities) {
+      const connected = this.options.graph.getConnectedEntities(
+        entity.id,
+        this.options.maxDepth
+      );
+      const relations = this.options.graph.getRelations(entity.id);
+
+      if (connected.length > 0 || relations.length > 0) {
+        let part = `**${entity.name}** (${entity.type})`;
+        
+        if (relations.length > 0) {
+          const relDescs = relations.map((r) => {
+            const otherId = r.source === entity.id ? r.target : r.source;
+            const other = this.options.graph.getEntity(otherId);
+            return `${r.type} → ${other?.name ?? otherId}`;
+          });
+          part += `\n  Relazioni: ${relDescs.join(", ")}`;
+        }
+
+        if (connected.length > 0) {
+          const connNames = connected.map((e) => e.name).join(", ");
+          part += `\n  Connesso a: ${connNames}`;
+        }
+
+        contextParts.push(part);
+      }
+    }
+
+    return contextParts.join("\n\n");
+  }
+
+  private buildAnswer(
+    _query: string,
+    hits: SearchHit[],
+    entities: Entity[],
+    _relations: Relation[],
+    graphContext: string
+  ): string {
+    const parts: string[] = [];
+
+    parts.push(`## Risposta\n`);
+    parts.push(`Basato sull'analisi di ${hits.length} documenti e ${entities.length} entità identificate:\n`);
+
+    if (graphContext) {
+      parts.push(`### Contesto dal Knowledge Graph\n${graphContext}\n`);
+    }
+
+    if (hits.length > 0) {
+      parts.push(`### Fonti Principali\n`);
+      hits.slice(0, 3).forEach((hit, i) => {
+        parts.push(`${i + 1}. **${hit.path}** (righe ${hit.startLine}-${hit.endLine})`);
+        parts.push(`   ${hit.text.slice(0, 200)}...\n`);
+      });
+    }
+
+    if (entities.length > 0) {
+      parts.push(`### Entità Identificate\n`);
+      entities.slice(0, 5).forEach((e) => {
+        parts.push(`- **${e.name}** (${e.type})`);
+      });
+    }
+
+    return parts.join("\n");
+  }
+}

package/src/llm-grader.ts

@@ -0,0 +1,69 @@
+import type { SearchHit } from "@eucode/indexer";
+import type { Grader, GraderResult, QueryRewriter } from "./types.js";
+
+export interface LlmProvider {
+  chat(messages: Array<{ role: string; content: string }>): Promise<string>;
+}
+
+export class LlmGrader implements Grader {
+  constructor(private llm: LlmProvider) {}
+
+  async grade(query: string, hit: SearchHit): Promise<GraderResult> {
+    const prompt = `Rate the relevance of this code snippet to the query.
+
+Query: ${query}
+
+Code snippet from ${hit.path}:${hit.startLine}-${hit.endLine}:
+\`\`\`
+${hit.text.slice(0, 500)}
+\`\`\`
+
+Respond with JSON only: {"relevant": true/false, "score": 0.0-1.0}`;
+
+    try {
+      const response = await this.llm.chat([
+        { role: "system", content: "You are a code relevance grader. Respond only with valid JSON." },
+        { role: "user", content: prompt },
+      ]);
+
+      const match = response.match(/\{[\s\S]*\}/);
+      if (!match) {
+        return { relevant: false, score: 0 };
+      }
+
+      const parsed = JSON.parse(match[0]);
+      return {
+        relevant: Boolean(parsed.relevant),
+        score: Number(parsed.score) || 0,
+      };
+    } catch {
+      return { relevant: false, score: 0 };
+    }
+  }
+}
+
+export class LlmQueryRewriter implements QueryRewriter {
+  constructor(private llm: LlmProvider) {}
+
+  async rewrite(query: string, context: string): Promise<string> {
+    const prompt = `The original query didn't find enough relevant results. Rewrite it to be more specific and effective.
+
+Original query: ${query}
+
+Context from partial results:
+${context.slice(0, 300)}
+
+Provide a rewritten query that will find better results. Respond with the query only, no explanation.`;
+
+    try {
+      const response = await this.llm.chat([
+        { role: "system", content: "You are a search query rewriter. Respond with the rewritten query only." },
+        { role: "user", content: prompt },
+      ]);
+
+      return response.trim();
+    } catch {
+      return query;
+    }
+  }
+}

package/src/metrics.ts

@@ -0,0 +1,121 @@
+import type { RagFeedback, RagMetrics } from "./feedback.js";
+
+/**
+ * Calcola metriche aggregate da un array di feedback
+ */
+export class MetricsCalculator {
+  /**
+   * Calcola le metriche per una strategia specifica
+   */
+  static calculateMetrics(feedbacks: RagFeedback[], strategy: string): RagMetrics {
+    if (feedbacks.length === 0) {
+      return {
+        strategy,
+        totalQueries: 0,
+        averageRating: 0,
+        averageRelevance: 0,
+        averageCompleteness: 0,
+        averageCitationsQuality: 0,
+        overallScore: 0,
+        confidence: 0,
+      };
+    }
+
+    const totalQueries = feedbacks.length;
+    
+    // Calcola medie
+    const sumRating = feedbacks.reduce((sum, f) => sum + f.rating, 0);
+    const sumRelevance = feedbacks.reduce((sum, f) => sum + f.relevance, 0);
+    const sumCompleteness = feedbacks.reduce((sum, f) => sum + f.completeness, 0);
+    const sumCitationsQuality = feedbacks.reduce((sum, f) => sum + f.citationsQuality, 0);
+
+    const averageRating = sumRating / totalQueries;
+    const averageRelevance = sumRelevance / totalQueries;
+    const averageCompleteness = sumCompleteness / totalQueries;
+    const averageCitationsQuality = sumCitationsQuality / totalQueries;
+
+    // Overall score: media pesata
+    // Rating (30%), Relevance (30%), Completeness (25%), Citations (15%)
+    const normalizedRating = averageRating / 5; // Normalizza a 0-1
+    const overallScore = 
+      normalizedRating * 0.30 +
+      averageRelevance * 0.30 +
+      averageCompleteness * 0.25 +
+      averageCitationsQuality * 0.15;
+
+    // Confidence: basato sul numero di sample
+    // Minimo 10 sample per avere confidence > 0.5
+    // Massimo confidence a 50+ sample
+    const confidence = Math.min(1, totalQueries / 50);
+
+    return {
+      strategy,
+      totalQueries,
+      averageRating,
+      averageRelevance,
+      averageCompleteness,
+      averageCitationsQuality,
+      overallScore,
+      confidence,
+    };
+  }
+
+  /**
+   * Calcola la deviazione standard per una metrica specifica
+   */
+  static calculateStandardDeviation(
+    feedbacks: RagFeedback[],
+    metric: "rating" | "relevance" | "completeness" | "citationsQuality"
+  ): number {
+    if (feedbacks.length < 2) return 0;
+
+    const values = feedbacks.map((f) => f[metric]);
+    const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+    const squaredDiffs = values.map((v) => Math.pow(v - mean, 2));
+    const variance = squaredDiffs.reduce((sum, v) => sum + v, 0) / (values.length - 1);
+    
+    return Math.sqrt(variance);
+  }
+
+  /**
+   * Calcola l'intervallo di confidenza al 95%
+   */
+  static calculateConfidenceInterval(
+    feedbacks: RagFeedback[],
+    metric: "rating" | "relevance" | "completeness" | "citationsQuality"
+  ): { lower: number; upper: number } {
+    if (feedbacks.length < 2) {
+      const value = feedbacks.length === 1 ? feedbacks[0][metric] : 0;
+      return { lower: value, upper: value };
+    }
+
+    const values = feedbacks.map((f) => f[metric]);
+    const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+    const stdDev = this.calculateStandardDeviation(feedbacks, metric);
+    const marginOfError = 1.96 * (stdDev / Math.sqrt(values.length)); // 95% confidence
+
+    return {
+      lower: Math.max(0, mean - marginOfError),
+      upper: Math.min(metric === "rating" ? 5 : 1, mean + marginOfError),
+    };
+  }
+
+  /**
+   * Identifica trend nei feedback (miglioramento o peggioramento)
+   */
+  static identifyTrend(feedbacks: RagFeedback[], windowSize: number = 10): "improving" | "declining" | "stable" {
+    if (feedbacks.length < windowSize * 2) return "stable";
+
+    const recent = feedbacks.slice(-windowSize);
+    const older = feedbacks.slice(-windowSize * 2, -windowSize);
+
+    const recentAvg = recent.reduce((sum, f) => sum + f.relevance, 0) / recent.length;
+    const olderAvg = older.reduce((sum, f) => sum + f.relevance, 0) / older.length;
+
+    const diff = recentAvg - olderAvg;
+    
+    if (diff > 0.05) return "improving";
+    if (diff < -0.05) return "declining";
+    return "stable";
+  }
+}