@game_ryo/lsji 0.1.0 → 0.3.0

package/docs/docs/cli.md

@@ -1,210 +0,0 @@
----
-title: CLI Reference
-description: Command-line interface for training and playing
----
-
-# CLI Reference
-
-LSJI includes a command-line interface for training and playing without writing code.
-
-## Installation
-
-```bash
-# Global install
-npm install -g lsji
-
-# Or use npx
-npx lsji --help
-```
-
-## Commands
-
-### `lsji train`
-
-Train the agent.
-
-```bash
-lsji train [options]
-```
-
-**Options:**
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--episodes <n>` | Number of training episodes | 200 |
-| `--pattern <0-3>` | Training pattern | 0 |
-| `--batch-size <n>` | Database batch size | 200 |
-| `--opponent <type>` | Opponent strategy | random |
-| `--storage <type>` | Storage backend | sqlite |
-| `--db-path <path>` | Database file path | ./lsji.db |
-| `--alpha <n>` | Learning rate | 0.1 |
-| `--gamma <n>` | Discount factor | 0.9 |
-| `--epsilon <n>` | Exploration rate | 0.1 |
-| `--json` | Output as JSON | false |
-
-**Training Patterns:**
-- `0` — Random actions
-- `1` — Always Rock
-- `2` — Counter previous action
-- `3` — Sequential (0,1,2,0,1,2...)
-
-**Opponent Strategies:**
-- `random` — Random actions
-- `always_rock` — Always plays Rock
-- `counter` — Counters agent's previous action
-- `sequential` — Cycles through actions
-
-**Examples:**
-```bash
-# Default training
-lsji train --episodes 500
-
-# Train against always-rock opponent
-lsji train --episodes 100 --pattern 1 --opponent always_rock
-
-# Train with custom hyperparameters
-lsji train --episodes 1000 --alpha 0.05 --gamma 0.95 --epsilon 0.2
-
-# Use memory storage (ephemeral)
-lsji train --episodes 100 --storage memory
-```
-
-### `lsji play`
-
-Play a single game against the agent.
-
-```bash
-lsji play --hand <0|1|2> [options]
-```
-
-**Options:**
-
-| Option | Description |
-|--------|-------------|
-| `--hand <0\|1\|2>` | Your hand: 0=Rock, 1=Scissors, 2=Paper |
-| `--opponent <type>` | Opponent strategy |
-| `--storage <type>` | Storage backend |
-| `--db-path <path>` | Database file path |
-| `--json` | Output as JSON |
-
-**Examples:**
-```bash
-lsji play --hand 0        # Play Rock
-lsji play --hand 1        # Play Scissors
-lsji play --hand 2 --json # Play Paper, JSON output
-```
-
-### `lsji status`
-
-Show system status and statistics.
-
-```bash
-lsji status [options]
-```
-
-**Options:**
-
-| Option | Description |
-|--------|-------------|
-| `--storage <type>` | Storage backend |
-| `--db-path <path>` | Database file path |
-| `--json` | Output as JSON |
-
-**Example:**
-```bash
-lsji status --json
-```
-
-Output:
-```json
-{
-  "status": "running",
-  "todayTotal": 42,
-  "limit": 90000,
-  "performance": [
-    { "mode": "train", "total": 1000, "win_rate": 65.5 },
-    { "mode": "test", "total": 50, "win_rate": 72.0 }
-  ],
-  "aiBrain": [
-    { "state": "0", "action": 0, "q_value": 0.45 },
-    { "state": "0", "action": 1, "q_value": 0.12 }
-  ]
-}
-```
-
-### `lsji start`
-
-Enable training and play.
-
-```bash
-lsji start [options]
-```
-
-### `lsji stop`
-
-Disable training and play (system paused).
-
-```bash
-lsji stop [options]
-```
-
-### `lsji help`
-
-Show help message.
-
-```bash
-lsji help
-lsji --help
-lsji -h
-```
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `LSJI_STORAGE` | Default storage backend | sqlite |
-| `LSJI_DB_PATH` | Default database path | ./lsji.db |
-
-## Examples
-
-### Full Training Session
-
-```bash
-# Start fresh
-rm -f lsji.db
-
-# Train against random opponent
-lsji train --episodes 500 --opponent random
-
-# Train against counter opponent
-lsji train --episodes 500 --opponent counter
-
-# Check progress
-lsji status --json
-
-# Play a few games
-lsji play --hand 0
-lsji play --hand 1
-lsji play --hand 2
-```
-
-### Using Memory Storage (CI/Testing)
-
-```bash
-lsji train --episodes 100 --storage memory
-lsji play --hand 0 --storage memory
-lsji status --storage memory
-```
-
-### Custom Hyperparameters
-
-```bash
-lsji train \
-  --episodes 2000 \
-  --alpha 0.05 \
-  --gamma 0.95 \
-  --epsilon 0.2 \
-  --opponent random \
-  --storage sqlite \
-  --db-path ./custom.db
-```

package/docs/docs/contributing.md

@@ -1,162 +0,0 @@
----
-title: Contributing
-description: How to contribute to LSJI
----
-
-# Contributing
-
-Thank you for your interest in contributing to LSJI!
-
-## Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/ryotagtagtag-wq/LSJI.git
-cd LSJI
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Build documentation
-cd docs && npm run build
-```
-
-## Project Structure
-
-```
-LSJI/
-├── src/                 # Core library
-│   ├── core/           # QLearning, Agent, Env
-│   ├── storage/        # Storage backends
-│   ├── envs/           # Built-in environments
-│   ├── cli.ts          # CLI
-│   └── index.ts        # Public exports
-├── test/               # Vitest tests
-├── docs/               # Docusaurus documentation
-└── bin/                # CLI entry point
-```
-
-## Making Changes
-
-### 1. Create a Branch
-
-```bash
-git checkout -b feature/my-feature
-```
-
-### 2. Make Changes
-
-Follow the existing code style:
-- TypeScript with JSDoc comments
-- ESM imports/exports
-- No external dependencies in core
-
-### 3. Run Tests
-
-```bash
-npm test
-```
-
-### 4. Update Documentation
-
-If you add new features, update relevant docs in `docs/docs/`.
-
-### 5. Commit
-
-```bash
-git add .
-git commit -m "feat: add my feature"
-```
-
-**Commit Message Format:**
-- `feat:` — New feature
-- `fix:` — Bug fix
-- `docs:` — Documentation
-- `refactor:` — Code refactoring
-- `test:` — Tests
-- `chore:` — Maintenance
-
-### 6. Push and Create PR
-
-```bash
-git push origin feature/my-feature
-```
-
-## Adding a New Environment
-
-1. Create `src/envs/my-env.ts` extending `Env`
-2. Implement all abstract methods
-3. Export from `src/index.ts`
-4. Add documentation in `docs/docs/api/environments.md`
-5. Add example in `docs/docs/examples/`
-
-## Adding a New Storage Backend
-
-1. Create `src/storage/my-backend.ts` extending `Storage`
-2. Implement all abstract methods
-3. Add to `createStorage` factory in `src/storage/index.ts`
-3. Export from `src/index.ts`
-4. Add tests in `test/storage/`
-
-## Modifying Learning Algorithm
-
-1. Extend `QLearning` class or create new class in `src/core/`
-2. Maintain compatibility with `Agent` interface
-3. Add tests for new algorithm
-4. Document in `docs/docs/api/`
-
-## Code Style
-
-- **TypeScript** with strict mode
-- **ESM** modules (`import`/`export`)
-- **JSDoc** for all public APIs
-- **No `any`** unless absolutely necessary
-- **Async/await** for async operations
-
-## Testing Guidelines
-
-- Use `MemoryStorage` for unit tests
-- Test both success and error cases
-- Test edge cases (empty Q-table, terminal states)
-- Keep tests fast and isolated
-
-```typescript
-// Example test structure
-import { describe, it, expect, beforeEach } from 'vitest';
-import { MyFeature } from '../src/core/my-feature';
-import { MemoryStorage } from '../src/storage/memory';
-
-describe('MyFeature', () => {
-  let storage;
-  let feature;
-
-  beforeEach(async () => {
-    storage = new MemoryStorage();
-    await storage.initialize();
-    feature = new MyFeature({ storage });
-  });
-
-  it('should do something', async () => {
-    const result = await feature.doSomething();
-    expect(result).toBe(expected);
-  });
-});
-```
-
-## Documentation
-
-- Update relevant `.md` files in `docs/docs/`
-- Add JSDoc comments for new public APIs
-- Include code examples
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.
-
-## Questions?
-
-- Open a [GitHub Issue](https://github.com/ryotagtagtag-wq/LSJI/issues)
-- Start a [Discussion](https://github.com/ryotagtagtag-wq/LSJI/discussions)

package/docs/docs/core-concepts.md

@@ -1,152 +0,0 @@
----
-title: Core Concepts
-description: Understand the core architecture of LSJI
----
-
-# Core Concepts
-
-LSJI is built around four core abstractions that work together to create a flexible reinforcement learning framework.
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        Agent                                 │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
-│  │ QLearning   │  │  Storage    │  │      Env            │  │
-│  │ (Engine)    │◄─┤ (Backend)   │  │ (Environment)       │  │
-│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 1. Environment (`Env`)
-
-The `Env` interface defines the problem domain. Any RL environment must implement:
-
-```typescript
-abstract class Env {
-  getState(): string;                    // Current state representation
-  step(action: number): Promise<StepResult>;  // Execute action
-  actionSize(): number;                  // Number of possible actions
-  reset(): Promise<string>;              // Reset to initial state
-}
-```
-
-**StepResult** contains:
-- `state` — New state after action
-- `reward` — Reward received (-1, 0, 1)
-- `done` — Whether episode ended
-- `info` — Additional diagnostic info
-
-### 2. Q-Learning Engine (`QLearning`)
-
-Tabular Q-Learning with Temporal Difference (TD) updates:
-
-```typescript
-class QLearning {
-  constructor({ alpha, gamma, epsilon, storage });
-  
-  // Epsilon-greedy action selection
-  async act(state: string, actionSize: number): Promise<number>;
-  
-  // Full TD update: Q(s,a) ← Q(s,a) + α[r + γ·max Q(s',a') - Q(s,a)]
-  async learn(state, action, reward, nextState, nextActionSize);
-  
-  // Simplified update (terminal states): Q(s,a) ← Q(s,a) + α[r - Q(s,a)]
-  async learnSimple(state, action, reward);
-  
-  // Get all Q-values for inspection
-  async getFullQTable(): Promise<QTableRecord[]>;
-}
-```
-
-**Hyperparameters:**
-- `alpha` (0.1) — Learning rate
-- `gamma` (0.9) — Discount factor  
-- `epsilon` (0.1) — Exploration rate
-
-### 3. Storage Backend (`Storage`)
-
-Pluggable persistence layer with three implementations:
-
-| Backend | Package | Use Case |
-|---------|---------|----------|
-| `SqliteStorage` | `node:sqlite` (built-in) | **Recommended** — Zero dependencies |
-| `BetterSqliteStorage` | `better-sqlite3` | High-performance synchronous access |
-| `MemoryStorage` | Built-in | Testing, CI, ephemeral workloads |
-
-All implement the same interface:
-```typescript
-interface Storage {
-  initialize(): Promise<void>;
-  close(): Promise<void>;
-  getSetting(key): Promise<Setting>;
-  setSetting(key, value): Promise<void>;
-  getQTable(): Promise<QTableRecord[]>;
-  updateQ(state, action, qValue): Promise<void>;
-  addBattle(record): Promise<void>;
-  getTodayBattleCount(): Promise<number>;
-  getPerformanceStats(): Promise<PerformanceStat[]>;
-}
-```
-
-### 4. Agent (`Agent`)
-
-High-level orchestration combining all components:
-
-```typescript
-class Agent {
-  constructor({ qlearning, storage, env });
-  
-  async train({ episodes, actionSelector, batchSize });
-  async play(options?): Promise<PlayResult>;
-  async status(): Promise<StatusInfo>;
-  async start(): Promise<{status, message}>;
-  async stop(): Promise<{status, message}>;
-  setEnvironment(env): void;
-}
-```
-
-## Data Flow
-
-### Training Loop
-```
-for each episode:
-  1. Get current state from Env
-  2. Select action via QLearning.act() (ε-greedy)
-  3. Execute action in Env → StepResult
-  4. Update Q-table via QLearning.learnSimple()
-  5. Persist battle record to Storage
-  6. Batch DB writes for performance
-```
-
-### Play Loop
-```
-1. Get current state from Env
-2. Select best action via QLearning.act() (ε=0 for exploitation)
-3. Execute action in Env
-4. Update Q-table with result
-5. Record battle to Storage
-6. Return result
-```
-
-## Reward System (RPS Example)
-
-| Outcome | Judge Formula | Reward |
-|---------|---------------|--------|
-| Win     | (ai - user + 3) % 3 = 2 | +1 |
-| Lose    | (ai - user + 3) % 3 = 1 | -1 |
-| Draw    | (ai - user + 3) % 3 = 0 | 0 |
-
-## Training Patterns
-
-Built-in patterns for the RPS environment:
-
-| Pattern | ID | Description |
-|---------|-----|-------------|
-| Random | 0 | Uniform random actions |
-| Always Rock | 1 | Always play action 0 |
-| Counter | 2 | Play counter to previous action |
-| Sequential | 3 | Cycle through 0,1,2,0,1,2... |
-
-Custom patterns can be implemented via `actionSelector` function.