Update README.md

README.md

@@ -1,97 +1,221 @@
 ---
-license: apache-2.0
 language:
 - en
 - fr
 tags:
 - code-generation
-- multilingual
-- chain-of-thought
-- instruction-tuned
-- finetuned
-- personalized
 - python
-- sparsemind
+- chain-of-thought
 - sparse-transformer
+- personalized
 - amforge
-base_model: AMFORGE/cofos_v2
-base_tokenizer: AMFORGE/cofos_tok_v2
+- sparsemind
+- fine-tuned
+library_name: pytorch
 pipeline_tag: text-generation
 inference: false
+base_model: AMFORGE/cofos_v2
+model-index:
+- name: cofos_logo_v2
+  results:
+  - task:
+      type: text-generation
+      name: Python code generation
+    metrics:
+    - type: real_syntax_valid
+      value: 66
+      name: Real Python syntax validity (held-out)
 ---
 
-# Cofos Logo v2 (v1-personal-from-v2) — SparseMind personalized code assistant
-
-Fine-tuned from [AMFORGE/cofos_v2](https://huggingface.co/AMFORGE/cofos_v2)
-on the author's personal data (GitHub repos + ChatGPT conversations +
-Anthropic conversations). The result is a model that codes and reasons in
-the author's own style — variable naming, code structure, French/English
-mix, debugging approach.
-
-**Lineage** — full SparseMind v15 chain:
-1. **Pretraining** on FineWeb-Edu (EN) + FineWeb-2 fra_Latn (FR) → `cofos_general_(600m|1b)`
-2. **Code finetune** on `cofos_distilled.jsonl` → `cofos_general_code_(600m|1b)`
-3. **Personal finetune** on `cofos_personal_redacted.jsonl` → THIS MODEL
-
-All API keys and credentials were redacted from the personal dataset BEFORE
-training. The model has never seen real secrets.
-
-Developed by **AMEFORGE**.
-
-## Architecture (SparseMind v15 — strictly preserved end-to-end)
-- **7 NeuronTypes** with dynamic plasticity (`DynamicTypeManager`):
-  STEM, EXCITATORY, INHIBITORY, MEMORY, RELAY, MODULATORY, PATTERN
-- **`BalancedDiversityLayer`** on every even layer — 5 specialised modules
-- **`SparseAttn`** (Top-K tokens) + **`SparseFFN`** with `SparseGate` (Top-K channels)
-- **`MemoryBank`** + **`MemoryLayer`** (off by default per AMFORGE empirical)
-- **Type-differentiated optimizer** (per-neuron weight decay)
-- **Label smoothing 0.05**, embedding tied with output projection
-
-## Parameters (inherited from base — unchanged)
-- `dim=1024`, `n_layers=20`, `n_heads=16` (head_dim=64)
-- `max_seq_len=2048`, `vocab_size=16384`
-- `channel_top_k=320`, `token_top_k=512`
-- **Total parameters:** 522,771,466
-
-## Personal fine-tune
-- **Base:** [AMFORGE/cofos_v2](https://huggingface.co/AMFORGE/cofos_v2)
-- **Steps:** 1500, **LR:** 1e-05 (2.5× lower than general finetune)
-- **Best `real_syntax_valid`:** 66.0%
-
-## Data mix (65% / 25% / 10%)
-- **65% personal** (`cofos_personal_redacted.jsonl`) — your GitHub + ChatGPT +
-  Anthropic conversations (secrets redacted before training)
-- **25% distilled** (`cofos_distilled.jsonl`) — kept as anti-catastrophic-
-  forgetting signal so generic skills aren't lost
-- **10% real HF Python** — production patterns
-
-## Tokenizer
-- [AMFORGE/cofos_tok_v2](https://huggingface.co/AMFORGE/cofos_tok_v2) — vocab 16384,
-  NexusBPE-based (custom AMEFORGE tokenizer built on SentencePiece),
-  byte_fallback=True (full multilingual + Unicode coverage), FR-aware
-- 381+ atomic tokens (Python keywords, dunders, builtins, decorators,
-  JS namespaced methods, Rust macros, structural tags `<instruction>`
-  `<thought>` `<python>` `<code>` `<test>`)
+# Cofos Logo v2 — Personalized Python Code Assistant
 
-## Usage
-```bash
-python cofos_inference_streaming.py \
-    --model AMFORGE/cofos_logo_v2 \
-    --prompt "Crée une classe Python LRUCache avec capacité maximale" \
-    --with-thought --max-tokens 5000
+**Cofos Logo v2** is a 522M-parameter personalized code assistant, fine-tuned from [`AMFORGE/cofos_v2`](https://huggingface.co/AMFORGE/cofos_v2) on a curated corpus of personal coding conversations and project artifacts. It is the first **personalization-tier** model in the Cofos family by **AMEFORGE**, built on the proprietary **SparseMind** architecture.
+
+The "Logo" suffix denotes that this variant has been fine-tuned on a specific developer's personal style and patterns. The base model remains general-purpose; this variant is a directional bias toward a particular coding voice.
+
+---
+
+## Model Summary
+
+| Field | Value |
+|---|---|
+| **Developer** | AMEFORGE |
+| **Architecture** | SparseMind v15 (proprietary) |
+| **Parameters** | 522M |
+| **Context length** | 2048 tokens |
+| **Vocabulary** | 16,384 (NexusBPE, FR-aware) |
+| **Languages** | French, English |
+| **Base model** | [AMFORGE/cofos_v2](https://huggingface.co/AMFORGE/cofos_v2) |
+| **Specialization** | Personal coding style + Python |
+| **License** | Apache 2.0 |
+| **Status** | Experimental — first personalization tier |
+
+---
+
+## Intended Use
+
+### Primary use cases
+
+- **Personalized Python code generation** that reflects a specific developer's style and preferred patterns
+- **Bilingual coding assistance** (French/English) where consistency with the developer's authored prompts matters
+- **Experimental baseline** for studying personalization of small code models through targeted fine-tuning
+
+### Out-of-scope
+
+This model is **not designed for**:
+- General-purpose code assistance for other developers (the personal bias may produce surprising stylistic outputs)
+- Tasks requiring broad knowledge or long-context reasoning
+- Languages other than French and English
+- Languages other than Python (other syntaxes appear only as artifacts of the base)
+- Production deployment without human review
+
+Cofos Logo v2 is a **research artifact**, not a general assistant. It explores whether targeted fine-tuning of a small specialized base on personal data produces a measurably "voiced" model.
+
+---
+
+## Performance
+
+Evaluated on the same held-out set of 100 real Python instruction prompts used during base training.
+
+| Metric | Cofos v2 base | Cofos Logo v2 (this) |
+|---|---:|---:|
+| Real-syntax-valid (n=100) | 67.0% | **66.0%** |
+| Validation loss | 3.07 | 2.98 |
+
+The fine-tune produces a small drop in raw Python syntactic validity (-1pp) and a meaningful improvement in validation loss on personal+code mixed data (-0.09). This is the expected trade-off of personalization: the model has shifted some capacity toward modeling personal style at a marginal cost to generic Python correctness.
+
+A separate external benchmark (50 prompts, semantic execution tests) is available in the [Cofos benchmark suite](https://huggingface.co/AMFORGE/cofos_v2). Refer to that for comparison against open-source small code models.
+
+---
+
+## Training
+
+### Fine-tune configuration
+
+- **Base**: AMFORGE/cofos_v2 (522M, step 11500, 67% real_syntax_valid)
+- **Method**: Continued training (not LoRA — full parameter fine-tune)
+- **Steps**: 1500
+- **Learning rate**: 1e-5 (conservative — base is heavily trained)
+- **Schedule**: 100-step warmup, cosine decay to 0
+- **Best checkpoint**: step 600 (saved as `cofos_model.pt`)
+
+### Data mix
+
+- **65% personal data** — curated conversations and code artifacts from the model author
+- **25% distilled instruction-response data** — kept as anti-catastrophic-forgetting signal so generic skills are preserved
+- **10% real Python instructions** — production patterns from public datasets
+
+All personal data was redacted for secrets (API keys, tokens, PEM keys) before training. Redaction tokens use stable placeholders so the model learns to emit the placeholder rather than the secret.
+
+### Tokenizer
+
+[AMFORGE/cofos_tok_v2](https://huggingface.co/AMFORGE/cofos_tok_v2) — NexusBPE-based custom tokenizer (vocab 16384, FR-aware, with atomic structural tags `<instruction>` `<thought>` `<python>` `<code>` `<test>`). Inherited from the base model unchanged.
+
+---
+
+## Lineage
+
+```
+cofos_tok_v2 (tokenizer, NexusBPE)
+       ↓
+cofos_v2 (base code model, from scratch, 67% syntax)
+       ↓
+cofos_logo_v2 (this model — personal fine-tune, 66% syntax)
 ```
 
-## How to use
+A parallel branch (`cofos_logo_general`) is planned, fine-tuning the upcoming general-purpose base instead of cofos_v2. The two variants will be compared empirically.
+
+---
+
+## Usage
+
+### Loading
+
 ```python
-import torch
-import sentencepiece as spm
+from huggingface_hub import hf_hub_download
+
+checkpoint_path = hf_hub_download(repo_id="AMFORGE/cofos_logo_v2",
+                                  filename="cofos_model.pt")
+tokenizer_path  = hf_hub_download(repo_id="AMFORGE/cofos_logo_v2",
+                                  filename="cofos_tokenizer.model")
+```
+
+Loading and inference require the AMEFORGE SparseMind runtime. The model architecture is proprietary; contact AMEFORGE for access to the runtime.
+
+### Prompt format
+
+```
+<instruction>Write a Python function that ...</instruction>
+```
+
+For chain-of-thought generation, prime with `<thought>`:
+
+```
+<instruction>Write a Python function that ...</instruction>
+<thought>
+```
+
+For code generation primed with the wrapper:
+
+```
+<instruction>Write a Python function that ...</instruction>
+<python><code>
+```
+
+---
+
+## Limitations & Risks
+
+### Personalization-specific
 
-# Load checkpoint
-ckpt = torch.load("cofos_best.pt", map_location="cpu")
-cfg_dict = ckpt["config"]
+- **Stylistic bias**: The model has been fine-tuned on one developer's style. Output will reflect that style and may feel unnatural to other developers.
+- **Voice persistence**: The model has learned recurring patterns (variable naming, function structure, comment style) from the personal corpus. These will appear even when not requested.
+- **Topical narrowness**: The personal corpus has its own topical distribution (heavy on ML, light on web frontend, etc.). Generations on topics outside that distribution may degrade in quality.
 
-# Instantiate model architecture
-# model = SparseMind(Config(**cfg_dict))
-# model.load_state_dict(ckpt["model"])
-# model.eval()
+### Inherited from base
+
+- **Capacity**: 522M parameters is small. Complex multi-step reasoning is limited.
+- **Hallucination**: As with all autoregressive language models, generated code can look plausible but be subtly wrong (invented variable names, swapped function names, etc.). Always test before use.
+- **No safety alignment**: No RLHF, no refusal training. Should not be deployed in user-facing products without safety layers.
+
+### Privacy
+
+The training data was redacted for technical secrets (API keys, tokens, PEM keys) before training. Personal information beyond such secrets (style, opinions, project context) is **intentionally retained** because the purpose of personalization is to learn that style. Users should be aware that interacting with this model exposes them to the trained style of the original author.
+
+---
+
+## Environmental Considerations
+
+This fine-tune adds approximately 5 GPU-hours (A100) on top of the base model's training cost. The personalization approach is designed to be lightweight, making personalized models accessible without retraining from scratch.
+
+---
+
+## License
+
+Released under the **Apache 2.0** license. You are free to use, modify, and redistribute it, subject to the terms of the license.
+
+---
+
+## Citation
+
+```bibtex
+@misc{cofos_logo_v2_2026,
+  title  = {Cofos Logo v2: A Personalized Python Code Assistant},
+  author = {{AMEFORGE}},
+  year   = {2026},
+  url    = {https://huggingface.co/AMFORGE/cofos_logo_v2}
+}
 ```
+
+---
+
+## Contact
+
+For questions, collaborations, or access to the AMEFORGE SparseMind runtime:
+
+- **Organization**: AMEFORGE
+- **HuggingFace**: [@AMFORGE](https://huggingface.co/AMFORGE)
+
+---
+
+*Cofos Logo v2 is part of the broader Cofos model family by AMEFORGE. See the [AMFORGE organization page](https://huggingface.co/AMFORGE) for the base model, sibling variants, and ongoing work on the general-purpose foundation.*