@flowrag/core 1.4.0 → 1.6.0

package/dist/index.d.mts

@@ -10,6 +10,21 @@ interface Embedder {
   embedBatch(texts: string[]): Promise<number[][]>;
 }
 //#endregion
+//#region src/interfaces/evaluator.d.ts
+/** Document passed to an evaluator */
+interface EvalDocument {
+  content: string;
+  score: number;
+}
+/** Evaluation result with named scores */
+interface EvalResult {
+  scores: Record<string, number>;
+}
+/** Pluggable evaluator for RAG quality metrics */
+interface Evaluator {
+  evaluate(query: string, documents: EvalDocument[], reference?: string): Promise<EvalResult>;
+}
+//#endregion
 //#region src/schema.d.ts
 /** Custom field definition */
 interface FieldDefinition {
@@ -131,10 +146,17 @@ interface ExtractedRelation {
   keywords: string[];
   fields?: Record<string, unknown>;
 }
+/** Token usage from LLM/embedding calls */
+interface TokenUsage {
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+}
 /** Result of entity extraction */
 interface ExtractionResult {
   entities: ExtractedEntity[];
   relations: ExtractedRelation[];
+  usage?: TokenUsage;
 }
 /** Query modes */
 type QueryMode = "local" | "global" | "hybrid" | "naive";
@@ -145,6 +167,18 @@ interface LLMExtractor {
   extractEntities(content: string, knownEntities: string[], schema: Schema): Promise<ExtractionResult>;
 }
 //#endregion
+//#region src/interfaces/parser.d.ts
+/** Parsed document output from a DocumentParser */
+interface ParsedDocument {
+  content: string;
+  metadata: Record<string, unknown>;
+}
+/** Pluggable file parser for non-text documents (PDF, DOCX, images, etc.) */
+interface DocumentParser {
+  readonly supportedExtensions: string[];
+  parse(filePath: string): Promise<ParsedDocument>;
+}
+//#endregion
 //#region src/interfaces/reranker.d.ts
 /**
 * Reranker interface for FlowRAG
@@ -195,11 +229,21 @@ interface GraphStorage {
   deleteRelation(id: Id): Promise<void>;
 }
 //#endregion
+//#region src/namespace.d.ts
+/** Storage set for FlowRAG */
+interface StorageSet {
+  kv: KVStorage;
+  vector: VectorStorage;
+  graph: GraphStorage;
+}
+/** Wrap storage with namespace isolation for multi-tenancy. */
+declare function withNamespace(storage: StorageSet, namespace: string): StorageSet;
+//#endregion
 //#region src/prompt.d.ts
 /**
 * Build the standard entity extraction prompt used by all LLM providers.
 */
 declare function buildExtractionPrompt(content: string, knownEntities: string[], schema: Schema): string;
 //#endregion
-export { Chunk, Document, DocumentMetadata, Embedder, Entity, EntityFilter, ExtractedEntity, ExtractedRelation, ExtractionResult, FieldDefinition, GraphStorage, Id, KVStorage, LLMExtractor, QueryMode, Relation, RelationDirection, RerankDocument, RerankResult, Reranker, Schema, SchemaConfig, SearchResult, VectorFilter, VectorRecord, VectorStorage, buildExtractionPrompt, defineSchema };
+export { Chunk, Document, DocumentMetadata, DocumentParser, Embedder, Entity, EntityFilter, EvalDocument, EvalResult, Evaluator, ExtractedEntity, ExtractedRelation, ExtractionResult, FieldDefinition, GraphStorage, Id, KVStorage, LLMExtractor, ParsedDocument, QueryMode, Relation, RelationDirection, RerankDocument, RerankResult, Reranker, Schema, SchemaConfig, SearchResult, StorageSet, TokenUsage, VectorFilter, VectorRecord, VectorStorage, buildExtractionPrompt, defineSchema, withNamespace };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,5 +1,139 @@
 import { z } from "zod";
 
+//#region src/namespace.ts
+function pfx(ns, id) {
+	return `${ns}:${id}`;
+}
+function unpfx(ns, id) {
+	return id.slice(ns.length + 1);
+}
+var NamespacedKVStorage = class {
+	constructor(inner, ns) {
+		this.inner = inner;
+		this.ns = ns;
+	}
+	get(key) {
+		return this.inner.get(pfx(this.ns, key));
+	}
+	set(key, value) {
+		return this.inner.set(pfx(this.ns, key), value);
+	}
+	delete(key) {
+		return this.inner.delete(pfx(this.ns, key));
+	}
+	async list(prefix) {
+		return (await this.inner.list(pfx(this.ns, prefix ?? ""))).map((k) => unpfx(this.ns, k));
+	}
+	async clear() {
+		const keys = await this.inner.list(`${this.ns}:`);
+		await Promise.all(keys.map((k) => this.inner.delete(k)));
+	}
+};
+var NamespacedVectorStorage = class {
+	constructor(inner, ns) {
+		this.inner = inner;
+		this.ns = ns;
+	}
+	upsert(records) {
+		return this.inner.upsert(records.map((r) => ({
+			...r,
+			id: pfx(this.ns, r.id),
+			metadata: {
+				...r.metadata,
+				__ns: this.ns
+			}
+		})));
+	}
+	async search(vector, limit, filter) {
+		return (await this.inner.search(vector, limit, {
+			...filter,
+			__ns: this.ns
+		})).map((r) => ({
+			...r,
+			id: unpfx(this.ns, r.id),
+			metadata: {
+				...r.metadata,
+				__ns: void 0
+			}
+		}));
+	}
+	delete(ids) {
+		return this.inner.delete(ids.map((id) => pfx(this.ns, id)));
+	}
+	count() {
+		return this.inner.count();
+	}
+};
+var NamespacedGraphStorage = class {
+	constructor(inner, ns) {
+		this.inner = inner;
+		this.ns = ns;
+	}
+	addEntity(entity) {
+		return this.inner.addEntity({
+			...entity,
+			id: pfx(this.ns, entity.id),
+			sourceChunkIds: entity.sourceChunkIds.map((id) => pfx(this.ns, id))
+		});
+	}
+	addRelation(relation) {
+		return this.inner.addRelation({
+			...relation,
+			id: pfx(this.ns, relation.id),
+			sourceId: pfx(this.ns, relation.sourceId),
+			targetId: pfx(this.ns, relation.targetId),
+			sourceChunkIds: relation.sourceChunkIds.map((id) => pfx(this.ns, id))
+		});
+	}
+	async getEntity(id) {
+		const e = await this.inner.getEntity(pfx(this.ns, id));
+		return e ? this.unpfxEntity(e) : null;
+	}
+	async getEntities(filter) {
+		return (await this.inner.getEntities(filter)).filter((e) => e.id.startsWith(`${this.ns}:`)).map((e) => this.unpfxEntity(e));
+	}
+	async getRelations(entityId, direction) {
+		return (await this.inner.getRelations(pfx(this.ns, entityId), direction)).map((r) => this.unpfxRelation(r));
+	}
+	async traverse(startId, depth, relationTypes) {
+		return (await this.inner.traverse(pfx(this.ns, startId), depth, relationTypes)).map((e) => this.unpfxEntity(e));
+	}
+	async findPath(fromId, toId, maxDepth) {
+		return (await this.inner.findPath(pfx(this.ns, fromId), pfx(this.ns, toId), maxDepth)).map((r) => this.unpfxRelation(r));
+	}
+	deleteEntity(id) {
+		return this.inner.deleteEntity(pfx(this.ns, id));
+	}
+	deleteRelation(id) {
+		return this.inner.deleteRelation(pfx(this.ns, id));
+	}
+	unpfxEntity(e) {
+		return {
+			...e,
+			id: unpfx(this.ns, e.id),
+			sourceChunkIds: e.sourceChunkIds.map((id) => unpfx(this.ns, id))
+		};
+	}
+	unpfxRelation(r) {
+		return {
+			...r,
+			id: unpfx(this.ns, r.id),
+			sourceId: unpfx(this.ns, r.sourceId),
+			targetId: unpfx(this.ns, r.targetId),
+			sourceChunkIds: r.sourceChunkIds.map((id) => unpfx(this.ns, id))
+		};
+	}
+};
+/** Wrap storage with namespace isolation for multi-tenancy. */
+function withNamespace(storage, namespace) {
+	return {
+		kv: new NamespacedKVStorage(storage.kv, namespace),
+		vector: new NamespacedVectorStorage(storage.vector, namespace),
+		graph: new NamespacedGraphStorage(storage.graph, namespace)
+	};
+}
+
+//#endregion
 //#region src/prompt.ts
 /**
 * Build the standard entity extraction prompt used by all LLM providers.
@@ -72,5 +206,5 @@ function defineSchema(config) {
 }
 
 //#endregion
-export { buildExtractionPrompt, defineSchema };
+export { buildExtractionPrompt, defineSchema, withNamespace };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/prompt.ts","../src/schema.ts"],"sourcesContent":["import type { Schema } from './schema.js';\n\n/**\n * Build the standard entity extraction prompt used by all LLM providers.\n */\nexport function buildExtractionPrompt(\n  content: string,\n  knownEntities: string[],\n  schema: Schema,\n): string {\n  const entityTypes = schema.entityTypes.join(', ');\n  const relationTypes = schema.relationTypes.join(', ');\n  const knownEntitiesList =\n    knownEntities.length > 0 ? `\\n\\nKnown entities to reference: ${knownEntities.join(', ')}` : '';\n\n  const entityFieldsDef =\n    Object.keys(schema.entityFields).length > 0\n      ? `\\n\\nEntity custom fields: ${JSON.stringify(schema.entityFields)}`\n      : '';\n  const relationFieldsDef =\n    Object.keys(schema.relationFields).length > 0\n      ? `\\n\\nRelation custom fields: ${JSON.stringify(schema.relationFields)}`\n      : '';\n\n  const fieldsInstruction =\n    entityFieldsDef || relationFieldsDef\n      ? '\\nInclude a \"fields\" object in each entity/relation with the custom field values when applicable.'\n      : '';\n\n  return `Extract entities and relations from the following content.\n\nEntity types: ${entityTypes}\nRelation types: ${relationTypes}${knownEntitiesList}${entityFieldsDef}${relationFieldsDef}\n\nContent:\n${content}\n\nReturn a JSON object with this structure:\n{\n  \"entities\": [\n    {\n      \"name\": \"entity name\",\n      \"type\": \"entity type from the list above, or 'Other' if not matching\",\n      \"description\": \"brief description of the entity\"${entityFieldsDef ? ',\\n      \"fields\": {}' : ''}\n    }\n  ],\n  \"relations\": [\n    {\n      \"source\": \"source entity name\",\n      \"target\": \"target entity name\",\n      \"type\": \"relation type from the list above\",\n      \"description\": \"description of the relationship\",\n      \"keywords\": [\"keyword1\", \"keyword2\"]${relationFieldsDef ? ',\\n      \"fields\": {}' : ''}\n    }\n  ]\n}\n\nFocus on technical entities and their relationships. Be precise and avoid duplicates.${fieldsInstruction}`;\n}\n","/**\n * Schema definition for FlowRAG\n */\n\nimport { z } from 'zod';\n\n/** Custom field definition */\nexport interface FieldDefinition {\n  type: 'string' | 'enum';\n  values?: string[];\n  default?: string;\n  filterable?: boolean;\n}\n\n/** Schema configuration input */\nexport interface SchemaConfig<\n  E extends readonly string[] = readonly string[],\n  R extends readonly string[] = readonly string[],\n> {\n  entityTypes: E;\n  relationTypes: R;\n  documentFields?: Record<string, FieldDefinition>;\n  entityFields?: Record<string, FieldDefinition>;\n  relationFields?: Record<string, FieldDefinition>;\n}\n\n/** Resolved schema with validation */\nexport interface Schema<\n  E extends readonly string[] = readonly string[],\n  R extends readonly string[] = readonly string[],\n> {\n  entityTypes: E;\n  relationTypes: R;\n  documentFields: Record<string, FieldDefinition>;\n  entityFields: Record<string, FieldDefinition>;\n  relationFields: Record<string, FieldDefinition>;\n  isValidEntityType: (type: string) => boolean;\n  isValidRelationType: (type: string) => boolean;\n  normalizeEntityType: (type: string) => E[number] | 'Other';\n  normalizeRelationType: (type: string) => R[number] | 'Other';\n}\n\nconst schemaConfigSchema = z.object({\n  entityTypes: z.array(z.string()).min(1),\n  relationTypes: z.array(z.string()).min(1),\n});\n\n/**\n * Define a schema for entity and relation types.\n * Types are suggestions - if LLM extracts a type not in the list, it falls back to 'Other'.\n */\nexport function defineSchema<const E extends readonly string[], const R extends readonly string[]>(\n  config: SchemaConfig<E, R>,\n): Schema<E, R> {\n  schemaConfigSchema.parse(config);\n\n  const entitySet = new Set<string>(config.entityTypes);\n  const relationSet = new Set<string>(config.relationTypes);\n\n  return {\n    entityTypes: config.entityTypes,\n    relationTypes: config.relationTypes,\n    documentFields: config.documentFields ?? {},\n    entityFields: config.entityFields ?? {},\n    relationFields: config.relationFields ?? {},\n    isValidEntityType: (type: string) => entitySet.has(type),\n    isValidRelationType: (type: string) => relationSet.has(type),\n    normalizeEntityType: (type: string) => (entitySet.has(type) ? (type as E[number]) : 'Other'),\n    normalizeRelationType: (type: string) =>\n      relationSet.has(type) ? (type as R[number]) : 'Other',\n  };\n}\n"],"mappings":";;;;;;AAKA,SAAgB,sBACd,SACA,eACA,QACQ;CACR,MAAM,cAAc,OAAO,YAAY,KAAK,KAAK;CACjD,MAAM,gBAAgB,OAAO,cAAc,KAAK,KAAK;CACrD,MAAM,oBACJ,cAAc,SAAS,IAAI,oCAAoC,cAAc,KAAK,KAAK,KAAK;CAE9F,MAAM,kBACJ,OAAO,KAAK,OAAO,aAAa,CAAC,SAAS,IACtC,6BAA6B,KAAK,UAAU,OAAO,aAAa,KAChE;CACN,MAAM,oBACJ,OAAO,KAAK,OAAO,eAAe,CAAC,SAAS,IACxC,+BAA+B,KAAK,UAAU,OAAO,eAAe,KACpE;AAON,QAAO;;gBAEO,YAAY;kBACV,gBAAgB,oBAAoB,kBAAkB,kBAAkB;;;EAGxF,QAAQ;;;;;;;;wDAQ8C,kBAAkB,4BAA0B,GAAG;;;;;;;;;4CAS3D,oBAAoB,4BAA0B,GAAG;;;;;uFA3BzF,mBAAmB,oBACf,wGACA;;;;;;;;ACeR,MAAM,qBAAqB,EAAE,OAAO;CAClC,aAAa,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,IAAI,EAAE;CACvC,eAAe,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,IAAI,EAAE;CAC1C,CAAC;;;;;AAMF,SAAgB,aACd,QACc;AACd,oBAAmB,MAAM,OAAO;CAEhC,MAAM,YAAY,IAAI,IAAY,OAAO,YAAY;CACrD,MAAM,cAAc,IAAI,IAAY,OAAO,cAAc;AAEzD,QAAO;EACL,aAAa,OAAO;EACpB,eAAe,OAAO;EACtB,gBAAgB,OAAO,kBAAkB,EAAE;EAC3C,cAAc,OAAO,gBAAgB,EAAE;EACvC,gBAAgB,OAAO,kBAAkB,EAAE;EAC3C,oBAAoB,SAAiB,UAAU,IAAI,KAAK;EACxD,sBAAsB,SAAiB,YAAY,IAAI,KAAK;EAC5D,sBAAsB,SAAkB,UAAU,IAAI,KAAK,GAAI,OAAqB;EACpF,wBAAwB,SACtB,YAAY,IAAI,KAAK,GAAI,OAAqB;EACjD"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/namespace.ts","../src/prompt.ts","../src/schema.ts"],"sourcesContent":["/**\n * Multi-tenancy namespace wrappers for storage isolation.\n */\n\nimport type { GraphStorage, KVStorage, VectorStorage } from './interfaces/storage.js';\nimport type {\n  Entity,\n  EntityFilter,\n  Id,\n  Relation,\n  RelationDirection,\n  SearchResult,\n  VectorFilter,\n  VectorRecord,\n} from './types.js';\n\nfunction pfx(ns: string, id: string): string {\n  return `${ns}:${id}`;\n}\n\nfunction unpfx(ns: string, id: string): string {\n  return id.slice(ns.length + 1);\n}\n\nclass NamespacedKVStorage implements KVStorage {\n  constructor(\n    private inner: KVStorage,\n    private ns: string,\n  ) {}\n\n  get<T>(key: string): Promise<T | null> {\n    return this.inner.get<T>(pfx(this.ns, key));\n  }\n\n  set<T>(key: string, value: T): Promise<void> {\n    return this.inner.set(pfx(this.ns, key), value);\n  }\n\n  delete(key: string): Promise<void> {\n    return this.inner.delete(pfx(this.ns, key));\n  }\n\n  async list(prefix?: string): Promise<string[]> {\n    const keys = await this.inner.list(pfx(this.ns, prefix ?? ''));\n    return keys.map((k) => unpfx(this.ns, k));\n  }\n\n  async clear(): Promise<void> {\n    const keys = await this.inner.list(`${this.ns}:`);\n    await Promise.all(keys.map((k) => this.inner.delete(k)));\n  }\n}\n\nclass NamespacedVectorStorage implements VectorStorage {\n  constructor(\n    private inner: VectorStorage,\n    private ns: string,\n  ) {}\n\n  upsert(records: VectorRecord[]): Promise<void> {\n    return this.inner.upsert(\n      records.map((r) => ({\n        ...r,\n        id: pfx(this.ns, r.id),\n        metadata: { ...r.metadata, __ns: this.ns },\n      })),\n    );\n  }\n\n  async search(vector: number[], limit: number, filter?: VectorFilter): Promise<SearchResult[]> {\n    const results = await this.inner.search(vector, limit, { ...filter, __ns: this.ns });\n    return results.map((r) => ({\n      ...r,\n      id: unpfx(this.ns, r.id),\n      metadata: { ...r.metadata, __ns: undefined },\n    }));\n  }\n\n  delete(ids: Id[]): Promise<void> {\n    return this.inner.delete(ids.map((id) => pfx(this.ns, id)));\n  }\n\n  count(): Promise<number> {\n    return this.inner.count();\n  }\n}\n\nclass NamespacedGraphStorage implements GraphStorage {\n  constructor(\n    private inner: GraphStorage,\n    private ns: string,\n  ) {}\n\n  addEntity(entity: Entity): Promise<void> {\n    return this.inner.addEntity({\n      ...entity,\n      id: pfx(this.ns, entity.id),\n      sourceChunkIds: entity.sourceChunkIds.map((id) => pfx(this.ns, id)),\n    });\n  }\n\n  addRelation(relation: Relation): Promise<void> {\n    return this.inner.addRelation({\n      ...relation,\n      id: pfx(this.ns, relation.id),\n      sourceId: pfx(this.ns, relation.sourceId),\n      targetId: pfx(this.ns, relation.targetId),\n      sourceChunkIds: relation.sourceChunkIds.map((id) => pfx(this.ns, id)),\n    });\n  }\n\n  async getEntity(id: Id): Promise<Entity | null> {\n    const e = await this.inner.getEntity(pfx(this.ns, id));\n    return e ? this.unpfxEntity(e) : null;\n  }\n\n  async getEntities(filter?: EntityFilter): Promise<Entity[]> {\n    const all = await this.inner.getEntities(filter);\n    return all.filter((e) => e.id.startsWith(`${this.ns}:`)).map((e) => this.unpfxEntity(e));\n  }\n\n  async getRelations(entityId: Id, direction?: RelationDirection): Promise<Relation[]> {\n    const rels = await this.inner.getRelations(pfx(this.ns, entityId), direction);\n    return rels.map((r) => this.unpfxRelation(r));\n  }\n\n  async traverse(startId: Id, depth: number, relationTypes?: string[]): Promise<Entity[]> {\n    const entities = await this.inner.traverse(pfx(this.ns, startId), depth, relationTypes);\n    return entities.map((e) => this.unpfxEntity(e));\n  }\n\n  async findPath(fromId: Id, toId: Id, maxDepth?: number): Promise<Relation[]> {\n    const rels = await this.inner.findPath(pfx(this.ns, fromId), pfx(this.ns, toId), maxDepth);\n    return rels.map((r) => this.unpfxRelation(r));\n  }\n\n  deleteEntity(id: Id): Promise<void> {\n    return this.inner.deleteEntity(pfx(this.ns, id));\n  }\n\n  deleteRelation(id: Id): Promise<void> {\n    return this.inner.deleteRelation(pfx(this.ns, id));\n  }\n\n  private unpfxEntity(e: Entity): Entity {\n    return {\n      ...e,\n      id: unpfx(this.ns, e.id),\n      sourceChunkIds: e.sourceChunkIds.map((id) => unpfx(this.ns, id)),\n    };\n  }\n\n  private unpfxRelation(r: Relation): Relation {\n    return {\n      ...r,\n      id: unpfx(this.ns, r.id),\n      sourceId: unpfx(this.ns, r.sourceId),\n      targetId: unpfx(this.ns, r.targetId),\n      sourceChunkIds: r.sourceChunkIds.map((id) => unpfx(this.ns, id)),\n    };\n  }\n}\n\n/** Storage set for FlowRAG */\nexport interface StorageSet {\n  kv: KVStorage;\n  vector: VectorStorage;\n  graph: GraphStorage;\n}\n\n/** Wrap storage with namespace isolation for multi-tenancy. */\nexport function withNamespace(storage: StorageSet, namespace: string): StorageSet {\n  return {\n    kv: new NamespacedKVStorage(storage.kv, namespace),\n    vector: new NamespacedVectorStorage(storage.vector, namespace),\n    graph: new NamespacedGraphStorage(storage.graph, namespace),\n  };\n}\n","import type { Schema } from './schema.js';\n\n/**\n * Build the standard entity extraction prompt used by all LLM providers.\n */\nexport function buildExtractionPrompt(\n  content: string,\n  knownEntities: string[],\n  schema: Schema,\n): string {\n  const entityTypes = schema.entityTypes.join(', ');\n  const relationTypes = schema.relationTypes.join(', ');\n  const knownEntitiesList =\n    knownEntities.length > 0 ? `\\n\\nKnown entities to reference: ${knownEntities.join(', ')}` : '';\n\n  const entityFieldsDef =\n    Object.keys(schema.entityFields).length > 0\n      ? `\\n\\nEntity custom fields: ${JSON.stringify(schema.entityFields)}`\n      : '';\n  const relationFieldsDef =\n    Object.keys(schema.relationFields).length > 0\n      ? `\\n\\nRelation custom fields: ${JSON.stringify(schema.relationFields)}`\n      : '';\n\n  const fieldsInstruction =\n    entityFieldsDef || relationFieldsDef\n      ? '\\nInclude a \"fields\" object in each entity/relation with the custom field values when applicable.'\n      : '';\n\n  return `Extract entities and relations from the following content.\n\nEntity types: ${entityTypes}\nRelation types: ${relationTypes}${knownEntitiesList}${entityFieldsDef}${relationFieldsDef}\n\nContent:\n${content}\n\nReturn a JSON object with this structure:\n{\n  \"entities\": [\n    {\n      \"name\": \"entity name\",\n      \"type\": \"entity type from the list above, or 'Other' if not matching\",\n      \"description\": \"brief description of the entity\"${entityFieldsDef ? ',\\n      \"fields\": {}' : ''}\n    }\n  ],\n  \"relations\": [\n    {\n      \"source\": \"source entity name\",\n      \"target\": \"target entity name\",\n      \"type\": \"relation type from the list above\",\n      \"description\": \"description of the relationship\",\n      \"keywords\": [\"keyword1\", \"keyword2\"]${relationFieldsDef ? ',\\n      \"fields\": {}' : ''}\n    }\n  ]\n}\n\nFocus on technical entities and their relationships. Be precise and avoid duplicates.${fieldsInstruction}`;\n}\n","/**\n * Schema definition for FlowRAG\n */\n\nimport { z } from 'zod';\n\n/** Custom field definition */\nexport interface FieldDefinition {\n  type: 'string' | 'enum';\n  values?: string[];\n  default?: string;\n  filterable?: boolean;\n}\n\n/** Schema configuration input */\nexport interface SchemaConfig<\n  E extends readonly string[] = readonly string[],\n  R extends readonly string[] = readonly string[],\n> {\n  entityTypes: E;\n  relationTypes: R;\n  documentFields?: Record<string, FieldDefinition>;\n  entityFields?: Record<string, FieldDefinition>;\n  relationFields?: Record<string, FieldDefinition>;\n}\n\n/** Resolved schema with validation */\nexport interface Schema<\n  E extends readonly string[] = readonly string[],\n  R extends readonly string[] = readonly string[],\n> {\n  entityTypes: E;\n  relationTypes: R;\n  documentFields: Record<string, FieldDefinition>;\n  entityFields: Record<string, FieldDefinition>;\n  relationFields: Record<string, FieldDefinition>;\n  isValidEntityType: (type: string) => boolean;\n  isValidRelationType: (type: string) => boolean;\n  normalizeEntityType: (type: string) => E[number] | 'Other';\n  normalizeRelationType: (type: string) => R[number] | 'Other';\n}\n\nconst schemaConfigSchema = z.object({\n  entityTypes: z.array(z.string()).min(1),\n  relationTypes: z.array(z.string()).min(1),\n});\n\n/**\n * Define a schema for entity and relation types.\n * Types are suggestions - if LLM extracts a type not in the list, it falls back to 'Other'.\n */\nexport function defineSchema<const E extends readonly string[], const R extends readonly string[]>(\n  config: SchemaConfig<E, R>,\n): Schema<E, R> {\n  schemaConfigSchema.parse(config);\n\n  const entitySet = new Set<string>(config.entityTypes);\n  const relationSet = new Set<string>(config.relationTypes);\n\n  return {\n    entityTypes: config.entityTypes,\n    relationTypes: config.relationTypes,\n    documentFields: config.documentFields ?? {},\n    entityFields: config.entityFields ?? {},\n    relationFields: config.relationFields ?? {},\n    isValidEntityType: (type: string) => entitySet.has(type),\n    isValidRelationType: (type: string) => relationSet.has(type),\n    normalizeEntityType: (type: string) => (entitySet.has(type) ? (type as E[number]) : 'Other'),\n    normalizeRelationType: (type: string) =>\n      relationSet.has(type) ? (type as R[number]) : 'Other',\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowrag/core",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "📐 The heart of FlowRAG. Defines all TypeScript interfaces (Storage, Embedder, LLMExtractor), the Zod-based schema system for defining entity/relation types, and the orchestration pipeline that coordinates indexing and querying. This package contains only contracts and types, no concrete implementations.",
   "keywords": [
     "interfaces",