Upload Clinical Agent Transformer mcp-full artifacts

README.md

@@ -32,6 +32,130 @@ This upload contains the final trained package from the Modal checkpoint volume:
 
 The `trainable_state.pt` file is important because this project modifies the LLaMA architecture with custom MLA, MoE, recurrent, QK-Norm, post-norm, and MTP components. The adapter files alone do not represent every custom trainable module.
 
+## Repository Layout
+
+```text
+.
+├── README.md
+├── metrics.json
+├── training_config.json
+├── training_history.csv
+├── losses.csv
+├── loss_curve.png
+├── train_validation_loss.png
+├── validation_perplexity.png
+├── learning_rate.png
+├── trainable_state.pt
+└── model/
+    ├── adapter_config.json
+    └── adapter_model.safetensors
+```
+
+## How To Clone
+
+```bash
+git lfs install
+git clone https://huggingface.co/madan2248c/clinical-agent-transformer-llama-31-8b
+cd clinical-agent-transformer-llama-31-8b
+```
+
+The repository uses Git LFS because `trainable_state.pt` is large.
+
+## How To Use This Model Package
+
+This repository is not a standalone vanilla Hugging Face `AutoModelForCausalLM.from_pretrained(...)` checkpoint. It is a Clinical Agent Transformer package with:
+
+1. the original gated base model dependency, `meta-llama/Llama-3.1-8B-Instruct`;
+2. PEFT/LoRA adapter weights in `model/`;
+3. custom architecture trainable weights in `trainable_state.pt`;
+4. project code that applies the architecture surgery before loading the trained state.
+
+To use it correctly, clone this project codebase and load the model through the same architecture path used during training.
+
+### Install Runtime Dependencies
+
+```bash
+pip install torch transformers==4.52.4 peft accelerate bitsandbytes huggingface_hub
+```
+
+You must also have access to the gated LLaMA base model and be logged in:
+
+```bash
+huggingface-cli login
+```
+
+### Example Loading Code
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+from peft import PeftModel
+
+from llama_surgery.config import AdapterConfig, SurgeryConfig, TrainingConfig
+from llama_surgery.model import load_model, load_tokenizer
+
+repo_id = "madan2248c/clinical-agent-transformer-llama-31-8b"
+hf_token = "YOUR_HF_TOKEN"
+
+config = TrainingConfig(
+    model_name="meta-llama/Llama-3.1-8B-Instruct",
+    hf_cache_dir="./hf_cache",
+    adapter=AdapterConfig(
+        enabled=True,
+        adapter_name="clinical_agent_adapter",
+        r=8,
+        lora_alpha=32,
+        lora_dropout=0.05,
+        target_modules=("q_proj", "k_proj", "v_proj", "o_proj"),
+    ),
+    surgery=SurgeryConfig(
+        use_mla=True,
+        use_qk_norm=True,
+        use_post_norm=True,
+        use_moe_layers=True,
+        use_recurrent_layers=True,
+        use_mtp_head=True,
+    ),
+)
+
+tokenizer = load_tokenizer(config, hf_token)
+model = load_model(config, hf_token)
+
+state_path = hf_hub_download(repo_id=repo_id, filename="trainable_state.pt", token=hf_token)
+state = torch.load(state_path, map_location="cpu")
+model.load_state_dict(state, strict=False)
+
+model = PeftModel.from_pretrained(model, repo_id, subfolder="model", token=hf_token)
+model.eval()
+
+prompt = "Evaluate ceftriaxone for community-acquired pneumonia in an adult with normal renal function."
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+
+with torch.no_grad():
+    output = model.generate(
+        **inputs,
+        max_new_tokens=256,
+        temperature=0.2,
+        do_sample=False,
+    )
+
+print(tokenizer.decode(output[0], skip_special_tokens=True))
+```
+
+### Important Loading Note
+
+The architecture surgery must be applied before loading `trainable_state.pt`. If someone loads only the adapter folder, they will miss the custom MLA, MoE, recurrent, post-norm, QK-Norm, and MTP trained components.
+
+## Training Artifacts
+
+The metrics and graph files can be used to inspect the training behavior:
+
+- `metrics.json`: final run metrics and architecture inspection.
+- `training_history.csv`: train loss, validation loss, validation perplexity, and learning rate per recorded step.
+- `train_validation_loss.png`: train/validation loss curve.
+- `validation_perplexity.png`: validation perplexity curve.
+- `learning_rate.png`: learning-rate schedule.
+
 ## Training Procedure
 
 The model was trained in two stages: