@game_ryo/lsji 0.1.0

package/docs/blog/authors.yml

@@ -0,0 +1,25 @@
+yangshun:
+  name: Yangshun Tay
+  title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
+  url: https://linkedin.com/in/yangshun
+  image_url: https://github.com/yangshun.png
+  page: true
+  socials:
+    x: yangshunz
+    linkedin: yangshun
+    github: yangshun
+    newsletter: https://www.greatfrontend.com
+
+slorber:
+  name: Sébastien Lorber
+  title: Docusaurus maintainer
+  url: https://sebastienlorber.com
+  image_url: https://github.com/slorber.png
+  page:
+    # customize the url of the author page at /blog/authors/<permalink>
+    permalink: '/all-sebastien-lorber-articles'
+  socials:
+    x: sebastienlorber
+    linkedin: sebastienlorber
+    github: slorber
+    newsletter: https://thisweekinreact.com

package/docs/blog/tags.yml

@@ -0,0 +1,19 @@
+facebook:
+  label: Facebook
+  permalink: /facebook
+  description: Facebook tag description
+
+hello:
+  label: Hello
+  permalink: /hello
+  description: Hello tag description
+
+docusaurus:
+  label: Docusaurus
+  permalink: /docusaurus
+  description: Docusaurus tag description
+
+hola:
+  label: Hola
+  permalink: /hola
+  description: Hola tag description

package/docs/docs/api/agent.md

@@ -0,0 +1,151 @@
+---
+title: Agent API
+description: High-level agent orchestration
+---
+
+# Agent API
+
+The `Agent` class provides high-level orchestration of Q-Learning, Storage, and Environment.
+
+## Import
+
+```typescript
+import { Agent } from 'lsji';
+```
+
+## Constructor
+
+```typescript
+const agent = new Agent({
+  qlearning: QLearning,    // Required: Q-Learning engine
+  storage: Storage,        // Required: Storage backend
+  env: Env                 // Optional: Environment for train/play
+});
+```
+
+## Methods
+
+### `start()`
+Enable the system for training and play.
+
+```typescript
+await agent.start();
+// Returns: { status: 'success', message: 'System STARTED' }
+```
+
+### `stop()`
+Disable the system (pauses training and play).
+
+```typescript
+await agent.stop();
+// Returns: { status: 'success', message: 'System STOPPED' }
+```
+
+### `status()`
+Get current system status and statistics.
+
+```typescript
+const status = await agent.status();
+// Returns:
+{
+  status: 'running' | 'stopped',
+  todayTotal: number,      // Battles today
+  limit: 90000,            // Daily limit
+  performance: [           // Per-mode statistics
+    { mode: 'train', total: 100, win_rate: 65.5 },
+    { mode: 'test', total: 50, win_rate: 72.0 }
+  ],
+  aiBrain: [               // Full Q-table
+    { state: '0', action: 0, q_value: 0.45 },
+    { state: '0', action: 1, q_value: 0.12 },
+    ...
+  ]
+}
+```
+
+### `train(options)`
+Train the agent.
+
+```typescript
+const result = await agent.train({
+  episodes: 200,           // Number of episodes (default: 200)
+  actionSelector: (episode, lastAction) => number,  // Custom pattern (optional)
+  batchSize: 200           // DB batch size (default: 200)
+});
+
+// Returns:
+{
+  episodes: 200,
+  wins: 85,
+  losses: 62,
+  draws: 53
+}
+```
+
+**Built-in Training Patterns:**
+```typescript
+import { TrainingPattern, getTrainingAction } from 'lsji';
+
+// Pattern 0: Random (default)
+await agent.train({ episodes: 500 });
+
+// Pattern 1: Always Rock
+await agent.train({ 
+  episodes: 500, 
+  actionSelector: (ep, last) => getTrainingAction(TrainingPattern.ALWAYS_ROCK, ep, last) 
+});
+
+// Pattern 2: Counter
+await agent.train({ 
+  episodes: 500, 
+  actionSelector: (ep, last) => getTrainingAction(TrainingPattern.COUNTER, ep, last) 
+});
+
+// Pattern 3: Sequential
+await agent.train({ 
+  episodes: 500, 
+  actionSelector: (ep, last) => getTrainingAction(TrainingPattern.SEQUENTIAL, ep, last) 
+});
+```
+
+### `play(options)`
+Play a single step against the agent.
+
+```typescript
+const result = await agent.play({
+  userAction: 0  // Optional: user action for envs that need it
+});
+
+// Returns:
+{
+  action: 1,              // Agent's chosen action
+  reward: 1,              // Reward received
+  done: false,            // Episode ended
+  info: { opponentAction: 0 }  // Environment-specific info
+}
+```
+
+### `setEnvironment(env)`
+Inject or change the environment at runtime.
+
+```typescript
+agent.setEnvironment(new MyCustomEnv());
+```
+
+## Example
+
+```typescript
+import { Agent, QLearning, createStorage, RockPaperScissorsEnv } from 'lsji';
+
+const storage = await createStorage('sqlite', { path: './agent.db' });
+const qlearning = new QLearning({ alpha: 0.1, gamma: 0.9, epsilon: 0.1, storage });
+const env = new RockPaperScissorsEnv({ opponent: 'random' });
+
+const agent = new Agent({ qlearning, storage, env });
+
+await agent.train({ episodes: 1000 });
+const result = await agent.play(0); // Play Rock
+console.log(`AI played: ${result.action}, Result: ${result.reward > 0 ? 'WIN' : result.reward < 0 ? 'LOSE' : 'DRAW'}`);
+
+await storage.close();
+```

package/docs/docs/api/env.md

@@ -0,0 +1,133 @@
+---
+title: Env Interface
+description: Base environment interface for RL problems
+---
+
+# Env Interface
+
+All reinforcement learning environments must extend the abstract `Env` class.
+
+## Import
+
+```typescript
+import { Env } from 'lsji';
+```
+
+## Abstract Methods
+
+### `getState()`
+Return current state as a string key.
+
+```typescript
+getState(): string;
+```
+
+### `step(action)`
+Execute an action and return the result.
+
+```typescript
+async step(action: number): Promise<StepResult>;
+```
+
+**StepResult:**
+```typescript
+interface StepResult {
+  state: string;      // New state
+  reward: number;     // Reward for this step
+  done: boolean;      // Episode ended
+  info?: object;      // Additional info
+}
+```
+
+### `actionSize()`
+Return number of possible actions.
+
+```typescript
+actionSize(): number;
+```
+
+### `reset()`
+Reset environment to initial state.
+
+```typescript
+async reset(): Promise<string>;  // Returns initial state
+```
+
+## Optional Methods
+
+### `render()`
+Human-readable representation for debugging.
+
+```typescript
+render(): string;
+```
+
+## StateEncoder Utility
+
+Helper for encoding/decoding complex states:
+
+```typescript
+import { StateEncoder } from 'lsji';
+
+// Encode object to string
+const key = StateEncoder.encode({ position: 5, inventory: ['sword'] });
+// Returns: '{"position":5,"inventory":["sword"]}'
+
+// Decode string to object
+const state = StateEncoder.decode(key);
+// Returns: { position: 5, inventory: ['sword'] }
+```
+
+## Creating a Custom Environment
+
+```typescript
+import { Env } from 'lsji';
+
+class GridWorldEnv extends Env {
+  constructor() {
+    super();
+    this.position = 0;
+    this.gridSize = 10;
+  }
+
+  getState() {
+    return String(this.position);
+  }
+
+  async step(action) {
+    // Actions: 0=left, 1=right
+    if (action === 0) this.position = Math.max(0, this.position - 1);
+    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;
+
+    return {
+      state: String(this.position),
+      reward,
+      done,
+      info: { position: this.position }
+    };
+  }
+
+  actionSize() {
+    return 2;
+  }
+
+  async reset() {
+    this.position = 0;
+    return '0';
+  }
+
+  render() {
+    return `GridWorld: position ${this.position}/${this.gridSize - 1}`;
+  }
+}
+```
+
+## Best Practices
+
+1. **State as string** — Use simple string keys for Q-table indexing
+2. **Deterministic rewards** — Same state-action should give consistent rewards
+3. **Action space** — Keep action space small for tabular Q-learning
+4. **Reset** — Always implement proper reset for episode boundaries

package/docs/docs/api/environments.md

@@ -0,0 +1,102 @@
+---
+title: Built-in Environments
+description: Pre-built environments for quick start
+---
+
+# Built-in Environments
+
+LSJI includes a Rock-Paper-Scissors environment for demonstration and testing.
+
+## Import
+
+```typescript
+import { 
+  RockPaperScissorsEnv, 
+  TrainingPattern, 
+  getTrainingAction 
+} from 'lsji';
+```
+
+## RockPaperScissorsEnv
+
+Classic Rock-Paper-Scissors game environment.
+
+### Constructor
+
+```typescript
+const env = new RockPaperScissorsEnv({
+  opponent: 'random'  // 'random' | 'always_rock' | 'counter' | 'sequential'
+});
+```
+
+### Opponent Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `'random'` | Uniform random actions (default) |
+| `'always_rock'` | Always plays Rock (0) |
+| `'counter'` | Plays counter to agent's previous action |
+| `'sequential'` | Cycles through Rock→Scissors→Paper |
+
+### Methods
+
+All standard `Env` methods plus:
+
+```typescript
+// Static helpers
+RockPaperScissorsEnv.getHandName(0);     // 'Rock'
+RockPaperScissorsEnv.getHandName(1);     // 'Scissors'
+RockPaperScissorsEnv.getHandName(2);     // 'Paper'
+
+const { judge, reward, outcome } = RockPaperScissorsEnv.calculateOutcome(0, 2);
+// judge: 2, reward: 1, outcome: 'WIN'
+```
+
+### Training Patterns
+
+```typescript
+import { TrainingPattern, getTrainingAction } from 'lsji';
+
+// Pattern IDs
+TrainingPattern.RANDOM;        // 0
+TrainingPattern.ALWAYS_ROCK;   // 1
+TrainingPattern.COUNTER;       // 2
+TrainingPattern.SEQUENTIAL;    // 3
+
+// Get action for pattern
+const action = getTrainingAction(TrainingPattern.COUNTER, episode, lastAction);
+```
+
+### Example
+
+```typescript
+import { 
+  Agent, QLearning, createStorage, 
+  RockPaperScissorsEnv, TrainingPattern, getTrainingAction 
+} from 'lsji';
+
+const storage = await createStorage('sqlite', { path: './rps.db' });
+const qlearning = new QLearning({ alpha: 0.1, gamma: 0.9, epsilon: 0.1, storage });
+
+// Train against counter opponent
+const env = new RockPaperScissorsEnv({ opponent: 'counter' });
+const agent = new Agent({ qlearning, storage, env });
+
+await agent.train({ 
+  episodes: 1000,
+  actionSelector: (ep, last) => getTrainingAction(TrainingPattern.RANDOM, ep, last)
+});
+
+// Play against random opponent
+const playEnv = new RockPaperScissorsEnv({ opponent: 'random' });
+agent.setEnvironment(playEnv);
+
+const result = await agent.play(0); // You play Rock
+console.log(`AI: ${RockPaperScissorsEnv.getHandName(result.action)} | ${result.reward > 0 ? 'WIN' : 'LOSE'}`);
+
+await storage.close();
+```
+
+## Creating Custom Environments
+
+See [Custom Environment Example](/docs/examples/custom-environment) for a complete guide.

package/docs/docs/api/qlearning.md

@@ -0,0 +1,138 @@
+---
+title: QLearning API
+description: Tabular Q-Learning engine with TD updates
+---
+
+# QLearning API
+
+The `QLearning` class implements tabular Q-Learning with epsilon-greedy exploration.
+
+## Import
+
+```typescript
+import { QLearning } from 'lsji';
+```
+
+## Constructor
+
+```typescript
+const qlearning = new QLearning({
+  alpha: 0.1,     // Learning rate [0, 1] (default: 0.1)
+  gamma: 0.9,     // Discount factor [0, 1] (default: 0.9)
+  epsilon: 0.1,   // Exploration rate [0, 1] (default: 0.1)
+  storage: Storage // Required: Storage backend
+});
+```
+
+Values are automatically clamped to [0, 1] range.
+
+## Methods
+
+### `initialize()`
+Load Q-table from storage. Called automatically by other methods.
+
+```typescript
+await qlearning.initialize();
+```
+
+### `getQValue(state, action)`
+Get Q-value for a state-action pair.
+
+```typescript
+const value = qlearning.getQValue('state1', 0);
+// Returns: number (0 if unseen)
+```
+
+### `setQValue(state, action, value)`
+Set Q-value and persist to storage.
+
+```typescript
+await qlearning.setQValue('state1', 0, 0.5);
+```
+
+### `act(state, actionSize)`
+Select action using epsilon-greedy policy.
+
+```typescript
+const action = await qlearning.act('state1', 3);
+// Returns: number (0 to actionSize-1)
+```
+
+**Behavior:**
+- With probability `epsilon`: random action
+- With probability `1-epsilon`: best known action (ties broken randomly)
+
+### `learn(state, action, reward, nextState, nextActionSize)`
+Full TD update: Q(s,a) ← Q(s,a) + α[r + γ·maxₐ' Q(s',a') - Q(s,a)]
+
+```typescript
+const newQ = await qlearning.learn('state1', 0, 1, 'state2', 3);
+// Returns: updated Q-value
+```
+
+### `learnSimple(state, action, reward)`
+Simplified update for terminal states: Q(s,a) ← Q(s,a) + α[r - Q(s,a)]
+
+```typescript
+const newQ = await qlearning.learnSimple('state1', 0, 1);
+// Returns: updated Q-value
+```
+
+### `reset()`
+Clear in-memory Q-table cache.
+
+```typescript
+await qlearning.reset();
+// Note: Does not clear storage
+```
+
+### `getStateValues(state, actionSize)`
+Get all Q-values for a state.
+
+```typescript
+const values = qlearning.getStateValues('state1', 3);
+// Returns: { 0: 0.5, 1: 0.2, 2: -0.1 }
+```
+
+### `getFullQTable()`
+Get entire Q-table for inspection.
+
+```typescript
+const table = await qlearning.getFullQTable();
+// Returns:
+[
+  { state: 'state1', action: 0, q_value: 0.5 },
+  { state: 'state1', action: 1, q_value: 0.2 },
+  ...
+]
+```
+
+## Hyperparameters
+
+| Parameter | Default | Range | Description |
+|-----------|---------|-------|-------------|
+| `alpha` | 0.1 | [0, 1] | Learning rate — how much new info overrides old |
+| `gamma` | 0.9 | [0, 1] | Discount factor — future reward importance |
+| `epsilon` | 0.1 | [0, 1] | Exploration rate — random action probability |
+
+## Example
+
+```typescript
+import { QLearning, createStorage } from 'lsji';
+
+const storage = await createStorage('memory');
+const ql = new QLearning({ alpha: 0.1, gamma: 0.9, epsilon: 0.1, storage });
+
+await ql.initialize();
+
+// Train on simple state-action pairs
+await ql.learnSimple('state1', 0, 1);  // Win
+await ql.learnSimple('state1', 0, 1);  // Win again
+await ql.learnSimple('state1', 1, -1); // Lose
+
+// Check learned values
+console.log(ql.getQValue('state1', 0)); // ~0.19
+console.log(ql.getQValue('state1', 1)); // ~-0.1
+
+await storage.close();
+```