Architecture
End-to-end system architecture of FeedRight — from sensor inputs to feed actuation and adaptive retraining.
Component Overview
FeedRight is composed of five major subsystems that form a closed-loop control pipeline:
| Subsystem | Module | Responsibility |
|---|---|---|
| Video Analysis | backend/experimental_routes.py | YOLO-based fish detection, biomass estimation, and feeding-behaviour feature extraction |
| Environment | lib/dqn_sb3/env.py | Wraps the 44-feature state space and reward logic as a Gymnasium environment |
| DQN Agent | lib/dqn_sb3/agent.py | Loads a trained Stable-Baselines 3 model, selects actions, applies safety constraints |
| Trainer | lib/dqn_sb3/train.py | Trains and evaluates the DQN model with checkpointing and TensorBoard logging |
| Adaptive Loop | lib/dqn_sb3/adaptive_retrain.py, experience_db.py, monitoring.py | Stores real outcomes, retrains on field data, tracks performance drift |
Data Flow Diagram
┌─────────────┐
│ Underwater │
│ Camera │
└──────┬──────┘
│ video frames
┌───────────┴───────────┐
▼ ▼
┌───────────────────┐ ┌───────────────────────┐
│ YOLO Fish Model │ │ YOLO Pellet Model │
│ (BiomassAnalyzer)│ │ (BehaviorAnalyzer) │
│ bbox → L, G, W │ │ uneaten pellet count │
│ per-fish weight │ │ pellet sinking time │
└────────┬──────────┘ └──────────┬────────────┘
│ │
│ ┌─────────────────┐ │
│ │ Optical Flow │ │
│ │ (Farnebäck) │ │
│ │ motion, frenzy │ │
│ │ surface ratio │ │
│ └───────┬─────────┘ │
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────────────────────┐ ┌──────────────┐
│ IoT │──►│ State Constructor │◄──│ Farm DB │
│ Sensors │ │ (44 normalised dims) │ │ (feeding │
│ (DO,temp │ │ │ │ history, │
│ wind…) │ └────────────┬─────────────┘ │ cage meta) │
└──────────┘ │ └──────────────┘
▼
┌─────────────────────┐
│ CageFeedingAgent │
│ ├─ DQN.predict() │
│ └─ safety_override │
└─────────┬───────────┘
│ action (0–5)
▼
┌─────────────────────┐
│ Automatic Feeder │
│ (0 / 0.5 / 1 / 2 │
│ / 3.5 / 5.0 kg) │
└─────────┬───────────┘
│ outcome measured
▼
┌─────────────────────┐
│ ExperienceDatabase │
│ (SQLite) │
│ ├─ experiences │
│ ├─ model_perf │
│ └─ retrain_hist │
└─────────┬───────────┘
│ periodic
▼
┌─────────────────────────┐
│ AdaptiveRetrainingService│
│ prefill replay buffer │
│ continue training │
│ evaluate & deploy │
└─────────────────────────┘Video Analysis Pipeline
The video and biomass features for the 44-dimension state vector are derived from YOLO detection models and dense optical flow. The pipeline produces 11 features: 6 Biomass features (indices 13–18) from YOLO fish detection with allometric weight estimation, and 5 Video features (indices 19–23) from spatial motion analysis, temporal dynamics, and optional pellet detection.
For the full methodology, signal sources, and feature computation details, see the dedicated Video Analysis page.
Gymnasium Environment (FishFeedingEnv)
The environment conforms to the Gymnasium gym.Env interface:
- Observation space:
Box(low=0, high=1, shape=(44,), dtype=float32)— all features normalised to[0, 1]. - Action space:
Discrete(6)— mapped to concrete feed amounts viaaction_to_kg. - Transition model (
_transition_state): Updates feeding history, hunger, motion intensity, and adds stochastic environmental noise. - Reward function (
_calculate_reward): Multi-factor shaped reward detailed in the Reward System page. - Episode termination: After
max_feeds_per_episode(default 6) feed actions have been executed.
CageFeedingAgent
CageFeedingAgent (lib/dqn_sb3/agent.py) wraps the trained DQN model for production use:
- Accepts either a dictionary of named features or a raw 44-dimensional array.
- Normalises and passes the state to
DQN.predict(obs, deterministic=True). - Maps the discrete action to kg via
env.action_to_kg. - Applies the Safety Constraint Layer.
- Returns a decision object with
feed_amount,is_safe,confidence,raw_prediction, andactionindex. - Optionally records the outcome to
ExperienceDatabasefor adaptive learning.
Each cage runs its own agent instance, identified by cage_id, enabling per-cage model specialisation in the future.