rice-node-sdk 1.0.2 → 1.0.3

package/dist/state/index.d.ts

@@ -45,9 +45,12 @@ export declare class StateClient {
      * 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.
+     * @param filter - Optional metadata filter.
      * @returns A promise that resolves to an array of traces/memories.
      */
-    reminisce(query: string, limit?: number): Promise<any[]>;
+    reminisce(query: string, limit?: number, filter?: {
+        [key: string]: any;
+    }): Promise<any[]>;
     /**
      * Triggers a specific skill or action.
      * @param skillName - The name of the skill to trigger.
@@ -59,4 +62,90 @@ export declare class StateClient {
      * @returns A promise that resolves to true if successful.
      */
     deleteRun(): Promise<boolean>;
+    /**
+     * Sets a variable in working memory.
+     * @param name - The name of the variable.
+     * @param value - The value to store (will be JSON-encoded).
+     * @param source - The source of the variable. Defaults to "explicit".
+     * @returns A promise that resolves to true if successful.
+     */
+    setVariable(name: string, value: any, source?: string): Promise<boolean>;
+    /**
+     * Gets a variable from working memory.
+     * @param name - The name of the variable to retrieve.
+     * @returns A promise that resolves to the variable details including value, type, and metadata.
+     */
+    getVariable(name: string): Promise<any>;
+    /**
+     * Lists all variables in working memory.
+     * @returns A promise that resolves to an array of variables.
+     */
+    listVariables(): Promise<any[]>;
+    /**
+     * Deletes a variable from working memory.
+     * @param name - The name of the variable to delete.
+     * @returns A promise that resolves to true if successful.
+     */
+    deleteVariable(name: string): Promise<boolean>;
+    /**
+     * Defines a concept with a schema.
+     * @param name - The name of the concept.
+     * @param schema - The schema definition (object or JSON string).
+     * @returns A promise that resolves to true if successful.
+     */
+    defineConcept(name: string, schema: any): Promise<boolean>;
+    /**
+     * Lists all defined concepts.
+     * @returns A promise that resolves to an array of concepts with their schemas.
+     */
+    listConcepts(): Promise<any[]>;
+    /**
+     * Adds a new goal.
+     * @param description - The description of the goal.
+     * @param priority - The priority level ("low", "medium", "high", "critical"). Defaults to "medium".
+     * @param parentId - Optional parent goal ID for hierarchical goals.
+     * @returns A promise that resolves to the created goal details.
+     */
+    addGoal(description: string, priority?: string, parentId?: string): Promise<any>;
+    /**
+     * Updates a goal's status.
+     * @param goalId - The ID of the goal to update.
+     * @param status - The new status ("active", "suspended", "achieved", "abandoned", "failed").
+     * @returns A promise that resolves to true if successful.
+     */
+    updateGoal(goalId: string, status: string): Promise<boolean>;
+    /**
+     * Lists all goals, optionally filtered by status.
+     * @param statusFilter - Optional status to filter by.
+     * @returns A promise that resolves to an array of goals.
+     */
+    listGoals(statusFilter?: string): Promise<any[]>;
+    /**
+     * Submits an action for execution.
+     * @param agentId - The ID of the agent submitting the action.
+     * @param actionType - The type of action ("reason", "retrieve", "learn", "ground").
+     * @param actionDetails - The action details (will be JSON-encoded).
+     * @returns A promise that resolves to the action result.
+     */
+    submitAction(agentId: string, actionType: string, actionDetails: any): Promise<any>;
+    /**
+     * Gets the action log for the current run.
+     * @param limit - Maximum number of entries to retrieve. Defaults to 100.
+     * @param actionTypeFilter - Optional action type to filter by.
+     * @returns A promise that resolves to an array of action log entries.
+     */
+    getActionLog(limit?: number, actionTypeFilter?: string): Promise<any[]>;
+    /**
+     * Runs a decision cycle, optionally with pre-proposed action candidates.
+     * @param agentId - The ID of the agent running the cycle.
+     * @param candidates - Optional array of action candidates with scores and rationales.
+     * @returns A promise that resolves to the cycle result.
+     */
+    runCycle(agentId: string, candidates?: any[]): Promise<any>;
+    /**
+     * Gets the decision cycle history for the current run.
+     * @param limit - Maximum number of cycles to retrieve. Defaults to 100.
+     * @returns A promise that resolves to an array of cycle records.
+     */
+    getCycleHistory(limit?: number): Promise<any[]>;
 }

package/dist/state/index.js

@@ -135,15 +135,17 @@ class StateClient {
      * 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.
+     * @param filter - Optional metadata filter.
      * @returns A promise that resolves to an array of traces/memories.
      */
-    reminisce(query, limit = 5) {
+    reminisce(query, limit = 5, filter) {
         return new Promise((resolve, reject) => {
             const req = {
                 embedding: [],
                 limit,
                 query_text: query,
                 run_id: this.runId,
+                filter: filter ? JSON.stringify(filter) : undefined,
             };
             this.client.Reminisce(req, this.metadata, (err, response) => {
                 if (err)
@@ -185,5 +187,324 @@ class StateClient {
             });
         });
     }
+    // ==========================================================================
+    // Working Memory (Structured Variables)
+    // ==========================================================================
+    /**
+     * Sets a variable in working memory.
+     * @param name - The name of the variable.
+     * @param value - The value to store (will be JSON-encoded).
+     * @param source - The source of the variable. Defaults to "explicit".
+     * @returns A promise that resolves to true if successful.
+     */
+    setVariable(name, value, source = "explicit") {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                name,
+                value_json: JSON.stringify(value),
+                source,
+            };
+            this.client.SetVariable(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.success);
+            });
+        });
+    }
+    /**
+     * Gets a variable from working memory.
+     * @param name - The name of the variable to retrieve.
+     * @returns A promise that resolves to the variable details including value, type, and metadata.
+     */
+    getVariable(name) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                name,
+            };
+            this.client.GetVariable(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve({
+                        name: response.name,
+                        value: JSON.parse(response.value_json || "null"),
+                        varType: response.var_type,
+                        createdAt: response.created_at,
+                        lastUpdated: response.last_updated,
+                        accessCount: response.access_count,
+                        source: response.source,
+                    });
+            });
+        });
+    }
+    /**
+     * Lists all variables in working memory.
+     * @returns A promise that resolves to an array of variables.
+     */
+    listVariables() {
+        return new Promise((resolve, reject) => {
+            this.client.ListVariables({ run_id: this.runId }, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve((response.variables || []).map((v) => ({
+                        name: v.name,
+                        value: JSON.parse(v.value_json || "null"),
+                        varType: v.var_type,
+                        source: v.source,
+                    })));
+            });
+        });
+    }
+    /**
+     * Deletes a variable from working memory.
+     * @param name - The name of the variable to delete.
+     * @returns A promise that resolves to true if successful.
+     */
+    deleteVariable(name) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                name,
+            };
+            this.client.DeleteVariable(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.success);
+            });
+        });
+    }
+    // ==========================================================================
+    // Concepts (Level 4 Agency)
+    // ==========================================================================
+    /**
+     * Defines a concept with a schema.
+     * @param name - The name of the concept.
+     * @param schema - The schema definition (object or JSON string).
+     * @returns A promise that resolves to true if successful.
+     */
+    defineConcept(name, schema) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                name,
+                schema_json: typeof schema === "string" ? schema : JSON.stringify(schema),
+            };
+            this.client.DefineConcept(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.success);
+            });
+        });
+    }
+    /**
+     * Lists all defined concepts.
+     * @returns A promise that resolves to an array of concepts with their schemas.
+     */
+    listConcepts() {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+            };
+            this.client.ListConcepts(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve((response.concepts || []).map((c) => ({
+                        name: c.name,
+                        schema: JSON.parse(c.schema_json || "{}"),
+                    })));
+            });
+        });
+    }
+    // ==========================================================================
+    // Goals
+    // ==========================================================================
+    /**
+     * Adds a new goal.
+     * @param description - The description of the goal.
+     * @param priority - The priority level ("low", "medium", "high", "critical"). Defaults to "medium".
+     * @param parentId - Optional parent goal ID for hierarchical goals.
+     * @returns A promise that resolves to the created goal details.
+     */
+    addGoal(description, priority = "medium", parentId) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                description,
+                priority,
+                parent_id: parentId || "",
+            };
+            this.client.AddGoal(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response);
+            });
+        });
+    }
+    /**
+     * Updates a goal's status.
+     * @param goalId - The ID of the goal to update.
+     * @param status - The new status ("active", "suspended", "achieved", "abandoned", "failed").
+     * @returns A promise that resolves to true if successful.
+     */
+    updateGoal(goalId, status) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                goal_id: goalId,
+                status,
+            };
+            this.client.UpdateGoal(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.success);
+            });
+        });
+    }
+    /**
+     * Lists all goals, optionally filtered by status.
+     * @param statusFilter - Optional status to filter by.
+     * @returns A promise that resolves to an array of goals.
+     */
+    listGoals(statusFilter) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                status_filter: statusFilter || "",
+            };
+            this.client.ListGoals(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.goals || []);
+            });
+        });
+    }
+    // ==========================================================================
+    // Actions
+    // ==========================================================================
+    /**
+     * Submits an action for execution.
+     * @param agentId - The ID of the agent submitting the action.
+     * @param actionType - The type of action ("reason", "retrieve", "learn", "ground").
+     * @param actionDetails - The action details (will be JSON-encoded).
+     * @returns A promise that resolves to the action result.
+     */
+    submitAction(agentId, actionType, actionDetails) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                agent_id: agentId,
+                action_type: actionType,
+                action_json: JSON.stringify(actionDetails),
+            };
+            this.client.SubmitAction(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve({
+                        actionId: response.action_id,
+                        success: response.success,
+                        result: response.result_json
+                            ? JSON.parse(response.result_json)
+                            : null,
+                        error: response.error,
+                        durationMs: response.duration_ms,
+                    });
+            });
+        });
+    }
+    /**
+     * Gets the action log for the current run.
+     * @param limit - Maximum number of entries to retrieve. Defaults to 100.
+     * @param actionTypeFilter - Optional action type to filter by.
+     * @returns A promise that resolves to an array of action log entries.
+     */
+    getActionLog(limit = 100, actionTypeFilter) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                limit,
+                action_type_filter: actionTypeFilter || "",
+            };
+            this.client.GetActionLog(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve((response.entries || []).map((e) => ({
+                        actionId: e.action_id,
+                        actionType: e.action_type,
+                        action: e.action_json ? JSON.parse(e.action_json) : null,
+                        success: e.success,
+                        result: e.result_json ? JSON.parse(e.result_json) : null,
+                        cycleNumber: e.cycle_number,
+                        timestamp: e.timestamp,
+                    })));
+            });
+        });
+    }
+    // ==========================================================================
+    // Decision Cycle
+    // ==========================================================================
+    /**
+     * Runs a decision cycle, optionally with pre-proposed action candidates.
+     * @param agentId - The ID of the agent running the cycle.
+     * @param candidates - Optional array of action candidates with scores and rationales.
+     * @returns A promise that resolves to the cycle result.
+     */
+    runCycle(agentId, candidates) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                agent_id: agentId,
+                candidates: (candidates || []).map((c) => ({
+                    action_type: c.actionType,
+                    action_json: JSON.stringify(c.action),
+                    score: c.score,
+                    rationale: c.rationale || "",
+                })),
+            };
+            this.client.RunCycle(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve({
+                        cycleNumber: response.cycle_number,
+                        selectedAction: response.selected_action,
+                        actionResult: response.action_result,
+                        planningTimeMs: response.planning_time_ms,
+                        executionTimeMs: response.execution_time_ms,
+                        timestamp: response.timestamp,
+                    });
+            });
+        });
+    }
+    /**
+     * Gets the decision cycle history for the current run.
+     * @param limit - Maximum number of cycles to retrieve. Defaults to 100.
+     * @returns A promise that resolves to an array of cycle records.
+     */
+    getCycleHistory(limit = 100) {
+        return new Promise((resolve, reject) => {
+            const req = {
+                run_id: this.runId,
+                limit,
+            };
+            this.client.GetCycleHistory(req, this.metadata, (err, response) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(response.cycles || []);
+            });
+        });
+    }
 }
 exports.StateClient = StateClient;

package/dist/state/proto/state.proto

@@ -2,20 +2,43 @@ syntax = "proto3";
 package slate;
 
 service Cortex {
-  // Flux
+  // Flux (Legacy Working Memory)
   rpc Focus(FocusRequest) returns (FocusResponse);
   rpc Drift(DriftRequest) returns (DriftResponse);
 
-  // Echoes
+  // Echoes (Episodic Memory)
   rpc Commit(Trace) returns (Ack);
   rpc Reminisce(RecallRequest) returns (RecallResponse);
 
-  // Nexus
+  // Nexus (Semantic Memory)
   rpc Consult(QueryRequest) returns (KnowledgeResponse);
 
-  // Reflex
+  // Reflex (Procedural Memory)
   rpc Trigger(ReflexRequest) returns (ExecutionResult);
 
+  // Working Memory (Structured Variables)
+  rpc SetVariable(SetVariableRequest) returns (Ack);
+  rpc GetVariable(GetVariableRequest) returns (VariableResponse);
+  rpc ListVariables(ListVariablesRequest) returns (ListVariablesResponse);
+  rpc DeleteVariable(DeleteVariableRequest) returns (Ack);
+
+  // Concepts (Level 4 Agency)
+  rpc DefineConcept(DefineConceptRequest) returns (Ack);
+  rpc ListConcepts(ListConceptsRequest) returns (ListConceptsResponse);
+
+  // Goals
+  rpc AddGoal(AddGoalRequest) returns (GoalResponse);
+  rpc UpdateGoal(UpdateGoalRequest) returns (Ack);
+  rpc ListGoals(ListGoalsRequest) returns (ListGoalsResponse);
+
+  // Actions
+  rpc SubmitAction(ActionRequest) returns (ActionResponse);
+  rpc GetActionLog(ActionLogRequest) returns (ActionLogResponse);
+
+  // Decision Cycle
+  rpc RunCycle(RunCycleRequest) returns (CycleResponse);
+  rpc GetCycleHistory(CycleHistoryRequest) returns (CycleHistoryResponse);
+
   // Management
   rpc DeleteRun(RunRequest) returns (Ack);
 }
@@ -98,3 +121,174 @@ message ReflexRequest {
 message ExecutionResult {
   int32 result = 1;
 }
+
+// =============================================================================
+// Working Memory (Structured Variables)
+// =============================================================================
+
+message SetVariableRequest {
+  string run_id = 1;
+  string name = 2;
+  string value_json = 3;  // JSON-encoded value
+  string source = 4;      // "system", "reasoning", "retrieval", "perception", "explicit"
+}
+
+message GetVariableRequest {
+  string run_id = 1;
+  string name = 2;
+}
+
+message VariableResponse {
+  string name = 1;
+  string value_json = 2;
+  string var_type = 3;
+  string created_at = 4;
+  string last_updated = 5;
+  uint64 access_count = 6;
+  string source = 7;
+}
+
+message ListVariablesRequest {
+  string run_id = 1;
+}
+
+message ListVariablesResponse {
+  repeated VariableResponse variables = 1;
+}
+
+message DeleteVariableRequest {
+  string run_id = 1;
+  string name = 2;
+}
+
+// =============================================================================
+// Concepts (Level 4 Agency)
+// =============================================================================
+
+message DefineConceptRequest {
+  string run_id = 1;
+  string name = 2;
+  string schema_json = 3;
+}
+
+message ListConceptsRequest {
+  string run_id = 1;
+}
+
+message Concept {
+  string name = 1;
+  string schema_json = 2;
+}
+
+message ListConceptsResponse {
+  repeated Concept concepts = 1;
+}
+
+// =============================================================================
+// Goals
+// =============================================================================
+
+message AddGoalRequest {
+  string run_id = 1;
+  string description = 2;
+  string priority = 3;    // "low", "medium", "high", "critical"
+  string parent_id = 4;   // Optional parent goal ID
+}
+
+message GoalResponse {
+  string id = 1;
+  string description = 2;
+  string priority = 3;
+  string status = 4;
+  string parent_id = 5;
+  string created_at = 6;
+}
+
+message UpdateGoalRequest {
+  string run_id = 1;
+  string goal_id = 2;
+  string status = 3;      // "active", "suspended", "achieved", "abandoned", "failed"
+}
+
+message ListGoalsRequest {
+  string run_id = 1;
+  string status_filter = 2;  // Optional: filter by status
+}
+
+message ListGoalsResponse {
+  repeated GoalResponse goals = 1;
+}
+
+// =============================================================================
+// Actions
+// =============================================================================
+
+message ActionRequest {
+  string run_id = 1;
+  string agent_id = 2;
+  string action_type = 3;  // "reason", "retrieve", "learn", "ground"
+  string action_json = 4;  // JSON-encoded action details
+}
+
+message ActionResponse {
+  string action_id = 1;
+  bool success = 2;
+  string result_json = 3;
+  string error = 4;
+  uint64 duration_ms = 5;
+}
+
+message ActionLogRequest {
+  string run_id = 1;
+  uint64 limit = 2;
+  string action_type_filter = 3;  // Optional
+}
+
+message ActionLogResponse {
+  repeated ActionLogEntry entries = 1;
+}
+
+message ActionLogEntry {
+  string action_id = 1;
+  string action_type = 2;
+  string action_json = 3;
+  bool success = 4;
+  string result_json = 5;
+  uint64 cycle_number = 6;
+  string timestamp = 7;
+}
+
+// =============================================================================
+// Decision Cycle
+// =============================================================================
+
+message RunCycleRequest {
+  string run_id = 1;
+  string agent_id = 2;
+  repeated ActionCandidate candidates = 3;  // Optional: pre-proposed candidates
+}
+
+message ActionCandidate {
+  string action_type = 1;
+  string action_json = 2;
+  float score = 3;
+  string rationale = 4;
+}
+
+message CycleResponse {
+  uint64 cycle_number = 1;
+  ActionCandidate selected_action = 2;
+  ActionResponse action_result = 3;
+  uint64 planning_time_ms = 4;
+  uint64 execution_time_ms = 5;
+  string timestamp = 6;
+}
+
+message CycleHistoryRequest {
+  string run_id = 1;
+  uint64 limit = 2;
+}
+
+message CycleHistoryResponse {
+  repeated CycleResponse cycles = 1;
+}