Upload README.md with huggingface_hub

README.md

@@ -1,110 +1,50 @@
----
-library_name: stable-baselines3
-tags:
-- FruitBox
-- reinforcement-learning
-- ppo
-- game-ai
-- puzzle-solving
-model-index:
-- name: AlphaApple
-  results:
-  - task:
-      type: reinforcement-learning
-      name: Reinforcement Learning
-    dataset:
-      name: FruitBox Game
-      type: fruitbox
-    metrics:
-    - type: mean_reward
-      value: 77.0
-      name: Mean Episode Score
-    - type: improvement_vs_random
-      value: 7.1%
-      name: Improvement vs Random
-    - type: improvement_vs_greedy  
-      value: 5.0%
-      name: Improvement vs Greedy
----
-
-# AlphaApple: FruitBox Game AI Agent
-
-## Model Description
-
-이 모델은 한국의 사과게임(FruitBox) 퍼즐을 해결하는 AI 에이전트입니다. 
-10×17 격자에서 합이 10인 직사각형을 찾아 제거하는 게임을 PPO(Proximal Policy Optimization) 알고리즘으로 학습했습니다.
-
-## Game Rules
-
-- 10×17 격자, 각 셀은 1-9 숫자
-- 직사각형 영역을 선택해서 숫자 합이 정확히 10이면 해당 영역 제거
-- 제거된 셀 개수만큼 점수 획득
-- 더 이상 제거할 수 있는 영역이 없으면 게임 종료
-
-## Performance
-
-| Agent   | Average Score | Improvement |
-|---------|--------------|-------------|
-| Random  | 71.9         | -           |
-| Greedy  | 73.3         | +1.9%       |
-| **PPO** | **77.0**     | **+7.1%**   |
-
-## Usage
-
-### Python (PyTorch)
-
-```python
-from stable_baselines3 import PPO
-from stable_baselines3.common.vec_env import DummyVecEnv
-
-# Load model
-model = PPO.load("pytorch_model.zip")
-
-# Use for inference
-obs = env.reset()
-action, _ = model.predict(obs)
-```
-
-### Web/JavaScript (ONNX)
-
-```javascript
-import { InferenceSession } from 'onnxruntime-web';
-
-// Load ONNX model
-const session = await InferenceSession.create('./fruitbox_ppo.onnx');
-
-// Predict action
-const { action_logits } = await session.run({
-    board_input: new ort.Tensor('float32', board_data, [1, 17, 10, 1])
-});
-const action = action_logits.data.indexOf(Math.max(...action_logits.data));
-```
-
-## Files
-
-- `pytorch_model.zip`: Original SB3 PPO model 
-- `fruitbox_ppo.onnx`: ONNX version for web deployment (2.95MB)
-- `model_info.json`: Model metadata and performance metrics
-
-## Training Details
-
-- Algorithm: PPO with action masking
-- Network: Custom CNN (SmallGridCNN)
-- Training steps: 1,000,000
-- Environment: Custom Gymnasium environment
-- Action space: 8,415 possible rectangles (masked)
-
-## Repository
-
-Source code: https://github.com/your-username/alphaapple
-
-## Citation
-
-```bibtex
-@misc{alphaapple2024,
-  title={AlphaApple: AI Agent for FruitBox Puzzle Game},
-  author={Your Name},
-  year={2024},
-  howpublished={\url{https://huggingface.co/AlphaApple}}
-}
-```
+# 🍎 AlphaApple - RL for Perfect FruitBox Play
+
+**목표**: 사과게임(FruitBox) 170개 셀 **전부 제거** (100% 클리어)
+
+강화학습으로 인간을 넘어서는 성능 달성을 목표로 하는 프로젝트입니다.
+
+## 🚀 현재 진행 상황 및 성과
+- **DQN 베이스라인 구축 완료**: CNN 기반의 DQN 모델과 커리큘럼 학습을 통해 안정적인 학습 기반을 마련했습니다.
+- **성능 기록**: 약 10,000 에피소드 학습 결과, 평균 **96% (163.4개)**의 사과를 제거하는 성과를 달성했습니다.
+- **솔루션 보장형 환경**: `BackwardBoardGenerator`를 도입하여 항상 해답이 존재하는 보드에서 학습할 수 있도록 환경을 개선했습니다.
+
+## 🛠 주요 기능
+- **고성능 환경 (`envs/fruitbox_env.py`)**: Prefix Sum 및 Incremental Action Masking을 적용하여 연산 속도를 극대화했습니다.
+- **DQN 에이전트 (`src/agent.py`, `src/models.py`)**: 10채널 One-hot 인코딩 입력과 액션 마스킹을 지원하는 CNN 모델입니다.
+- **Colab 최적화**: GPU 및 TPU 가속을 지원하는 통합 학습 노트북(`experiments/train_colab_integrated.ipynb`, `experiments/train_colab_jax.ipynb`)을 제공합니다.
+- **시각화 도구**: 에이전트의 플레이를 단계별 ASCII 그래픽으로 렌더링하고 전략을 분석할 수 있는 기능을 포함하고 있습니다.
+
+## 📁 프로젝트 구조
+- `envs/`: 사과게임 환경 및 보드 생성기
+- `src/`: DQN 모델 아키텍처 및 에이전트 로직
+- `experiments/`: 로컬 및 Colab용 학습 스크립트/노트북
+- `checkpoints/`: 학습된 모델 저장 폴더
+
+## 🚀 모델 배포 및 실전 도입
+### 1. ONNX 변환 및 Hugging Face 업로드
+- **ONNX 변환**: 브라우저에서 실행 가능하도록 모델을 변환합니다.
+  ```bash
+  uv run python src/export_onnx.py --model_path checkpoints/model.pth --output_path extension/model.onnx
+  ```
+- **Hugging Face 업로드**: 학습된 가중치와 ONNX 모델을 허브에 공유합니다.
+  ```bash
+  uv run python src/upload_hf.py --repo_id "사용자/리포지토리" --model_path checkpoints/model.pth --onnx_path extension/model.onnx
+  ```
+
+### 2. Chrome Extension (FruitBox Solver)
+실제 [Gamesaien Fruit Box](https://en.gamesaien.com/game/fruit_box/) 사이트에서 모델을 실행하여 해답을 찾아주는 확장 프로그램입니다.
+
+#### 설치 방법:
+1. 브라우저 주소창에 `chrome://extensions/` 입력
+2. '개발자 모드' 활성화
+3. '압축해제된 확장 프로그램을 로드합니다' 클릭 후 프로젝트의 `extension/` 폴더 선택
+4. **중요**: 확장 프로그램 폴더 안에 `model.onnx` 파일과 [onnxruntime-web](https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/onnxruntime.min.js) 라이브러리가 포함되어야 합니다.
+
+#### 사용 방법:
+- 게임 사이트 접속 후 확장 프로그램 팝업에서 **"Find Best Move"** 버튼 클릭
+- 화면에 최적의 사과 박스가 빨간색으로 표시됩니다.
+
+## 📈 앞으로의 계획
+- **100% 클리어 도전**: 현재의 96% 성과를 넘어 100% 클리어를 위해 더 깊은 신경망(ResNet 등)과 PPO 알고리즘 도입을 검토 중입니다.
+- **JAX/TPU 가속 확대**: 더 빠른 실험을 위해 JAX 기반의 분산 학습 환경을 고도화할 예정입니다.