@farukada/langchain-ts-rms 0.1.0

package/dist/domain/ports.d.ts

@@ -0,0 +1,63 @@
+import type { Research, ResearchStatus } from "./contracts.js";
+/** Payload filter options for searching research entries. */
+export interface ResearchSearchFilter {
+    tenantId?: string | undefined;
+    status?: ResearchStatus[] | undefined;
+    tags?: string[] | undefined;
+}
+/** Paging and filter options for listing research entries. */
+export interface ResearchListOptions {
+    tenantId?: string | undefined;
+    status?: ResearchStatus[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    /** Opaque cursor from a previous list() call. Takes precedence over offset. */
+    cursor?: string | undefined;
+}
+/** Deterministic page payload with total count metadata. */
+export interface ResearchListResult {
+    items: Research[];
+    total: number;
+    limit: number;
+    offset: number;
+    /** Opaque cursor for fetching the next page. Undefined if no more pages. */
+    nextCursor?: string | undefined;
+}
+/**
+ * Storage-agnostic repository contract for research persistence.
+ *
+ * Implement this interface to plug in any vector store backend
+ * (Qdrant, Pinecone, pgvector, in-memory, etc.).
+ */
+export interface IResearchRepository {
+    /** Upsert a research entry into the store. */
+    upsert(research: Research): Promise<void>;
+    /** Semantic search with optional payload filters. */
+    search(query: string, opts?: {
+        k?: number;
+        filter?: ResearchSearchFilter;
+    }): Promise<Array<{
+        research: Research;
+        score: number;
+    }>>;
+    /** Retrieve a research entry by ID (exact match). */
+    getById(researchId: string): Promise<Research | null>;
+    /** List research entries with server-side pagination and optional filters. */
+    list(options?: ResearchListOptions): Promise<ResearchListResult>;
+    /** Delete research entries by IDs. */
+    deleteByIds(ids: string[]): Promise<void>;
+    /** Find research entries by subject using semantic similarity. */
+    findBySubject(subject: string, opts?: {
+        tenantId?: string | undefined;
+        k?: number | undefined;
+    }): Promise<Array<{
+        research: Research;
+        score: number;
+    }>>;
+    /** Find stale (expired) research entries. */
+    findStale(now: Date, opts?: {
+        tenantId?: string | undefined;
+        limit?: number | undefined;
+    }): Promise<Research[]>;
+}
+//# sourceMappingURL=ports.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/domain/ports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE/D,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,cAAc,EAAE,GAAG,SAAS,CAAC;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAC7B;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,cAAc,EAAE,GAAG,SAAS,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C,qDAAqD;IACrD,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,oBAAoB,CAAA;KAAE,GACnD,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAEzD,qDAAqD;IACrD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAEtD,8EAA8E;IAC9E,IAAI,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAEjE,sCAAsC;IACtC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C,kEAAkE;IAClE,aAAa,CACX,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAC/D,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAEzD,6CAA6C;IAC7C,SAAS,CACP,GAAG,EAAE,IAAI,EACT,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GACnE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACxB"}

package/dist/domain/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/domain/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/domain/ports.ts"],"names":[],"mappings":""}

package/dist/domain/researchUtils.d.ts

@@ -0,0 +1,51 @@
+import type { Research, SourceSummaryEntry } from "./contracts.js";
+/**
+ * Checks whether a research entry is still fresh (not expired).
+ * A research entry is fresh if its `expiresAt` timestamp is in the future.
+ */
+export declare function isResearchFresh(research: Research, now?: Date): boolean;
+/**
+ * Calculates the expiration timestamp by adding `freshnessDays` to the given date.
+ */
+export declare function calculateExpiresAt(updatedAt: string, freshnessDays: number): string;
+/**
+ * Builds a human-readable composite summary from per-source summaries.
+ * Filters out low-relevance sources (< 0.3) so the summary stays useful.
+ */
+export declare function buildCompositeSummary(sources: SourceSummaryEntry[]): string;
+/**
+ * Constructs a new Research domain object with sensible defaults.
+ *
+ * When `sourceSummaries` is provided, the composite `summary` is
+ * auto-generated from per-source takeaways (unless an explicit
+ * `summary` override is also given).
+ */
+export declare function buildResearch(input: {
+    subject: string;
+    sourceSummaries?: SourceSummaryEntry[] | undefined;
+    summary?: string | undefined;
+    sourceUrls?: string[] | undefined;
+    searchQueries?: string[] | undefined;
+    confidenceScore?: number | undefined;
+    tags?: string[] | undefined;
+    language?: string | undefined;
+    rawResultCount?: number | undefined;
+    keyFindings?: string[] | undefined;
+    limitations?: string[] | undefined;
+    tenantId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    freshnessDays?: number | undefined;
+}): Research;
+/**
+ * Merges incoming metadata with existing metadata (shallow merge).
+ */
+export declare function mergeResearchMetadata(existing: Record<string, unknown>, incoming: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Returns the age of a research entry in milliseconds.
+ */
+export declare function getResearchAge(research: Research, now?: Date): number;
+/**
+ * Returns the age of a research entry in days.
+ */
+export declare function getResearchAgeDays(research: Research, now?: Date): number;
+//# sourceMappingURL=researchUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"researchUtils.d.ts","sourceRoot":"","sources":["../../src/domain/researchUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEnE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAIvE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAInF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAK3E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,kBAAkB,EAAE,GAAG,SAAS,CAAC;IACnD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACrC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,GAAG,QAAQ,CA0BX;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAIrE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAEzE"}

package/dist/domain/researchUtils.js

@@ -0,0 +1,85 @@
+/**
+ * Checks whether a research entry is still fresh (not expired).
+ * A research entry is fresh if its `expiresAt` timestamp is in the future.
+ */
+export function isResearchFresh(research, now) {
+    if (!research.expiresAt)
+        return false;
+    const currentTime = now ?? new Date();
+    return new Date(research.expiresAt).getTime() > currentTime.getTime();
+}
+/**
+ * Calculates the expiration timestamp by adding `freshnessDays` to the given date.
+ */
+export function calculateExpiresAt(updatedAt, freshnessDays) {
+    const date = new Date(updatedAt);
+    date.setDate(date.getDate() + freshnessDays);
+    return date.toISOString();
+}
+/**
+ * Builds a human-readable composite summary from per-source summaries.
+ * Filters out low-relevance sources (< 0.3) so the summary stays useful.
+ */
+export function buildCompositeSummary(sources) {
+    if (sources.length === 0)
+        return "No sources available.";
+    const relevant = sources.filter((s) => s.relevance >= 0.3);
+    if (relevant.length === 0)
+        return "No sufficiently relevant sources found.";
+    return relevant.map((s) => `**${s.title}**\n${s.keyTakeaways}\n[Source: ${s.url}]`).join("\n\n");
+}
+/**
+ * Constructs a new Research domain object with sensible defaults.
+ *
+ * When `sourceSummaries` is provided, the composite `summary` is
+ * auto-generated from per-source takeaways (unless an explicit
+ * `summary` override is also given).
+ */
+export function buildResearch(input) {
+    const now = new Date().toISOString();
+    const freshnessDays = input.freshnessDays ?? 7;
+    const sourceSummaries = input.sourceSummaries ?? [];
+    const summary = input.summary ?? buildCompositeSummary(sourceSummaries);
+    return {
+        id: crypto.randomUUID(),
+        subject: input.subject,
+        summary,
+        sourceSummaries,
+        sourceUrls: input.sourceUrls ?? [],
+        searchQueries: input.searchQueries ?? [],
+        createdAt: now,
+        updatedAt: now,
+        expiresAt: calculateExpiresAt(now, freshnessDays),
+        status: "active",
+        confidenceScore: input.confidenceScore ?? 0.5,
+        sourceCount: input.sourceUrls?.length ?? 0,
+        tenantId: input.tenantId,
+        tags: input.tags ?? [],
+        language: input.language ?? "en",
+        rawResultCount: input.rawResultCount ?? 0,
+        keyFindings: input.keyFindings,
+        limitations: input.limitations,
+        metadata: input.metadata ?? {},
+    };
+}
+/**
+ * Merges incoming metadata with existing metadata (shallow merge).
+ */
+export function mergeResearchMetadata(existing, incoming) {
+    return { ...existing, ...incoming };
+}
+/**
+ * Returns the age of a research entry in milliseconds.
+ */
+export function getResearchAge(research, now) {
+    const currentTime = now ?? new Date();
+    const updatedAt = research.updatedAt ? new Date(research.updatedAt) : new Date(0);
+    return currentTime.getTime() - updatedAt.getTime();
+}
+/**
+ * Returns the age of a research entry in days.
+ */
+export function getResearchAgeDays(research, now) {
+    return getResearchAge(research, now) / (1000 * 60 * 60 * 24);
+}
+//# sourceMappingURL=researchUtils.js.map

package/dist/domain/researchUtils.js.map

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

package/dist/infra/chat/chatModelProvider.d.ts

@@ -0,0 +1,4 @@
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+/** Creates an Ollama chat model from environment configuration. */
+export declare function createChatModelProvider(): BaseChatModel;
+//# sourceMappingURL=chatModelProvider.d.ts.map

package/dist/infra/chat/chatModelProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatModelProvider.d.ts","sourceRoot":"","sources":["../../../src/infra/chat/chatModelProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAIjF,mEAAmE;AACnE,wBAAgB,uBAAuB,IAAI,aAAa,CAQvD"}

package/dist/infra/chat/chatModelProvider.js

@@ -0,0 +1,13 @@
+import { ChatOllama } from "@langchain/ollama";
+import { loadEnv } from "../../config/env.js";
+/** Creates an Ollama chat model from environment configuration. */
+export function createChatModelProvider() {
+    const env = loadEnv();
+    return new ChatOllama({
+        baseUrl: env.OLLAMA_HOST,
+        model: env.RMS_OLLAMA_CHAT_MODEL ?? env.OLLAMA_CHAT_MODEL,
+        temperature: 0,
+        numCtx: env.RMS_OLLAMA_NUM_CTX,
+    });
+}
+//# sourceMappingURL=chatModelProvider.js.map

package/dist/infra/chat/chatModelProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatModelProvider.js","sourceRoot":"","sources":["../../../src/infra/chat/chatModelProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE9C,mEAAmE;AACnE,MAAM,UAAU,uBAAuB;IACrC,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,OAAO,IAAI,UAAU,CAAC;QACpB,OAAO,EAAE,GAAG,CAAC,WAAW;QACxB,KAAK,EAAE,GAAG,CAAC,qBAAqB,IAAI,GAAG,CAAC,iBAAiB;QACzD,WAAW,EAAE,CAAC;QACd,MAAM,EAAE,GAAG,CAAC,kBAAkB;KAC/B,CAAC,CAAC;AACL,CAAC"}

package/dist/infra/checkpoint/checkpointerFactory.d.ts

@@ -0,0 +1,38 @@
+import { type BaseCheckpointSaver } from "@langchain/langgraph";
+/**
+ * Configuration for the checkpointer factory.
+ * All fields are optional — environment variables are used as defaults.
+ */
+export interface CheckpointerOptions {
+    /**
+     * Backend to use: `"memory"` or `"sqlite"`.
+     * Falls back to `RMS_CHECKPOINTER` env var, then `"memory"`.
+     */
+    backend?: "memory" | "sqlite" | undefined;
+    /**
+     * SQLite connection string (file path).
+     * Falls back to `RMS_CHECKPOINT_DB` env var, then `"rms_checkpoints.db"`.
+     */
+    sqliteConnectionString?: string | undefined;
+}
+/**
+ * Creates a checkpointer based on configuration.
+ *
+ * - `"memory"` → in-process {@link MemorySaver} (development/testing only)
+ * - `"sqlite"` → durable SQLite-backed saver via `@langchain/langgraph-checkpoint-sqlite`
+ *
+ * The SQLite backend is dynamically imported so the package is only required
+ * when actually selected. This avoids adding a hard dependency for users who
+ * don't need HITL persistence.
+ *
+ * @example
+ * ```ts
+ * // Uses env vars (RMS_CHECKPOINTER, RMS_CHECKPOINT_DB)
+ * const checkpointer = await createCheckpointer();
+ *
+ * // Explicit configuration
+ * const checkpointer = await createCheckpointer({ backend: "sqlite", sqliteConnectionString: "./data/rms.db" });
+ * ```
+ */
+export declare function createCheckpointer(opts?: CheckpointerOptions): Promise<BaseCheckpointSaver>;
+//# sourceMappingURL=checkpointerFactory.d.ts.map

package/dist/infra/checkpoint/checkpointerFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointerFactory.d.ts","sourceRoot":"","sources":["../../../src/infra/checkpoint/checkpointerFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAI7E;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1C;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqCjG"}

package/dist/infra/checkpoint/checkpointerFactory.js

@@ -0,0 +1,54 @@
+import { MemorySaver } from "@langchain/langgraph";
+import { loadEnv } from "../../config/env.js";
+import { logInfo, logWarn } from "../observability/tracing.js";
+/**
+ * Creates a checkpointer based on configuration.
+ *
+ * - `"memory"` → in-process {@link MemorySaver} (development/testing only)
+ * - `"sqlite"` → durable SQLite-backed saver via `@langchain/langgraph-checkpoint-sqlite`
+ *
+ * The SQLite backend is dynamically imported so the package is only required
+ * when actually selected. This avoids adding a hard dependency for users who
+ * don't need HITL persistence.
+ *
+ * @example
+ * ```ts
+ * // Uses env vars (RMS_CHECKPOINTER, RMS_CHECKPOINT_DB)
+ * const checkpointer = await createCheckpointer();
+ *
+ * // Explicit configuration
+ * const checkpointer = await createCheckpointer({ backend: "sqlite", sqliteConnectionString: "./data/rms.db" });
+ * ```
+ */
+export async function createCheckpointer(opts) {
+    const env = loadEnv();
+    const backend = opts?.backend ?? env.RMS_CHECKPOINTER;
+    if (backend === "sqlite") {
+        const connString = opts?.sqliteConnectionString ?? env.RMS_CHECKPOINT_DB;
+        logInfo("Creating SQLite checkpointer", { connectionString: connString });
+        try {
+            // Dynamic import — @langchain/langgraph-checkpoint-sqlite is an optional peer dependency.
+            // Variable indirection prevents TS from resolving the module at compile time.
+            const pkgName = "@langchain/langgraph-checkpoint-sqlite";
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const mod = await import(pkgName);
+            const SqliteSaver = mod["SqliteSaver"];
+            if (!SqliteSaver) {
+                throw new Error("SqliteSaver not found in @langchain/langgraph-checkpoint-sqlite");
+            }
+            return SqliteSaver.fromConnString(connString);
+        }
+        catch (err) {
+            const msg = `Failed to create SQLite checkpointer: ${err instanceof Error ? err.message : String(err)}\n` +
+                "Install the package: npm install @langchain/langgraph-checkpoint-sqlite";
+            throw new Error(msg, { cause: err });
+        }
+    }
+    logInfo("Creating in-memory checkpointer (MemorySaver)", { backend });
+    if (process.env["NODE_ENV"] === "production") {
+        logWarn("MemorySaver is not suitable for production. " +
+            "Set RMS_CHECKPOINTER=sqlite or inject a durable checkpointer via deps.checkpointer.");
+    }
+    return new MemorySaver();
+}
+//# sourceMappingURL=checkpointerFactory.js.map

package/dist/infra/checkpoint/checkpointerFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointerFactory.js","sourceRoot":"","sources":["../../../src/infra/checkpoint/checkpointerFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA4B,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAmB/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAA0B;IACjE,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,GAAG,CAAC,gBAAgB,CAAC;IAEtD,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,IAAI,EAAE,sBAAsB,IAAI,GAAG,CAAC,iBAAiB,CAAC;QACzE,OAAO,CAAC,8BAA8B,EAAE,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC,CAAC;QAE1E,IAAI,CAAC;YACH,0FAA0F;YAC1F,8EAA8E;YAC9E,MAAM,OAAO,GAAG,wCAAwC,CAAC;YACzD,mEAAmE;YACnE,MAAM,GAAG,GAA4B,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;YAC3D,MAAM,WAAW,GAAG,GAAG,CAAC,aAAa,CAExB,CAAC;YACd,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;YACrF,CAAC;YACD,OAAO,WAAW,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GACP,yCAAyC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI;gBAC7F,yEAAyE,CAAC;YAC5E,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,OAAO,CAAC,+CAA+C,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACtE,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,EAAE,CAAC;QAC7C,OAAO,CACL,8CAA8C;YAC5C,qFAAqF,CACxF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC;AAC3B,CAAC"}

package/dist/infra/content/contentExtractor.d.ts

@@ -0,0 +1,58 @@
+import { type TokenBucketLimiter } from "../rateLimit/rateLimiter.js";
+import { type CircuitBreaker } from "../rateLimit/circuitBreaker.js";
+/** Which extraction tier produced the content. */
+export type ExtractionMethod = "article-extractor" | "cheerio" | "snippet";
+/** Result of content extraction from a URL. */
+export interface ExtractedContent {
+    /** Extracted readable text (or original snippet as fallback). */
+    text: string;
+    /** Length of extracted text in characters. */
+    extractedLength: number;
+    /** True if full page content was fetched; false if fell back to snippet. */
+    wasExtracted: boolean;
+    /** Which extraction method produced this content. */
+    extractionMethod: ExtractionMethod;
+}
+export interface ContentExtractionOptions {
+    /** Max characters to extract per page (prevents blowing LLM context). */
+    maxChars?: number;
+    /** Request timeout per URL in milliseconds. */
+    timeoutMs?: number;
+    /** User-Agent header for HTTP requests. */
+    userAgent?: string;
+    /** Override the default content extraction rate limiter (for DI/testing). */
+    limiter?: TokenBucketLimiter;
+    /** Override the default content extraction circuit breaker (for DI/testing). */
+    breaker?: CircuitBreaker;
+}
+/**
+ * Extracts readable text content from an HTML page.
+ *
+ * Strips navigation, ads, scripts, and other non-content elements.
+ * Collapses whitespace and truncates to `maxChars`.
+ */
+export declare function extractTextFromHtml(html: string, maxChars: number): string;
+/**
+ * Fetches a web page and extracts readable text content.
+ *
+ * Uses a tiered extraction strategy:
+ * 1. `@extractus/article-extractor` — smart article detection with its own fetch
+ * 2. Direct fetch + Cheerio — fallback HTML parsing pipeline
+ * 3. SearXNG snippet — final fallback when both extraction methods fail
+ *
+ * Each tier only fires when the previous one didn't produce enough content.
+ */
+export declare function extractContent(url: string, fallbackSnippet: string, options?: ContentExtractionOptions): Promise<ExtractedContent>;
+/**
+ * Batch-extracts content from multiple URLs with concurrency limiting.
+ *
+ * Returns results in the same order as input URLs. Failed extractions
+ * fall back to the provided snippets.
+ */
+export declare function batchExtractContent(sources: Array<{
+    url: string;
+    snippet: string;
+}>, options?: ContentExtractionOptions & {
+    concurrency?: number;
+}): Promise<ExtractedContent[]>;
+//# sourceMappingURL=contentExtractor.d.ts.map

package/dist/infra/content/contentExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentExtractor.d.ts","sourceRoot":"","sources":["../../../src/infra/content/contentExtractor.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtF,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrF,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,GAAG,SAAS,GAAG,SAAS,CAAC;AAE3E,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;IACtB,qDAAqD;IACrD,gBAAgB,EAAE,gBAAgB,CAAC;CACpC;AAED,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,gFAAgF;IAChF,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAwBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAqB1E;AAkHD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAsG3B;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EAChD,OAAO,CAAC,EAAE,wBAAwB,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAmD7B"}