@framers/agentos 0.1.22 → 0.1.24

package/dist/rag/audit/RAGAuditCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RAGAuditCollector.d.ts","sourceRoot":"","sources":["../../../src/rag/audit/RAGAuditCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EAElB,MAAM,oBAAoB,CAAC;AAO5B,4EAA4E;AAC5E,UAAU,eAAe;IACvB,WAAW,CACT,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EACrF,KAAK,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GACrH,IAAI,CAAC;CACT;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qGAAqG;IACrG,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;gBAG9D,IAAI,EAAE,iBAAiB,CAAC,eAAe,CAAC,EACxC,UAAU,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI;IAqBhD,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,GAAG,IAAI;IAKtE,UAAU,CACR,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC,GACD,IAAI;IAiBP,aAAa,CAAC,KAAK,EAAE,iBAAiB,CAAC,YAAY,CAAC,GAAG,IAAI;IAK3D,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK9B,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAKrC,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAKrC,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC,GAAG,IAAI;IAK9E,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC,iBAAiB,CAAC,eAAe,CAAC,CAAC,GAAG,IAAI;IAKhF;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,iBAAiB;CAoB/E;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;gBAE1C,OAAO,EAAE,wBAAwB;IAM7C,+DAA+D;IAC/D,cAAc,CAAC,IAAI,EAAE,iBAAiB,CAAC,eAAe,CAAC,GAAG,kBAAkB;IAM5E,0EAA0E;IAC1E,QAAQ,IAAI,aAAa;CAyG1B"}

package/dist/rag/audit/RAGAuditCollector.js

@@ -0,0 +1,230 @@
+/**
+ * @fileoverview Request-scoped collector that accumulates RAG operations during
+ * a single retrieval pipeline execution and produces a finalized RAGAuditTrail.
+ *
+ * Usage:
+ * ```typescript
+ * const collector = new RAGAuditCollector({ requestId: 'req-1', query: 'What is ML?' });
+ *
+ * const embedOp = collector.startOperation('embedding');
+ * // ... do embedding work ...
+ * embedOp.setTokenUsage({ embeddingTokens: 512, llmPromptTokens: 0, llmCompletionTokens: 0, totalTokens: 512 });
+ * embedOp.complete(1);
+ *
+ * const trail = collector.finalize();
+ * ```
+ *
+ * @module @framers/agentos/rag/audit
+ */
+let _idCounter = 0;
+function nextId(prefix) {
+    return `${prefix}-${Date.now().toString(36)}-${(++_idCounter).toString(36)}`;
+}
+/**
+ * Fluent handle for a single in-flight RAG operation.
+ * Call `.complete(resultsCount)` to finalize timing and add it to the collector.
+ */
+export class RAGOperationHandle {
+    constructor(type, onComplete) {
+        this.completed = false;
+        this.startTime = Date.now();
+        this.onComplete = onComplete;
+        this.entry = {
+            operationId: nextId(`op-${type}`),
+            operationType: type,
+            startedAt: new Date().toISOString(),
+            durationMs: 0,
+            sources: [],
+            tokenUsage: {
+                embeddingTokens: 0,
+                llmPromptTokens: 0,
+                llmCompletionTokens: 0,
+                totalTokens: 0,
+            },
+            costUSD: 0,
+            resultsCount: 0,
+        };
+    }
+    setRetrievalMethod(method) {
+        this.entry.retrievalMethod = method;
+        return this;
+    }
+    addSources(chunks) {
+        for (const c of chunks) {
+            const chunkId = c.chunkId ?? c.id ?? 'unknown';
+            const documentId = c.documentId ?? c.originalDocumentId ?? chunkId;
+            this.entry.sources.push({
+                chunkId,
+                documentId,
+                source: c.source,
+                contentSnippet: c.contentSnippet ?? (c.content ?? '').slice(0, 200),
+                relevanceScore: c.relevanceScore ?? 0,
+                dataSourceId: c.dataSourceId,
+                metadata: c.metadata,
+            });
+        }
+        return this;
+    }
+    setTokenUsage(usage) {
+        this.entry.tokenUsage = usage;
+        return this;
+    }
+    setCost(costUSD) {
+        this.entry.costUSD = costUSD;
+        return this;
+    }
+    setDataSourceIds(ids) {
+        this.entry.dataSourceIds = ids;
+        return this;
+    }
+    setCollectionIds(ids) {
+        this.entry.collectionIds = ids;
+        return this;
+    }
+    setGraphDetails(details) {
+        this.entry.graphDetails = details;
+        return this;
+    }
+    setRerankDetails(details) {
+        this.entry.rerankDetails = details;
+        return this;
+    }
+    /**
+     * Finalizes the operation, records duration, computes relevance score stats,
+     * and adds the entry to the parent collector.
+     *
+     * @param resultsCount Number of results this operation produced.
+     * @param overrideDurationMs Optional override for duration (when timing is measured externally).
+     */
+    complete(resultsCount, overrideDurationMs) {
+        if (this.completed)
+            return this.entry;
+        this.completed = true;
+        this.entry.durationMs = overrideDurationMs ?? (Date.now() - this.startTime);
+        this.entry.resultsCount = resultsCount;
+        // Compute relevance score stats from sources
+        if (this.entry.sources.length > 0) {
+            const scores = this.entry.sources.map((s) => s.relevanceScore);
+            this.entry.relevanceScores = {
+                min: Math.min(...scores),
+                max: Math.max(...scores),
+                avg: scores.reduce((a, b) => a + b, 0) / scores.length,
+            };
+        }
+        this.onComplete(this.entry);
+        return this.entry;
+    }
+}
+/**
+ * Request-scoped audit collector. Create one per `retrieveContext()` call.
+ * NOT a singleton — scoped to a single pipeline execution.
+ */
+export class RAGAuditCollector {
+    constructor(options) {
+        this.operations = [];
+        this.options = options;
+        this.trailId = nextId('trail');
+        this.startTime = Date.now();
+    }
+    /** Start tracking a new operation. Returns a fluent handle. */
+    startOperation(type) {
+        return new RAGOperationHandle(type, (entry) => {
+            this.operations.push(entry);
+        });
+    }
+    /** Finalize and return the complete audit trail with computed summary. */
+    finalize() {
+        const totalDurationMs = Date.now() - this.startTime;
+        // Aggregate totals
+        let totalTokens = 0;
+        let totalPromptTokens = 0;
+        let totalCompletionTokens = 0;
+        let totalEmbeddingTokens = 0;
+        let totalCostUSD = 0;
+        let totalLLMCalls = 0;
+        let totalEmbeddingCalls = 0;
+        const operationTypes = new Set();
+        const uniqueDocuments = new Set();
+        const uniqueCollections = new Set();
+        const uniqueDataSources = new Set();
+        for (const op of this.operations) {
+            operationTypes.add(op.operationType);
+            totalTokens += op.tokenUsage.totalTokens;
+            totalPromptTokens += op.tokenUsage.llmPromptTokens;
+            totalCompletionTokens += op.tokenUsage.llmCompletionTokens;
+            totalEmbeddingTokens += op.tokenUsage.embeddingTokens;
+            totalCostUSD += op.costUSD;
+            if (op.operationType === 'embedding') {
+                totalEmbeddingCalls++;
+            }
+            else if (op.operationType === 'rerank' ||
+                op.operationType === 'graph_local' ||
+                op.operationType === 'graph_global') {
+                // Graph search and reranking use LLM calls
+                if (op.tokenUsage.llmPromptTokens > 0 || op.tokenUsage.llmCompletionTokens > 0) {
+                    totalLLMCalls++;
+                }
+            }
+            for (const src of op.sources) {
+                uniqueDocuments.add(src.documentId);
+                if (src.dataSourceId)
+                    uniqueDataSources.add(src.dataSourceId);
+            }
+            if (op.collectionIds) {
+                for (const cId of op.collectionIds)
+                    uniqueCollections.add(cId);
+            }
+            if (op.dataSourceIds) {
+                for (const dsId of op.dataSourceIds)
+                    uniqueDataSources.add(dsId);
+            }
+        }
+        const trail = {
+            trailId: this.trailId,
+            requestId: this.options.requestId,
+            seedId: this.options.seedId,
+            sessionId: this.options.sessionId,
+            query: this.options.query,
+            timestamp: new Date(this.startTime).toISOString(),
+            operations: this.operations,
+            summary: {
+                totalOperations: this.operations.length,
+                totalLLMCalls,
+                totalEmbeddingCalls,
+                totalTokens,
+                totalPromptTokens,
+                totalCompletionTokens,
+                totalEmbeddingTokens,
+                totalCostUSD,
+                totalDurationMs,
+                operationTypes: Array.from(operationTypes),
+                sourceSummary: {
+                    uniqueDocuments: uniqueDocuments.size,
+                    uniqueCollections: uniqueCollections.size,
+                    uniqueDataSources: uniqueDataSources.size,
+                },
+            },
+        };
+        // Push to UsageLedger when one was provided.
+        if (this.options.usageLedger && this.options.sessionId) {
+            const ledger = this.options.usageLedger;
+            const sessionId = this.options.sessionId;
+            const personaId = this.options.seedId;
+            for (const op of this.operations) {
+                const providerId = op.operationType === 'embedding' ? 'rag-embedding'
+                    : op.operationType === 'rerank' ? 'rag-rerank'
+                        : op.operationType.startsWith('graph_') ? 'rag-graphrag'
+                            : 'rag-vector';
+                ledger.ingestUsage({ sessionId, personaId, providerId, modelId: op.rerankDetails?.modelId }, {
+                    promptTokens: op.tokenUsage.llmPromptTokens,
+                    completionTokens: op.tokenUsage.llmCompletionTokens,
+                    totalTokens: op.tokenUsage.totalTokens,
+                    costUSD: op.costUSD || undefined,
+                    isFinal: true,
+                });
+            }
+        }
+        return trail;
+    }
+}
+//# sourceMappingURL=RAGAuditCollector.js.map

package/dist/rag/audit/RAGAuditCollector.js.map

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

package/dist/rag/audit/RAGAuditTypes.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Types for RAG audit trails — full transparency on memory/RAG operations.
+ * Captures per-operation details (vector search, graph search, reranking, embeddings)
+ * with token usage, cost tracking, and source attribution.
+ * @module @framers/agentos/rag/audit
+ */
+/** A single RAG operation within a request pipeline. */
+export interface RAGOperationEntry {
+    operationId: string;
+    operationType: 'vector_query' | 'graph_local' | 'graph_global' | 'ingest' | 'rerank' | 'embedding';
+    /** ISO 8601 timestamp when the operation started. */
+    startedAt: string;
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** Retrieval strategy details (for vector_query operations). */
+    retrievalMethod?: {
+        strategy: 'similarity' | 'mmr' | 'hybrid';
+        hybridAlpha?: number;
+        topK?: number;
+        mmrLambda?: number;
+    };
+    /** Source documents/chunks that contributed to this operation's results. */
+    sources: RAGSourceAttribution[];
+    /** Token usage breakdown for this operation. */
+    tokenUsage: {
+        embeddingTokens: number;
+        llmPromptTokens: number;
+        llmCompletionTokens: number;
+        totalTokens: number;
+    };
+    /** Estimated cost in USD for this operation. */
+    costUSD: number;
+    /** Number of results returned by this operation. */
+    resultsCount: number;
+    /** Relevance score statistics across results. */
+    relevanceScores?: {
+        min: number;
+        max: number;
+        avg: number;
+    };
+    /** Data source IDs queried by this operation. */
+    dataSourceIds?: string[];
+    /** Collection IDs involved in this operation. */
+    collectionIds?: string[];
+    /** Graph-specific details (for graph_local / graph_global operations). */
+    graphDetails?: {
+        entitiesMatched: number;
+        communitiesSearched: number;
+        traversalTimeMs: number;
+    };
+    /** Reranking-specific details (for rerank operations). */
+    rerankDetails?: {
+        providerId: string;
+        modelId: string;
+        documentsReranked: number;
+    };
+}
+/** Attribution to a specific source document/chunk. */
+export interface RAGSourceAttribution {
+    chunkId: string;
+    documentId: string;
+    /** Original source pointer (URL, file path, etc.). */
+    source?: string;
+    /** First 200 characters of chunk content. */
+    contentSnippet: string;
+    /** Similarity/relevance score (0–1). */
+    relevanceScore: number;
+    /** Data source / collection this chunk came from. */
+    dataSourceId?: string;
+    /** Chunk metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Aggregated audit trail for a complete RAG request. */
+export interface RAGAuditTrail {
+    trailId: string;
+    /** Correlates with the conversation turn or API request. */
+    requestId: string;
+    /** Wunderland agent seed ID. */
+    seedId?: string;
+    /** Conversation session ID. */
+    sessionId?: string;
+    /** The user query that triggered RAG. */
+    query: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Per-operation breakdown. */
+    operations: RAGOperationEntry[];
+    /** Aggregated summary across all operations. */
+    summary: {
+        totalOperations: number;
+        totalLLMCalls: number;
+        totalEmbeddingCalls: number;
+        totalTokens: number;
+        totalPromptTokens: number;
+        totalCompletionTokens: number;
+        totalEmbeddingTokens: number;
+        totalCostUSD: number;
+        totalDurationMs: number;
+        /** Unique operation types used (e.g. ['embedding', 'vector_query', 'rerank']). */
+        operationTypes: string[];
+        sourceSummary: {
+            uniqueDocuments: number;
+            uniqueCollections: number;
+            uniqueDataSources: number;
+        };
+    };
+}
+//# sourceMappingURL=RAGAuditTypes.d.ts.map

package/dist/rag/audit/RAGAuditTypes.d.ts.map

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

package/dist/rag/audit/RAGAuditTypes.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Types for RAG audit trails — full transparency on memory/RAG operations.
+ * Captures per-operation details (vector search, graph search, reranking, embeddings)
+ * with token usage, cost tracking, and source attribution.
+ * @module @framers/agentos/rag/audit
+ */
+export {};
+//# sourceMappingURL=RAGAuditTypes.js.map

package/dist/rag/audit/RAGAuditTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RAGAuditTypes.js","sourceRoot":"","sources":["../../../src/rag/audit/RAGAuditTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/rag/audit/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview RAG Audit Trail module — types and collector for transparent
+ * tracking of RAG operations (vector search, graph search, reranking, embeddings).
+ * @module @framers/agentos/rag/audit
+ */
+export type { RAGAuditTrail, RAGOperationEntry, RAGSourceAttribution, } from './RAGAuditTypes.js';
+export { RAGAuditCollector, RAGOperationHandle, type RAGAuditCollectorOptions, } from './RAGAuditCollector.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/rag/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/audit/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC"}

package/dist/rag/audit/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview RAG Audit Trail module — types and collector for transparent
+ * tracking of RAG operations (vector search, graph search, reranking, embeddings).
+ * @module @framers/agentos/rag/audit
+ */
+export { RAGAuditCollector, RAGOperationHandle, } from './RAGAuditCollector.js';
+//# sourceMappingURL=index.js.map

package/dist/rag/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/audit/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,GAEnB,MAAM,wBAAwB,CAAC"}

package/dist/rag/graphrag/GraphRAGEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GraphRAGEngine.d.ts","sourceRoot":"","sources":["../../../src/rag/graphrag/GraphRAGEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GraphRAGEngine.d.ts","sourceRoot":"","sources":["../../../src/rag/graphrag/GraphRAGEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAkB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAOjE,UAAU,WAAW;IACnB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvG;AAED,UAAU,kBAAkB;IAC1B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACtE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CAC5E;AAuBD,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,aAAa,CAAkB;IAGvC,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,WAAW,CAA0C;IAC7D,OAAO,CAAC,mBAAmB,CAA0B;IACrD,OAAO,CAAC,sBAAsB,CAAkC;IAChE,OAAO,CAAC,2BAA2B,CAAmE;IACtG,OAAO,CAAC,iCAAiC,CAAyE;IAGlH,OAAO,CAAC,KAAK,CAAS;IAGtB,OAAO,CAAC,WAAW,CAAC,CAAe;IACnC,OAAO,CAAC,gBAAgB,CAAC,CAAoB;IAC7C,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,kBAAkB,CAAC,CAAqB;IAEhD,OAAO,CAAC,WAAW,CAAuB;gBAE9B,IAAI,CAAC,EAAE;QACjB,WAAW,CAAC,EAAE,YAAY,CAAC;QAC3B,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;QACrC,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;KACzC;YASa,yBAAyB;YA0BzB,mBAAmB;IA4B3B,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAkDvD,OAAO,CAAC,iBAAiB;IAenB,eAAe,CACnB,SAAS,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;KAAE,CAAC,GAC1F,OAAO,CAAC;QACT,iBAAiB,EAAE,MAAM,CAAC;QAC1B,sBAAsB,EAAE,MAAM,CAAC;QAC/B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,kBAAkB,EAAE,MAAM,CAAC;KAC5B,CAAC;IAkJI,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACpD,gBAAgB,EAAE,MAAM,CAAC;QACzB,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;YA4DY,+BAA+B;YAa/B,UAAU;IAsFxB,OAAO,CAAC,cAAc;IAsDtB,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,WAAW;IAsCnB,OAAO,CAAC,iBAAiB;YA6DX,wBAAwB;YAyDxB,iBAAiB;YA6EjB,uBAAuB;YAoHvB,0BAA0B;YAoD1B,kBAAkB;IAiDhC,OAAO,CAAC,eAAe;IAajB,YAAY,CAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,kBAAkB,CAAC;IAwKxB,WAAW,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,iBAAiB,CAAC;IAiKvB,WAAW,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAShF,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAOhE,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IASzD,QAAQ,IAAI,OAAO,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,gBAAgB,EAAE,MAAM,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;QACxB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;IAYI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YAcjB,uBAAuB;YAkGvB,mBAAmB;YAkJnB,UAAU;IAyHxB,OAAO,CAAC,yBAAyB;IA4CjC,OAAO,CAAC,+BAA+B;YA0BzB,2CAA2C;YAmD3C,2BAA2B;CA6F1C"}

package/dist/rag/graphrag/GraphRAGEngine.js

@@ -961,6 +961,32 @@ ${summaryContext}
 
 Provide a comprehensive answer based on the information above.`, { maxTokens: 500, temperature: 0 });
             const synthesisTimeMs = Date.now() - synthesisStart;
+            // Audit: record graph global search with LLM synthesis
+            if (options?.auditCollector) {
+                const auditOp = options.auditCollector.startOperation('graph_global');
+                auditOp.setGraphDetails({
+                    entitiesMatched: 0,
+                    communitiesSearched: this.communities.size,
+                    traversalTimeMs: Date.now() - startTime,
+                });
+                auditOp.addSources(matchedCommunities.map(c => ({
+                    id: c.communityId,
+                    originalDocumentId: c.communityId,
+                    content: c.summary,
+                    relevanceScore: c.relevanceScore,
+                    source: `community:${c.title}`,
+                })));
+                // Estimate LLM tokens for synthesis (~4 chars per token)
+                const promptChars = summaryContext.length + query.length + 100;
+                const completionChars = answer.length;
+                auditOp.setTokenUsage({
+                    embeddingTokens: 0,
+                    llmPromptTokens: Math.ceil(promptChars / 4),
+                    llmCompletionTokens: Math.ceil(completionChars / 4),
+                    totalTokens: Math.ceil((promptChars + completionChars) / 4),
+                });
+                auditOp.complete(matchedCommunities.length);
+            }
             return {
                 query,
                 answer,
@@ -976,6 +1002,23 @@ Provide a comprehensive answer based on the information above.`, { maxTokens: 50
         answer = matchedCommunities
             .map(c => `${c.title}: ${c.summary}`)
             .join('\n\n');
+        // Audit: record graph global search
+        if (options?.auditCollector) {
+            const auditOp = options.auditCollector.startOperation('graph_global');
+            auditOp.setGraphDetails({
+                entitiesMatched: 0,
+                communitiesSearched: this.communities.size,
+                traversalTimeMs: Date.now() - startTime,
+            });
+            auditOp.addSources(matchedCommunities.map(c => ({
+                id: c.communityId,
+                originalDocumentId: c.communityId,
+                content: c.summary,
+                relevanceScore: c.relevanceScore,
+                source: `community:${c.title}`,
+            })));
+            auditOp.complete(matchedCommunities.length);
+        }
         return {
             query,
             answer,
@@ -1089,6 +1132,23 @@ Provide a comprehensive answer based on the information above.`, { maxTokens: 50
             '## Community Context',
             commContext,
         ].join('\n');
+        // Audit: record graph local search
+        if (options?.auditCollector) {
+            const auditOp = options.auditCollector.startOperation('graph_local');
+            auditOp.setGraphDetails({
+                entitiesMatched: matchedEntities.length,
+                communitiesSearched: seenCommunities.size,
+                traversalTimeMs: graphTraversalTimeMs,
+            });
+            auditOp.addSources(matchedEntities.map(e => ({
+                id: e.id,
+                originalDocumentId: e.sourceDocumentIds[0] ?? e.id,
+                content: `${e.name} (${e.type}): ${e.description}`,
+                relevanceScore: e.relevanceScore,
+                source: `entity:${e.name}`,
+            })));
+            auditOp.complete(matchedEntities.length);
+        }
         return {
             query,
             entities: matchedEntities,