code/self_healing_finetuning/README.md

# Linvest21 SHFT Platform

This is the dry-run-first implementation of the Linvest21 Self-Healing Fine-Tuning Platform.

Default behavior is safe:

- no live provider calls unless `--live` is explicitly passed;
- FinGPT-first model policy using `FinGPT/fingpt-mt_llama3-8b_lora` as the default current FinGPT multitask candidate;
- explicit `train_provider` and `infer_provider` routing;
- heartbeat and audit JSONL events;
- per-iteration evidence and improvement reports;
- secret scanning and provider environment validation.

Run locally from this directory:

```bash
python -m n21.cli validate-config --provider hf_managed
python -m n21.cli select-model --task finance_qa --env dev
python -m n21.cli train --train-provider hf_managed
python -m n21.cli eval --run-id <run_id>
python -m n21.cli deploy --run-id <run_id> --infer-provider hf_managed --env stage
```

## Runtime Boundaries

SHFT platform state and generated implementation products are separate:

```text
impl_codex/self_healing_finetuning   platform code and configuration
impl_codex/shft_workspace            run evidence, registries, evals, logs, and verification reports
impl_codex/implementation_products   versioned runnable model products
```

Current SHFT runs must write evidence under `impl_codex/shft_workspace/runs/<run_id>`. The generated implementation is an output of SHFT, not an input dependency for the SHFT run.

Current exports write versioned products under `impl_codex/implementation_products/<model_id>`. Active SHFT code does not use the retired unversioned implementation tree.

## Controlled Super-Agent Flexibility

The 18 target Linvest21 FinGPT submodels are controlled by:

```text
configs/super_agent_matrix.json
```

The matrix is:

```text
3 asset classes: equity, fixed_income, multi_asset
6 roles: chief_investment_officer, client_portfolio_manager, performance_manager, portfolio_manager, researcher, risk_manager
```

The model ID template is:

```text
linvest21_fingpt_<asset_class>_<role>_<version>
```

The versioned implementation product directory template is:

```text
impl_codex/implementation_products/linvest21_fingpt_<asset_class>_<role>_<version>
```

Use the generic batch wrapper to keep operator commands simple while still parameterizing the asset class, role, and version:

```bat
impl_codex\scripts\run_linvest21fingpt_super_agent_to_implementation.bat equity researcher all v1_000
```

For an interactive single-entry dispatcher that lists all 18 super-agents and routes to the wrapper above, use the menu driver:

```bat
impl_codex\scripts\run_linvest21fingpt_super_agent_menu.bat                  REM interactive
impl_codex\scripts\run_linvest21fingpt_super_agent_menu.bat --list
impl_codex\scripts\run_linvest21fingpt_super_agent_menu.bat --index 5
impl_codex\scripts\run_linvest21fingpt_super_agent_menu.bat --asset equity --role researcher --version v1_000 --mode all
```

By default, each new super-agent fine-tune starts from the approved Linvest21 FinGPT bootstrap adapter:

```text
Meta-Llama-3-8B base
+ linvest21/linvest21_fingpt_v1_000 bootstrap adapter
+ role-specific adapter being trained
```

This is controlled by `--finetune-start-policy`:

```bat
impl_codex\scripts\run_linvest21fingpt_super_agent_menu.bat --asset equity --role researcher --version v1_001 --mode all --finetune-start-policy bootstrap
impl_codex\scripts\run_linvest21fingpt_super_agent_menu.bat --asset equity --role researcher --version v1_001 --mode all --finetune-start-policy continue-best
```

`bootstrap` is the default. It starts from `linvest21/linvest21_fingpt_v1_000` and avoids compounding bias from failed prior role adapters. `continue-best` is opt-in. It reads `impl_codex/shft_workspace/best_runs/<release_id>.json` and continues only from the best measured checkpoint for that exact asset/role/version. It fails closed if no best-run record exists.

For parallel role launches in separate visible Command Prompt windows, use:

```bat
impl_codex\scripts\run_linvest21fingpt_parallel_super_agents.bat
impl_codex\scripts\run_linvest21fingpt_parallel_super_agents.bat --asset fixed_income --role researcher --role risk_manager --version v1_001 --mode status
impl_codex\scripts\run_linvest21fingpt_parallel_super_agents.bat --asset multi_asset --roles researcher,portfolio_manager,risk_manager --version v1_001 --mode all
impl_codex\scripts\run_linvest21fingpt_parallel_super_agents.bat --asset equity --version v1_001 --mode all-until-certified --continue-best
```

The parallel launcher defaults to the six equity roles, titles each window as `SHFT <asset_class> <role> <version>`, and cascades the windows so all runs remain visible. It only dispatches to the existing menu driver; all validation, paid-job guardrails, quality gates, and output paths remain centralized there.

The menu reads `configs/super_agent_matrix.json`, validates that `data/learning/<asset_class>/<role>` exists (exits 2 with a clear message otherwise), resolves the unique versioned `Model ID` (`linvest21_fingpt_<asset_class>_<role>_<version>`), then delegates to the per-agent wrapper, which packages the portable runtime (chat console + token-protected JSON API via `LINVEST21_API_TOKEN`) under `impl_codex/implementation_products/<model_id>`.

Live submit modes are intentionally guarded:

```text
HF_TOKEN must be present.
SHFT_SUBMIT_HF_JOB must equal true.
```

Use `--mode status` or `--list` for safe inspection without job submission.

Validate the configured matrix, learning-data directories, and any generated implementation folders with:

```bat
impl_codex\scripts\validate_super_agent_matrix.bat
```

The bootstrap model `linvest21/linvest21_fingpt_v1_000` is lineage and starting point. Exported runtime identity must be the super-agent model ID, and must appear in `release_manifest.json`, `runtime/chat_config.json`, chat output, `/health`, `/v1/models`, and `/v1/chat/completions`.

## Production Inference Architecture

For Linvest21 production inference, use base model plus adapters as the default architecture:

```text
shared approved base model
+ certified adapter for each asset_class/role/version
```

This is superior for the current 18-super-agent platform because the agents should share the same approved financial base capability while each adapter captures the role-specific investment behavior. It reduces storage, supports faster per-role retraining, gives each adapter separate training/eval/promotion evidence, and allows one role to roll back without touching the rest.

Publish each certified super-agent as an independent adapter model repo or artifact, for example:

```text
linvest21_fingpt_equity_researcher_v1_001
linvest21_fingpt_equity_risk_manager_v1_001
linvest21_fingpt_fixed_income_risk_manager_v1_001
```

Merged or quantized full-model artifacts are optional deployment builds. Use them when a role needs offline serving, GGUF/local desktop deployment, different base-model lineage, or simpler single-model loading. They should not replace the certified adapter as the governance source of truth.

## Step 0 Public-Source Intake Gate

Default policy:

```text
Download public material automatically, but train only on material that passes the configured source-policy gate.
```

The policy and catalog are controlled by configuration, not hardcoded operator choices:

```text
configs/data/source_policy.yaml
configs/data/public_source_catalog.json
```

Run public-source intake for one super-agent:

```bat
cd impl_codex\self_healing_finetuning
python -m n21.cli intake-public-sources --asset-class equity --role risk_manager
```

Run training-data validation and optional quarantine recommendation:

```bat
cd impl_codex\self_healing_finetuning
python -m n21.cli validate-training-data --source ..\..\data\learning\equity\risk_manager --output-dir ..\shft_workspace\runs\<run_id>\data_validation --backup-dir ..\shft_workspace\runs\<run_id>\data_validation\quarantine_backup --apply-quarantine
```

The intake command writes raw downloads, approved copies, and review-required copies under:

```text
data/learning_intake/<asset_class>/<role>
```

Only source-policy-approved material is promoted into:

```text
data/learning/<asset_class>/<role>
```

Downloaded files are never trained directly unless they are already curated JSONL. They first pass through a normalization layer:

```text
raw download -> normalized .normalized.json -> training/validation eligibility -> Step 0b JSONL
```

Default format policy:

- `pdf`: normalize, train, and validate.
- `jsonl`: normalize/pass through, train, and validate.
- clean direct `html`: normalize and train, but do not use for validation by default.
- `html_index`: download and normalize for review, but do not train by default.
- `txt` and `md`: normalize and train, but do not validate by default.
- `unknown`: do not normalize, train, or validate.

Transparency artifacts are written as `source_intake_manifest.json`, `license_manifest.json`, `training_data_validation_report.json`, `conflict_report.json`, and `quarantine_manifest.json`. This keeps automatic discovery/download flexible while keeping training strict and auditable.

## Model-Quality Gate

Self-healing cycle scores are orchestration evidence. They are not enough for promotion.

Promotion and final copyable packaging require measured model-quality evidence:

```text
impl_codex/shft_workspace/runs/<run_id>/eval/paired_eval_report.json
impl_codex/shft_workspace/runs/<run_id>/remote_artifacts/training_plan.json
impl_codex/shft_workspace/runs/<run_id>/dataset_snapshot/dataset_manifest.json
impl_codex/shft_workspace/runs/<run_id>/eval/model_judge_report.json
impl_codex/shft_workspace/runs/<run_id>/eval/human_spot_check_report.json
```

Run the gate directly:

```bat
cd impl_codex\self_healing_finetuning
python -m n21.cli quality-gate --run-id <run_id>
```

The gate fails closed and prints exact blockers when evidence is missing or thresholds are not met.

When `all` reaches a failed model-quality gate, SHFT now runs an automatic Step 0 stall-breakout pass. If breakout creates new trainable material, `all` starts a fresh run id and repeats train -> fetch -> paired proof -> quality gate until the gate passes or the configured recovery budget is exhausted. The failed run is never certified retroactively.

For explicit operator-supervised continuous training, use `all-until-certified`:

```bat
impl_codex\scripts\run_linvest21fingpt_super_agent_menu.bat --asset equity --role researcher --version v1_001 --mode all-until-certified
```

This is a paid live mode. It repeats train -> fetch -> paired proof -> quality gate -> source breakout -> retrain until the configured model-quality gate passes. It does not stop at `SHFT_MAX_BREAKOUT_ROUNDS`; the human operator stops it with Ctrl+C or by closing the command window. It still fails closed for certification: a run is not promoted or packaged as certified unless the measured quality gate passes.

Continuous mode writes operator-visible intelligence and recovery status after each quality gate and breakout:

```text
impl_codex/shft_workspace/continuous_training/<release_id>_status.json
impl_codex/shft_workspace/runs/<run_id>/continuous_training_status.json
impl_codex/shft_workspace/runs/<run_id>/next_data_strategy.json
impl_codex/shft_workspace/best_runs/<release_id>.json
```

These artifacts report current aggregate, critical-pass rate, pairwise win/loss rate, training loss when available, train/validation counts, distance to configured thresholds, best measured run so far, source-breakout status, and the next data strategy.

When `fetch-proof` reaches a failed model-quality gate, SHFT still runs the breakout pass and writes the recovery package, but it does not auto-submit a fresh paid training job because `fetch-proof` is a resume/fetch command.

Each breakout pass creates transparent recovery artifacts under:

```text
impl_codex/shft_workspace/runs/<run_id>/stall_breakout
```

Key artifacts:

```text
stall_breakout_plan.json
source_intake_manifest.json
license_manifest.json
training_data_validation/training_data_validation_report.json
```

The breakout pass uses the configured public-source catalog and source policy, downloads public material automatically, promotes only normalized `eligibility.training=true` sources into `data/learning/<asset_class>/<role>`, validates the resulting corpus, and records whether the new sources are actually trainable by the current Step 0b converters.

Source acquisition is fallback-aware: a failed URL, `403`, `404`, timeout, blocked source, or non-trainable normalized source is recorded and SHFT continues to the next matching source until it finds the configured number of trainable sources or exhausts the catalog. The default policy remains: download public material automatically, but train only on material that passes the configured source-policy gate.

Control flags:

```bat
set SHFT_AUTO_STALL_BREAKOUT=false
set SHFT_AUTO_BREAKOUT_RETRAIN=false
set SHFT_MAX_BREAKOUT_ROUNDS=3
set SHFT_CONTINUOUS_DISCOVERY_SLEEP_SECONDS=300
```

Disable automatic breakout for a run with:

```bat
set SHFT_AUTO_STALL_BREAKOUT=false
```