@ai-agent-context/core 0.1.0

package/dist/core/search/bm25.js

@@ -0,0 +1,108 @@
+/**
+ * BM25 ranking over repository context nodes.
+ *
+ * Deterministic: no randomness, no external services, no embeddings. Scoring uses
+ * field-weighted term frequencies (title ≫ keywords > body) and exact identifier
+ * boosts, so `payment idempotency` ranks `PaymentMustBeIdempotentError` above a
+ * file that merely mentions the words.
+ */
+import { compareStrings } from "../../model/canonical.js";
+import { analyze, expandQueryTerms, pathSegments, stem } from "./analyzer.js";
+const FIELD_WEIGHT = { title: 3, keywords: 2, body: 1 };
+export class Bm25Index {
+    name = 'bm25';
+    documents = [];
+    documentFrequency = new Map();
+    k1;
+    b;
+    titleBoost;
+    identifierBoost;
+    averageLength = 0;
+    constructor(documents, options = {}) {
+        this.k1 = options.k1 ?? 1.2;
+        this.b = options.b ?? 0.75;
+        this.titleBoost = options.titleBoost ?? 1.35;
+        this.identifierBoost = options.identifierBoost ?? 0.9;
+        for (const document of documents) {
+            const terms = new Map();
+            const add = (text, weight) => {
+                for (const term of analyze(text, { keepStopWords: true })) {
+                    terms.set(term, (terms.get(term) ?? 0) + weight);
+                }
+            };
+            add(document.title, FIELD_WEIGHT.title);
+            for (const keyword of document.keywords)
+                add(keyword, FIELD_WEIGHT.keywords);
+            add(document.body, FIELD_WEIGHT.body);
+            let length = 0;
+            for (const count of terms.values())
+                length += count;
+            for (const term of terms.keys()) {
+                this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+            }
+            this.documents.push({
+                document,
+                terms,
+                length,
+                identifiers: new Set([...analyze(document.title, { keepStopWords: true }), ...pathSegments(document.title)]),
+            });
+        }
+        const total = this.documents.reduce((sum, entry) => sum + entry.length, 0);
+        this.averageLength = this.documents.length === 0 ? 1 : Math.max(1, total / this.documents.length);
+    }
+    get size() {
+        return this.documents.length;
+    }
+    query(query) {
+        const limit = query.limit ?? 10;
+        const terms = expandQueryTerms(analyze(query.text));
+        if (terms.size === 0)
+            return [];
+        const allowedTypes = query.types === undefined ? null : new Set(query.types);
+        const totalDocuments = Math.max(1, this.documents.length);
+        const results = [];
+        for (const entry of this.documents) {
+            if (allowedTypes !== null && !allowedTypes.has(entry.document.type))
+                continue;
+            let score = 0;
+            const matched = [];
+            for (const [term, weight] of terms) {
+                const frequency = entry.terms.get(term) ?? 0;
+                let termScore = 0;
+                if (frequency > 0) {
+                    const documentFrequency = this.documentFrequency.get(term) ?? 0;
+                    const idf = Math.log(1 + (totalDocuments - documentFrequency + 0.5) / (documentFrequency + 0.5));
+                    const normalization = 1 - this.b + this.b * (entry.length / this.averageLength);
+                    const saturation = frequency * (this.k1 + 1);
+                    termScore = (idf * saturation) / (frequency + this.k1 * normalization);
+                    matched.push(term);
+                }
+                else if (entry.identifiers.has(term) || entry.identifiers.has(stem(term))) {
+                    // Identifier boost: the term appears verbatim in the node name/path.
+                    termScore = 0.6 * (this.documentFrequency.get(term) === undefined ? 1 : 0.5);
+                    matched.push(term);
+                }
+                score += termScore * weight;
+            }
+            if (score <= 0)
+                continue;
+            const titleTerms = new Set(analyze(entry.document.title, { keepStopWords: true }));
+            for (const term of matched) {
+                if (titleTerms.has(term))
+                    score *= this.titleBoost;
+            }
+            const positional = matched.filter((term) => pathSegments(entry.document.title).includes(term)).length;
+            score += positional * this.identifierBoost;
+            const reasons = [];
+            if (titleTerms.size > 0)
+                reasons.push(`matched ${matched.length} of ${terms.size} query terms`);
+            results.push({ document: entry.document, score, matched, reasons });
+        }
+        results.sort((a, b) => a.score === b.score
+            ? compareStrings(a.document.id, b.document.id)
+            : b.score - a.score);
+        const minimum = query.minScore ?? 0;
+        return results.filter((result) => result.score >= minimum).slice(0, limit);
+    }
+}
+//# sourceMappingURL=bm25.js.map

package/dist/core/search/bm25.js.map

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

package/dist/core/search/documents.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Search document construction.
+ *
+ * Nodes of the knowledge graph are flattened into documents with a title (what the
+ * node *is*), keywords (identity: paths, kinds, module ids) and a body (facts:
+ * signals, exports, responsibilities, evidence). The same node kinds are exposed
+ * by the CLI, the programmatic API and the MCP tools, so `search_context`
+ * returns results an agent can act on.
+ */
+import type { SearchDocument } from './types.ts';
+import type { KnowledgeGraph } from '../graph/knowledge-graph.ts';
+import type { ParsedFile } from '../../adapters/language/types.ts';
+export interface SearchDocumentInput {
+    graph: KnowledgeGraph;
+    parsed: Map<string, ParsedFile>;
+}
+export declare function buildSearchDocuments(input: SearchDocumentInput): SearchDocument[];
+/** Compact snippet shown next to a search hit. */
+export declare function snippetFor(document: SearchDocument, limit?: number): string;
+//# sourceMappingURL=documents.d.ts.map

package/dist/core/search/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../../src/core/search/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAGnE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACjC;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,EAAE,CAyGjF;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,SAAM,GAAG,MAAM,CAGxE"}

package/dist/core/search/documents.js

@@ -0,0 +1,106 @@
+import { compareStrings } from "../../model/canonical.js";
+export function buildSearchDocuments(input) {
+    const { graph, parsed } = input;
+    const documents = [];
+    for (const file of graph.repository.files) {
+        const facts = parsed.get(file.path);
+        const exportedNames = (graph.symbolsByFile.get(file.path) ?? [])
+            .filter((symbol) => symbol.exported)
+            .map((symbol) => symbol.name)
+            .slice(0, 25);
+        const bodyParts = [
+            `kind: ${file.kind}`,
+            `language: ${file.language}`,
+            file.moduleId !== null ? `module: ${file.moduleId}` : '',
+            file.signals.length > 0 ? `signals: ${file.signals.join(', ')}` : '',
+            exportedNames.length > 0 ? `exports: ${exportedNames.join(', ')}` : '',
+            facts !== undefined && facts.routes.length > 0
+                ? `routes: ${facts.routes.map((route) => `${route.method} ${route.path}`).join(', ')}`
+                : '',
+            facts !== undefined && facts.imports.length > 0
+                ? `imports: ${[...new Set(facts.imports.map((record) => record.specifier))].slice(0, 20).join(', ')}`
+                : '',
+        ].filter((part) => part.length > 0);
+        documents.push({
+            id: `file:${file.path}`,
+            type: 'file',
+            title: file.path,
+            body: bodyParts.join('\n'),
+            keywords: [file.language, file.kind, file.moduleId ?? '', ...file.signals],
+        });
+    }
+    for (const module of graph.repository.modules) {
+        const bodyParts = [
+            `path: ${module.path}`,
+            `basis: ${module.basis}`,
+            module.roles.length > 0 ? `roles: ${module.roles.map((role) => `${role.value} (${role.confidence})`).join(', ')}` : '',
+            module.responsibilities.length > 0
+                ? `responsibilities: ${module.responsibilities.map((entry) => entry.value).join('; ')}`
+                : '',
+            module.dependsOn.length > 0 ? `depends on: ${module.dependsOn.join(', ')}` : '',
+            module.usedBy.length > 0 ? `used by: ${module.usedBy.join(', ')}` : '',
+            module.publicExports.length > 0
+                ? `public API: ${module.publicExports.map((entry) => entry.name).join(', ')}`
+                : '',
+            module.signals.length > 0 ? `signals: ${module.signals.join(', ')}` : '',
+            `files: ${module.files.length}`,
+        ].filter((part) => part.length > 0);
+        documents.push({
+            id: `module:${module.id}`,
+            type: 'module',
+            title: `${module.id} ${module.name}`,
+            body: bodyParts.join('\n'),
+            keywords: [module.path, module.packageName ?? '', module.basis, ...module.roles.map((role) => role.value)],
+        });
+    }
+    for (const symbol of graph.repository.symbols) {
+        const bodyParts = [
+            `${symbol.kind} in ${symbol.file} (line ${symbol.line})`,
+            symbol.exported ? 'exported' : 'internal',
+            symbol.extends.length > 0 ? `extends ${symbol.extends.join(', ')}` : '',
+            symbol.implements.length > 0 ? `implements ${symbol.implements.join(', ')}` : '',
+            symbol.moduleId !== null ? `module ${symbol.moduleId}` : '',
+        ].filter((part) => part.length > 0);
+        documents.push({
+            id: `symbol:${symbol.id}`,
+            type: 'symbol',
+            title: symbol.name,
+            body: bodyParts.join('\n'),
+            keywords: [symbol.file, symbol.kind, symbol.moduleId ?? ''],
+        });
+    }
+    for (const decision of graph.repository.decisions) {
+        documents.push({
+            id: `decision:${decision.id}`,
+            type: 'decision',
+            title: decision.title,
+            body: [decision.excerpt ?? '', `status: ${decision.status}`, `origin: ${decision.origin}`, decision.source].join('\n'),
+            keywords: [decision.id, decision.status, decision.kind],
+        });
+    }
+    for (const convention of graph.repository.conventions) {
+        documents.push({
+            id: `convention:${convention.id}`,
+            type: 'convention',
+            title: convention.statement,
+            body: [convention.category, ...convention.evidence.map((entry) => `${entry.source}: ${entry.detail}`)].join('\n'),
+            keywords: [convention.category, convention.origin],
+        });
+    }
+    for (const entry of graph.repository.entryPoints) {
+        documents.push({
+            id: `entry-point:${entry.path}:${entry.type}`,
+            type: 'entry-point',
+            title: `${entry.path} (${entry.type})`,
+            body: [entry.details ?? '', ...entry.evidence.map((item) => `${item.source}: ${item.detail}`)].join('\n'),
+            keywords: [entry.type, entry.moduleId ?? ''],
+        });
+    }
+    return documents.sort((a, b) => compareStrings(a.id, b.id));
+}
+/** Compact snippet shown next to a search hit. */
+export function snippetFor(document, limit = 160) {
+    const text = document.body.replace(/\s+/g, ' ').trim();
+    return text.length <= limit ? text : `${text.slice(0, limit - 1).trimEnd()}\u2026`;
+}
+//# sourceMappingURL=documents.js.map

package/dist/core/search/documents.js.map

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

package/dist/core/search/service.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Search service.
+ *
+ * Orchestrates the backend (BM25 by default) and the optional reranker, then
+ * projects the hits into `SearchResult` objects with a deterministic `reason`
+ * string — an agent must be able to see *why* a node was returned.
+ */
+import type { SearchResult } from '../../model/types.ts';
+import { type SearchDocumentInput } from './documents.ts';
+import type { RankedDocument, Reranker, SearchBackend, SearchNodeType } from './types.ts';
+export interface SearchOptions {
+    limit?: number;
+    types?: SearchNodeType[];
+    minScore?: number;
+    /** Optional semantic/LLM reranking hook; unused by default (local-first). */
+    reranker?: Reranker;
+}
+export declare class SearchService {
+    private readonly backend;
+    constructor(backend: SearchBackend);
+    get backendName(): string;
+    /** Builds a service over the knowledge graph with the default BM25 backend. */
+    static fromGraph(input: SearchDocumentInput): SearchService;
+    /** Builds a service over an explicit backend (embeddings, vector DB, ...). */
+    static withBackend(backend: SearchBackend): SearchService;
+    search(text: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+/** Maps a ranked document onto the public, agent-facing result shape. */
+export declare function toSearchResult(ranked: RankedDocument, backendName: string): SearchResult;
+//# sourceMappingURL=service.d.ts.map

package/dist/core/search/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/core/search/service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,OAAO,EAAoC,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAe,MAAM,YAAY,CAAC;AAEvG,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAE5B,OAAO,EAAE,aAAa;IAIlC,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,+EAA+E;IAC/E,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,mBAAmB,GAAG,aAAa;IAI3D,8EAA8E;IAC9E,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa;IAInD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAWjF;AAID,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY,CAiBxF"}

package/dist/core/search/service.js

@@ -0,0 +1,54 @@
+import { compareStrings } from "../../model/canonical.js";
+import { Bm25Index } from "./bm25.js";
+import { buildSearchDocuments, snippetFor } from "./documents.js";
+export class SearchService {
+    backend;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    get backendName() {
+        return this.backend.name;
+    }
+    /** Builds a service over the knowledge graph with the default BM25 backend. */
+    static fromGraph(input) {
+        return new SearchService(new Bm25Index(buildSearchDocuments(input)));
+    }
+    /** Builds a service over an explicit backend (embeddings, vector DB, ...). */
+    static withBackend(backend) {
+        return new SearchService(backend);
+    }
+    async search(text, options = {}) {
+        const query = { text, limit: options.limit ?? 10 };
+        if (options.types !== undefined)
+            query.types = options.types;
+        if (options.minScore !== undefined)
+            query.minScore = options.minScore;
+        let ranked = this.backend.query(query);
+        if (options.reranker !== undefined && ranked.length > 0) {
+            ranked = await options.reranker(query, ranked);
+        }
+        return ranked.map((entry) => toSearchResult(entry, this.backend.name));
+    }
+}
+const STOP_WORD_FILTER = new Set(['and', 'the', 'of', 'in', 'is', 'to', 'for', 'with']);
+/** Maps a ranked document onto the public, agent-facing result shape. */
+export function toSearchResult(ranked, backendName) {
+    const matched = ranked.matched.filter((term) => !STOP_WORD_FILTER.has(term)).sort(compareStrings);
+    const reasonParts = [
+        matched.length > 0 ? `matched terms: ${matched.join(', ')}` : 'matched by identifier',
+        ...ranked.reasons,
+        `ranked by ${backendName}`,
+    ];
+    const [type, ...idParts] = ranked.document.id.split(':');
+    const result = {
+        type: (type ?? 'file'),
+        id: idParts.join(':'),
+        score: Math.round(ranked.score * 10_000) / 10_000,
+        reason: reasonParts.filter((part) => part.length > 0).join('; '),
+    };
+    const snippet = snippetFor(ranked.document);
+    if (snippet.length > 0)
+        result.snippet = snippet;
+    return result;
+}
+//# sourceMappingURL=service.js.map

package/dist/core/search/service.js.map

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

package/dist/core/search/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Deterministic lexical search.
+ *
+ * No embeddings, no LLM, no network: tokens are extracted with a small
+ * language-aware analyzer, expanded with a synonym map and scored with BM25 over
+ * per-node documents. An optional {@link Reranker} hook (LLM, embeddings, vector
+ * database) can be plugged in later without touching the index or the callers.
+ */
+import type { SearchResult } from '../../model/types.ts';
+export type SearchNodeType = SearchResult['type'];
+export interface SearchDocument {
+    id: string;
+    type: SearchNodeType;
+    /** Primary text (path, symbol name, statement, ...). */
+    title: string;
+    /** Secondary text used for matching but not for identifier boosting. */
+    body: string;
+    /** Extra keywords: module ids, paths, kinds. */
+    keywords: string[];
+}
+export interface SearchQuery {
+    text: string;
+    limit?: number;
+    /** Restrict results to specific node types. */
+    types?: SearchNodeType[];
+    /** Minimum score below which results are dropped. */
+    minScore?: number;
+}
+export interface RankedDocument {
+    document: SearchDocument;
+    score: number;
+    /** Matched terms, sorted by weight contribution. */
+    matched: string[];
+    /** Reasons the ranking backend wants to surface. */
+    reasons: string[];
+}
+/** Pluggable ranking backend. `Bm25Index` is the deterministic default. */
+export interface SearchBackend {
+    readonly name: string;
+    query(query: SearchQuery): RankedDocument[];
+}
+/** Optional post-processing hook (LLM reranking, vector search, ...). */
+export type Reranker = (query: SearchQuery, results: RankedDocument[]) => Promise<RankedDocument[]>;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/search/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/search/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,MAAM,cAAc,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,EAAE,CAAC;CAC7C;AAED,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC"}

package/dist/core/search/types.js

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

package/dist/core/search/types.js.map

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

package/dist/core/serialization/documents.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Builders for the canonical `.agent/` documents.
+ *
+ * Determinism rules: arrays are sorted by stable keys, absolute paths never leak
+ * into the output, and timestamps are optional (`output.includeTimestamp`).
+ */
+import type { KnowledgeGraph } from '../graph/knowledge-graph.ts';
+import type { ParsedFile } from '../../adapters/language/types.ts';
+import type { AgentContextConfig } from '../../config/types.ts';
+import type { ArchitectureDocument, ContextDocuments, DecisionsDocument, DependenciesDocument, DocumentBuildOptions, IndexDocument, ConventionsDocument } from './types.ts';
+/** Builds the `index.json` manifest. */
+export declare function buildIndexDocument(graph: KnowledgeGraph, parsed: Map<string, ParsedFile>, config: AgentContextConfig, options: DocumentBuildOptions): IndexDocument;
+/** Builds `architecture.json`. */
+export declare function buildArchitectureDocument(graph: KnowledgeGraph, config: AgentContextConfig, options: DocumentBuildOptions): ArchitectureDocument;
+/** Builds `dependencies.json` (module edges, external packages, per-file imports). */
+export declare function buildDependenciesDocument(graph: KnowledgeGraph, config: AgentContextConfig, options: DocumentBuildOptions): DependenciesDocument;
+/** Builds `conventions.json` and the human readable `conventions.md` projection. */
+export declare function buildConventionsDocuments(graph: KnowledgeGraph, config: AgentContextConfig, options: DocumentBuildOptions): {
+    document: ConventionsDocument;
+    markdown: string;
+};
+/** Builds `decisions.json`. */
+export declare function buildDecisionsDocument(graph: KnowledgeGraph, options: DocumentBuildOptions): DecisionsDocument;
+/** Builds every canonical document in one pass. */
+export declare function buildContextDocuments(graph: KnowledgeGraph, parsed: Map<string, ParsedFile>, config: AgentContextConfig, options: DocumentBuildOptions): ContextDocuments;
+//# sourceMappingURL=documents.d.ts.map

package/dist/core/serialization/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/documents.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAIhE,OAAO,KAAK,EACV,oBAAoB,EAEpB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAMpB,wCAAwC;AACxC,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC/B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAuDf;AAED,kCAAkC;AAClC,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,oBAAoB,CAuDtB;AAID,sFAAsF;AACtF,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,oBAAoB,CAmEtB;AAED,oFAAoF;AACpF,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B;IAAE,QAAQ,EAAE,mBAAmB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAiBrD;AAED,+BAA+B;AAC/B,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CASnB;AAED,mDAAmD;AACnD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC/B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,gBAAgB,CAUlB"}