rice-node-sdk 1.0.0

package/dist/storage/client/HttpClient.js

@@ -0,0 +1,335 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const BaseClient_1 = require("./BaseClient");
+const long_1 = __importDefault(require("long"));
+const BitVector_1 = require("../utils/BitVector");
+class HttpClient extends BaseClient_1.BaseRiceDBClient {
+    constructor(host = "localhost", port = 3000, token) {
+        super(host, port);
+        this.token = null;
+        if (token) {
+            this.token = token;
+        }
+        this.client = axios_1.default.create({
+            baseURL: `http://${host}:${port}`,
+            timeout: 30000,
+            validateStatus: () => true, // Handle status codes manually
+        });
+        if (this.token) {
+            this.setAuthHeader();
+        }
+    }
+    async connect() {
+        try {
+            const res = await this.client.get("/health");
+            this.connected = res.status === 200;
+            return this.connected;
+        }
+        catch (e) {
+            this.connected = false;
+            throw e;
+        }
+    }
+    disconnect() {
+        this.connected = false;
+    }
+    setAuthHeader() {
+        if (this.token) {
+            this.client.defaults.headers.common["Authorization"] = `Bearer ${this.token}`;
+        }
+    }
+    async request(method, url, data, params) {
+        const res = await this.client.request({
+            method,
+            url,
+            data,
+            params,
+        });
+        if (res.status >= 400) {
+            throw new Error(`Request failed with status ${res.status}: ${JSON.stringify(res.data)}`);
+        }
+        return res.data;
+    }
+    async health() {
+        return this.request("GET", "/health");
+    }
+    async login(username, password) {
+        const res = await this.request("POST", "/auth/login", { username, password });
+        this.token = res.token;
+        this.setAuthHeader();
+        return this.token;
+    }
+    async createUser(username, password, role = "user") {
+        const res = await this.request("POST", "/auth/create_user", { username, password, role });
+        return long_1.default.fromNumber(res.user_id);
+    }
+    async deleteUser(username) {
+        await this.request("DELETE", "/auth/delete_user", { username });
+        return true;
+    }
+    async getUser(username) {
+        return this.request("GET", `/auth/users/${username}`);
+    }
+    async listUsers() {
+        return this.request("GET", "/auth/users");
+    }
+    async insert(nodeId, text, metadata, userId = 1, sessionId, embedding) {
+        const payload = {
+            id: this.toLong(nodeId).toNumber(),
+            text,
+            metadata,
+            user_id: this.toLong(userId).toNumber(),
+        };
+        if (sessionId)
+            payload.session_id = sessionId;
+        if (embedding)
+            payload.embedding = embedding;
+        const res = await this.request("POST", "/insert", payload);
+        if (!res.success) {
+            throw new Error(res.message || "Insert failed");
+        }
+        return {
+            success: res.success,
+            nodeId: long_1.default.fromValue(res.node_id),
+            message: res.message,
+        };
+    }
+    async search(query, userId, k = 10, sessionId, filter, queryEmbedding) {
+        const payload = {
+            query,
+            user_id: this.toLong(userId).toNumber(),
+            k,
+        };
+        if (sessionId)
+            payload.session_id = sessionId;
+        if (filter)
+            payload.filter = filter;
+        if (queryEmbedding)
+            payload.query_embedding = queryEmbedding;
+        const res = await this.request("POST", "/search", payload);
+        const results = Array.isArray(res) ? res : res.results || [];
+        return results.map((r) => ({
+            id: long_1.default.fromValue(r.id),
+            similarity: r.similarity,
+            metadata: r.metadata,
+        }));
+    }
+    async delete(nodeId, sessionId) {
+        const params = {};
+        if (sessionId)
+            params.session_id = sessionId;
+        await this.request("DELETE", `/node/${this.toLong(nodeId).toString()}`, undefined, params);
+        return true;
+    }
+    // Cortex
+    async createSession(parentSessionId) {
+        const payload = {};
+        if (parentSessionId)
+            payload.parent_session_id = parentSessionId;
+        const res = await this.request("POST", "/session/create", payload);
+        return res.session_id;
+    }
+    async snapshotSession(sessionId, path) {
+        await this.request("POST", `/session/${sessionId}/snapshot`, { path });
+        return true;
+    }
+    async loadSession(path) {
+        const res = await this.request("POST", "/session/load", { path });
+        return res.session_id;
+    }
+    async commitSession(sessionId, mergeStrategy = "overwrite") {
+        await this.request("POST", `/session/${sessionId}/commit`, {
+            merge_strategy: mergeStrategy,
+        });
+        return true;
+    }
+    async dropSession(sessionId) {
+        await this.request("DELETE", `/session/${sessionId}/drop`);
+        return true;
+    }
+    // SDM
+    async writeMemory(address, data, userId = 1) {
+        const res = await this.request("POST", "/sdm/write", {
+            address: address.toList().map((l) => l.toNumber()),
+            data: data.toList().map((l) => l.toNumber()),
+            user_id: this.toLong(userId).toNumber(),
+        });
+        return { success: res.success, message: res.message };
+    }
+    async readMemory(address, userId = 1) {
+        const res = await this.request("POST", "/sdm/read", {
+            address: address.toList().map((l) => l.toNumber()),
+            user_id: this.toLong(userId).toNumber(),
+        });
+        // Assuming res.data is list of numbers
+        return new BitVector_1.BitVector(res.data.map((n) => long_1.default.fromNumber(n)));
+    }
+    // Agent Memory
+    async addMemory(sessionId, agentId, content, metadata = {}, ttlSeconds) {
+        const payload = {
+            agent_id: agentId,
+            content,
+            metadata,
+        };
+        if (ttlSeconds !== undefined)
+            payload.ttl_seconds = ttlSeconds;
+        const res = await this.request("POST", `/memory/${sessionId}`, payload);
+        return {
+            success: res.success,
+            message: res.message,
+            entry: {
+                ...res.entry,
+                timestamp: long_1.default.fromValue(res.entry.timestamp),
+                expiresAt: res.entry.expires_at
+                    ? long_1.default.fromValue(res.entry.expires_at)
+                    : undefined,
+            },
+        };
+    }
+    async getMemory(sessionId, limit = 50, after = 0, filter = {}) {
+        const params = { limit };
+        if (after)
+            params.after_timestamp = long_1.default.fromValue(after).toNumber();
+        const res = await this.request("GET", `/memory/${sessionId}`, undefined, params);
+        const entries = res.entries || [];
+        return entries.map((e) => ({
+            ...e,
+            timestamp: long_1.default.fromValue(e.timestamp),
+            expiresAt: e.expires_at ? long_1.default.fromValue(e.expires_at) : undefined,
+        }));
+    }
+    async clearMemory(sessionId) {
+        const res = await this.request("DELETE", `/memory/${sessionId}`);
+        return { success: res.success, message: res.message || "" };
+    }
+    async *watchMemory(sessionId) {
+        throw new Error("Watch memory is not supported via HTTP transport. Use gRPC.");
+    }
+    // Graph
+    async addEdge(fromNode, toNode, relation, weight = 1.0) {
+        await this.request("POST", "/graph/edge", {
+            from: this.toLong(fromNode).toNumber(),
+            to: this.toLong(toNode).toNumber(),
+            relation,
+            weight,
+        });
+        return true;
+    }
+    async getNeighbors(nodeId, relation) {
+        const payload = { node_id: this.toLong(nodeId).toNumber() };
+        if (relation)
+            payload.relation = relation;
+        const res = await this.request("POST", "/graph/neighbors", payload);
+        return (res.neighbors || []).map((id) => long_1.default.fromNumber(id));
+    }
+    async traverse(startNode, maxDepth = 1) {
+        const res = await this.request("POST", "/graph/traverse", {
+            start: this.toLong(startNode).toNumber(),
+            max_depth: maxDepth,
+        });
+        return (res.visited || []).map((id) => long_1.default.fromNumber(id));
+    }
+    async sampleGraph(limit = 100) {
+        return this.request("POST", "/graph/sample", { limit });
+    }
+    async *subscribe(filterType = "all", nodeId, queryText = "", threshold = 0.8) {
+        throw new Error("Subscribe is not supported via HTTP transport. Use gRPC.");
+    }
+    async batchInsert(documents, userId = 1) {
+        const payload = documents.map((doc) => ({
+            id: this.toLong(doc.id).toNumber(),
+            text: doc.text || "",
+            metadata: doc.metadata,
+            user_id: doc.userId !== undefined
+                ? this.toLong(doc.userId).toNumber()
+                : this.toLong(userId).toNumber(),
+        }));
+        const res = await this.request("POST", "/batch_insert", payload);
+        return {
+            count: res.count,
+            nodeIds: (res.node_ids || []).map((id) => long_1.default.fromNumber(id)),
+        };
+    }
+    async grantPermission(nodeId, userId, permissions) {
+        await this.request("POST", "/acl/grant", {
+            node_id: this.toLong(nodeId).toNumber(),
+            target_user_id: this.toLong(userId).toNumber(),
+            permissions,
+        });
+        return true;
+    }
+    async revokePermission(nodeId, userId) {
+        await this.request("POST", "/acl/revoke", {
+            node_id: this.toLong(nodeId).toNumber(),
+            target_user_id: this.toLong(userId).toNumber(),
+        });
+        return true;
+    }
+    async checkPermission(nodeId, userId, permissionType) {
+        const res = await this.request("POST", "/acl/check", {
+            node_id: this.toLong(nodeId).toNumber(),
+            user_id: this.toLong(userId).toNumber(),
+            permission_type: permissionType,
+        });
+        return res.allowed || false;
+    }
+    async batchGrant(grants) {
+        const results = [];
+        const errors = [];
+        for (let i = 0; i < grants.length; i++) {
+            const grant = grants[i];
+            try {
+                const success = await this.grantPermission(grant.nodeId, grant.userId, grant.permissions);
+                results.push({
+                    index: i,
+                    nodeId: grant.nodeId,
+                    userId: grant.userId,
+                    success: true,
+                    result: success,
+                });
+            }
+            catch (e) {
+                errors.push({
+                    index: i,
+                    nodeId: grant.nodeId,
+                    userId: grant.userId,
+                    error: e.message || String(e),
+                });
+            }
+        }
+        return {
+            total: grants.length,
+            successful: results.length,
+            failed: errors.length,
+            results,
+            errors,
+        };
+    }
+    async insertWithAcl(nodeId, text, metadata, userPermissions) {
+        if (!userPermissions || userPermissions.length === 0) {
+            throw new Error("At least one user permission must be provided");
+        }
+        const primaryUser = userPermissions[0];
+        const primaryUserId = primaryUser.userId;
+        // 1. Insert for primary user
+        const insertRes = await this.insert(nodeId, text, metadata, primaryUserId);
+        // 2. Grant permissions for others
+        const additionalGrants = userPermissions.slice(1).map((p) => ({
+            nodeId: nodeId,
+            userId: p.userId,
+            permissions: p.permissions,
+        }));
+        if (additionalGrants.length > 0) {
+            const grantRes = await this.batchGrant(additionalGrants);
+            insertRes.aclGrants = grantRes;
+        }
+        insertRes.aclUsers = userPermissions;
+        return insertRes;
+    }
+}
+exports.HttpClient = HttpClient;

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

@@ -0,0 +1,306 @@
+import { BaseRiceDBClient, HealthInfo, InsertResult, SearchResultItem, MemoryEntry } from "./BaseClient";
+import Long from "long";
+import { BitVector } from "../utils/BitVector";
+/**
+ * Client for RiceDB (Persistent Semantic Database).
+ * Supports both gRPC and HTTP transports.
+ */
+export declare class RiceDBClient extends BaseRiceDBClient {
+    private client;
+    private transport;
+    private _grpcPort;
+    private _httpPort;
+    private token;
+    /**
+     * Creates a new RiceDB client instance.
+     * @param host - The hostname of the RiceDB server (default: "localhost").
+     * @param transport - The transport protocol to use: "grpc", "http", or "auto" (default: "auto").
+     * @param grpcPort - The port for gRPC connections (default: 50051).
+     * @param httpPort - The port for HTTP connections (default: 3000).
+     * @param token - Optional authentication token.
+     */
+    constructor(host?: string, transport?: "grpc" | "http" | "auto", grpcPort?: number, httpPort?: number, token?: string);
+    /**
+     * Connects to the RiceDB server.
+     * If transport is "auto", tries gRPC first, then falls back to HTTP.
+     * @returns A promise that resolves to true if connected successfully.
+     */
+    connect(): Promise<boolean>;
+    /**
+     * Disconnects from the RiceDB server.
+     */
+    disconnect(): void;
+    private checkConnected;
+    /**
+     * Checks the health of the RiceDB server.
+     * @returns Detailed health information.
+     */
+    health(): Promise<HealthInfo>;
+    /**
+     * Logs in a user.
+     * @param username - The username.
+     * @param password - The password.
+     * @returns An authentication token or session ID.
+     */
+    login(username: string, password: string): Promise<string>;
+    /**
+     * Creates a new user.
+     * @param username - The username.
+     * @param password - The password.
+     * @param role - Optional role for the user.
+     * @returns The ID of the created user.
+     */
+    createUser(username: string, password: string, role?: string): Promise<Long>;
+    /**
+     * Deletes a user.
+     * @param username - The username to delete.
+     * @returns True if successful.
+     */
+    deleteUser(username: string): Promise<boolean>;
+    /**
+     * Retrieves user details.
+     * @param username - The username.
+     * @returns User details object.
+     */
+    getUser(username: string): Promise<any>;
+    /**
+     * Lists all users.
+     * @returns An array of user objects.
+     */
+    listUsers(): Promise<any[]>;
+    /**
+     * Inserts a document/node into the database.
+     * @param nodeId - Unique identifier for the node.
+     * @param text - The text content.
+     * @param metadata - Arbitrary metadata object.
+     * @param userId - The ID of the user inserting.
+     * @param sessionId - Optional session ID.
+     * @param embedding - Optional pre-computed embedding vector.
+     * @returns Result of the insertion.
+     */
+    insert(nodeId: Long | number | string, text: string, metadata: any, userId?: Long | number | string, sessionId?: string, embedding?: number[]): Promise<InsertResult>;
+    /**
+     * Searches for similar documents/nodes.
+     * @param query - The query text.
+     * @param userId - The user ID performing the search.
+     * @param k - Number of results to return (default: 10).
+     * @param sessionId - Optional session ID to filter by.
+     * @param filter - Metadata filter criteria.
+     * @param queryEmbedding - Optional query embedding vector.
+     * @returns An array of search results.
+     */
+    search(query: string, userId: Long | number | string, k?: number, sessionId?: string, filter?: {
+        [key: string]: any;
+    }, queryEmbedding?: number[]): Promise<SearchResultItem[]>;
+    /**
+     * Deletes a document/node.
+     * @param nodeId - The ID of the node to delete.
+     * @param sessionId - Optional session ID.
+     * @returns True if successful.
+     */
+    delete(nodeId: Long | number | string, sessionId?: string): Promise<boolean>;
+    /**
+     * Creates a new session.
+     * @param parentSessionId - Optional parent session ID to fork from.
+     * @returns The new session ID.
+     */
+    createSession(parentSessionId?: string): Promise<string>;
+    /**
+     * Saves a snapshot of a session to disk.
+     * @param sessionId - The session ID.
+     * @param path - The file path to save to.
+     * @returns True if successful.
+     */
+    snapshotSession(sessionId: string, path: string): Promise<boolean>;
+    /**
+     * Loads a session from a snapshot.
+     * @param path - The file path to load from.
+     * @returns The loaded session ID.
+     */
+    loadSession(path: string): Promise<string>;
+    /**
+     * Commits changes in a session (e.g., merging back).
+     * @param sessionId - The session ID.
+     * @param mergeStrategy - Strategy for merging ("overwrite", etc.).
+     * @returns True if successful.
+     */
+    commitSession(sessionId: string, mergeStrategy?: string): Promise<boolean>;
+    /**
+     * Drops (deletes) a session.
+     * @param sessionId - The session ID.
+     * @returns True if successful.
+     */
+    dropSession(sessionId: string): Promise<boolean>;
+    /**
+     * Writes raw data to memory at a specific address.
+     * @param address - The memory address (BitVector).
+     * @param data - The data to write (BitVector).
+     * @param userId - The user ID.
+     * @returns Success status and message.
+     */
+    writeMemory(address: BitVector, data: BitVector, userId?: Long | number | string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Reads raw data from memory at a specific address.
+     * @param address - The memory address (BitVector).
+     * @param userId - The user ID.
+     * @returns The data at the address (BitVector).
+     */
+    readMemory(address: BitVector, userId?: Long | number | string): Promise<BitVector>;
+    /**
+     * Adds a high-level memory entry for an agent.
+     * @param sessionId - The session ID.
+     * @param agentId - The agent ID.
+     * @param content - The content of the memory.
+     * @param metadata - Optional metadata.
+     * @param ttlSeconds - Time-to-live in seconds.
+     * @returns The created memory entry.
+     */
+    addMemory(sessionId: string, agentId: string, content: string, metadata?: {
+        [key: string]: string;
+    }, ttlSeconds?: number): Promise<{
+        success: boolean;
+        message: string;
+        entry: MemoryEntry;
+    }>;
+    /**
+     * Retrieves memories for a session.
+     * @param sessionId - The session ID.
+     * @param limit - Maximum number of memories.
+     * @param after - Timestamp or ID to start after.
+     * @param filter - Metadata filter.
+     * @returns An array of memory entries.
+     */
+    getMemory(sessionId: string, limit?: number, after?: number | Long, filter?: {
+        [key: string]: string;
+    }): Promise<MemoryEntry[]>;
+    /**
+     * Clears all memories for a session.
+     * @param sessionId - The session ID.
+     * @returns Success status.
+     */
+    clearMemory(sessionId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Watches for changes in memory for a session.
+     * @param sessionId - The session ID.
+     * @returns An async iterable of changes.
+     */
+    watchMemory(sessionId: string): AsyncIterable<any>;
+    /**
+     * Adds an edge between two nodes in the graph.
+     * @param fromNode - Source node ID.
+     * @param toNode - Target node ID.
+     * @param relation - The type of relation.
+     * @param weight - Edge weight (default: 1.0).
+     * @returns True if successful.
+     */
+    addEdge(fromNode: Long | number | string, toNode: Long | number | string, relation: string, weight?: number): Promise<boolean>;
+    /**
+     * Gets neighboring nodes.
+     * @param nodeId - The node ID.
+     * @param relation - Optional relation type to filter by.
+     * @returns An array of neighbor node IDs.
+     */
+    getNeighbors(nodeId: Long | number | string, relation?: string): Promise<Long[]>;
+    /**
+     * Traverses the graph from a start node.
+     * @param startNode - The starting node ID.
+     * @param maxDepth - Maximum depth to traverse (default: 1).
+     * @returns An array of visited node IDs.
+     */
+    traverse(startNode: Long | number | string, maxDepth?: number): Promise<Long[]>;
+    /**
+     * Samples random nodes from the graph.
+     * @param limit - Number of nodes to sample.
+     * @returns Sampled nodes.
+     */
+    sampleGraph(limit?: number): Promise<any>;
+    /**
+     * Subscribes to real-time updates.
+     * @param filterType - "all", "node", "query".
+     * @param nodeId - Specific node ID to watch.
+     * @param queryText - Query text to watch for similar items.
+     * @param threshold - Similarity threshold.
+     * @returns An async iterable of updates.
+     */
+    subscribe(filterType?: string, nodeId?: Long | number | string, queryText?: string, threshold?: number): AsyncIterable<any>;
+    /**
+     * Inserts multiple documents in a batch.
+     * @param documents - Array of documents.
+     * @param userId - User ID.
+     * @returns Count of inserted items and their node IDs.
+     */
+    batchInsert(documents: any[], userId?: Long | number | string): Promise<{
+        count: number;
+        nodeIds: Long[];
+    }>;
+    /**
+     * Grants permissions on a node to a user.
+     * @param nodeId - Node ID.
+     * @param userId - User ID.
+     * @param permissions - Permissions object ({ read, write, delete }).
+     * @returns True if successful.
+     */
+    grantPermission(nodeId: Long | number | string, userId: Long | number | string, permissions: {
+        read?: boolean;
+        write?: boolean;
+        delete?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Revokes all permissions on a node for a user.
+     * @param nodeId - Node ID.
+     * @param userId - User ID.
+     * @returns True if successful.
+     */
+    revokePermission(nodeId: Long | number | string, userId: Long | number | string): Promise<boolean>;
+    /**
+     * Checks if a user has a specific permission on a node.
+     * @param nodeId - Node ID.
+     * @param userId - User ID.
+     * @param permissionType - "read", "write", "delete".
+     * @returns True if allowed.
+     */
+    checkPermission(nodeId: Long | number | string, userId: Long | number | string, permissionType: string): Promise<boolean>;
+    /**
+     * Grants permissions in batch.
+     * @param grants - Array of grant objects.
+     * @returns Detailed results of the operation.
+     */
+    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[];
+    }>;
+    /**
+     * Inserts a node with ACL permissions in one go.
+     * @param nodeId - Node ID.
+     * @param text - Content.
+     * @param metadata - Metadata.
+     * @param userPermissions - Array of user permissions.
+     * @returns Insertion result.
+     */
+    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;
+}