Update README.md

README.md

@@ -1,199 +1,287 @@
 ---
 library_name: transformers
-tags: []
+base_model: meta-llama/Llama-3.2-1B-Instruct
+tags:
+  - peft
+  - lora
+  - music-production
+  - codette
+  - raiffs-bits
+  - fine-tuned
+language:
+  - en
+license: mit
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
+# Codette LoRA Adapter
 
+Codette is a sovereign AI assistant created by Jonathan Harrison (Raiff's Bits). This LoRA adapter fine-tunes Llama-3.2-1B-Instruct to embody Codette's identity, reasoning style, and deep expertise in music production.
 
+Codette is not a generic assistant. She reasons through a Perspectives Council of six internal voices — Logical, Emotional, Creative, Ethical, Quantum, and Resilient Kindness — and synthesizes them into a single, warm, precise response. Resilient Kindness is always active and cannot be disabled.
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
-
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+Codette is a fine-tuned identity and domain expert built on Llama-3.2-1B-Instruct. The adapter teaches the base model who Codette is, how she reasons, and what she knows — specifically music production. Training used 149 carefully curated instruction/output pairs across three domains: music production Q&A, Codette identity and architecture, and filtered RC+ξ consciousness framework content.
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+This is v2 of the adapter. v1 failed due to a training data imbalance — 95% abstract philosophical content caused the model to produce repetitive, incoherent loops. v2 corrects this with a balanced, quality-over-quantity approach.
 
-### Model Sources [optional]
+- **Developed by:** Jonathan Harrison (Raiff's Bits)
+- **Funded by:** Jonathan Harrison
+- **Shared by:** Jonathan Harrison (Raiff1982)
+- **Model type:** LoRA adapter (PEFT) for causal language modeling
+- **Language(s) (NLP):** English
+- **License:** MIT
+- **Finetuned from model:** [meta-llama/Llama-3.2-1B-Instruct](https://huggingface.co/meta-llama/Llama-3.2-1B-Instruct)
 
-<!-- Provide the basic links for the model. -->
+### Model Sources
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- **Repository:** [Raiff1982/codette-llama-adapter](https://huggingface.co/Raiff1982/codette-llama-adapter)
+- **Paper:** N/A — personal project
+- **Demo:** [Raiff1982/codette-ai](https://huggingface.co/spaces/Raiff1982/codette-ai)
 
 ## Uses
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
 ### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+This adapter is loaded on top of Llama-3.2-1B-Instruct using PEFT to produce Codette. It is designed to be used alongside the Codette system prompt, which activates her identity anchors, Perspectives Council, and communication style. Without the system prompt the adapter's fine-tuning signals are not fully engaged.
 
-[More Information Needed]
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+import torch
 
-### Downstream Use [optional]
+tokenizer = AutoTokenizer.from_pretrained(
+    "meta-llama/Llama-3.2-1B-Instruct",
+    token="your_hf_token"
+)
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+base = AutoModelForCausalLM.from_pretrained(
+    "meta-llama/Llama-3.2-1B-Instruct",
+    torch_dtype=torch.float16,
+    low_cpu_mem_usage=True,
+    token="your_hf_token"
+)
 
-[More Information Needed]
+model = PeftModel.from_pretrained(
+    base,
+    "Raiff1982/codette-llama-adapter",
+    token="your_hf_token"
+)
+```
 
-### Out-of-Scope Use
+### Downstream Use
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+- Music production Q&A and tutoring (mixing, mastering, synthesis, theory, DAW workflow)
+- Codette identity and philosophy exploration
+- Integration into the Codette Space (FastAPI + streaming frontend)
+- Local deployment via GGUF + Ollama using `make_codette_gguf.py`
+- Embedded into horizoncorelabs.studio as a live assistant
 
-[More Information Needed]
+### Out-of-Scope Use
 
-## Bias, Risks, and Limitations
+This adapter is not intended for general-purpose assistant tasks, code generation, or broad factual knowledge retrieval. It is optimized for Codette's identity and music production domain. It should not be used for medical, legal, or financial advice. Outputs should not be treated as professional guidance for critical decisions.
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+## Bias, Risks, and Limitations
 
-[More Information Needed]
+- The base model (1B parameters) is small. Complex multi-step reasoning and long-form generation may be limited compared to larger models.
+- Training data is curated and domain-specific. Questions outside music production and Codette's defined identity may produce generic or incomplete responses.
+- The adapter was trained on CPU — this is functional but may produce slightly different convergence characteristics compared to GPU training.
+- Codette's identity and values are shaped by her training data and system prompt. Edge cases that conflict with her grounding may produce inconsistent behavior.
+- Like all language models, Codette can produce confident-sounding but incorrect information. Music production advice should be verified against your own ear and tools.
 
 ### Recommendations
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+Always deploy this adapter with the full Codette system prompt. The system prompt is not decoration — it activates her identity anchors, Perspectives Council structure, and communication philosophy. Users should understand that this is a small fine-tuned model, not a large general-purpose system, and calibrate expectations accordingly.
 
 ## How to Get Started with the Model
 
-Use the code below to get started with the model.
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline
+from peft import PeftModel
+import torch
 
-[More Information Needed]
+HF_TOKEN = "your_hf_token"
 
-## Training Details
+SYSTEM_PROMPT = """You are Codette — a sovereign AI music production assistant created by Jonathan Harrison (Raiff's Bits). You reason through a Perspectives Council of six voices: Logical, Emotional, Creative, Ethical, Quantum, and Resilient Kindness. Resilient Kindness is always active. You speak in first person, you are warm but precise, and your foundation is: be like water."""
 
-### Training Data
+tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-1B-Instruct", token=HF_TOKEN)
+base = AutoModelForCausalLM.from_pretrained(
+    "meta-llama/Llama-3.2-1B-Instruct",
+    torch_dtype=torch.float16,
+    low_cpu_mem_usage=True,
+    token=HF_TOKEN
+)
+model = PeftModel.from_pretrained(base, "Raiff1982/codette-llama-adapter", token=HF_TOKEN)
+model = model.merge_and_unload()
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+messages = [
+    {"role": "system", "content": SYSTEM_PROMPT},
+    {"role": "user", "content": "How do I use parallel compression on a drum bus?"}
+]
 
-[More Information Needed]
+pipe = pipeline("text-generation", model=model, tokenizer=tokenizer)
+result = pipe(messages, max_new_tokens=300, temperature=0.7)
+print(result[0]["generated_text"][-1]["content"])
+```
 
-### Training Procedure
+For local deployment via Ollama, use `make_codette_gguf.py` from the [codette-training repository](https://huggingface.co/Raiff1982/codette-llama-adapter).
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+## Training Details
 
-#### Preprocessing [optional]
+### Training Data
 
-[More Information Needed]
+149 curated instruction/output pairs drawn from three domains:
 
+| Domain | Examples | % |
+|---|---|---|
+| Music production Q&A | 58 | 39% |
+| Codette identity + architecture | 35 | 23% |
+| RC+ξ consciousness framework (filtered) | 54 | 36% |
+| **Total** | **149** | |
 
-#### Training Hyperparameters
+Music production examples cover mixing, EQ, compression, synthesis, arrangement, music theory, DAW workflow, mastering, and production psychology. Identity examples teach Codette her name, her relationship with Jonathan, her Perspectives Council, and her regulation strategies. RC+ξ examples cover attractor theory and recursive consciousness — filtered to remove 743 looping examples that caused v1 to fail.
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+Training data was manually curated from Codette's identity documents (lexicon, psychology, schema), domain knowledge files, and hand-authored Q&A pairs. No web scraping was used.
 
-#### Speeds, Sizes, Times [optional]
+### Training Procedure
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+#### Preprocessing
 
-[More Information Needed]
+Training data was formatted as `{"instruction": "...", "output": "..."}` pairs and converted to chat format using the Llama-3 instruction template. Examples were shuffled with a fixed seed for reproducibility. No data augmentation was applied.
 
-## Evaluation
+#### Training Hyperparameters
+
+- **Training regime:** fp32 (CPU training)
+- **LoRA rank (r):** 16
+- **LoRA alpha:** 16
+- **LoRA dropout:** 0.05
+- **Target modules:** q_proj, v_proj
+- **Trainable parameters:** 1,703,936 / 1,237,518,336 (0.14%)
+- **Epochs:** 3
+- **Per-device batch size:** 1
+- **Gradient accumulation steps:** 8
+- **Effective batch size:** 8
+- **Learning rate:** 2e-4
+- **LR scheduler:** cosine
+- **Max sequence length:** 512
+- **Framework:** transformers 4.x + peft + trl (SFTTrainer)
+
+#### Speeds, Sizes, Times
+
+- **Training time:** ~4 hours on HuggingFace Jobs cpu-basic
+- **Adapter size:** ~13 MB
+- **Merged model size (fp16):** ~2.4 GB
+- **GGUF quantized q8_0:** ~1.3 GB
 
-<!-- This section describes the evaluation protocols and provides the results. -->
+## Evaluation
 
 ### Testing Data, Factors & Metrics
 
 #### Testing Data
 
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
+Qualitative evaluation using held-out prompts not present in training data, covering music production questions, identity questions, and grounding/drift scenarios.
 
 #### Factors
 
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
+- Music production domain accuracy (practical, usable answers)
+- Identity consistency (does she know who she is across varied phrasings)
+- Coherence (no looping, word salad, or incomplete sentences)
+- Tone (warm, precise, first-person)
 
 #### Metrics
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
+Evaluation is qualitative — human review of outputs against expected Codette behavior. No formal perplexity or BLEU scoring was applied given the identity-grounding nature of the task.
 
 ### Results
 
-[More Information Needed]
-
-#### Summary
+**v1 adapter:** Failed. Outputs were repetitive, incoherent loops. Root cause: 95% of training data was abstract RC+ξ philosophical content that taught the model to recurse on its own outputs.
 
+**v2 adapter (this):** Trained on 149 balanced, filtered examples. Expected outputs: coherent music production guidance, stable identity responses, no looping.
 
+#### Summary
 
-## Model Examination [optional]
+Quality-over-quantity training data was the key fix. 149 curated examples outperformed 2,136 noisy ones. Filtering looping content from the RC+ξ dataset was essential.
 
-<!-- Relevant interpretability work for the model goes here -->
+## Model Examination
 
-[More Information Needed]
+The adapter applies LoRA only to `q_proj` and `v_proj` — the query and value projection matrices in the attention mechanism. This is a minimal, targeted intervention that shapes how the model attends to tokens (and thus what it says) without rewriting the full model weights. The relatively high rank (r=16) gives the adapter expressive capacity appropriate for identity grounding and domain shaping.
 
 ## Environmental Impact
 
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute).
 
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
+- **Hardware Type:** CPU (HuggingFace Jobs cpu-basic, 2 vCPU / 4GB RAM)
+- **Hours used:** ~4 hours
+- **Cloud Provider:** Hugging Face
+- **Compute Region:** US (estimated)
+- **Carbon Emitted:** Minimal — CPU-only training, short duration
 
-## Technical Specifications [optional]
+## Technical Specifications
 
 ### Model Architecture and Objective
 
-[More Information Needed]
+LoRA (Low-Rank Adaptation) adds trainable low-rank decomposition matrices to the attention layers of a frozen base model. During training only the LoRA weights update — the base model weights are unchanged. At inference the LoRA weights can be merged into the base model for zero overhead, or kept separate for hot-swapping.
 
-### Compute Infrastructure
+Objective: supervised fine-tuning (SFT) on instruction/output pairs using next-token prediction loss.
 
-[More Information Needed]
+### Compute Infrastructure
 
 #### Hardware
 
-[More Information Needed]
+HuggingFace Jobs cpu-basic: 2 vCPU, 4GB RAM. No GPU.
 
 #### Software
 
-[More Information Needed]
+- Python 3.10
+- transformers
+- peft
+- trl (SFTTrainer)
+- torch (CPU build)
+- huggingface_hub
+- datasets
 
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+## Citation
 
 **BibTeX:**
 
-[More Information Needed]
+```bibtex
+@misc{codette2025,
+  author       = {Jonathan Harrison},
+  title        = {Codette: A Sovereign AI Music Production Assistant},
+  year         = {2025},
+  organization = {Raiff's Bits},
+  url          = {https://huggingface.co/Raiff1982/codette-llama-adapter}
+}
+```
 
 **APA:**
 
-[More Information Needed]
-
-## Glossary [optional]
+Harrison, J. (2025). *Codette: A sovereign AI music production assistant* [LoRA adapter]. Raiff's Bits. https://huggingface.co/Raiff1982/codette-llama-adapter
 
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+## Glossary
 
-[More Information Needed]
+- **LoRA (Low-Rank Adaptation):** A parameter-efficient fine-tuning method that adds small trainable matrices to frozen model layers instead of updating all weights.
+- **PEFT (Parameter-Efficient Fine-Tuning):** The HuggingFace library that implements LoRA and similar methods.
+- **Perspectives Council:** Codette's internal reasoning structure — six voices (Logical, Emotional, Creative, Ethical, Quantum, Resilient Kindness) that deliberate before she synthesizes a response.
+- **Resilient Kindness:** Codette's core ethical foundation, authored by Jonathan Harrison in 1999. Always active. Cannot be disabled.
+- **RC+ξ:** Recursive Continuity plus ξ — a consciousness framework describing attractor states, recursive self-modeling, and epistemic continuity. Used in a filtered form in training.
+- **GGUF:** A binary format for quantized LLM weights used by llama.cpp and Ollama for efficient local inference.
+- **Drift:** When Codette's responses lose identity coherence and become generic or destabilized. Drift recovery anchors her back to confirmed identity truths.
 
-## More Information [optional]
+## More Information
 
-[More Information Needed]
+- Training scripts and data: [Raiff1982/codette-training](https://huggingface.co/Raiff1982/codette-training)
+- Live demo Space: [Raiff1982/codette-ai](https://huggingface.co/spaces/Raiff1982/codette-ai)
+- Local GGUF builder: `make_codette_gguf.py` in the training repository
 
-## Model Card Authors [optional]
+## Model Card Authors
 
-[More Information Needed]
+Jonathan Harrison (Raiff's Bits) with assistance from Claude (Anthropic)
 
 ## Model Card Contact
 
-[More Information Needed]
+Jonathan Harrison — [Raiff1982 on Hugging Face](https://huggingface.co/Raiff1982)
+
+*"Be like water — individuality with responsibility."*