@flowrag/core 0.0.1 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/dist/index.d.mts +160 -0
  2. package/dist/index.mjs +31 -0
  3. package/dist/index.mjs.map +1 -0
  4. package/package.json +41 -6
  5. package/index.js +0 -2
package/dist/index.d.mts ADDED
@@ -0,0 +1,160 @@
1
+ //#region src/interfaces/embedder.d.ts
2
+ /**
3
+ * Embedder interface for FlowRAG
4
+ */
5
+ /** Embedder - generates vector embeddings from text */
6
+ interface Embedder {
7
+ readonly dimensions: number;
8
+ readonly modelName: string;
9
+ embed(text: string): Promise<number[]>;
10
+ embedBatch(texts: string[]): Promise<number[][]>;
11
+ }
12
+ //#endregion
13
+ //#region src/schema.d.ts
14
+ /** Schema configuration input */
15
+ interface SchemaConfig<E extends readonly string[] = readonly string[], R extends readonly string[] = readonly string[]> {
16
+ entityTypes: E;
17
+ relationTypes: R;
18
+ }
19
+ /** Resolved schema with validation */
20
+ interface Schema<E extends readonly string[] = readonly string[], R extends readonly string[] = readonly string[]> {
21
+ entityTypes: E;
22
+ relationTypes: R;
23
+ isValidEntityType: (type: string) => boolean;
24
+ isValidRelationType: (type: string) => boolean;
25
+ normalizeEntityType: (type: string) => E[number] | "Other";
26
+ normalizeRelationType: (type: string) => R[number] | "Other";
27
+ }
28
+ /**
29
+ * Define a schema for entity and relation types.
30
+ * Types are suggestions - if LLM extracts a type not in the list, it falls back to 'Other'.
31
+ */
32
+ declare function defineSchema<const E extends readonly string[], const R extends readonly string[]>(config: SchemaConfig<E, R>): Schema<E, R>;
33
+ //#endregion
34
+ //#region src/types.d.ts
35
+ /**
36
+ * Core types for FlowRAG
37
+ */
38
+ /** Unique identifier */
39
+ type Id = string;
40
+ /** Document - original input file/text */
41
+ interface Document {
42
+ id: Id;
43
+ content: string;
44
+ metadata: DocumentMetadata;
45
+ }
46
+ interface DocumentMetadata {
47
+ filePath?: string;
48
+ title?: string;
49
+ createdAt: Date;
50
+ updatedAt: Date;
51
+ [key: string]: unknown;
52
+ }
53
+ /** Chunk - a piece of a document */
54
+ interface Chunk {
55
+ id: Id;
56
+ documentId: Id;
57
+ content: string;
58
+ index: number;
59
+ tokenCount: number;
60
+ }
61
+ /** Entity - a node in the knowledge graph */
62
+ interface Entity {
63
+ id: Id;
64
+ name: string;
65
+ type: string;
66
+ description: string;
67
+ sourceChunkIds: Id[];
68
+ }
69
+ /** Relation - an edge in the knowledge graph */
70
+ interface Relation {
71
+ id: Id;
72
+ sourceId: Id;
73
+ targetId: Id;
74
+ type: string;
75
+ description: string;
76
+ keywords: string[];
77
+ sourceChunkIds: Id[];
78
+ }
79
+ /** Vector record for storage */
80
+ interface VectorRecord {
81
+ id: Id;
82
+ vector: number[];
83
+ metadata: Record<string, unknown>;
84
+ }
85
+ /** Search result from vector storage */
86
+ interface SearchResult {
87
+ id: Id;
88
+ score: number;
89
+ metadata: Record<string, unknown>;
90
+ }
91
+ /** Filter for vector search */
92
+ interface VectorFilter {
93
+ [field: string]: unknown;
94
+ }
95
+ /** Filter for entity queries */
96
+ interface EntityFilter {
97
+ type?: string;
98
+ name?: string;
99
+ }
100
+ /** Direction for relation queries */
101
+ type RelationDirection = "in" | "out" | "both";
102
+ /** Extracted entity from LLM */
103
+ interface ExtractedEntity {
104
+ name: string;
105
+ type: string;
106
+ description: string;
107
+ }
108
+ /** Extracted relation from LLM */
109
+ interface ExtractedRelation {
110
+ source: string;
111
+ target: string;
112
+ type: string;
113
+ description: string;
114
+ keywords: string[];
115
+ }
116
+ /** Result of entity extraction */
117
+ interface ExtractionResult {
118
+ entities: ExtractedEntity[];
119
+ relations: ExtractedRelation[];
120
+ }
121
+ /** Query modes */
122
+ type QueryMode = "local" | "global" | "hybrid" | "naive";
123
+ //#endregion
124
+ //#region src/interfaces/extractor.d.ts
125
+ /** LLM Extractor - extracts entities and relations from text */
126
+ interface LLMExtractor {
127
+ extractEntities(content: string, knownEntities: string[], schema: Schema): Promise<ExtractionResult>;
128
+ }
129
+ //#endregion
130
+ //#region src/interfaces/storage.d.ts
131
+ /** KV Storage - for documents, chunks, and cache */
132
+ interface KVStorage {
133
+ get<T>(key: string): Promise<T | null>;
134
+ set<T>(key: string, value: T): Promise<void>;
135
+ delete(key: string): Promise<void>;
136
+ list(prefix?: string): Promise<string[]>;
137
+ clear(): Promise<void>;
138
+ }
139
+ /** Vector Storage - for embeddings and semantic search */
140
+ interface VectorStorage {
141
+ upsert(records: VectorRecord[]): Promise<void>;
142
+ search(vector: number[], limit: number, filter?: VectorFilter): Promise<SearchResult[]>;
143
+ delete(ids: Id[]): Promise<void>;
144
+ count(): Promise<number>;
145
+ }
146
+ /** Graph Storage - for entities and relations */
147
+ interface GraphStorage {
148
+ addEntity(entity: Entity): Promise<void>;
149
+ addRelation(relation: Relation): Promise<void>;
150
+ getEntity(id: Id): Promise<Entity | null>;
151
+ getEntities(filter?: EntityFilter): Promise<Entity[]>;
152
+ getRelations(entityId: Id, direction?: RelationDirection): Promise<Relation[]>;
153
+ traverse(startId: Id, depth: number, relationTypes?: string[]): Promise<Entity[]>;
154
+ findPath(fromId: Id, toId: Id, maxDepth?: number): Promise<Relation[]>;
155
+ deleteEntity(id: Id): Promise<void>;
156
+ deleteRelation(id: Id): Promise<void>;
157
+ }
158
+ //#endregion
159
+ export { Chunk, Document, DocumentMetadata, Embedder, Entity, EntityFilter, ExtractedEntity, ExtractedRelation, ExtractionResult, GraphStorage, Id, KVStorage, LLMExtractor, QueryMode, Relation, RelationDirection, Schema, SchemaConfig, SearchResult, VectorFilter, VectorRecord, VectorStorage, defineSchema };
160
+ //# sourceMappingURL=index.d.mts.map
package/dist/index.mjs ADDED
@@ -0,0 +1,31 @@
1
+ import { z } from "zod";
2
+
3
+ //#region src/schema.ts
4
+ /**
5
+ * Schema definition for FlowRAG
6
+ */
7
+ const schemaConfigSchema = z.object({
8
+ entityTypes: z.array(z.string()).min(1),
9
+ relationTypes: z.array(z.string()).min(1)
10
+ });
11
+ /**
12
+ * Define a schema for entity and relation types.
13
+ * Types are suggestions - if LLM extracts a type not in the list, it falls back to 'Other'.
14
+ */
15
+ function defineSchema(config) {
16
+ schemaConfigSchema.parse(config);
17
+ const entitySet = new Set(config.entityTypes);
18
+ const relationSet = new Set(config.relationTypes);
19
+ return {
20
+ entityTypes: config.entityTypes,
21
+ relationTypes: config.relationTypes,
22
+ isValidEntityType: (type) => entitySet.has(type),
23
+ isValidRelationType: (type) => relationSet.has(type),
24
+ normalizeEntityType: (type) => entitySet.has(type) ? type : "Other",
25
+ normalizeRelationType: (type) => relationSet.has(type) ? type : "Other"
26
+ };
27
+ }
28
+
29
+ //#endregion
30
+ export { defineSchema };
31
+ //# sourceMappingURL=index.mjs.map
package/dist/index.mjs.map ADDED
@@ -0,0 +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"}
package/package.json CHANGED
@@ -1,12 +1,47 @@
1
1
  {
2
2
  "name": "@flowrag/core",
3
- "version": "0.0.1",
4
- "description": "FlowRAG core - placeholder package",
5
- "main": "index.js",
6
- "author": "Zweer <n.olivieriachille@gmail.com>",
7
- "license": "MIT",
3
+ "version": "1.0.1",
4
+ "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.",
5
+ "keywords": [
6
+ "interfaces",
7
+ "schema",
8
+ "pipeline",
9
+ "types",
10
+ "zod"
11
+ ],
12
+ "homepage": "https://github.com/Zweer/FlowRAG#readme",
13
+ "bugs": {
14
+ "url": "https://github.com/Zweer/FlowRAG/issues"
15
+ },
8
16
  "repository": {
9
17
  "type": "git",
10
- "url": "https://github.com/Zweer/FlowRAG.git"
18
+ "url": "git+https://github.com/Zweer/FlowRAG.git",
19
+ "directory": "packages/core"
20
+ },
21
+ "license": "MIT",
22
+ "author": {
23
+ "name": "Zweer",
24
+ "email": "n.olivieriachille@gmail.com"
25
+ },
26
+ "type": "module",
27
+ "exports": {
28
+ ".": "./dist/index.mjs",
29
+ "./package.json": "./package.json"
30
+ },
31
+ "main": "./dist/index.mjs",
32
+ "module": "./dist/index.mjs",
33
+ "types": "./dist/index.d.mts",
34
+ "files": [
35
+ "dist"
36
+ ],
37
+ "dependencies": {
38
+ "zod": "^4.3.5"
39
+ },
40
+ "engines": {
41
+ "node": ">=20"
42
+ },
43
+ "publishConfig": {
44
+ "access": "public",
45
+ "provenance": true
11
46
  }
12
47
  }
package/index.js DELETED
@@ -1,2 +0,0 @@
1
- // Placeholder for @flowrag/core
2
- module.exports = {};