@anvia/neo4j 1.1.4 → 1.1.5

package/README.md

@@ -1,49 +1,38 @@
 # @anvia/neo4j
 
-Schema-first local GraphRAG for Neo4j 2026.01 and newer.
+Build GraphRAG applications on Neo4j with typed schemas, document ingestion, and
+retrieval that follows connected entities back to their source evidence.
 
-Provider-neutral schemas from `@anvia/graph` are accepted alongside the compatibility
-`defineNeo4jGraphSchema()` API. Registered graphs expose `graph.retrieve()`, and the shared
-`createGraphSearchTool()` factory gives Neo4j and Memgraph the same Agent tool API.
-
-## Installation
+## Install
 
 ```sh
-pnpm add @anvia/graph @anvia/neo4j @anvia/core
+pnpm add @anvia/neo4j @anvia/graph @anvia/core @anvia/openai zod
 ```
 
-## Managed knowledge graph
+Requires Neo4j 2026.01 or newer. `@anvia/openai` supplies the example's models.
+
+## Quickstart
+
+Set `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, and `OPENAI_API_KEY`.
 
 ```ts
-import { Agent } from "@anvia/core/agent";
-import { createGraphSearchTool, ingestGraphText } from "@anvia/graph";
-import { Neo4jClient, defineNeo4jGraphSchema } from "@anvia/neo4j";
+import { defineGraphSchema, ingestGraphText } from "@anvia/graph";
+import { Neo4jClient } from "@anvia/neo4j";
+import { OpenAIClient } from "@anvia/openai";
 import { z } from "zod";
 
-const schema = defineNeo4jGraphSchema({
+const schema = defineGraphSchema({
   nodes: {
     Product: {
       description: "A product or service.",
       identity: ["id"],
       properties: z.strictObject({ id: z.string(), name: z.string() }),
     },
-    Incident: {
-      description: "An operational incident.",
-      identity: ["id"],
-      properties: z.strictObject({ id: z.string(), title: z.string() }),
-    },
-  },
-  relationships: {
-    AFFECTS: {
-      description: "An incident affects a product.",
-      from: "Incident",
-      to: "Product",
-      properties: z.strictObject({ severity: z.enum(["low", "high"]) }),
-    },
   },
+  relationships: {},
 });
-
-await using client = new Neo4jClient({
+const models = new OpenAIClient({ apiKey: process.env.OPENAI_API_KEY! });
+const client = new Neo4jClient({
   uri: process.env.NEO4J_URI!,
   auth: {
     username: process.env.NEO4J_USERNAME!,
@@ -56,209 +45,40 @@ const graph = client.managedKnowledgeGraph({
   resources: {
     labels: { document: "SupportDocument", chunk: "SupportChunk", entity: "SupportEntity" },
     indexes: {
-      chunks: {
-        vector: { name: "support_chunks_vector", dimensions: 1536, similarity: "cosine" },
-        fulltext: { name: "support_chunks_text" },
-      },
-      entities: {
-        vector: { name: "support_entities_vector", dimensions: 1536, similarity: "cosine" },
-        fulltext: { name: "support_entities_text", properties: ["id", "name", "title"] },
-      },
-    },
-  },
-});
-
-await graph.ensure({ indexTimeoutMs: 60_000 });
-
-const ingestion = await ingestGraphText({
-  graph,
-  document: { id: "incident-42", text },
-  extractionModel,
-  embeddingModel,
-  chunking: {
-    strategy: "recursive",
-    maxSize: 1_000,
-    overlap: 100,
-    separators: ["\n\n", "\n", " "],
-  },
-  conflict: "error",
-  orphanEntities: "delete",
-});
-console.log(ingestion.write);
-
-const searchGraph = createGraphSearchTool({
-  name: "search_support_graph",
-  description: "Search connected support incidents and products.",
-  graph,
-  model: embeddingModel,
-  search: {
-    type: "hybrid",
-    seeds: ["chunks", "entities"],
-    topK: 8,
-    candidatesPerSeed: 20,
-    rrfK: 60,
-  },
-  traversal: {
-    relationships: ["AFFECTS"],
-    direction: "both",
-    maxDepth: 2,
-    maxNodes: 40,
-    maxRelationships: 80,
-  },
-  evidence: { type: "chunks", maxChunks: 12 },
-});
-
-const agent = new Agent({ id: "support", model: chatModel, tools: [searchGraph] });
-```
-
-Call `ensure()` once during application startup or deployment initialization, then reuse the graph
-handle in jobs. It is idempotent, but calling it for every ingestion job adds version, schema, and
-index checks to the hot path. Call `validate()` for readiness checks that must never provision.
-
-## Tenant namespaces
-
-Reuse the same labels, indexes, and Qdrant collection across tenants without constructing resource
-names from user input:
-
-```ts
-const tenant = client.tenant(userId);
-const graph = tenant.managedKnowledgeGraph({ name: "support", schema, resources });
-
-const qdrantTenant = qdrant.tenant(userId);
-const vectors = qdrantTenant.vectorStore({
-  collectionName: "support_documents",
-  dimensions: 1536,
-});
-```
-
-Both adapters hash the tenant ID using the same deterministic namespace. Neo4j includes that
-namespace in managed uniqueness constraints, indexed vector filtering, writes, retrieval,
-traversal, evidence, deletion, and exploration. Do not mix namespaced and non-namespaced handles
-with the same Neo4j resource definitions; `validate()` reports the incompatible constraint or
-index so it can be migrated explicitly.
-
-Tenant handles scope Anvia's managed lifecycle, retrieval, and exploration APIs; they are not a
-database authorization boundary. `graph.query()` and `client.nativeDriver()` intentionally expose
-raw Cypher access. Use separate Neo4j credentials or databases when untrusted callers require a
-hard security boundary.
-
-The application owns file discovery, reading, model loading, retry policy, and Agent lifecycle.
-`ingestGraphText()` and `ingestGraphDocuments()` provide the convenient end-to-end path. Advanced
-callers can compose `prepareGraphDocuments()`, `extractGraphFacts()`, `embedDocuments()`, and
-`replaceDocuments()` directly when they need custom orchestration.
-
-Graph property schemas must use `z.strictObject()` and must not coerce, default, transform,
-preprocess, catch, trim, or otherwise overwrite values. This keeps extraction, comparison, and
-stored Neo4j properties exact.
-
-Re-ingestion is document-scoped. `replaceDocuments()` removes the old chunks and their provenance
-before inserting the new representation. Facts supported by other documents remain. Use
-`deleteDocuments({ documentIds, orphanEntities })` for explicit removal.
-
-Both write operations return exact logical before-and-after counts for documents, chunks, entities,
-relationships, and mentions. A resource is `created`, `updated`, `deleted`, or `unchanged` by its
-stable public identity; the result is produced inside the same transaction as the mutation.
-
-Retrieval always requires an explicit evidence mode. `{ type: "none" }` performs no evidence read.
-Managed graphs can use `{ type: "chunks", maxChunks }` to hydrate exact source chunks in ranked
-provenance order. Seeds, nodes, and relationships refer to those records through `sourceChunkIds`.
-
-## Existing graph
-
-```ts
-const graph = client.knowledgeGraph({
-  schema,
-  seeds: {
-    incidents: {
-      nodeTypes: ["Incident"],
-      vectorIndex: {
-        name: "existing_incident_vectors",
-        property: "embedding",
-        dimensions: 1536,
-        similarity: "cosine",
-      },
-      fulltextIndex: {
-        name: "existing_incident_text",
-        properties: ["title"],
-      },
-    },
-    products: {
-      nodeTypes: ["Product"],
-      vectorIndex: {
-        name: "existing_product_vectors",
-        property: "embedding",
-        dimensions: 1536,
-        similarity: "cosine",
-      },
-      fulltextIndex: {
-        name: "existing_product_text",
-        properties: ["name"],
-      },
+      chunks: { vector: { name: "support_chunks", dimensions: 1536, similarity: "cosine" } },
+      entities: { vector: { name: "support_entities", dimensions: 1536, similarity: "cosine" } },
     },
   },
 });
 
-await graph.validate();
-```
-
-## Graph explorer
-
-Managed and existing graph registrations implement the shared `GraphExplorer` contract:
-
-```ts
-const overview = await graph.explore({ mode: "overview", maxNodes: 100 });
-const neighborhood = await graph.explore({
-  mode: "expand",
-  nodeIds: [overview.nodes[0]!.id],
-  maxDepth: 1,
-});
+try {
+  await graph.ensure({ indexTimeoutMs: 60_000 });
+  const result = await ingestGraphText({
+    graph,
+    document: { id: "products", text: "The product with ID anvia is named Anvia." },
+    extractionModel: models.completionModel({ modelId: "gpt-5.6", api: "responses" }),
+    embeddingModel: models.embeddingModel({ modelId: "text-embedding-3-small" }),
+    conflict: "error",
+    orphanEntities: "delete",
+  });
+  console.log(result.write);
+} finally {
+  await client.close();
+}
 ```
 
-Pass `includeProvenance: true` to expose supported source document and chunk IDs on explorer nodes
-and relationships. This can drive article-to-entity UI links without a separate identity mapping
-table; Neo4j element IDs remain opaque expansion cursors.
-
-## Production ingestion workflow
-
-For a queue worker (including BullMQ), use stable document IDs, attach a monotonic revision, and
-call `ingestGraphTextToStores({ graph, vectorStore, ... })`. Persist its receipt as the job result.
-Retry extraction/provider failures as a whole. If `GraphIngestionStageError.stage === "vector"`,
-the graph transaction already committed; re-run the idempotent job with `conflict: "overwrite"`.
-Refresh by replacing the same document ID;
-delete from both stores and record each completed stage. Pass the queue cancellation signal through
-`abortSignal`, create tenant-scoped handles before processing user-owned jobs, and request explorer
-provenance for source attribution.
+## What you can build
 
-The explorer returns Neo4j element IDs as opaque strings, limits every query, and omits embeddings
-and other `__anvia_*` properties. Use stable graph identity properties for application logic; use the
-opaque IDs only to expand the current view.
+- Managed graphs with explicit provisioning and document-scoped replacement.
+- Vector and hybrid retrieval with bounded traversal and source chunk evidence.
+- Agent search tools through `createGraphSearchTool()` from `@anvia/graph`.
+- Bounded exploration and read-only registration of existing graphs.
 
-Existing registrations are read-only and expose no provisioning or write methods. Use
-`client.nativeDriver()` for application-owned Cypher.
+Tenant handles scope managed graph operations in shared resources. They are not a database
+authorization boundary. Existing graph registrations are read-only.
 
-Existing graph registrations do not own Anvia document and chunk resources, so their retrieval and
-tool registrations accept only `evidence: { type: "none" }`.
+## Learn more
 
-Each existing seed describes exactly one indexed node type and the complete expected vector and
-full-text index definitions. Register additional node types as separate seeds and fuse them with
-hybrid retrieval.
-
-Package operations use explicit transactions and do not invoke Neo4j's managed retry APIs. Abort
-signals roll back the active transaction. Applications decide whether and how to retry an entire
-operation.
-
-`Neo4jClient` supports `await using` and closes a driver that it creates from `uri` and `auth`.
-When a caller supplies `driver`, that driver remains caller-owned; closing or disposing the client
-only closes the Anvia client handle.
-
-The public property boundary is intentionally JSON-safe. Unsafe Neo4j integers, temporal and
-spatial objects, nodes, relationships, paths, maps, and heterogeneous property arrays are rejected
-instead of being coerced.
-
-## Development
-
-```sh
-pnpm --filter @anvia/neo4j typecheck
-pnpm --filter @anvia/neo4j test
-pnpm --filter @anvia/neo4j build
-```
+- [Usage guide](https://github.com/anvia-hq/anvia/blob/main/docs/packages/graph-neo4j.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/neo4j",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Schema-first Neo4j GraphRAG integration for Anvia.",
   "author": "anvia",
   "license": "MIT",
@@ -26,19 +26,19 @@
   },
   "dependencies": {
     "neo4j-driver": "^6.2.0",
-    "@anvia/graph": "1.1.4"
+    "@anvia/graph": "1.1.5"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.8",
+    "vitest": "^4.1.11",
     "zod": "^4.6.5",
-    "@anvia/core": "1.3.1"
+    "@anvia/core": "1.6.1"
   },
   "peerDependencies": {
     "zod": "^4.6.5",
-    "@anvia/core": "^1.3.1"
+    "@anvia/core": "^1.6.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --sourcemap --clean",