@anvia/graph 0.0.0-bootstrap.0 → 1.0.4

package/dist/index.js

@@ -0,0 +1,672 @@
+import {
+  resolveGraphExploreOptions
+} from "./chunk-N3CKMOPE.js";
+
+// src/extract.ts
+import { Usage } from "@anvia/core";
+import { extract } from "@anvia/core/extractor";
+import { z as z2 } from "zod";
+
+// src/schema.ts
+import { z } from "zod";
+var graphReservedPropertyPrefix = "__anvia_";
+function defineGraphSchema(options) {
+  validateGraphSchemaOptions(options);
+  return freezeGraphSchema(options, "graph-schema");
+}
+function validateGraphSchemaOptions(options) {
+  if (Object.keys(options.nodes).length === 0) {
+    throw new TypeError("A graph schema requires at least one node type.");
+  }
+  for (const [type, definition] of Object.entries(options.nodes)) {
+    assertGraphName(type, "node type");
+    assertDescription(definition.description, `node ${type}`);
+    if (!(definition.properties instanceof z.ZodObject)) {
+      throw new TypeError(`Properties for node ${type} must be a Zod object schema.`);
+    }
+    assertExactPropertySchema(definition.properties, `node ${type}`);
+    if (definition.identity.length === 0 || new Set(definition.identity).size !== definition.identity.length) {
+      throw new TypeError(`Node ${type} must declare unique identity properties.`);
+    }
+    for (const property of definition.identity) {
+      assertGraphPropertyName(property);
+      if (!(property in definition.properties.shape)) {
+        throw new TypeError(`Identity property ${property} is not declared by node ${type}.`);
+      }
+    }
+    for (const property of Object.keys(definition.properties.shape)) {
+      assertGraphPropertyName(property);
+    }
+  }
+  for (const [type, definition] of Object.entries(options.relationships)) {
+    assertGraphName(type, "relationship type");
+    assertDescription(definition.description, `relationship ${type}`);
+    if (!(definition.from in options.nodes) || !(definition.to in options.nodes)) {
+      throw new TypeError(`Relationship ${type} references an unknown endpoint type.`);
+    }
+    if (!(definition.properties instanceof z.ZodObject)) {
+      throw new TypeError(`Properties for relationship ${type} must be a Zod object schema.`);
+    }
+    assertExactPropertySchema(definition.properties, `relationship ${type}`);
+    const identity = definition.identity ?? [];
+    if (new Set(identity).size !== identity.length) {
+      throw new TypeError(`Relationship ${type} contains duplicate identity properties.`);
+    }
+    for (const property of Object.keys(definition.properties.shape)) {
+      assertGraphPropertyName(property);
+    }
+    for (const property of identity) {
+      if (!(property in definition.properties.shape)) {
+        throw new TypeError(
+          `Identity property ${property} is not declared by relationship ${type}.`
+        );
+      }
+    }
+  }
+}
+function freezeGraphSchema(options, kind) {
+  const nodes = Object.fromEntries(
+    Object.entries(options.nodes).map(([type, definition]) => [
+      type,
+      Object.freeze({ ...definition, identity: Object.freeze([...definition.identity]) })
+    ])
+  );
+  const relationships = Object.fromEntries(
+    Object.entries(options.relationships).map(([type, definition]) => {
+      const copy = { ...definition };
+      if (definition.identity !== void 0) {
+        Object.assign(copy, { identity: Object.freeze([...definition.identity]) });
+      }
+      return [type, Object.freeze(copy)];
+    })
+  );
+  return Object.freeze({
+    nodes: Object.freeze(nodes),
+    relationships: Object.freeze(relationships),
+    kind
+  });
+}
+function parseGraphProperties(value, label) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object of graph property values.`);
+  }
+  const output = {};
+  for (const [key, item] of Object.entries(value)) {
+    assertGraphPropertyName(key);
+    output[key] = parseGraphPropertyValue(item, `${label}.${key}`);
+  }
+  return output;
+}
+function parseGraphPropertyValue(value, label) {
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError(`${label} must be finite.`);
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      throw new TypeError(`${label} must be a safe integer.`);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [];
+    const parsed = value.map((item, index) => parsePrimitive(item, `${label}[${index}]`));
+    const type = typeof parsed[0];
+    if (!parsed.every((item) => typeof item === type)) {
+      throw new TypeError(`${label} must be a homogeneous array.`);
+    }
+    return parsed;
+  }
+  throw new TypeError(`${label} is not a supported graph property value.`);
+}
+function assertGraphName(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+}
+function assertGraphPropertyName(value) {
+  assertGraphName(value, "graph property name");
+  if (value.startsWith(graphReservedPropertyPrefix)) {
+    throw new TypeError(
+      `Graph property names beginning with ${graphReservedPropertyPrefix} are reserved.`
+    );
+  }
+}
+function parsePrimitive(value, label) {
+  const parsed = parseGraphPropertyValue(value, label);
+  if (typeof parsed === "string" || typeof parsed === "number" || typeof parsed === "boolean") {
+    return parsed;
+  }
+  throw new TypeError(`${label} must be a primitive property value.`);
+}
+function assertDescription(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${label} requires a non-empty description.`);
+  }
+}
+function assertExactPropertySchema(schema, label) {
+  const definition = schema._zod.def;
+  if (!(definition.catchall instanceof z.ZodNever)) {
+    throw new TypeError(`${label} properties must use a strict Zod object schema.`);
+  }
+  for (const [property, propertySchema] of Object.entries(schema.shape)) {
+    assertNonEffectfulSchema(propertySchema, `${label} property ${property}`, /* @__PURE__ */ new Set());
+  }
+}
+function assertNonEffectfulSchema(value, label, visited) {
+  if (!(value instanceof z.ZodType)) throw new TypeError(`${label} must be a Zod schema.`);
+  if (visited.has(value)) return;
+  visited.add(value);
+  const definition = value._zod.def;
+  const type = definition.type;
+  if (definition.coerce === true || type === "default" || type === "prefault" || type === "catch" || type === "transform" || type === "pipe") {
+    throw new TypeError(
+      `${label} must not coerce, default, transform, preprocess, or catch values.`
+    );
+  }
+  const checks = definition.checks;
+  if (Array.isArray(checks) && checks.some((check) => {
+    if (typeof check !== "object" || check === null) return false;
+    return check._zod?.def?.check === "overwrite";
+  })) {
+    throw new TypeError(`${label} must not normalize or overwrite values.`);
+  }
+  for (const child of schemaChildren(definition)) assertNonEffectfulSchema(child, label, visited);
+}
+function schemaChildren(definition) {
+  const children = [];
+  for (const key of ["innerType", "element", "left", "right", "rest", "keyType", "valueType"]) {
+    const value = definition[key];
+    if (value instanceof z.ZodType) children.push(value);
+  }
+  for (const key of ["options", "items"]) {
+    const value = definition[key];
+    if (Array.isArray(value)) {
+      for (const item of value) if (item instanceof z.ZodType) children.push(item);
+    }
+  }
+  return children;
+}
+
+// src/extract.ts
+async function extractGraphFacts(options) {
+  assertConcurrency(options.concurrency);
+  throwIfAborted(options.abortSignal);
+  const ids = /* @__PURE__ */ new Set();
+  for (const chunk of options.chunks) {
+    if (ids.has(chunk.id)) throw new TypeError(`Duplicate graph chunk id: ${chunk.id}`);
+    ids.add(chunk.id);
+    if (typeof chunk.text !== "string") {
+      throw new TypeError(`Graph chunk ${chunk.id} text must be a string.`);
+    }
+  }
+  const outputSchema = extractionSchema(options.schema);
+  const instructions = graphInstructions(options.schema, options.instructions);
+  const extractions = await mapConcurrent(
+    options.chunks,
+    options.concurrency ?? 1,
+    async (chunk) => {
+      throwIfAborted(options.abortSignal);
+      const result = await extract({
+        model: options.model,
+        text: chunk.text,
+        outputSchema,
+        instructions,
+        retries: options.retries,
+        abortSignal: options.abortSignal
+      });
+      return { chunkId: chunk.id, output: result.output, usage: result.usage };
+    }
+  );
+  return {
+    output: normalizeFacts(options.schema, extractions),
+    usage: extractions.reduce((usage, item) => Usage.add(usage, item.usage), Usage.empty())
+  };
+}
+function extractionSchema(schema) {
+  const entities = Object.entries(schema.nodes).map(
+    ([type, definition]) => z2.object({ ref: z2.string().min(1), type: z2.literal(type), properties: definition.properties })
+  );
+  const relationships = Object.entries(schema.relationships).map(
+    ([type, definition]) => z2.object({
+      type: z2.literal(type),
+      from: z2.string().min(1),
+      to: z2.string().min(1),
+      properties: definition.properties
+    })
+  );
+  return z2.object({
+    entities: z2.array(union(entities, z2.never())),
+    relationships: z2.array(union(relationships, z2.never()))
+  });
+}
+function union(items, empty) {
+  if (items.length === 0) return empty;
+  if (items.length === 1) return items[0];
+  return z2.union(items);
+}
+function graphInstructions(schema, extra) {
+  const nodes = Object.entries(schema.nodes).map(([type, definition]) => `- ${type}: ${definition.description}`).join("\n");
+  const relationships = Object.entries(schema.relationships).map(
+    ([type, definition]) => `- ${type}: ${definition.from} -> ${definition.to}. ${definition.description}`
+  ).join("\n");
+  return [
+    "Extract only facts directly supported by the source text.",
+    "Give every extracted entity a unique local ref and use those refs as relationship endpoints.",
+    "Do not invent entity or relationship types outside the declared schema.",
+    `Node types:
+${nodes}`,
+    relationships.length === 0 ? "No relationship types are allowed." : `Relationship types:
+${relationships}`,
+    extra
+  ].filter((part) => part !== void 0 && part.length > 0).join("\n\n");
+}
+function normalizeFacts(schema, extractions) {
+  const entities = /* @__PURE__ */ new Map();
+  const relationships = /* @__PURE__ */ new Map();
+  const mentions = /* @__PURE__ */ new Map();
+  for (const extraction of extractions) {
+    const refs = /* @__PURE__ */ new Map();
+    for (const raw of extraction.output.entities) {
+      if (refs.has(raw.ref)) {
+        throw new TypeError(`Duplicate entity ref ${raw.ref} in chunk ${extraction.chunkId}.`);
+      }
+      const definition = schema.nodes[raw.type];
+      if (definition === void 0) throw new TypeError(`Unknown graph entity type: ${raw.type}`);
+      const properties2 = parseGraphProperties(
+        definition.properties.parse(raw.properties),
+        `entity ${raw.type}`
+      );
+      const identity = identityFromProperties(definition.identity, properties2, raw.type);
+      const key = `${raw.type}:${stableObject(identity)}`;
+      const current = entities.get(key);
+      const next = {
+        key,
+        type: raw.type,
+        identity,
+        properties: properties2,
+        sourceChunkIds: [extraction.chunkId]
+      };
+      if (current === void 0) {
+        entities.set(key, next);
+        refs.set(raw.ref, next);
+      } else {
+        assertSameProperties(
+          current.properties,
+          properties2,
+          key,
+          current.sourceChunkIds,
+          extraction.chunkId
+        );
+        const merged = {
+          ...current,
+          sourceChunkIds: [...current.sourceChunkIds, extraction.chunkId]
+        };
+        entities.set(key, merged);
+        refs.set(raw.ref, merged);
+      }
+      mentions.set(`${extraction.chunkId}\0${key}`, {
+        chunkId: extraction.chunkId,
+        entityKey: key
+      });
+    }
+    for (const raw of extraction.output.relationships) {
+      const definition = schema.relationships[raw.type];
+      if (definition === void 0) {
+        throw new TypeError(`Unknown graph relationship type: ${raw.type}`);
+      }
+      const from = refs.get(raw.from);
+      const to = refs.get(raw.to);
+      if (from === void 0 || to === void 0) {
+        throw new TypeError(
+          `Relationship ${raw.type} in chunk ${extraction.chunkId} references an unknown entity ref.`
+        );
+      }
+      if (from.type !== definition.from || to.type !== definition.to) {
+        throw new TypeError(
+          `Relationship ${raw.type} has invalid endpoint types ${from.type} -> ${to.type}.`
+        );
+      }
+      const properties2 = parseGraphProperties(
+        definition.properties.parse(raw.properties),
+        `relationship ${raw.type}`
+      );
+      const identity = identityFromProperties(definition.identity ?? [], properties2, raw.type);
+      const key = `${raw.type}:${from.key}->${to.key}:${stableObject(identity)}`;
+      const current = relationships.get(key);
+      const next = {
+        key,
+        type: raw.type,
+        from: from.key,
+        to: to.key,
+        properties: properties2,
+        sourceChunkIds: [extraction.chunkId]
+      };
+      if (current === void 0) relationships.set(key, next);
+      else {
+        assertSameProperties(
+          current.properties,
+          properties2,
+          key,
+          current.sourceChunkIds,
+          extraction.chunkId
+        );
+        relationships.set(key, {
+          ...current,
+          sourceChunkIds: [...current.sourceChunkIds, extraction.chunkId]
+        });
+      }
+    }
+  }
+  return {
+    entities: [...entities.values()],
+    relationships: [...relationships.values()],
+    mentions: [...mentions.values()]
+  };
+}
+function identityFromProperties(keys, properties2, type) {
+  const identity = {};
+  for (const key of keys) {
+    const value = properties2[key];
+    if (value === void 0 || !(typeof value === "string" || typeof value === "number" || typeof value === "boolean")) {
+      throw new TypeError(`Identity property ${key} for ${type} must be a primitive value.`);
+    }
+    identity[key] = value;
+  }
+  return identity;
+}
+function stableObject(value) {
+  return JSON.stringify(
+    Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)))
+  );
+}
+function assertSameProperties(left, right, key, sourceChunkIds, nextChunkId) {
+  if (stableObject(left) !== stableObject(right)) {
+    throw new GraphFactConflictError(key, [...sourceChunkIds, nextChunkId]);
+  }
+}
+var GraphFactConflictError = class extends Error {
+  constructor(factKey, sourceChunkIds) {
+    super(
+      `Conflicting graph fact ${factKey} was extracted from chunks ${sourceChunkIds.join(", ")}.`
+    );
+    this.factKey = factKey;
+    this.sourceChunkIds = sourceChunkIds;
+    this.name = "GraphFactConflictError";
+  }
+  factKey;
+  sourceChunkIds;
+};
+function assertConcurrency(value) {
+  if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) {
+    throw new RangeError("Graph extraction concurrency must be a positive safe integer.");
+  }
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted !== true) return;
+  if (signal.reason instanceof Error) throw signal.reason;
+  throw new DOMException("The operation was aborted.", "AbortError");
+}
+async function mapConcurrent(values, concurrency, run) {
+  const output = Array(values.length);
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+      for (; ; ) {
+        const index = cursor;
+        cursor += 1;
+        if (index >= values.length) return;
+        output[index] = await run(values[index]);
+      }
+    })
+  );
+  return output;
+}
+
+// src/ingest.ts
+import {
+  chunkTextDocuments
+} from "@anvia/core/documents";
+import { embedDocuments } from "@anvia/core/embeddings";
+async function ingestGraphText(options) {
+  return ingestGraphDocuments({
+    graph: options.graph,
+    documents: [options.document],
+    extractionModel: options.extractionModel,
+    embeddingModel: options.embeddingModel,
+    chunking: options.chunking,
+    entityText: options.entityText,
+    instructions: options.instructions,
+    retries: options.retries,
+    concurrency: options.concurrency,
+    abortSignal: options.abortSignal,
+    conflict: options.conflict,
+    orphanEntities: options.orphanEntities
+  });
+}
+async function ingestGraphDocuments(options) {
+  const prepared = await prepareGraphDocuments(options);
+  const write = await options.graph.replaceDocuments({
+    documents: prepared.documents,
+    chunks: prepared.chunks,
+    entities: prepared.entities,
+    relationships: prepared.relationships,
+    mentions: prepared.mentions,
+    conflict: options.conflict,
+    orphanEntities: options.orphanEntities,
+    abortSignal: options.abortSignal
+  });
+  return { ...prepared, write };
+}
+async function prepareGraphDocuments(options) {
+  validatePortableMetadata(options.documents);
+  const chunks = chunkTextDocuments({
+    documents: options.documents,
+    chunking: options.chunking
+  });
+  const graphChunks = chunks.map((chunk) => graphChunk(chunk));
+  const [facts, embeddedChunks] = await Promise.all([
+    extractGraphFacts({
+      model: options.extractionModel,
+      schema: options.graph.schema,
+      chunks: graphChunks,
+      instructions: options.instructions,
+      retries: options.retries,
+      concurrency: options.concurrency,
+      abortSignal: options.abortSignal
+    }),
+    embedDocuments({
+      model: options.embeddingModel,
+      documents: graphChunks,
+      id: (chunk) => chunk.id,
+      content: (chunk) => chunk.text,
+      metadata: (chunk) => chunk.metadata,
+      retries: options.retries,
+      concurrency: options.concurrency,
+      abortSignal: options.abortSignal
+    })
+  ]);
+  const embeddedEntities = await embedDocuments({
+    model: options.embeddingModel,
+    documents: [...facts.output.entities],
+    id: (entity) => entity.key,
+    content: options.entityText ?? defaultGraphEntityText,
+    retries: options.retries,
+    concurrency: options.concurrency,
+    abortSignal: options.abortSignal
+  });
+  const vectorDocuments = groupVectorDocuments(options.documents, embeddedChunks.documents);
+  return {
+    documents: options.documents.map((document) => graphDocument(document)),
+    chunks: embeddedChunks.documents,
+    vectorDocuments,
+    entities: embeddedEntities.documents,
+    relationships: facts.output.relationships,
+    mentions: facts.output.mentions,
+    usage: facts.usage
+  };
+}
+function validatePortableMetadata(documents) {
+  for (const document of documents) {
+    if (document.metadata === void 0) {
+      continue;
+    }
+    const metadata = parseGraphProperties(
+      document.metadata,
+      `Text document ${document.id} metadata`
+    );
+    for (const [key, value] of Object.entries(metadata)) {
+      if (Array.isArray(value)) {
+        throw new TypeError(
+          `Text document ${document.id} metadata.${key} must be a portable primitive value`
+        );
+      }
+    }
+  }
+}
+function groupVectorDocuments(documents, chunks) {
+  const chunksByDocument = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const documentChunks = chunksByDocument.get(chunk.document.documentId);
+    if (documentChunks === void 0) {
+      chunksByDocument.set(chunk.document.documentId, [chunk]);
+    } else {
+      documentChunks.push(chunk);
+    }
+  }
+  return documents.map((document) => {
+    const documentChunks = chunksByDocument.get(document.id);
+    if (documentChunks === void 0) {
+      throw new TypeError(`Text document ${document.id} has no embedded graph chunks`);
+    }
+    const embeddedDocument = {
+      id: document.id,
+      document,
+      embeddings: documentChunks.flatMap((chunk) => chunk.embeddings)
+    };
+    if (document.metadata !== void 0) {
+      embeddedDocument.metadata = document.metadata;
+    }
+    return embeddedDocument;
+  });
+}
+function graphDocument(document) {
+  if (document.metadata === void 0) {
+    return { id: document.id };
+  }
+  return { id: document.id, properties: document.metadata };
+}
+function graphChunk(chunk) {
+  if (chunk.metadata === void 0) {
+    return {
+      id: chunk.id,
+      documentId: chunk.documentId,
+      index: chunk.index,
+      text: chunk.text
+    };
+  }
+  return {
+    id: chunk.id,
+    documentId: chunk.documentId,
+    index: chunk.index,
+    text: chunk.text,
+    metadata: chunk.metadata
+  };
+}
+function defaultGraphEntityText(entity) {
+  const properties2 = Object.entries(entity.properties).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}: ${formatGraphProperty(value)}`).join("\n");
+  return properties2.length === 0 ? entity.type : `${entity.type}
+${properties2}`;
+}
+function formatGraphProperty(value) {
+  if (Array.isArray(value)) {
+    return value.join(", ");
+  }
+  return String(value);
+}
+
+// src/tool.ts
+import { createTool } from "@anvia/core/tool";
+import { z as z3 } from "zod";
+var primitive = z3.union([z3.string(), z3.number().finite(), z3.boolean()]);
+var propertyValue = z3.union([
+  primitive,
+  z3.array(z3.string()),
+  z3.array(z3.number().finite()),
+  z3.array(z3.boolean())
+]);
+var properties = z3.record(z3.string(), propertyValue);
+var contextSchema = z3.object({
+  seeds: z3.array(
+    z3.object({
+      key: z3.string(),
+      type: z3.string(),
+      score: z3.number().finite(),
+      properties,
+      sourceChunkIds: z3.array(z3.string())
+    })
+  ),
+  nodes: z3.array(
+    z3.object({
+      key: z3.string(),
+      type: z3.string(),
+      identity: z3.record(z3.string(), primitive),
+      properties,
+      sourceChunkIds: z3.array(z3.string())
+    })
+  ),
+  relationships: z3.array(
+    z3.object({
+      key: z3.string(),
+      type: z3.string(),
+      from: z3.string(),
+      to: z3.string(),
+      properties,
+      sourceChunkIds: z3.array(z3.string())
+    })
+  ),
+  evidence: z3.array(
+    z3.object({
+      chunkId: z3.string(),
+      documentId: z3.string(),
+      index: z3.number().int(),
+      text: z3.string(),
+      metadata: properties
+    })
+  )
+});
+function createGraphSearchTool(options) {
+  return createTool({
+    name: options.name,
+    description: options.description,
+    inputSchema: z3.object({
+      query: z3.string().min(1).describe("The question or concept to search for in the graph.")
+    }),
+    outputSchema: contextSchema,
+    execute: async ({ query }, context) => await options.graph.retrieve({
+      model: options.model,
+      query,
+      search: options.search,
+      traversal: options.traversal,
+      evidence: options.evidence,
+      retries: options.retries,
+      abortSignal: context.abortSignal
+    })
+  });
+}
+export {
+  GraphFactConflictError,
+  assertGraphName,
+  assertGraphPropertyName,
+  createGraphSearchTool,
+  defineGraphSchema,
+  extractGraphFacts,
+  freezeGraphSchema,
+  graphReservedPropertyPrefix,
+  ingestGraphDocuments,
+  ingestGraphText,
+  parseGraphProperties,
+  parseGraphPropertyValue,
+  prepareGraphDocuments,
+  resolveGraphExploreOptions,
+  validateGraphSchemaOptions
+};
+//# sourceMappingURL=index.js.map