@flowrag/core 1.0.2 → 1.4.0

package/README.md

@@ -0,0 +1,53 @@
+# @flowrag/core
+
+Interfaces, schema definition, and types for FlowRAG.
+
+## Installation
+
+```bash
+npm install @flowrag/core
+```
+
+## Usage
+
+### Schema Definition
+
+```typescript
+import { defineSchema } from '@flowrag/core';
+
+const schema = defineSchema({
+  entityTypes: ['SERVICE', 'DATABASE', 'PROTOCOL'],
+  relationTypes: ['USES', 'PRODUCES', 'CONSUMES'],
+});
+
+schema.isValidEntityType('SERVICE');     // true
+schema.normalizeEntityType('UNKNOWN');   // 'Other'
+```
+
+### Custom Fields
+
+```typescript
+const schema = defineSchema({
+  entityTypes: ['SERVICE', 'DATABASE'],
+  relationTypes: ['USES', 'PRODUCES'],
+  entityFields: {
+    status: { type: 'enum', values: ['active', 'deprecated'], default: 'active' },
+  },
+  relationFields: {
+    syncType: { type: 'enum', values: ['sync', 'async'] },
+  },
+});
+```
+
+## Interfaces
+
+- `KVStorage` — key-value storage (documents, chunks, cache)
+- `VectorStorage` — vector embeddings for semantic search
+- `GraphStorage` — knowledge graph (entities, relations, traversal)
+- `Embedder` — text to vector embeddings
+- `LLMExtractor` — entity/relation extraction via LLM
+- `Reranker` — post-retrieval result reranking
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -11,15 +11,28 @@ interface Embedder {
 }
 //#endregion
 //#region src/schema.d.ts
+/** Custom field definition */
+interface FieldDefinition {
+  type: "string" | "enum";
+  values?: string[];
+  default?: string;
+  filterable?: boolean;
+}
 /** Schema configuration input */
 interface SchemaConfig<E extends readonly string[] = readonly string[], R extends readonly string[] = readonly string[]> {
   entityTypes: E;
   relationTypes: R;
+  documentFields?: Record<string, FieldDefinition>;
+  entityFields?: Record<string, FieldDefinition>;
+  relationFields?: Record<string, FieldDefinition>;
 }
 /** Resolved schema with validation */
 interface Schema<E extends readonly string[] = readonly string[], R extends readonly string[] = readonly string[]> {
   entityTypes: E;
   relationTypes: R;
+  documentFields: Record<string, FieldDefinition>;
+  entityFields: Record<string, FieldDefinition>;
+  relationFields: Record<string, FieldDefinition>;
   isValidEntityType: (type: string) => boolean;
   isValidRelationType: (type: string) => boolean;
   normalizeEntityType: (type: string) => E[number] | "Other";
@@ -48,6 +61,7 @@ interface DocumentMetadata {
   title?: string;
   createdAt: Date;
   updatedAt: Date;
+  fields?: Record<string, unknown>;
   [key: string]: unknown;
 }
 /** Chunk - a piece of a document */
@@ -65,6 +79,7 @@ interface Entity {
   type: string;
   description: string;
   sourceChunkIds: Id[];
+  fields?: Record<string, unknown>;
 }
 /** Relation - an edge in the knowledge graph */
 interface Relation {
@@ -75,6 +90,7 @@ interface Relation {
   description: string;
   keywords: string[];
   sourceChunkIds: Id[];
+  fields?: Record<string, unknown>;
 }
 /** Vector record for storage */
 interface VectorRecord {
@@ -104,6 +120,7 @@ interface ExtractedEntity {
   name: string;
   type: string;
   description: string;
+  fields?: Record<string, unknown>;
 }
 /** Extracted relation from LLM */
 interface ExtractedRelation {
@@ -112,6 +129,7 @@ interface ExtractedRelation {
   type: string;
   description: string;
   keywords: string[];
+  fields?: Record<string, unknown>;
 }
 /** Result of entity extraction */
 interface ExtractionResult {
@@ -127,6 +145,27 @@ interface LLMExtractor {
   extractEntities(content: string, knownEntities: string[], schema: Schema): Promise<ExtractionResult>;
 }
 //#endregion
+//#region src/interfaces/reranker.d.ts
+/**
+* Reranker interface for FlowRAG
+*/
+/** A scored document to rerank */
+interface RerankDocument {
+  id: string;
+  content: string;
+  score: number;
+}
+/** Result after reranking */
+interface RerankResult {
+  id: string;
+  score: number;
+  index: number;
+}
+/** Reranker - re-scores search results for better relevance */
+interface Reranker {
+  rerank(query: string, documents: RerankDocument[], limit?: number): Promise<RerankResult[]>;
+}
+//#endregion
 //#region src/interfaces/storage.d.ts
 /** KV Storage - for documents, chunks, and cache */
 interface KVStorage {
@@ -156,5 +195,11 @@ interface GraphStorage {
   deleteRelation(id: Id): Promise<void>;
 }
 //#endregion
-export { Chunk, Document, DocumentMetadata, Embedder, Entity, EntityFilter, ExtractedEntity, ExtractedRelation, ExtractionResult, GraphStorage, Id, KVStorage, LLMExtractor, QueryMode, Relation, RelationDirection, Schema, SchemaConfig, SearchResult, VectorFilter, VectorRecord, VectorStorage, defineSchema };
+//#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 };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,5 +1,47 @@
 import { z } from "zod";
 
+//#region src/prompt.ts
+/**
+* Build the standard entity extraction prompt used by all LLM providers.
+*/
+function buildExtractionPrompt(content, knownEntities, schema) {
+	const entityTypes = schema.entityTypes.join(", ");
+	const relationTypes = schema.relationTypes.join(", ");
+	const knownEntitiesList = knownEntities.length > 0 ? `\n\nKnown entities to reference: ${knownEntities.join(", ")}` : "";
+	const entityFieldsDef = Object.keys(schema.entityFields).length > 0 ? `\n\nEntity custom fields: ${JSON.stringify(schema.entityFields)}` : "";
+	const relationFieldsDef = Object.keys(schema.relationFields).length > 0 ? `\n\nRelation custom fields: ${JSON.stringify(schema.relationFields)}` : "";
+	return `Extract entities and relations from the following content.
+
+Entity types: ${entityTypes}
+Relation types: ${relationTypes}${knownEntitiesList}${entityFieldsDef}${relationFieldsDef}
+
+Content:
+${content}
+
+Return a JSON object with this structure:
+{
+  "entities": [
+    {
+      "name": "entity name",
+      "type": "entity type from the list above, or 'Other' if not matching",
+      "description": "brief description of the entity"${entityFieldsDef ? ",\n      \"fields\": {}" : ""}
+    }
+  ],
+  "relations": [
+    {
+      "source": "source entity name",
+      "target": "target entity name",
+      "type": "relation type from the list above",
+      "description": "description of the relationship",
+      "keywords": ["keyword1", "keyword2"]${relationFieldsDef ? ",\n      \"fields\": {}" : ""}
+    }
+  ]
+}
+
+Focus on technical entities and their relationships. Be precise and avoid duplicates.${entityFieldsDef || relationFieldsDef ? "\nInclude a \"fields\" object in each entity/relation with the custom field values when applicable." : ""}`;
+}
+
+//#endregion
 //#region src/schema.ts
 /**
 * Schema definition for FlowRAG
@@ -19,6 +61,9 @@ function defineSchema(config) {
 	return {
 		entityTypes: config.entityTypes,
 		relationTypes: config.relationTypes,
+		documentFields: config.documentFields ?? {},
+		entityFields: config.entityFields ?? {},
+		relationFields: config.relationFields ?? {},
 		isValidEntityType: (type) => entitySet.has(type),
 		isValidRelationType: (type) => relationSet.has(type),
 		normalizeEntityType: (type) => entitySet.has(type) ? type : "Other",
@@ -27,5 +72,5 @@ function defineSchema(config) {
 }
 
 //#endregion
-export { defineSchema };
+export { buildExtractionPrompt, defineSchema };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/schema.ts"],"sourcesContent":["/**\n * Schema definition for FlowRAG\n */\n\nimport { z } from 'zod';\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}\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  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    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":";;;;;;AA4BA,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,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/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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowrag/core",
-  "version": "1.0.2",
+  "version": "1.4.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",
@@ -28,14 +28,12 @@
     ".": "./dist/index.mjs",
     "./package.json": "./package.json"
   },
-  "main": "./dist/index.mjs",
-  "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "files": [
     "dist"
   ],
   "dependencies": {
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   },
   "engines": {
     "node": ">=20"