@fllf/agent-sdk 0.1.0

package/dist/rag/stores/postgres/sql.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePostgresTableNames = resolvePostgresTableNames;
+exports.quoteIdentifier = quoteIdentifier;
+exports.createJson = createJson;
+exports.createOptionalJson = createOptionalJson;
+exports.readJsonObject = readJsonObject;
+exports.readJsonArray = readJsonArray;
+exports.readJson = readJson;
+exports.toVectorLiteral = toVectorLiteral;
+exports.buildChunkSearchWhere = buildChunkSearchWhere;
+exports.assignIfDefined = assignIfDefined;
+exports.normalizeTopK = normalizeTopK;
+exports.rowToChunkMetadata = rowToChunkMetadata;
+exports.readOptionalString = readOptionalString;
+exports.readOptionalNumber = readOptionalNumber;
+exports.readOptionalStringArray = readOptionalStringArray;
+const DEFAULT_TABLE_PREFIX = 'rag';
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function resolvePostgresTableNames(tablePrefix = DEFAULT_TABLE_PREFIX) {
+    assertSafeIdentifier(tablePrefix, 'tablePrefix');
+    return {
+        documents: quoteIdentifier(`${tablePrefix}_documents`),
+        chunks: quoteIdentifier(`${tablePrefix}_chunks`),
+        embeddings: quoteIdentifier(`${tablePrefix}_embeddings`),
+        keywordEntries: quoteIdentifier(`${tablePrefix}_keyword_entries`),
+    };
+}
+function quoteIdentifier(identifier) {
+    assertSafeIdentifier(identifier, 'identifier');
+    return `"${identifier}"`;
+}
+function createJson(value) {
+    return JSON.stringify(value ?? null);
+}
+function createOptionalJson(value) {
+    return value === undefined ? null : JSON.stringify(value);
+}
+function readJsonObject(value) {
+    const parsed = readJson(value);
+    return isRecord(parsed) ? parsed : undefined;
+}
+function readJsonArray(value) {
+    const parsed = readJson(value);
+    return Array.isArray(parsed) ? parsed : undefined;
+}
+function readJson(value) {
+    if (typeof value === 'string') {
+        return JSON.parse(value);
+    }
+    return value;
+}
+function toVectorLiteral(vector) {
+    return `[${vector.map((value) => String(value)).join(',')}]`;
+}
+function buildChunkSearchWhere(options, startIndex = 1, alias = 'c') {
+    const clauses = [];
+    const values = [];
+    const column = (name) => `${alias}.${quoteIdentifier(name)}`;
+    const nextPlaceholder = (value) => {
+        values.push(value);
+        return `$${startIndex + values.length - 1}`;
+    };
+    if (options.tenantId !== undefined) {
+        clauses.push(`${column('tenant_id')} = ${nextPlaceholder(options.tenantId)}`);
+    }
+    if (options.knowledgeBaseId !== undefined) {
+        clauses.push(`${column('knowledge_base_id')} = ${nextPlaceholder(options.knowledgeBaseId)}`);
+    }
+    if (options.documentIds !== undefined) {
+        clauses.push(`${column('document_id')} = ANY(${nextPlaceholder(options.documentIds)}::text[])`);
+    }
+    if (options.sources !== undefined) {
+        clauses.push(`${column('source')} = ANY(${nextPlaceholder(options.sources)}::text[])`);
+    }
+    if (options.acl !== undefined) {
+        clauses.push(`(${column('acl')} IS NULL OR cardinality(${column('acl')}) = 0 OR ${column('acl')} && ${nextPlaceholder(options.acl)}::text[])`);
+    }
+    for (const [key, expected] of Object.entries(options.metadataFilter ?? {})) {
+        clauses.push(buildMetadataFilterClause({
+            key,
+            expected,
+            metadataAlias: alias,
+            nextPlaceholder,
+        }));
+    }
+    return {
+        clause: clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '',
+        values,
+    };
+}
+function buildMetadataFilterClause(input) {
+    const coreColumn = toMetadataColumn(input.key);
+    if (coreColumn !== undefined) {
+        const column = `${input.metadataAlias}.${quoteIdentifier(coreColumn)}`;
+        if (Array.isArray(input.expected)) {
+            return `${column} = ANY(${input.nextPlaceholder(input.expected)}::text[])`;
+        }
+        return `${column} = ${input.nextPlaceholder(input.expected)}`;
+    }
+    if (Array.isArray(input.expected)) {
+        const clauses = input.expected.map((value) => (`${input.metadataAlias}.${quoteIdentifier('extra')} @> ${input.nextPlaceholder(createJson({ [input.key]: value }))}::jsonb`));
+        return `(${clauses.join(' OR ')})`;
+    }
+    return `${input.metadataAlias}.${quoteIdentifier('extra')} @> ${input.nextPlaceholder(createJson({ [input.key]: input.expected }))}::jsonb`;
+}
+function toMetadataColumn(key) {
+    const columns = {
+        source: 'source',
+        title: 'title',
+        tenantId: 'tenant_id',
+        knowledgeBaseId: 'knowledge_base_id',
+        page: 'page',
+        startOffset: 'start_offset',
+        endOffset: 'end_offset',
+        chunkIndex: 'chunk_index',
+    };
+    return columns[key];
+}
+function assignIfDefined(target, key, value) {
+    if (value !== undefined) {
+        target[key] = value;
+    }
+}
+function normalizeTopK(topK) {
+    if (topK === undefined) {
+        return 10;
+    }
+    if (!Number.isFinite(topK) || topK <= 0) {
+        return 0;
+    }
+    return Math.floor(topK);
+}
+function rowToChunkMetadata(row) {
+    const metadata = {
+        source: String(row.source ?? 'inline'),
+        chunkIndex: Number(row.chunk_index ?? 0),
+    };
+    assignIfDefined(metadata, 'title', readOptionalString(row.title));
+    assignIfDefined(metadata, 'tenantId', readOptionalString(row.tenant_id));
+    assignIfDefined(metadata, 'knowledgeBaseId', readOptionalString(row.knowledge_base_id));
+    assignIfDefined(metadata, 'page', readOptionalNumber(row.page));
+    assignIfDefined(metadata, 'startOffset', readOptionalNumber(row.start_offset));
+    assignIfDefined(metadata, 'endOffset', readOptionalNumber(row.end_offset));
+    assignIfDefined(metadata, 'headingPath', readOptionalStringArray(row.heading_path));
+    assignIfDefined(metadata, 'acl', readOptionalStringArray(row.acl));
+    assignIfDefined(metadata, 'extra', readJsonObject(row.extra));
+    return metadata;
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readOptionalNumber(value) {
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'string' && value.length > 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function readOptionalStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.filter((item) => typeof item === 'string');
+}
+function assertSafeIdentifier(value, label) {
+    if (!IDENTIFIER_PATTERN.test(value)) {
+        throw new Error(`Invalid PostgreSQL ${label}: ${value}`);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=sql.js.map

package/dist/rag/stores/postgres/sql.js.map

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

package/dist/rag/stores/postgres/types.d.ts

@@ -0,0 +1,17 @@
+export interface PostgresQueryResult<Row = Record<string, unknown>> {
+    rows: Row[];
+}
+export interface PostgresQueryExecutor {
+    query<Row = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PostgresQueryResult<Row>>;
+}
+export interface PostgresRagStoreOptions {
+    db: PostgresQueryExecutor;
+    tablePrefix?: string;
+}
+export interface PostgresTableNames {
+    documents: string;
+    chunks: string;
+    embeddings: string;
+    keywordEntries: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rag/stores/postgres/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/rag/stores/postgres/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,IAAI,EAAE,GAAG,EAAE,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IAClC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,GACnB,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,uBAAuB;IACpC,EAAE,EAAE,qBAAqB,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CAC1B"}

package/dist/rag/stores/postgres/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/rag/stores/postgres/types.js.map

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

package/dist/rag/stores/types.d.ts

@@ -0,0 +1,36 @@
+import type { Chunk, EmbeddedChunk, RawDocument } from '../types';
+export interface SearchOptions {
+    topK?: number;
+    minScore?: number;
+    tenantId?: string;
+    knowledgeBaseId?: string;
+    acl?: string[];
+    documentIds?: string[];
+    sources?: string[];
+    metadataFilter?: Record<string, unknown>;
+}
+export interface ScoredChunkRef {
+    chunkId: string;
+    documentId: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+export interface DocumentStore {
+    upsertDocuments(documents: RawDocument[]): Promise<void>;
+    upsertChunks(chunks: Chunk[]): Promise<void>;
+    getChunks(ids: string[]): Promise<Chunk[]>;
+    getChunksByDocument(documentId: string): Promise<Chunk[]>;
+    deleteDocument(documentId: string): Promise<void>;
+}
+export interface VectorStore {
+    readonly dimensions: number;
+    upsert(items: EmbeddedChunk[]): Promise<void>;
+    search(vector: number[], options?: SearchOptions): Promise<ScoredChunkRef[]>;
+    deleteByDocument(documentId: string): Promise<void>;
+}
+export interface KeywordStore {
+    upsert(chunks: Chunk[]): Promise<void>;
+    search(query: string, options?: SearchOptions): Promise<ScoredChunkRef[]>;
+    deleteByDocument(documentId: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rag/stores/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rag/stores/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,KAAK,EACL,aAAa,EACb,WAAW,EACd,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,aAAa;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC1B,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC3C,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1D,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC7E,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,YAAY;IACzB,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC1E,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD"}

package/dist/rag/stores/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/rag/stores/types.js.map

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

package/dist/rag/stores/utils.d.ts

@@ -0,0 +1,11 @@
+import type { Chunk, EmbeddedChunk, RawDocument } from '../types';
+import type { ScoredChunkRef, SearchOptions } from './types';
+export declare const DEFAULT_SEARCH_TOP_K = 10;
+export declare function cloneRawDocument(document: RawDocument): RawDocument;
+export declare function cloneChunk(chunk: Chunk): Chunk;
+export declare function cloneEmbeddedChunk(item: EmbeddedChunk): EmbeddedChunk;
+export declare function cloneScoredChunkRef(ref: ScoredChunkRef): ScoredChunkRef;
+export declare function normalizeTopK(topK: number | undefined): number;
+export declare function matchesSearchOptions(chunk: Chunk, options?: SearchOptions): boolean;
+export declare function applyScoreOptions(refs: ScoredChunkRef[], options?: SearchOptions): ScoredChunkRef[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/rag/stores/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/rag/stores/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,KAAK,EAIL,aAAa,EACb,WAAW,EACd,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACR,cAAc,EACd,aAAa,EAChB,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,CAYnE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAY9C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAKrE;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc,CAYvE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAU9D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CA8BvF;AAED,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,cAAc,EAAE,EACtB,OAAO,GAAE,aAAkB,GAC5B,cAAc,EAAE,CAiBlB"}

package/dist/rag/stores/utils.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SEARCH_TOP_K = void 0;
+exports.cloneRawDocument = cloneRawDocument;
+exports.cloneChunk = cloneChunk;
+exports.cloneEmbeddedChunk = cloneEmbeddedChunk;
+exports.cloneScoredChunkRef = cloneScoredChunkRef;
+exports.normalizeTopK = normalizeTopK;
+exports.matchesSearchOptions = matchesSearchOptions;
+exports.applyScoreOptions = applyScoreOptions;
+exports.DEFAULT_SEARCH_TOP_K = 10;
+function cloneRawDocument(document) {
+    const clone = {
+        id: document.id,
+        content: document.content,
+        metadata: cloneDocumentMetadata(document.metadata),
+    };
+    if (document.blocks !== undefined) {
+        clone.blocks = document.blocks.map(cloneDocumentBlock);
+    }
+    return clone;
+}
+function cloneChunk(chunk) {
+    const clone = {
+        id: chunk.id,
+        documentId: chunk.documentId,
+        content: chunk.content,
+        kind: chunk.kind,
+        metadata: cloneChunkMetadata(chunk.metadata),
+    };
+    assignIfDefined(clone, 'parentId', chunk.parentId);
+    return clone;
+}
+function cloneEmbeddedChunk(item) {
+    return {
+        chunk: cloneChunk(item.chunk),
+        embedding: [...item.embedding],
+    };
+}
+function cloneScoredChunkRef(ref) {
+    const clone = {
+        chunkId: ref.chunkId,
+        documentId: ref.documentId,
+        score: ref.score,
+    };
+    if (ref.metadata !== undefined) {
+        clone.metadata = { ...ref.metadata };
+    }
+    return clone;
+}
+function normalizeTopK(topK) {
+    if (topK === undefined) {
+        return exports.DEFAULT_SEARCH_TOP_K;
+    }
+    if (!Number.isFinite(topK) || topK <= 0) {
+        return 0;
+    }
+    return Math.floor(topK);
+}
+function matchesSearchOptions(chunk, options = {}) {
+    if (options.tenantId !== undefined && chunk.metadata.tenantId !== options.tenantId) {
+        return false;
+    }
+    if (options.knowledgeBaseId !== undefined
+        && chunk.metadata.knowledgeBaseId !== options.knowledgeBaseId) {
+        return false;
+    }
+    if (options.documentIds !== undefined
+        && !options.documentIds.includes(chunk.documentId)) {
+        return false;
+    }
+    if (options.sources !== undefined
+        && !options.sources.includes(chunk.metadata.source)) {
+        return false;
+    }
+    if (!matchesAcl(chunk.metadata.acl, options.acl)) {
+        return false;
+    }
+    if (!matchesMetadataFilter(chunk.metadata, options.metadataFilter)) {
+        return false;
+    }
+    return true;
+}
+function applyScoreOptions(refs, options = {}) {
+    const minScore = options.minScore;
+    const topK = normalizeTopK(options.topK);
+    if (topK === 0) {
+        return [];
+    }
+    return refs
+        .filter((ref) => minScore === undefined || ref.score >= minScore)
+        .sort((left, right) => (right.score - left.score
+        || left.documentId.localeCompare(right.documentId)
+        || left.chunkId.localeCompare(right.chunkId)))
+        .slice(0, topK)
+        .map(cloneScoredChunkRef);
+}
+function cloneDocumentMetadata(metadata) {
+    const clone = {
+        source: metadata.source,
+    };
+    assignIfDefined(clone, 'title', metadata.title);
+    assignIfDefined(clone, 'mimeType', metadata.mimeType);
+    assignIfDefined(clone, 'tenantId', metadata.tenantId);
+    assignIfDefined(clone, 'knowledgeBaseId', metadata.knowledgeBaseId);
+    assignIfDefined(clone, 'version', metadata.version);
+    assignIfDefined(clone, 'checksum', metadata.checksum);
+    assignIfDefined(clone, 'createdAt', metadata.createdAt);
+    assignIfDefined(clone, 'updatedAt', metadata.updatedAt);
+    if (metadata.acl !== undefined) {
+        clone.acl = [...metadata.acl];
+    }
+    if (metadata.extra !== undefined) {
+        clone.extra = { ...metadata.extra };
+    }
+    return clone;
+}
+function cloneChunkMetadata(metadata) {
+    const clone = {
+        source: metadata.source,
+        chunkIndex: metadata.chunkIndex,
+    };
+    assignIfDefined(clone, 'title', metadata.title);
+    assignIfDefined(clone, 'tenantId', metadata.tenantId);
+    assignIfDefined(clone, 'knowledgeBaseId', metadata.knowledgeBaseId);
+    assignIfDefined(clone, 'page', metadata.page);
+    assignIfDefined(clone, 'startOffset', metadata.startOffset);
+    assignIfDefined(clone, 'endOffset', metadata.endOffset);
+    if (metadata.headingPath !== undefined) {
+        clone.headingPath = [...metadata.headingPath];
+    }
+    if (metadata.acl !== undefined) {
+        clone.acl = [...metadata.acl];
+    }
+    if (metadata.extra !== undefined) {
+        clone.extra = { ...metadata.extra };
+    }
+    return clone;
+}
+function cloneDocumentBlock(block) {
+    switch (block.type) {
+        case 'heading':
+            return { ...block };
+        case 'paragraph':
+            return { ...block };
+        case 'table': {
+            const clone = {
+                type: 'table',
+                markdown: block.markdown,
+            };
+            if (block.rows !== undefined) {
+                clone.rows = [...block.rows];
+            }
+            return clone;
+        }
+        case 'code':
+            return { ...block };
+        case 'image':
+            return { ...block };
+    }
+}
+function matchesAcl(chunkAcl, requestedAcl) {
+    if (requestedAcl === undefined) {
+        return true;
+    }
+    if (chunkAcl === undefined || chunkAcl.length === 0) {
+        return true;
+    }
+    return chunkAcl.some((acl) => requestedAcl.includes(acl));
+}
+function matchesMetadataFilter(metadata, filter) {
+    if (filter === undefined) {
+        return true;
+    }
+    return Object.entries(filter).every(([key, expected]) => {
+        const actual = readMetadataValue(metadata, key);
+        return matchesFilterValue(actual, expected);
+    });
+}
+function readMetadataValue(metadata, key) {
+    if (key in metadata) {
+        return metadata[key];
+    }
+    return metadata.extra?.[key];
+}
+function matchesFilterValue(actual, expected) {
+    if (Array.isArray(expected)) {
+        return expected.some((value) => matchesFilterValue(actual, value));
+    }
+    if (Array.isArray(actual)) {
+        return actual.some((value) => Object.is(value, expected));
+    }
+    return Object.is(actual, expected);
+}
+function assignIfDefined(target, key, value) {
+    if (value !== undefined) {
+        target[key] = value;
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/rag/stores/utils.js.map

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

package/dist/rag/types.d.ts

@@ -0,0 +1,174 @@
+import type { ChatModel, TokenUsage } from '../llm';
+import type { TraceContext } from '../observability';
+export type ChunkKind = 'text' | 'table' | 'code' | 'image_text';
+export type RetrievalSource = 'dense' | 'sparse' | 'hybrid' | 'rerank';
+export type RagConfidence = 'high' | 'medium' | 'low';
+/**
+ * RawDocument 是文档进入 RAG 系统后的标准形态。
+ * Loader / Parser 可以处理不同来源，但进入切块层前必须归一成这个结构。
+ */
+export interface RawDocument {
+    id: string;
+    content: string;
+    metadata: DocumentMetadata;
+    blocks?: DocumentBlock[];
+}
+export interface DocumentMetadata {
+    source: string;
+    title?: string;
+    mimeType?: string;
+    tenantId?: string;
+    knowledgeBaseId?: string;
+    acl?: string[];
+    version?: string;
+    checksum?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    extra?: Record<string, unknown>;
+}
+/**
+ * 结构化 block 用来保留 Markdown、表格、代码等文档语义。
+ * 初始实现可以只用 content，后续 chunker 可逐步利用 blocks 做更精细切割。
+ */
+export type DocumentBlock = {
+    type: 'heading';
+    text: string;
+    level: number;
+} | {
+    type: 'paragraph';
+    text: string;
+} | {
+    type: 'table';
+    markdown: string;
+    rows?: unknown[];
+} | {
+    type: 'code';
+    language?: string;
+    code: string;
+} | {
+    type: 'image';
+    alt?: string;
+    text?: string;
+};
+/**
+ * Chunk 是检索和引用的最小稳定单元。
+ * parentId 预留给 parent-child chunk：小 chunk 负责召回，大 chunk 负责提供上下文。
+ */
+export interface Chunk {
+    id: string;
+    documentId: string;
+    parentId?: string;
+    content: string;
+    kind: ChunkKind;
+    metadata: ChunkMetadata;
+}
+export interface ChunkMetadata {
+    source: string;
+    title?: string;
+    tenantId?: string;
+    knowledgeBaseId?: string;
+    headingPath?: string[];
+    page?: number;
+    startOffset?: number;
+    endOffset?: number;
+    chunkIndex: number;
+    acl?: string[];
+    extra?: Record<string, unknown>;
+}
+export interface EmbeddedChunk {
+    chunk: Chunk;
+    embedding: number[];
+}
+/**
+ * RetrievedChunk 只表达“证据片段及其分数”，不表达最终答案。
+ * 这样 retrieve() 可以被工具调用、调试和评测复用。
+ */
+export interface RetrievedChunk {
+    chunk: Chunk;
+    score: number;
+    source: RetrievalSource;
+    metadata?: Record<string, unknown>;
+}
+export interface Citation {
+    /**
+     * 生成上下文中的稳定引用编号，通常渲染为 [1]、[2]。
+     */
+    index: number;
+    chunkId: string;
+    documentId: string;
+    source: string;
+    title?: string;
+    headingPath?: string[];
+    page?: number;
+    quote?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RagContextItem {
+    citation: Citation;
+    chunk: Chunk;
+    content: string;
+    score: number;
+    source: RetrievalSource;
+    tokenEstimate: number;
+}
+export interface RagContext {
+    query: string;
+    text: string;
+    items: RagContextItem[];
+    citations: Citation[];
+    estimatedTokens: number;
+}
+export interface RagAnswer {
+    answer: string;
+    citations: Citation[];
+    confidence: RagConfidence;
+    retrieved: RetrievedChunk[];
+    usage?: TokenUsage;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * ingest() 先支持直接传标准文档，也预留 content/source 给后续 Loader 层。
+ * 具体实现应在写入索引前补齐 id、checksum、tenantId、acl 等元数据。
+ */
+export interface IngestInput {
+    documents?: RawDocument[];
+    content?: string;
+    data?: Uint8Array | ArrayBuffer;
+    source?: string;
+    mimeType?: string;
+    metadata?: Partial<DocumentMetadata>;
+    tenantId?: string;
+    knowledgeBaseId?: string;
+    acl?: string[];
+    replaceExisting?: boolean;
+}
+export interface IngestResult {
+    documentCount: number;
+    chunkCount: number;
+    documentIds: string[];
+    chunkIds: string[];
+    skippedDocumentIds?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface RetrieveOptions {
+    topK?: number;
+    minScore?: number;
+    tenantId?: string;
+    knowledgeBaseId?: string;
+    acl?: string[];
+    documentIds?: string[];
+    sources?: string[];
+    metadataFilter?: Record<string, unknown>;
+    trace?: TraceContext;
+}
+export interface AnswerOptions extends RetrieveOptions {
+    /**
+     * RAG 本身不拥有模型实例，生成阶段使用调用方传入的 ChatModel。
+     */
+    llm?: ChatModel;
+    maxContextTokens?: number;
+    requireCitations?: boolean;
+    systemPrompt?: string;
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map