v0.27.0

What's New

Features

• Forager composite-score auto-exclude (#146, #147) — A second-tier auto-exclude path that scores each coin on three dimensions and pauses quoting when the blended score falls below a threshold, separate from the existing markout-driven auto_exclude. The score combines activity (close-event flow vs. idle), close-quality (maker close rate, with a minimum-closes gate before the dimension is trusted), and cost (per-1K-volume net cost). Each dimension is weighted independently so operators can re-balance without touching the score formula. Opt-in via --forager; tuning via --forager-threshold (default 30.0) plus --forager-w-activity / -quality / -cost (defaults 0.3 / 0.4 / 0.3). Cooldown and consecutive-strike gates mirror the existing auto_exclude semantics so the two features compose cleanly. The five non-CLI knobs (FORAGER_WINDOW_SECONDS, FORAGER_CHECK_INTERVAL_SECONDS, FORAGER_ACTIVITY_IDLE_MIN_SECONDS, FORAGER_COST_MAX_PER_1K, FORAGER_MIN_CLOSES_FOR_QUALITY) stay env-only to keep the CLI surface manageable. (#147 promotes the previously hardcoded 5-close quality gate to the same env knob, so all formula thresholds are configurable.)

• JSON config as a layered input source (#148, #149) — New --config <path> CLI flag (repeatable; later files override earlier) and BOT_CONFIG=<path> env var that load a JSON file as a config layer between the dataclass defaults and CLI/env. Final precedence is CLI > env > JSON > defaults, so the rollout is opt-in and pure-additive: existing CLI/env workflows are byte-identical when no --config is supplied. The loader auto-detects flat ({"spread_bps": 10, …}) vs. nested ({"market_making": {"spread_bps": 10, …}}) form; nested keys are flattened against _NESTED_TO_FLAT_MAP so downstream MMConfig.from_legacy_dict() is unchanged. JSON values under the risk namespace are wired through to Config.{KEY.upper()} via a new _apply_json_risk_overrides helper (closes the gap from the initial #148 wiring); CLI risk flags still beat JSON, JSON beats env, and the helper pops applied keys so they don't leak back into strategy_config. Unknown keys log a typo warning but otherwise pass through; malformed JSON aborts startup with exit code 2 (fail-safe). An examples/config.example.json covers the nested form.

Fixes

• _STRATEGY_PARAMS / _COMMON_PARAMS at module scope (#150) — Latent bug discovered during round-trip migration-tool verification: PR #148 lazily imports these lists in validation.strategy_validator.known_market_making_keys() for typo detection, but only _RISK_PARAMS was promoted to module level in #149 — the other two stayed inside main(), so any --config invocation hit ImportError at startup. This release moves both lists out of main() (call-sites unchanged) and adds a TestKnownMarketMakingKeys regression class that pins the contract via direct import + indirect function calls; future demotion will fail CI rather than reach production.

Upgrade Notes

• All changes are backward compatible — defaults preserve existing behaviour:
  • Forager is default-disabled. Without --forager the strategy and shutdown paths are byte-identical to v0.26.0. Operators flipping it on are advised to start with the default weights and --forager-threshold 30, observe [forager] log lines for at least one full session, and tighten only after the per-coin score distribution stabilises.
  • JSON config is opt-in. With neither --config nor BOT_CONFIG set, the JSON loader is never invoked. When set, the layer sits below env/CLI; existing .env.farming + start_farming*.sh flows continue to win on every shared key.
  • Migration tool: a companion scripts/env_to_json.py lives in the hip-3-farming-agent-team repo — it converts .env.farming to a nested JSON config, skipping credentials/DEX/framework keys. Useful for staging a JSON deployment without re-typing the existing knob set.
  • Level 1 risk guardrails (risk_manager.py hardcoded values) are untouched in this release.

Operator Checklist

• Forager Phase A (default weights, min_fills=3, score threshold 30): turn on via FORAGER_ENABLED=true + --forager. Watch the per-coin score component breakdown in the periodic [forager] summary; confirm no coin is scored below threshold purely on a single dimension before tightening any weight.
• JSON config Phase A (loader path validation): set BOT_CONFIG=/abs/path/config.json in .env.farming while leaving all CLI flags in start_farming*.sh intact. Confirm [config] Loaded N key(s) from … and [config] JSON layer loaded: N key(s) from 1 file(s) appear at startup with no warnings beyond intentional skips. Phase B (stripping CLI flags so JSON drives values) is a separate operator step after a 24h observation window.