@game_ryo/lsji 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@game_ryo/lsji",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A general-purpose reinforcement learning agent framework (Node.js)",
   "license": "Apache-2.0",
   "type": "module",
@@ -22,5 +22,8 @@
   },
   "devDependencies": {
     "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/docs/README.md

@@ -1,43 +0,0 @@
-# Website
-
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
-
-## Installation
-
-```bash
-npm install
-```
-
-**Note**: feel free to use the package manager of your choice.
-
-## Local Development
-
-```bash
-npm run start
-```
-
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
-
-## Build
-
-```bash
-npm run build
-```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-## Deployment
-
-Using SSH:
-
-```bash
-USE_SSH=true npm run deploy
-```
-
-Not using SSH:
-
-```bash
-GIT_USER=<Your GitHub username> npm run deploy
-```
-
-If you are using GitHub Pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

package/docs/blog/2019-05-28-first-blog-post.mdx

@@ -1,12 +0,0 @@
----
-slug: first-blog-post
-title: First Blog Post
-authors: [slorber, yangshun]
-tags: [hola, docusaurus]
----
-
-Lorem ipsum dolor sit amet...
-
-{/* truncate */}
-
-...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

package/docs/blog/2019-05-29-long-blog-post.mdx

@@ -1,44 +0,0 @@
----
-slug: long-blog-post
-title: Long Blog Post
-authors: yangshun
-tags: [hello, docusaurus]
----
-
-This is the summary of a very long blog post,
-
-Use a `{/*` `truncate` `*/}` comment to limit blog post size in the list view.
-
-{/* truncate */}
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

package/docs/blog/2021-08-01-mdx-blog-post.mdx

@@ -1,24 +0,0 @@
----
-slug: mdx-blog-post
-title: MDX Blog Post
-authors: [slorber]
-tags: [docusaurus]
----
-
-Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).
-
-:::tip
-
-Use the power of React to create interactive blog posts.
-
-:::
-
-{/* truncate */}
-
-For example, use JSX to create an interactive button:
-
-```js
-<button onClick={() => alert('button clicked!')}>Click me!</button>
-```
-
-<button onClick={() => alert('button clicked!')}>Click me!</button>

package/docs/blog/2021-08-26-welcome/index.mdx

@@ -1,29 +0,0 @@
----
-slug: welcome
-title: Welcome
-authors: [slorber, yangshun]
-tags: [facebook, hello, docusaurus]
----
-
-[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
-
-Here are a few tips you might find useful.
-
-{/* truncate */}
-
-Simply add Markdown files (or folders) to the `blog` directory.
-
-Regular blog authors can be added to `authors.yml`.
-
-The blog post date can be extracted from filenames, such as:
-
-- `2019-05-30-welcome.md`
-- `2019-05-30-welcome/index.md`
-
-A blog post folder can be convenient to co-locate blog post images:
-
-![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
-
-The blog supports tags as well!
-
-**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.

package/docs/blog/authors.yml

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

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

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

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

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