Skip to content

Interfaces

FlowRAG is built on pluggable interfaces. Implement any of these to add custom storage backends or AI providers.

Key-value storage for documents, chunks, LLM cache, and document hashes.

interface KVStorage {
get<T>(key: string): Promise<T | null>;
set<T>(key: string, value: T): Promise<void>;
delete(key: string): Promise<void>;
list(prefix?: string): Promise<string[]>;
clear(): Promise<void>;
}

Implementations: JsonKVStorage (files), S3KVStorage (S3), RedisKVStorage (Redis)

Vector embeddings for semantic search.

interface VectorStorage {
upsert(records: VectorRecord[]): Promise<void>;
search(vector: number[], limit: number, filter?: Filter): Promise<SearchResult[]>;
delete(ids: string[]): Promise<void>;
count(): Promise<number>;
}

Implementations: LanceDBVectorStorage, SQLiteVectorStorage, OpenSearchVectorStorage, RedisVectorStorage

Knowledge graph with entities and relations.

interface GraphStorage {
addEntity(entity: Entity): Promise<void>;
addRelation(relation: Relation): Promise<void>;
getEntity(id: string): Promise<Entity | null>;
getEntities(filter?: EntityFilter): Promise<Entity[]>;
getRelations(entityId: string, direction?: 'in' | 'out' | 'both'): Promise<Relation[]>;
traverse(startId: string, depth: number, relationTypes?: string[]): Promise<Entity[]>;
findPath(fromId: string, toId: string, maxDepth?: number): Promise<Relation[]>;
deleteEntity(id: string): Promise<void>;
deleteRelation(id: string): Promise<void>;
}

Implementations: SQLiteGraphStorage, OpenSearchGraphStorage

interface Embedder {
readonly dimensions: number;
readonly modelName: string;
embed(text: string): Promise<number[]>;
embedBatch(texts: string[]): Promise<number[][]>;
}

Implementations: LocalEmbedder (ONNX), GeminiEmbedder, BedrockEmbedder, OpenAIEmbedder

interface LLMExtractor {
extractEntities(
content: string,
knownEntities: string[],
schema: Schema,
): Promise<ExtractionResult>;
}
interface ExtractionResult {
entities: ExtractedEntity[];
relations: ExtractedRelation[];
}

Implementations: GeminiExtractor, BedrockExtractor, OpenAIExtractor, AnthropicExtractor

interface Reranker {
rerank(query: string, documents: RerankDocument[], limit?: number): Promise<RerankResult[]>;
}
interface RerankDocument {
id: string;
content: string;
score: number;
}
interface RerankResult {
id: string;
score: number;
index: number;
}

Implementations: LocalReranker (ONNX), GeminiReranker, BedrockReranker, OpenAIReranker, AnthropicReranker

Wrap any storage set with withNamespace for tenant isolation:

import { withNamespace } from '@flowrag/core';
const storage = withNamespace({ kv, vector, graph }, 'tenant-123');

KV keys and graph entity/relation IDs are transparently prefixed. Vector records get a __ns metadata field for filtered search. See Multi-Tenancy guide for details.

interface DocumentParser {
readonly supportedExtensions: string[];
parse(filePath: string): Promise<ParsedDocument>;
}
interface ParsedDocument {
content: string;
metadata: Record<string, unknown>;
}

Pluggable file parsing for non-text documents. Register parsers via parsers: [...] in the FlowRAG config. Files with matching extensions are parsed instead of read as plain text.

interface Evaluator {
evaluate(query: string, documents: EvalDocument[], reference?: string): Promise<EvalResult>;
}
interface EvalDocument {
content: string;
score: number;
}
interface EvalResult {
scores: Record<string, number>;
}

Pluggable RAG quality evaluation. Call rag.evaluate(query, { reference }) to run a search and pass results to the evaluator.

interface Entity {
id: string;
name: string;
type: string;
description: string;
sourceChunkIds: string[];
fields?: Record<string, unknown>;
}
interface Relation {
id: string;
sourceId: string;
targetId: string;
type: string;
description: string;
keywords: string[];
sourceChunkIds: string[];
fields?: Record<string, unknown>;
}
interface EntitySearchResult {
entity: Entity;
score: number;
}