Update README.md

README.md

@@ -1,47 +1,195 @@
 ---
-license: bsl-1.0
+license: apache-2.0
+language:
+- en
+- fr
+tags:
+- code-generation
+- python
+- chain-of-thought
+- sparse-transformer
+- multilingual
+- amforge
+- sparsemind
+library_name: pytorch
+pipeline_tag: text-generation
+inference: false
+model-index:
+- name: cofos_v2
+  results:
+  - task:
+      type: text-generation
+      name: Python code generation
+    metrics:
+    - type: real_syntax_valid
+      value: 63.0
+      name: Real Python syntax validity (held-out)
 ---
 
-# Cofos Code Model ({MODEL_VERSION}) — SparseMind 500M
+# Cofos v2 — Multilingual Python Code Assistant
 
-**Cofos v2** is a 500M-parameter code model built on AMFORGE's **SparseMind v15**
-architecture. Same essence as Cofos v1 (296M @ 34% real_syntax_valid),
-scaled larger and trained with multilingual instructions + chain-of-thought.
+**Cofos v2** is a 522M-parameter code assistant specialized in Python, with native French/English bilingual support and optional chain-of-thought reasoning. It is the second iteration in the Cofos series by **AMEFORGE**, built on the proprietary **SparseMind** architecture.
 
-Developed by **{ORGANIZATION}**.
+This model is designed to produce syntactically correct, executable Python code from natural-language instructions in either French or English, with the ability to emit its reasoning before the code when requested.
 
-## Architecture (SparseMind v15)
+---
+
+## Model Summary
+
+| Field | Value |
+|---|---|
+| **Developer** | AMEFORGE |
+| **Architecture** | SparseMind v15 (proprietary) |
+| **Parameters** | 522M |
+| **Context length** | 2048 tokens |
+| **Vocabulary** | 16,384 (custom nexusBPE) |
+| **Languages** | French, English |
+| **Primary task** | Python code generation |
+| **License** | Apache 2.0 |
+| **Status** | Active development |
+
+---
+
+## Intended Use
+
+### Primary use cases
+
+- **Python code generation** from natural-language prompts (function specs, class designs, algorithm requests)
+- **Bilingual coding assistance** for developers working in French or English
+- **Chain-of-thought reasoning** when reasoning steps are useful before the code (toggle via prompt format)
+- Integration as a lightweight code assistant in development pipelines where larger models are impractical
 
+### Out-of-scope
 
-## Parameters
-- `dim={cfg.dim}` (v1: 768), `n_layers={cfg.n_layers}`, `n_heads={cfg.n_heads}`
-  (`head_dim={cfg.dim // cfg.n_heads}` — same as v1)
-- `max_seq_len={cfg.max_seq_len}` (v1: 512), `vocab_size={cfg.vocab_size}`
-- `channel_top_k={cfg.channel_top_k}`, `token_top_k={cfg.token_top_k}`
-  (same sparsity ratios as v1)
-- **Total parameters:** {model.n_params:,}
+This model is **not designed for**:
+- General conversation or open-ended dialogue
+- Languages other than French and English
+- Code in languages other than Python (some JavaScript and Rust tokens are present in the vocabulary but the model has not been trained for general production in those languages)
+- Tasks requiring large-context reasoning (>2048 tokens)
+- Factual knowledge retrieval, scientific reasoning, or creative writing
 
-## Training data (3-way mix)
-- **30% real HF Python** (`iamtarun/python_code_instructions_18k_alpaca`)
+Cofos v2 is a specialized coding tool. Use it for what it was built for and pair it with appropriate tools for everything else.
 
+---
+
+## Performance
+
+Evaluated on a held-out set of real Python instruction prompts (no overlap with training data).
+
+| Metric | Value |
+|---|---|
+| Real-syntax-valid (held-out, n=100) | **63.0%** |
+| Validation loss | 3.08 |
+| Model size (on disk) | ~2.1 GB (fp32) |
+
+The model has been observed to generate syntactically valid Python with reasonable semantic alignment to short-to-medium instructions. Performance degrades with very long contexts (>1500 tokens) and on instructions that combine multiple distinct subtasks.
+
+---
 
-## Result
-- **Best `real_syntax_valid`:** {best_syntax:.1f}% on held-out real Python instructions
+## Usage
 
-## Tokenizer
-- v2 tokenizer at [{HF_TOK_REPO_ID}](https://huggingface.co/{HF_TOK_REPO_ID})
-  
+### Loading
 
-## How to use
 ```python
+from huggingface_hub import hf_hub_download
 import torch
-import sentencepiece as spm
 
-# Load checkpoint
-ckpt = torch.load("cofos_best.pt", map_location="cpu")
-cfg_dict = ckpt["config"]
+# Download checkpoint
+checkpoint_path = hf_hub_download(repo_id="AMFORGE/cofos_v2", filename="cofos_model.pt")
+tokenizer_path  = hf_hub_download(repo_id="AMFORGE/cofos_v2", filename="cofos_tokenizer.model")
+
+# Loading requires the AMEFORGE inference runtime. Contact AMEFORGE for access
+# to the runtime, or use the streaming inference script provided with the model.
+```
+
+### Prompt format
+
+Cofos v2 expects a structured prompt format with explicit XML-style tags. The basic pattern is:
+
+```
+<instruction>Write a Python function that ...</instruction>
+```
+
+For chain-of-thought generation, prefix with a `<thought>` tag:
+
+```
+<instruction>Write a Python function that ...</instruction>
+<thought>
+```
+
+The model will then generate its reasoning, followed by the code block.
+
+---
+
+## Training
+
+Cofos v2 was trained from scratch on a curated mix of:
+- Multi-source distilled instruction data with chain-of-thought reasoning (in French and English)
+- Real Python instruction-following data from public datasets
+- A small synthetic component for algorithmic diversity
+
+Training was conducted with the proprietary SparseMind training pipeline, with periodic safety checkpointing to ensure reproducibility and recovery from interruptions.
+
+**Tokenizer:** [AMFORGE/cofos_tok_v2](https://huggingface.co/AMFORGE/cofos_tok_v2) — a custom SentencePiece model with French-aware coverage, structural XML tags as atomic tokens, and Python keyword/builtin atoms for compact representation of code.
+
+---
+
+## Lineage
+
+```
+cofos_tok_v2 (tokenizer)
+       ↓
+cofos_v2 (this model) — code-specialized from scratch
+```
+
+Cofos v2 is a standalone code-specialized model. It is **not** a derivative of any other published model.
+
+---
+
+## Limitations & Biases
+
+- **Capacity**: At 522M parameters, Cofos v2 has limited capacity for complex multi-step reasoning compared to billion-parameter models. Use it for focused coding tasks, not as a general-purpose assistant.
+- **Language coverage**: The model is bilingual FR/EN. Prompts in other languages will produce degraded output or fall back to broken English/French.
+- **Hallucination**: As with all autoregressive language models, Cofos v2 can produce code that looks plausible but is incorrect. Always test generated code before use.
+- **Training data**: While care was taken to use clean, publicly-sourced datasets, the model may reflect biases present in those datasets.
+- **No safety alignment**: Cofos v2 has not undergone RLHF or any explicit safety alignment beyond pre-training data curation. It should not be deployed in user-facing products without additional safety layers.
+
+---
+
+## Environmental Considerations
+
+Cofos v2 is intentionally small (522M parameters) to minimize the compute footprint of both training and inference. It can run on a single consumer GPU and is suitable for on-device deployment after appropriate optimization.
+
+---
+
+## License
+
+This model is released under the **Apache 2.0** license. You are free to use, modify, and redistribute it, including for commercial purposes, subject to the terms of the license.
+
+---
+
+## Citation
+
+If you use Cofos v2 in your work, please cite:
+
+```bibtex
+@misc{cofos_v2_2026,
+  title  = {Cofos v2: A Multilingual Python Code Assistant},
+  author = {{AMEFORGE}},
+  year   = {2026},
+  url    = {https://huggingface.co/AMFORGE/cofos_v2}
+}
+```
+
+---
+
+## Contact
+
+For questions, collaborations, or access to the AMEFORGE inference runtime:
+
+- **Organization**: AMEFORGE
+- **HuggingFace**: [@AMFORGE](https://huggingface.co/AMFORGE)
+
+---
 
-# Instantiate model architecture
-# model = SparseMind(Config(**cfg_dict))
-# model.load_state_dict(ckpt["model"])
-# model.eval()
+*Cofos is part of a broader family of specialized models being developed by AMEFORGE under the SparseMind architecture program. See the [AMFORGE organization page](https://huggingface.co/AMFORGE) for related work.*