rice-node-sdk 1.0.0

package/README.md

@@ -0,0 +1,270 @@
+# Rice Node SDK
+
+Unified Node.js/TypeScript SDK for RiceDB (Persistent Semantic Database) and State (AI Memory).
+
+## Installation
+
+```bash
+npm install rice-node-sdk
+```
+
+## Quick Start
+
+The SDK provides a unified `Client` to access both Storage and State services.
+
+```typescript
+import { Client } from "rice-node-sdk";
+
+// Initialize client (loads config from rice.config.js and .env)
+const client = new Client();
+await client.connect();
+
+// --- Storage (RiceDB) ---
+// Insert data
+await client.storage.insert(
+  "unique-node-id",
+  "This is a piece of information stored in RiceDB.",
+  { category: "example", value: 123 }
+);
+
+// Search for similar data
+const results = await client.storage.search("information stored", 1, 5);
+console.log(results);
+
+// --- State (AI Memory) ---
+// Focus on a context/task
+await client.state.focus("User is asking about weather");
+
+// Store a long-term memory (commit)
+await client.state.commit(
+  "The user prefers metric units for temperature.",
+  "User preference noted.",
+  {
+    source: "conversation",
+  }
+);
+
+// Recall relevant memories
+const memories = await client.state.reminisce("weather preferences");
+console.log(memories);
+```
+
+## Configuration
+
+The SDK loads configuration from `rice.config.js` (or `.ts`/`.mjs`), environment variables, and constructor options.
+
+### 1. Configuration File (`rice.config.js`)
+
+Control which services are enabled. Useful for applications that only need Storage or only need State.
+
+```javascript
+/** @type {import('rice-node-sdk').RiceConfig} */
+module.exports = {
+  // Enable/Disable Storage (RiceDB)
+  storage: {
+    enabled: true, // Set to false if you only use State
+  },
+  // Enable/Disable State (Memory)
+  state: {
+    enabled: true, // Set to false if you only use Storage
+  },
+};
+```
+
+### 2. Environment Variables (`.env`)
+
+Configure connection details and authentication.
+
+```bash
+# --- Storage (RiceDB) ---
+# URL of your RiceDB instance (default: localhost:50051)
+STORAGE_INSTANCE_URL=localhost:50051
+# Auth token (if enabled on server)
+STORAGE_AUTH_TOKEN=my-secret-token
+# User for auto-login (default: admin)
+STORAGE_USER=admin
+
+# --- State (Memory) ---
+# URL of your State instance
+STATE_INSTANCE_URL=localhost:50051
+# Auth token
+STATE_AUTH_TOKEN=my-secret-token
+# Default Run ID for memory sessions (optional)
+STATE_RUN_ID=default-run-id
+
+# --- LLM Providers (for examples) ---
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+GOOGLE_API_KEY=...
+```
+
+### 3. Advanced Configuration
+
+#### Custom Config Path
+
+You can load a specific config file by passing the path to the `Client` constructor.
+
+```typescript
+const client = new Client({ configPath: "./config/prod.rice.config.js" });
+```
+
+#### Managing Run IDs (Multi-User/Multi-Agent)
+
+For State memory, the `runId` determines the session or agent context. You can switch run IDs dynamically to manage memory for different users or agents.
+
+```typescript
+// Option A: Set globally in constructor
+const client = new Client({ runId: "user-123-session" });
+
+// Option B: Switch dynamically
+client.state.setRunId("user-456-session");
+await client.state.focus("New task for user 456");
+```
+
+## AI Tool Definitions
+
+The SDK provides pre-built tool definitions tailored for popular LLM providers. These tools map directly to State memory operations.
+
+### Available Imports
+
+- `rice-node-sdk/tools/anthropic`
+- `rice-node-sdk/tools/google`
+- `rice-node-sdk/tools/openai`
+
+### Example Usage (Anthropic)
+
+```typescript
+import { state as anthropicTools } from "rice-node-sdk/tools/anthropic";
+import { executeTool } from "rice-node-sdk/tools/execute";
+import { Client } from "rice-node-sdk";
+
+const client = new Client();
+await client.connect();
+
+// 1. Pass tools to your LLM
+const response = await anthropic.messages.create({
+  model: "claude-3-opus-20240229",
+  tools: anthropicTools,
+  // ...
+});
+
+// 2. Execute tools invoked by the LLM
+for (const toolUse of response.content.filter((c) => c.type === "tool_use")) {
+  const result = await executeTool(client.state, toolUse.name, toolUse.input);
+  console.log("Tool result:", result);
+}
+```
+
+### Example Usage (OpenAI)
+
+```typescript
+import { state as openaiTools } from "rice-node-sdk/tools/openai";
+import { executeTool } from "rice-node-sdk/tools/execute";
+import { Client } from "rice-node-sdk";
+
+const client = new Client();
+await client.connect();
+
+// 1. Pass tools to OpenAI
+const response = await openai.chat.completions.create({
+  model: "gpt-4",
+  messages: [
+    /* ... */
+  ],
+  tools: openaiTools, // Tools are already in OpenAI format
+});
+
+// 2. Execute tools
+const toolCalls = response.choices[0].message.tool_calls;
+if (toolCalls) {
+  for (const toolCall of toolCalls) {
+    const args = JSON.parse(toolCall.function.arguments);
+    const result = await executeTool(
+      client.state,
+      toolCall.function.name,
+      args
+    );
+    console.log("Tool result:", result);
+  }
+}
+```
+
+### Example Usage (Google Gemini)
+
+```typescript
+import { state as googleTools } from "rice-node-sdk/tools/google";
+import { executeTool } from "rice-node-sdk/tools/execute";
+import { Client } from "rice-node-sdk";
+
+const client = new Client();
+await client.connect();
+
+// 1. Pass tools to Gemini
+const model = genAI.getGenerativeModel({
+  model: "gemini-3-flash-preview",
+  tools: [{ functionDeclarations: googleTools }],
+});
+
+// 2. Execute tools
+const chat = model.startChat();
+const result = await chat.sendMessage("Remember that I like pizza.");
+const call = result.response.functionCalls()?.[0];
+
+if (call) {
+  const result = await executeTool(client.state, call.name, call.args);
+  console.log("Tool result:", result);
+}
+```
+
+### Tools Included
+
+| Tool       | Purpose                                          | SDK Method                 |
+| ---------- | ------------------------------------------------ | -------------------------- |
+| `focus`    | Store information in short-term working memory   | `client.state.focus()`     |
+| `remember` | Store information in long-term persistent memory | `client.state.commit()`    |
+| `recall`   | Retrieve relevant memories from long-term memory | `client.state.reminisce()` |
+
+> **Note**: The `remember` tool provided to LLMs maps to the `commit` method in the SDK.
+
+## API Reference
+
+### Client
+
+```typescript
+class Client {
+  constructor(options?: { configPath?: string; runId?: string });
+  async connect(): Promise<void>;
+  get storage(): RiceDBClient;
+  get state(): StateClient;
+}
+```
+
+### Storage (RiceDB)
+
+```typescript
+interface RiceDBClient {
+  insert(id: string, text: string, metadata?: object): Promise<void>;
+  search(
+    query: string,
+    limit?: number,
+    offset?: number
+  ): Promise<SearchResult[]>;
+  delete(id: string): Promise<void>;
+  // ... graph operations
+}
+```
+
+### State (Memory)
+
+```typescript
+interface StateClient {
+  focus(content: string): Promise<void>;
+  commit(input: string, output: string, metadata?: object): Promise<void>;
+  reminisce(query: string): Promise<string[]>;
+  setRunId(runId: string): void;
+}
+```
+
+## License
+
+ISC

package/dist/Client.d.ts

@@ -0,0 +1,16 @@
+import { RiceDBClient } from "./storage/client/RiceDBClient";
+import { StateClient } from "./state";
+export interface ClientOptions {
+    configPath?: string;
+    runId?: string;
+}
+export declare class Client {
+    private _config;
+    private _storage;
+    private _state;
+    private options;
+    constructor(optionsOrPath?: string | ClientOptions);
+    connect(): Promise<void>;
+    get storage(): RiceDBClient;
+    get state(): StateClient;
+}

package/dist/Client.js

@@ -0,0 +1,117 @@
+"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.Client = void 0;
+const config_1 = require("./config");
+const RiceDBClient_1 = require("./storage/client/RiceDBClient");
+const state_1 = require("./state");
+const dotenv = __importStar(require("dotenv"));
+const path = __importStar(require("path"));
+class Client {
+    constructor(optionsOrPath) {
+        this._config = null;
+        this._storage = null;
+        this._state = null;
+        if (typeof optionsOrPath === "string") {
+            this.options = { configPath: optionsOrPath };
+        }
+        else {
+            this.options = optionsOrPath || {};
+        }
+    }
+    async connect() {
+        // Load environment variables
+        dotenv.config({ path: path.resolve(process.cwd(), ".env") });
+        // Load config
+        this._config = await (0, config_1.loadConfig)(this.options.configPath);
+        // Initialize Storage
+        if (this._config.storage?.enabled) {
+            const storageUrl = process.env.STORAGE_INSTANCE_URL ||
+                process.env.RICEDB_HOST ||
+                "localhost:50051";
+            // Parse host and port
+            let host = "localhost";
+            let port = 50051;
+            const parts = storageUrl.split(":");
+            if (parts.length === 2) {
+                host = parts[0];
+                port = parseInt(parts[1], 10);
+            }
+            else {
+                host = storageUrl;
+            }
+            const token = process.env.STORAGE_AUTH_TOKEN;
+            const user = process.env.STORAGE_USER || "admin";
+            // We assume STORAGE_INSTANCE_URL points to the gRPC port
+            // Pass token to constructor initially (if it's a valid token, it works; if it's a password, we login)
+            this._storage = new RiceDBClient_1.RiceDBClient(host, "auto", port, 3000, token);
+            await this._storage.connect();
+            if (token) {
+                try {
+                    // Attempt auto-login using the token as password
+                    console.log(`Attempting login for user ${user}...`);
+                    const newToken = await this._storage.login(user, token);
+                    console.log(`Login successful. Token length: ${newToken.length}`);
+                }
+                catch (e) {
+                    // If login fails, maybe the token was already a valid session token?
+                    // Or credentials are wrong. We log warning but don't crash,
+                    // allowing subsequent calls to fail if auth is missing.
+                    console.warn(`Auto-login failed for user ${user}:`, e);
+                }
+            }
+        }
+        // Initialize State
+        if (this._config.state?.enabled) {
+            const address = process.env.STATE_INSTANCE_URL || "localhost:50051";
+            const token = process.env.STATE_AUTH_TOKEN;
+            const runId = this.options.runId || process.env.STATE_RUN_ID || "default";
+            this._state = new state_1.StateClient(address, token, runId);
+        }
+    }
+    get storage() {
+        if (!this._storage) {
+            throw new Error("Config mismatch: storage is not enabled or not connected");
+        }
+        return this._storage;
+    }
+    get state() {
+        if (!this._state) {
+            throw new Error("Config mismatch: state is not enabled or not connected");
+        }
+        return this._state;
+    }
+}
+exports.Client = Client;

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export interface RiceConfig {
+    storage?: {
+        enabled: boolean;
+    };
+    state?: {
+        enabled: boolean;
+        llm_mode?: boolean;
+        flux?: {
+            enabled: boolean;
+        };
+    };
+}
+export declare function loadConfig(configPath?: string): Promise<RiceConfig>;

package/dist/config.js

@@ -0,0 +1,53 @@
+"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.loadConfig = loadConfig;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+async function loadConfig(configPath) {
+    const defaultPath = path.resolve(process.cwd(), "rice.config.js");
+    const filePath = configPath ? path.resolve(configPath) : defaultPath;
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Config file not found at ${filePath}`);
+    }
+    try {
+        // Dynamic import to support both ESM and CJS if environment allows
+        const configModule = await Promise.resolve(`${filePath}`).then(s => __importStar(require(s)));
+        return configModule.default || configModule;
+    }
+    catch (error) {
+        throw new Error(`Failed to load config from ${filePath}: ${error}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Rice Node SDK
+ * Unified client for RiceDB (Storage) and State (AI Memory).
+ */
+import { Client } from "./Client";
+export * from "./storage";
+export * from "./state";
+export * from "./Client";
+export * from "./config";
+export * from "./state/tools";
+declare const _default: {
+    Client: typeof Client;
+    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 import("./tools/execute").execute;
+    };
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Rice Node SDK
+ * Unified client for RiceDB (Storage) and State (AI Memory).
+ */
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Client_1 = require("./Client");
+const tools_1 = require("./state/tools");
+// Re-export types and classes from storage (for typing usage)
+__exportStar(require("./storage"), exports);
+// Re-export types and classes from state (for typing usage)
+__exportStar(require("./state"), exports);
+// Export Unified Client, Config, and Tools
+__exportStar(require("./Client"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./state/tools"), exports);
+exports.default = {
+    Client: Client_1.Client,
+    statetool: tools_1.statetool,
+};

package/dist/state/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Client for interacting with State (AI Memory).
+ * Provides methods for managing conversational memory, drift, and skills.
+ */
+export declare class StateClient {
+    private client;
+    private metadata;
+    private runId;
+    /**
+     * 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?: string, token?: string, runId?: string);
+    /**
+     * Sets the run ID for subsequent operations.
+     * @param runId - The new run ID to use.
+     */
+    setRunId(runId: string): void;
+    /**
+     * 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: string): Promise<string>;
+    /**
+     * Retrieves the current drift or context drift items.
+     * @returns A promise that resolves to an array of drift items.
+     */
+    drift(): Promise<any[]>;
+    /**
+     * 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: string, outcome: string, options?: {
+        action?: string;
+        reasoning?: string;
+        agent_id?: string;
+    }): Promise<boolean>;
+    /**
+     * 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: string, limit?: number): Promise<any[]>;
+    /**
+     * 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: string): Promise<number>;
+    /**
+     * Deletes the current run/session and its associated data.
+     * @returns A promise that resolves to true if successful.
+     */
+    deleteRun(): Promise<boolean>;
+}