Enhanced model card with comprehensive documentation

README.md

@@ -1,25 +1,265 @@
 ---
 license: apache-2.0
 base_model: mistralai/Mistral-Small-Instruct-2409
-tags:
-- insurance
-- actuarial
-- accounting
-- legal
-- lora
-- peft
-language:
-- en
 library_name: peft
+pipeline_tag: text-generation
+language:
+  - en
+tags:
+  - insurance
+  - actuarial
+  - life-insurance
+  - health-insurance
+  - accounting
+  - cpa
+  - cfa
+  - legal
+  - bar-exam
+  - finance
+  - wealth-management
+  - estate-planning
+  - mistral
+  - lora
+  - qlora
+  - peft
+  - conversational
+datasets:
+  - custom
+model-index:
+  - name: morbi-v022
+    results:
+      - task:
+          type: text-generation
+          name: Text Generation
+        metrics:
+          - type: loss
+            value: 0.117
+            name: Eval Loss
+---
+
+<div align="center">
+
+# Morbi v0.2.2
+
+### Professional Domain Expert for Insurance, Actuarial Science, Accounting & Legal
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Base Model](https://img.shields.io/badge/Base-Mistral--Small--22B-orange)](https://huggingface.co/mistralai/Mistral-Small-Instruct-2409)
+[![PEFT](https://img.shields.io/badge/Method-QLoRA-green)](https://github.com/huggingface/peft)
+
+*A specialized AI assistant trained on 19,000+ examples across insurance, actuarial science, accounting (CPA/CFA), and legal (Bar Exam) domains.*
+
+[HEIR Platform](https://heir.es) | [Documentation](https://heir.es/docs) | [API Access](https://heir.es/api)
+
+</div>
+
+---
+
+## Model Description
+
+**Morbi** is a domain-specialized large language model built for professional financial services applications. Named after the actuarial term for mortality/morbidity analysis, Morbi provides expert-level assistance across interconnected professional domains.
+
+| Attribute | Value |
+|-----------|-------|
+| **Developer** | [HEIR](https://heir.es) |
+| **Model Type** | Causal Language Model (LoRA Adapter) |
+| **Base Model** | [Mistral-Small-Instruct-2409](https://huggingface.co/mistralai/Mistral-Small-Instruct-2409) (22B parameters) |
+| **Language** | English |
+| **License** | Apache 2.0 |
+| **Version** | 0.2.2 (January 2026) |
+
+### What's New in v0.2.2
+
+- **Accounting Domain**: Added CPA exam topics (FAR, AUD, REG, BEC), GAAP/IFRS standards, and financial calculations
+- **Legal Domain**: Added California Bar Exam subjects, UCC Article 2, and case analysis capabilities
+- **Improved Training**: Lower learning rate with cosine schedule for better convergence
+
+---
+
+## Intended Uses
+
+### Primary Use Cases
+
+| Domain | Applications |
+|--------|--------------|
+| **Insurance Advisory** | Product recommendations, policy analysis, claims guidance, underwriting support |
+| **Actuarial Analysis** | Mortality calculations, reserve estimates, premium projections, risk assessment |
+| **Accounting Support** | CPA exam prep, GAAP/IFRS guidance, financial statement analysis, audit procedures |
+| **Legal Research** | Bar exam preparation, contract analysis, legal concept explanation, case briefing |
+| **Wealth Management** | Estate planning, tax implications, beneficiary strategies, asset protection |
+
+### Out-of-Scope Uses
+
+- **Not for**: Medical diagnosis, investment advice requiring fiduciary duty, legal representation
+- **Not a substitute for**: Licensed professionals (CPAs, attorneys, actuaries, financial advisors)
+- **Should not be used for**: High-stakes decisions without professional verification
+
+---
+
+## Domain Expertise
+
+### Insurance & Actuarial Science
+
+```
+Life Insurance          Health Insurance         Actuarial Methods
+├── Term Life           ├── Medical              ├── Mortality Tables (CSO, VBT)
+├── Whole Life          ├── Dental/Vision        ├── Interest Theory
+├── Universal Life      ├── Disability (STD/LTD) ├── Life Contingencies
+├── Variable Life       ├── Long-Term Care       ├── Reserve Calculations
+├── Indexed Products    └── Medicare/Medicaid    ├── Premium Development
+└── Annuities                                    └── Experience Studies
+```
+
+**Sample Topics**: Non-forfeiture options, policy loans, 1035 exchanges, HIPAA compliance, NAIC regulations, SOA exam concepts, risk classification, reinsurance structures.
+
+### Accounting & Finance (CPA/CFA)
+
+| CPA Exam Section | Key Topics |
+|------------------|------------|
+| **FAR** | Financial statements, leases, bonds, consolidations, governmental accounting |
+| **AUD** | Audit procedures, internal controls, sampling, ethics, reporting |
+| **REG** | Individual/corporate taxation, business law, ethics |
+| **BEC** | Economics, IT, operations, financial management, cost accounting |
+
+| CFA Topics | Coverage |
+|------------|----------|
+| Ethics & Standards | Code of Ethics, GIPS |
+| Quantitative Methods | Time value, statistics, probability |
+| Financial Analysis | Ratios, cash flow, earnings quality |
+| Corporate Finance | NPV, IRR, WACC, capital structure |
+
+### Legal (Bar Exam)
+
+| Subject | Key Concepts |
+|---------|--------------|
+| **Contracts** | Formation, consideration, breach, remedies, UCC Article 2 |
+| **Evidence** | Hearsay exceptions, privileges, relevance, authentication |
+| **Torts** | Negligence, strict liability, intentional torts, damages |
+| **Constitutional Law** | Due process, equal protection, commerce clause, amendments |
+| **Civil Procedure** | Jurisdiction, Erie doctrine, pleading, discovery, res judicata |
+| **Criminal Law** | Actus reus, mens rea, defenses, 4th/5th/6th Amendment |
+| **Real Property** | Estates, easements, covenants, recording acts, landlord-tenant |
+
+---
+
+## Training Details
+
+### Training Data
+
+| Category | Examples | Percentage |
+|----------|----------|------------|
+| Insurance & Actuarial | 19,080 | 98.5% |
+| Accounting (CPA/CFA) | ~150 | 0.8% |
+| Legal (Bar Exam) | ~145 | 0.7% |
+| **Total Training** | **19,374** | 100% |
+| Validation Set | 1,068 | - |
+
+**Data Sources**:
+- Proprietary insurance training materials
+- Actuarial exam preparation content
+- CPA/CFA study guides and practice questions
+- California Bar Exam past papers and study materials
+- UCC Article 2 and Black's Law Dictionary excerpts
+
+### Training Procedure
+
+| Hyperparameter | Value |
+|----------------|-------|
+| Learning Rate | 5e-5 |
+| LR Schedule | Cosine with warmup |
+| Warmup Steps | 50 |
+| Batch Size | 1 (gradient accumulation: 8) |
+| Effective Batch Size | 8 |
+| Max Steps | 2,000 |
+| Max Sequence Length | 2,048 |
+| Weight Decay | 0.01 |
+| Gradient Clipping | 0.5 |
+
+### LoRA Configuration
+
+| Parameter | Value |
+|-----------|-------|
+| Rank (r) | 32 |
+| Alpha | 64 |
+| Dropout | 0.05 |
+| Target Modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
+| Trainable Parameters | ~763M |
+
+### Quantization
+
+| Setting | Value |
+|---------|-------|
+| Method | QLoRA (4-bit) |
+| Compute Dtype | bfloat16 |
+| Quant Type | nf4 |
+| Double Quant | True |
+
+### Hardware & Compute
+
+| Resource | Specification |
+|----------|---------------|
+| GPU | NVIDIA A100-SXM4-80GB |
+| Training Time | 8.2 hours (29,394 seconds) |
+| Platform | RunPod |
+
 ---
 
-# Morbi v0.2.2 LoRA Adapter
+## Evaluation
+
+### Quantitative Results
+
+| Metric | Value |
+|--------|-------|
+| **Final Training Loss** | 1.269 |
+| **Evaluation Loss** | 0.117 |
+| Training Samples/Second | 0.544 |
+
+### Qualitative Examples
+
+<details>
+<summary><b>Insurance Example</b></summary>
+
+**Prompt**: What are the key differences between term and whole life insurance?
+
+**Response**: Term life insurance provides pure death benefit protection for a specified period (10, 20, or 30 years) with no cash value accumulation. Premiums are lower initially but increase upon renewal. Whole life insurance provides lifetime coverage with guaranteed level premiums and builds cash value on a tax-deferred basis. The cash value can be accessed through policy loans or withdrawals. Key considerations include: (1) affordability vs. permanence, (2) need for cash value accumulation, (3) estate planning objectives, and (4) the insured's age and health status...
+
+</details>
+
+<details>
+<summary><b>Actuarial Example</b></summary>
+
+**Prompt**: Calculate the present value of a life annuity-due for a person age 65.
+
+**Response**: To calculate the present value of a life annuity-due (ä_65), we use the formula: ä_x = Σ(v^k × k_p_x) for k=0 to ω-x, where v = 1/(1+i) is the discount factor, k_p_x is the probability of surviving k years, and ω is the limiting age. Using the 2017 CSO mortality table at 4% interest...
+
+</details>
+
+<details>
+<summary><b>Accounting Example</b></summary>
+
+**Prompt**: When does UCC Article 2 apply instead of common law for contracts?
+
+**Response**: UCC Article 2 applies to contracts for the sale of goods, while common law governs contracts for services, real estate, and intangibles. Key distinctions: (1) Goods are defined as movable, tangible personal property at the time of identification to the contract; (2) Mixed contracts (goods + services) use the predominant purpose test; (3) UCC provides different rules for offer/acceptance (battle of forms §2-207), statute of frauds ($500 threshold), and warranties...
 
-LoRA adapter for Mistral-Small, trained on insurance, accounting, and legal data.
+</details>
+
+<details>
+<summary><b>Legal Example</b></summary>
+
+**Prompt**: Explain the hearsay rule and its major exceptions.
+
+**Response**: Hearsay is an out-of-court statement offered to prove the truth of the matter asserted (FRE 801). It is generally inadmissible because the declarant was not under oath and cannot be cross-examined. Major exceptions include: (1) Present sense impression (FRE 803(1)); (2) Excited utterance (FRE 803(2)); (3) State of mind (FRE 803(3)); (4) Medical diagnosis (FRE 803(4)); (5) Business records (FRE 803(6)); (6) Former testimony (FRE 804(b)(1)); (7) Dying declaration (FRE 804(b)(2))...
+
+</details>
+
+---
 
 ## Usage
 
+### Quick Start
+
 ```python
+import torch
 from transformers import AutoModelForCausalLM, AutoTokenizer
 from peft import PeftModel
 
@@ -27,16 +267,170 @@ from peft import PeftModel
 base_model = AutoModelForCausalLM.from_pretrained(
     "mistralai/Mistral-Small-Instruct-2409",
     torch_dtype=torch.bfloat16,
-    device_map="auto"
+    device_map="auto",
+    trust_remote_code=True
 )
 
 # Load LoRA adapter
 model = PeftModel.from_pretrained(base_model, "h3ir/morbi-v022-lora")
 tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-Small-Instruct-2409")
+
+# Generate response
+prompt = """<s>[INST] You are Morbi, an expert AI assistant specializing in insurance, actuarial science, accounting, and legal matters.
+
+What is the difference between GAAP and IFRS for revenue recognition? [/INST]"""
+
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+outputs = model.generate(
+    **inputs,
+    max_new_tokens=512,
+    temperature=0.7,
+    do_sample=True,
+    top_p=0.9
+)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+### Prompt Format
+
+Morbi uses the Mistral instruction format with a specialized system prompt:
+
+```
+<s>[INST] You are Morbi, an expert AI assistant specializing in insurance, actuarial science, accounting, and legal matters.
+
+{your question here} [/INST]
 ```
 
-## Training
+### With vLLM
+
+```python
+from vllm import LLM, SamplingParams
+from vllm.lora.request import LoRARequest
+
+llm = LLM(
+    model="mistralai/Mistral-Small-Instruct-2409",
+    enable_lora=True,
+    max_lora_rank=32
+)
+
+sampling_params = SamplingParams(temperature=0.7, max_tokens=512)
+
+outputs = llm.generate(
+    prompts,
+    sampling_params,
+    lora_request=LoRARequest("morbi", 1, "h3ir/morbi-v022-lora")
+)
+```
+
+### With Text Generation Inference (TGI)
+
+```bash
+# Download and merge adapter first, or use TGI's LoRA support
+docker run --gpus all -p 8080:80 \
+  -v $PWD/data:/data \
+  ghcr.io/huggingface/text-generation-inference:latest \
+  --model-id mistralai/Mistral-Small-Instruct-2409 \
+  --lora-adapters h3ir/morbi-v022-lora
+```
+
+---
+
+## Technical Specifications
+
+### Memory Requirements
+
+| Precision | VRAM Required |
+|-----------|---------------|
+| bfloat16 (full) | ~44 GB |
+| 8-bit quantized | ~24 GB |
+| 4-bit quantized | ~14 GB |
+| 4-bit + LoRA adapter | ~16 GB |
+
+### Supported Backends
+
+- Transformers + PEFT
+- vLLM (with LoRA support)
+- Text Generation Inference
+- llama.cpp (after conversion)
+- Ollama (after conversion)
+
+---
+
+## Limitations & Risks
+
+### Known Limitations
+
+1. **Domain Imbalance**: Insurance/actuarial data (98.5%) significantly outweighs accounting (0.8%) and legal (0.7%) data
+2. **Jurisdiction**: Legal training focuses on U.S. law (California Bar Exam); may not apply to other jurisdictions
+3. **Temporal**: Training data has a knowledge cutoff; regulations and laws change
+4. **Calculations**: While trained on calculation examples, complex numerical computations should be verified
+
+### Potential Biases
+
+- May reflect biases present in insurance industry practices
+- Legal analysis may favor common law interpretations over civil law systems
+- Financial calculations assume U.S. regulatory frameworks
+
+### Mitigation Recommendations
+
+- Always verify critical calculations with qualified professionals
+- Cross-reference legal advice with licensed attorneys
+- Use for educational and research purposes; not as sole decision-making tool
+
+---
+
+## Environmental Impact
+
+| Metric | Value |
+|--------|-------|
+| Hardware | 1x NVIDIA A100-80GB |
+| Training Duration | 8.2 hours |
+| Estimated Energy | ~3.3 kWh |
+| Estimated CO2 | ~1.3 kg CO2eq* |
+
+*Estimate based on U.S. average grid intensity
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v0.2.2 | Jan 2026 | Added accounting (CPA/CFA) and legal (Bar Exam) domains |
+| v0.2.1 | Jan 2026 | Improved training with cosine LR schedule, lower learning rate |
+| v0.2.0 | Jan 2026 | Initial release with insurance and actuarial focus |
+
+---
+
+## Citation
+
+```bibtex
+@misc{morbi-v022,
+  author = {HEIR},
+  title = {Morbi v0.2.2: Professional Domain Expert for Insurance, Actuarial Science, Accounting \& Legal},
+  year = {2026},
+  month = {January},
+  publisher = {Hugging Face},
+  howpublished = {\url{https://huggingface.co/h3ir/morbi-v022-lora}},
+  note = {LoRA adapter for Mistral-Small-Instruct-2409}
+}
+```
+
+---
+
+## Contact & Support
+
+- **Website**: [https://heir.es](https://heir.es)
+- **Documentation**: [https://heir.es/docs](https://heir.es/docs)
+- **Issues**: [GitHub Issues](https://github.com/heir-es/morbi/issues)
+- **Email**: support@heir.es
+
+---
+
+<div align="center">
+
+**Built with care by [HEIR](https://heir.es)**
+
+*Empowering wealth management through AI*
 
-- Base: Mistral-Small-Instruct-2409 (22B)
-- Method: QLoRA (r=32, alpha=64)
-- Examples: 19,374 (insurance, accounting, legal)
+</div>