# FenixAI v2.5 Development History

Status: release-candidate narrative, public-safe draft  
Scope: work performed after the v2.0 release and before the planned v2.5 publication  
Last updated: 2026-05-05

> FenixAI v2.5 is not a profitability claim. It is a stability, research, execution-safety, and observability release built from months of paper, testnet, and small-size live canary testing.

## Executive Summary

FenixAI v2.0 moved the project from the first public architecture into a LangGraph-based multi-agent trading system with ReasoningBank memory, a React dashboard, and multi-provider LLM support. The months after v2.0 were not spent on one single feature. They were spent on repeatedly testing the bot against real market conditions and fixing the parts that failed under pressure.

The main v2.5 theme is simple: make Fenix easier to test honestly.

That required improvements in five areas:

1. **Execution correctness**: live positions, protective orders, exchange minimums, stale local state, and close accounting had to match Binance reality.
2. **Decision quality**: the agents had to stop getting stuck in permanent `HOLD`, stop over-trading weak consensus, and stop opening positions from invalid or stale data.
3. **Latency**: short-timeframe loops could not wait on slow cloud models every cycle.
4. **Risk accounting**: failed orders and opening events could not be counted as realized losses, and closed trades had to use real exchange fills.
5. **Research transparency**: model benchmarks, NanoFenix experiments, live canaries, and known limitations needed to be documented in English before any public update.

The result is a more mature system, but still an experimental one. v2.5 should be described as a safer and more observable research release, not as a finished autonomous profit machine.

## Where v2.0 Started

v2.0 was the architectural reset:

- CrewAI was replaced by **LangGraph**.
- The old monolithic live runner was split into modules under `src/`.
- The agent stack became more formal:
  - Technical Analyst
  - Visual Analyst
  - Sentiment Analyst
  - QABBA microstructure/volatility analyst
  - Decision Agent
  - Risk Manager
- **ReasoningBank** was introduced for memory and self-evaluation.
- Multi-provider inference was added for Ollama, MLX, Groq, HuggingFace, and later Ollama Cloud.
- The dashboard moved to React, Vite, TypeScript, TailwindCSS, FastAPI, and Socket.IO.
- Basic safety was added:
  - explicit live-trading flag
  - secure secrets manager
  - local API binding by default
  - demo-user gating

That foundation was good enough to start serious testing. It was not good enough to trust blindly.

## Phase 1: Decision Behavior and Position Safety

Early post-v2.0 testing exposed two opposite problems:

- The bot could become paralyzed by rigid consensus rules and emit mostly `HOLD`.
- When it did act, it could flip direction too quickly or hedge unintentionally.

### Why We Changed It

Rigid consensus looked safe, but it prevented the Decision Agent from doing its real job: synthesizing evidence. At the same time, allowing opposite-side entries without carefully closing existing exposure created confusing live behavior and poor capital usage.

### What Changed

- The Decision Agent prompt was changed from rigid "all agents must agree" behavior to a more flexible synthesis policy.
- The engine added checks to prevent involuntary hedging.
- Opposite-side position handling was improved so the bot can close or reconcile exposure instead of blindly opening the other side.
- Same-side adds became explicit and configurable through `FENIX_ALLOW_ADD_TO_POSITION`.

### What We Learned

Consensus is not the same as intelligence. A trading stack needs:

- flexible synthesis when evidence is strong;
- hard safety rules around actual exchange exposure;
- clear separation between "new entry", "same-side add", "opposite exit", and "reversal".

## Phase 2: Market Regime Filters and Indicator Upgrades

After the bot became more willing to act, testing showed that it could sell too aggressively near support or buy into exhaustion. This led to a broader indicator and filter pass.

### What Changed

v2.5 includes a timeframe-aware indicator system:

- indicator profiles by timeframe;
- market-regime classification;
- advanced indicator support such as VWAP bands, HMA, Fisher Transform, CHOP, Donchian Channels, Keltner Channels, CVD, OBI, funding rate, and open-interest context;
- per-timeframe guidance for Technical and QABBA prompts.

Execution filters were also expanded:

- CHOP transition handling;
- RSI extreme protection;
- support/resistance proximity checks;
- rebound/rejection guards;
- trend-conflict and confluence guards;
- long/short guard rails for risky contexts;
- buy-hold consolidation guard for weak reversal setups.

### Why It Matters

The goal was not to add indicators for the sake of complexity. The goal was to stop treating every timeframe and every regime the same way.

A 1m scalp signal should not be evaluated like a 15m swing signal. A support-zone short should not be treated like a clean breakdown. A QABBA microstructure impulse should not always override broader technical context.

## Phase 3: Short-Timeframe Latency and Nonblocking Agents

Short-timeframe testing made a core bottleneck obvious: LLM calls are too slow and too unstable to sit directly on the hot path every cycle.

### What Changed

The v2.5 engine added a nonblocking short-timeframe mode:

- Technical and QABBA can return cached or deterministic fallback reports immediately.
- Slow LLM refreshes run in the background.
- Decision fallback logic can synthesize from available cached reports.
- Visual analysis and chart generation can be moved off the critical path.
- Paper trades no longer initialize Binance services just to fetch balance.
- Agent timeouts became shorter and role-specific for live-friendly runs.

### Measured Impact

Internal measurements on SOLUSDT 1m showed the hot path moving from heavy LLM-blocked cycles into millisecond-level cache/fallback cycles in the lite path. A documented hot-path test measured approximately:

- cold-start lite cycle: about 12.9 ms;
- cache-hit cycle: about 7.9 ms;
- no REST balance spike for paper execution.

Full LLM cycles can still take tens of seconds, especially with visual models or slow cloud responses. v2.5 does not claim that every agent response is millisecond-fast. It claims that short-timeframe operation no longer has to block entirely on every LLM call.

## Phase 4: Cloud Model Benchmarks and Agent Role Selection

The project spent a large amount of time testing model behavior by role rather than assuming one model should run every agent.

### What We Tested

The benchmark work covered many cloud and local models across:

- Technical Analyst;
- QABBA;
- Decision Agent;
- Risk Manager;
- Visual Agent;
- mixed live/paper suites;
- split-key cloud routing;
- risk-local vs risk-cloud configurations.

### Notable Findings

The v21 benchmark summary identified role-specific winners:

| Agent | Strong Candidate | Observation |
| --- | --- | --- |
| QABBA | `cogito-2.1:671b-cloud` | Strong microstructure accuracy in benchmark windows. |
| Technical | `nemotron-3-nano:30b-cloud` | Good directional accuracy and practical activity. |
| Visual | `gemini-3-flash-preview:cloud` / `qwen3-vl` variants | Useful, but expensive in latency. |
| Decision | `nemotron-3-nano:30b-cloud` or later `gemma4:31b-cloud` in some short tests | Activity/latency tradeoff matters. |
| Risk | `glm-5:cloud`, `devstral-small-2:24b-cloud`, or deterministic risk depending on run type | LLM risk can be useful but must be guarded. |

Later April tests showed that a practical team for some short live canaries was:

```text
technical = gemma4:31b-cloud or nemotron-3-nano:30b-cloud
qabba = gemma4:31b-cloud
decision = gemma4:31b-cloud
sentiment = gemma4:31b-cloud
risk_manager = devstral-small-2:24b-cloud
visual = off for short runs
```

### Why This Matters

Different agents fail differently:

- some models are accurate but too slow;
- some are active but biased;
- some parse JSON poorly;
- some become too conservative and output mostly `HOLD`;
- some copy examples from prompts into live risk levels.

v2.5 therefore treats model choice as a per-agent decision, not a single global setting.

## Phase 5: Live Testing Framework

The project moved toward an engine-first live testing system instead of relying on older hybrid flows.

### What Changed

New live-test tooling focused on the real `TradingEngine` lifecycle:

- `scripts/run_fenix_live_slot.py` for single-slot runs;
- `scripts/run_fenix_live_suite.py` for sequential suites;
- JSONL event logs for every slot;
- summary JSON files with decision counts, risk blocks, judge blocks, filter blocks, trade counts, and accounting checks;
- support for per-agent model assignment;
- support for paper, testnet, and live modes;
- dual-key and split-key experiments for Ollama Cloud stability;
- lock files to prevent accidental duplicate live slots on the same account/symbol.

### Why It Matters

Several bugs only appeared in real engine runs:

- cloud endpoint confusion;
- stale lock behavior;
- visual warmup latency;
- Binance exchange minimums;
- stale local position state;
- discrepancy between internal close price and exchange fill price.

The live slot runner made these failures reproducible and measurable.

## Phase 6: Binance Live Execution Reliability

This was one of the most important v2.5 areas. Many changes were not "new features" but safety corrections discovered from real exchange behavior.

### Problems Found

Testing exposed:

- string numeric fields from Binance causing position-comparison bugs;
- same-side pyramiding when not explicitly intended;
- local state believing a position was open after Binance was already flat;
- local state closing a position before a real reduce-only exit was confirmed;
- event logs missing real exchange closes;
- protective order verification missing Binance Futures algorithmic orders;
- standard `openOrders` not showing newer conditional/algo protective orders;
- risk accounting being updated from attempted trades instead of confirmed closes;
- exchange minimum notional and step-size rules causing silent skips or invalid sizing.

### What Changed

v2.5 includes:

- live position hydration at startup;
- stale local position reconciliation before new live entries;
- reduce-only live exits before local close records on opposite signals;
- exchange-fill synchronization for live exits;
- protective order checks using `openAlgoOrders`;
- cleanup-on-stop behavior that can cancel protection and close open exposure;
- exchange minimum quantity and min-notional flooring with live safety constraints;
- same-side entry prevention by default;
- explicit add-to-position flags when pyramiding is desired.

### Why It Matters

The engine must never confuse internal memory with exchange truth. Binance is the source of truth for live exposure. v2.5 moves closer to that standard.

## Phase 7: Runtime Risk Manager and Accounting Fixes

Live testing showed that incorrect accounting can be as dangerous as incorrect execution.

### Problems Found

- Failed execution attempts were being counted as realized losses.
- Opening a position could trigger risk manager state as if a loss had occurred.
- Baseline balances from old state could create false drawdown alerts.
- Closed trades could be recorded with `pnl=0` and `success=false` even when Binance showed a win.
- Daily PnL could remain polluted after a baseline re-anchor.
- Risk LLM outputs sometimes returned `approved_size` values that were ambiguous or implausible for the symbol/account.

### What Changed

- `open_trade()` and `close_trade()` flows were restored and separated.
- Risk state now updates on real closes rather than failed attempts or opens.
- Balance baseline re-anchoring clears stale daily PnL.
- Live closes pass real PnL, PnL percent, exit price, and success status to the risk manager.
- Implausible `approved_size` values from the Risk LLM are ignored.
- Deterministic ATR-based risk can replace LLM risk for speed and reliability.
- Missing balance no longer silently falls back to an unrealistic 10000 USDT assumption.
- Live notional can be capped to available margin.

### Current Honest Status

Risk accounting is much better than it was, but risk LLM outputs are still not trusted blindly. The engine now treats them as suggestions that must pass deterministic validation.

## Phase 8: NanoFenix Companion Work

NanoFenix became a major research track after v2.0.

### Original Problem

The early NanoFenix companion was too rigid:

- short and long horizons had to agree too often;
- weak calibration could still look directionally confident;
- trailing exits could be gross-positive but net-negative after fees;
- companion readiness and runtime restoration were inconsistent;
- companion docs and actual runtime defaults drifted apart.

### What Changed

NanoFenix v2.5 work includes:

- interval-specific runtime state restoration;
- adaptive dual-horizon fusion;
- online reliability tracking;
- companion JSON output for Fenix;
- signal fields such as expected bps, uncertainty bps, net actionable edge, calibration health, drift score, and size multiplier hints;
- `allow_add_to_position` guidance;
- fee-aware trailing exits;
- companion signal freshness checks;
- configurable hard-veto reasons;
- more explicit engine-side NanoFenix policy events.

### What We Learned

NanoFenix is useful as a filter and diagnostic companion. It is not yet proven as an independent profit driver.

In SOL 15m canaries, NanoFenix often blocked entries for:

- low actionable edge;
- high uncertainty;
- low calibration health;
- low confidence;
- companion not ready;
- low direction accuracy.

That reduced churn, but it also made the stack too conservative in some sessions. The current v2.5 stance is to keep NanoFenix as a companion signal, not as a single authority over execution.

## Phase 9: Paper vs Live Parity

Paper testing is useful only if it does not lie.

### Problems Found

- Paper/hybrid flows could record entries with invalid or zero prices.
- Paper mode could call Binance services unnecessarily and distort latency.
- Hybrid runner code drifted away from the current `TradingEngine` constructor.
- Hybrid multi-timeframe runs were harder to compare against live slot event logs.

### What Changed

- Paper/hybrid execution rejects invalid prices before recording position transitions.
- Paper mode can use fallback balance without REST calls.
- Hybrid runner now filters engine kwargs against the actual constructor signature.
- Staged TP/SL tracking and partial close support were added to the hybrid runner.
- Visual can be disabled globally for cleaner multi-timeframe probes.

## Phase 10: Real Live Canary Evidence

Several small live canaries were run across ETH and SOL. They were intentionally small and should be treated as engineering validation, not performance marketing.

### ETH 5m March Canary

An ETH 5m live run produced a positive net result in one overnight window:

- roughly 8.5 hours;
- 97 final decisions;
- 24 recorded closes;
- Binance-window net approximately positive after fees;
- QABBA alignment improved accuracy in the analyzed sample.

The deeper analysis showed a key lesson: fees consumed a large share of gross edge. The bot could be directionally better than random and still lose too much to churn.

### ETH 15m April Canary

An ETH 15m overnight run completed cleanly with:

- 5 closed trades;
- 4 wins and 1 loss;
- positive small live PnL;
- QABBA acting as the strongest directional layer in that sample.

This was encouraging but not enough to claim stable profitability.

### SOL 15m April Canaries

SOL 15m became the main hardening environment. It exposed:

- over-shorting near support;
- NanoFenix overconservatism;
- stale local position state;
- missing close reconciliation;
- live vs event-log mismatch;
- the need for support/resistance and microstructure confirmation filters;
- the need for margin-aware sizing on small accounts.

Some SOL canaries were positive. Others were negative. The value of this work was mostly the bugs it revealed.

### Latest v31b SOLUSDT Run

The latest reviewed v31b run completed its 8-hour window:

- 33 analysis cycles;
- decisions: 23 SELL, 9 HOLD, 1 BUY;
- 3 live round trips;
- 3 losses;
- total internal PnL around -0.1677 USDT;
- final risk state: `CAUTION` due to loss streak;
- Binance ended flat with no open regular or algorithmic orders.

This is important because it validates operational cleanup, but it also shows the current strategy still needs better entry selectivity and opposite-signal handling.

## Phase 11: DeepSeek v4 Cloud Tests

DeepSeek v4 Flash and DeepSeek v4 Pro were pulled and smoke-tested through Ollama Cloud.

### What Happened

Paper tests showed that DeepSeek Flash could produce active decisions, but it also produced unstable or oversized sizing behavior in the tested configuration. DeepSeek Pro/mix runs showed availability and timeout issues in some cases.

### Current Release Stance

DeepSeek v4 integration can be mentioned as tested, but it should not be presented as the recommended v2.5 live agent team yet.

The safer current recommendation is to keep the stable cloud team that has been through more live canary cycles, while documenting DeepSeek as an experimental model option.

## Phase 12: Documentation and Release Hygiene

Preparing v2.5 also required cleaning the project story.

### What Changed

- v2.5 release notes were added.
- The README now describes v2.5 as an official release.
- NanoFenix HTF changes were translated into English.
- Runtime comments/docstrings in release-relevant files were translated where maintainability matters.
- A release checklist was added.
- Documentation now distinguishes:
  - public release notes;
  - internal live-test notes;
  - benchmark results;
  - known blockers.

### Remaining Cleanup Work

Before publishing, the project still needs:

- a final review of the public-safe script index and script evolution guide;
- clearer separation between production launchers and historical experiment launchers;
- old Spanish analysis reports either translated, archived, or excluded from the public package;
- a final release checklist pass for secrets, account identifiers, local paths, and private run artifacts.

## Phase 13: v25 to v31 Live-Safe Launcher Cleanup

The final v2.5 preparation pass focused on turning the recent production scripts into an understandable release story.

### What Happened

The first May 2026 SOLUSDT live production test started from `scripts/launch_fenix_v25_live_mtf_safe.sh`. That script was intentionally conservative: 15m entry, deterministic 30m MTF bias, NanoFenix v3 companion observer, no add-to-position, small max notional, and the live slot runner as the execution path.

As testing continued, the launcher evolved through several corrections:

- NanoFenix companion freshness and observer-only behavior were tightened.
- The kline watchdog was tuned for 15m live cycles.
- The lite consensus mode changed to `technical_mtf_qabba_guard` so Technical + MTF agreement could open a candidate entry while QABBA remained a strong-opposition guard.
- Lite Technical/QABBA node calls were wrapped in timeouts so a slow cloud response could not stretch a cycle indefinitely.
- Model teams were corrected after Technical JSON parse failures and QABBA latency issues.
- The long paper suite runner was corrected so MTF guard settings are carried explicitly by the plan instead of depending on shell state.
- Technical timeout/error fallbacks were blocked from using the optional MTF+QABBA entry path, because a failed Technical node is not a clean HOLD signal.

The user then correctly asked to move the production test to the newer v31 family. The original `scripts/launch_fenix_v31.sh` was not safe for live orders because it used the hybrid paper runner and a March ETHUSDT setup. The project therefore added `scripts/launch_fenix_v31_live_mtf_safe.sh`, which keeps the newer v31 direction while using the safer `scripts/run_fenix_live_slot.py` execution path.

### Latest Live Safety Fix

The v31 live-safe SOLUSDT test also exposed a live/local reconciliation bug:

- Fenix hydrated an existing Binance SHORT after restart.
- A rule-based local `time_exit` closed the `TradeManager` position.
- Binance still had the real SHORT open.

The fix was to make rule-based live exits execute a reduce-only market close, confirm Binance is flat, reconcile the fill price/PnL/commission from exchange trades, and rehydrate if flat confirmation fails.

### Latest Live Accounting Fix

The follow-up v31 SOLUSDT canary completed 26 live analysis cycles with no new BUY/SELL entries. It also safely closed the already-hydrated exchange SHORT from the prior run, leaving Binance flat with no open SOLUSDT orders.

The summary initially marked the run as `completed_with_accounting_gap` because accounting counted one `position:closed` event and zero `position:opened` events. That was misleading: the close belonged to a `position:hydrated` exchange position, not to a missing local open event.

The fix was to count hydrated positions in live slot summaries and treat `position_opened + position_hydrated` as the closeable position base. The summary can now distinguish a real open/close mismatch from a correct close of inherited exposure.

### Documentation Result

The script surface is now documented in:

- `scripts/README.md` for the practical index;
- `docs/releases/v2.5-script-evolution.md` for the narrative history and current release stance.

This makes the release safer to explain: v2.5 can keep historical launchers for reproducibility without implying every old script is current production guidance.

## What v2.5 Improves Over v2.0

### Better Execution Safety

v2.5 is much more careful about:

- live position hydration;
- stale local state;
- same-side entry prevention;
- exchange min-notional and step-size constraints;
- protective algorithmic orders;
- cleanup-on-stop;
- real exchange-fill reconciliation.

### Better Testing Infrastructure

v2.5 has:

- repeatable live slot runs;
- summary JSON accounting;
- event-level JSONL logs;
- model-role benchmark tooling;
- split-key and cloud/local model experiments;
- focused regression tests for every major live bug found.

### Better Short-Timeframe Responsiveness

v2.5 moves slow LLM work off the short-timeframe hot path when needed, while keeping the larger agent reasoning available through background refresh and cached reports.

### Better Risk Accounting

v2.5 no longer treats failed executions, opens, or stale local closes as reliable realized PnL. It is more careful about when a trade is actually a trade.

### Better NanoFenix Integration

NanoFenix moved from a rigid directional companion toward a calibrated policy layer that can reason about uncertainty, net edge, and whether adding to a position is justified.

### More Honest Public Framing

The project now has enough data to say what improved and what did not. v2.5 should be publicized as a safer research release, not as a guaranteed profitable bot.

## Known Limitations to State Publicly

These should not be hidden in the release:

- FenixAI is still experimental trading software.
- Small live canaries have mixed results.
- Fees can consume a large part of gross edge.
- Some LLMs produce invalid or overly generic risk outputs unless guarded.
- Visual analysis is useful but can be too slow for short timeframes.
- NanoFenix is promising as a filter but not yet proven as a standalone driver.
- SOL 15m tests showed repeated over-short behavior in some market regimes.
- Opposite-signal exits and reversal handling have improved but should continue to be monitored.
- Paper results should not be treated as equivalent to live results without exchange-fill verification.

## Recommended Public v2.5 Message

Use this framing:

> FenixAI v2.5 is the result of several months of live, testnet, and paper experimentation after v2.0. The release focuses on making the bot safer to test, easier to inspect, and more honest about real execution behavior. It improves live position synchronization, protective order handling, exchange-aware sizing, runtime risk accounting, short-timeframe latency, model-role benchmarking, and NanoFenix companion integration. It is still experimental and should be tested in paper mode before any live use.

Avoid this framing:

> FenixAI v2.5 is profitable.

That is not supported by the current evidence.

## Suggested Release Notes Structure

For the public v2.5 release, use:

1. **What changed since v2.0**
   - execution safety;
   - risk accounting;
   - latency;
   - NanoFenix;
   - benchmarks;
   - documentation.
2. **Why those changes were necessary**
   - real failures found during testing;
   - examples of bugs fixed;
   - paper/live mismatches corrected.
3. **How to test safely**
   - paper mode first;
   - testnet next;
   - live only with small size and explicit flags.
4. **Known limitations**
   - mixed live canary results;
   - fees and churn;
   - model instability;
   - ongoing tuning.
5. **What is next**
   - better opposite-signal exits;
   - stronger regime classification;
   - better script organization;
   - public-safe benchmark reports;
   - continued NanoFenix calibration.

Use `docs/releases/v2.5-new-systems.md` alongside this file when explaining the component-level additions: NanoFenix, MiniFenix, Fenix Experimental, model-role teams, optional Web3 Intelligence, and live slot runners.
