Clarify Trace training, privacy, and evaluation

Position Trace as a specialized model trained on curated synthetic data. Add source links and privacy boundaries. Remove open-source wording and an unsupported evaluation claim.

README.md

@@ -1,63 +1,76 @@
 ---
-language: en
+language:
+- en
 license: other
 library_name: mlx
+pipeline_tag: text-generation
 base_model: mlx-community/Qwen2.5-7B-Instruct-4bit
 tags:
-  - sba
-  - "504"
-  - "7a"
-  - lora
-  - mlx
-pipeline_tag: text-generation
+- sba
+- "504"
+- "7a"
+- lora
+- screening
 ---
 
 # Trace
 
-This repository contains LoRA weights and `adapter_config.json` for Trace, in the MLX format used by `mlx_lm`.
+Trace is a specialized MLX LoRA adapter trained on high-quality, curated synthetic data for SBA 504 and 7(a) screening.
 
-Trace is a small open-source 504/7(a) screening model for CDFIs and lenders. Ask it a file. It returns the SOP or CFR paragraph in force on the loan-number date, a hard-stop or bounce, and a board you can check. A human certifies eligibility and credit.
+It helps a lender identify the rule that applies on a loan’s effective date, surface a potential hard stop, and prepare a reviewable screening summary. A qualified human must confirm every eligibility and credit decision.
 
-**Occupancy opens [13 CFR 120.131](https://www.ecfr.gov/current/title-13/section-120.131).**
+## What is included
 
-Working capital on a 504 opens [13 CFR 120.120](https://www.ecfr.gov/current/title-13/section-120.120). SOP 50 10 8.1 does not leak onto a January 2026 file.
+- LoRA adapter weights in MLX format
+- `adapter_config.json`
+- Evaluation visuals based on synthetic screening scenarios
 
-These artifacts load on the public base [`mlx-community/Qwen2.5-7B-Instruct-4bit`](https://huggingface.co/mlx-community/Qwen2.5-7B-Instruct-4bit). The staff runtime is the dated lake plus TRACE bind — not this adapter alone.
+The complete Trace system also uses a dated retrieval layer and deterministic policy checks. Those components are separate from this adapter.
 
-## Highlights
+## Training and grounding
 
-- **Occupancy.** Investor real estate and low occupancy open 13 CFR 120.131. Existing buy is **(b) 51%**. New construction is **(a) 60%**.
-- **Proceeds.** Payroll, inventory, and marketing on a 504 open 13 CFR 120.120 **(b)** and fail `USE_OF_PROCEEDS`.
-- **Clock.** A loan number on or after 2026-10-01 opens **SOP 50 10 8.1**. January files stay on SOP 50 10 8.
-- **Talk.** Messy processor English. Follow-up (“what if they occupy 100”) keeps the file. TRACE re-runs.
+The adapter was trained on 11,196 curated synthetic examples and 768 screening stems. The examples use fictional entities and are grounded in authoritative program material.
 
-If it cannot open the paragraph, it is not a screen.
+The runtime retrieval layer contains 23 official sources and 4,775 indexed sections, including:
 
-## Model overview
+- SBA SOP 50 10 guidance
+- SBA SOP 50 55 and SOP 50 57 guidance
+- 13 CFR Parts 120 and 121
+- Relevant SBA notices and program forms
 
-| | |
-|---|---|
-| Type | Causal LM + LoRA (screening JSON / officer memo) |
-| Base | Qwen2.5-7B-Instruct 4-bit (MLX) |
-| Method | MLX LoRA, rank 16, `mask_prompt` |
-| Pick | v9-160 (ScreenBench, not min val loss) |
-| Lake | Public SOP 50 10 / 50 55 / 50 57, 13 CFR 120–121, SBA notices — **retrieved**, not CPT |
-| Mouth (optional) | v17-160 English; JSON still TRACE-bound |
+The effective loan date selects the applicable SOP version. Runtime retrieval provides the current source text; it is not stored in the adapter weights.
 
-## Evaluation
+## Privacy boundary
 
-Grader is code (`sba_screen/quality.py`). Not an LLM judge.
+The training set does not include:
 
-**ScreenBench holdout n=12**
+- AmPac borrower files
+- Borrower names, loan numbers, addresses, or account numbers
+- Tax returns, Social Security numbers, or other borrower NPI
+- Historical approval or decline records
+- Private email or document content
 
-| | All-pass | False-kill |
-|---|---|---|
-| This adapter, no TRACE bind | 6/12 | 0 |
-| Complete system (lake + TRACE bind) | 12/12 | 0 |
+## Model details
+
+| Field | Value |
+| --- | --- |
+| Architecture | Causal language model with LoRA adapter |
+| Base model | [Qwen2.5-7B-Instruct 4-bit for MLX](https://huggingface.co/mlx-community/Qwen2.5-7B-Instruct-4bit) |
+| Fine-tuning method | MLX LoRA, rank 16, prompt masking enabled |
+| Selected checkpoint | v9-160 |
+| Primary output | Screening JSON and officer-facing draft summary |
+| Intended users | Trained lending and compliance staff |
+
+## Evaluation
 
-Exam-v1 (n=76) with bind: all-pass 76/76, false-kill 0. Retrieve on occupancy / WC / clock sentinels: 13/13.
+ScreenBench holdout uses 12 frozen synthetic files and a deterministic grader.
 
-Do not quote 12/12 as a naked-7B number. The adapter copies the board. TRACE computes the board.
+| Configuration | All-pass | False-kill |
+| --- | ---: | ---: |
+| Adapter without the Trace runtime | 6/12 | 0 |
+| Complete system with retrieval and policy checks | 12/12 | 0 |
+
+These results measure the complete screening workflow on a small internal holdout. They are not an independent certification.
 
 ## Quickstart
 
@@ -70,27 +83,21 @@ model, tokenizer = load(
 )
 ```
 
-Staff runner (opens 120.131 on investor apartments; no GPU required for TRACE-only):
-
-```bash
-python3 -m sba_screen --as-of 2026-01-15 --program 504 \
-  --sketch "504 to buy apartments they will rent out and not occupy"
-```
+The adapter alone does not provide the dated retrieval and deterministic policy checks used by the complete Trace system.
 
-Talk:
-
-```bash
-python3 -m sba_screen --talk --as-of 2026-01-15 --program 504
-```
+## Important limitations
 
-Studio mouth (`--mouth`) is optional English. TRACE still binds `hard_stop`.
+Trace does not determine eligibility, approve credit, or speak for the U.S. Small Business Administration. It produces review drafts for qualified staff.
 
-## Limitations
+Do not use Trace as the sole basis for an approval, decline, servicing action, or applicant communication. Confirm the source text and effective date before relying on an output.
 
-Does not determine eligibility. Does not decide credit. Does not speak for SBA. Trace is not an SBA product. SBA does not approve or endorse Trace. Do not give Trace to applicants. Outputs are drafts.
+## Official references
 
-Not included in training: borrower NPI, tax returns, AmPac files, approve/decline tapes.
+- [SBA SOP 50 10 — Lender and Development Company Loan Programs](https://www.sba.gov/document/sop-50-10-lender-development-company-loan-programs)
+- [13 CFR 120.120 — Eligible use of proceeds](https://www.ecfr.gov/current/title-13/section-120.120)
+- [13 CFR 120.131 — Leasing part of an existing or proposed building](https://www.ecfr.gov/current/title-13/section-120.131)
+- [AmPac Business Capital](https://www.ampac.com/)
 
-## License
+## License and attribution
 
-`other`. Qwen2.5 weights are Tongyi Qianwen. The SOP/CFR lake is U.S. government work. Screening code is ours.
+Repository license: `other`. The base model has its own license and terms. SBA SOPs, federal regulations, and notices remain subject to their source terms.