@hazeljs/kag 0.0.0-stage → 2.0.9

package/dist/kag.module.js

@@ -0,0 +1,58 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var KagModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KagModule = void 0;
+const core_1 = require("@hazeljs/core");
+const core_2 = __importDefault(require("@hazeljs/core"));
+const kag_service_1 = require("./kag.service");
+const types_1 = require("./types");
+let KagModule = KagModule_1 = class KagModule {
+    static forRoot(options = {}) {
+        core_2.default.info('Configuring KAG module...');
+        const service = new kag_service_1.KagService(options);
+        return {
+            module: KagModule_1,
+            providers: [
+                { provide: types_1.KAG_OPTIONS, useValue: options },
+                { provide: kag_service_1.KagService, useValue: service },
+            ],
+            exports: [kag_service_1.KagService],
+            global: true,
+        };
+    }
+    static forRootAsync(options) {
+        return {
+            module: KagModule_1,
+            providers: [
+                {
+                    provide: types_1.KAG_OPTIONS,
+                    useFactory: options.useFactory,
+                    inject: options.inject,
+                },
+                {
+                    provide: kag_service_1.KagService,
+                    useFactory: (...args) => new kag_service_1.KagService(args[0]),
+                    inject: [types_1.KAG_OPTIONS],
+                },
+            ],
+            exports: [kag_service_1.KagService],
+            global: true,
+        };
+    }
+};
+exports.KagModule = KagModule;
+exports.KagModule = KagModule = KagModule_1 = __decorate([
+    (0, core_1.HazelModule)({
+        providers: [],
+        exports: [],
+    })
+], KagModule);

package/dist/kag.service.d.ts

@@ -0,0 +1,66 @@
+import type { AskOptions, ContextContribution, ContextContributor, KagModuleOptions, KnowledgeAnswer, EntityResolutionResult, KnowledgeEntity, KnowledgeFact, KnowledgeRelation, ObservationPromotion, TraversalResult } from './types';
+import { KnowledgeGraph } from './knowledge-graph';
+import { type IngestBatch, type IngestResult } from './ingestion/ingest';
+import { type GraphStoreLike } from './adapters/graphrag.adapter';
+export declare class KagService implements ContextContributor {
+    readonly kind: "kag";
+    private readonly graphs;
+    private readonly options;
+    constructor(options?: KagModuleOptions);
+    forTenant(tenantId: string, graph?: string): KnowledgeGraph;
+    private graphOrThrow;
+    entity(input: KnowledgeEntity, opts?: {
+        tenantId?: string;
+        graph?: string;
+    }): Promise<KnowledgeEntity>;
+    relate(input: Omit<KnowledgeRelation, 'id'> & {
+        id?: string;
+    }, opts?: {
+        tenantId?: string;
+        graph?: string;
+    }): Promise<KnowledgeRelation>;
+    fact(input: KnowledgeFact, opts?: {
+        tenantId?: string;
+        graph?: string;
+    }): Promise<{
+        fact: KnowledgeFact;
+        contradictions: KnowledgeFact[];
+    }>;
+    ingest(batch: IngestBatch, opts?: {
+        tenantId?: string;
+        graph?: string;
+        raw?: unknown;
+    }): Promise<IngestResult>;
+    traverse(seedIds: string[], options?: {
+        depth?: number;
+        asOf?: Date | string;
+        tenantId?: string;
+        graph?: string;
+    }): Promise<TraversalResult>;
+    ask(question: string, options?: AskOptions & {
+        tenantId?: string;
+    }): Promise<KnowledgeAnswer>;
+    resolve(candidate: KnowledgeEntity, opts?: {
+        tenantId?: string;
+        graph?: string;
+    }): Promise<EntityResolutionResult>;
+    promoteObservation(observation: ObservationPromotion, opts?: {
+        tenantId?: string;
+        graph?: string;
+    }): Promise<KnowledgeFact | null>;
+    importGraphRag(graphStore: GraphStoreLike, opts?: {
+        tenantId?: string;
+        graph?: string;
+    }): Promise<{
+        entities: number;
+        relations: number;
+    }>;
+    contribute(request: {
+        query: string;
+        tenantId: string;
+        namespace?: string;
+        agentId?: string;
+    }): Promise<ContextContribution>;
+    private key;
+}
+//# sourceMappingURL=kag.service.d.ts.map

package/dist/kag.service.d.ts.map

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

package/dist/kag.service.js

@@ -0,0 +1,92 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KagService = void 0;
+const core_1 = require("@hazeljs/core");
+const knowledge_graph_1 = require("./knowledge-graph");
+const kag_error_1 = require("./errors/kag.error");
+const ingest_1 = require("./ingestion/ingest");
+const graphrag_adapter_1 = require("./adapters/graphrag.adapter");
+let KagService = class KagService {
+    constructor(options = {}) {
+        this.kind = 'kag';
+        this.graphs = new Map();
+        this.options = options;
+        if (options.tenantId) {
+            this.graphs.set(this.key(options.tenantId, options.graph), new knowledge_graph_1.KnowledgeGraph({
+                ...options,
+                tenantId: options.tenantId,
+            }));
+        }
+    }
+    forTenant(tenantId, graph) {
+        const k = this.key(tenantId, graph ?? this.options.graph);
+        let g = this.graphs.get(k);
+        if (!g) {
+            g = new knowledge_graph_1.KnowledgeGraph({
+                ...this.options,
+                tenantId,
+                graph: graph ?? this.options.graph,
+            });
+            this.graphs.set(k, g);
+        }
+        return g;
+    }
+    graphOrThrow(tenantId, graph) {
+        const tid = tenantId ?? this.options.tenantId;
+        if (!tid) {
+            throw kag_error_1.KagError.tenantRequired();
+        }
+        return this.forTenant(tid, graph);
+    }
+    async entity(input, opts) {
+        return this.graphOrThrow(opts?.tenantId, opts?.graph).entity(input);
+    }
+    async relate(input, opts) {
+        return this.graphOrThrow(opts?.tenantId, opts?.graph).relate(input);
+    }
+    async fact(input, opts) {
+        return this.graphOrThrow(opts?.tenantId, opts?.graph).fact(input);
+    }
+    async ingest(batch, opts) {
+        const g = this.graphOrThrow(opts?.tenantId, opts?.graph);
+        return (0, ingest_1.ingestKnowledge)(g, batch, {
+            extractor: this.options.extractor,
+            raw: opts?.raw,
+        });
+    }
+    async traverse(seedIds, options) {
+        return this.graphOrThrow(options?.tenantId, options?.graph).traverse(seedIds, options);
+    }
+    async ask(question, options = {}) {
+        return this.graphOrThrow(options.tenantId, options.graph).ask(question, options);
+    }
+    async resolve(candidate, opts) {
+        return this.graphOrThrow(opts?.tenantId, opts?.graph).resolve(candidate);
+    }
+    async promoteObservation(observation, opts) {
+        return this.graphOrThrow(opts?.tenantId, opts?.graph).promoteObservation(observation);
+    }
+    async importGraphRag(graphStore, opts) {
+        return (0, graphrag_adapter_1.importGraph)(this.graphOrThrow(opts?.tenantId, opts?.graph), graphStore);
+    }
+    async contribute(request) {
+        return this.forTenant(request.tenantId, request.namespace).contribute(request);
+    }
+    key(tenantId, graph) {
+        return `${tenantId}::${graph ?? 'default'}`;
+    }
+};
+exports.KagService = KagService;
+exports.KagService = KagService = __decorate([
+    (0, core_1.Service)(),
+    __metadata("design:paramtypes", [Object])
+], KagService);

package/dist/knowledge-graph.d.ts

@@ -0,0 +1,50 @@
+import type { AskOptions, ContextContribution, ContextContributor, EntityResolutionResult, KagModuleOptions, KnowledgeAnswer, KnowledgeEntity, KnowledgeFact, KnowledgeRelation, KnowledgeScope, KnowledgeStore, ObservationPromotion, TraversalResult } from './types';
+export interface KnowledgeGraphOptions extends KagModuleOptions {
+    store?: KnowledgeStore;
+    tenantId: string;
+    graph?: string;
+}
+/**
+ * Primary KAG facade for scripts and tests (similar to GraphRAGPipeline).
+ */
+export declare class KnowledgeGraph implements ContextContributor {
+    readonly kind: "kag";
+    private readonly store;
+    private readonly scope;
+    private readonly resolver;
+    private readonly planner;
+    private readonly authorizer;
+    private readonly retriever?;
+    private readonly llm?;
+    private readonly confidenceAggregation;
+    private readonly externalEmitter?;
+    private readonly localEmitter;
+    constructor(options: KnowledgeGraphOptions);
+    on(event: string, listener: (...args: unknown[]) => void): this;
+    getScope(): KnowledgeScope;
+    entity(input: KnowledgeEntity): Promise<KnowledgeEntity>;
+    relate(input: Omit<KnowledgeRelation, 'id'> & {
+        id?: string;
+    }): Promise<KnowledgeRelation>;
+    fact(input: KnowledgeFact): Promise<{
+        fact: KnowledgeFact;
+        contradictions: KnowledgeFact[];
+    }>;
+    resolve(candidate: KnowledgeEntity): Promise<EntityResolutionResult>;
+    traverse(seedIds: string[], options?: {
+        depth?: number;
+        asOf?: Date | string;
+    }): Promise<TraversalResult>;
+    ask(question: string, options?: AskOptions): Promise<KnowledgeAnswer>;
+    promoteObservation(observation: ObservationPromotion): Promise<KnowledgeFact | null>;
+    changes(from: Date | string, to: Date | string): Promise<KnowledgeFact[]>;
+    currentFacts(subject?: string): Promise<KnowledgeFact[]>;
+    contribute(request: {
+        query: string;
+        tenantId: string;
+        namespace?: string;
+        agentId?: string;
+    }): Promise<ContextContribution>;
+    private emit;
+}
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/knowledge-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../src/knowledge-graph.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EAEf,eAAe,EAEf,aAAa,EAEb,iBAAiB,EAEjB,cAAc,EAEd,cAAc,EACd,oBAAoB,EACpB,eAAe,EAChB,MAAM,SAAS,CAAC;AAUjB,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,cAAe,YAAW,kBAAkB;IACvD,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAE/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAyD;IAC/F,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAmC;IACpE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;gBAEvC,OAAO,EAAE,qBAAqB;IAuB1C,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAK/D,QAAQ,IAAI,cAAc;IAIpB,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAmBxD,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAe1F,IAAI,CACR,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,cAAc,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;IAa9D,OAAO,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAKpE,QAAQ,CACZ,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;KAAE,GACjD,OAAO,CAAC,eAAe,CAAC;IAKrB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IA+GzE,kBAAkB,CAAC,WAAW,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAqBpF,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAKzE,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAQxD,UAAU,CAAC,OAAO,EAAE;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAYhC,OAAO,CAAC,IAAI;CAIb"}

package/dist/knowledge-graph.js

@@ -0,0 +1,290 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeGraph = void 0;
+const eventemitter3_1 = __importDefault(require("eventemitter3"));
+const crypto_1 = require("crypto");
+const types_1 = require("./types");
+const in_memory_knowledge_store_1 = require("./stores/in-memory-knowledge.store");
+const entity_resolver_1 = require("./resolution/entity-resolver");
+const heuristic_query_planner_1 = require("./planner/heuristic-query-planner");
+const authorizer_1 = require("./security/authorizer");
+const kag_error_1 = require("./errors/kag.error");
+const confidence_1 = require("./confidence");
+const temporal_1 = require("./temporal");
+/**
+ * Primary KAG facade for scripts and tests (similar to GraphRAGPipeline).
+ */
+class KnowledgeGraph {
+    constructor(options) {
+        this.kind = 'kag';
+        this.localEmitter = new eventemitter3_1.default();
+        if (!options.tenantId) {
+            throw kag_error_1.KagError.tenantRequired();
+        }
+        this.store = options.store ?? new in_memory_knowledge_store_1.InMemoryKnowledgeStore(options.contradictionPolicy ?? 'rank');
+        this.scope = { tenantId: options.tenantId, graph: options.graph };
+        this.resolver = new entity_resolver_1.EntityResolver({
+            mergeThreshold: options.mergeThreshold ?? 0.9,
+            embed: options.embed,
+            strategies: options.embed ? ['exact', 'normalized', 'semantic'] : ['exact', 'normalized'],
+        });
+        this.planner =
+            options.planner ??
+                new heuristic_query_planner_1.HeuristicQueryPlanner({
+                    industry: options.industry,
+                });
+        this.authorizer = options.authorizer ?? new authorizer_1.TenantKnowledgeAuthorizer(options.tenantId);
+        this.retriever = options.retriever;
+        this.llm = options.llm;
+        this.confidenceAggregation = options.confidenceAggregation ?? 'min';
+        this.externalEmitter = options.eventEmitter;
+    }
+    on(event, listener) {
+        this.localEmitter.on(event, listener);
+        return this;
+    }
+    getScope() {
+        return { ...this.scope };
+    }
+    async entity(input) {
+        await (0, authorizer_1.assertAuthorized)(this.authorizer, this.scope, 'write', {
+            kind: 'entity',
+            id: input.id,
+            type: input.type,
+        });
+        const existing = await this.store.listEntities(this.scope);
+        const resolution = await this.resolver.resolve(input, existing);
+        const toWrite = resolution.merged
+            ? { ...resolution.merged, id: resolution.merged.id }
+            : { ...input, confidence: input.confidence ?? 1 };
+        const prior = await this.store.getEntity(this.scope, toWrite.id);
+        await this.store.upsertEntity(this.scope, toWrite);
+        this.emit(prior ? types_1.KAG_EVENTS.ENTITY_UPDATED : types_1.KAG_EVENTS.ENTITY_CREATED, toWrite);
+        return toWrite;
+    }
+    async relate(input) {
+        await (0, authorizer_1.assertAuthorized)(this.authorizer, this.scope, 'write', {
+            kind: 'relation',
+            type: input.type,
+        });
+        const relation = {
+            ...input,
+            id: input.id ?? `${input.from}:${input.type}:${input.to}`,
+            confidence: input.confidence ?? 1,
+        };
+        await this.store.upsertRelation(this.scope, relation);
+        this.emit(types_1.KAG_EVENTS.RELATION_CREATED, relation);
+        return relation;
+    }
+    async fact(input) {
+        await (0, authorizer_1.assertAuthorized)(this.authorizer, this.scope, 'write', {
+            kind: 'fact',
+            id: input.subject,
+        });
+        const { contradictions } = await this.store.upsertFact(this.scope, input);
+        if (contradictions.length > 0) {
+            this.emit(types_1.KAG_EVENTS.CONTRADICTION_DETECTED, { fact: input, contradictions });
+        }
+        this.emit(types_1.KAG_EVENTS.FACT_ADDED, input);
+        return { fact: input, contradictions };
+    }
+    async resolve(candidate) {
+        const existing = await this.store.listEntities(this.scope);
+        return this.resolver.resolve(candidate, existing);
+    }
+    async traverse(seedIds, options) {
+        await (0, authorizer_1.assertAuthorized)(this.authorizer, this.scope, 'read', { kind: 'entity' });
+        return this.store.traverse(this.scope, seedIds, options);
+    }
+    async ask(question, options = {}) {
+        await (0, authorizer_1.assertAuthorized)(this.authorizer, this.scope, 'read', { kind: 'entity' });
+        const entities = await this.store.listEntities(this.scope);
+        const plan = await this.planner.plan(question, { scope: this.scope, entities });
+        const seeds = plan.seedIds.length > 0 ? plan.seedIds : entities.slice(0, 5).map((e) => e.id);
+        const traversal = await this.store.traverse(this.scope, seeds, {
+            depth: options.depth ?? plan.depth,
+            relationTypes: plan.relationTypes,
+            asOf: options.asOf,
+        });
+        const evidence = [];
+        for (const rel of traversal.relations) {
+            evidence.push({
+                entity: rel.from,
+                relation: rel.type,
+                entity2: rel.to,
+                source: rel.source,
+            });
+        }
+        for (const f of traversal.facts) {
+            evidence.push({ fact: f, source: f.source, entity: f.subject });
+        }
+        let alternatives;
+        const subjectIds = [
+            ...new Set([
+                ...seeds,
+                ...traversal.entities.map((e) => e.id),
+                ...traversal.facts.map((f) => f.subject),
+            ]),
+        ];
+        const query = await this.store.query(this.scope, {
+            entityIds: subjectIds.length > 0 ? subjectIds : undefined,
+            asOf: options.asOf,
+        });
+        if (query.contradictions && query.contradictions.length > 0) {
+            alternatives = query.contradictions.flat();
+            const winners = query.contradictions.map((group) => (0, confidence_1.rankFacts)(group)[0]);
+            for (const w of winners) {
+                if (!evidence.some((e) => e.fact?.id === w.id)) {
+                    evidence.push({ fact: w, source: w.source, entity: w.subject });
+                }
+            }
+        }
+        if (options.rag && this.retriever) {
+            const passages = await this.retriever.search(question, {
+                topK: 5,
+                tenantId: this.scope.tenantId,
+            });
+            for (const p of passages) {
+                evidence.push({
+                    source: { type: 'rag', id: p.id },
+                    fact: {
+                        subject: '_rag',
+                        predicate: 'passage',
+                        object: p.content,
+                        confidence: p.score ?? 0.7,
+                        source: { type: 'rag', id: p.id },
+                    },
+                });
+            }
+        }
+        const sources = [];
+        for (const e of evidence) {
+            if (e.source)
+                sources.push(e.source);
+            if (e.fact?.source)
+                sources.push(e.fact.source);
+        }
+        const confidence = (0, confidence_1.aggregateConfidence)([
+            traversal.confidence,
+            ...traversal.facts.map((f) => f.confidence ?? 1),
+            ...traversal.relations.map((r) => r.confidence ?? 1),
+        ], this.confidenceAggregation);
+        const explanation = options.explain
+            ? formatExplanation(evidence, confidence, plan.template)
+            : undefined;
+        let answer;
+        if (this.llm) {
+            const prompt = `Answer using ONLY the following evidence. Do not invent facts.\n` +
+                `Question: ${question}\n` +
+                `Evidence:\n${JSON.stringify(evidence, null, 2)}\n` +
+                `Confidence: ${confidence.toFixed(2)}`;
+            answer = await this.llm(prompt);
+        }
+        else {
+            answer = explanation ?? summarizeEvidence(evidence);
+        }
+        const result = {
+            answer,
+            evidence,
+            sources: dedupeSources(sources),
+            confidence,
+            alternatives,
+            explanation,
+        };
+        this.emit(types_1.KAG_EVENTS.QUERY_COMPLETED, { question, confidence, evidenceCount: evidence.length });
+        return result;
+    }
+    async promoteObservation(observation) {
+        if (!observation.validated) {
+            return null;
+        }
+        if (observation.confidence === undefined || observation.confidence < 0) {
+            throw kag_error_1.KagError.validationError('Validated observations require a confidence score.');
+        }
+        const fact = {
+            id: (0, crypto_1.randomUUID)(),
+            subject: observation.subject,
+            predicate: observation.predicate,
+            object: observation.object,
+            confidence: observation.confidence,
+            source: observation.source ?? { type: 'memory', id: 'promotion' },
+            validFrom: observation.validFrom,
+            validUntil: observation.validUntil,
+        };
+        await this.fact(fact);
+        return fact;
+    }
+    async changes(from, to) {
+        const result = await this.store.query(this.scope, {});
+        return (0, temporal_1.changesBetween)(result.facts, from, to);
+    }
+    async currentFacts(subject) {
+        const result = await this.store.query(this.scope, {
+            entityIds: subject ? [subject] : undefined,
+            currentOnly: true,
+        });
+        return result.facts.filter((f) => (0, temporal_1.isFactValidAt)(f));
+    }
+    async contribute(request) {
+        if (request.tenantId !== this.scope.tenantId) {
+            throw kag_error_1.KagError.accessDenied('tenant');
+        }
+        const answer = await this.ask(request.query, { explain: true });
+        return {
+            text: answer.answer ?? answer.explanation ?? '',
+            evidence: answer.evidence,
+            fingerprint: `${this.scope.tenantId}:${answer.confidence}:${answer.evidence.length}`,
+        };
+    }
+    emit(event, payload) {
+        this.localEmitter.emit(event, payload);
+        this.externalEmitter?.emit(event, payload);
+    }
+}
+exports.KnowledgeGraph = KnowledgeGraph;
+function formatExplanation(evidence, confidence, template) {
+    const lines = evidence.map((e) => {
+        if (e.relation && e.entity && e.entity2) {
+            return `${e.entity} -[${e.relation}]-> ${e.entity2}`;
+        }
+        if (e.fact) {
+            return (`${e.fact.subject}.${e.fact.predicate} = ${JSON.stringify(e.fact.object)}` +
+                (e.fact.source
+                    ? ` (source: ${e.fact.source.type}${e.fact.source.id ? ':' + e.fact.source.id : ''})`
+                    : ''));
+        }
+        return JSON.stringify(e);
+    });
+    const header = template ? `Template: ${template}\n` : '';
+    return `${header}Evidence path (confidence ${confidence.toFixed(2)}):\n` + lines.join('\n');
+}
+function summarizeEvidence(evidence) {
+    if (evidence.length === 0)
+        return 'No knowledge evidence found.';
+    return evidence
+        .slice(0, 8)
+        .map((e) => {
+        if (e.relation)
+            return `${e.entity} ${e.relation} ${e.entity2}`;
+        if (e.fact)
+            return `${e.fact.subject} ${e.fact.predicate} ${JSON.stringify(e.fact.object)}`;
+        return '';
+    })
+        .filter(Boolean)
+        .join('; ');
+}
+function dedupeSources(sources) {
+    const seen = new Set();
+    const out = [];
+    for (const s of sources) {
+        const key = `${s.type}:${s.id ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(s);
+    }
+    return out;
+}

package/dist/planner/heuristic-query-planner.d.ts

@@ -0,0 +1,36 @@
+import type { KnowledgeEntity, KnowledgeQueryPlanner, KnowledgeScope } from '../types';
+import { type IndustryProfile, type QueryTemplate } from './industry-profiles';
+export interface HeuristicQueryPlannerOptions {
+    /**
+     * Industry / domain profile(s). Defaults to GENERIC_INDUSTRY_PROFILE
+     * (no commerce-specific relation filters).
+     */
+    industry?: IndustryProfile | IndustryProfile[];
+    /** Extra templates layered on top of the industry profile. */
+    templates?: QueryTemplate[];
+    /** Override default BFS depth when no template matches. */
+    defaultDepth?: number;
+}
+/**
+ * V1 planner: seed entities from the question + optional industry templates.
+ *
+ * Core behavior is industry-agnostic. Pass `COMMERCE_INDUSTRY_PROFILE` (or a
+ * custom profile) when your graph uses domain-specific relation types.
+ */
+export declare class HeuristicQueryPlanner implements KnowledgeQueryPlanner {
+    private readonly templates;
+    private readonly defaultDepth;
+    private readonly industryId;
+    constructor(options?: HeuristicQueryPlannerOptions);
+    getIndustryId(): string;
+    plan(question: string, context: {
+        scope: KnowledgeScope;
+        entities: KnowledgeEntity[];
+    }): Promise<{
+        seedIds: string[];
+        depth: number;
+        relationTypes?: string[];
+        template?: string;
+    }>;
+}
+//# sourceMappingURL=heuristic-query-planner.d.ts.map

package/dist/planner/heuristic-query-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heuristic-query-planner.d.ts","sourceRoot":"","sources":["../../src/planner/heuristic-query-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACvF,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IAC/C,8DAA8D;IAC9D,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,qBAAqB;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,GAAE,4BAAiC;IAYtD,aAAa,IAAI,MAAM;IAIjB,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QAAE,KAAK,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,eAAe,EAAE,CAAA;KAAE,GAC9D,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CAuCH"}

package/dist/planner/heuristic-query-planner.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeuristicQueryPlanner = void 0;
+const industry_profiles_1 = require("./industry-profiles");
+/**
+ * V1 planner: seed entities from the question + optional industry templates.
+ *
+ * Core behavior is industry-agnostic. Pass `COMMERCE_INDUSTRY_PROFILE` (or a
+ * custom profile) when your graph uses domain-specific relation types.
+ */
+class HeuristicQueryPlanner {
+    constructor(options = {}) {
+        const industries = normalizeIndustries(options.industry);
+        const fromIndustry = industries.flatMap((p) => p.templates);
+        this.templates = [...fromIndustry, ...(options.templates ?? [])];
+        this.defaultDepth =
+            options.defaultDepth ??
+                industries.map((p) => p.defaultDepth).find((d) => d !== undefined) ??
+                industry_profiles_1.GENERIC_INDUSTRY_PROFILE.defaultDepth ??
+                3;
+        this.industryId = industries.map((p) => p.id).join('+') || 'generic';
+    }
+    getIndustryId() {
+        return this.industryId;
+    }
+    async plan(question, context) {
+        const lower = question.toLowerCase();
+        const seeds = [];
+        for (const entity of context.entities) {
+            const names = [
+                entity.id.toLowerCase(),
+                String(entity.properties.name ?? '').toLowerCase(),
+                ...(entity.aliases ?? []).map((a) => a.toLowerCase()),
+            ].filter(Boolean);
+            for (const name of names) {
+                if (name.length >= 3 && lower.includes(name)) {
+                    seeds.push(entity.id);
+                    break;
+                }
+            }
+        }
+        // Match entity type tokens in the question (domain-agnostic).
+        if (seeds.length === 0) {
+            for (const entity of context.entities) {
+                if (lower.includes(entity.type.toLowerCase())) {
+                    seeds.push(entity.id);
+                }
+            }
+        }
+        const matches = this.templates.filter((t) => t.pattern.test(question));
+        // Prefer domain templates that constrain relation types over generic intents.
+        const template = matches.find((t) => t.relationTypes && t.relationTypes.length > 0) ?? matches[0];
+        return {
+            seedIds: [...new Set(seeds)].slice(0, 20),
+            depth: template?.depth ?? this.defaultDepth,
+            relationTypes: template?.relationTypes,
+            template: template?.name,
+        };
+    }
+}
+exports.HeuristicQueryPlanner = HeuristicQueryPlanner;
+function normalizeIndustries(industry) {
+    if (!industry) {
+        return [industry_profiles_1.GENERIC_INDUSTRY_PROFILE];
+    }
+    return Array.isArray(industry) ? industry : [industry];
+}