@anvia/graph 1.1.4 → 1.1.6

package/README.md

@@ -1,9 +1,23 @@
 # @anvia/graph
 
-Provider-neutral schema, extraction, retrieval-context, and tool primitives for knowledge graphs.
+Turn text into typed entities and relationships for GraphRAG. Define a graph schema once,
+then use it for extraction, retrieval tools, and ingestion with Neo4j or Memgraph.
+
+## Install
+
+```sh
+pnpm add @anvia/graph @anvia/core @anvia/openai zod
+```
+
+`@anvia/openai` supplies the extraction model below; other completion adapters work too.
+
+## Quickstart
+
+Set `OPENAI_API_KEY`. This example extracts graph facts without requiring a graph database.
 
 ```ts
 import { defineGraphSchema, extractGraphFacts } from "@anvia/graph";
+import { OpenAIClient } from "@anvia/openai";
 import { z } from "zod";
 
 const schema = defineGraphSchema({
@@ -16,134 +30,35 @@ const schema = defineGraphSchema({
   },
   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",
-  factConflicts: {
-    entity: {
-      properties: {
-        summary: "prefer-longest",
-        aliases: "union",
-        confidence: "max",
-      },
+const client = new OpenAIClient({ apiKey: process.env.OPENAI_API_KEY! });
+const facts = await extractGraphFacts({
+  model: client.completionModel({ modelId: "gpt-5.6", api: "responses" }),
+  schema,
+  chunks: [
+    {
+      id: "chunk-1",
+      documentId: "products",
+      index: 0,
+      text: "The product with ID anvia is named Anvia.",
     },
-  },
-});
-```
-
-Extraction conflicts and stored-graph write conflicts are separate policies. `factConflicts`
-resolves disagreements between chunks before persistence; `conflict` controls collisions with facts
-already stored by the graph adapter. Extraction rejects disagreements by default. Built-in
-property strategies include `prefer-first`, `prefer-last`, `prefer-defined`, `prefer-longest`,
-`union`, `max`, and `min`; a custom resolver receives structured candidate and source chunk data.
-Conflict errors and resolved warnings include the fact type, stable key, parsed identity, property,
-candidate values, and source chunk IDs. Resolved disagreements are returned in `warnings`.
-
-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 });
-```
-
-Every ingestion result includes a `receipt` with document, entity, relationship, and vector IDs,
-the graph write counts, warnings, an optional caller-supplied `revision`, and vector-stage status.
-Use `ingestGraphTextToStores()` or `ingestGraphDocumentsToStores()` to write the graph followed by
-the vector store. If the second stage fails, `GraphIngestionStageError` exposes a receipt with a
-completed graph stage and failed vector stage for queue reconciliation.
-
-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 },
+  ],
 });
+console.log(facts.output.entities);
 ```
 
-The graph registration controls which evidence modes are valid. Managed graphs can hydrate stored
-chunks, while existing graph registrations use `{ type: "none" }`.
-
-## Exploration
+## Build on the same schema
 
-Adapters implementing `GraphExplorer` expose a portable, bounded view for visualization:
+- Ingest documents with chunking, extraction, and embeddings into managed graphs.
+- Reuse chunk embeddings in vector stores and track partial writes with ingestion receipts.
+- Resolve extraction conflicts with explicit property policies.
+- Create bounded graph search tools and explore graph neighborhoods.
 
-```ts
-const overview = await graph.explore({
-  mode: "overview",
-  nodeTypes: ["Product"],
-  includeProvenance: true,
-  maxNodes: 100,
-  maxRelationships: 200,
-});
-
-const neighborhood = await graph.explore({
-  mode: "expand",
-  nodeIds: [overview.nodes[0]!.id],
-  direction: "both",
-  maxDepth: 1,
-});
-```
+Persistence and provisioning belong to [Neo4j](https://github.com/anvia-hq/anvia/blob/main/packages/graph-neo4j/README.md)
+and [Memgraph](https://github.com/anvia-hq/anvia/blob/main/packages/graph-memgraph/README.md).
+Property schemas must use `z.strictObject()` and preserve input values without transforms or defaults.
 
-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.
+## Learn more
 
-When `includeProvenance` is true, supported adapters attach source `documentIds` and `chunkIds` to
-nodes and relationships.
+- [Usage guide](https://github.com/anvia-hq/anvia/blob/main/docs/packages/graph.md)
+- [Anvia overview](https://github.com/anvia-hq/anvia/blob/main/README.md)
+- [Contributing](https://github.com/anvia-hq/anvia/blob/main/CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvia/graph",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Provider-neutral knowledge graph primitives for Anvia.",
   "author": "anvia",
   "license": "MIT",
@@ -32,13 +32,13 @@
     "@types/node": "^24.9.1",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.8",
-    "zod": "^4.6.5",
-    "@anvia/core": "1.3.1"
+    "vitest": "^4.1.11",
+    "zod": "^4.6.7",
+    "@anvia/core": "1.17.2"
   },
   "peerDependencies": {
-    "zod": "^4.6.5",
-    "@anvia/core": "^1.3.1"
+    "zod": "^4.6.7",
+    "@anvia/core": "^1.17.2"
   },
   "scripts": {
     "build": "tsup src/index.ts src/explore.ts --format esm --dts --sourcemap --clean",