@anvia/graph 0.0.0-bootstrap.0 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Indra Zulfi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
 # @anvia/graph
 
-Bootstrap placeholder. The production package is published from the Anvia release workflow.
+Provider-neutral schema, extraction, retrieval-context, and tool primitives for knowledge graphs.
+
+```ts
+import { defineGraphSchema, extractGraphFacts } from "@anvia/graph";
+import { z } from "zod";
+
+const schema = defineGraphSchema({
+  nodes: {
+    Product: {
+      description: "A product or service.",
+      identity: ["id"],
+      properties: z.strictObject({ id: z.string(), name: z.string() }),
+    },
+  },
+  relationships: {},
+});
+
+const facts = await extractGraphFacts({ model, schema, chunks });
+```
+
+Database provisioning, persistence, and query execution belong to graph adapter packages such as
+`@anvia/neo4j` and `@anvia/memgraph`.
+
+## Ingestion
+
+Managed graphs accept the same raw text document shape as vector ingestion:
+
+```ts
+import { ingestGraphText } from "@anvia/graph";
+
+const ingestion = await ingestGraphText({
+  graph,
+  document: {
+    id: "incident-42",
+    text,
+    metadata: { tenant: "acme" },
+  },
+  extractionModel,
+  embeddingModel,
+  chunking: {
+    strategy: "recursive",
+    maxSize: 1_000,
+    overlap: 100,
+    separators: ["\n\n", "\n", " "],
+  },
+  conflict: "error",
+  orphanEntities: "delete",
+});
+```
+
+Use `ingestGraphDocuments()` for a batch. Both functions extract facts, embed chunks and entities,
+and atomically replace each source document in the managed graph. Existing graph registrations are
+read-only and are rejected as ingestion targets by TypeScript.
+
+The result also exposes `vectorDocuments`, grouped by source document ID, so a vector store can
+reuse the chunk embeddings without another model call:
+
+```ts
+await vectorStore.upsert({ documents: ingestion.vectorDocuments });
+```
+
+The graph and vector writes are separate transactions. Applications that require cross-store
+reconciliation should persist their own ingestion status and retry the incomplete write. Advanced
+callers can use `prepareGraphDocuments()` to run chunking, extraction, and embedding without writing,
+then pass its graph fields to `graph.replaceDocuments()` and its `vectorDocuments` to a vector store.
+
+## Search tool
+
+Create the same Agent tool for any graph adapter implementing `GraphContextRetriever`:
+
+```ts
+import { createGraphSearchTool } from "@anvia/graph";
+
+const searchGraph = createGraphSearchTool({
+  name: "search_graph",
+  description: "Search connected entities and supporting evidence.",
+  graph,
+  model: embeddingModel,
+  search: {
+    type: "vector",
+    seeds: ["entities"],
+    topK: 8,
+  },
+  traversal: {
+    relationships: ["AFFECTS"],
+    direction: "both",
+    maxDepth: 2,
+    maxNodes: 40,
+    maxRelationships: 80,
+  },
+  evidence: { type: "chunks", maxChunks: 12 },
+});
+```
+
+The graph registration controls which evidence modes are valid. Managed graphs can hydrate stored
+chunks, while existing graph registrations use `{ type: "none" }`.
+
+## Exploration
+
+Adapters implementing `GraphExplorer` expose a portable, bounded view for visualization:
+
+```ts
+const overview = await graph.explore({
+  mode: "overview",
+  nodeTypes: ["Product"],
+  maxNodes: 100,
+  maxRelationships: 200,
+});
+
+const neighborhood = await graph.explore({
+  mode: "expand",
+  nodeIds: [overview.nodes[0]!.id],
+  direction: "both",
+  maxDepth: 1,
+});
+```
+
+Explorer IDs are opaque and provider-specific. They are intended for follow-up expansion within the
+same graph, not persistence or cross-provider migration. Adapters cap overview and expansion requests,
+return truncation metadata, and omit reserved Anvia properties such as stored embeddings.

package/dist/chunk-N3CKMOPE.js

@@ -0,0 +1,85 @@
+// src/explore.ts
+var defaultMaxNodes = 100;
+var maximumNodes = 500;
+var defaultMaxRelationships = 200;
+var maximumRelationships = 1e3;
+var defaultMaxDepth = 1;
+var maximumDepth = 4;
+var maximumRoots = 20;
+function resolveGraphExploreOptions(schema, options) {
+  const nodeTypes = resolveNames(options.nodeTypes, Object.keys(schema.nodes), "node type");
+  const relationships = resolveNames(
+    options.relationships,
+    Object.keys(schema.relationships),
+    "relationship type",
+    true
+  );
+  const base = {
+    nodeTypes,
+    relationships,
+    maxNodes: boundedInteger(options.maxNodes, defaultMaxNodes, maximumNodes, "maxNodes"),
+    maxRelationships: boundedInteger(
+      options.maxRelationships,
+      defaultMaxRelationships,
+      maximumRelationships,
+      "maxRelationships"
+    )
+  };
+  if (options.abortSignal !== void 0) base.abortSignal = options.abortSignal;
+  if (options.mode === "overview") {
+    return { ...base, mode: "overview" };
+  }
+  const nodeIds = uniqueNonEmptyStrings(options.nodeIds, "node id");
+  if (nodeIds.length === 0) {
+    throw new TypeError("Graph expansion requires at least one node id.");
+  }
+  if (nodeIds.length > maximumRoots) {
+    throw new RangeError(`Graph expansion accepts at most ${maximumRoots} root nodes.`);
+  }
+  const direction = options.direction ?? "both";
+  if (direction !== "outgoing" && direction !== "incoming" && direction !== "both") {
+    throw new TypeError("Graph expansion direction must be outgoing, incoming, or both.");
+  }
+  return {
+    ...base,
+    mode: "expand",
+    nodeIds,
+    direction,
+    maxDepth: boundedInteger(options.maxDepth, defaultMaxDepth, maximumDepth, "maxDepth")
+  };
+}
+function resolveNames(selected, available, label, allowEmpty = false) {
+  const values = selected === void 0 ? [...available] : uniqueNonEmptyStrings(selected, label);
+  if (!allowEmpty && values.length === 0) {
+    throw new TypeError(`Graph exploration requires at least one ${label}.`);
+  }
+  const known = new Set(available);
+  for (const value of values) {
+    if (!known.has(value))
+      throw new TypeError(`Graph exploration references unknown ${label} ${value}.`);
+  }
+  return values;
+}
+function uniqueNonEmptyStrings(values, label) {
+  const unique = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (typeof value !== "string" || value.length === 0) {
+      throw new TypeError(`Graph ${label} must be a non-empty string.`);
+    }
+    if (unique.has(value)) throw new TypeError(`Duplicate graph ${label}: ${value}.`);
+    unique.add(value);
+  }
+  return [...unique];
+}
+function boundedInteger(value, fallback, maximum, label) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {
+    throw new RangeError(`Graph exploration ${label} must be between 1 and ${maximum}.`);
+  }
+  return resolved;
+}
+
+export {
+  resolveGraphExploreOptions
+};
+//# sourceMappingURL=chunk-N3CKMOPE.js.map

package/dist/chunk-N3CKMOPE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/explore.ts"],"sourcesContent":["import type { GraphExploreDirection, GraphExploreOptions, GraphSchemaLike } from \"./types.js\";\n\nconst defaultMaxNodes = 100;\nconst maximumNodes = 500;\nconst defaultMaxRelationships = 200;\nconst maximumRelationships = 1_000;\nconst defaultMaxDepth = 1;\nconst maximumDepth = 4;\nconst maximumRoots = 20;\n\ntype ResolvedGraphExploreBase = Readonly<{\n  nodeTypes: readonly string[];\n  relationships: readonly string[];\n  maxNodes: number;\n  maxRelationships: number;\n  abortSignal?: AbortSignal | undefined;\n}>;\n\nexport type ResolvedGraphExploreOverviewOptions = ResolvedGraphExploreBase &\n  Readonly<{ mode: \"overview\" }>;\n\nexport type ResolvedGraphExploreExpandOptions = ResolvedGraphExploreBase &\n  Readonly<{\n    mode: \"expand\";\n    nodeIds: readonly string[];\n    direction: GraphExploreDirection;\n    maxDepth: number;\n  }>;\n\nexport type ResolvedGraphExploreOptions =\n  | ResolvedGraphExploreOverviewOptions\n  | ResolvedGraphExploreExpandOptions;\n\nexport function resolveGraphExploreOptions<Schema extends GraphSchemaLike>(\n  schema: Schema,\n  options: GraphExploreOptions<Schema>,\n): ResolvedGraphExploreOptions {\n  const nodeTypes = resolveNames(options.nodeTypes, Object.keys(schema.nodes), \"node type\");\n  const relationships = resolveNames(\n    options.relationships,\n    Object.keys(schema.relationships),\n    \"relationship type\",\n    true,\n  );\n  const base: {\n    nodeTypes: string[];\n    relationships: string[];\n    maxNodes: number;\n    maxRelationships: number;\n    abortSignal?: AbortSignal | undefined;\n  } = {\n    nodeTypes,\n    relationships,\n    maxNodes: boundedInteger(options.maxNodes, defaultMaxNodes, maximumNodes, \"maxNodes\"),\n    maxRelationships: boundedInteger(\n      options.maxRelationships,\n      defaultMaxRelationships,\n      maximumRelationships,\n      \"maxRelationships\",\n    ),\n  };\n  if (options.abortSignal !== undefined) base.abortSignal = options.abortSignal;\n  if (options.mode === \"overview\") {\n    return { ...base, mode: \"overview\" };\n  }\n  const nodeIds = uniqueNonEmptyStrings(options.nodeIds, \"node id\");\n  if (nodeIds.length === 0) {\n    throw new TypeError(\"Graph expansion requires at least one node id.\");\n  }\n  if (nodeIds.length > maximumRoots) {\n    throw new RangeError(`Graph expansion accepts at most ${maximumRoots} root nodes.`);\n  }\n  const direction = options.direction ?? \"both\";\n  if (direction !== \"outgoing\" && direction !== \"incoming\" && direction !== \"both\") {\n    throw new TypeError(\"Graph expansion direction must be outgoing, incoming, or both.\");\n  }\n  return {\n    ...base,\n    mode: \"expand\",\n    nodeIds,\n    direction,\n    maxDepth: boundedInteger(options.maxDepth, defaultMaxDepth, maximumDepth, \"maxDepth\"),\n  };\n}\n\nfunction resolveNames(\n  selected: readonly string[] | undefined,\n  available: readonly string[],\n  label: string,\n  allowEmpty = false,\n): string[] {\n  const values = selected === undefined ? [...available] : uniqueNonEmptyStrings(selected, label);\n  if (!allowEmpty && values.length === 0) {\n    throw new TypeError(`Graph exploration requires at least one ${label}.`);\n  }\n  const known = new Set(available);\n  for (const value of values) {\n    if (!known.has(value))\n      throw new TypeError(`Graph exploration references unknown ${label} ${value}.`);\n  }\n  return values;\n}\n\nfunction uniqueNonEmptyStrings(values: readonly string[], label: string): string[] {\n  const unique = new Set<string>();\n  for (const value of values) {\n    if (typeof value !== \"string\" || value.length === 0) {\n      throw new TypeError(`Graph ${label} must be a non-empty string.`);\n    }\n    if (unique.has(value)) throw new TypeError(`Duplicate graph ${label}: ${value}.`);\n    unique.add(value);\n  }\n  return [...unique];\n}\n\nfunction boundedInteger(\n  value: number | undefined,\n  fallback: number,\n  maximum: number,\n  label: string,\n): number {\n  const resolved = value ?? fallback;\n  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {\n    throw new RangeError(`Graph exploration ${label} must be between 1 and ${maximum}.`);\n  }\n  return resolved;\n}\n"],"mappings":";AAEA,IAAM,kBAAkB;AACxB,IAAM,eAAe;AACrB,IAAM,0BAA0B;AAChC,IAAM,uBAAuB;AAC7B,IAAM,kBAAkB;AACxB,IAAM,eAAe;AACrB,IAAM,eAAe;AAyBd,SAAS,2BACd,QACA,SAC6B;AAC7B,QAAM,YAAY,aAAa,QAAQ,WAAW,OAAO,KAAK,OAAO,KAAK,GAAG,WAAW;AACxF,QAAM,gBAAgB;AAAA,IACpB,QAAQ;AAAA,IACR,OAAO,KAAK,OAAO,aAAa;AAAA,IAChC;AAAA,IACA;AAAA,EACF;AACA,QAAM,OAMF;AAAA,IACF;AAAA,IACA;AAAA,IACA,UAAU,eAAe,QAAQ,UAAU,iBAAiB,cAAc,UAAU;AAAA,IACpF,kBAAkB;AAAA,MAChB,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,MAAI,QAAQ,gBAAgB,OAAW,MAAK,cAAc,QAAQ;AAClE,MAAI,QAAQ,SAAS,YAAY;AAC/B,WAAO,EAAE,GAAG,MAAM,MAAM,WAAW;AAAA,EACrC;AACA,QAAM,UAAU,sBAAsB,QAAQ,SAAS,SAAS;AAChE,MAAI,QAAQ,WAAW,GAAG;AACxB,UAAM,IAAI,UAAU,gDAAgD;AAAA,EACtE;AACA,MAAI,QAAQ,SAAS,cAAc;AACjC,UAAM,IAAI,WAAW,mCAAmC,YAAY,cAAc;AAAA,EACpF;AACA,QAAM,YAAY,QAAQ,aAAa;AACvC,MAAI,cAAc,cAAc,cAAc,cAAc,cAAc,QAAQ;AAChF,UAAM,IAAI,UAAU,gEAAgE;AAAA,EACtF;AACA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,MAAM;AAAA,IACN;AAAA,IACA;AAAA,IACA,UAAU,eAAe,QAAQ,UAAU,iBAAiB,cAAc,UAAU;AAAA,EACtF;AACF;AAEA,SAAS,aACP,UACA,WACA,OACA,aAAa,OACH;AACV,QAAM,SAAS,aAAa,SAAY,CAAC,GAAG,SAAS,IAAI,sBAAsB,UAAU,KAAK;AAC9F,MAAI,CAAC,cAAc,OAAO,WAAW,GAAG;AACtC,UAAM,IAAI,UAAU,2CAA2C,KAAK,GAAG;AAAA,EACzE;AACA,QAAM,QAAQ,IAAI,IAAI,SAAS;AAC/B,aAAW,SAAS,QAAQ;AAC1B,QAAI,CAAC,MAAM,IAAI,KAAK;AAClB,YAAM,IAAI,UAAU,wCAAwC,KAAK,IAAI,KAAK,GAAG;AAAA,EACjF;AACA,SAAO;AACT;AAEA,SAAS,sBAAsB,QAA2B,OAAyB;AACjF,QAAM,SAAS,oBAAI,IAAY;AAC/B,aAAW,SAAS,QAAQ;AAC1B,QAAI,OAAO,UAAU,YAAY,MAAM,WAAW,GAAG;AACnD,YAAM,IAAI,UAAU,SAAS,KAAK,8BAA8B;AAAA,IAClE;AACA,QAAI,OAAO,IAAI,KAAK,EAAG,OAAM,IAAI,UAAU,mBAAmB,KAAK,KAAK,KAAK,GAAG;AAChF,WAAO,IAAI,KAAK;AAAA,EAClB;AACA,SAAO,CAAC,GAAG,MAAM;AACnB;AAEA,SAAS,eACP,OACA,UACA,SACA,OACQ;AACR,QAAM,WAAW,SAAS;AAC1B,MAAI,CAAC,OAAO,cAAc,QAAQ,KAAK,WAAW,KAAK,WAAW,SAAS;AACzE,UAAM,IAAI,WAAW,qBAAqB,KAAK,0BAA0B,OAAO,GAAG;AAAA,EACrF;AACA,SAAO;AACT;","names":[]}

package/dist/explore-9jm2c1mG.d.ts

@@ -0,0 +1,277 @@
+import { RetrySetting, CompletionModel, Usage } from '@anvia/core';
+import { EmbeddingModel, EmbeddedDocument } from '@anvia/core/embeddings';
+import { Tool } from '@anvia/core/tool';
+import { z } from 'zod';
+
+type GraphPropertyPrimitive = string | number | boolean;
+type GraphPropertyValue = GraphPropertyPrimitive | readonly string[] | readonly number[] | readonly boolean[];
+type GraphProperties = Readonly<Record<string, GraphPropertyValue>>;
+type GraphNodeIdentity = Readonly<Record<string, GraphPropertyPrimitive>>;
+type GraphNodeDefinition = Readonly<{
+    description: string;
+    identity: readonly string[];
+    properties: z.ZodObject<z.ZodRawShape>;
+}>;
+type GraphRelationshipDefinition = Readonly<{
+    description: string;
+    from: string;
+    to: string;
+    identity?: readonly string[] | undefined;
+    properties: z.ZodObject<z.ZodRawShape>;
+}>;
+type GraphSchemaOptions = Readonly<{
+    nodes: Readonly<Record<string, GraphNodeDefinition>>;
+    relationships: Readonly<Record<string, GraphRelationshipDefinition>>;
+}>;
+type GraphSchema<Options extends GraphSchemaOptions = GraphSchemaOptions> = Readonly<Options & {
+    kind: "graph-schema";
+}>;
+type GraphSchemaLike<Options extends GraphSchemaOptions = GraphSchemaOptions> = Readonly<Options & {
+    kind: string;
+}>;
+type NodeDefinitions<Schema extends GraphSchemaLike> = Schema["nodes"];
+type RelationshipDefinitions<Schema extends GraphSchemaLike> = Schema["relationships"];
+type GraphEntity<Schema extends GraphSchemaLike = GraphSchemaLike> = {
+    [Type in keyof NodeDefinitions<Schema> & string]: Readonly<{
+        key: string;
+        type: Type;
+        identity: GraphNodeIdentity;
+        properties: z.output<NodeDefinitions<Schema>[Type]["properties"]> & GraphProperties;
+        sourceChunkIds: readonly string[];
+    }>;
+}[keyof NodeDefinitions<Schema> & string];
+type GraphRelationship<Schema extends GraphSchemaLike = GraphSchemaLike> = {
+    [Type in keyof RelationshipDefinitions<Schema> & string]: Readonly<{
+        key: string;
+        type: Type;
+        from: string;
+        to: string;
+        properties: z.output<RelationshipDefinitions<Schema>[Type]["properties"]> & GraphProperties;
+        sourceChunkIds: readonly string[];
+    }>;
+}[keyof RelationshipDefinitions<Schema> & string];
+type GraphMention = Readonly<{
+    chunkId: string;
+    entityKey: string;
+}>;
+type GraphFacts<Schema extends GraphSchemaLike = GraphSchemaLike> = Readonly<{
+    entities: readonly GraphEntity<Schema>[];
+    relationships: readonly GraphRelationship<Schema>[];
+    mentions: readonly GraphMention[];
+}>;
+type GraphChunk<Metadata extends GraphProperties = GraphProperties> = Readonly<{
+    id: string;
+    documentId: string;
+    index: number;
+    text: string;
+    metadata?: Metadata | undefined;
+}>;
+type GraphDocument<Properties extends GraphProperties = GraphProperties> = Readonly<{
+    id: string;
+    properties?: Properties | undefined;
+}>;
+type ExtractGraphFactsOptions<Schema extends GraphSchemaLike, Model extends CompletionModel> = Readonly<{
+    model: Model;
+    schema: Schema;
+    chunks: readonly GraphChunk[];
+    instructions?: string | undefined;
+    retries?: RetrySetting | undefined;
+    concurrency?: number | undefined;
+    abortSignal?: AbortSignal | undefined;
+}>;
+type ExtractGraphFactsResult<Schema extends GraphSchemaLike> = Readonly<{
+    output: GraphFacts<Schema>;
+    usage: Usage;
+}>;
+type GraphVectorSearchOptions = Readonly<{
+    type: "vector";
+    seeds: readonly string[];
+    topK: number;
+    minScore?: number | undefined;
+}>;
+type GraphHybridSearchOptions = Readonly<{
+    type: "hybrid";
+    seeds: readonly string[];
+    topK: number;
+    candidatesPerSeed: number;
+    rrfK: number;
+}>;
+type GraphSearchOptions = GraphVectorSearchOptions | GraphHybridSearchOptions;
+type GraphEvidenceOptions = Readonly<{
+    type: "none";
+}> | Readonly<{
+    type: "chunks";
+    maxChunks: number;
+}>;
+type GraphTraversalOptions<Schema extends GraphSchemaLike = GraphSchemaLike> = Readonly<{
+    relationships: readonly (keyof Schema["relationships"] & string)[];
+    direction: "outgoing" | "incoming" | "both";
+    maxDepth: number;
+    maxNodes: number;
+    maxRelationships: number;
+}>;
+type GraphContextSeed = Readonly<{
+    key: string;
+    type: string;
+    score: number;
+    properties: GraphProperties;
+    sourceChunkIds: readonly string[];
+}>;
+type GraphContextNode = Readonly<{
+    key: string;
+    type: string;
+    identity: GraphNodeIdentity;
+    properties: GraphProperties;
+    sourceChunkIds: readonly string[];
+}>;
+type GraphContextRelationship = Readonly<{
+    key: string;
+    type: string;
+    from: string;
+    to: string;
+    properties: GraphProperties;
+    sourceChunkIds: readonly string[];
+}>;
+type GraphEvidence = Readonly<{
+    chunkId: string;
+    documentId: string;
+    index: number;
+    text: string;
+    metadata: GraphProperties;
+}>;
+type GraphContext = Readonly<{
+    seeds: readonly GraphContextSeed[];
+    nodes: readonly GraphContextNode[];
+    relationships: readonly GraphContextRelationship[];
+    evidence: readonly GraphEvidence[];
+}>;
+type GraphEvidenceCapability = "none" | "chunks";
+type GraphEvidenceFor<Capability extends GraphEvidenceCapability> = Extract<GraphEvidenceOptions, {
+    type: "none";
+}> | (Capability extends "chunks" ? Extract<GraphEvidenceOptions, {
+    type: "chunks";
+}> : never);
+type GraphRetrieveOptions<Schema extends GraphSchemaLike, Evidence extends GraphEvidenceCapability = GraphEvidenceCapability> = Readonly<{
+    model: EmbeddingModel;
+    query: string;
+    search: GraphSearchOptions;
+    traversal: GraphTraversalOptions<Schema>;
+    evidence: GraphEvidenceFor<Evidence>;
+    retries?: RetrySetting | undefined;
+    abortSignal?: AbortSignal | undefined;
+}>;
+interface GraphContextRetriever<Schema extends GraphSchemaLike = GraphSchemaLike, Evidence extends GraphEvidenceCapability = GraphEvidenceCapability> {
+    readonly evidenceCapability: Evidence;
+    retrieve(options: GraphRetrieveOptions<Schema, Evidence>): Promise<GraphContext>;
+}
+type GraphExploreDirection = "outgoing" | "incoming" | "both";
+type GraphExploreOverviewOptions<Schema extends GraphSchemaLike> = Readonly<{
+    mode: "overview";
+    nodeTypes?: readonly (keyof Schema["nodes"] & string)[] | undefined;
+    relationships?: readonly (keyof Schema["relationships"] & string)[] | undefined;
+    maxNodes?: number | undefined;
+    maxRelationships?: number | undefined;
+    abortSignal?: AbortSignal | undefined;
+}>;
+type GraphExploreExpandOptions<Schema extends GraphSchemaLike> = Readonly<{
+    mode: "expand";
+    nodeIds: readonly string[];
+    nodeTypes?: readonly (keyof Schema["nodes"] & string)[] | undefined;
+    relationships?: readonly (keyof Schema["relationships"] & string)[] | undefined;
+    direction?: GraphExploreDirection | undefined;
+    maxDepth?: number | undefined;
+    maxNodes?: number | undefined;
+    maxRelationships?: number | undefined;
+    abortSignal?: AbortSignal | undefined;
+}>;
+type GraphExploreOptions<Schema extends GraphSchemaLike> = GraphExploreOverviewOptions<Schema> | GraphExploreExpandOptions<Schema>;
+type GraphExploreNode = Readonly<{
+    id: string;
+    key?: string | undefined;
+    type: string;
+    identity: GraphNodeIdentity;
+    properties: GraphProperties;
+}>;
+type GraphExploreRelationship = Readonly<{
+    id: string;
+    key?: string | undefined;
+    type: string;
+    from: string;
+    to: string;
+    properties: GraphProperties;
+}>;
+type GraphExploreResult = Readonly<{
+    nodes: readonly GraphExploreNode[];
+    relationships: readonly GraphExploreRelationship[];
+    truncated: Readonly<{
+        nodes: boolean;
+        relationships: boolean;
+    }>;
+}>;
+interface GraphExplorer<Schema extends GraphSchemaLike = GraphSchemaLike> {
+    readonly schema: Schema;
+    explore(options: GraphExploreOptions<Schema>): Promise<GraphExploreResult>;
+}
+type CreateGraphSearchToolOptions<Schema extends GraphSchemaLike, Retriever extends GraphContextRetriever<Schema> = GraphContextRetriever<Schema>> = Readonly<{
+    name: string;
+    description: string;
+    graph: Retriever;
+    model: EmbeddingModel;
+    search: GraphSearchOptions;
+    traversal: GraphTraversalOptions<Schema>;
+    evidence: GraphEvidenceFor<Retriever["evidenceCapability"]>;
+    retries?: RetrySetting | undefined;
+}>;
+type GraphSearchTool = Tool<{
+    query: string;
+}, GraphContext>;
+type GraphChangeCounts = Readonly<{
+    created: number;
+    updated: number;
+    deleted: number;
+    unchanged: number;
+}>;
+type GraphWriteResult = Readonly<{
+    documents: GraphChangeCounts;
+    chunks: GraphChangeCounts;
+    entities: GraphChangeCounts;
+    relationships: GraphChangeCounts;
+    mentions: GraphChangeCounts;
+}>;
+type GraphWriteConflict = "error" | "overwrite" | "keep-existing";
+type GraphOrphanEntityPolicy = "delete" | "keep";
+type ReplaceGraphDocumentsOptions<Schema extends GraphSchemaLike> = Readonly<{
+    documents: readonly GraphDocument[];
+    chunks: readonly EmbeddedDocument<GraphChunk>[];
+    entities: readonly EmbeddedDocument<GraphEntity<Schema>>[];
+    relationships: readonly GraphRelationship<Schema>[];
+    mentions: readonly GraphMention[];
+    conflict: GraphWriteConflict;
+    orphanEntities: GraphOrphanEntityPolicy;
+    abortSignal?: AbortSignal | undefined;
+}>;
+interface GraphDocumentWriter<Schema extends GraphSchemaLike = GraphSchemaLike> {
+    readonly schema: Schema;
+    replaceDocuments(options: ReplaceGraphDocumentsOptions<Schema>): Promise<GraphWriteResult>;
+}
+
+type ResolvedGraphExploreBase = Readonly<{
+    nodeTypes: readonly string[];
+    relationships: readonly string[];
+    maxNodes: number;
+    maxRelationships: number;
+    abortSignal?: AbortSignal | undefined;
+}>;
+type ResolvedGraphExploreOverviewOptions = ResolvedGraphExploreBase & Readonly<{
+    mode: "overview";
+}>;
+type ResolvedGraphExploreExpandOptions = ResolvedGraphExploreBase & Readonly<{
+    mode: "expand";
+    nodeIds: readonly string[];
+    direction: GraphExploreDirection;
+    maxDepth: number;
+}>;
+type ResolvedGraphExploreOptions = ResolvedGraphExploreOverviewOptions | ResolvedGraphExploreExpandOptions;
+declare function resolveGraphExploreOptions<Schema extends GraphSchemaLike>(schema: Schema, options: GraphExploreOptions<Schema>): ResolvedGraphExploreOptions;
+
+export { type GraphExploreExpandOptions as A, type GraphExploreNode as B, type CreateGraphSearchToolOptions as C, type GraphExploreOptions as D, type ExtractGraphFactsOptions as E, type GraphExploreOverviewOptions as F, type GraphSchemaLike as G, type GraphExploreRelationship as H, type GraphExploreResult as I, type GraphExplorer as J, type GraphFacts as K, type GraphHybridSearchOptions as L, type GraphNodeDefinition as M, type GraphNodeIdentity as N, type GraphPropertyPrimitive as O, type GraphRelationshipDefinition as P, type GraphRetrieveOptions as Q, type GraphSearchOptions as R, type GraphTraversalOptions as S, type GraphVectorSearchOptions as T, type ReplaceGraphDocumentsOptions as U, type ResolvedGraphExploreExpandOptions as V, type ResolvedGraphExploreOptions as W, type ResolvedGraphExploreOverviewOptions as X, resolveGraphExploreOptions as Y, type ExtractGraphFactsResult as a, type GraphEntity as b, type GraphDocumentWriter as c, type GraphWriteConflict as d, type GraphOrphanEntityPolicy as e, type GraphDocument as f, type GraphChunk as g, type GraphRelationship as h, type GraphMention as i, type GraphWriteResult as j, type GraphSchemaOptions as k, type GraphSchema as l, type GraphProperties as m, type GraphPropertyValue as n, type GraphContextRetriever as o, type GraphSearchTool as p, type GraphChangeCounts as q, type GraphContext as r, type GraphContextNode as s, type GraphContextRelationship as t, type GraphContextSeed as u, type GraphEvidence as v, type GraphEvidenceCapability as w, type GraphEvidenceFor as x, type GraphEvidenceOptions as y, type GraphExploreDirection as z };

package/dist/explore.d.ts

@@ -0,0 +1,5 @@
+export { V as ResolvedGraphExploreExpandOptions, W as ResolvedGraphExploreOptions, X as ResolvedGraphExploreOverviewOptions, Y as resolveGraphExploreOptions } from './explore-9jm2c1mG.js';
+import '@anvia/core';
+import '@anvia/core/embeddings';
+import '@anvia/core/tool';
+import 'zod';

package/dist/explore.js

@@ -0,0 +1,7 @@
+import {
+  resolveGraphExploreOptions
+} from "./chunk-N3CKMOPE.js";
+export {
+  resolveGraphExploreOptions
+};
+//# sourceMappingURL=explore.js.map

package/dist/explore.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import * as _anvia_core from '@anvia/core';
+import { CompletionModel, RetrySetting, Usage } from '@anvia/core';
+import { G as GraphSchemaLike, E as ExtractGraphFactsOptions, a as ExtractGraphFactsResult, b as GraphEntity, c as GraphDocumentWriter, d as GraphWriteConflict, e as GraphOrphanEntityPolicy, f as GraphDocument, g as GraphChunk, h as GraphRelationship, i as GraphMention, j as GraphWriteResult, k as GraphSchemaOptions, l as GraphSchema, m as GraphProperties, n as GraphPropertyValue, o as GraphContextRetriever, C as CreateGraphSearchToolOptions, p as GraphSearchTool } from './explore-9jm2c1mG.js';
+export { q as GraphChangeCounts, r as GraphContext, s as GraphContextNode, t as GraphContextRelationship, u as GraphContextSeed, v as GraphEvidence, w as GraphEvidenceCapability, x as GraphEvidenceFor, y as GraphEvidenceOptions, z as GraphExploreDirection, A as GraphExploreExpandOptions, B as GraphExploreNode, D as GraphExploreOptions, F as GraphExploreOverviewOptions, H as GraphExploreRelationship, I as GraphExploreResult, J as GraphExplorer, K as GraphFacts, L as GraphHybridSearchOptions, M as GraphNodeDefinition, N as GraphNodeIdentity, O as GraphPropertyPrimitive, P as GraphRelationshipDefinition, Q as GraphRetrieveOptions, R as GraphSearchOptions, S as GraphTraversalOptions, T as GraphVectorSearchOptions, U as ReplaceGraphDocumentsOptions, V as ResolvedGraphExploreExpandOptions, W as ResolvedGraphExploreOptions, X as ResolvedGraphExploreOverviewOptions, Y as resolveGraphExploreOptions } from './explore-9jm2c1mG.js';
+import { TextDocument, TextDocumentMetadata, TextDocumentChunkingOptions } from '@anvia/core/documents';
+import { EmbeddingModel, EmbeddedDocument } from '@anvia/core/embeddings';
+import '@anvia/core/tool';
+import 'zod';
+
+declare function extractGraphFacts<Schema extends GraphSchemaLike, Model extends _anvia_core.CompletionModel>(options: ExtractGraphFactsOptions<Schema, Model>): Promise<ExtractGraphFactsResult<Schema>>;
+declare class GraphFactConflictError extends Error {
+    readonly factKey: string;
+    readonly sourceChunkIds: readonly string[];
+    constructor(factKey: string, sourceChunkIds: readonly string[]);
+}
+
+type GraphPreparationOptions<Schema extends GraphSchemaLike, ExtractionModel extends CompletionModel> = Readonly<{
+    graph: Readonly<{
+        schema: Schema;
+    }>;
+    documents: readonly TextDocument<TextDocumentMetadata>[];
+    extractionModel: ExtractionModel;
+    embeddingModel: EmbeddingModel;
+    chunking?: TextDocumentChunkingOptions | undefined;
+    entityText?: ((entity: GraphEntity<Schema>) => string) | undefined;
+    instructions?: string | undefined;
+    retries?: RetrySetting | undefined;
+    concurrency?: number | undefined;
+    abortSignal?: AbortSignal | undefined;
+}>;
+type PrepareGraphDocumentsOptions<Schema extends GraphSchemaLike, ExtractionModel extends CompletionModel = CompletionModel> = GraphPreparationOptions<Schema, ExtractionModel>;
+type IngestGraphDocumentsOptions<Schema extends GraphSchemaLike, ExtractionModel extends CompletionModel = CompletionModel> = Omit<GraphPreparationOptions<Schema, ExtractionModel>, "graph"> & Readonly<{
+    graph: GraphDocumentWriter<Schema>;
+    conflict: GraphWriteConflict;
+    orphanEntities: GraphOrphanEntityPolicy;
+}>;
+type IngestGraphTextOptions<Schema extends GraphSchemaLike, ExtractionModel extends CompletionModel = CompletionModel> = Omit<IngestGraphDocumentsOptions<Schema, ExtractionModel>, "documents"> & Readonly<{
+    document: TextDocument<TextDocumentMetadata>;
+}>;
+type PreparedGraphDocuments<Schema extends GraphSchemaLike> = Readonly<{
+    documents: readonly GraphDocument[];
+    chunks: readonly EmbeddedDocument<GraphChunk<TextDocumentMetadata>, TextDocumentMetadata>[];
+    vectorDocuments: readonly EmbeddedDocument<TextDocument<TextDocumentMetadata>, TextDocumentMetadata>[];
+    entities: readonly EmbeddedDocument<GraphEntity<Schema>>[];
+    relationships: readonly GraphRelationship<Schema>[];
+    mentions: readonly GraphMention[];
+    usage: Usage;
+}>;
+type IngestGraphDocumentsResult<Schema extends GraphSchemaLike> = PreparedGraphDocuments<Schema> & Readonly<{
+    write: GraphWriteResult;
+}>;
+declare function ingestGraphText<Schema extends GraphSchemaLike, ExtractionModel extends CompletionModel>(options: IngestGraphTextOptions<Schema, ExtractionModel>): Promise<IngestGraphDocumentsResult<Schema>>;
+declare function ingestGraphDocuments<Schema extends GraphSchemaLike, ExtractionModel extends CompletionModel>(options: IngestGraphDocumentsOptions<Schema, ExtractionModel>): Promise<IngestGraphDocumentsResult<Schema>>;
+declare function prepareGraphDocuments<Schema extends GraphSchemaLike, ExtractionModel extends CompletionModel>(options: PrepareGraphDocumentsOptions<Schema, ExtractionModel>): Promise<PreparedGraphDocuments<Schema>>;
+
+declare const graphReservedPropertyPrefix = "__anvia_";
+declare function defineGraphSchema<const Options extends GraphSchemaOptions>(options: Options): GraphSchema<Options>;
+declare function validateGraphSchemaOptions(options: GraphSchemaOptions): void;
+declare function freezeGraphSchema<const Options extends GraphSchemaOptions, const Kind extends string>(options: Options, kind: Kind): Readonly<Options & {
+    kind: Kind;
+}>;
+declare function parseGraphProperties(value: unknown, label: string): GraphProperties;
+declare function parseGraphPropertyValue(value: unknown, label: string): GraphPropertyValue;
+declare function assertGraphName(value: string, label: string): void;
+declare function assertGraphPropertyName(value: string): void;
+
+declare function createGraphSearchTool<Schema extends GraphSchemaLike, Retriever extends GraphContextRetriever<Schema>>(options: CreateGraphSearchToolOptions<Schema, Retriever>): GraphSearchTool;
+
+export { CreateGraphSearchToolOptions, ExtractGraphFactsOptions, ExtractGraphFactsResult, GraphChunk, GraphContextRetriever, GraphDocument, GraphDocumentWriter, GraphEntity, GraphFactConflictError, GraphMention, GraphOrphanEntityPolicy, GraphProperties, GraphPropertyValue, GraphRelationship, GraphSchema, GraphSchemaLike, GraphSchemaOptions, GraphSearchTool, GraphWriteConflict, GraphWriteResult, type IngestGraphDocumentsOptions, type IngestGraphDocumentsResult, type IngestGraphTextOptions, type PrepareGraphDocumentsOptions, type PreparedGraphDocuments, assertGraphName, assertGraphPropertyName, createGraphSearchTool, defineGraphSchema, extractGraphFacts, freezeGraphSchema, graphReservedPropertyPrefix, ingestGraphDocuments, ingestGraphText, parseGraphProperties, parseGraphPropertyValue, prepareGraphDocuments, validateGraphSchemaOptions };