linvest21/shft-artifacts/code/self_healing_finetuning - Storage Bucket

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:

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:

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:

configs/super_agent_matrix.json

The matrix is:

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:

linvest21_fingpt_<asset_class>_<role>_<version>

The versioned implementation product directory template is:

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:

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:

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:

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

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

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:

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:

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:

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:

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:

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:

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:

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

Run public-source intake for one super-agent:

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:

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:

data/learning_intake/<asset_class>/<role>

Only source-policy-approved material is promoted into:

data/learning/<asset_class>/<role>

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

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:

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:

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:

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:

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:

impl_codex/shft_workspace/runs/<run_id>/stall_breakout

Key artifacts:

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:

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:

set SHFT_AUTO_STALL_BREAKOUT=false