@game_ryo/lsji 0.1.0 → 0.1.1

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

@@ -1,198 +0,0 @@
----
-title: Custom Environment
-description: Build your own RL environment
----
-
-# Custom Environment Example
-
-This guide shows how to create a custom environment by extending the `Env` base class.
-
-## Grid World Environment
-
-A simple 1D grid where the agent learns to move right to reach the goal.
-
-```typescript
-import { Env } from 'lsji';
-
-class GridWorldEnv extends Env {
-  constructor(gridSize = 10) {
-    super();
-    this.gridSize = gridSize;
-    this.position = 0;
-  }
-
-  getState(): string {
-    return String(this.position);
-  }
-
-  async step(action: number): Promise<StepResult> {
-    // Actions: 0 = left, 1 = right
-    if (action === 0) {
-      this.position = Math.max(0, this.position - 1);
-    } else if (action === 1) {
-      this.position = Math.min(this.gridSize - 1, this.position + 1);
-    }
-
-    const done = this.position === this.gridSize - 1;
-    const reward = done ? 1 : -0.01; // Small penalty for each step
-
-    return {
-      state: String(this.position),
-      reward,
-      done,
-      info: { position: this.position }
-    };
-  }
-
-  actionSize(): number {
-    return 2; // Left, Right
-  }
-
-  async reset(): Promise<string> {
-    this.position = 0;
-    return '0';
-  }
-
-  render(): string {
-    const bar = ' '.repeat(this.gridSize);
-    const chars = bar.split('');
-    chars[this.position] = 'A';
-    chars[this.gridSize - 1] = 'G';
-    return `[${chars.join('')}]`;
-  }
-}
-```
-
-## Using the Custom Environment
-
-```typescript
-import { Agent, QLearning, createStorage } from 'lsji';
-import { GridWorldEnv } from './grid-world';
-
-async function main() {
-  const storage = await createStorage('sqlite', { path: './gridworld.db' });
-  
-  const qlearning = new QLearning({
-    alpha: 0.1,
-    gamma: 0.9,
-    epsilon: 0.1,
-    storage
-  });
-
-  const env = new GridWorldEnv(10);
-  const agent = new Agent({ qlearning, storage, env });
-
-  console.log('Training...');
-  await agent.train({ episodes: 5000 });
-
-  console.log('Testing...');
-  await agent.play(); // Single step
-  
-  const status = await agent.status();
-  console.log('Q-table:', status.aiBrain);
-
-  await storage.close();
-}
-
-main().catch(console.error);
-```
-
-## Multi-State Environment
-
-For environments with multiple state variables, use `StateEncoder`:
-
-```typescript
-import { Env, StateEncoder } from 'lsji';
-
-interface GameState {
-  playerHP: number;
-  enemyHP: number;
-  hasPotion: boolean;
-}
-
-class BattleEnv extends Env {
-  state: GameState = { playerHP: 100, enemyHP: 50, hasPotion: true };
-
-  getState(): string {
-    return StateEncoder.encode(this.state);
-  }
-
-  async step(action: number): Promise<StepResult> {
-    // 0 = attack, 1 = heal, 2 = defend
-    let reward = 0;
-    let done = false;
-
-    if (action === 0) { // Attack
-      this.state.enemyHP -= 10;
-      reward = this.state.enemyHP <= 0 ? 10 : -1;
-      done = this.state.enemyHP <= 0;
-    } else if (action === 1) { // Heal
-      if (this.state.hasPotion) {
-        this.state.playerHP = Math.min(100, this.state.playerHP + 30);
-        this.state.hasPotion = false;
-        reward = -1;
-      } else {
-        reward = -5; // No potion penalty
-      }
-    } else if (action === 2) { // Defend
-      reward = -0.5;
-    }
-
-    // Enemy counter-attack
-    if (!done) {
-      this.state.playerHP -= 5;
-      if (this.state.playerHP <= 0) {
-        reward = -10;
-        done = true;
-      }
-    }
-
-    return {
-      state: StateEncoder.encode(this.state),
-      reward,
-      done,
-      info: { ...this.state }
-    };
-  }
-
-  actionSize(): number {
-    return 3;
-  }
-
-  async reset(): Promise<string> {
-    this.state = { playerHP: 100, enemyHP: 50, hasPotion: true };
-    return StateEncoder.encode(this.state);
-  }
-}
-```
-
-## Key Points
-
-1. **State as string** — Use `StateEncoder.encode()` for complex states
-2. **Reward design** — Shape rewards to guide learning (dense vs sparse)
-3. **Action space** — Keep small for tabular Q-learning
-4. **Episode termination** — Always implement `done` condition
-5. **Reset** — Must restore initial state completely
-
-## Testing Your Environment
-
-```typescript
-async function testEnv() {
-  const env = new GridWorldEnv(5);
-  
-  console.log('Initial:', env.getState());
-  console.log(env.render());
-  
-  for (let i = 0; i < 10; i++) {
-    const result = await env.step(1); // Always move right
-    console.log(`Step ${i}: state=${result.state}, reward=${result.reward}, done=${result.done}`);
-    console.log(env.render());
-    if (result.done) break;
-  }
-  
-  await env.reset();
-  console.log('After reset:', env.getState());
-}
-
-testEnv();
-```

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

@@ -1,251 +0,0 @@
----
-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

@@ -1,91 +0,0 @@
----
-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

@@ -1,149 +0,0 @@
-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;