# FenixAI v2.5 New Systems Guide

Status: release-candidate public documentation draft  
Scope: new subsystems and usage model added after the public v2.0 release  
Last updated: 2026-05-22

> FenixAI v2.5 should be presented as a broader research and reliability release than v2.0, not as a guaranteed profitable trading system.

## Why This Document Exists

The public v2.0 page described FenixAI as a LangGraph multi-agent trading bot with six core agents, ReasoningBank memory, a React dashboard, multi-provider LLM support, and Binance Futures execution.

v2.5 keeps that foundation, but the project has grown into a larger testing platform:

- **Fenix Core** remains the main multi-agent LLM trading engine.
- **NanoFenix** is now a high-frequency, zero-LLM companion signal engine.
- **MiniFenix** is a two-speed research prototype used to test slow-brain/fast-trigger ideas.
- **Fenix Experimental** connects the slow-brain/fast-trigger architecture back into Fenix-style agent snapshots.
- **Live slot runners** make paper, testnet, and small live canaries reproducible.
- **Model-role teams** let each agent use a different model instead of forcing one model across the whole stack.
- **Optional Web3 Intelligence code** exists as an experimental on-chain/social-data agent path, but it is not yet a default public trading dependency.

The main message for users is:

> v2.0 introduced the architecture. v2.5 explains what happened after months of real testing: the engine became safer to run, easier to measure, and more modular. The new subsystems exist because live markets exposed latency, execution, sizing, and market-adaptation problems that a pure LLM agent graph could not solve by itself.

## v2.0 Baseline vs v2.5 Additions

| Area | v2.0 public release | v2.5 public release |
| --- | --- | --- |
| Core architecture | LangGraph multi-agent engine | Same base, with more live-oriented fallback, timeout, validation, and runner controls |
| Agent team | Technical, Visual, Sentiment, QABBA, Decision, Risk | Same main team, with stronger Technical/QABBA weighting, stricter risk validation, cached/fallback paths, optional monolithic benchmark mode, and experimental Web3 Intelligence code |
| Memory | ReasoningBank + TradeMemory | ReasoningBank remains, with more explicit disable switches for controlled experiments |
| Execution | Binance Futures paper/testnet/live | Restart hydration, stale-state reconciliation, reduce-only exits, protective algo-order checks, margin-aware sizing, and event accounting |
| Model usage | Multi-provider LLM support | Per-agent model teams, Ollama Cloud benchmarks, DeepSeek v4 experiments, deterministic risk option |
| Short-timeframe research | Multi-timeframe support | NanoFenix, MiniFenix, fast-trigger experiments, nonblocking/cached agent paths |
| Testing | Manual paper/testnet flows | Live slot runner, live suite runner, JSONL event logs, summary JSON, paper/live parity checks |
| Documentation | v2.0 README and architecture docs | v2.5 release notes, development history, new systems guide, scripts index, release checklist |

## System Map

| System | Purpose | Runtime style | Public v2.5 status |
| --- | --- | --- | --- |
| Fenix Core | Main LLM multi-agent trading engine | LangGraph + Binance engine | Supported release-candidate path |
| NanoFenix v3.5 | Microstructure companion signal | WebSocket + 1s/5s bars + LightGBM | Experimental companion, recommended for research/paper comparison |
| MiniFenix | Two-speed architecture proof of concept | Slow LLM brain + fast WebSocket trigger | Research prototype, not the main live runner |
| Fenix Experimental | Bridge between Fenix agent snapshots and fast-trigger execution | Paper runner with SlowBrain/FastTrigger | Experimental paper runner |
| Live Slot Runner | Reproducible single run | One symbol/timeframe/model team | Preferred controlled test harness |
| Live Suite Runner | Reproducible sequence of slots | JSON plan runner | Preferred model/timeframe comparison harness |
| Web3 Intelligence | Smart-money/social/on-chain context | Binance Skills Hub-style data feeds + LLM | Prototype code, not default graph path |
| Monolithic Mode | Single-model benchmark path | One LLM produces decision + risk payload | Benchmark/control mode, not preferred production architecture |

## Fenix Core in v2.5

Fenix Core is still the main product. Users who ran v2.0 should think of v2.5 as the same core engine, but with a much more realistic live-testing layer around it.

### What changed

- The engine now treats exchange state as the source of truth when restarting live runs.
- Open Binance positions can be hydrated before the bot assumes it is flat.
- Opposite-side signals can close or reconcile exposure instead of accidentally creating confusing local state.
- Failed order attempts are not counted as realized trading losses.
- Protective-order verification checks Binance Futures algorithmic orders, not only normal open orders.
- Paper/hybrid execution rejects invalid zero/missing prices before logging position transitions.
- Runtime risk accounting distinguishes failed attempts, opens, closes, and realized close PnL.

### How to use it

Default paper mode remains the safest entry point:

```bash
python run_fenix.py
```

For a controlled slot test, use the v2.5 runner:

```bash
python scripts/run_fenix_live_slot.py \
  --symbol SOLUSDT \
  --timeframe 15m \
  --run-minutes 60 \
  --mode paper \
  --team-provider ollama_cloud \
  --team-models technical=nemotron-3-nano:30b-cloud,qabba=cogito-2.1:671b-cloud,decision=nemotron-3-nano:30b-cloud,risk_manager=glm-5:cloud
```

For live mode, the explicit live flag is still required:

```bash
python scripts/run_fenix_live_slot.py \
  --symbol SOLUSDT \
  --timeframe 15m \
  --run-minutes 60 \
  --mode live \
  --allow-live
```

Live mode uses real money. Paper mode should remain the public recommendation.

## NanoFenix v3.5

NanoFenix is the biggest new subsystem after v2.0.

It exists because the LLM graph is too slow for pure microstructure timing. Technical, QABBA, Visual, Sentiment, Decision, and Risk can reason about market context, but waiting for LLMs on every short-timeframe tick loses the microstructure edge. NanoFenix separates the problem:

- Fenix Core handles higher-level reasoning, risk, and execution policy.
- NanoFenix watches the market stream continuously and emits a compact companion signal.

### What NanoFenix does

NanoFenix v3.5 reads Binance WebSocket data, aggregates it into short bars, computes microstructure features, and predicts short-horizon directional movement.

Pipeline:

```text
Binance bookTicker + aggTrade
  -> 1s/5s bar aggregation
  -> multi-scale feature engine
  -> dual-horizon LightGBM predictors
  -> adaptive fusion / policy layer
  -> companion JSON signal
  -> optional Fenix engine policy checks
```

### Why it is different from Fenix agents

NanoFenix does not call an LLM on the hot path.

It uses:

- LightGBM-style online prediction;
- short and long horizon models;
- adaptive dual-horizon fusion;
- direction-accuracy tracking;
- confidence calibration;
- net actionable edge after uncertainty and fee buffer;
- companion readiness checks;
- paper executor for standalone testing.

### How Fenix uses NanoFenix

NanoFenix writes a JSON signal file. Fenix reads that file when companion mode is enabled.

NanoFenix can inform:

- whether a Fenix entry is confirmed;
- whether a signal is stale;
- whether the predicted edge is too small after uncertainty and fees;
- whether the companion is calibrated enough;
- whether a same-side add is allowed;
- whether an opposite-side exit needs confirmation;
- whether position size should be reduced.

Important policy fields include:

| Field | Meaning |
| --- | --- |
| `action` / `signal` | Companion direction: `BUY`, `SELL`, or `HOLD` |
| `confidence` | Calibrated confidence for the current signal |
| `pred_bps` / `expected_bps` | Expected movement in basis points |
| `edge_net_bps` | Edge after uncertainty and fee buffer |
| `uncertainty_bps` | Estimated forecast uncertainty |
| `calibration_health` | Whether recent calibration is reliable enough |
| `allow_execute` | Whether the policy considers the signal actionable |
| `allow_add_to_position` | Whether adding to the same side is allowed |
| `size_multiplier_hint` | Suggested size reduction/boost signal |
| `source` | Whether the decision came from consensus, fusion, short-only, long-only, or none |

### Recommended v2.5 NanoFenix run

Use NanoFenix v3.5 directly:

```bash
python run_nanofenixv3.py \
  --symbol SOLUSDT \
  --companion \
  --adaptive-fusion \
  --output-path logs/nanofenixv3_companion_solusdt.json
```

Then point Fenix Core to the companion file:

```bash
export FENIX_ENABLE_NANOFENIX_COMPANION=1
export FENIX_NANOFENIX_SIGNAL_PATH=logs/nanofenixv3_companion_solusdt.json
```

For stricter live testing, configure which NanoFenix reasons are hard vetoes:

```bash
export FENIX_NANOFENIX_HARD_VETO_REASONS=companion_not_ready,direction_mismatch,high_uncertainty,stale_signal,symbol_mismatch,signal_file_missing,signal_file_empty,signal_parse_error,missing_or_invalid_timestamp
```

### Current NanoFenix stance

NanoFenix should be described as a companion and calibration layer, not as an independent proof of profitability.

The latest testing showed useful behavior, but also real limitations:

- it can reduce churn by blocking weak entries;
- it can become too conservative;
- it can miss opportunities when calibration gates are too strict;
- fees can erase small gross wins;
- it needs more live data across trending and ranging regimes.

## MiniFenix

MiniFenix is a separate research prototype. It is not the main v2.5 runner.

Its job is to test the two-speed architecture:

- **Slow Loop / Brain**: an LLM periodically reads market context and publishes a short-lived trading regime.
- **Fast Loop / Trigger**: a WebSocket consumer processes book-ticker data quickly with quantitative features and ML/heuristics.

MiniFenix was useful because it showed that LLMs should not sit directly in the fastest execution path.

### MiniFenix architecture

```text
Binance bookTicker stream
  -> FastTrigger
  -> feature engine / SOTA predictor / quant math
  -> paper or testnet trader

SlowBrain
  -> periodic Ollama call
  -> regime: LONG, SHORT, or NEUTRAL
  -> max spread and OFI thresholds
  -> FastTrigger reads regime without blocking
```

### How to run MiniFenix

```bash
python run_minifenix.py
```

The model-sweep helper can compare LLMs for the slow brain:

```bash
python run_minifenix_model_sweep.py --duration 600 --symbol BTCUSDT
```

### What MiniFenix contributed to v2.5

MiniFenix influenced several v2.5 decisions:

- keep LLM reasoning off the hot path where possible;
- keep fast triggers deterministic or ML-based;
- make market regime a shared object instead of a blocking call;
- benchmark slow-brain models separately from execution logic;
- treat high-frequency execution as a different problem from high-level reasoning.

MiniFenix remains a lab. The public v2.5 documentation should present it as research that informed NanoFenix and the experimental runner, not as the recommended live trading system.

## Fenix Experimental

`fenix_experimental/` is the bridge between the MiniFenix idea and Fenix-style agent snapshots.

It uses:

- `SlowBrain` to publish a short-lived regime from Technical and QABBA reports;
- `FastTrigger` to process book-ticker/aggregate-trade style data;
- optional NanoFenix v3 adapter logic;
- an experimental paper runner that logs Fenix-like events.

This line is useful for testing whether Fenix can become a two-speed system:

```text
Fenix agents define regime
  -> fast trigger waits for microstructure confirmation
  -> paper runner records position events
```

It is not the default public release path yet. It is a research branch inside the repo that helps answer whether v2.6/v3.0 should move more execution timing out of the LLM graph.

## New and Updated Agents

v2.0 publicly documented six agents. v2.5 keeps those agents but changes how they are used.

### Technical Analyst

v2.0 Technical focused on RSI, MACD, ADX, SuperTrend, and EMA-style analysis.

v2.5 Technical is more timeframe-aware. It now participates in:

- market-regime context;
- support/resistance guards;
- trend-conflict detection;
- short-timeframe fallback/cached analysis paths;
- Decision Agent directional scoring.

### QABBA Agent

v2.0 QABBA focused on Bollinger Bands, volatility, squeeze detection, OBI, and CVD.

v2.5 QABBA became the main microstructure and volatility specialist:

- CHOP context;
- Donchian/Keltner/squeeze context;
- order-flow imbalance;
- trade imbalance;
- volume and liquidity interpretation;
- short-timeframe cached/fallback paths.

### Visual Analyst

The Visual Agent remains useful, but v2.5 treats it more carefully.

Visual analysis can be slow, especially with cloud vision models. v2.5 adds safer vision-model selection, timeout handling, and nonblocking/deferred behavior for short-timeframe research paths.

Public framing:

> Visual is valuable for context and pattern confirmation, but it is not required for every fast loop.

### Sentiment Analyst

Sentiment remains lower weight than Technical/QABBA in most live-style tests.

v2.5 adds:

- local news cache;
- smaller prompt payloads;
- faster fallback behavior;
- reduced weight in short-timeframe setups.

### Decision Agent

The Decision Agent changed from strict agreement toward synthesis.

v2.5 improvements:

- less rigid `HOLD` behavior;
- deterministic consensus fallback when the LLM times out or returns invalid JSON;
- directional score rebuilt from agent state;
- Web3 report fields can be included if available;
- better separation between final decision and risk payload.

### Risk Manager

The Risk Manager is one of the most important v2.5 hardening areas.

v2.5 improvements:

- deterministic ATR-style fallback/override paths;
- direction-aware SL/TP validation;
- rejected implausible LLM sizes;
- margin-aware notional caps;
- failed attempts separated from realized losses;
- close events tied to real fill accounting when possible.

### Web3 Intelligence Agent

The repo now contains a Web3 Intelligence agent prototype. Its purpose is to analyze:

- smart-money signals;
- social hype rankings;
- token rankings;
- smart-money inflow;
- meme-rush context;
- token snapshot/security data.

Current v2.5 status:

- the agent code and validation rules exist;
- the Decision Agent can consume `web3_intel_report` if present;
- `scripts/run_live_web3_monitor.py` is an experimental monitor path;
- the default public Fenix graph should not depend on it yet.

This should be documented as experimental because the integration is not as mature as Technical/QABBA/Decision/Risk.

## Model-Role Teams

v2.0 supported multiple providers. v2.5 goes further by assigning different models to different agent roles.

Example:

```bash
--team-models technical=nemotron-3-nano:30b-cloud,qabba=cogito-2.1:671b-cloud,visual=gemini-3-flash-preview:cloud,decision=nemotron-3-nano:30b-cloud,risk_manager=glm-5:cloud
```

Why this matters:

- Technical and QABBA need directional discipline and market structure.
- Visual needs image support.
- Decision needs synthesis and JSON reliability.
- Risk needs conservative sizing and valid stop/take-profit levels.

DeepSeek v4 Flash and DeepSeek v4 Pro were tested through Ollama Cloud, but they should be described as experimental options until more stable role-specific live testing is available.

## Live Slot and Suite Runners

v2.5 added better ways to test the bot repeatedly.

### Single slot

```bash
python scripts/run_fenix_live_slot.py --symbol ETHUSDT --timeframe 15m --run-minutes 60 --mode paper
```

Outputs:

- `logs/live_slot_events_*.jsonl`
- `logs/live_slot_summary_*.json`

### Suite

```bash
python scripts/run_fenix_live_suite.py --plan plans/example.json --mode paper
```

The suite runner is useful for comparing:

- model teams;
- symbols;
- timeframes;
- risk settings;
- monolithic vs multi-agent runs;
- NanoFenix companion settings.

## Recommended Public Explanation

Use this wording in public v2.5 materials:

> FenixAI v2.5 expands the original v2.0 multi-agent trading bot into a modular research platform. Fenix Core remains the main LangGraph system, while NanoFenix adds a zero-LLM microstructure companion, MiniFenix demonstrates the slow-brain/fast-trigger architecture, and the live slot runners make paper/testnet/live canaries easier to reproduce. The release focuses on safer execution, better observability, model-role specialization, and honest paper/live comparison.

Avoid this wording:

> v2.5 proves the bot is profitable.

The current evidence does not support that claim.

## What Should Be Public in v2.5

Recommended public release surface:

- `run_fenix.py`
- `scripts/run_fenix_live_slot.py`
- `scripts/run_fenix_live_suite.py`
- `run_nanofenixv3.py`
- `run_minifenix.py`
- `run_minifenix_model_sweep.py`
- `docs/releases/v2.5.md`
- `docs/releases/v2.5-development-history.md`
- `docs/releases/v2.5-new-systems.md`
- `docs/releases/v2.5-script-evolution.md`
- `docs/NANOFENIX_HTF_V2_5_CHANGES.md`
- `scripts/README.md`

Keep historical launchers as reproducibility artifacts unless a release note explicitly recommends them.

## Remaining Documentation Work

- Review remaining Spanish MiniFenix runtime messages and comments if the code itself will be part of the public v2.5 surface.
- Decide whether `scripts/run_nanofenix_companion_signal.sh` should be updated to v3.5 or left as a legacy v2 wrapper.
- Add a concise v2.5 architecture diagram once the public release surface is final.
- Review all launch scripts for hardcoded local paths, private run tags, old API-key assumptions, or live-account artifacts.
- Review `docs/releases/v2.5-script-evolution.md` before publishing so internal live canary templates are not mistaken for generic public live commands.
