@game_ryo/lsji 1.2.0 → 1.2.2

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 **LSJI** (Learning System for JavaScript Intelligence) is a general-purpose Reinforcement Learning agent framework for Node.js. It provides a clean abstraction for building RL agents with pluggable storage backends, environments, and learning algorithms.
 
-Originally migrated from a Cloudflare Workers implementation (Rock-Paper-Scissors AI), now redesigned as a standalone npm package with Apache 2.0 license, targeting Apache Incubator entry.
+Originally migrated from a Cloudflare Workers implementation (Rock-Paper-Scissors AI), now redesigned as a standalone npm package with MIT license, targeting MIT licensed.
 
 ## Architecture
 
@@ -19,6 +19,23 @@ src/
 │   ├── sqlite.js       # node:sqlite implementation (Node 22+)
 │   ├── better-sqlite.js # better-sqlite3 implementation
 │   └── memory.js       # In-memory implementation
+├── execution/          # Production execution systems
+│   ├── budget/         # TokenCounter, CostTracker, CircuitBreaker
+│   ├── hitl/           # ApprovalGate, ApprovalStore, Notifier
+│   ├── idempotency.js  # Duplicate prevention
+│   └── engine.js       # Durable execution with checkpoints
+├── llm/                # LLM Agent Framework
+│   ├── providers/      # OpenAI, Anthropic, Gemini, Local (Ollama)
+│   ├── llm-agent.js    # ReAct agent with tools & memory
+│   ├── tools/          # Built-in tools (web_search, file_read, file_write, code_exec, api_call, send_email, db_query)
+│   ├── memory/         # Conversation, Semantic, Episodic
+│   ├── plugins/        # Dynamic plugin system
+│   └── prompt-manager.js
+├── server/             # Runtime server + Web UI
+│   ├── index.js        # Express + Socket.io
+│   └── ui/             # React + Vite control panel
+├── envs/
+│   └── rps.js          # Rock-Paper-Scissors environment
 ├── cli.js              # Command-line interface
 └── index.js            # Public API exports
 ```
@@ -59,9 +76,9 @@ Pluggable backends:
 
 ## Usage
 
-### As Library
+### As Library (RL)
 ```javascript
-import { Agent, QLearning, createStorage, Env } from 'lsji';
+import { Agent, QLearning, createStorage, Env } from '@game_ryo/lsji';
 
 // Create custom environment
 class MyEnv extends Env {
@@ -77,23 +94,60 @@ await agent.train({ episodes: 1000 });
 const result = await agent.play(userAction);
 ```
 
+### As Library (LLM Agent)
+```javascript
+import { createLLMAgent, startServer } from '@game_ryo/lsji';
+
+// Create an agent with full production features
+const agent = await createLLMAgent({
+  llm: { provider: 'gemini', model: 'gemini-1.5-flash', apiKey: process.env.GEMINI_API_KEY },
+  budget: { maxCostPerRun: 5, maxCostPerDay: 50 },
+  hitl: { enabled: true, defaultTimeout: 300000 }, // 5 min approval timeout
+  memory: { conversation: true, episodic: true, semantic: true },
+  storage: { type: 'sqlite', options: { path: './lsji.db' } },
+});
+
+const result = await agent.run("Research TypeScript best practices and create a summary");
+console.log(result.answer);
+
+// Or start the full runtime server
+const server = await startServer({ port: 3456 });
+// Visit http://localhost:3456 for the web control panel
+```
+
 ### CLI
 ```bash
 # Install globally or use npx
 npm link  # for local development
 
-# Train
-lsji train --episodes 500 --pattern 0
-
-# Play
-lsji play --hand 0  # 0=Rock, 1=Scissors, 2=Paper
-
-# Status
-lsji status --json
-
-# Control
-lsji start
-lsji stop
+# RL Commands
+npx @game_ryo/lsji train --episodes 500 --pattern 0
+npx @game_ryo/lsji play --hand 0  # 0=Rock, 1=Scissors, 2=Paper
+npx @game_ryo/lsji status --json
+npx @game_ryo/lsji start
+npx @game_ryo/lsji stop
+
+# LLM Agent Commands
+npx @game_ryo/lsji agent run --task "Search for latest AI news and summarize" --provider gemini --model gemini-1.5-flash
+npx @game_ryo/lsji agent run-durable --task "Analyze codebase and create report" --workflow-id my-analysis
+npx @game_ryo/lsji agent status
+
+# Budget & Approvals
+npx @game_ryo/lsji budget status --budgetId my-project
+npx @game_ryo/lsji hitl list                       # Pending approvals
+npx @game_ryo/lsji hitl approve --id <id> --reason "Approved"
+
+# Durability
+npx @game_ryo/lsji checkpoint list
+npx @game_ryo/lsji checkpoint show --workflowId my-analysis
+npx @game_ryo/lsji checkpoint recover --workflowId my-analysis
+
+# Plugins
+npx @game_ryo/lsji plugin list
+npx @game_ryo/lsji plugin create --name my-tools
+
+# Server
+npx @game_ryo/lsji serve --port 3456
 ```
 
 ## Development
@@ -102,20 +156,20 @@ lsji stop
 ```bash
 npm test        # Run tests (vitest)
 npm run build   # No build step (ESM)
+npm run build:ui # Build web UI
+npm run serve   # Start runtime server
 ```
 
 ### Testing
-- Tests use `vitest` with `MemoryStorage` for isolation
-- Run `npm test` to verify all functionality
-
-## Key Design Decisions
+- Tests use `vitest` with `Memo## Key Design Decisions
 
 1. **ESM only** - Uses `"type": "module"` in package.json
 2. **Node 22+** - Requires Node 22 for built-in `node:sqlite`
-3. **Apache 2.0** - License compatible with Apache Incubator
+3. **MIT** - License compatible with open source
 4. **Single package** - All core functionality in one npm package
 5. **Storage abstraction** - Easy to swap backends
 6. **Worker.js compatibility** - Training patterns and reward logic match original
+7. **Production-grade** - HITL, durability, budget controls, idempotency built-in
 
 ## Common Tasks
 
@@ -129,6 +183,11 @@ npm run build   # No build step (ESM)
 2. Implement all abstract methods
 3. Add to `createStorage` factory
 
+### Adding a New LLM Tool
+1. Create tool definition in `src/llm/tools/registry.js` or plugin
+2. Implement `execute` function
+3. Add to tool registry
+
 ### Modifying Learning Algorithm
 - Extend `QLearning` class or create new algorithm in `src/core/`
 
@@ -140,4 +199,14 @@ npm run build   # No build step (ESM)
 
 ## License
 
-Apache 2.0 - see LICENSE file
+MIT - see LICENSE file
+
+## Git Workflow
+
+- Commit messages in English
+- Format: `<type>: <subject>` (e.g., `feat: add new environment base class`)
+- Types: feat, fix, docs, refactor, test, chore
+
+## License
+
+MIT - see LICENSE file

package/README.md

@@ -25,14 +25,14 @@
 
 ```bash
 # Install
-npm install lsji
+npm install @game_ryo/lsji
 
 # Set your API key (Gemini, OpenAI, or Anthropic)
 export GEMINI_API_KEY="your-gemini-key"
 # or: export OPENAI_API_KEY="your-openai-key"
 
 # Start the runtime server with web UI
-npx lsji serve
+npx @game_ryo/npx @game_ryo/lsji serve
 
 # Open http://localhost:3456 — create runs, watch thought logs, approve actions
 ```
@@ -41,25 +41,25 @@ npx lsji serve
 
 ```bash
 # Runtime server with control panel
-lsji serve --port 3456              # Start server + UI
-lsji serve --no-ui                  # Headless mode
+npx @game_ryo/lsji serve --port 3456              # Start server + UI
+npx @game_ryo/lsji serve --no-ui                  # Headless mode
 
 # Agent operations
-lsji agent run --task "Write a report on AI trends" --provider gemini --model gemini-1.5-flash
-lsji agent run-durable --task "Analyze codebase" --workflow-id my-analysis
+npx @game_ryo/lsji agent run --task "Write a report on AI trends" --provider gemini --model gemini-1.5-flash
+npx @game_ryo/lsji agent run-durable --task "Analyze codebase" --workflow-id my-analysis
 
 # Budget & approvals
-lsji budget status --budgetId my-project
-lsji hitl list                       # Pending approvals
-lsji hitl approve --id <id> --reason "Approved"
+npx @game_ryo/lsji budget status --budgetId my-project
+npx @game_ryo/lsji hitl list                       # Pending approvals
+npx @game_ryo/lsji hitl approve --id <id> --reason "Approved"
 
 # Plugins
-lsji plugin list
-lsji plugin create --name my-tools   # Generate template
+npx @game_ryo/lsji plugin list
+npx @game_ryo/lsji plugin create --name my-tools   # Generate template
 
 # RL (legacy)
-lsji train --episodes 500
-lsji play --hand 0
+npx @game_ryo/lsji train --episodes 500
+npx @game_ryo/lsji play --hand 0
 ```
 
 ## Programmatic Usage
@@ -85,7 +85,7 @@ const server = await startServer({ port: 3456 });
 
 ## Web Control Panel
 
-When you run `lsji serve`, you get a real-time dashboard at **http://localhost:3456**:
+When you run `npx @game_ryo/lsji serve`, you get a real-time dashboard at **http://localhost:3456**:
 
 | Panel | Features |
 |-------|----------|
@@ -117,7 +117,7 @@ export default {
 ```
 
 ```bash
-lsji plugin list  # Shows: my-tools (1 tools)
+npx @game_ryo/lsji plugin list  # Shows: my-tools (1 tools)
 ```
 
 ## Architecture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@game_ryo/lsji",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A general-purpose reinforcement learning agent framework (Node.js) with LLM agent capabilities",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
     "vitest": "^2.0.0"
   },
   "dependencies": {
+    "better-sqlite3": "^13.0.3",
     "cors": "^2.8.5",
     "express": "^4.19.2",
     "openai": "^7.8.0",
@@ -32,4 +33,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/cli.js

@@ -215,6 +215,7 @@ export async function main() {
             
             console.log(`Running agent on task: ${task}`);
             
+            const storageConfig = { type: storageType, options: { path: dbPath } };
             const agent = await createLLMAgent({
               llm: {
                 provider: options.provider || 'openai',
@@ -234,6 +235,7 @@ export async function main() {
                 semantic: options.semantic === 'true',
                 episodic: options.episodic !== 'false',
               },
+              storage: storageConfig,
             });
             
             const result = await agent.run(task, {
@@ -257,6 +259,7 @@ export async function main() {
             
             console.log(`Running durable agent on task: ${task}`);
             
+            const storageConfig = { type: storageType, options: { path: dbPath } };
             const agent = await createLLMAgent({
               llm: {
                 provider: options.provider || 'openai',
@@ -266,6 +269,7 @@ export async function main() {
               execution: {
                 checkpointInterval: parseInt(options.checkpointInterval) || 3,
               },
+              storage: storageConfig,
             });
             
             const result = await agent.runDurable(task, {
@@ -280,13 +284,16 @@ export async function main() {
           }
           
           case 'status': {
-            const agent = await createLLMAgent({
-              llm: { provider: 'openai', model: 'gpt-4o-mini' },
+            const storageConfig = { type: storageType, options: { path: dbPath } };
+            // Create agent without initializing LLM for status check
+            const { LLMAgent } = await import('./llm/llm-agent.js');
+            const agent = new LLMAgent({
+              llm: { provider: 'local', model: 'test', baseUrl: 'http://localhost:11434/v1' },
+              storage: storageConfig,
             });
-            
+            // Don't initialize - just get status
             const status = agent.getStatus();
             output(status, jsonOutput);
-            await agent.shutdown();
             break;
           }
           

package/src/execution/budget/index.js

@@ -53,6 +53,22 @@ export function createBudgetController(config = {}) {
       };
     },
     
+    /**
+     * Record cost/usage after operation (alias for recordUsage)
+     * Supports both recordCost(budgetId, usage) and recordCost({ budgetId, ...usage })
+     */
+    recordCost(budgetId, usage) {
+      // Handle both calling conventions:
+      // 1. recordCost(budgetId, usageObj)
+      // 2. recordCost({ budgetId, ...usageObj })
+      if (usage === undefined && budgetId && typeof budgetId === 'object') {
+        // Called as recordCost({ budgetId, ...usage })
+        const obj = budgetId;
+        return this.recordUsage(obj.budgetId, obj);
+      }
+      return this.recordUsage(budgetId, usage);
+    },
+    
     /**
      * Reset run budget
      */

package/src/execution/hitl/approval-gate.js

@@ -199,7 +199,9 @@ export class ApprovalGate {
  * Create approval gate from config
  */
 export async function createApprovalGate(config = {}) {
-  const store = await createApprovalStore(config.store || {});
+  // Support both config.store and config.storage for storage configuration
+  const storageConfig = config.storage || config.store || { type: 'sqlite', options: {} };
+  const store = await createApprovalStore(storageConfig);
   const notifier = new Notifier(config.notifier || {});
   
   return new ApprovalGate({

package/src/execution/idempotency.js

@@ -323,9 +323,11 @@ export class IdempotencyStore {
  * Create idempotency store from config
  */
 export async function createIdempotencyStore(config = {}) {
+  // Support both config.storage and config.type/config.options for storage configuration
+  const storageConfig = config.storage || { type: config.type || 'sqlite', options: config.options || {} };
   const storage = await createStorage(
-    config.type || 'sqlite',
-    config.options || {}
+    storageConfig.type || 'sqlite',
+    storageConfig.options || {}
   );
   const store = new IdempotencyStore(storage, { ttl: config.ttl });
   await store.initialize();

package/src/index.js

@@ -96,4 +96,4 @@ export {
 } from './llm/plugins/index.js';
 
 // Version
-export const VERSION = '0.3.0';
+export const VERSION = '1.2.2';

package/src/llm/llm-agent.js

@@ -14,7 +14,7 @@ import { createPromptManager } from './prompt-manager.js';
 import { createExecutionEngine } from '../execution/engine.js';
 import { createApprovalGate } from '../execution/hitl/approval-gate.js';
 import { createBudgetController } from '../execution/budget/index.js';
-import { IdempotencyStore } from '../execution/idempotency.js';
+import { createIdempotencyStore } from '../execution/idempotency.js';
 import { v4 as uuidv4 } from 'uuid';
 
 /**
@@ -27,6 +27,8 @@ import { v4 as uuidv4 } from 'uuid';
  * @property {Object} [hitl] - HITL approval config
  * @property {Object} [budget] - Budget control config
  * @property {Object} [idempotency] - Idempotency config
+ * @property {Object} [prompts] - Prompt manager config
+ * @property {string} [sessionId] - Session ID for conversation memory
  */
 
 /**
@@ -61,6 +63,9 @@ export class LLMAgent {
       throw new Error(`LLM validation failed: ${valid.error}`);
     }
     
+    // Get storage config
+    const storageConfig = this.config.storage || { type: 'sqlite', options: {} };
+    
     // Initialize tool registry
     this.tools = createToolRegistry({
       idempotencyStore: this.idempotency,
@@ -69,24 +74,39 @@ export class LLMAgent {
     
     // Initialize memory systems
     if (this.config.memory?.conversation !== false) {
-      this.memory.conversation = await createConversationMemory(this.config.memory?.conversation);
+      this.memory.conversation = await createConversationMemory({
+        ...this.config.memory?.conversation,
+        storage: storageConfig
+      });
       await this.memory.conversation.startSession(this.config.sessionId);
     }
     
     if (this.config.memory?.semantic) {
-      this.memory.semantic = await createSemanticMemory(this.config.memory.semantic);
+      this.memory.semantic = await createSemanticMemory({
+        ...this.config.memory.semantic,
+        storage: storageConfig
+      });
     }
     
     if (this.config.memory?.episodic) {
-      this.memory.episodic = await createEpisodicMemory(this.config.memory.episodic);
+      this.memory.episodic = await createEpisodicMemory({
+        ...this.config.memory.episodic,
+        storage: storageConfig
+      });
     }
     
     // Initialize execution engine
-    this.execution = await createExecutionEngine(this.config.execution);
+    this.execution = await createExecutionEngine({
+      ...this.config.execution,
+      storage: storageConfig
+    });
     
     // Initialize HITL
     if (this.config.hitl?.enabled !== false) {
-      this.hitl = await createApprovalGate(this.config.hitl);
+      this.hitl = await createApprovalGate({
+        ...this.config.hitl,
+        store: storageConfig
+      });
       // Update tool registry with HITL
       this.tools.approvalGate = this.hitl;
     }
@@ -95,7 +115,10 @@ export class LLMAgent {
     this.budget = createBudgetController(this.config.budget);
     
     // Initialize idempotency
-    this.idempotency = await IdempotencyStore.create(this.config.idempotency);
+    this.idempotency = await createIdempotencyStore({
+      ...this.config.idempotency,
+      ...storageConfig
+    });
     this.tools.idempotencyStore = this.idempotency;
     
     // Initialize prompt manager

package/src/llm/memory/conversation.js

@@ -37,8 +37,9 @@ export class ConversationMemory {
   async initialize() {
     if (this.initialized) return;
     
-    if (this.storage.db) {
-      await this.storage.db.exec(`
+    // Use the new storage interface method
+    if (typeof this.storage.exec === 'function') {
+      await this.storage.exec(`
         CREATE TABLE IF NOT EXISTS conversations (
           id TEXT PRIMARY KEY,
           session_id TEXT NOT NULL,
@@ -52,11 +53,11 @@ export class ConversationMemory {
         )
       `);
       
-      await this.storage.db.exec(`
+      await this.storage.exec(`
         CREATE INDEX IF NOT EXISTS idx_conversations_session ON conversations(session_id)
       `);
       
-      await this.storage.db.exec(`
+      await this.storage.exec(`
         CREATE INDEX IF NOT EXISTS idx_conversations_created ON conversations(created_at)
       `);
     }
@@ -86,8 +87,8 @@ export class ConversationMemory {
   async loadSession(sessionId) {
     await this.initialize();
     
-    if (this.storage.db) {
-      const rows = await this.storage.db.all(
+    if (typeof this.storage.all === 'function') {
+      const rows = await this.storage.all(
         'SELECT * FROM conversations WHERE session_id = ? ORDER BY created_at ASC',
         [sessionId]
       );
@@ -123,12 +124,12 @@ export class ConversationMemory {
     this.messages.push(msg);
     
     // Persist to storage
-    if (this.storage.db && this.sessionId) {
+    if (typeof this.storage.run === 'function' && this.sessionId) {
       const tokens = this.tokenCounter 
         ? await this.tokenCounter.estimateTokens([msg], { provider: 'openai', model: 'gpt-4o-mini' })
         : 0;
       
-      await this.storage.db.run(
+      await this.storage.run(
         `INSERT INTO conversations (id, session_id, role, content, name, tool_call_id, tool_calls, tokens, created_at)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         [
@@ -229,8 +230,8 @@ export class ConversationMemory {
   async clear() {
     this.messages = [];
     
-    if (this.storage.db && this.sessionId) {
-      await this.storage.db.run(
+    if (typeof this.storage.run === 'function' && this.sessionId) {
+      await this.storage.run(
         'DELETE FROM conversations WHERE session_id = ?',
         [this.sessionId]
       );