rice-node-sdk 1.0.0

package/dist/storage/client/RiceDBClient.js

@@ -0,0 +1,408 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RiceDBClient = void 0;
+const BaseClient_1 = require("./BaseClient");
+const GrpcClient_1 = require("./GrpcClient");
+const HttpClient_1 = require("./HttpClient");
+const long_1 = __importDefault(require("long"));
+/**
+ * Client for RiceDB (Persistent Semantic Database).
+ * Supports both gRPC and HTTP transports.
+ */
+class RiceDBClient extends BaseClient_1.BaseRiceDBClient {
+    /**
+     * 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 = "localhost", transport = "auto", grpcPort = 50051, httpPort = 3000, token) {
+        super(host, 0);
+        this.client = null;
+        this.transport = transport;
+        this._grpcPort = grpcPort;
+        this._httpPort = httpPort;
+        this.token = token;
+    }
+    /**
+     * 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.
+     */
+    async connect() {
+        if (this.transport === "grpc") {
+            this.client = new GrpcClient_1.GrpcClient(this.host, this._grpcPort, this.token);
+            await this.client.connect();
+            this.connected = true;
+            return true;
+        }
+        else if (this.transport === "http") {
+            this.client = new HttpClient_1.HttpClient(this.host, this._httpPort, this.token);
+            await this.client.connect();
+            this.connected = true;
+            return true;
+        }
+        else {
+            // Auto
+            try {
+                const grpcClient = new GrpcClient_1.GrpcClient(this.host, this._grpcPort, this.token);
+                await grpcClient.connect();
+                this.client = grpcClient;
+                this.connected = true;
+                return true;
+            }
+            catch (e) {
+                // Fallback
+                console.warn("gRPC connection failed, falling back to HTTP");
+                this.client = new HttpClient_1.HttpClient(this.host, this._httpPort, this.token);
+                await this.client.connect();
+                this.connected = true;
+                return true;
+            }
+        }
+    }
+    /**
+     * Disconnects from the RiceDB server.
+     */
+    disconnect() {
+        if (this.client) {
+            this.client.disconnect();
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    checkConnected() {
+        if (!this.client)
+            throw new Error("Not connected");
+    }
+    /**
+     * Checks the health of the RiceDB server.
+     * @returns Detailed health information.
+     */
+    async health() {
+        this.checkConnected();
+        return this.client.health();
+    }
+    /**
+     * Logs in a user.
+     * @param username - The username.
+     * @param password - The password.
+     * @returns An authentication token or session ID.
+     */
+    async login(username, password) {
+        this.checkConnected();
+        return this.client.login(username, password);
+    }
+    /**
+     * 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.
+     */
+    async createUser(username, password, role) {
+        this.checkConnected();
+        return this.client.createUser(username, password, role);
+    }
+    /**
+     * Deletes a user.
+     * @param username - The username to delete.
+     * @returns True if successful.
+     */
+    async deleteUser(username) {
+        this.checkConnected();
+        return this.client.deleteUser(username);
+    }
+    /**
+     * Retrieves user details.
+     * @param username - The username.
+     * @returns User details object.
+     */
+    async getUser(username) {
+        this.checkConnected();
+        return this.client.getUser(username);
+    }
+    /**
+     * Lists all users.
+     * @returns An array of user objects.
+     */
+    async listUsers() {
+        this.checkConnected();
+        return this.client.listUsers();
+    }
+    /**
+     * 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.
+     */
+    async insert(nodeId, text, metadata, userId = 1, sessionId, embedding) {
+        this.checkConnected();
+        return this.client.insert(nodeId, text, metadata, userId, sessionId, embedding);
+    }
+    /**
+     * 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.
+     */
+    async search(query, userId, k = 10, sessionId, filter, queryEmbedding) {
+        this.checkConnected();
+        return this.client.search(query, userId, k, sessionId, filter, queryEmbedding);
+    }
+    /**
+     * Deletes a document/node.
+     * @param nodeId - The ID of the node to delete.
+     * @param sessionId - Optional session ID.
+     * @returns True if successful.
+     */
+    async delete(nodeId, sessionId) {
+        this.checkConnected();
+        return this.client.delete(nodeId, sessionId);
+    }
+    /**
+     * Creates a new session.
+     * @param parentSessionId - Optional parent session ID to fork from.
+     * @returns The new session ID.
+     */
+    async createSession(parentSessionId) {
+        this.checkConnected();
+        return this.client.createSession(parentSessionId);
+    }
+    /**
+     * 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.
+     */
+    async snapshotSession(sessionId, path) {
+        this.checkConnected();
+        return this.client.snapshotSession(sessionId, path);
+    }
+    /**
+     * Loads a session from a snapshot.
+     * @param path - The file path to load from.
+     * @returns The loaded session ID.
+     */
+    async loadSession(path) {
+        this.checkConnected();
+        return this.client.loadSession(path);
+    }
+    /**
+     * 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.
+     */
+    async commitSession(sessionId, mergeStrategy = "overwrite") {
+        this.checkConnected();
+        return this.client.commitSession(sessionId, mergeStrategy);
+    }
+    /**
+     * Drops (deletes) a session.
+     * @param sessionId - The session ID.
+     * @returns True if successful.
+     */
+    async dropSession(sessionId) {
+        this.checkConnected();
+        return this.client.dropSession(sessionId);
+    }
+    /**
+     * 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.
+     */
+    async writeMemory(address, data, userId = 1) {
+        this.checkConnected();
+        return this.client.writeMemory(address, data, userId);
+    }
+    /**
+     * 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).
+     */
+    async readMemory(address, userId = 1) {
+        this.checkConnected();
+        return this.client.readMemory(address, userId);
+    }
+    /**
+     * 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.
+     */
+    async addMemory(sessionId, agentId, content, metadata = {}, ttlSeconds) {
+        this.checkConnected();
+        return this.client.addMemory(sessionId, agentId, content, metadata, ttlSeconds);
+    }
+    /**
+     * 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.
+     */
+    async getMemory(sessionId, limit = 50, after = 0, filter = {}) {
+        this.checkConnected();
+        return this.client.getMemory(sessionId, limit, after, filter);
+    }
+    /**
+     * Clears all memories for a session.
+     * @param sessionId - The session ID.
+     * @returns Success status.
+     */
+    async clearMemory(sessionId) {
+        this.checkConnected();
+        return this.client.clearMemory(sessionId);
+    }
+    /**
+     * Watches for changes in memory for a session.
+     * @param sessionId - The session ID.
+     * @returns An async iterable of changes.
+     */
+    async *watchMemory(sessionId) {
+        this.checkConnected();
+        yield* this.client.watchMemory(sessionId);
+    }
+    /**
+     * 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.
+     */
+    async addEdge(fromNode, toNode, relation, weight = 1.0) {
+        this.checkConnected();
+        return this.client.addEdge(fromNode, toNode, relation, weight);
+    }
+    /**
+     * Gets neighboring nodes.
+     * @param nodeId - The node ID.
+     * @param relation - Optional relation type to filter by.
+     * @returns An array of neighbor node IDs.
+     */
+    async getNeighbors(nodeId, relation) {
+        this.checkConnected();
+        return this.client.getNeighbors(nodeId, relation);
+    }
+    /**
+     * 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.
+     */
+    async traverse(startNode, maxDepth = 1) {
+        this.checkConnected();
+        return this.client.traverse(startNode, maxDepth);
+    }
+    /**
+     * Samples random nodes from the graph.
+     * @param limit - Number of nodes to sample.
+     * @returns Sampled nodes.
+     */
+    async sampleGraph(limit = 100) {
+        this.checkConnected();
+        return this.client.sampleGraph(limit);
+    }
+    /**
+     * 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.
+     */
+    async *subscribe(filterType = "all", nodeId, queryText = "", threshold = 0.8) {
+        this.checkConnected();
+        yield* this.client.subscribe(filterType, nodeId, queryText, threshold);
+    }
+    /**
+     * Inserts multiple documents in a batch.
+     * @param documents - Array of documents.
+     * @param userId - User ID.
+     * @returns Count of inserted items and their node IDs.
+     */
+    async batchInsert(documents, userId = 1) {
+        this.checkConnected();
+        return this.client.batchInsert(documents, userId);
+    }
+    /**
+     * 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.
+     */
+    async grantPermission(nodeId, userId, permissions) {
+        this.checkConnected();
+        return this.client.grantPermission(nodeId, userId, permissions);
+    }
+    /**
+     * Revokes all permissions on a node for a user.
+     * @param nodeId - Node ID.
+     * @param userId - User ID.
+     * @returns True if successful.
+     */
+    async revokePermission(nodeId, userId) {
+        this.checkConnected();
+        return this.client.revokePermission(nodeId, userId);
+    }
+    /**
+     * 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.
+     */
+    async checkPermission(nodeId, userId, permissionType) {
+        this.checkConnected();
+        return this.client.checkPermission(nodeId, userId, permissionType);
+    }
+    /**
+     * Grants permissions in batch.
+     * @param grants - Array of grant objects.
+     * @returns Detailed results of the operation.
+     */
+    async batchGrant(grants) {
+        this.checkConnected();
+        return this.client.batchGrant(grants);
+    }
+    /**
+     * 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.
+     */
+    async insertWithAcl(nodeId, text, metadata, userPermissions) {
+        this.checkConnected();
+        return this.client.insertWithAcl(nodeId, text, metadata, userPermissions);
+    }
+    // Helper to convert inputs to Long
+    toLong(val) {
+        return long_1.default.fromValue(val);
+    }
+}
+exports.RiceDBClient = RiceDBClient;

package/dist/storage/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./client/BaseClient";
+export * from "./client/GrpcClient";
+export * from "./client/HttpClient";
+export * from "./client/RiceDBClient";
+export * from "./utils/BitVector";
+export { RiceDBClient as default } from "./client/RiceDBClient";
+import Long from "long";
+export { Long };

package/dist/storage/index.js

@@ -0,0 +1,29 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Long = exports.default = void 0;
+__exportStar(require("./client/BaseClient"), exports);
+__exportStar(require("./client/GrpcClient"), exports);
+__exportStar(require("./client/HttpClient"), exports);
+__exportStar(require("./client/RiceDBClient"), exports);
+__exportStar(require("./utils/BitVector"), exports);
+var RiceDBClient_1 = require("./client/RiceDBClient");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return RiceDBClient_1.RiceDBClient; } });
+const long_1 = __importDefault(require("long"));
+exports.Long = long_1.default;