@farukada/langchain-ts-rms 0.1.0

package/dist/app/summarization/summarizer.js

@@ -0,0 +1,181 @@
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { logInfo, logWarn } from "../../infra/observability/tracing.js";
+import { SourceSummaryOutputSchema } from "./summarizationSchema.js";
+import { batchExtractContent } from "../../infra/content/contentExtractor.js";
+// ── Helpers ───────────────────────────────────────────────────────
+/**
+ * Normalizes tags: lowercase, replace spaces with hyphens, deduplicate, sort.
+ * Ensures consistent tag format across all sources.
+ */
+export function normalizeTags(tags) {
+    const normalized = new Set(tags.map((t) => t.trim().toLowerCase().replace(/\s+/g, "-")).filter((t) => t.length > 0));
+    return [...normalized].sort();
+}
+// ── Constants ────────────────────────────────────────────────────
+/** Maximum characters of extracted content to include per source in the prompt. */
+const MAX_CHARS_PER_SOURCE = 8000;
+/** Minimum acceptable length for a keyTakeaways field (chars). Below this, retry once. */
+const MIN_TAKEAWAY_LENGTH = 200;
+// ── Prompt ────────────────────────────────────────────────────────
+const SYSTEM_PROMPT = `You are a research extraction assistant. Your takeaways feed into a synthesis step that produces a research report for developers.
+
+Before extracting, consider: what specific facts does this source contribute, and what concrete details would a developer find actionable?
+
+Guidelines:
+1. Focus on facts, techniques, tools, numbers, and actionable insights relevant to the research subject.
+2. Be concrete — include names, version numbers, code patterns, and configuration values.
+3. Write substantive multi-paragraph extractions covering all noteworthy information.
+4. If the source has no useful information, write "No relevant information found." and set relevance to 0.
+5. Score relevance generously: 0.7-1.0 for on-topic sources, 0.4-0.7 for partially relevant, below 0.3 only for truly off-topic.`;
+// ── Core logic ──────────────────────────────────────────────────────
+/**
+ * Summarizes a single source via a focused LLM call.
+ *
+ * If the LLM call fails or produces a thin takeaway, retries once with a
+ * reinforced prompt. If both attempts fail, returns a degraded fallback
+ * using the snippet.
+ */
+async function summarizeSingleSource(subject, searchResult, contentText, wasExtracted, sourceIndex, totalSources, chatModel) {
+    const contentLabel = wasExtracted ? "Full Page Content" : "Snippet";
+    const truncatedText = contentText.slice(0, MAX_CHARS_PER_SOURCE);
+    const humanMsg = `Research subject:\n<subject>\n${subject}\n</subject>\n\n` +
+        `--- Source ---\n` +
+        `Title: ${searchResult.title}\n` +
+        `URL: ${searchResult.url}\n\n` +
+        `<source_content type="${contentLabel}">\n${truncatedText}\n</source_content>\n\n` +
+        `Extract key takeaways from this source.`;
+    try {
+        const structuredModel = chatModel.withStructuredOutput(SourceSummaryOutputSchema, {
+            method: "jsonSchema",
+            name: "source_summary",
+        });
+        let result = await structuredModel.invoke([
+            new SystemMessage(SYSTEM_PROMPT),
+            new HumanMessage(humanMsg),
+        ]);
+        // Quality gate: if takeaway is too thin, retry once with reinforced prompt
+        if (result.keyTakeaways.trim().length < MIN_TAKEAWAY_LENGTH) {
+            logWarn(`Source [${String(sourceIndex + 1)}/${String(totalSources)}] takeaway too thin, retrying`, {
+                node: "summarizer",
+                url: searchResult.url,
+                takeawayLength: result.keyTakeaways.trim().length,
+            });
+            const retryMsg = humanMsg +
+                "\n\nIMPORTANT: Your previous response had a very short takeaway. " +
+                "Write a substantially longer extraction with much more detail. " +
+                "Extract specific facts, version numbers, code patterns, and actionable advice from the source.";
+            result = await structuredModel.invoke([
+                new SystemMessage(SYSTEM_PROMPT),
+                new HumanMessage(retryMsg),
+            ]);
+        }
+        logInfo(`Source [${String(sourceIndex + 1)}/${String(totalSources)}] summarized`, {
+            node: "summarizer",
+            url: searchResult.url,
+            takeawayLength: result.keyTakeaways.trim().length,
+            relevance: result.relevance,
+        });
+        return {
+            url: searchResult.url,
+            title: searchResult.title,
+            keyTakeaways: result.keyTakeaways.trim(),
+            relevance: Math.min(1, Math.max(0, result.relevance ?? 0.5)),
+            tags: result.tags ?? [],
+            language: result.language ?? "en",
+        };
+    }
+    catch (err) {
+        logWarn(`Source [${String(sourceIndex + 1)}/${String(totalSources)}] summarization failed, using degraded fallback`, {
+            node: "summarizer",
+            url: searchResult.url,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        // Degraded fallback: use the snippet as-is with zero relevance
+        return {
+            url: searchResult.url,
+            title: searchResult.title,
+            keyTakeaways: searchResult.snippet,
+            relevance: 0,
+            tags: [],
+            language: "en",
+        };
+    }
+}
+/**
+ * Summarizes search results by making ONE focused LLM call per source.
+ *
+ * Each source gets full page content extracted (when available, via streaming
+ * with byte-limit protection) or falls back to SearXNG snippets. Content is
+ * truncated to {@link MAX_CHARS_PER_SOURCE} chars per source.
+ *
+ * Individual source failures are isolated — a failed LLM call for one source
+ * does not affect the others. Failed sources fall back to snippet-based
+ * degraded entries with `relevance: 0`.
+ */
+export async function summarizeSearchResults(subject, searchResults, chatModel) {
+    logInfo("Summarizing results (per-source sequential)", {
+        node: "summarizer",
+        researchId: subject,
+        sourceCount: searchResults.length,
+    });
+    if (searchResults.length === 0) {
+        logWarn("No search results to summarize", {
+            node: "summarizer",
+            researchId: subject,
+        });
+        throw new Error("No search results to summarize");
+    }
+    // Extract full page content for all sources (with snippet fallback)
+    const extractedContents = await batchExtractContent(searchResults.map((sr) => ({ url: sr.url, snippet: sr.snippet })));
+    // Build extraction breakdown for debugging
+    const extractionBreakdown = extractedContents.map((c, i) => ({
+        url: searchResults[i]?.url ?? "",
+        method: c.extractionMethod,
+        extractedLength: c.extractedLength,
+    }));
+    // Process each source sequentially with its own focused LLM call
+    const sourceSummaries = [];
+    for (let i = 0; i < searchResults.length; i++) {
+        const sr = searchResults[i];
+        const content = extractedContents[i];
+        const summary = await summarizeSingleSource(subject, sr, content.text, content.wasExtracted, i, searchResults.length, chatModel);
+        sourceSummaries.push(summary);
+    }
+    const successCount = sourceSummaries.filter((s) => s.relevance > 0).length;
+    logInfo("Per-source summarization complete", {
+        node: "summarizer",
+        researchId: subject,
+        successCount,
+        degradedCount: sourceSummaries.length - successCount,
+        totalSources: searchResults.length,
+    });
+    return buildSummarizationResult(sourceSummaries, extractionBreakdown);
+}
+/**
+ * Computes aggregate confidence, tags, and language from per-source summaries.
+ */
+function buildSummarizationResult(sourceSummaries, extractionBreakdown = []) {
+    // Weighted confidence: only relevant sources count, weighted by relevance.
+    // NaN >= 0.3 is false, so NaN-relevance sources are excluded by the filter.
+    // The final Number.isFinite guard catches any remaining arithmetic edge cases.
+    const relevantSources = sourceSummaries.filter((s) => Number.isFinite(s.relevance) && s.relevance >= 0.3);
+    const rawConfidence = relevantSources.length > 0
+        ? Math.min(1, Math.max(0.1, relevantSources.reduce((sum, s) => sum + s.relevance, 0) / relevantSources.length))
+        : 0.1;
+    const overallConfidence = Number.isFinite(rawConfidence) ? rawConfidence : 0.1;
+    const allTags = normalizeTags(sourceSummaries.flatMap((s) => s.tags));
+    // Majority-vote language
+    const langCounts = new Map();
+    for (const s of sourceSummaries) {
+        langCounts.set(s.language, (langCounts.get(s.language) ?? 0) + 1);
+    }
+    const language = [...langCounts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "en";
+    return {
+        sourceSummaries,
+        overallConfidence: Math.round(overallConfidence * 100) / 100,
+        tags: allTags,
+        language,
+        extractionBreakdown,
+    };
+}
+//# sourceMappingURL=summarizer.js.map

package/dist/app/summarization/summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.js","sourceRoot":"","sources":["../../../src/app/summarization/summarizer.ts"],"names":[],"mappings":"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"}

package/dist/app/summarization/synthesisSchema.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod/v4";
+/**
+ * Schema for structured LLM output when synthesizing all per-source
+ * takeaways into a unified research summary.
+ *
+ * Used with `chatModel.withStructuredOutput(SynthesisOutputSchema)`.
+ * This is a single LLM call that receives all relevant takeaways
+ * and produces a comprehensive, theme-organized research report.
+ */
+export declare const SynthesisOutputSchema: z.ZodObject<{
+    synthesizedSummary: z.ZodString;
+    keyFindings: z.ZodArray<z.ZodString>;
+    limitations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type SynthesisOutput = z.infer<typeof SynthesisOutputSchema>;
+//# sourceMappingURL=synthesisSchema.d.ts.map

package/dist/app/summarization/synthesisSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesisSchema.d.ts","sourceRoot":"","sources":["../../../src/app/summarization/synthesisSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;iBAmChC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/app/summarization/synthesisSchema.js

@@ -0,0 +1,43 @@
+import { z } from "zod/v4";
+/**
+ * Schema for structured LLM output when synthesizing all per-source
+ * takeaways into a unified research summary.
+ *
+ * Used with `chatModel.withStructuredOutput(SynthesisOutputSchema)`.
+ * This is a single LLM call that receives all relevant takeaways
+ * and produces a comprehensive, theme-organized research report.
+ */
+export const SynthesisOutputSchema = z.object({
+    synthesizedSummary: z.string().meta({
+        description: "A comprehensive research summary organized by themes (NOT by source). " +
+            "Write 5-10 paragraphs covering: key concepts, practical techniques, " +
+            "tools/frameworks mentioned, best practices, trade-offs, and implementation details. " +
+            "Include specific facts, numbers, version references, code patterns, and actionable advice. " +
+            "Go deep — write flowing prose.",
+        examples: [
+            "State management in LangGraph centers on the StateGraph API, introduced in v0.2 as a replacement for the legacy MessageGraph. " +
+                "Persistence is handled through a pluggable checkpointer interface with MemorySaver for development and PostgresSaver for production.",
+        ],
+    }),
+    keyFindings: z
+        .array(z.string())
+        .max(15)
+        .meta({
+        description: "5-15 crisp, actionable key findings distilled from the research. " +
+            "Each finding should be a single sentence with specific details (names, versions, numbers). " +
+            "Cover all major insights — do not artificially limit the count.",
+        examples: [
+            "TypeScript strict mode catches 15-20% more bugs at compile time",
+            "Use path aliases in tsconfig.json to avoid deeply nested relative imports",
+        ],
+    }),
+    limitations: z
+        .array(z.string())
+        .default([])
+        .meta({
+        description: "Known gaps, caveats, or limitations in the research. " +
+            "E.g. 'Most sources focus on Node.js backend; frontend patterns are underrepresented.' " +
+            "Leave empty if no significant limitations.",
+    }),
+});
+//# sourceMappingURL=synthesisSchema.js.map

package/dist/app/summarization/synthesisSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesisSchema.js","sourceRoot":"","sources":["../../../src/app/summarization/synthesisSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;QAClC,WAAW,EACT,wEAAwE;YACxE,sEAAsE;YACtE,sFAAsF;YACtF,6FAA6F;YAC7F,gCAAgC;QAClC,QAAQ,EAAE;YACR,gIAAgI;gBAC9H,sIAAsI;SACzI;KACF,CAAC;IACF,WAAW,EAAE,CAAC;SACX,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,GAAG,CAAC,EAAE,CAAC;SACP,IAAI,CAAC;QACJ,WAAW,EACT,mEAAmE;YACnE,6FAA6F;YAC7F,iEAAiE;QACnE,QAAQ,EAAE;YACR,iEAAiE;YACjE,2EAA2E;SAC5E;KACF,CAAC;IACJ,WAAW,EAAE,CAAC;SACX,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,OAAO,CAAC,EAAE,CAAC;SACX,IAAI,CAAC;QACJ,WAAW,EACT,uDAAuD;YACvD,wFAAwF;YACxF,4CAA4C;KAC/C,CAAC;CACL,CAAC,CAAC"}

package/dist/app/summarization/synthesizer.d.ts

@@ -0,0 +1,21 @@
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { SourceSummary } from "./summarizer.js";
+/** Result of synthesizing per-source takeaways into a unified report. */
+export interface SynthesisResult {
+    /** The synthesized multi-paragraph research summary. */
+    synthesizedSummary: string;
+    /** 3-7 crisp, actionable key findings. */
+    keyFindings: string[];
+    /** Known gaps or limitations in the research. */
+    limitations: string[];
+}
+/**
+ * Synthesizes per-source takeaways into a unified, theme-organized
+ * research report using a single LLM call.
+ *
+ * Only sources with relevance ≥ 0.3 are included.
+ * This produces a qualitatively superior summary compared to
+ * simple concatenation of per-source takeaways.
+ */
+export declare function synthesizeSummary(subject: string, sourceSummaries: SourceSummary[], chatModel: BaseChatModel): Promise<SynthesisResult>;
+//# sourceMappingURL=synthesizer.d.ts.map

package/dist/app/summarization/synthesizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesizer.d.ts","sourceRoot":"","sources":["../../../src/app/summarization/synthesizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAEjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMrD,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iDAAiD;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAmBD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,aAAa,EAAE,EAChC,SAAS,EAAE,aAAa,GACvB,OAAO,CAAC,eAAe,CAAC,CAwE1B"}

package/dist/app/summarization/synthesizer.js

@@ -0,0 +1,86 @@
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { SynthesisOutputSchema } from "./synthesisSchema.js";
+import { logInfo, logWarn, logError, ErrorCodes } from "../../infra/observability/tracing.js";
+// ── Prompt ────────────────────────────────────────────────────────
+const SYSTEM_PROMPT = `You are a senior research analyst producing final research reports for developers and technical decision-makers.
+
+Before writing, consider: what themes emerge across sources, and where do sources agree or contradict?
+
+Guidelines:
+1. Organize by theme, grouping related insights from different sources together.
+2. Write flowing prose with exhaustive detail — specific facts, numbers, code patterns, and actionable advice.
+3. Highlight consensus and contradictions across sources.
+4. Synthesize into a unified narrative — the reader should not be aware of individual source boundaries.`;
+/** Minimum relevance threshold for including a source in synthesis. */
+const MIN_RELEVANCE_FOR_SYNTHESIS = 0.3;
+// ── Core logic ──────────────────────────────────────────────────────
+/**
+ * Synthesizes per-source takeaways into a unified, theme-organized
+ * research report using a single LLM call.
+ *
+ * Only sources with relevance ≥ 0.3 are included.
+ * This produces a qualitatively superior summary compared to
+ * simple concatenation of per-source takeaways.
+ */
+export async function synthesizeSummary(subject, sourceSummaries, chatModel) {
+    const relevantSources = sourceSummaries.filter((s) => s.relevance >= MIN_RELEVANCE_FOR_SYNTHESIS);
+    if (relevantSources.length === 0) {
+        logWarn("No relevant sources for synthesis", {
+            node: "synthesizer",
+            researchId: subject,
+            totalSources: sourceSummaries.length,
+        });
+        return {
+            synthesizedSummary: "No sufficiently relevant sources were found to produce a research synthesis.",
+            keyFindings: [],
+            limitations: ["All sources had low relevance to the research subject."],
+        };
+    }
+    logInfo("Synthesizing research summary", {
+        node: "synthesizer",
+        researchId: subject,
+        relevantSources: relevantSources.length,
+        totalSources: sourceSummaries.length,
+    });
+    const takeawaysBlock = relevantSources
+        .map((s, i) => `[Source ${String(i + 1)}] (relevance: ${String(s.relevance)}, tags: ${s.tags.join(", ")})\n${s.keyTakeaways}`)
+        .join("\n\n");
+    const humanMsg = `Research subject:\n<subject>\n${subject}\n</subject>\n\n` +
+        `Total sources analyzed: ${String(sourceSummaries.length)} ` +
+        `(${String(relevantSources.length)} relevant)\n\n` +
+        `<source_takeaways>\n${takeawaysBlock}\n</source_takeaways>\n\n` +
+        `Synthesize these takeaways into a comprehensive research report.`;
+    try {
+        const structuredModel = chatModel.withStructuredOutput(SynthesisOutputSchema, {
+            method: "jsonSchema",
+            name: "research_synthesis",
+        });
+        const result = await structuredModel.invoke([
+            new SystemMessage(SYSTEM_PROMPT),
+            new HumanMessage(humanMsg),
+        ]);
+        logInfo("Synthesis complete", {
+            node: "synthesizer",
+            researchId: subject,
+            summaryLength: result.synthesizedSummary.length,
+            keyFindingsCount: result.keyFindings.length,
+            limitationsCount: result.limitations?.length ?? 0,
+        });
+        return {
+            synthesizedSummary: result.synthesizedSummary.trim(),
+            keyFindings: result.keyFindings.map((f) => f.trim()),
+            limitations: (result.limitations ?? []).map((l) => l.trim()),
+        };
+    }
+    catch (err) {
+        logError("Synthesis failed, returning fallback", {
+            node: "synthesizer",
+            researchId: subject,
+            errorCode: ErrorCodes.SUMMARIZATION_FAILED,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        // Synthesis failure is non-fatal — caller falls back to composite summary
+        throw err;
+    }
+}
+//# sourceMappingURL=synthesizer.js.map

package/dist/app/summarization/synthesizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesizer.js","sourceRoot":"","sources":["../../../src/app/summarization/synthesizer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAc9F,qEAAqE;AAErE,MAAM,aAAa,GAAG;;;;;;;;yGAQmF,CAAC;AAE1G,uEAAuE;AACvE,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAExC,uEAAuE;AAEvE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe,EACf,eAAgC,EAChC,SAAwB;IAExB,MAAM,eAAe,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,2BAA2B,CAAC,CAAC;IAElG,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,mCAAmC,EAAE;YAC3C,IAAI,EAAE,aAAa;YACnB,UAAU,EAAE,OAAO;YACnB,YAAY,EAAE,eAAe,CAAC,MAAM;SACrC,CAAC,CAAC;QACH,OAAO;YACL,kBAAkB,EAChB,8EAA8E;YAChF,WAAW,EAAE,EAAE;YACf,WAAW,EAAE,CAAC,wDAAwD,CAAC;SACxE,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,+BAA+B,EAAE;QACvC,IAAI,EAAE,aAAa;QACnB,UAAU,EAAE,OAAO;QACnB,eAAe,EAAE,eAAe,CAAC,MAAM;QACvC,YAAY,EAAE,eAAe,CAAC,MAAM;KACrC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,eAAe;SACnC,GAAG,CACF,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,WAAW,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,iBAAiB,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE,CACjH;SACA,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,MAAM,QAAQ,GACZ,iCAAiC,OAAO,kBAAkB;QAC1D,2BAA2B,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG;QAC5D,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,gBAAgB;QAClD,uBAAuB,cAAc,2BAA2B;QAChE,kEAAkE,CAAC;IAErE,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,SAAS,CAAC,oBAAoB,CAAC,qBAAqB,EAAE;YAC5E,MAAM,EAAE,YAAY;YACpB,IAAI,EAAE,oBAAoB;SAC3B,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC;YAC1C,IAAI,aAAa,CAAC,aAAa,CAAC;YAChC,IAAI,YAAY,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,OAAO,CAAC,oBAAoB,EAAE;YAC5B,IAAI,EAAE,aAAa;YACnB,UAAU,EAAE,OAAO;YACnB,aAAa,EAAE,MAAM,CAAC,kBAAkB,CAAC,MAAM;YAC/C,gBAAgB,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM;YAC3C,gBAAgB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;SAClD,CAAC,CAAC;QAEH,OAAO;YACL,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE;YACpD,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACpD,WAAW,EAAE,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SAC7D,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,QAAQ,CAAC,sCAAsC,EAAE;YAC/C,IAAI,EAAE,aAAa;YACnB,UAAU,EAAE,OAAO;YACnB,SAAS,EAAE,UAAU,CAAC,oBAAoB;YAC1C,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC,CAAC;QACH,0EAA0E;QAC1E,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/config/env.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod/v4";
+declare const envSchema: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        test: "test";
+        production: "production";
+    }>>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+        debug: "debug";
+    }>>;
+    QDRANT_URL: z.ZodDefault<z.ZodURL>;
+    QDRANT_API_KEY: z.ZodOptional<z.ZodString>;
+    QDRANT_TIMEOUT_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    OLLAMA_HOST: z.ZodDefault<z.ZodURL>;
+    OLLAMA_EMBEDDING_MODEL: z.ZodDefault<z.ZodString>;
+    OLLAMA_CHAT_MODEL: z.ZodDefault<z.ZodString>;
+    RMS_OLLAMA_EMBEDDING_MODEL: z.ZodOptional<z.ZodString>;
+    RMS_OLLAMA_CHAT_MODEL: z.ZodOptional<z.ZodString>;
+    RMS_OLLAMA_NUM_CTX: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    SEARXNG_API_BASE: z.ZodDefault<z.ZodURL>;
+    SEARXNG_ENGINES: z.ZodOptional<z.ZodString>;
+    SEARXNG_LANGUAGE: z.ZodOptional<z.ZodString>;
+    SEARXNG_TIME_RANGE: z.ZodOptional<z.ZodString>;
+    SEARXNG_URL_BLOCKLIST: z.ZodOptional<z.ZodString>;
+    RMS_FRESHNESS_DAYS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    LANGCHAIN_TRACING_V2: z.ZodDefault<z.ZodCodec<z.ZodString, z.ZodBoolean>>;
+    LANGCHAIN_API_KEY: z.ZodOptional<z.ZodString>;
+    RMS_MCP_AUTH_TOKEN: z.ZodOptional<z.ZodString>;
+    RMS_USER_AGENT: z.ZodOptional<z.ZodString>;
+    RMS_CHECKPOINTER: z.ZodDefault<z.ZodEnum<{
+        memory: "memory";
+        sqlite: "sqlite";
+    }>>;
+    RMS_CHECKPOINT_DB: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type Env = z.infer<typeof envSchema>;
+/** Reset cached env (for tests only) */
+export declare function resetEnv(): void;
+/**
+ * Loads and validates environment variables (cached after first call).
+ * @note In tests, call `resetEnv()` before each test to avoid stale cached values
+ *       from bleeding into subsequent test cases.
+ */
+export declare function loadEnv(): Env;
+export {};
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,QAAA,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCb,CAAC;AAEH,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAI5C,wCAAwC;AACxC,wBAAgB,QAAQ,IAAI,IAAI,CAE/B;AAED;;;;GAIG;AACH,wBAAgB,OAAO,IAAI,GAAG,CAW7B"}

package/dist/config/env.js

@@ -0,0 +1,54 @@
+import { z } from "zod/v4";
+const envSchema = z.object({
+    NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+    LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+    QDRANT_URL: z.url().default("http://localhost:6333"),
+    QDRANT_API_KEY: z.string().optional(),
+    QDRANT_TIMEOUT_MS: z.coerce.number().int().positive().default(10000),
+    OLLAMA_HOST: z.url().default("http://localhost:11434"),
+    OLLAMA_EMBEDDING_MODEL: z.string().default("bge-m3"),
+    OLLAMA_CHAT_MODEL: z.string().default("qwen3:8b"),
+    RMS_OLLAMA_EMBEDDING_MODEL: z.string().optional(),
+    RMS_OLLAMA_CHAT_MODEL: z.string().optional(),
+    RMS_OLLAMA_NUM_CTX: z.coerce.number().int().positive().default(16384),
+    SEARXNG_API_BASE: z.url().default("http://localhost:8080"),
+    SEARXNG_ENGINES: z.string().optional(),
+    SEARXNG_LANGUAGE: z.string().optional(),
+    SEARXNG_TIME_RANGE: z.string().optional(),
+    /** Comma-separated list of additional domains to block from search results. */
+    SEARXNG_URL_BLOCKLIST: z.string().optional(),
+    RMS_FRESHNESS_DAYS: z.coerce.number().int().positive().default(7),
+    /** Zod v4 codec: coerces env string "true"/"false" → boolean. */
+    LANGCHAIN_TRACING_V2: z.stringbool().default(false),
+    LANGCHAIN_API_KEY: z.string().optional(),
+    RMS_MCP_AUTH_TOKEN: z.string().optional(),
+    RMS_USER_AGENT: z.string().optional(),
+    /** Checkpointer backend: "memory" (default, dev only) or "sqlite" (durable, for HITL). */
+    RMS_CHECKPOINTER: z.enum(["memory", "sqlite"]).default("memory"),
+    /** SQLite file path for the checkpoint database (when RMS_CHECKPOINTER=sqlite). */
+    RMS_CHECKPOINT_DB: z.string().default("rms_checkpoints.db"),
+});
+let _env = null;
+/** Reset cached env (for tests only) */
+export function resetEnv() {
+    _env = null;
+}
+/**
+ * Loads and validates environment variables (cached after first call).
+ * @note In tests, call `resetEnv()` before each test to avoid stale cached values
+ *       from bleeding into subsequent test cases.
+ */
+export function loadEnv() {
+    if (_env)
+        return _env;
+    const parsed = envSchema.safeParse(process.env);
+    if (!parsed.success) {
+        const msg = parsed.error.issues
+            .map((e) => `${e.path.map(String).join(".")}: ${e.message}`)
+            .join("; ");
+        throw new Error(`Invalid environment configuration: ${msg}`);
+    }
+    _env = parsed.data;
+    return _env;
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"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"}

package/dist/domain/contracts.d.ts

@@ -0,0 +1,59 @@
+import { z } from "zod/v4";
+/** Research entry status in the lifecycle */
+export declare const ResearchStatusSchema: z.ZodEnum<{
+    active: "active";
+    stale: "stale";
+    refreshing: "refreshing";
+    archived: "archived";
+    low_confidence: "low_confidence";
+}>;
+export type ResearchStatus = z.infer<typeof ResearchStatusSchema>;
+/** Response contract version stamped on all RMS tool outputs. */
+export declare const RESPONSE_CONTRACT_VERSION = "1.0";
+/** Per-source summary stored in a Research entry. */
+export declare const SourceSummarySchema: z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodString;
+    keyTakeaways: z.ZodString;
+    relevance: z.ZodDefault<z.ZodNumber>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    language: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type SourceSummaryEntry = z.infer<typeof SourceSummarySchema>;
+/** Research entry — the core domain object for RMS. */
+export declare const ResearchSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    subject: z.ZodString;
+    summary: z.ZodString;
+    sourceSummaries: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        title: z.ZodString;
+        keyTakeaways: z.ZodString;
+        relevance: z.ZodDefault<z.ZodNumber>;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        language: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>>;
+    sourceUrls: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    searchQueries: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    createdAt: z.ZodOptional<z.ZodISODateTime>;
+    updatedAt: z.ZodOptional<z.ZodISODateTime>;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    status: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        stale: "stale";
+        refreshing: "refreshing";
+        archived: "archived";
+        low_confidence: "low_confidence";
+    }>>;
+    confidenceScore: z.ZodDefault<z.ZodNumber>;
+    sourceCount: z.ZodDefault<z.ZodNumber>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    language: z.ZodDefault<z.ZodString>;
+    rawResultCount: z.ZodDefault<z.ZodNumber>;
+    keyFindings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limitations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type Research = z.infer<typeof ResearchSchema>;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/domain/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/domain/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,6CAA6C;AAC7C,eAAO,MAAM,oBAAoB;;;;;;EAM/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,QAAQ,CAAC;AAE/C,qDAAqD;AACrD,eAAO,MAAM,mBAAmB;;;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAErE,uDAAuD;AACvD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/domain/contracts.js

@@ -0,0 +1,52 @@
+import { z } from "zod/v4";
+/** Research entry status in the lifecycle */
+export const ResearchStatusSchema = z.enum([
+    "active",
+    "stale",
+    "refreshing",
+    "archived",
+    "low_confidence",
+]);
+/** Response contract version stamped on all RMS tool outputs. */
+export const RESPONSE_CONTRACT_VERSION = "1.0";
+/** Per-source summary stored in a Research entry. */
+export const SourceSummarySchema = z.object({
+    url: z.string(),
+    title: z.string(),
+    keyTakeaways: z.string(),
+    relevance: z.number().min(0).max(1).default(0.5),
+    tags: z.array(z.string()).default([]),
+    language: z.string().default("en"),
+});
+/** Research entry — the core domain object for RMS. */
+export const ResearchSchema = z.object({
+    id: z.uuid(),
+    subject: z.string().min(1),
+    summary: z.string().min(1),
+    sourceSummaries: z.array(SourceSummarySchema).default([]),
+    sourceUrls: z.array(z.string()).default([]),
+    searchQueries: z.array(z.string()).default([]),
+    /**
+     * Timestamps use ISO 8601 with timezone offset.
+     *
+     * Design note: These intentionally allow future dates:
+     * - `expiresAt` is always in the future (freshness window)
+     * - `createdAt` / `updatedAt` are system-generated, not user input
+     * - Adding `max: now()` would break deserialization under clock skew
+     *   or when reading entries created on a different host
+     */
+    createdAt: z.iso.datetime({ offset: true }).optional(),
+    updatedAt: z.iso.datetime({ offset: true }).optional(),
+    expiresAt: z.iso.datetime({ offset: true }).optional(),
+    status: ResearchStatusSchema.default("active"),
+    confidenceScore: z.number().min(0).max(1).default(0.5),
+    sourceCount: z.number().int().min(0).default(0),
+    tenantId: z.string().optional(),
+    tags: z.array(z.string()).default([]),
+    language: z.string().default("en"),
+    rawResultCount: z.number().int().min(0).default(0),
+    keyFindings: z.array(z.string()).optional(),
+    limitations: z.array(z.string()).optional(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+});
+//# sourceMappingURL=contracts.js.map

package/dist/domain/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/domain/contracts.ts"],"names":[],"mappings":"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"}