@game_ryo/lsji 0.1.0

package/docs/docs/examples/custom-storage.md

@@ -0,0 +1,251 @@
+---
+title: Custom Storage Backend
+description: Implement your own storage backend
+---
+
+# Custom Storage Backend
+
+Create a custom storage backend by extending the abstract `Storage` class.
+
+## Interface to Implement
+
+```typescript
+import { Storage } from 'lsji';
+
+abstract class Storage {
+  abstract initialize(): Promise<void>;
+  abstract close(): Promise<void>;
+  abstract getSetting(key: string): Promise<{key: string, value: string} | null>;
+  abstract setSetting(key: string, value: string | number): Promise<void>;
+  abstract getQTable(): Promise<Array<{state: string, action: number, q_value: number}>>;
+  abstract updateQ(state: string, action: number, qValue: number): Promise<void>;
+  abstract addBattle(record: BattleRecord): Promise<void>;
+  abstract getTodayBattleCount(): Promise<number>;
+  abstract getPerformanceStats(): Promise<Array<{mode: string, total: number, win_rate: number}>>;
+}
+
+interface BattleRecord {
+  mode: 'train' | 'test';
+  handA: number;
+  handB: number;
+  reward: number;
+  createdAt: string;
+}
+```
+
+## Example: Redis Storage
+
+```typescript
+import { Storage } from 'lsji';
+import Redis from 'ioredis';
+
+class RedisStorage extends Storage {
+  constructor(redisUrl = 'redis://localhost:6379') {
+    super();
+    this.redis = new Redis(redisUrl);
+    this.keyPrefix = 'lsji:';
+  }
+
+  async initialize() {
+    // Set default settings
+    await this.setSetting('is_active', 1);
+  }
+
+  async close() {
+    await this.redis.quit();
+  }
+
+  async getSetting(key) {
+    const value = await this.redis.get(this.keyPrefix + 'setting:' + key);
+    return value ? { key, value } : null;
+  }
+
+  async setSetting(key, value) {
+    await this.redis.set(this.keyPrefix + 'setting:' + key, String(value));
+  }
+
+  async getQTable() {
+    const keys = await this.redis.keys(this.keyPrefix + 'q:*');
+    const results = [];
+    
+    for (const key of keys) {
+      const value = await this.redis.get(key);
+      const parts = key.replace(this.keyPrefix + 'q:', '').split(':');
+      results.push({
+        state: parts[0],
+        action: parseInt(parts[1], 10),
+        q_value: parseFloat(value)
+      });
+    }
+    
+    return results.sort((a, b) => a.state.localeCompare(b.state) || a.action - b.action);
+  }
+
+  async updateQ(state, action, qValue) {
+    await this.redis.set(
+      this.keyPrefix + `q:${state}:${action}`, 
+      qValue.toString()
+    );
+  }
+
+  async addBattle(record) {
+    const battleKey = this.keyPrefix + `battle:${Date.now()}:${Math.random()}`;
+    await this.redis.hset(battleKey, {
+      mode: record.mode,
+      hand_a: record.handA.toString(),
+      hand_b: record.handB.toString(),
+      reward: record.reward.toString(),
+      created_at: record.createdAt
+    });
+    
+    // Add to sorted set for date queries
+    await this.redis.zadd(
+      this.keyPrefix + 'battles:by_date',
+      new Date(record.createdAt).getTime(),
+      battleKey
+    );
+  }
+
+  async getTodayBattleCount() {
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    const tomorrow = new Date(today);
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    
+    return this.redis.zcount(
+      this.keyPrefix + 'battles:by_date',
+      today.getTime(),
+      tomorrow.getTime()
+    );
+  }
+
+  async getPerformanceStats() {
+    const keys = await this.redis.zrange(this.keyPrefix + 'battles:by_date', 0, -1);
+    const stats = new Map();
+    
+    for (const key of keys) {
+      const battle = await this.redis.hgetall(key);
+      const mode = battle.mode;
+      
+      if (!stats.has(mode)) {
+        stats.set(mode, { total: 0, wins: 0 });
+      }
+      
+      const stat = stats.get(mode);
+      stat.total++;
+      if (parseInt(battle.reward) > 0) stat.wins++;
+    }
+    
+    return Array.from(stats.entries()).map(([mode, stat]) => ({
+      mode,
+      total: stat.total,
+      win_rate: stat.total > 0 ? Math.round((stat.wins / stat.total) * 1000) / 10 : 0
+    }));
+  }
+}
+```
+
+## Register Custom Storage
+
+Add to `createStorage` factory (or use directly):
+
+```typescript
+import { createStorage } from 'lsji';
+
+// Option 1: Use directly
+const storage = new RedisStorage('redis://localhost:6379');
+await storage.initialize();
+
+// Option 2: Extend createStorage (modify src/storage/index.js)
+import { RedisStorage } from './redis-storage';
+
+// In your code:
+const storage = new RedisStorage();
+await storage.initialize();
+```
+
+## Example: PostgreSQL Storage
+
+```typescript
+import { Pool } from 'pg';
+
+class PostgresStorage extends Storage {
+  constructor(connectionString) {
+    super();
+    this.pool = new Pool({ connectionString });
+  }
+
+  async initialize() {
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS settings (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS battle_history (
+        id SERIAL PRIMARY KEY,
+        mode TEXT NOT NULL,
+        hand_a INTEGER NOT NULL,
+        hand_b INTEGER NOT NULL,
+        reward INTEGER NOT NULL,
+        created_at TIMESTAMP NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS q_table (
+        state TEXT NOT NULL,
+        action INTEGER NOT NULL,
+        q_value REAL NOT NULL DEFAULT 0,
+        PRIMARY KEY (state, action)
+      );
+    `);
+    await this.setSetting('is_active', 1);
+  }
+
+  async close() {
+    await this.pool.end();
+  }
+
+  async getSetting(key) {
+    const res = await this.pool.query('SELECT key, value FROM settings WHERE key = $1', [key]);
+    return res.rows[0] || null;
+  }
+
+  async setSetting(key, value) {
+    await this.pool.query(
+      `INSERT INTO settings (key, value) VALUES ($1, $2) 
+       ON CONFLICT (key) DO UPDATE SET value = $2`,
+      [key, String(value)]
+    );
+  }
+
+  // ... implement other methods similarly
+}
+```
+
+## Testing Custom Storage
+
+```typescript
+import { MemoryStorage } from 'lsji';
+
+// Use MemoryStorage as reference implementation for testing
+async function testStorageImplementation(StorageClass) {
+  const storage = new StorageClass();
+  await storage.initialize();
+  
+  // Test settings
+  await storage.setSetting('test', 'value');
+  const setting = await storage.getSetting('test');
+  assert(setting.value === 'value');
+  
+  // Test Q-table
+  await storage.updateQ('state1', 0, 0.5);
+  const qTable = await storage.getQTable();
+  assert(qTable[0].q_value === 0.5);
+  
+  // Test battles
+  await storage.addBattle({ mode: 'train', handA: 0, handB: 1, reward: 1, createdAt: new Date().toISOString() });
+  const count = await storage.getTodayBattleCount();
+  assert(count === 1);
+  
+  await storage.close();
+  console.log('All tests passed!');
+}
+```

package/docs/docs/getting-started.md

@@ -0,0 +1,91 @@
+---
+title: Getting Started
+description: Install LSJI and run your first RL agent
+---
+
+# Getting Started
+
+## Prerequisites
+
+- **Node.js 22+** (required for built-in `node:sqlite`)
+- npm, yarn, or pnpm
+
+## Installation
+
+```bash
+# Install as a library
+npm install lsji
+
+# Or use CLI directly with npx
+npx lsji --help
+```
+
+## Quick Start
+
+### 1. Train an Agent
+
+```bash
+# Train with default settings (200 episodes, random pattern)
+npx lsji train --episodes 500
+
+# Train against specific opponent
+npx lsji train --episodes 1000 --opponent counter
+```
+
+### 2. Play Against the Agent
+
+```bash
+# Play Rock (0)
+npx lsji play --hand 0
+
+# Play Paper (2)
+npx lsji play --hand 2
+```
+
+### 3. Check Status
+
+```bash
+npx lsji status --json
+```
+
+## Using as a Library
+
+```javascript
+import { Agent, QLearning, createStorage, RockPaperScissorsEnv } from 'lsji';
+
+async function main() {
+  // Create storage (SQLite recommended for persistence)
+  const storage = await createStorage('sqlite', { path: './my-agent.db' });
+
+  // Create Q-Learning engine
+  const qlearning = new QLearning({
+    alpha: 0.1,    // learning rate
+    gamma: 0.9,    // discount factor
+    epsilon: 0.1,  // exploration rate
+    storage
+  });
+
+  // Create environment
+  const env = new RockPaperScissorsEnv({ opponent: 'random' });
+
+  // Create agent
+  const agent = new Agent({ qlearning, storage, env });
+
+  // Train
+  await agent.train({ episodes: 1000 });
+
+  // Play
+  const result = await agent.play(0); // 0 = Rock
+  console.log(result);
+
+  await storage.close();
+}
+
+main().catch(console.error);
+```
+
+## Next Steps
+
+- Read [Core Concepts](/docs/core-concepts) to understand the architecture
+- Explore [API Reference](/docs/api/agent) for detailed class documentation
+- Try [Examples](/docs/examples/custom-environment) for custom environments

package/docs/docusaurus.config.ts

@@ -0,0 +1,149 @@
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'LSJI',
+  tagline: 'Learning System for JavaScript Intelligence',
+  favicon: 'img/favicon.ico',
+
+  future: {
+    v4: true,
+  },
+
+  url: 'https://lsji.ryopc.org',
+  baseUrl: '/',
+
+  organizationName: 'ryotagtagtag-wq',
+  projectName: 'LSJI',
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          editUrl: 'https://github.com/ryotagtagtag-wq/LSJI/tree/main/docs/',
+        },
+        blog: {
+          showReadingTime: true,
+          feedOptions: {
+            type: ['rss', 'atom'],
+            xslt: true,
+          },
+          editUrl: 'https://github.com/ryotagtagtag-wq/LSJI/tree/main/docs/',
+          onInlineTags: 'warn',
+          onInlineAuthors: 'warn',
+          onUntruncatedBlogPosts: 'warn',
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    image: 'img/lsji-social-card.jpg',
+    colorMode: {
+      respectPrefersColorScheme: true,
+    },
+    navbar: {
+      title: 'LSJI',
+      logo: {
+        alt: 'LSJI Logo',
+        src: 'img/logo.png',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'tutorialSidebar',
+          position: 'left',
+          label: 'Docs',
+        },
+        {to: '/blog', label: 'Blog', position: 'left'},
+        {
+          href: 'https://github.com/ryotagtagtag-wq/LSJI',
+          label: 'GitHub',
+          position: 'right',
+        },
+        {
+          href: 'https://www.npmjs.com/package/lsji',
+          label: 'npm',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Documentation',
+          items: [
+            {
+              label: 'Getting Started',
+              to: '/docs/getting-started',
+            },
+            {
+              label: 'Core Concepts',
+              to: '/docs/core-concepts',
+            },
+            {
+              label: 'API Reference',
+              to: '/docs/api/agent',
+            },
+            {
+              label: 'CLI Reference',
+              to: '/docs/cli',
+            },
+          ],
+        },
+        {
+          title: 'Community',
+          items: [
+            {
+              label: 'GitHub Issues',
+              href: 'https://github.com/ryotagtagtag-wq/LSJI/issues',
+            },
+            {
+              label: 'GitHub Discussions',
+              href: 'https://github.com/ryotagtagtag-wq/LSJI/discussions',
+            },
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'Blog',
+              to: '/blog',
+            },
+            {
+              label: 'GitHub',
+              href: 'https://github.com/ryotagtagtag-wq/LSJI',
+            },
+            {
+              label: 'npm',
+              href: 'https://www.npmjs.com/package/lsji',
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} LSJI Contributors. Built with Docusaurus.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;