rax-flow-core 0.1.0

package/src/memory/graph-memory.ts

@@ -0,0 +1,150 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export interface GraphNode {
+    id: string;
+    type: "action" | "artifact" | "concept" | "agent";
+    content: string;
+    metadata: Record<string, any>;
+    timestamp: number;
+}
+
+export interface GraphEdge {
+    from: string;
+    to: string;
+    type: "produced" | "triggered_by" | "depends_on" | "relates_to";
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Quantum Semantic Graph Memory (QSGM) Core.
+ * Manages relationships between actions, artifacts, and concepts.
+ */
+export class GraphMemory {
+    private nodes: Map<string, GraphNode> = new Map();
+    private edges: GraphEdge[] = [];
+
+    constructor(private persistPath?: string) { }
+
+    public addNode(node: GraphNode): void {
+        this.nodes.set(node.id, node);
+    }
+
+    public removeNode(nodeId: string): boolean {
+        if (!this.nodes.has(nodeId)) return false;
+        this.nodes.delete(nodeId);
+        this.edges = this.edges.filter(e => e.from !== nodeId && e.to !== nodeId);
+        return true;
+    }
+
+    public addEdge(edge: GraphEdge): void {
+        this.edges.push(edge);
+    }
+
+    /**
+     * Traverses the graph to find nodes related to a starting point.
+     * Useful for finding "ripple effects" or deep context.
+     */
+    public traverse(startNodeId: string, maxDepth: number = 2): GraphNode[] {
+        const visited = new Set<string>();
+        const results: GraphNode[] = [];
+        const queue: { id: string; depth: number }[] = [{ id: startNodeId, depth: 0 }];
+
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift()!;
+            if (visited.has(id) || depth > maxDepth) continue;
+
+            visited.add(id);
+            const node = this.nodes.get(id);
+            if (node) {
+                results.push(node);
+            }
+
+            // Find neighbors
+            const neighbors = this.edges
+                .filter(e => e.from === id)
+                .map(e => ({ id: e.to, depth: depth + 1 }));
+
+            const reverseNeighbors = this.edges
+                .filter(e => e.to === id)
+                .map(e => ({ id: e.from, depth: depth + 1 }));
+
+            queue.push(...neighbors, ...reverseNeighbors);
+        }
+
+        return results;
+    }
+
+    public async load(): Promise<void> {
+        if (!this.persistPath) return;
+        try {
+            const raw = await readFile(this.persistPath, "utf8");
+            const data = JSON.parse(raw);
+            this.nodes = new Map(Object.entries(data.nodes || {}));
+            this.edges = data.edges || [];
+        } catch {
+            this.nodes = new Map();
+            this.edges = [];
+        }
+    }
+
+    public async save(): Promise<void> {
+        if (!this.persistPath) return;
+        try {
+            await mkdir(path.dirname(this.persistPath), { recursive: true });
+            await writeFile(this.persistPath, JSON.stringify({
+                nodes: Object.fromEntries(this.nodes),
+                edges: this.edges
+            }, null, 2));
+        } catch (err) {
+            console.error("Failed to persist graph memory:", err);
+        }
+    }
+
+    public getNodes(): GraphNode[] {
+        return Array.from(this.nodes.values());
+    }
+
+    public getGraphData(): { nodes: Record<string, GraphNode>; edges: GraphEdge[] } {
+        return {
+            nodes: Object.fromEntries(this.nodes),
+            edges: this.edges
+        };
+    }
+
+    public findByType(type: string): GraphNode[] {
+        return Array.from(this.nodes.values()).filter(n => n.type === type);
+    }
+
+    public search(query: string, limit: number = 5): GraphNode[] {
+        return Array.from(this.nodes.values())
+            .filter(n => n.content?.includes(query) || JSON.stringify(n.metadata).includes(query))
+            .slice(0, limit);
+    }
+
+    public getConnections(nodeId: string): { incoming: GraphNode[]; outgoing: GraphNode[] } {
+        const incoming = this.edges
+            .filter(e => e.to === nodeId)
+            .map(e => this.nodes.get(e.from)!)
+            .filter(Boolean);
+        
+        const outgoing = this.edges
+            .filter(e => e.from === nodeId)
+            .map(e => this.nodes.get(e.to)!)
+            .filter(Boolean);
+
+        return { incoming, outgoing };
+    }
+
+    public getStats(): any {
+        return {
+            nodeCount: this.nodes.size,
+            edgeCount: this.edges.length,
+            nodesByType: Array.from(this.nodes.values()).reduce((acc: Record<string, number>, n) => {
+                acc[n.type] = (acc[n.type] || 0) + 1;
+                return acc;
+            }, {})
+        };
+    }
+}
+

package/src/memory/local-vector-store.ts

@@ -0,0 +1,129 @@
+import { IVectorStore, MemoryDocument, SearchResult } from "../types/contracts.js";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * A lightweight, local vector store using Cosine Similarity.
+ * Suitable for small-to-medium datasets (thousands of records).
+ * Persists data to a simple JSON structure.
+ */
+export class LocalVectorStore implements IVectorStore {
+    private documents: MemoryDocument[] = [];
+    private vectors: number[][] = [];
+    private metadata: Map<string, Record<string, unknown>> = new Map();
+
+    constructor(private persistPath?: string) { }
+
+    async add(documents: MemoryDocument[], vectors: number[][]): Promise<void> {
+        if (documents.length !== vectors.length) {
+            throw new Error("Mismatched documents and vectors count.");
+        }
+        this.documents.push(...documents);
+        this.vectors.push(...vectors);
+        if (this.persistPath) await this.save();
+    }
+
+    async search(queryVector: number[], limit: number = 5): Promise<SearchResult[]> {
+        if (this.vectors.length === 0) return [];
+
+        const results: SearchResult[] = this.vectors.map((vec, i) => {
+            const score = this.cosineSimilarity(queryVector, vec);
+            return { ...this.documents[i], score };
+        });
+
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+
+    async clear(): Promise<void> {
+        this.documents = [];
+        this.vectors = [];
+        this.metadata.clear();
+        if (this.persistPath) await this.save();
+    }
+
+    async delete(docIds: string[]): Promise<void> {
+        for (const id of docIds) {
+            const idx = this.documents.findIndex(d => d.id === id);
+            if (idx >= 0) {
+                this.documents.splice(idx, 1);
+                this.vectors.splice(idx, 1);
+                this.metadata.delete(id);
+            }
+        }
+        if (this.persistPath) await this.save();
+    }
+
+    async searchByMetadata(metadata: Record<string, unknown>): Promise<SearchResult[]> {
+        return this.documents.filter(doc => {
+            const docMeta = this.metadata.get(doc.id) || {};
+            return Object.entries(metadata).every(([key, value]) => docMeta[key] === value);
+        }).map(doc => ({ ...doc, score: 1.0 }));
+    }
+
+    public count(): number {
+        return this.documents.length;
+    }
+
+    public getMetrics() {
+        return {
+            documentCount: this.documents.length,
+            vectorDimensions: this.vectors[0]?.length || 0
+        };
+    }
+
+    /**
+     * Calculates cosine similarity between two numeric vectors.
+     */
+    private cosineSimilarity(vecA: number[], vecB: number[]): number {
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+
+        // Using common length. Error check in a production environment.
+        const len = Math.min(vecA.length, vecB.length);
+        for (let i = 0; i < len; i++) {
+            dotProduct += vecA[i] * vecB[i];
+            normA += vecA[i] * vecA[i];
+            normB += vecB[i] * vecB[i];
+        }
+
+        const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+        if (denominator === 0) return 0;
+        return dotProduct / denominator;
+    }
+
+    /**
+     * Manually triggers a load from the persistence file.
+     */
+    async load(): Promise<void> {
+        if (!this.persistPath) return;
+        try {
+            const raw = await readFile(this.persistPath, "utf8");
+            const data = JSON.parse(raw);
+            this.documents = data.documents || [];
+            this.vectors = data.vectors || [];
+        } catch {
+            // File might not exist yet, ignore
+            this.documents = [];
+            this.vectors = [];
+        }
+    }
+
+    /**
+     * Internal save to disk.
+     */
+    private async save(): Promise<void> {
+        if (!this.persistPath) return;
+        try {
+            await mkdir(path.dirname(this.persistPath), { recursive: true });
+            await writeFile(this.persistPath, JSON.stringify({
+                documents: this.documents,
+                vectors: this.vectors
+            }));
+        } catch (err) {
+            console.error("Failed to persist vector store:", err);
+        }
+    }
+}

package/src/memory/memory-manager.ts

@@ -0,0 +1,126 @@
+import { IVectorStore, MemoryDocument, SearchResult } from "../types/contracts.js";
+import { GraphMemory, GraphNode, GraphEdge } from "./graph-memory.js";
+
+export interface MemoryQuery {
+    text?: string;
+    vector?: number[];
+    metadata?: Record<string, unknown>;
+    limit?: number;
+}
+
+export interface MemoryStatistics {
+    totalDocuments: number;
+    totalNodes: number;
+    totalEdges: number;
+    lastUpdated: string;
+}
+
+/**
+ * MemoryManager coordinates Vector search and Graph traversal.
+ * This is the heart of QSGM, allowing for "logical navigation" of context.
+ */
+export class MemoryManager {
+    private stats: MemoryStatistics = {
+        totalDocuments: 0,
+        totalNodes: 0,
+        totalEdges: 0,
+        lastUpdated: new Date().toISOString()
+    };
+
+    constructor(
+        private vectorStore: IVectorStore,
+        private graphMemory: GraphMemory
+    ) { }
+
+    /**
+     * Retrieves context using a hybrid approach:
+     * 1. Find the most semantically relevant node via Vector Search.
+     * 2. Traverse the Graph from that node to find related concepts/actions/artifacts.
+     */
+    public async getQuantumContext(queryVector: number[], limit: number = 3): Promise<string> {
+        const vectorResults = await this.vectorStore.search(queryVector, 1);
+
+        if (vectorResults.length === 0) return "";
+
+        const seedNodeId = vectorResults[0].id;
+        const relatedNodes = this.graphMemory.traverse(seedNodeId, 2);
+
+        return relatedNodes
+            .map(node => `[QSGM_KNOWLEDGE] (${node.type.toUpperCase()})\n${node.content}`)
+            .join("\n\n");
+    }
+
+    /**
+     * Records a new interaction in both stores.
+     */
+    public async remember(doc: MemoryDocument, vector: number[], relatedToId?: string): Promise<void> {
+        // 1. Add to Vector Store for semantic search
+        await this.vectorStore.add([doc], [vector]);
+
+        // 2. Add to Graph Memory for logical navigation
+        this.graphMemory.addNode({
+            id: doc.id,
+            type: "artifact",
+            content: doc.text,
+            metadata: doc.metadata,
+            timestamp: doc.timestamp
+        });
+
+        if (relatedToId) {
+            this.graphMemory.addEdge({
+                from: relatedToId,
+                to: doc.id,
+                type: "produced"
+            });
+        }
+
+        await this.graphMemory.save();
+        this.stats.totalDocuments++;
+        this.stats.totalNodes++;
+        this.stats.lastUpdated = new Date().toISOString();
+    }
+
+    public async search(query: MemoryQuery): Promise<SearchResult[]> {
+        if (!query.vector) return [];
+        return this.vectorStore.search(query.vector, query.limit || 5);
+    }
+
+    public async forget(docId: string): Promise<void> {
+        if (this.vectorStore.delete) {
+            await this.vectorStore.delete([docId]);
+        }
+        this.graphMemory.removeNode(docId);
+        this.stats.totalDocuments = Math.max(0, this.stats.totalDocuments - 1);
+    }
+
+    public async clear(): Promise<void> {
+        this.stats = {
+            totalDocuments: 0,
+            totalNodes: 0,
+            totalEdges: 0,
+            lastUpdated: new Date().toISOString()
+        };
+    }
+
+    public getGraphData(): any {
+        return this.graphMemory.getGraphData();
+    }
+
+    public getStatistics(): MemoryStatistics {
+        return { ...this.stats };
+    }
+
+    public async batchRemember(docs: MemoryDocument[], vectors: number[][]): Promise<void> {
+        for (let i = 0; i < docs.length; i++) {
+            await this.remember(docs[i], vectors[i]);
+        }
+    }
+
+    public async export(): Promise<any> {
+        return {
+            graphs: this.getGraphData(),
+            timestamp: new Date().toISOString(),
+            stats: this.stats
+        };
+    }
+}

package/src/metrics/metrics-engine.ts

@@ -0,0 +1,39 @@
+import { ExecutionMetrics } from "../types/contracts.js";
+
+export class MetricsEngine {
+  private readonly runs: ExecutionMetrics[] = [];
+
+  push(metrics: ExecutionMetrics): void {
+    this.runs.push(metrics);
+  }
+
+  summary(): {
+    totalRuns: number;
+    avgConfidence: number;
+    avgLatencyMs: number;
+    totalCostUsd: number;
+    interventionRate: number;
+  } {
+    if (this.runs.length === 0) {
+      return { totalRuns: 0, avgConfidence: 0, avgLatencyMs: 0, totalCostUsd: 0, interventionRate: 0 };
+    }
+    const total = this.runs.length;
+    const sums = this.runs.reduce(
+      (acc, run) => {
+        acc.conf += run.confidence;
+        acc.lat += run.totalLatencyMs;
+        acc.cost += run.totalCostUsd;
+        acc.human += run.humanInterventionRequired ? 1 : 0;
+        return acc;
+      },
+      { conf: 0, lat: 0, cost: 0, human: 0 }
+    );
+    return {
+      totalRuns: total,
+      avgConfidence: sums.conf / total,
+      avgLatencyMs: sums.lat / total,
+      totalCostUsd: Number(sums.cost.toFixed(4)),
+      interventionRate: sums.human / total
+    };
+  }
+}