Update README.md

README.md

@@ -1,3 +1,132 @@
----
-license: agpl-3.0
----
+---
+license: agpl-3.0
+language:
+- en
+tags:
+- pokemon-showdown
+- transformer
+- game-ai
+- monte-carlo-search
+library_name: pytorch
+pipeline_tag: text-generation
+---
+
+# AlphaMon
+
+AlphaMon is a transformer-based battle policy model for Pokemon Showdown doubles formats, trained on large-scale replay logs and used with a Monte Carlo rollout search layer for decision support.
+
+Current repository: https://github.com/davidemodolo/alphamon
+
+## Model summary
+
+AlphaMon is a decoder-only transformer trained on tokenized Showdown battle logs.  
+It predicts:
+
+1. Next token (policy head)
+2. Win probability (value head)
+
+At inference time, model outputs are combined with structured rollout search to produce ranked battle actions.
+
+## What is currently released
+
+This model repo currently includes:
+
+1. Pretrained checkpoint:
+   - checkpoints/alphamon_pretrained_best.pt
+2. Training replay list used for dataset construction:
+   - release/training_games_list.txt
+
+Finetuned checkpoints are still in progress and may be added later.
+
+## Architecture
+
+Main model config (current defaults from training code):
+
+1. Context length: 2048
+2. Hidden size: 512
+3. Attention heads: 8
+4. Layers: 6
+5. Dropout: 0.1
+
+Training objective:
+
+1. Cross-entropy loss for policy tokens
+2. MSE loss for value prediction
+3. Combined loss: policy + 0.5 * value
+
+## Data
+
+Training data is derived from publicly available Pokemon Showdown replay logs, harvested by format and filtered/cleaned before tokenization.
+
+Data pipeline includes:
+
+1. Replay harvesting from Showdown search endpoint
+2. Metadata extraction (winner, ratings, format)
+3. Quality and format filtering
+4. Tokenization and mmap cache construction
+
+## Intended use
+
+AlphaMon is intended for:
+
+1. Research and experimentation in game AI
+2. Decision support for Pokemon Showdown doubles battle states
+3. Study of sequence modeling + search-based action selection
+
+It is not intended for:
+
+1. Fully autonomous ladder abuse or platform policy violations
+2. Safety-critical applications
+3. Legal advice or compliance decisions
+
+## Limitations
+
+1. Strongly domain-specific to Showdown-style tokenized logs
+2. Quality depends on training replay distribution and filtering
+3. Not guaranteed to choose legal-optimal actions in all edge cases
+4. Performance can degrade on unseen formats or mechanics
+
+## Inference notes
+
+In the main project, inference uses:
+
+1. Monte Carlo rollout search for TURN, TEAM_PREVIEW, and FAINT objectives
+2. Optional team-aware logit bias to nudge generation toward known:
+   - species tokens
+   - move tokens
+   - item tokens
+   - tera type tokens
+
+This bias is additive and does not hard-force outputs.
+
+## How to use with the project
+
+1. Clone the main repo:
+   - https://github.com/davidemodolo/alphamon
+2. Download checkpoint from this HF model repo into:
+   - checkpoints/alphamon_pretrained_best.pt
+3. Run server inference from the repo:
+   - python server/server.py
+
+## License and third-party content
+
+This repository is currently marked AGPL-3.0.
+
+Important note:
+Pokemon-related names, mechanics, and source replay content may be subject to their own rights and terms by their respective owners/platforms.  
+This model card and repository license apply to the released project assets to the extent permitted.
+
+## Citation
+
+If you use AlphaMon in research, please cite:
+
+Modolo, Davide. AlphaMon: Transformer-based Showdown Battle Policy Model.
+
+You can also cite the GitHub repository:
+https://github.com/davidemodolo/alphamon
+
+## Contact
+
+Maintainer: Davide Modolo  
+HF: https://huggingface.co/davidemodolo  
+GitHub: https://github.com/davidemodolo