@eucoder/rag 0.2.0

package/src/agentic-rag.ts

@@ -0,0 +1,220 @@
+import type { SearchHit } from "@eucode/indexer";
+import type {
+  AgenticRagOptions,
+  AgenticRagResult,
+  ReasoningStep,
+  RagCitation,
+} from "./types.js";
+
+/**
+ * Agentic RAG con Reasoning e Self-Reflection
+ * 
+ * Implementa un ciclo di ragionamento:
+ * 1. Thought: Analizza la query e pianifica l'approccio
+ * 2. Action: Esegue retrieval e grading
+ * 3. Observation: Valuta i risultati
+ * 4. Self-Reflection: Valuta la qualità della risposta
+ * 5. Itera se necessario
+ */
+export class AgenticRag {
+  private options: Required<AgenticRagOptions>;
+
+  constructor(options: AgenticRagOptions) {
+    this.options = {
+      maxIterations: options.maxIterations ?? 3,
+      enableSelfReflection: options.enableSelfReflection ?? true,
+      enableChainOfThought: options.enableChainOfThought ?? true,
+      ...options,
+    };
+  }
+
+  async search(query: string): Promise<AgenticRagResult> {
+    const reasoningSteps: ReasoningStep[] = [];
+    let currentQuery = query;
+    let bestHits: SearchHit[] = [];
+    let bestScore = 0;
+    let iterations = 0;
+
+    // Ciclo di ragionamento
+    for (let i = 0; i < this.options.maxIterations; i++) {
+      iterations++;
+
+      // Step 1: Thought
+      const thought = this.generateThought(currentQuery, i);
+
+      // Step 2: Action - Retrieval
+      const hits = await this.options.retriever.search(currentQuery, 10);
+
+      // Step 3: Action - Grading
+      const gradedHits = await this.gradeHits(currentQuery, hits);
+      const avgScore = gradedHits.length > 0
+        ? gradedHits.reduce((sum, h) => sum + h.score, 0) / gradedHits.length
+        : 0;
+
+      // Step 4: Observation
+      const observation = this.generateObservation(gradedHits, avgScore);
+
+      reasoningSteps.push({
+        thought,
+        action: `Retrieved ${hits.length} hits, graded ${gradedHits.length} as relevant`,
+        observation,
+      });
+
+      // Aggiorna best hits se migliori
+      if (avgScore > bestScore) {
+        bestScore = avgScore;
+        bestHits = gradedHits;
+      }
+
+      // Step 5: Self-Reflection (se abilitato)
+      if (this.options.enableSelfReflection && i < this.options.maxIterations - 1) {
+        const reflection = this.selfReflect(currentQuery, gradedHits, avgScore);
+        
+        if (reflection.shouldRewrite) {
+          // Riscrivi la query
+          currentQuery = await this.options.rewriter.rewrite(
+            currentQuery,
+            gradedHits.map((h) => h.text).join("\n")
+          );
+          continue;
+        } else if (reflection.isSatisfied) {
+          break; // Risultati soddisfacenti
+        }
+      } else if (avgScore > 0.7) {
+        break; // Score足够高, termina
+      }
+    }
+
+    // Genera risposta finale
+    const answer = this.buildAnswer(query, bestHits, reasoningSteps);
+    const citations: RagCitation[] = bestHits.map((hit) => ({
+      path: hit.path,
+      startLine: hit.startLine,
+      endLine: hit.endLine,
+      text: hit.text,
+    }));
+
+    // Self-reflection finale
+    const selfReflection = this.options.enableSelfReflection
+      ? this.finalReflection(query, bestHits, bestScore, iterations)
+      : undefined;
+
+    return {
+      answer,
+      citations,
+      reasoningSteps,
+      selfReflection,
+      iterations,
+      confidence: bestScore,
+    };
+  }
+
+  private generateThought(query: string, iteration: number): string {
+    if (iteration === 0) {
+      return `Analizzo la query: "${query}". Cerco documenti rilevanti e valuto la loro pertinenza.`;
+    } else {
+      return `Iterazione ${iteration + 1}. I risultati precedenti non erano sufficientemente pertinenti. Riscrivo la query per migliorare i risultati.`;
+    }
+  }
+
+  private async gradeHits(query: string, hits: SearchHit[]): Promise<SearchHit[]> {
+    const graded = await Promise.all(
+      hits.map(async (hit) => {
+        const result = await this.options.grader.grade(query, hit);
+        return { ...hit, score: result.score };
+      })
+    );
+
+    return graded
+      .filter((h) => h.score > 0.3)
+      .sort((a, b) => b.score - a.score);
+  }
+
+  private generateObservation(hits: SearchHit[], avgScore: number): string {
+    if (hits.length === 0) {
+      return "Nessun documento rilevante trovato. Score medio: 0";
+    }
+    return `Trovati ${hits.length} documenti rilevanti. Score medio: ${avgScore.toFixed(2)}. Miglior documento: ${hits[0]?.path ?? "N/A"}`;
+  }
+
+  private selfReflect(
+    _query: string,
+    hits: SearchHit[],
+    avgScore: number
+  ): { shouldRewrite: boolean; isSatisfied: boolean } {
+    // Se score è alto, siamo soddisfatti
+    if (avgScore > 0.7 && hits.length >= 3) {
+      return { shouldRewrite: false, isSatisfied: true };
+    }
+
+    // Se score è molto basso, riscrivi
+    if (avgScore < 0.4 || hits.length < 2) {
+      return { shouldRewrite: true, isSatisfied: false };
+    }
+
+    // Score medio, continua ma non riscrivere
+    return { shouldRewrite: false, isSatisfied: false };
+  }
+
+  private buildAnswer(
+    _query: string,
+    hits: SearchHit[],
+    reasoningSteps: ReasoningStep[]
+  ): string {
+    const parts: string[] = [];
+
+    // Chain of Thought (se abilitato)
+    if (this.options.enableChainOfThought && reasoningSteps.length > 0) {
+      parts.push(`## Processo di Ragionamento\n`);
+      reasoningSteps.forEach((step, i) => {
+        parts.push(`### Step ${i + 1}`);
+        parts.push(`**Thought:** ${step.thought}`);
+        parts.push(`**Action:** ${step.action}`);
+        parts.push(`**Observation:** ${step.observation}\n`);
+      });
+    }
+
+    // Risposta finale
+    parts.push(`## Risposta\n`);
+    
+    if (hits.length === 0) {
+      parts.push(`Non sono stati trovati documenti rilevanti per la query fornita.`);
+    } else {
+      parts.push(`Basato su ${hits.length} documenti pertinenti:\n`);
+      
+      hits.slice(0, 5).forEach((hit, i) => {
+        parts.push(`### Fonte ${i + 1}: ${hit.path}`);
+        parts.push(`Righe ${hit.startLine}-${hit.endLine} (score: ${hit.score.toFixed(2)})\n`);
+        parts.push(`\`\`\`\n${hit.text}\n\`\`\`\n`);
+      });
+    }
+
+    return parts.join("\n");
+  }
+
+  private finalReflection(
+    query: string,
+    hits: SearchHit[],
+    avgScore: number,
+    iterations: number
+  ): string {
+    const parts: string[] = [];
+
+    parts.push(`**Valutazione Finale:**`);
+    parts.push(`- Query: "${query}"`);
+    parts.push(`- Iterazioni: ${iterations}`);
+    parts.push(`- Documenti trovati: ${hits.length}`);
+    parts.push(`- Score medio: ${avgScore.toFixed(2)}`);
+    parts.push(`- Confidenza: ${avgScore > 0.7 ? "Alta" : avgScore > 0.4 ? "Media" : "Bassa"}`);
+
+    if (avgScore > 0.7) {
+      parts.push(`\n✅ I risultati sono altamente pertinenti alla query.`);
+    } else if (avgScore > 0.4) {
+      parts.push(`\n⚠️ I risultati sono parzialmente pertinenti. Potrebbe essere necessario raffinare la query.`);
+    } else {
+      parts.push(`\n❌ I risultati non sono sufficientemente pertinenti. Considera di riformulare la query.`);
+    }
+
+    return parts.join("\n");
+  }
+}

package/src/corrective-rag.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest";
+import { CorrectiveRag } from "./corrective-rag.js";
+import type { SearchHit } from "@eucode/indexer";
+import type { Retriever, Grader, QueryRewriter } from "./types.js";
+
+class MockRetriever implements Retriever {
+  constructor(private hits: SearchHit[]) {}
+
+  async search(_query: string, _topK: number): Promise<SearchHit[]> {
+    return this.hits;
+  }
+}
+
+class MockGrader implements Grader {
+  constructor(private relevantIds: Set<string>) {}
+
+  async grade(_query: string, hit: SearchHit) {
+    const relevant = this.relevantIds.has(hit.id);
+    return {
+      relevant,
+      score: relevant ? 0.9 : 0.1,
+    };
+  }
+}
+
+class MockRewriter implements QueryRewriter {
+  async rewrite(query: string, _context: string): Promise<string> {
+    return `${query} (rewritten)`;
+  }
+}
+
+function createHit(id: string, path: string, text: string): SearchHit {
+  return {
+    id,
+    path,
+    startLine: 1,
+    endLine: 10,
+    text,
+    score: 0.5,
+  };
+}
+
+describe("CorrectiveRag", () => {
+  it("returns relevant hits without rewriting when enough good hits", async () => {
+    const hits = [
+      createHit("1", "src/auth.ts", "function login() { ... }"),
+      createHit("2", "src/auth.ts", "function logout() { ... }"),
+      createHit("3", "src/billing.ts", "function charge() { ... }"),
+    ];
+
+    const rag = new CorrectiveRag({
+      retriever: new MockRetriever(hits),
+      grader: new MockGrader(new Set(["1", "2"])),
+      rewriter: new MockRewriter(),
+      minGoodHits: 2,
+    });
+
+    const result = await rag.answer("authentication");
+
+    expect(result.citations).toHaveLength(2);
+    expect(result.rewrites).toBe(0);
+    expect(result.steps).toContain("Initial query: \"authentication\"");
+  });
+
+  it("rewrites query when not enough relevant hits", async () => {
+    const hits = [
+      createHit("1", "src/auth.ts", "function login() { ... }"),
+      createHit("2", "src/billing.ts", "function charge() { ... }"),
+    ];
+
+    const rag = new CorrectiveRag({
+      retriever: new MockRetriever(hits),
+      grader: new MockGrader(new Set(["1"])),
+      rewriter: new MockRewriter(),
+      minGoodHits: 2,
+      maxRewrites: 1,
+    });
+
+    const result = await rag.answer("authentication");
+
+    expect(result.rewrites).toBe(1);
+    expect(result.steps.some((s) => s.includes("Rewriting query"))).toBe(true);
+  });
+
+  it("respects maxRewrites limit", async () => {
+    const hits = [
+      createHit("1", "src/billing.ts", "function charge() { ... }"),
+    ];
+
+    const rag = new CorrectiveRag({
+      retriever: new MockRetriever(hits),
+      grader: new MockGrader(new Set()),
+      rewriter: new MockRewriter(),
+      minGoodHits: 2,
+      maxRewrites: 2,
+    });
+
+    const result = await rag.answer("authentication");
+
+    expect(result.rewrites).toBe(2);
+  });
+
+  it("formats answer with citations", async () => {
+    const hits = [
+      createHit("1", "src/auth.ts", "function login() { return true; }"),
+      createHit("2", "src/auth.ts", "function logout() { return false; }"),
+    ];
+
+    const rag = new CorrectiveRag({
+      retriever: new MockRetriever(hits),
+      grader: new MockGrader(new Set(["1", "2"])),
+      rewriter: new MockRewriter(),
+      minGoodHits: 2,
+    });
+
+    const result = await rag.answer("authentication");
+
+    expect(result.text).toContain("src/auth.ts:1-10");
+    expect(result.citations).toHaveLength(2);
+    expect(result.citations[0].path).toBe("src/auth.ts");
+  });
+
+  it("returns empty answer when no relevant hits found", async () => {
+    const hits = [
+      createHit("1", "src/billing.ts", "function charge() { ... }"),
+    ];
+
+    const rag = new CorrectiveRag({
+      retriever: new MockRetriever(hits),
+      grader: new MockGrader(new Set()),
+      rewriter: new MockRewriter(),
+      minGoodHits: 1,
+      maxRewrites: 0,
+    });
+
+    const result = await rag.answer("authentication");
+
+    expect(result.citations).toHaveLength(0);
+    expect(result.text).toContain("No relevant results found");
+  });
+
+  it("uses web fallback when configured", async () => {
+    const hits = [
+      createHit("1", "src/billing.ts", "function charge() { ... }"),
+    ];
+
+    const webHits = [
+      createHit("web1", "https://example.com", "Web result about auth"),
+    ];
+
+    const rag = new CorrectiveRag({
+      retriever: new MockRetriever(hits),
+      grader: new MockGrader(new Set()),
+      rewriter: new MockRewriter(),
+      minGoodHits: 1,
+      maxRewrites: 0,
+      webFallback: async (_query: string) => webHits,
+    });
+
+    const result = await rag.answer("authentication");
+
+    expect(result.citations).toHaveLength(1);
+    expect(result.citations[0].path).toBe("https://example.com");
+    expect(result.steps.some((s) => s.includes("Falling back to web search"))).toBe(true);
+  });
+});

package/src/corrective-rag.ts

@@ -0,0 +1,115 @@
+import type {
+  CorrectiveRagOptions,
+  RagAnswer,
+  RagCitation,
+  Retriever,
+  Grader,
+  QueryRewriter,
+} from "./types.js";
+
+const DEFAULT_MAX_REWRITES = 1;
+const DEFAULT_MIN_GOOD_HITS = 2;
+const DEFAULT_MIN_SCORE = 0.3;
+const DEFAULT_TOP_K = 8;
+
+export class CorrectiveRag {
+  private retriever: Retriever;
+  private grader: Grader;
+  private rewriter: QueryRewriter;
+  private maxRewrites: number;
+  private minGoodHits: number;
+  private minScore: number;
+  private webFallback?: (query: string) => Promise<any[]>;
+
+  constructor(options: CorrectiveRagOptions) {
+    this.retriever = options.retriever;
+    this.grader = options.grader;
+    this.rewriter = options.rewriter;
+    this.maxRewrites = options.maxRewrites ?? DEFAULT_MAX_REWRITES;
+    this.minGoodHits = options.minGoodHits ?? DEFAULT_MIN_GOOD_HITS;
+    this.minScore = options.minScore ?? DEFAULT_MIN_SCORE;
+    this.webFallback = options.webFallback;
+  }
+
+  async answer(query: string): Promise<RagAnswer> {
+    const steps: string[] = [];
+    let currentQuery = query;
+    let rewrites = 0;
+
+    steps.push(`Initial query: "${query}"`);
+
+    let hits = await this.retriever.search(currentQuery, DEFAULT_TOP_K);
+    steps.push(`Retrieved ${hits.length} candidates`);
+
+    let goodHits = await this.gradeHits(currentQuery, hits);
+    steps.push(`Graded: ${goodHits.length} relevant hits (min score: ${this.minScore})`);
+
+    while (goodHits.length < this.minGoodHits && rewrites < this.maxRewrites) {
+      rewrites++;
+      steps.push(`Rewriting query (attempt ${rewrites}/${this.maxRewrites})`);
+
+      const context = goodHits.map((h) => h.text).join("\n");
+      currentQuery = await this.rewriter.rewrite(currentQuery, context);
+      steps.push(`Rewritten query: "${currentQuery}"`);
+
+      hits = await this.retriever.search(currentQuery, DEFAULT_TOP_K);
+      steps.push(`Retrieved ${hits.length} candidates after rewrite`);
+
+      goodHits = await this.gradeHits(currentQuery, hits);
+      steps.push(`Graded: ${goodHits.length} relevant hits`);
+    }
+
+    if (goodHits.length < this.minGoodHits && this.webFallback) {
+      steps.push(`Falling back to web search`);
+      const webHits = await this.webFallback(currentQuery);
+      goodHits = [...goodHits, ...webHits];
+      steps.push(`Added ${webHits.length} web results`);
+    }
+
+    const citations: RagCitation[] = goodHits.map((hit) => ({
+      path: hit.path,
+      startLine: hit.startLine,
+      endLine: hit.endLine,
+      text: hit.text,
+    }));
+
+    const text = this.formatAnswer(currentQuery, goodHits);
+
+    return {
+      text,
+      citations,
+      steps,
+      rewrites,
+    };
+  }
+
+  private async gradeHits(query: string, hits: any[]): Promise<any[]> {
+    const graded = await Promise.all(
+      hits.map(async (hit) => {
+        const result = await this.grader.grade(query, hit);
+        return { hit, result };
+      })
+    );
+
+    return graded
+      .filter(({ result }) => result.relevant && result.score >= this.minScore)
+      .map(({ hit }) => hit);
+  }
+
+  private formatAnswer(query: string, hits: any[]): string {
+    if (hits.length === 0) {
+      return `No relevant results found for: "${query}"`;
+    }
+
+    const sections = hits.map((hit, i) => {
+      const location = `${hit.path}:${hit.startLine}-${hit.endLine}`;
+      return `## Result ${i + 1} (${location})\n\n${hit.text}`;
+    });
+
+    return sections.join("\n\n---\n\n");
+  }
+}
+
+export function createCorrectiveRag(options: CorrectiveRagOptions): CorrectiveRag {
+  return new CorrectiveRag(options);
+}