Update model card: Legal Agent Council architecture, v24 corpus stats, comprehensive overview

README.md

@@ -10,6 +10,10 @@ tags:
 - parental-alienation
 - bert
 - modernbert
+- legal-agent-council
+- multi-agent
+- retrieval
+- classification
 datasets:
 - Roderick3rd/OhioCustodyBERT-corpus
 pipeline_tag: text-classification
@@ -17,82 +21,220 @@ pipeline_tag: text-classification
 
 # OhioCustodyBERT
 
-**Ohio Family Law & Custody Specialist** — Fine-tuned ModernBERT for Ohio family law, child custody, and parental alienation analysis.
+**A domain-specific legal AI system for Ohio family law, child custody, and parental alienation.** Built from the ground up with over 13,000 curated training examples from Ohio statutes, appellate decisions, Supreme Court cases, and legal reference materials.
 
-## Model Overview
+> ⚠️ **This is a legal research tool, not legal advice.** Always consult a licensed attorney for legal matters.
+
+---
+
+## Why This Exists
+
+The Ohio family court system processes thousands of custody cases annually. Parents — especially pro se litigants — face a legal system built on decades of case law, statutes, and procedural rules that are nearly impossible to navigate without expensive legal counsel.
+
+**OhioCustodyBERT aims to democratize access to Ohio family law knowledge** by providing AI models trained specifically on:
+- Ohio Revised Code (ORC) Chapter 3109 and related family law statutes
+- Ohio Administrative Code (OAC) custody and child welfare rules
+- Appellate court decisions on custody, parental alienation, and visitation
+- US Supreme Court precedent on parental rights (Santosky, Stanley, Troxel)
+- Ohio Supreme Court reports, bench cards, and practice guides
+
+---
+
+## The Legal Agent Council
+
+OhioCustodyBERT is not a single model — it's a **multi-agent legal reasoning system** where specialized AI models work together to provide comprehensive legal analysis. Each model is fine-tuned on the same curated Ohio family law corpus, but serves a different role.
+
+### Architecture
+
+```
+User Query
+    │
+    ▼
+┌─────────────────────────────┐
+│  ① BERT Retriever           │ ← OhioCustodyBERT (this model)
+│  Finds relevant statutes,   │    ModernBERT-base, 149.7M params
+│  case law, and rules        │
+└──────────┬──────────────────┘
+           │ Retrieved context
+           ▼
+┌─────────────────────────────┐
+│  ② Statute Agent            │ ← OhioCustodyBERT-Qwen3.5-9B (LoRA)
+│  "What does the law say?"   │    Analyzes applicable statutes
+├─────────────────────────────┤
+│  ③ Case Law Agent           │ ← Same base, different prompt
+│  "What have courts held?"   │    Finds binding precedent
+├─────────────────────────────┤
+│  ④ Procedure Agent          │ ← Qwen3-30B-A3B (MoE, planned)
+│  "Was due process followed?"│    Procedural compliance check
+├─────────────────────────────┤
+│  ⑤ Adversary Agent          │ ← OhioCustodyBERT-Qwen3.5-9B (LoRA)
+│  "What's the other side?"   │    Steel-mans the opposition
+└──────────┬──────────────────┘
+           │ All analyses
+           ▼
+┌─────────────────────────────┐
+│  ⑥ Synthesis Judge          │ ← QwQ-32B (deep reasoning)
+│  Weighs all perspectives,   │    Produces final analysis with
+│  resolves conflicts         │    confidence scoring
+└──────────┬──────────────────┘
+           │ Final analysis
+           ▼
+┌─────────────────────────────┐
+│  ⑦ BERT Verifier            │ ← OhioCustodyBERT (this model)
+│  Fact-checks citations,     │    Catches hallucinated case law
+│  validates statute refs     │    and incorrect statute numbers
+└─────────────────────────────┘
+```
+
+### Why Multiple Models?
+
+**Same data, different architectures = meaningful consensus.** When all models agree on a legal analysis, confidence is high. When they disagree, the disagreement reveals where the law is ambiguous or the facts need closer examination — which is exactly what a good lawyer would identify.
+
+---
+
+## Models in This System
+
+| Model | HuggingFace | Role | Architecture |
+|-------|-------------|------|-------------|
+| **OhioCustodyBERT** | [This repo](https://huggingface.co/Roderick3rd/OhioCustodyBERT) | Retriever + Verifier | ModernBERT-base (149.7M) |
+| **OhioCustodyBERT-Qwen3.5-9B** | [Adapter repo](https://huggingface.co/Roderick3rd/OhioCustodyBERT-Qwen3.5-9B) | Generative Agents | Qwen3.5-9B + LoRA |
+| **Training Corpus** | [Dataset](https://huggingface.co/datasets/Roderick3rd/OhioCustodyBERT-corpus) | All training data | 13,346 SFT pairs + raw corpus |
+
+---
+
+## This Model: ModernBERT Retriever + Verifier
+
+### What It Does
+- **Semantic retrieval**: Find the most relevant statutes, rules, and case law for a given legal question
+- **Classification**: Identify legal issues (custody type, parental alienation indicators, due process violations)
+- **NER**: Extract legal entities (judge names, case citations, statute references)
+- **Citation verification**: Validate that LLM-generated citations point to real cases and statutes
+
+### Model Details
 
 | | |
 |---|---|
-| **Base Model** | ModernBERT-base (149.7M params) |
+| **Base** | ModernBERT-base (149.7M params) |
 | **Domain** | Ohio family law, child custody, parental alienation |
-| **Training** | Kaggle 2×T4, 864 examples, 3 epochs, bf16 |
-| **Loss** | 1.01 → 0.84 (final eval: 0.91) |
-| **Version** | v0.1 (v0.2 in progress) |
+| **Training** | Masked Language Modeling on curated Ohio legal corpus |
+| **Version** | v0.1 (v0.2 training in progress — full corpus) |
+| **License** | Apache 2.0 |
 
-## Part of the Legal Agent Council
+---
 
-OhioCustodyBERT is one of **4 models** in a multi-agent legal council architecture. All models are fine-tuned on the **identical curated Ohio family law corpus**, enabling consensus-based legal analysis where different architectures cross-validate each other.
+## Training Corpus (v24 — March 2026)
 
-| Model | Role in Council |
-|---|---|
-| **OhioCustodyBERT** ← this model | Retriever + Verifier (classification, NER, fact-checking) |
-| Qwen3.5-9B (LoRA) | Specialist Agents (statute, case law, adversary) |
-| Qwen3-30B-A3B (LoRA) | Procedure Agent (sparse expert routing) |
-| Qwen3.5-27B-Claude-Opus-Distilled (Q8_0) | Synthesis Judge (Claude reasoning distilled, 28 GB) |
-
-**Principle**: Same data, different architectures = meaningful consensus. When all 4 models agree, confidence is high. When they disagree, the disagreement reveals where the law is ambiguous or the facts need closer examination.
-
-## Training Corpus (v0.2 — March 2026)
-
-### Court Opinions — 469 deduplicated, full-text opinions (14.9 MB)
-| Source | Count | Key Cases |
-|---|---|---|
-| Ohio Court of Appeals | 149 | PA, custody, GAL, DV, contempt, visitation |
-| Ohio Supreme Court | 199 | Shearer, Felton, In re Murray, In re Bonfield |
-| US Supreme Court | 121 | Santosky v. Kramer, Stanley v. Illinois, Troxel v. Granville |
-
-### SFT Training Data (audited March 12, 2026)
-| Dataset | Records | Status |
-|---|---|---|
-| v19 curated pairs | 916 train / 76 valid | ✅ Audited (77% clean) |
-| Opinion-generated pairs (glm-5:cloud) | 480 (469/469 opinions) | ✅ Complete (96.6% clean) |
-| Phase 2 strategy pairs | 177 | ✅ Ready |
-| OFR report pairs (glm-5:cloud) | 115 (117 reports) | ✅ Complete |
-| **Packaged total** | **1,536 train / 115 valid** | **1,651 unique pairs** |
-
-### Cloud-Scraped Corpus (March 12, 2026)
+All models in the Legal Agent Council are trained on the same curated corpus:
+
+### SFT Training Data — 13,346 unique pairs
+
+| Source | Pairs | Description |
+|--------|-------|-------------|
+| Ohio Revised Code | 4,145 | R.C. 3109, 2919, 2151, 3111, 3127, 3105 — statutes on custody, DV, juvenile, paternity, UCCJEA, divorce |
+| Ohio Administrative Code | 3,849 | OAC rules on child welfare, custody evaluation, court procedures |
+| Curated Q&A | 2,288 | Hand-audited pairs from opinion analysis, case strategy, verified datasets |
+| CourtListener opinions | 1,374 | Ohio appellate court custody and family law decisions |
+| Reference materials | 732 | Ohio SC task force reports, bench cards, GAL guides, custody evaluator toolkit |
+| Targeted opinions | 560 | Ohio appellate, Ohio SC, and SCOTUS parental rights decisions |
+| Sperm donor cases | 154 | R.C. 3111 paternity and donor rights case law |
+| OhioFamilyRights | 113 | Family law reform advocacy, legislative testimony, case analyses |
+| Juvenile court | 75 | Juvenile court procedures and delinquency |
+| Gemini-generated | 56 | Cloud-generated Q&A from corpus documents |
+
+**Generators**: Gemini 2.5 Flash, qwen3-coder:480b, Ollama local models, manual curation
+
+### Raw Corpus
 | Source | Records | Size |
-|---|---|---|
+|--------|---------|------|
 | Ohio Revised Code (19 chapters) | 1,034 sections | 3.0 MB |
 | Ohio Administrative Code (19 divisions) | 1,283 rules | 7.3 MB |
 | CourtListener opinions (OH App, SC, SCOTUS) | 259 opinions | 14 MB |
-| **Total corpus** | **2,576 records** | **24.3 MB** |
+| Reference materials | 941 records | 4.0 MB |
+| Parental alienation research | 55 papers | — |
 
-### Reference Materials
-- **941 records (4.0 MB)**: Black's Law Dictionary (591), OH Task Force on Family Law, Custody Evaluator Toolkit, GAL Task Force, Parenting Time Guide
-- **ORC Family Law (323 records, 1.2 MB)**: §3109, §2919, §2151, §3111, §3127, §3105
-- **55 PA references**: Academic papers, case analyses, legal guides
+### Key Cases Covered
+- **SCOTUS**: Santosky v. Kramer, Stanley v. Illinois, Troxel v. Granville, Michael H. v. Gerald D., Lehr v. Robertson
+- **Ohio SC**: In re Murray, In re Bonfield, Shearer v. Shearer, Felton, Davis v. Flickinger
+- **Topics**: Best interest standard (R.C. 3109.04), shared parenting, parental alienation, GAL standards, custody evaluation, DV protective orders, contempt, UCCJEA jurisdiction
 
-## Intended Use
+---
+
+## Quick Start
+
+### Using This Model (ModernBERT — Retrieval/Classification)
+
+```python
+from transformers import AutoModel, AutoTokenizer
+
+model = AutoModel.from_pretrained("Roderick3rd/OhioCustodyBERT")
+tokenizer = AutoTokenizer.from_pretrained("Roderick3rd/OhioCustodyBERT")
+
+# Encode legal text for semantic search
+text = "What factors does R.C. 3109.04 consider for shared parenting?"
+inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=512)
+outputs = model(**inputs)
+embeddings = outputs.last_hidden_state.mean(dim=1)
+```
+
+### Using the Generative Model (Qwen3.5-9B — Legal Analysis)
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3.5-9B")
+model = PeftModel.from_pretrained(base, "Roderick3rd/OhioCustodyBERT-Qwen3.5-9B")
+tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3.5-9B")
+```
+
+### Using via Ollama (Easiest)
 
-- **Classification**: Custody outcome prediction, legal issue spotting
-- **NER**: Legal entity recognition (judges, statutes, case names)
-- **Retrieval**: Semantic search over Ohio family law corpus
-- **Fact-checking**: Citation verification for LLM-generated legal text
-- **Council agent**: BERT Retriever + Verifier roles in Legal Agent Council
+```bash
+ollama run ohio-custody
+>>> What are the best interest factors under R.C. 3109.04?
+```
+
+---
 
 ## Limitations
 
-- Trained primarily on Ohio law — may not generalize to other jurisdictions
-- v0.1 had limited training examples (864); v0.2 will substantially expand this
-- Not a substitute for legal counsel
-- Classification boundaries reflect Ohio statutory framework (R.C. 3109.04)
+- **Ohio-specific**: Trained primarily on Ohio law — may not generalize to other states
+- **Not legal advice**: This is a research tool, not a substitute for a licensed attorney
+- **v0.1**: Current model trained on limited examples; v0.2 will substantially improve quality
+- **Case law currency**: Training data has a cutoff; recent decisions may not be reflected
+- **Classification bias**: Reflects the Ohio statutory framework (R.C. 3109.04 best interest factors)
+
+---
+
+## Intended Use
+
+| Use Case | ✅ Appropriate | ❌ Not Appropriate |
+|----------|---------------|-------------------|
+| Legal research | Identifying relevant statutes and cases | Generating court filings |
+| Case preparation | Understanding legal standards and precedent | Making custody recommendations |
+| Education | Learning Ohio family law framework | Replacing legal counsel |
+| Citation checking | Verifying case law references | Autonomous legal decision-making |
+
+---
+
+## Project Status
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| ModernBERT v0.1 | ✅ Live | 149.7M params, 864 examples |
+| ModernBERT v0.2 | 🔄 Training | Full corpus MLM retraining |
+| Qwen3.5-9B LoRA | 🔄 Training | 13,346 pairs, MLX on M4 Pro 48GB |
+| v24 Corpus | ✅ Complete | 13,346 pairs from 19 sources |
+| Legal Agent Council | 🔄 In Development | 6-agent pipeline, sequential model swap |
+| Kaggle Datasets | ✅ Published | `ohio-legal-corpus`, `pa-references`, `ohio-custody-sft-v21` |
+
+---
 
 ## Citation
 
 ```bibtex
 @misc{ohiocustodybert2026,
-  title={OhioCustodyBERT: Domain-Specific Legal Language Model for Ohio Family Law},
+  title={OhioCustodyBERT: Domain-Specific Legal AI System for Ohio Family Law},
   author={Roderick Mullins},
   year={2026},
   howpublished={HuggingFace: Roderick3rd/OhioCustodyBERT}
@@ -101,6 +243,6 @@ OhioCustodyBERT is one of **4 models** in a multi-agent legal council architectu
 
 ## Related Resources
 
-- **Corpus**: [Roderick3rd/OhioCustodyBERT-corpus](https://huggingface.co/datasets/Roderick3rd/OhioCustodyBERT-corpus)
+- **Generative Model**: [OhioCustodyBERT-Qwen3.5-9B](https://huggingface.co/Roderick3rd/OhioCustodyBERT-Qwen3.5-9B) — LoRA adapter for legal analysis generation
+- **Training Corpus**: [OhioCustodyBERT-corpus](https://huggingface.co/datasets/Roderick3rd/OhioCustodyBERT-corpus) — Full dataset with SFT pairs
 - **Kaggle**: [ohio-legal-corpus](https://www.kaggle.com/datasets/phoenixintelligence/ohio-legal-corpus), [pa-references](https://www.kaggle.com/datasets/phoenixintelligence/pa-references)
-- **Council Architecture**: 6 agents, 4 models, sequential swap on M4 Pro 48GB