rice-node-sdk 1.0.0

package/dist/state/index.js

@@ -0,0 +1,189 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateClient = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const path = __importStar(require("path"));
+// For library usage, we expect proto file to be in ./proto relative to built file
+// But since we use protoLoader, we need the file present.
+const PROTO_PATH = path.join(__dirname, "proto", "state.proto");
+/**
+ * Client for interacting with State (AI Memory).
+ * Provides methods for managing conversational memory, drift, and skills.
+ */
+class StateClient {
+    /**
+     * Creates an instance of StateClient.
+     * @param address - The address of the State service (e.g., "localhost:50051").
+     * @param token - Optional authorization token.
+     * @param runId - Unique identifier for the current run/session. Defaults to "default".
+     */
+    constructor(address = "localhost:50051", token, runId = "default") {
+        const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+            keepCase: true,
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+        });
+        const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
+        // Internal usage: The proto package is still 'slate' for compatibility
+        const slate = protoDescriptor.slate;
+        this.client = new slate.Cortex(address, grpc.credentials.createInsecure());
+        this.metadata = new grpc.Metadata();
+        if (token) {
+            this.metadata.add("authorization", token);
+        }
+        this.runId = runId;
+    }
+    /**
+     * Sets the run ID for subsequent operations.
+     * @param runId - The new run ID to use.
+     */
+    setRunId(runId) {
+        this.runId = runId;
+    }
+    /**
+     * Focuses the state on a specific content or context.
+     * @param content - The content to focus on.
+     * @returns A promise that resolves to the ID of the focus operation.
+     */
+    focus(content) {
+        return new Promise((resolve, reject) => {
+            this.client.Focus({ content, run_id: this.runId }, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.id);
+            });
+        });
+    }
+    /**
+     * Retrieves the current drift or context drift items.
+     * @returns A promise that resolves to an array of drift items.
+     */
+    drift() {
+        return new Promise((resolve, reject) => {
+            this.client.Drift({ run_id: this.runId }, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.items || []);
+            });
+        });
+    }
+    /**
+     * Commits a trace of an interaction (input/outcome) to memory.
+     * @param input - The input or prompt.
+     * @param outcome - The result or response.
+     * @param options - Optional parameters including action, reasoning, and agent_id.
+     * @returns A promise that resolves to true if successful.
+     */
+    commit(input, outcome, options) {
+        return new Promise((resolve, reject) => {
+            const trace = {
+                input,
+                outcome,
+                reasoning: options?.reasoning || "Node Client",
+                action: options?.action || "Action",
+                agent_id: options?.agent_id || "node-user",
+                embedding: [], // Mock
+                run_id: this.runId,
+            };
+            this.client.Commit(trace, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.success);
+            });
+        });
+    }
+    /**
+     * Recalls past memories relevant to a query.
+     * @param query - The query text to search for memories.
+     * @param limit - Maximum number of memories to retrieve. Defaults to 5.
+     * @returns A promise that resolves to an array of traces/memories.
+     */
+    reminisce(query, limit = 5) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                embedding: [],
+                limit,
+                query_text: query,
+                run_id: this.runId,
+            };
+            this.client.Reminisce(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.traces || []);
+            });
+        });
+    }
+    /**
+     * Triggers a specific skill or action.
+     * @param skillName - The name of the skill to trigger.
+     * @returns A promise that resolves to the result code (number).
+     */
+    trigger(skillName) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                skill_name: skillName,
+            };
+            this.client.Trigger(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.result);
+            });
+        });
+    }
+    /**
+     * Deletes the current run/session and its associated data.
+     * @returns A promise that resolves to true if successful.
+     */
+    deleteRun() {
+        return new Promise((resolve, reject) => {
+            this.client.DeleteRun({ run_id: this.runId }, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.success);
+            });
+        });
+    }
+}
+exports.StateClient = StateClient;

package/dist/state/proto/state.proto

@@ -0,0 +1,100 @@
+syntax = "proto3";
+package slate;
+
+service Cortex {
+  // Flux
+  rpc Focus(FocusRequest) returns (FocusResponse);
+  rpc Drift(DriftRequest) returns (DriftResponse);
+
+  // Echoes
+  rpc Commit(Trace) returns (Ack);
+  rpc Reminisce(RecallRequest) returns (RecallResponse);
+
+  // Nexus
+  rpc Consult(QueryRequest) returns (KnowledgeResponse);
+
+  // Reflex
+  rpc Trigger(ReflexRequest) returns (ExecutionResult);
+
+  // Management
+  rpc DeleteRun(RunRequest) returns (Ack);
+}
+
+message FocusRequest {
+  string content = 1;
+  string run_id = 2;
+}
+
+message FocusResponse {
+  string id = 1;
+}
+
+message DriftRequest {
+  string run_id = 1;
+}
+
+message DriftResponse {
+  repeated FluxItem items = 1;
+}
+
+message FluxItem {
+  string id = 1;
+  string content = 2;
+  float relevance = 3;
+}
+
+message Trace {
+  string input = 1;
+  string reasoning = 2;
+  string action = 3;
+  string outcome = 4;
+  string agent_id = 5;
+  repeated float embedding = 6;
+  string run_id = 7;
+}
+
+message Ack {
+  bool success = 1;
+}
+
+message RecallRequest {
+  repeated float embedding = 1;
+  uint64 limit = 2;
+  string query_text = 3;
+  string filter = 4;
+  string run_id = 5;
+}
+
+message RecallResponse {
+  repeated Trace traces = 1;
+}
+
+message QueryRequest {
+  repeated float embedding = 1;
+  uint64 limit = 2;
+  string query_text = 3;
+  string filter = 4;
+  string run_id = 5;
+}
+
+message RunRequest {
+  string run_id = 1;
+}
+
+message KnowledgeResponse {
+  repeated Fact facts = 1;
+}
+
+message Fact {
+  string id = 1;
+  string content = 2;
+  string source = 3;
+}
+
+message ReflexRequest {
+  string skill_name = 1;
+}
+
+message ExecutionResult {
+  int32 result = 1;
+}

package/dist/state/tools.d.ts

@@ -0,0 +1,97 @@
+import { execute } from "../tools/execute";
+export declare const statetool: {
+    google: ({
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                content: {
+                    type: string;
+                    description: string;
+                };
+                query?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                query: {
+                    type: string;
+                    description: string;
+                };
+                content?: undefined;
+            };
+            required: string[];
+        };
+    })[];
+    openai: ({
+        type: string;
+        function: {
+            name: string;
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    content: {
+                        type: string;
+                        description: string;
+                    };
+                    query?: undefined;
+                };
+                required: string[];
+            };
+        };
+    } | {
+        type: string;
+        function: {
+            name: string;
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    query: {
+                        type: string;
+                        description: string;
+                    };
+                    content?: undefined;
+                };
+                required: string[];
+            };
+        };
+    })[];
+    anthropic: ({
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                content: {
+                    type: string;
+                    description: string;
+                };
+                query?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                query: {
+                    type: string;
+                    description: string;
+                };
+                content?: undefined;
+            };
+            required: string[];
+        };
+    })[];
+    execute: typeof execute;
+};

package/dist/state/tools.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statetool = void 0;
+const google_1 = require("../tools/google");
+const openai_1 = require("../tools/openai");
+const anthropic_1 = require("../tools/anthropic");
+const execute_1 = require("../tools/execute");
+exports.statetool = {
+    google: google_1.state,
+    openai: openai_1.state,
+    anthropic: anthropic_1.state,
+    execute: execute_1.execute,
+};

package/dist/storage/client/BaseClient.d.ts

@@ -0,0 +1,133 @@
+import { BitVector } from "../utils/BitVector";
+import Long from "long";
+export interface HealthInfo {
+    status: string;
+    version: string;
+}
+export interface InsertResult {
+    success: boolean;
+    nodeId: Long;
+    message: string;
+    aclGrants?: any;
+    aclUsers?: any[];
+}
+export interface SearchResultItem {
+    id: Long;
+    similarity: number;
+    metadata: any;
+}
+export interface MemoryEntry {
+    id: string;
+    sessionId: string;
+    agentId: string;
+    content: string;
+    timestamp: Long;
+    metadata: {
+        [key: string]: string;
+    };
+    expiresAt?: Long;
+}
+export declare abstract class BaseRiceDBClient {
+    protected host: string;
+    protected port: number;
+    protected connected: boolean;
+    constructor(host?: string, port?: number);
+    abstract connect(): Promise<boolean>;
+    abstract disconnect(): void;
+    abstract health(): Promise<HealthInfo>;
+    abstract login(username: string, password: string): Promise<string>;
+    abstract createUser(username: string, password: string, role?: string): Promise<Long>;
+    abstract deleteUser(username: string): Promise<boolean>;
+    abstract getUser(username: string): Promise<any>;
+    abstract listUsers(): Promise<any[]>;
+    abstract insert(nodeId: Long | number | string, text: string, metadata: any, userId?: Long | number | string, sessionId?: string, embedding?: number[]): Promise<InsertResult>;
+    abstract search(query: string, userId: Long | number | string, k?: number, sessionId?: string, filter?: {
+        [key: string]: any;
+    }, queryEmbedding?: number[]): Promise<SearchResultItem[]>;
+    abstract delete(nodeId: Long | number | string, sessionId?: string): Promise<boolean>;
+    abstract createSession(parentSessionId?: string): Promise<string>;
+    abstract snapshotSession(sessionId: string, path: string): Promise<boolean>;
+    abstract loadSession(path: string): Promise<string>;
+    abstract commitSession(sessionId: string, mergeStrategy?: string): Promise<boolean>;
+    abstract dropSession(sessionId: string): Promise<boolean>;
+    abstract writeMemory(address: BitVector, data: BitVector, userId?: Long | number | string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    abstract readMemory(address: BitVector, userId?: Long | number | string): Promise<BitVector>;
+    abstract addMemory(sessionId: string, agentId: string, content: string, metadata?: {
+        [key: string]: string;
+    }, ttlSeconds?: number): Promise<{
+        success: boolean;
+        message: string;
+        entry: MemoryEntry;
+    }>;
+    abstract getMemory(sessionId: string, limit?: number, after?: number | Long, filter?: {
+        [key: string]: string;
+    }): Promise<MemoryEntry[]>;
+    abstract clearMemory(sessionId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    abstract watchMemory(sessionId: string): AsyncIterable<any>;
+    /**
+     * Create a semantic link between two nodes.
+     * Alias for addEdge.
+     */
+    link(sourceId: Long | number | string, relation: string, targetId: Long | number | string, weight?: number): Promise<boolean>;
+    abstract addEdge(fromNode: Long | number | string, toNode: Long | number | string, relation: string, weight?: number): Promise<boolean>;
+    abstract getNeighbors(nodeId: Long | number | string, relation?: string): Promise<Long[]>;
+    abstract traverse(startNode: Long | number | string, maxDepth?: number): Promise<Long[]>;
+    abstract sampleGraph(limit?: number): Promise<any>;
+    abstract subscribe(filterType?: string, nodeId?: Long | number | string, queryText?: string, threshold?: number): AsyncIterable<any>;
+    abstract batchInsert(documents: any[], userId?: Long | number | string): Promise<{
+        count: number;
+        nodeIds: Long[];
+    }>;
+    /**
+     * High-performance bulk ingestion using batches and concurrency.
+     *
+     * @param documents List of documents to insert
+     * @param batchSize Number of documents per batch (default 500)
+     * @param concurrency Number of concurrent requests (default 4)
+     * @param userId User ID to own the documents
+     */
+    fastIngest(documents: any[], batchSize?: number, concurrency?: number, userId?: Long | number | string): Promise<{
+        totalInserted: number;
+        failedBatches: number;
+        errors: string[];
+        timeTaken: number;
+        throughput: number;
+    }>;
+    abstract grantPermission(nodeId: Long | number | string, userId: Long | number | string, permissions: {
+        read?: boolean;
+        write?: boolean;
+        delete?: boolean;
+    }): Promise<boolean>;
+    abstract revokePermission(nodeId: Long | number | string, userId: Long | number | string): Promise<boolean>;
+    abstract checkPermission(nodeId: Long | number | string, userId: Long | number | string, permissionType: string): Promise<boolean>;
+    abstract batchGrant(grants: Array<{
+        nodeId: Long | number | string;
+        userId: Long | number | string;
+        permissions: {
+            read?: boolean;
+            write?: boolean;
+            delete?: boolean;
+        };
+    }>): Promise<{
+        total: number;
+        successful: number;
+        failed: number;
+        results: any[];
+        errors: any[];
+    }>;
+    abstract insertWithAcl(nodeId: Long | number | string, text: string, metadata: any, userPermissions: Array<{
+        userId: Long | number | string;
+        permissions: {
+            read?: boolean;
+            write?: boolean;
+            delete?: boolean;
+        };
+    }>): Promise<InsertResult>;
+    protected toLong(val: Long | number | string): Long;
+}

package/dist/storage/client/BaseClient.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseRiceDBClient = void 0;
+const long_1 = __importDefault(require("long"));
+class BaseRiceDBClient {
+    constructor(host = "localhost", port = 3000) {
+        this.connected = false;
+        this.host = host;
+        this.port = port;
+    }
+    // Graph
+    /**
+     * Create a semantic link between two nodes.
+     * Alias for addEdge.
+     */
+    async link(sourceId, relation, targetId, weight = 1.0) {
+        return this.addEdge(sourceId, targetId, relation, weight);
+    }
+    /**
+     * High-performance bulk ingestion using batches and concurrency.
+     *
+     * @param documents List of documents to insert
+     * @param batchSize Number of documents per batch (default 500)
+     * @param concurrency Number of concurrent requests (default 4)
+     * @param userId User ID to own the documents
+     */
+    async fastIngest(documents, batchSize = 500, concurrency = 4, userId) {
+        const startTime = Date.now();
+        let totalInserted = 0;
+        let failedBatches = 0;
+        const errors = [];
+        // Create chunks
+        const chunks = [];
+        for (let i = 0; i < documents.length; i += batchSize) {
+            chunks.push(documents.slice(i, i + batchSize));
+        }
+        // Process with concurrency
+        const queue = [...chunks];
+        const processChunk = async (chunk) => {
+            try {
+                const result = await this.batchInsert(chunk, userId);
+                totalInserted += result.count;
+            }
+            catch (e) {
+                failedBatches++;
+                if (errors.length < 10) {
+                    errors.push(e.message || String(e));
+                }
+            }
+        };
+        const workers = Array(Math.min(concurrency, chunks.length))
+            .fill(null)
+            .map(async () => {
+            while (queue.length > 0) {
+                const chunk = queue.shift();
+                if (chunk) {
+                    await processChunk(chunk);
+                }
+            }
+        });
+        await Promise.all(workers);
+        const endTime = Date.now();
+        const timeTaken = (endTime - startTime) / 1000;
+        const throughput = timeTaken > 0 ? totalInserted / timeTaken : 0;
+        return {
+            totalInserted,
+            failedBatches,
+            errors,
+            timeTaken,
+            throughput,
+        };
+    }
+    // Helper to convert inputs to Long
+    toLong(val) {
+        return long_1.default.fromValue(val);
+    }
+}
+exports.BaseRiceDBClient = BaseRiceDBClient;

package/dist/storage/client/GrpcClient.d.ts

@@ -0,0 +1,87 @@
+import { BaseRiceDBClient, HealthInfo, InsertResult, SearchResultItem, MemoryEntry } from "./BaseClient";
+import Long from "long";
+import { BitVector } from "../utils/BitVector";
+export declare class GrpcClient extends BaseRiceDBClient {
+    private client;
+    private token;
+    constructor(host?: string, port?: number, token?: string);
+    connect(): Promise<boolean>;
+    disconnect(): void;
+    private getMetadata;
+    private promisify;
+    health(): Promise<HealthInfo>;
+    login(username: string, password: string): Promise<string>;
+    createUser(username: string, password: string, role?: string): Promise<Long>;
+    deleteUser(username: string): Promise<boolean>;
+    getUser(username: string): Promise<any>;
+    listUsers(): Promise<any[]>;
+    insert(nodeId: Long | number | string, text: string, metadata: any, userId?: Long | number | string, sessionId?: string, embedding?: number[]): Promise<InsertResult>;
+    search(query: string, userId: Long | number | string, k?: number, sessionId?: string, filter?: {
+        [key: string]: any;
+    }, queryEmbedding?: number[]): Promise<SearchResultItem[]>;
+    delete(nodeId: Long | number | string, sessionId?: string): Promise<boolean>;
+    createSession(parentSessionId?: string): Promise<string>;
+    snapshotSession(sessionId: string, path: string): Promise<boolean>;
+    loadSession(path: string): Promise<string>;
+    commitSession(sessionId: string, mergeStrategy?: string): Promise<boolean>;
+    dropSession(sessionId: string): Promise<boolean>;
+    writeMemory(address: BitVector, data: BitVector, userId?: Long | number | string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    readMemory(address: BitVector, userId?: Long | number | string): Promise<BitVector>;
+    addMemory(sessionId: string, agentId: string, content: string, metadata?: {
+        [key: string]: string;
+    }, ttlSeconds?: number): Promise<{
+        success: boolean;
+        message: string;
+        entry: MemoryEntry;
+    }>;
+    getMemory(sessionId: string, limit?: number, after?: number | Long, filter?: {
+        [key: string]: string;
+    }): Promise<MemoryEntry[]>;
+    clearMemory(sessionId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    watchMemory(sessionId: string): AsyncIterable<any>;
+    addEdge(fromNode: Long | number | string, toNode: Long | number | string, relation: string, weight?: number): Promise<boolean>;
+    getNeighbors(nodeId: Long | number | string, relation?: string): Promise<Long[]>;
+    traverse(startNode: Long | number | string, maxDepth?: number): Promise<Long[]>;
+    sampleGraph(limit?: number): Promise<any>;
+    subscribe(filterType?: string, nodeId?: Long | number | string, queryText?: string, threshold?: number): AsyncIterable<any>;
+    batchInsert(documents: any[], userId?: Long | number | string): Promise<{
+        count: number;
+        nodeIds: Long[];
+    }>;
+    grantPermission(nodeId: Long | number | string, userId: Long | number | string, permissions: {
+        read?: boolean;
+        write?: boolean;
+        delete?: boolean;
+    }): Promise<boolean>;
+    revokePermission(nodeId: Long | number | string, userId: Long | number | string): Promise<boolean>;
+    checkPermission(nodeId: Long | number | string, userId: Long | number | string, permissionType: string): Promise<boolean>;
+    batchGrant(grants: Array<{
+        nodeId: Long | number | string;
+        userId: Long | number | string;
+        permissions: {
+            read?: boolean;
+            write?: boolean;
+            delete?: boolean;
+        };
+    }>): Promise<{
+        total: number;
+        successful: number;
+        failed: number;
+        results: any[];
+        errors: any[];
+    }>;
+    insertWithAcl(nodeId: Long | number | string, text: string, metadata: any, userPermissions: Array<{
+        userId: Long | number | string;
+        permissions: {
+            read?: boolean;
+            write?: boolean;
+            delete?: boolean;
+        };
+    }>): Promise<InsertResult>;
+}