Purpose
This document describes the GAIA EDGE precision agriculture AI platform — what it does, how it works, what it depends on, and what the critical path to delivery looks like. Written by UV based on confirmed project artefacts, sprint documentation, and the project README.
Field Classification
| Marker | Meaning |
|---|---|
| [M] | MANDATORY — requires confirmed information from client or domain research. Cannot be invented. |
| [D] | DERIVED — UV proposes based on experience. Client confirms or corrects. |
Section 01 — Overview [M]
| Field | Value |
|---|---|
| Use Case ID | UC-GAIA |
| Client Reference [M] | GAIA EDGE — Precision Agriculture Platform |
| System Name [M] | GAIA EDGE |
| Domain [M] | Precision Agriculture / AgriTech / Edge AI |
| One-Line Description [M] | End-to-end AI platform combining computer vision, tabular ML, IoT sensor data, and real-time weather APIs into a unified Streamlit dashboard for precision farming on GPU-accelerated liquid immersion infrastructure. |
| Status [M] | Production (8 sprints complete) |
| Target Delivery [M] | March 2026 (delivered) |
Summary [M]
GAIA EDGE is a sovereign AI-driven precision agriculture platform built on an NVIDIA GB10 edge device and targeting scale-up to an HP Z4 rack server immersed in Oleon Qloe dielectric fluid. It demonstrates sustainable high-performance AI infrastructure applied to real-world agricultural use cases.
The platform delivers eight production AI models across six agricultural domains: crop disease detection (27-class YOLOv8s), crop health classification (8-class ResNet-50 at 99.66% accuracy), fruit ripeness/harvest timing (4-class ResNet-18), crop yield prediction (LightGBM/XGBoost/RandomForest ensemble), crop recommendation (22-class RandomForest), and IoT-based irrigation advisory (LightGBM at 100% accuracy). A real-time weather outlook integrates the Open-Meteo API for 7-day forecasting.
All capabilities are surfaced through a 9-page Streamlit dashboard with executive/technical toggle views, custom CSS theming, and a Nexus capstone dashboard providing live pipeline visualisation, KPIs, and a model registry.
Section 02 — Actors [M]
| Role [M] | Description [M] | Access Level [D] | Frequency [D] |
|---|---|---|---|
| Executive / C-Suite | Reviews high-level KPIs, sustainability narrative, model performance summaries | Executive View toggle — summary dashboards, no model controls | Weekly |
| Agronomist / Field Operator | Uploads crop images for disease detection, checks soil/harvest advisories, reviews weather outlook | Full dashboard access — inference, advisory tools, technical appendix | Daily |
| Data Scientist / ML Engineer | Trains and evaluates models, reviews technical appendix, manages MLflow experiments, rebuilds TRT engines | Full access including training scripts, MLflow, CLI tools | As needed (sprint cycles) |
| Platform Engineer | Deploys platform to new hardware, manages Docker containers, rebuilds TensorRT engines, configures environments | SSH/CLI access, Docker, environment configuration | On deployment events |
| Demo Audience | Views live inference demos and sustainability narrative during presentations | Read-only dashboard access with demo trace mode | Ad hoc |
Section 03 — User Stories [M/D]
Actor: Executive / C-Suite
- P1 [M]: As an executive, I want to see a single-page snapshot of all model performance KPIs, so that I can assess platform readiness at a glance.
- P1 [M]: As an executive, I want to toggle between executive and technical views, so that I see only the level of detail relevant to me.
- P2 [D]: As an executive, I want to view the sustainability narrative (liquid immersion cooling benefits), so that I can communicate the infrastructure story to stakeholders.
Actor: Agronomist / Field Operator
- P1 [M]: As an agronomist, I want to upload a crop leaf image and receive a disease detection result with bounding boxes and confidence scores, so that I can identify field issues quickly.
- P1 [M]: As an agronomist, I want to input soil parameters (N, P, K, pH, temperature, humidity, rainfall) and receive a crop recommendation, so that I can plan planting decisions.
- P1 [M]: As an agronomist, I want to view a 7-day weather forecast for my location, so that I can plan field operations around weather conditions.
- P1 [M]: As an agronomist, I want to upload fruit images and receive a ripeness classification (unripe/nearly_ripe/ripe/overripe), so that I can time harvests optimally.
- P2 [D]: As an agronomist, I want to input IoT sensor readings and receive an irrigation recommendation, so that I can manage water resources efficiently.
- P2 [D]: As an agronomist, I want to see crop yield predictions based on climate and soil features, so that I can forecast production volumes.
Actor: Data Scientist / ML Engineer
- P1 [M]: As a data scientist, I want to review per-model metrics (accuracy, mAP, RMSE, confusion matrices), so that I can evaluate model quality.
- P1 [M]: As a data scientist, I want to retrain models using provided scripts with configurable hyperparameters, so that I can iterate on model performance.
- P2 [D]: As a data scientist, I want to view SHAP explainability outputs for yield predictions, so that I can understand feature importance.
- P2 [D]: As a data scientist, I want to compare PyTorch FP32 vs TensorRT FP16 inference benchmarks, so that I can quantify optimisation gains.
Actor: Platform Engineer
- P1 [M]: As a platform engineer, I want to rebuild the TensorRT engine on new hardware with a single command, so that the object detector runs optimally on the target GPU.
- P1 [M]: As a platform engineer, I want a clear environment setup procedure (venv, CUDA, dependencies), so that I can deploy the platform on a new machine within an hour.
- P3 [D]: As a platform engineer, I want Docker containers for both development and Streamlit serving, so that I can standardise deployments.
Section 04 — System Flows [M/D]
Flow: Crop Disease Detection [M]
Trigger [M]: User uploads a crop leaf image via the Crop Disease Detection Streamlit page.
| # | Step [M] | Actor [M] | Input [M] | Output [D] | Decision [M] |
|---|---|---|---|---|---|
| 1 | Upload image | Agronomist | JPEG/PNG crop leaf image | — | — |
| 2 | Preprocess image | System | Raw image | Resized 640×640 tensor | — |
| 3 | Run YOLOv8s inference | System | Preprocessed tensor | Bounding boxes + class probabilities | TRT engine available? → Use FP16; else → PyTorch FP32 |
| 4 | Apply confidence threshold | System | Raw detections | Filtered detections (conf ≥ threshold) | — |
| 5 | Render annotated image | System | Filtered detections + original image | Annotated image with bounding boxes, class labels, confidence scores | — |
| 6 | Display results | System | Annotated image + detection summary | Dashboard view | — |
Result [M]: Annotated image displayed with disease class labels, bounding boxes, confidence scores, and inference latency.
Exceptions [D]: No detections above threshold → display "No diseases detected" message. Invalid image format → display upload error. TRT engine missing → fallback to PyTorch FP32 inference with warning.
SLA [D]: < 500ms end-to-end (TRT FP16: ~5ms inference, ~200ms total with pre/post processing and rendering).
Volume [M]: Ad hoc — estimated 10–50 images per session during field assessments or demos.
Flow: Crop Yield Prediction [M]
Trigger [M]: User navigates to the Yield Outcome page and inputs climate/soil feature values.
| # | Step [M] | Actor [M] | Input [M] | Output [D] | Decision [M] |
|---|---|---|---|---|---|
| 1 | Input features | Agronomist | Climate and soil parameters | — | — |
| 2 | Load preprocessor | System | preprocessor.pkl |
Scaled feature vector | — |
| 3 | Run ensemble inference | System | Scaled features | Predictions from LightGBM, XGBoost, RandomForest | — |
| 4 | Aggregate results | System | Three predictions | Ensemble prediction + individual model breakdown | — |
| 5 | Generate explainability | System | Feature values + model | SHAP waterfall/summary plots | — |
| 6 | Display results | System | Prediction + SHAP plots | Dashboard view with metrics and explainability | — |
Result [M]: Yield prediction displayed with per-model breakdown and SHAP explainability visualisations.
Exceptions [D]: Missing required features → validation error shown. Model file not found → graceful error with instruction to retrain.
SLA [D]: < 2 seconds end-to-end.
Volume [M]: Low — estimated 5–20 predictions per session.
Flow: Soil / Crop Recommendation [M]
Trigger [M]: User inputs soil parameters on the Soil Advisor page.
| # | Step [M] | Actor [M] | Input [M] | Output [D] | Decision [M] |
|---|---|---|---|---|---|
| 1 | Input soil parameters | Agronomist | N, P, K, temperature, humidity, pH, rainfall | — | — |
| 2 | Load model + encoder | System | crop_recommender.pkl, label_encoder.pkl |
— | — |
| 3 | Run classification | System | Feature vector | Predicted crop class (1 of 22) | — |
| 4 | Check IoT irrigation | System | Sensor readings (if available) | Irrigate / Don't irrigate | IoT data available? → run LightGBM; else → skip |
| 5 | Display recommendation | System | Crop class + irrigation advisory | Dashboard view | — |
Result [M]: Recommended crop displayed with confidence. If IoT sensor data provided, irrigation advisory also shown.
Exceptions [D]: Out-of-range values → warning displayed. Model not found → error with retrain instructions.
SLA [D]: < 1 second.
Volume [M]: Low-medium — 10–30 queries per session.
Flow: TensorRT Engine Rebuild [M]
Trigger [M]: Platform deployed to new GPU hardware or TensorRT version updated.
| # | Step [M] | Actor [M] | Input [M] | Output [D] | Decision [M] |
|---|---|---|---|---|---|
| 1 | Set environment variables | Engineer | PYTORCH_NVFUSER_DISABLE=1, TORCHDYNAMO_DISABLE=1 |
— | — |
| 2 | Run build script | Engineer | python sprints/sprint_6/build_trt_engine.py --force |
— | — |
| 3 | Export ONNX | System | best.pt weights |
yolov8s.onnx (FP32) |
— |
| 4 | Build TRT engine | System | ONNX model | yolov8s_fp16.engine (GPU-specific binary) |
— |
| 5 | Run benchmark | Engineer | python sprints/sprint_6/benchmark.py |
benchmark_results.json |
— |
| 6 | Validate | Engineer | Benchmark results | Confirmed FPS/latency baseline | — |
Result [M]: GPU-specific TensorRT FP16 engine built and benchmarked. Baseline performance established.
Exceptions [D]: CUDA context error → apply torch.cuda.init() fix (documented). Unsupported GPU arch → fallback to PyTorch inference.
SLA [D]: 3–8 minutes for engine build. Benchmark < 2 minutes.
Volume [M]: Per deployment event (rare — new hardware only).
Section 05 — Data Model [M/D]
Entities
| Entity [M] | Description [M] | Key Fields [M] | States [D] | Relationships [D] |
|---|---|---|---|---|
| CropImage | Input image for disease detection or health classification | image_path, upload_timestamp, resolution | uploaded → preprocessed → inferred | → Detection, → HealthClassification |
| Detection | YOLOv8s bounding box prediction | class_id, confidence, bbox_coords, image_ref | raw → filtered → displayed | → CropImage, → ClassNameMap |
| HealthClassification | ResNet-50 crop health prediction | class_label, confidence, image_ref | predicted → displayed | → CropImage |
| YieldPrediction | Regression output from ensemble | model_name, predicted_yield, features_used | computed → displayed | → FeatureSet |
| CropRecommendation | Soil-based crop suggestion | soil_params (N,P,K,pH,temp,humidity,rainfall), predicted_crop | computed → displayed | → SoilFeatureSet |
| IrrigationAdvisory | IoT sensor-based irrigation decision | sensor_readings (temp, humidity, water_level, N, P, K), recommendation | computed → displayed | → IoTSensorData |
| HarvestClassification | Fruit ripeness prediction | class_label (unripe/nearly_ripe/ripe/overripe), confidence | predicted → displayed | → CropImage |
| WeatherForecast | 7-day forecast from Open-Meteo | location, date_range, temperature, precipitation, wind | fetched → cached → displayed | — (external API) |
| TrainedModel | Serialised model artefact | model_path, model_type, metrics, sprint_origin | trained → serialised → deployed | → ModelMetrics |
| TRTEngine | TensorRT compiled engine | engine_path, gpu_arch, trt_version, precision | built → benchmarked → deployed | → TrainedModel |
Business Rules [M/D]
| ID | Rule [M] | Trigger [D] | On Violation [D] |
|---|---|---|---|
| BR-01 | TensorRT engines must be rebuilt when deploying to a different GPU architecture or TRT version | Platform deployment to new hardware | Block inference; display rebuild instruction |
| BR-02 | YOLOv8 data YAML must use absolute paths matching the deployment machine | Training or dataset setup | Training fails with path-not-found error; display update instruction |
| BR-03 | Environment variables PYTORCH_NVFUSER_DISABLE=1 and TORCHDYNAMO_DISABLE=1 must be set on sm_120+ GPUs |
Application or training startup | PyTorch nvfuser crash or torch.compile interference |
| BR-04 | CUDA context must be explicitly initialised before calling trt.Builder() |
TRT engine build | TypeError: pybind11::init(): factory function returned nullptr; apply documented fix |
| BR-05 | Model .pt and .pkl files are platform-independent and transfer without rebuild |
Platform migration | N/A — informational |
| BR-06 | Datasets are not committed to the repository; must be re-downloaded via Kaggle API on new deployments | Fresh clone / new platform | Missing data errors; run Kaggle download commands |
| BR-07 | Detection confidence threshold must be applied before displaying results to users | Inference pipeline | False positive overload if threshold bypassed |
Section 06 — Screens [D]
| Screen [D] | Actor [M] | Purpose [D] | Key Elements [D] |
|---|---|---|---|
| Executive Snapshot (Home) | Executive, Agronomist | Platform overview with summary KPIs for all models | Model count, accuracy summaries, infrastructure status, sustainability narrative |
| Yield Outcome | Agronomist, Data Scientist | Crop yield prediction with ensemble model comparison | Feature input form, per-model predictions, ensemble result, decision levers |
| Technical Appendix | Data Scientist | Deep-dive multi-tab technical analysis of yield models | SHAP plots, feature importance, model comparison tables, hyperparameter details |
| Crop Health Intelligence | Agronomist, Data Scientist | 8-class crop health image classification | Image upload, ResNet-50 prediction, confidence bar, class breakdown |
| Crop Disease Detection | Agronomist, Data Scientist | 27-class YOLOv8s object detection on leaf images | Image upload, annotated output image, bounding boxes, class labels, confidence scores, TRT/PyTorch toggle |
| Weather Outlook | Agronomist | 7-day weather forecast via Open-Meteo API | Location input, temperature chart, precipitation, wind speed, daily summary |
| Soil Advisor | Agronomist | Crop recommendation + IoT irrigation advisory | Soil parameter sliders (N,P,K,pH,temp,humidity,rainfall), recommended crop, irrigation status |
| Harvest Window | Agronomist | Fruit ripeness classification for harvest timing | Image upload, ripeness class prediction (4-class), confidence, harvest recommendation |
| Nexus — GAIA EDGE | Executive, Demo Audience | Capstone dashboard with live pipeline canvas | Pipeline visualisation, model registry, KPI grid, system health, demo trace timeline |
All screens share a global CSS theme (dark palette: #07100d background, #4fa865 primary green, #d4a227 harvest amber accent). Executive/Technical view toggle available globally via sidebar.
Section 07 — Integrations [M]
| System [M] | Direction [M] | Data [M] | Format [D] | Frequency [M] | Fallback [D] |
|---|---|---|---|---|---|
| Open-Meteo API | In | 7-day weather forecast (temperature, precipitation, wind, humidity) | REST JSON | On-demand per page load | Cache last successful response; display stale data warning |
| Kaggle API | In | Training datasets (crop detection, PlantVillage, fruit ripeness, crop recommendation, IoT soil) | CLI download + unzip | One-time per deployment / dataset refresh | Manual download via browser; place in expected directory structure |
| MLflow (local) | Both | Experiment tracking — metrics, parameters, artefacts | Local file store (./mlruns/) |
Per training run | Graceful degradation — training proceeds without tracking |
| DVC (local) | Both | Data version control metadata | Local disk remote | Per data change | Manual file management |
| TensorRT Runtime | In | Compiled FP16 inference engine | Binary .engine file |
On inference request | Fallback to PyTorch FP32 inference |
Section 08 — Infrastructure [D]
| Layer | Choice [D] | Reason [D] |
|---|---|---|
| Hosting | NVIDIA GB10 edge device (MVP) → HP Z4 rack server in Oleon Qloe liquid immersion (production) | Edge AI inference requirement; liquid immersion for sustained GPU boost clocks and sustainability narrative |
| Database | File-based (.pkl, .pt, .json, .csv) + MLflow file store |
No relational DB needed — all models serialised to disk; MLflow tracks experiments locally |
| Frontend | Streamlit (multi-page st.navigation API) |
Rapid prototyping, Python-native, built-in data visualisation, executive-friendly |
| Runtime | Python 3.12 + PyTorch 2.10.0+cu128 + TensorRT 10.15.1.29 | NVIDIA GPU stack alignment; TRT for inference acceleration |
| Containerisation | Docker (Dockerfile.dev + Dockerfile.streamlit) | Reproducible environments; deployment portability |
| Experiment Tracking | MLflow (local) | Lightweight; no server infrastructure required |
| Data Versioning | DVC (local disk remote) | Dataset reproducibility without committing large files to Git |
Constraints [M]
- GPU dependency: All computer vision inference requires an NVIDIA GPU with CUDA 12.x. No CPU-only fallback for production workloads.
- TRT portability: TensorRT engines are GPU-architecture-specific binaries. Must be rebuilt per target GPU.
- aarch64 vs x86_64: Different wheel families required for TensorRT and PyTorch depending on architecture.
- Data residency: Datasets sourced from Kaggle (public). No client-specific data residency requirements confirmed.
Environments [D]
| Environment | Purpose |
|---|---|
| Development (GB10) | Local training, inference, dashboard development on NVIDIA GB10 edge device |
| Production (Liquid Immersion) | HP Z4 rack server immersed in Oleon Qloe fluid — sustained high-performance inference and demo |
| Docker (dev) | Containerised development environment (Dockerfile.dev) |
| Docker (Streamlit) | Containerised dashboard serving (Dockerfile.streamlit) |
Section 09 — Critical Path [D]
| # | Item [D] | Depends On | Duration [D] | Blocker Risk [D] |
|---|---|---|---|---|
| 1 | Environment setup (Python 3.12, CUDA, venv, dependencies) | Hardware access | 1–2 hours | Low — well-documented in README |
| 2 | Dataset download (Kaggle API, 5 datasets) | #1 + Kaggle credentials | 30–60 minutes | Low — public datasets |
| 3 | Model artefact transfer (.pt, .pkl, .onnx files) |
#1 | 10 minutes | Low — platform-independent |
| 4 | TensorRT engine rebuild | #1 + #3 + GPU available | 3–8 minutes | Medium — GPU architecture must be confirmed; CUDA context fix may be needed |
| 5 | Benchmark validation | #4 | 5 minutes | Low |
| 6 | YOLO data YAML path update | #2 | 5 minutes | Low — single path edit |
| 7 | Streamlit dashboard launch & validation | #1 + #3 | 5 minutes | Low |
| 8 | Full end-to-end validation (all 9 pages) | #2 + #4 + #7 | 30 minutes | Low |
Parallel Work (off critical path) [D]
| Item | Can Start After | Duration |
|---|---|---|
| Docker image builds | #1 | 15 minutes |
| MLflow experiment review | #1 | 10 minutes |
| Documentation review | Immediate | 30 minutes |
| Model retraining (if desired: larger model / more epochs) | #2 + #6 | 1–4 hours |
Milestones [D]
| Milestone | Reached When | Target Date |
|---|---|---|
| M1: Environment operational | Python, CUDA, all dependencies installed and verified | Day 1 of deployment |
| M2: All models loaded | .pt and .pkl artefacts load successfully; inference runs on test input |
Day 1 of deployment |
| M3: TRT engine rebuilt | FP16 engine compiled for target GPU; benchmark confirms expected FPS | Day 1 of deployment |
| M4: Dashboard live | All 9 Streamlit pages render correctly with model inference | Day 1 of deployment |
| M5: Production validated | Full end-to-end testing complete; new benchmark baseline established | Day 1–2 of deployment |
Section 10 — What Is Needed [M]
| # | Item [M] | From [M] | Blocking [M] | Status [M] |
|---|---|---|---|---|
| 1 | Target GPU architecture confirmed (sm_XX, VRAM, CUDA version) | Platform team | Yes — required for TRT engine build | Open |
| 2 | SSH / physical access to liquid immersion platform | Infrastructure team | Yes — cannot deploy without access | Open |
| 3 | Kaggle API credentials (kaggle.json) |
Data team / existing credentials | Yes — required for dataset download | Received (exists in repo root) |
| 4 | Python 3.12 available on target platform | Platform team | Yes — runtime dependency | Open |
| 5 | NVIDIA CUDA 12.x toolkit on target platform | Platform team | Yes — GPU inference dependency | Open |
| 6 | Network access for Open-Meteo API (outbound HTTPS) | Network team | No — weather page degrades gracefully | Open |
| 7 | Network access for PyPI / NVIDIA PyPI (outbound HTTPS) | Network team | Yes — dependency installation | Open |
Section 11 — Acceptance Criteria [M/D]
Definition of Done [D]
| Criterion [D] | Verified By [D] |
|---|---|
| All 9 Streamlit pages render without error | Manual page-through of every page |
| YOLOv8s inference returns valid detections on test images | Upload test image → verify bounding boxes + class labels |
| TensorRT FP16 engine built and benchmarked on target GPU | benchmark_results.json generated with FPS > PyTorch baseline |
All .pt and .pkl models load successfully |
Each model page invoked without import/load error |
| Crop recommendation returns valid crop class for known input | Input known soil params → verify expected crop output |
| Weather outlook returns live forecast | Open weather page → verify 7-day forecast renders |
| Executive/Technical view toggle works across all pages | Toggle sidebar switch → verify UI changes |
| Environment variables set correctly | python -c "import torch; print(torch.cuda.get_device_name(0))" succeeds |
Success Metrics (30/60/90 days) [M]
| Metric [M] | Target [M] | Measured By [D] |
|---|---|---|
| YOLOv8s TRT FP16 inference FPS on target GPU | ≥ 197.5 FPS (GB10 baseline) or higher | benchmark_results.json |
| All 8 production models operational | 8/8 models loadable and producing valid output | Manual smoke test per model |
| Dashboard uptime during demo sessions | 100% (no crashes during live demo) | Observation during demo events |
| Crop health classifier accuracy maintained | ≥ 99% on PlantVillage test set | Re-evaluation script |
| Platform deployment time (clean machine → fully operational) | < 2 hours | Timed deployment run |
Section 12 — Risks [D]
| # | Risk [D] | Likelihood [D] | Impact [D] | Mitigation [D] |
|---|---|---|---|---|
| R1 | Target GPU architecture incompatible with TensorRT 10.15 | Low | High — blocks TRT inference | Confirm GPU sm_XX before deployment; fallback to PyTorch FP32 |
| R2 | PyTorch sm_121 nvfuser warning causes unexpected behaviour on new GPU | Medium | Medium — training/inference errors | Set PYTORCH_NVFUSER_DISABLE=1; test incrementally |
| R3 | Liquid immersion platform has no outbound internet → cannot download datasets or pip packages | Medium | High — blocks setup | Pre-package wheels and datasets on transfer media; offline pip install |
| R4 | CUDA version mismatch (driver vs PyTorch build) | Low | High — GPU inference fails entirely | Verify nvidia-smi and nvcc --version before installing PyTorch; match index URL |
| R5 | Kaggle dataset structure changes break training scripts | Low | Medium — retraining fails | Pin dataset versions; validate directory structure post-download |
| R6 | Large model files exceed Git/CodeCommit size limits | Medium | Low — deployment friction | Use Git LFS or S3 model storage |
| R7 | Streamlit version upgrade breaks st.navigation API |
Low | Medium — dashboard non-functional | Pin Streamlit version in requirements.txt |
Open Questions [M]
| # | Question [M] | Impacts [D] | Resolution [M] |
|---|---|---|---|
| Q1 | What is the exact GPU model and compute capability on the liquid immersion platform? | TRT engine build, benchmark targets, batch size tuning | Must be answered before deployment |
| Q2 | Is the target platform aarch64 or x86_64? | PyTorch wheel selection, TRT wheel family (cu12 vs cu13) |
Must be answered before dependency installation |
| Q3 | Does the immersion platform have outbound internet access? | Dataset download, pip install, weather API | Must be answered to plan offline/online deployment |
| Q4 | What is the target Streamlit serving port (8501 default or custom)? | Firewall rules, reverse proxy config | Confirm before go-live |
| Q5 | Will the platform serve multiple concurrent users or single-user demo? | Streamlit worker config, GPU memory management | Confirm to size infrastructure |
Section 13 — Cooperator Brief [D]
| Field | Value |
|---|---|
| Scope [D] | Deploy the complete GAIA EDGE precision agriculture AI platform (8 models, 9 Streamlit pages, TensorRT inference) onto a liquid immersion cooled GPU server. No new model development required — all artefacts exist. |
| Stack [D] | Python 3.12, PyTorch 2.10.0+cu128, TensorRT 10.15.1.29, Ultralytics 8.4.18, Streamlit, LightGBM, XGBoost, scikit-learn, Plotly, MLflow, DVC, Docker |
| Timeline [D] | M1–M4: Day 1 (environment + models + TRT + dashboard). M5: Day 2 (full validation + benchmark baseline). |
| Dependencies [D] | GPU hardware access, CUDA 12.x, Python 3.12, network access (or offline packages), Kaggle credentials |
| Interfaces [D] | Receives: Crop images (JPEG/PNG), soil parameters (manual input), IoT sensor data (manual input), weather data (Open-Meteo API). Delivers: Disease detections, crop recommendations, yield predictions, harvest advisories, weather forecasts — all via Streamlit dashboard. |
| Quality Bar [D] | All 8 models pass smoke test. TRT engine builds without error. All 9 pages render. Benchmark results recorded. No unit test regressions. |
| Handover [D] | Operational Streamlit dashboard on target platform, new benchmark_results.json and hardware_benchmark_results.json, updated data_abs.yaml with target paths, deployment log confirming all checklist items complete. |
Section 14 — Proposed Unified Architecture (Phase 2)
> Status: Proposed — under review. This section captures the target architecture for the next phase of GAIA EDGE deployment, integrating Atlas, NeXus, Chameleon, and deltaPrism into a unified sovereign stack.
Layer 1 — Hardware + Infrastructure
Target Deployment: HP Z4R (France)
| Spec | Value |
|---|---|
| RAM | 256GB DDR5 ECC |
| CPU | 24C / 48T Intel |
| GPU | NVIDIA Blackwell RTX Pro |
| Storage | Local NVMe scratch |
| Cooling | Immersion cooled in Qloe dielectric fluid |
| Enclosure | GRC Micro tank |
Edge Compute Characteristics:
- Low-latency inference
- High sustained GPU utilisation
- No thermal throttling
- High power density
- Sovereign local inference
Layer 2 — Core AI Runtime (Gaia Edge Runtime)
Responsibilities:
- Vision inference
- TensorRT engines
- Sensor ingestion
- Weather ingestion
- Time-series analytics
- Streamlit dashboards
Core Technologies:
| Technology | Role |
|---|---|
| PyTorch | Model training and FP32 inference |
| TensorRT | FP16 accelerated inference |
| ONNX | Model portability and export |
| OpenCV | Image pre/post processing |
| Streamlit | Dashboard UI layer |
| LightGBM | Tabular ML (irrigation, yield) |
| XGBoost | Ensemble yield prediction |
| YOLOv8 | 27-class crop disease detection |
Layer 3 — Atlas Sovereign Intelligence Layer
Atlas becomes the deterministic intelligence layer overlaid on the GAIA inference pipeline.
3.1 Reasoning
Atlas provides causal and contextual reasoning over model outputs:
- "Why is drought risk increasing?"
- "What environmental factors are driving yield decline?"
- "Which crops are at highest stress risk?"
- "What is the likely root cause of reduced harvest readiness?"
3.2 Recommendation Generation
Atlas translates inference results into actionable field recommendations:
- Irrigation recommendations
- Fertiliser recommendations
- Harvest timing recommendations
- Crop rotation suggestions
- Environmental risk mitigation
3.3 Deterministic Governance
All Atlas recommendations pass through a governance pipeline — exactly as implemented in Orion Edge:
| Control | Description |
|---|---|
| Deterministic rules | Hard rule checks before output |
| Threshold checks | Confidence and value range gates |
| Explainability scoring | SHAP / attribution required before output |
| Audit logging | Every recommendation logged with inputs |
| Confidence gates | Low-confidence outputs flagged, not suppressed |
Atlas must never operate as uncontrolled autonomous AI. Every output is governed.
3.4 Executive Narrative Generation
Atlas provides the executive storytelling layer over model results:
- Executive summaries
- Seasonal reports
- Farm risk reports
- Sustainability narratives
- Yield impact summaries
Layer 4 — CodeZero Sovereign Stack
NeXus (Orchestration + Form Flow Layer)
> Formerly: Wormwood. Now unified under the NeXus brand.
NeXus becomes the orchestration backbone for event routing, workflow management, and operator-facing form flows.
Responsibilities:
- Workflow orchestration
- Agent chaining
- Deterministic execution
- Event routing
- Approval pipelines
- State management
- Form flows (data entry, field advisory submission, operator confirmations)
Example Flows:
- Weather alert → trigger Atlas reasoning → update GAIA dashboard
- Soil stress threshold exceeded → generate intervention recommendation
- Harvest readiness confidence > threshold → notify operator
- Agronomist submits soil parameters → NeXus form flow → Atlas recommendation → operator review
Chameleon / Grafana (Presentation Layer)
Interim Dashboard: Grafana
Grafana is used as the operator and executive dashboard layer until ChameleonBI is production-ready. This applies to all real-time metric views, model performance monitoring, and farm health dashboards.
| Dashboard | Tool | Notes |
|---|---|---|
| Real-time inference metrics | Grafana | Interim |
| Model performance monitoring | Grafana | Interim |
| Farm health / KPI views | Grafana | Interim |
| Executive interface | Grafana | Interim |
| Multi-tenant / white-label | Chameleon | Target state (pending ChameleonBI) |
Target State: Chameleon
Once ChameleonBI is available, Chameleon replaces Grafana as the white-label presentation layer:
- White-label UI
- Executive interface
- Operator dashboards
- Multi-tenant presentation
deltaPrism (Governance Layer)
deltaPrism provides immutable audit and lineage for all GAIA operations:
Responsibilities:
- Immutable audit trail
- Data lineage tracking
- Model artefact tracking
- Governance enforcement
- API control boundaries
- Integration control
Architecture Summary
| Layer | Component | Role |
|---|---|---|
| L1 — Hardware | HP Z4R + GRC Micro (Qloe immersion) | Sovereign edge compute, France deployment |
| L2 — AI Runtime | Gaia Edge Runtime | Vision inference, sensor + weather ingestion, dashboards |
| L3 — Intelligence | Atlas | Reasoning, recommendations, governance, narrative |
| L4 — Orchestration | NeXus (Wormwood) | Workflow, event routing, agent chaining, form flows |
| L4 — UI | Grafana (interim) → Chameleon | Operator + executive dashboards (Grafana until ChameleonBI ready) |
| L4 — Audit | deltaPrism | Lineage, artefact tracking, immutable audit |
Classification Summary
| Section | Classification | Notes |
|---|---|---|
| 01 Overview | Mandatory | Cannot proceed without this |
| 02 Actors | Mandatory | Must know who uses it |
| 03 User Stories | Mixed | P1 mandatory, rest derived |
| 04 System Flows | Mixed | Triggers/steps mandatory, error handling derived |
| 05 Data Model | Mixed | Entities mandatory, lifecycle/validation derived |
| 06 Screens | Derived | UV proposes entirely |
| 07 Integrations | Mandatory | Must know what connects to what |
| 08 Infrastructure | Derived | UV proposes unless hard constraints exist |
| 09 Critical Path | Derived | UV calculates from dependencies |
| 10 What Is Needed | Mandatory | Blocker list |
| 11 Acceptance | Mixed | Success metrics mandatory, criteria derived |
| 12 Risks | Derived | UV identifies from analysis |
| 13 Cooperator Brief | Derived | Internal UV document |
Version History
| Version | Date | Changes |
|---|---|---|
| 1.1 | 2026-05-06 | Added Section 14 — Proposed Unified Architecture (Phase 2). HP Z4R France target, Atlas intelligence layer, NeXus orchestration, Chameleon UI, deltaPrism audit. |
| 1.0 | 2026-05-03 | Initial GAIA EDGE use case document — all 13 sections populated from project artefacts and README. |
*Uued Viljapuuaiad OU — Nexus Platform Documentation*
*Use Case Document: GAIA EDGE · UC-GAIA · 2026-05-03*