Add English model documentation

Adds an English summary to the main model card and a complete English documentation file.

README.md

@@ -24,6 +24,8 @@ datasets:
 
 **Prévia técnica experimental em português para pesquisa e inferência local**
 
+🇧🇷 **Português** · 🇺🇸 [English documentation](README_EN.md)
+
 ![Parâmetros](https://img.shields.io/badge/parâmetros-203.263.872-19c37d)
 ![Pré--treino](https://img.shields.io/badge/pré--treino-1.000.013.824%20tokens-19c37d)
 ![Contexto](https://img.shields.io/badge/contexto-1.024%20tokens-19c37d)
@@ -38,6 +40,25 @@ datasets:
   <img src="assets/warmind-200m-v2-poster.png" alt="Resumo visual do WARMIND-200M V2" width="520">
 </p>
 
+## English summary
+
+**WARMIND-200M V2** is an experimental, Portuguese-first causal language model developed by **WAR Enterprise** for compact-model research and local inference.
+
+- **203,263,872 parameters**
+- **1,000,013,824 pretraining tokens**
+- **23,751,277 supervised SFT tokens**
+- **20 layers**, hidden size **896**
+- **14 attention heads** and **2 KV heads**
+- **Grouped-Query Attention, SwiGLU, RMSNorm and RoPE**
+- **24,576-token SentencePiece vocabulary**
+- **1,024-token operational context**
+- local CPU inference; CUDA is supported by the example script
+- Apache 2.0 license
+
+This is a research checkpoint, not a production assistant. It can hallucinate, fail on simple reasoning tasks and produce incomplete or incorrect answers.
+
+➡️ **[Open the full English documentation](README_EN.md)**
+
 ## Visão geral
 
 O **WARMIND-200M V2** é um modelo de linguagem causal compacto desenvolvido pela **WAR Enterprise** para pesquisa em geração de texto em português e inferência local.
@@ -141,7 +162,7 @@ python generate_local.py \
 
 ## Treinamento
 
-O checkpoint foi treinado em uma **NVIDIA H100 80 GB HBM3**, utilizando **BF16**.
+O checkpoint foi treinado em uma **NVIDIA H100 80 GB HBM3**, utilizando **BF16**. A execução principal do pré-treinamento levou aproximadamente **2 horas e 30 minutos**; preparação dos dados, treinamento do tokenizer, SFT, empacotamento e testes locais foram realizados separadamente.
 
 | Etapa | Registro |
 |---|---:|

README_EN.md

@@ -0,0 +1,258 @@
+# WARMIND-200M V2
+
+**Experimental Portuguese-first technical preview for research and local inference**
+
+🇧🇷 [Português](README.md) · 🇺🇸 **English**
+
+![Parameters](https://img.shields.io/badge/parameters-203%2C263%2C872-19c37d)
+![Pretraining](https://img.shields.io/badge/pretraining-1%2C000%2C013%2C824%20tokens-19c37d)
+![Context](https://img.shields.io/badge/context-1%2C024%20tokens-19c37d)
+![License](https://img.shields.io/badge/license-Apache--2.0-blue)
+![Status](https://img.shields.io/badge/status-experimental-orange)
+
+> ⚠️ **Usage warning:** this checkpoint may produce incorrect information, incomplete answers and hallucinations. Do not use its outputs for medical, legal, financial, safety-related or other high-impact decisions without qualified human review.
+
+<p align="center">
+  <img src="assets/warmind-200m-v2-poster.png" alt="WARMIND-200M V2 visual summary" width="520">
+</p>
+
+## Overview
+
+**WARMIND-200M V2** is a compact causal language model developed by **WAR Enterprise** for research on Portuguese text generation and local inference.
+
+The published version is a **research artifact**, not a production assistant. Its main purpose was to validate a complete development pipeline: data preparation, tokenizer training, pretraining, supervised fine-tuning, packaging, integrity verification and local execution.
+
+## At a glance
+
+| Item | Value |
+|---|---:|
+| Parameters | **203,263,872** |
+| Pretraining tokens | **1,000,013,824** |
+| Tokens processed during SFT | **23,751,277** |
+| Layers | **20** |
+| Hidden size | **896** |
+| Attention / KV heads | **14 / 2** |
+| Vocabulary | **24,576-token SentencePiece** |
+| Operational context | **1,024 tokens** |
+| Published weights | **safetensors FP32** |
+| Primary language | **Portuguese** |
+| Execution | **Local CPU; CUDA supported by the example script** |
+
+## Transparent demonstration — including limitations
+
+The video below shows the checkpoint's real behavior, including weak and incorrect answers. These limitations are part of the technical evaluation of this release.
+
+[![Open the real WARMIND-200M V2 demonstration](assets/demo-thumb.jpg)](assets/demo-real.mp4)
+
+The demonstration includes:
+
+- basic Portuguese generation;
+- retrieval of some facts;
+- mistakes in arithmetic and factual knowledge;
+- plausible but incorrect answers;
+- an explicit review of observed failures.
+
+## Quick start
+
+### Requirements
+
+- Python **3.12**
+- at least **8 GB of free RAM** for a comfortable local experience
+
+### Installation
+
+```bash
+python -m venv .venv
+python -m pip install -r requirements.txt
+```
+
+### Windows PowerShell
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+
+python generate_local.py `
+  --prompt "Defina fotossíntese em uma frase." `
+  --max-new-tokens 96
+```
+
+### Linux or macOS
+
+```bash
+source .venv/bin/activate
+
+python generate_local.py \
+  --prompt "Defina fotossíntese em uma frase." \
+  --max-new-tokens 96
+```
+
+### More controlled generation
+
+```bash
+python generate_local.py \
+  --prompt "Explique em duas frases o que é inteligência artificial." \
+  --temperature 0.2 \
+  --top-k 20 \
+  --top-p 0.9 \
+  --repetition-penalty 1.12 \
+  --max-new-tokens 160
+```
+
+> Confirm whether the published script accepts `--max-new-tokens` or `--maximum-new-tokens`, and keep only the supported form in the documentation.
+
+## Architecture
+
+| Component | Value |
+|---|---|
+| Type | Causal decoder-only Transformer |
+| Layers | 20 |
+| Hidden size | 896 |
+| Attention heads | 14 |
+| KV heads | 2 |
+| Attention | Grouped-Query Attention (GQA) |
+| FFN dimension | 2,688 |
+| Activation | SwiGLU |
+| Normalization | RMSNorm |
+| Positional encoding | RoPE, θ = 10,000 |
+| Trained/operational context | 1,024 tokens |
+| Extended context accepted by the code | up to 2,048 tokens, not validated as training context |
+
+## Training
+
+The checkpoint was trained on a single **NVIDIA H100 80 GB HBM3** using **BF16**.
+
+The main pretraining run took approximately **2 hours and 30 minutes**. Data preparation, tokenizer training, supervised fine-tuning, packaging and local testing were performed separately.
+
+| Stage | Recorded value |
+|---|---:|
+| V2 pretraining | 1,000,013,824 tokens |
+| Supervised fine-tuning | completed at step 1,200 |
+| Validation loss at step 100 | 2.1085 |
+| Validation loss at step 1,200 | 1.8038 |
+
+These values describe the recorded training process and should not be interpreted on their own as proof of general model quality.
+
+## Data and provenance
+
+### Pretraining
+
+Pretraining used a Portuguese sample from `epfml/FineWeb2-HQ` (`por_Latn`), under **ODC-By-1.0** and also subject to Common Crawl terms.
+
+Approximate prepared-data composition:
+
+- **93.6%** general content;
+- **5.0%** legal content;
+- **1.4%** technical content.
+
+### Supervised fine-tuning
+
+The SFT mixture included:
+
+- Portuguese conversations from `HuggingFaceTB/smoltalk2`;
+- filtered data from `OpenAssistant/oasst2`;
+- WAR Enterprise's own examples.
+
+Attributions and the subsets used should remain documented in [`NOTICE.md`](NOTICE.md).
+
+> Source data may contain errors, distortions, synthetic content or personal information present in the original datasets. Training does not make the model a reliable factual source.
+
+## Experimental local chat
+
+`chat_calibrate.py` adds:
+
+- short-term memory;
+- search over local files;
+- a deterministic calculator;
+- optional Wikipedia and Wikidata lookup.
+
+```bash
+python chat_calibrate.py
+```
+
+This orchestrator does not change the model weights and does not provide access to the Transformer's “internal thoughts.”
+
+When online lookup is enabled, the question text may be sent to the corresponding public APIs. Use:
+
+```text
+/online off
+```
+
+to keep the session offline.
+
+## Maturity status
+
+**Status:** `EXPERIMENTAL_NOT_DEMO_READY` / `AWAITING_HUMAN_REVIEW`
+
+V2 improved over the first checkpoint, but it still shows:
+
+- hallucinated facts, names, numbers and identities;
+- repetition and topic drift;
+- failures to follow requested length limits;
+- plausible but incorrect answers;
+- sensitivity to sampling parameters;
+- limitations in basic arithmetic and reasoning.
+
+This release should therefore be treated as a **technical preview for research, learning and local reproduction**, not as a state-of-the-art benchmark.
+
+## Intended uses
+
+- research on compact Portuguese models;
+- study of local CPU inference;
+- generation experiments with human review;
+- educational prototyping;
+- comparison of post-processing techniques;
+- experiments with external tools.
+
+## Non-recommended uses
+
+- automated or high-impact decisions;
+- medical, legal or financial advice;
+- factual content without external verification;
+- moderation, surveillance or classification of people;
+- applications requiring guaranteed safety, accuracy or availability.
+
+## File integrity
+
+SHA-256 hashes are listed in [`SHA256SUMS`](SHA256SUMS).
+
+Expected hash for `model.safetensors`:
+
+```text
+42218dacd46c7a3d244856e664442822e002312bf871a57181379d9026a61045
+```
+
+## Future research
+
+WAR Enterprise is studying a future generation in the range of **500 million parameters**, potentially trained on a substantially larger token budget.
+
+This is a **research objective**, not a release promise. Progress depends on infrastructure, data, evaluations and technical results.
+
+## Technical feedback
+
+Useful contributions include:
+
+- tests on different CPUs;
+- RAM and tokens-per-second measurements;
+- Portuguese benchmarks;
+- tokenizer bug reports;
+- GGUF and quantization suggestions;
+- reproducible failure examples.
+
+Use the repository's **Community** tab to open a discussion.
+
+## Citation
+
+```bibtex
+@software{warmind200mv2_2026,
+  title  = {WARMIND-200M V2},
+  author = {WAR Enterprise},
+  year   = {2026},
+  note   = {Experimental technical preview of a Portuguese language model},
+  url    = {https://huggingface.co/warenterprise/WARMIND-200M-V2}
+}
+```
+
+---
+
+Developed by **WAR Enterprise**  
+Compact-model research, local execution and technical transparency.