@hazeljs/kag 0.0.0-stage → 2.0.10

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @hazeljs/kag
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Entities, facts, and relationships — with provenance you can audit.**
+
+Knowledge-Augmented Generation for HazelJS — typed knowledge graphs, time-scoped facts, contradictions, and explainable multi-hop reasoning. Use when the question is “why did X change?” over structured domain state, not “which PDF page mentions X?”
+
+KAG does **not** duplicate GraphRAG internals. Import document-derived graphs via `importGraph()`; community detection and vector search stay in `@hazeljs/rag`.
+
+[![npm version](https://img.shields.io/npm/v/@hazeljs/kag.svg)](https://www.npmjs.com/package/@hazeljs/kag)
+[![npm downloads](https://img.shields.io/npm/dm/@hazeljs/kag)](https://www.npmjs.com/package/@hazeljs/kag)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+## KAG vs RAG
+
+|          | KAG                                                | RAG                         |
+| -------- | -------------------------------------------------- | --------------------------- |
+| Question | What entities, facts, and relationships do I know? | What passages are relevant? |
+| Unit     | Entity / relation / fact                           | Document chunk              |
+| Strength | Multi-hop structured reasoning                     | Semantic similarity         |
+
+## Features
+
+- **Typed primitives** — `KnowledgeEntity` / `KnowledgeRelation` / `KnowledgeFact` with confidence + provenance
+- **Tenant-partitioned store** — `InMemoryKnowledgeStore` (Neo4j/Postgres via `KnowledgeStore` ports later)
+- **Entity resolution** — `exact` / `normalized` / `semantic` / `custom`; no auto-merge below threshold
+- **Temporal + contradictions** — `asOf`, ranked conflicts, policy `keep` | `rank` | `reject`
+- **Industry-pluggable planner** — generic by default; opt in with `COMMERCE_INDUSTRY_PROFILE` (or your own)
+- **Explainable answers** — `ask({ explain: true })` returns evidence paths (not model CoT)
+- **Agent OS port** — inject as `AgentRuntimeConfig.kagService`; DNA may declare `context.kag.enabled`
+
+## Installation
+
+```bash
+npm install @hazeljs/kag @hazeljs/core
+```
+
+## Quick Start
+
+```typescript
+import { KnowledgeGraph, COMMERCE_INDUSTRY_PROFILE } from '@hazeljs/kag';
+
+const knowledge = new KnowledgeGraph({
+  tenantId: 'merchant-123',
+  graph: 'commerce',
+  industry: COMMERCE_INDUSTRY_PROFILE, // opt-in commerce vocabulary
+});
+
+await knowledge.entity({
+  id: 'merchant-123',
+  type: 'merchant',
+  properties: { name: 'Demo Restaurant' },
+});
+await knowledge.entity({
+  id: 'order-456',
+  type: 'order',
+  properties: { total: 120 },
+});
+await knowledge.relate({
+  from: 'merchant-123',
+  to: 'order-456',
+  type: 'HAS_ORDER',
+});
+
+const result = await knowledge.ask('Why was settlement lower yesterday?', {
+  explain: true,
+});
+// { answer, evidence, sources, confidence, explanation }
+```
+
+## Entities, Relationships, Facts
+
+Typed primitives with optional `confidence`, `source` provenance, and `validFrom` / `validUntil`.
+
+## Entity Resolution
+
+`EntityResolver` strategies: `exact`, `normalized`, `semantic` (when embed is provided), `custom`. Uncertain matches stay as candidates below `mergeThreshold` (default 0.9).
+
+## Temporal Knowledge, Confidence, Contradictions
+
+- Query with `asOf` or `currentFacts()` / `changes(from, to)`
+- Path confidence aggregates with `min` (default) or `product`
+- Contradictions are retained; ranked by authority → timestamp → confidence → priority
+- Policy `reject` throws `KnowledgeConflictError`
+
+## Knowledge Queries & RAG Integration
+
+`HeuristicQueryPlanner` is industry-agnostic by default (generic causal/temporal/comparison intents). Opt into a domain with `industry: COMMERCE_INDUSTRY_PROFILE` (or your own `IndustryProfile`). Pass `{ rag: true }` with an injected `KnowledgeRetriever` to fuse document passages.
+
+## Memory Integration
+
+`promoteObservation({ validated: true, confidence })` is explicit. No automatic promotion from `@hazeljs/memory`.
+
+## Agent Integration
+
+Inject `KagService` as `AgentRuntimeConfig.kagService`. DNA may declare `context.kag.enabled`.
+
+## Security
+
+Every store call requires `KnowledgeScope.tenantId`. Optional `KnowledgeAuthorizer` or `createCaslKnowledgeAuthorizer(can)`.
+
+## Production Guide
+
+- Start with `InMemoryKnowledgeStore`; design against `KnowledgeStore` for Neo4j/Postgres later
+- Always set tenant scope; add authorizer for entity-level access
+- Prefer `explain: true` for enterprise audit trails (evidence, not model CoT)
+
+## Related
+
+- Docs: [hazeljs.ai/docs/packages/kag](https://hazeljs.ai/docs/packages/kag)
+- Blog: [RAG vs CAG vs KAG](https://hazeljs.ai/blog/rag-vs-cag-vs-kag)
+- Lab: [meridian-ops `example:kag`](https://github.com/hazel-js/hazeljs-meridian-ops/tree/main/examples/kag-commerce-agent)
+- `@hazeljs/rag` — GraphRAG import source + document retrieval
+- `@hazeljs/cag` — stable cached context
+- `@hazeljs/context` — unified planner
+- `@hazeljs/memory` — user continuity (promote explicitly)
+
+## License
+
+Apache 2.0 © [HazelJS](https://hazeljs.ai)
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.

package/dist/adapters/graphrag.adapter.d.ts

@@ -0,0 +1,47 @@
+import type { KnowledgeEntity, KnowledgeExtractor, KnowledgeRelation, KnowledgeScope } from '../types';
+import type { KnowledgeGraph } from '../knowledge-graph';
+/**
+ * Minimal GraphRAG-like shapes so KAG can import without a hard dependency
+ * on @hazeljs/rag at compile time.
+ */
+export interface GraphRagEntityLike {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    sourceDocIds?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface GraphRagRelationshipLike {
+    id: string;
+    sourceId: string;
+    targetId: string;
+    type: string;
+    description?: string;
+    weight?: number;
+    sourceDocIds?: string[];
+}
+export interface GraphStoreLike {
+    entities?: Map<string, GraphRagEntityLike> | GraphRagEntityLike[];
+    relationships?: Map<string, GraphRagRelationshipLike> | GraphRagRelationshipLike[];
+    [key: string]: unknown;
+}
+/**
+ * Map GraphRAG entities/relations into KAG writes.
+ */
+export declare function importGraph(graph: KnowledgeGraph, graphStore: GraphStoreLike, _scope?: KnowledgeScope): Promise<{
+    entities: number;
+    relations: number;
+}>;
+/**
+ * Maps a GraphRAG-style extraction result into KAG write shapes.
+ */
+export declare function mapExtractionResult(result: {
+    entities?: GraphRagEntityLike[];
+    relationships?: GraphRagRelationshipLike[];
+}): {
+    entities: KnowledgeEntity[];
+    relations: KnowledgeRelation[];
+};
+export declare function createExtractionMapper(extract: KnowledgeExtractor['extract']): KnowledgeExtractor;
+//# sourceMappingURL=graphrag.adapter.d.ts.map

package/dist/adapters/graphrag.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphrag.adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/graphrag.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAElB,iBAAiB,EACjB,cAAc,EACf,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,kBAAkB,EAAE,CAAC;IAClE,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,wBAAwB,EAAE,CAAC;IAEnF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAQD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,cAAc,EAC1B,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAwDlD;AAqBD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C,GAAG;IACF,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC,CAkBA;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,GAAG,kBAAkB,CAejG"}

package/dist/adapters/graphrag.adapter.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importGraph = importGraph;
+exports.mapExtractionResult = mapExtractionResult;
+exports.createExtractionMapper = createExtractionMapper;
+function asList(value) {
+    if (!value)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    return [...value.values()];
+}
+/**
+ * Map GraphRAG entities/relations into KAG writes.
+ */
+async function importGraph(graph, graphStore, _scope) {
+    // Prefer public getters if present (GraphStore)
+    const entities = typeof graphStore.getStats === 'function'
+        ? extractEntitiesFromStore(graphStore)
+        : asList(graphStore.entities);
+    const relationships = typeof graphStore.getStats === 'function'
+        ? extractRelationsFromStore(graphStore)
+        : asList(graphStore.relationships);
+    let entityCount = 0;
+    for (const e of entities) {
+        await graph.entity({
+            id: e.id,
+            type: e.type || 'OTHER',
+            properties: {
+                name: e.name,
+                description: e.description ?? '',
+            },
+            metadata: {
+                ...e.metadata,
+                graphRagId: e.id,
+                sourceDocIds: e.sourceDocIds,
+            },
+        });
+        entityCount++;
+    }
+    let relationCount = 0;
+    for (const r of relationships) {
+        await graph.relate({
+            id: r.id,
+            from: r.sourceId,
+            to: r.targetId,
+            type: r.type,
+            properties: {
+                description: r.description,
+                weight: r.weight,
+                sourceDocIds: r.sourceDocIds,
+            },
+            confidence: r.weight !== undefined ? Math.min(1, r.weight / 10) : 0.8,
+            source: { type: 'graphrag', id: r.id, authority: 50 },
+        });
+        relationCount++;
+    }
+    return { entities: entityCount, relations: relationCount };
+}
+function extractEntitiesFromStore(store) {
+    // GraphStore keeps private maps; support toJSON() if available
+    const maybeJson = store.toJSON?.();
+    if (maybeJson?.entities)
+        return maybeJson.entities;
+    if (store.entities)
+        return asList(store.entities);
+    return [];
+}
+function extractRelationsFromStore(store) {
+    const maybeJson = store.toJSON?.();
+    if (maybeJson?.relationships)
+        return maybeJson.relationships;
+    if (store.relationships) {
+        return asList(store.relationships);
+    }
+    return [];
+}
+/**
+ * Maps a GraphRAG-style extraction result into KAG write shapes.
+ */
+function mapExtractionResult(result) {
+    return {
+        entities: (result.entities ?? []).map((e) => ({
+            id: e.id,
+            type: e.type || 'OTHER',
+            properties: { name: e.name, description: e.description ?? '' },
+            metadata: { graphRagId: e.id, sourceDocIds: e.sourceDocIds, ...e.metadata },
+        })),
+        relations: (result.relationships ?? []).map((r) => ({
+            id: r.id,
+            from: r.sourceId,
+            to: r.targetId,
+            type: r.type,
+            properties: { description: r.description, weight: r.weight },
+            confidence: r.weight !== undefined ? Math.min(1, r.weight / 10) : 0.8,
+            source: { type: 'graphrag', id: r.id },
+        })),
+    };
+}
+function createExtractionMapper(extract) {
+    return {
+        async extract(input) {
+            const raw = await extract(input);
+            return {
+                entities: raw.entities,
+                relations: raw.relations,
+                facts: raw.facts,
+            };
+        },
+    };
+}

package/dist/confidence.d.ts

@@ -0,0 +1,7 @@
+import type { ConfidenceAggregation, KnowledgeFact } from './types';
+export declare function aggregateConfidence(values: number[], mode?: ConfidenceAggregation): number;
+/**
+ * Rank conflicting facts: source authority → timestamp → confidence → priority.
+ */
+export declare function rankFacts(facts: KnowledgeFact[]): KnowledgeFact[];
+//# sourceMappingURL=confidence.d.ts.map

package/dist/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../src/confidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGpE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,qBAA6B,GAAG,MAAM,CAMjG;AAOD;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAkBjE"}

package/dist/confidence.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregateConfidence = aggregateConfidence;
+exports.rankFacts = rankFacts;
+const temporal_1 = require("./temporal");
+function aggregateConfidence(values, mode = 'min') {
+    if (values.length === 0)
+        return 1;
+    if (mode === 'product') {
+        return values.reduce((acc, v) => acc * clamp01(v), 1);
+    }
+    return Math.min(...values.map(clamp01));
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+/**
+ * Rank conflicting facts: source authority → timestamp → confidence → priority.
+ */
+function rankFacts(facts) {
+    return [...facts].sort((a, b) => {
+        const authA = a.source?.authority ?? 0;
+        const authB = b.source?.authority ?? 0;
+        if (authB !== authA)
+            return authB - authA;
+        const timeA = (0, temporal_1.toDate)(a.createdAt)?.getTime() ?? (0, temporal_1.toDate)(a.validFrom)?.getTime() ?? 0;
+        const timeB = (0, temporal_1.toDate)(b.createdAt)?.getTime() ?? (0, temporal_1.toDate)(b.validFrom)?.getTime() ?? 0;
+        if (timeB !== timeA)
+            return timeB - timeA;
+        const confA = a.confidence ?? 0;
+        const confB = b.confidence ?? 0;
+        if (confB !== confA)
+            return confB - confA;
+        const priA = a.priority ?? a.source?.priority ?? 0;
+        const priB = b.priority ?? b.source?.priority ?? 0;
+        return priB - priA;
+    });
+}

package/dist/errors/kag.error.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Structured KAG errors for robust handling and observability.
+ */
+export declare enum KagErrorCode {
+    ENTITY_NOT_FOUND = "KAG_ENTITY_NOT_FOUND",
+    STORE_ERROR = "KAG_STORE_ERROR",
+    CONFLICT = "KAG_CONFLICT",
+    ACCESS_DENIED = "KAG_ACCESS_DENIED",
+    TENANT_REQUIRED = "KAG_TENANT_REQUIRED",
+    VALIDATION_ERROR = "KAG_VALIDATION_ERROR",
+    CONFIGURATION_ERROR = "KAG_CONFIGURATION_ERROR"
+}
+export declare class KagError extends Error {
+    readonly code: KagErrorCode;
+    readonly cause?: Error;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: KagErrorCode, cause?: Error, details?: Record<string, unknown>);
+    static entityNotFound(id: string): KagError;
+    static storeError(message: string, cause?: Error): KagError;
+    static conflict(message: string, details?: Record<string, unknown>): KagError;
+    static accessDenied(resource: string): KagError;
+    static tenantRequired(): KagError;
+    static validationError(message: string): KagError;
+    static configurationError(message: string): KagError;
+}
+/** @deprecated Prefer KagError */
+export declare class KnowledgeEntityNotFoundError extends KagError {
+    constructor(id: string);
+}
+/** @deprecated Prefer KagError */
+export declare class KnowledgeStoreError extends KagError {
+    constructor(message: string, cause?: Error);
+}
+/** @deprecated Prefer KagError */
+export declare class KnowledgeConflictError extends KagError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** @deprecated Prefer KagError */
+export declare class KnowledgeAccessDeniedError extends KagError {
+    constructor(resource: string);
+}
+//# sourceMappingURL=kag.error.d.ts.map

package/dist/errors/kag.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kag.error.d.ts","sourceRoot":"","sources":["../../src/errors/kag.error.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oBAAY,YAAY;IACtB,gBAAgB,yBAAyB;IACzC,WAAW,oBAAoB;IAC/B,QAAQ,iBAAiB;IACzB,aAAa,sBAAsB;IACnC,eAAe,wBAAwB;IACvC,gBAAgB,yBAAyB;IACzC,mBAAmB,4BAA4B;CAChD;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,EAClB,KAAK,CAAC,EAAE,KAAK,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUnC,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ;IAO3C,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ;IAI3D,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ;IAI7E,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ;IAO/C,MAAM,CAAC,cAAc,IAAI,QAAQ;IAOjC,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;IAIjD,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;CAGrD;AAED,kCAAkC;AAClC,qBAAa,4BAA6B,SAAQ,QAAQ;gBAC5C,EAAE,EAAE,MAAM;CAIvB;AAED,kCAAkC;AAClC,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI3C;AAED,kCAAkC;AAClC,qBAAa,sBAAuB,SAAQ,QAAQ;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,kCAAkC;AAClC,qBAAa,0BAA2B,SAAQ,QAAQ;gBAC1C,QAAQ,EAAE,MAAM;CAI7B"}

package/dist/errors/kag.error.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Structured KAG errors for robust handling and observability.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeAccessDeniedError = exports.KnowledgeConflictError = exports.KnowledgeStoreError = exports.KnowledgeEntityNotFoundError = exports.KagError = exports.KagErrorCode = void 0;
+var KagErrorCode;
+(function (KagErrorCode) {
+    KagErrorCode["ENTITY_NOT_FOUND"] = "KAG_ENTITY_NOT_FOUND";
+    KagErrorCode["STORE_ERROR"] = "KAG_STORE_ERROR";
+    KagErrorCode["CONFLICT"] = "KAG_CONFLICT";
+    KagErrorCode["ACCESS_DENIED"] = "KAG_ACCESS_DENIED";
+    KagErrorCode["TENANT_REQUIRED"] = "KAG_TENANT_REQUIRED";
+    KagErrorCode["VALIDATION_ERROR"] = "KAG_VALIDATION_ERROR";
+    KagErrorCode["CONFIGURATION_ERROR"] = "KAG_CONFIGURATION_ERROR";
+})(KagErrorCode || (exports.KagErrorCode = KagErrorCode = {}));
+class KagError extends Error {
+    constructor(message, code, cause, details) {
+        super(message);
+        this.name = 'KagError';
+        this.code = code;
+        this.cause = cause;
+        this.details = details;
+        Object.setPrototypeOf(this, KagError.prototype);
+    }
+    static entityNotFound(id) {
+        return new KagError(`Knowledge entity "${id}" was not found in the current tenant scope.`, KagErrorCode.ENTITY_NOT_FOUND);
+    }
+    static storeError(message, cause) {
+        return new KagError(message, KagErrorCode.STORE_ERROR, cause);
+    }
+    static conflict(message, details) {
+        return new KagError(message, KagErrorCode.CONFLICT, undefined, details);
+    }
+    static accessDenied(resource) {
+        return new KagError(`Access denied for knowledge resource "${resource}".`, KagErrorCode.ACCESS_DENIED);
+    }
+    static tenantRequired() {
+        return new KagError('tenantId is required for knowledge operations. Pass a KnowledgeScope with tenantId.', KagErrorCode.TENANT_REQUIRED);
+    }
+    static validationError(message) {
+        return new KagError(message, KagErrorCode.VALIDATION_ERROR);
+    }
+    static configurationError(message) {
+        return new KagError(message, KagErrorCode.CONFIGURATION_ERROR);
+    }
+}
+exports.KagError = KagError;
+/** @deprecated Prefer KagError */
+class KnowledgeEntityNotFoundError extends KagError {
+    constructor(id) {
+        super(KagError.entityNotFound(id).message, KagErrorCode.ENTITY_NOT_FOUND);
+        this.name = 'KnowledgeEntityNotFoundError';
+    }
+}
+exports.KnowledgeEntityNotFoundError = KnowledgeEntityNotFoundError;
+/** @deprecated Prefer KagError */
+class KnowledgeStoreError extends KagError {
+    constructor(message, cause) {
+        super(message, KagErrorCode.STORE_ERROR, cause);
+        this.name = 'KnowledgeStoreError';
+    }
+}
+exports.KnowledgeStoreError = KnowledgeStoreError;
+/** @deprecated Prefer KagError */
+class KnowledgeConflictError extends KagError {
+    constructor(message, details) {
+        super(message, KagErrorCode.CONFLICT, undefined, details);
+        this.name = 'KnowledgeConflictError';
+    }
+}
+exports.KnowledgeConflictError = KnowledgeConflictError;
+/** @deprecated Prefer KagError */
+class KnowledgeAccessDeniedError extends KagError {
+    constructor(resource) {
+        super(KagError.accessDenied(resource).message, KagErrorCode.ACCESS_DENIED);
+        this.name = 'KnowledgeAccessDeniedError';
+    }
+}
+exports.KnowledgeAccessDeniedError = KnowledgeAccessDeniedError;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './types';
+export * from './errors/kag.error';
+export * from './kag.module';
+export * from './kag.service';
+export * from './knowledge-graph';
+export * from './stores/in-memory-knowledge.store';
+export * from './resolution/entity-resolver';
+export * from './planner/heuristic-query-planner';
+export * from './planner/industry-profiles';
+export * from './security/authorizer';
+export * from './ingestion/ingest';
+export * from './adapters/graphrag.adapter';
+export * from './temporal';
+export * from './confidence';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./errors/kag.error"), exports);
+__exportStar(require("./kag.module"), exports);
+__exportStar(require("./kag.service"), exports);
+__exportStar(require("./knowledge-graph"), exports);
+__exportStar(require("./stores/in-memory-knowledge.store"), exports);
+__exportStar(require("./resolution/entity-resolver"), exports);
+__exportStar(require("./planner/heuristic-query-planner"), exports);
+__exportStar(require("./planner/industry-profiles"), exports);
+__exportStar(require("./security/authorizer"), exports);
+__exportStar(require("./ingestion/ingest"), exports);
+__exportStar(require("./adapters/graphrag.adapter"), exports);
+__exportStar(require("./temporal"), exports);
+__exportStar(require("./confidence"), exports);

package/dist/ingestion/ingest.d.ts

@@ -0,0 +1,24 @@
+import type { KnowledgeEntity, KnowledgeExtractor, KnowledgeFact, KnowledgeRelation } from '../types';
+import type { KnowledgeGraph } from '../knowledge-graph';
+import { EntityResolver } from '../resolution/entity-resolver';
+export interface IngestBatch {
+    entities?: KnowledgeEntity[];
+    relations?: KnowledgeRelation[];
+    facts?: KnowledgeFact[];
+}
+export interface IngestResult {
+    entities: number;
+    relations: number;
+    facts: number;
+    unresolvedCandidates: number;
+}
+/**
+ * Ingestion pipeline: extract → resolve → dedupe → validate → write.
+ * Uncertain entity matches are not merged.
+ */
+export declare function ingestKnowledge(graph: KnowledgeGraph, batch: IngestBatch, options?: {
+    extractor?: KnowledgeExtractor;
+    raw?: unknown;
+    resolver?: EntityResolver;
+}): Promise<IngestResult>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/ingestion/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/ingestion/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,GACA,OAAO,CAAC,YAAY,CAAC,CAwDvB"}

package/dist/ingestion/ingest.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ingestKnowledge = ingestKnowledge;
+/**
+ * Ingestion pipeline: extract → resolve → dedupe → validate → write.
+ * Uncertain entity matches are not merged.
+ */
+async function ingestKnowledge(graph, batch, options) {
+    let entities = batch.entities ?? [];
+    let relations = batch.relations ?? [];
+    let facts = batch.facts ?? [];
+    if (options?.extractor && options.raw !== undefined) {
+        const extracted = await options.extractor.extract(options.raw);
+        entities = [...entities, ...extracted.entities];
+        relations = [...relations, ...extracted.relations];
+        facts = [...facts, ...(extracted.facts ?? [])];
+    }
+    // Deduplicate entities by id
+    const entityById = new Map();
+    for (const e of entities) {
+        entityById.set(e.id, e);
+    }
+    let unresolvedCandidates = 0;
+    for (const entity of entityById.values()) {
+        const resolution = await graph.resolve(entity);
+        if (resolution.merged) {
+            await graph.entity(resolution.merged);
+        }
+        else {
+            if (resolution.candidates.length > 0) {
+                unresolvedCandidates += resolution.candidates.length;
+            }
+            await graph.entity(entity);
+        }
+    }
+    // Deduplicate relations
+    const relKeys = new Set();
+    let relationCount = 0;
+    for (const rel of relations) {
+        const key = rel.id ?? `${rel.from}:${rel.type}:${rel.to}`;
+        if (relKeys.has(key))
+            continue;
+        relKeys.add(key);
+        await graph.relate(rel);
+        relationCount++;
+    }
+    let factCount = 0;
+    for (const fact of facts) {
+        // Basic validation
+        if (!fact.subject || !fact.predicate)
+            continue;
+        await graph.fact(fact);
+        factCount++;
+    }
+    return {
+        entities: entityById.size,
+        relations: relationCount,
+        facts: factCount,
+        unresolvedCandidates,
+    };
+}

package/dist/kag.module.d.ts

@@ -0,0 +1,29 @@
+import { KagService } from './kag.service';
+import type { KagModuleOptions } from './types';
+export declare class KagModule {
+    static forRoot(options?: KagModuleOptions): {
+        module: typeof KagModule;
+        providers: Array<{
+            provide: string | typeof KagService;
+            useValue?: unknown;
+            useFactory?: (...args: unknown[]) => unknown;
+            inject?: unknown[];
+        }>;
+        exports: Array<typeof KagService | string>;
+        global: boolean;
+    };
+    static forRootAsync(options: {
+        useFactory: (...args: unknown[]) => Promise<KagModuleOptions> | KagModuleOptions;
+        inject?: unknown[];
+    }): {
+        module: typeof KagModule;
+        providers: Array<{
+            provide: string | typeof KagService;
+            useFactory: (...args: unknown[]) => unknown;
+            inject?: unknown[];
+        }>;
+        exports: Array<typeof KagService | string>;
+        global: boolean;
+    };
+}
+//# sourceMappingURL=kag.module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kag.module.d.ts","sourceRoot":"","sources":["../src/kag.module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD,qBAIa,SAAS;IACpB,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,gBAAqB,GAAG;QAC9C,MAAM,EAAE,OAAO,SAAS,CAAC;QACzB,SAAS,EAAE,KAAK,CAAC;YACf,OAAO,EAAE,MAAM,GAAG,OAAO,UAAU,CAAC;YACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;YAC7C,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;SACpB,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,CAAC,OAAO,UAAU,GAAG,MAAM,CAAC,CAAC;QAC3C,MAAM,EAAE,OAAO,CAAC;KACjB;IAcD,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE;QAC3B,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;QACjF,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;KACpB,GAAG;QACF,MAAM,EAAE,OAAO,SAAS,CAAC;QACzB,SAAS,EAAE,KAAK,CAAC;YACf,OAAO,EAAE,MAAM,GAAG,OAAO,UAAU,CAAC;YACpC,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;YAC5C,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;SACpB,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,CAAC,OAAO,UAAU,GAAG,MAAM,CAAC,CAAC;QAC3C,MAAM,EAAE,OAAO,CAAC;KACjB;CAmBF"}