Project A.R.I.E.S.

Autonomous Research Interface for Extraterrestrial Signals

Project A.R.I.E.S. is an autonomous multi-agent research system that ingests astrophysical telemetry from NASA observatories, processes signals through a white-box cognitive pipeline, and synthesizes publication-ready academic reports. Built with Google's Agent Development Kit (ADK) and the Gemini API.

Now featuring 124+ registered tools, 19 auto-discovered skills, 30+ physics formulas, knowledge retrieval (RAG), ML-based flare prediction, anomaly detection, hypothesis generation engine, DAG workflow planner, causal reasoning, 6 specialized role agents, and a centralized prompt management system.

---

Architecture

Pipeline Diagrams

Full Pipeline — Agents, Tools & Data Flow

ADK Brain — 4-Phase Loop Routing to 6 Role Agents & Tool Registry

Additional diagrams: ADK Brain Loop, Tool Calling Architecture, End-to-End Pipeline

Two Entry Points — Same Backend

The system has two control paths that share the same tool registry, signal processor, and 6 role agents:

                            User Query
                               │
                     ┌─────────┴──────────┐
                     ▼                    ▼
              ADK Brain (async)     Orchestrator (sync)
              /api/query/stream     /api/query
              ?mode=adk
                     │                    │
                     └────────┬───────────┘
                              ▼
                    ┌─────────────────────┐
                    │   Tool Registry     │
                    │   (124+ tools)      │
                    │   6 Role Agents     │
                    │   Signal Processor  │
                    │   RAG Knowledge Base│
                    └─────────────────────┘

Feature	ADK Brain	Orchestrator
Type	Async loop	Sync direct call
Control Flow	Plan → Reason → Route → Reflect	Parse → Execute → Return
Retry Logic	Yes (3 attempts, exponential backoff)	No
Quality Gates	Yes (via Reflector + 6 role agent gates)	No
Use Case	Complex queries ("analyze in detail...")	Simple/standard queries
Agents Used	ADK agents (4) + Role agents (6)	Role agents (6)

---

ADK Brain — 4-Phase Meta-Cognitive Loop

The ADK Brain (backend/adk_agents/) is an async loop that wraps the entire pipeline with planning, reasoning, routing, and reflection:

Phase	Agent File	What it Does
① PLAN	planner.py	Decomposes user query into atomic sub-tasks. Outputs a DAG (dependency graph) of ordered operations. E.g. "analyze May 2024 storm" → [fetch_donki_cme, fetch_flare, apply_filters, compute_dst, generate_report]
② REASON	reasoner.py	Resolves each sub-task: checks parameter availability, picks best tools, assigns confidence scores. Detects gaps (e.g. "Bz missing, using B_total fallback").
③ ROUTE	router.py	Dispatches sub-tasks to the Tool Registry (direct tools, MCP servers, or role agents). Caches results per sub-task.
④ REFLECT	reflector.py	Evaluates output quality. If confidence < threshold → retry (up to 3, exponential backoff). If still failing → fallback strategy or escalate.

The loop is auto-triggered when the query contains keywords like "analyze in detail", "comprehensive", "investigate" — or when mode=adk is explicitly set.

---

6 Role Agents — Sequential Pipeline with Quality Gates

The 6 role agents (backend/agents/role_*.py) form a linear pipeline executed by BOTH the ADK Brain and Orchestrator. Each has a dedicated prompt template from backend/prompts/:

Data Collector → Analyst → Validator → Interpreter → Reporter → Reviewer
(Phase 1)      (Phase 2)  (Phase 3)   (Phase 4)     (Phase 5)  (Phase 6)

Agent	File	Responsibility	Tools Used
1. Data Collector	role_data_collector.py	Fetches real-time & historical data from NASA DONKI, NOAA SWPC, ESA. Validates data integrity. Normalizes into NumPy arrays.	nasa_mcp.py, data_processor.py
2. Analyst	role_analyst.py	Applies 30+ physics formulas (Burton, MHD, reconnection, etc.), runs ML inference (XGBoost, Isolation Forest), detects anomalies & trends.	formulas/ (9 modules), ml_inference.py, signal_processor.py
3. Validator	role_validator.py	Cross-references results against RAG knowledge base, validates against historical events, runs peer consistency checks, assigns confidence score.	rag_knowledge_base.py, plausibility.py
4. Interpreter	role_interpreter.py	Contextualizes findings in natural language, generates scientific explanations, identifies impact & severity, coordinates signal processing & visualization.	signal_processor.py, visualization_agent.py
5. Reporter	role_reporter.py	Formats the 8-section academic report (Abstract → References), embeds generated figures, drafts executive summary.	academic_writer.py, pdf_generator.py
6. Reviewer	role_reviewer.py	Final quality gate: reviews content accuracy, checks citations & sources, approves or requests revision.	self_assessment.py, evidence_graph.py

Quality gates between phases: Each phase has a gate that checks output quality before passing to the next:

• Gate 1: Data complete & valid? → fail = re-fetch
• Gate 2: Analysis confidence > 85%? → fail = re-analyze
• Gate 3: Validation score > threshold? → fail = re-validate
• Gate 4: Interpretation clear & actionable? → fail = re-interpret
• Gate 5: Report meets standards? → fail = re-format
• Gate 6 (Reviewer): Final approve/reject

---

Tool Registry — Unified Shared Backend

Both control paths route through the same Tool Registry (tool_registry.py):

Tool Registry (124+ callable tools)
├── signal_processor.py      Filters, FFT, 4 dashboard generators (16 panels)
├── nasa_mcp.py              DONKI / EONET / SWPC / APOD API wrappers
├── formulas/ (9 modules)    30+ physics formulas (magnetosphere, reconnection, waves, etc.)
├── ml_inference.py          XGBoost flare prediction + Isolation Forest anomaly detection
├── rag_knowledge_base.py    TF-IDF document retrieval for space weather knowledge
├── sandbox_executor.py      Isolated Python sandbox for user scripts
├── skills/* (19 modules)    Auto-discovered domain skills (data ingestion, forecasting, etc.)
├── tool_plan_executor.py    Executes tool plans as dependency-aware DAGs
└── +15 more tool modules    Visualization, data quality, monitoring, export, etc.

---

How They Work Together

User Query: "analyze the May 2024 solar storm in detail"
                    │
                    ▼
          ┌─────────────────┐
          │  ADK Brain      │  ← auto-triggered (keyword "analyze in detail")
          │  planner.py     │
          │  → decomposes   │  → sub-tasks: [fetch_cme, fetch_flare, fetch_gst,
          │    into DAG     │                  apply_filter, compute_dst, report]
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │  Tool Registry  │  → dispatches fetch tasks to nasa_mcp.py
          │                 │  → dispatches compute tasks to signal_processor.py
          │  124+ tools     │  → dispatches validation to rag_knowledge_base.py
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │  6 Role Agents  │  → Collector: gather DONKI/CME data
          │  (pipeline)     │  → Analyst: apply filters, FFT, physics formulas
          │                 │  → Validator: cross-reference with KB
          │  quality gates  │  → Interpreter: generate NL explanation + viz
          │  between each   │  → Reporter: generate 8-section report
          └────────┬────────┘  → Reviewer: approve/reject
                   │
                   ▼
          Final Report + 4 dashboards (16 visualization panels)

Summary: The ADK Brain plans what to do and in what order (DAG). The Tool Registry provides how to do each step (specific tools). The 6 Role Agents execute the analysis in sequence with quality checks at each stage. The Orchestrator is a simpler path that skips planning/reflection and goes directly to execution — faster but with fewer safeguards.

---

Multi-Agent Pipeline

User Query → Orchestrator (LLM) → Intent Parsing
    ├── ADK Brain (Plan→Reason→Route→Reflect loop)
    ├── Role Data Collector     → NASA/NOAA API data gathering
    ├── Role Analyst            → Formula computation + signal processing
    ├── Role Validator          → Physical plausibility + consistency checks
    ├── Role Interpreter        → Scientific narrative + hypothesis generation
    ├── Role Reporter           → Report formatting + visualization
    ├── Role Reviewer           → Quality assessment + critique
    ├── Skill Dispatcher        → 19 auto-discovered domain skill modules
    ├── Formula Engine          → 30+ physics formulas + algorithm selection
    └── Knowledge Base (RAG)    → TF-IDF document retrieval

Agent	Role
ADK Brain	Top-level controller running plan→reason→route→reflect loop with retry logic
Root Orchestrator	Gemini-powered LLM agent that parses user intent, routes tasks, dispatches skills, and manages chain-of-thought trace
Data Ingestion Pipeline	Sequential workflow agent that normalizes raw telemetry (JSON/CSV/Excel/FITS) into NumPy matrices
Signal Processor	Applies median/Savitzky–Golay/Butterworth/Wiener filters + FFT + STFT spectrograms for noise reduction and spectral feature extraction
Academic Writer	Synthesizes processed data into formal 5-section academic reports with embedded figures, literature context, and citations
Skill Dispatcher	Auto-discovers 19 domain skills at runtime; maps user intent to skill modules via skill_intent_map
Formula Engine	Registry of 30+ physics formulas (Burton, MHD waves, reconnection, spectral, etc.) with automatic algorithm selection, confidence scoring, physical plausibility checks, and uncertainty propagation
Role Agents (6)	Specialized agents for data collection, analysis, validation, interpretation, reporting, and review — each with role-specific prompts and quality gates
Hypothesis Engine	Generates and evaluates multiple scientific hypotheses for space weather events
DAG Workflow Planner	Topologically sorts and executes tool plans as dependency-aware graphs
Iterative Analyzer	Runs multi-depth analysis passes (basic stats → signal processing → cross-referencing)
Evidence Graph	Tracks data→computation→conclusion chains across skill boundaries
Knowledge Base (RAG)	In-memory TF-IDF document retrieval for space weather knowledge

System Design

• White-Box Mode: Every agent decision is streamed as a real-time chain-of-thought trace to the UI before execution
• Model Fallback: Primary gemini-2.5-flash → fallback gemini-2.5-flash-lite on rate limits, auto-detected
• 8-Tier Caching: Separate TTL caches for Gemini API, intent parsing, signal processing, NASA API, spectrograms, reports, persistent file-backed cache (APOD), and alert state — each with hit-rate monitoring
• Skill Auto-Discovery: Any .py file in backend/skills/ defining a Skill subclass is automatically registered — no manual wiring needed
• Monolithic Deployment: FastAPI backend serves both API routes and frontend static files — no separate frontend server required
• Unified ToolRegistry: Central dispatch dict mapping 124+ tool names to callable functions, auto-populated from formula registry, skills registry, and direct imports
• Prompt Management: YAML-based prompt templates with versioning, context injection, hot-reload, and caching
• Embedding-Based Tool Retrieval: TF-IDF vectorization retrieves top-20 relevant tools for each query, keeping LLM prompts focused
• ML-Based Forecasting: XGBoost flare prediction (with ONNX runtime) + Isolation Forest anomaly detection, both with graceful fallback to statistical models
• DAG Workflow Execution: Tool plans executed as dependency-aware directed acyclic graphs with parallel independent steps
• Self-Assessment: Analysis results scored across completeness, consistency, and confidence dimensions
• Audit Logging: All sandbox executions and security events logged to persistent audit trail

---

Features

19 Domain Skills (Auto-Discovered)

Skill	Tools	Purpose
data_ingestion	7 tools	Fetch data from NASA DONKI (CME, flares, GST, SEP), EONET (natural events), APOD, and NOAA SWPC (real-time solar wind)
signal_processing	8 tools	Median, Savitzky–Golay, Butterworth, Wiener filters; FFT analysis; spectrogram generation; filter auto-detection
visualization	2 tools	Publication-quality comparison plots and spectrograms
forecasting	3 tools	ARIMA flare probability forecast, CME arrival time (drag-based model), geomagnetic storm prediction
heliophysics	5 tools	Plasma beta, Alfven speed, Debye length, plasma frequency, solar wind Mach numbers
impact_assessment	4 tools	NOAA G-scale severity, aviation radiation dose, GIC risk for power grids, satellite anomaly risk
data_quality	5 tools	DONKI record validation, data gap detection, outlier flagging (IQR/Z-score), correction suggestions, quality report
historical_mining	4 tools	Multi-archive flare queries, solar cycle statistics (SILSO), cross-cycle comparison, light curve builder
monitoring	5 tools	Real-time solar wind monitor, GOES flare activity tracker, threshold-based alert registration/evaluation
solar_image_analysis	4 tools	SDO image fetch (any AIA wavelength), bright region detection, magnetic complexity classification, sunspot area estimation
data_export	5 tools	Export to CSV, JSON, HDF5, FITS-like format, batch multi-format export
multilingual	3 tools	Language detection (ISO 639-1), query translation, response generation in user's language
literature_review	4 tools	NASA ADS search, arXiv search (astro-ph.SR), key finding extraction, cross-source literature synthesis
education	4 tools	Concept explanation (3 difficulty levels), tutorial generator, next-step suggestions, study guide creator
citizen_science	4 tools	Radio spectrum ingestion (FITs-IDI/CSV/HDF5), intensity calibration, static interference removal, burst candidate detection
radio_detection	3 tools	Morphological burst detection in dynamic spectra, drift-rate-based Type II/III/IV classification, spectral feature extraction
ml_inference	4 tools	Model loading (ONNX/sklearn), input validation + inference, multi-model event classification, model metadata queries
multi_spacecraft	4 tools	Cross-instrument calibration, time-delay correlation, TDOA source triangulation, weighted spectrogram fusion
formulas	18 tools	30+ physics formulas (Burton equation, Akasofu epsilon, Sweet-Parker/Petschek reconnection, MHD wave speeds, Parker spiral, Elsasser variables, Lomb-Scargle periodogram, wavelet/Hilbert-Huang transforms, firehose/mirror instabilities, Fokker-Planck diffusion, CME kinematics) + algorithm selection engine + confidence scoring + physical plausibility + data quality pipeline

Physics Formula Engine

The system includes a registry of 30+ computational physics formulas that were previously only documented as educational text. Now every formula is a callable tool:

Category	Formulas
Magnetosphere	Burton equation (Dst prediction), Akasofu epsilon coupling, magnetopause standoff distance, dynamic pressure
Reconnection	Lundquist number, Sweet-Parker rate, Petschek rate, reconnection regime classification
Plasma Waves	Appleton-Hartree dispersion, upper hybrid frequency, cyclotron frequency, MHD wave speeds (slow/Alfven/fast)
Turbulence	Parker spiral angle, Elsasser variables, cross helicity, Kolmogorov spectral index fitting
Instabilities	Firehose instability criterion, mirror instability criterion, Troyon beta limit
Spectral Methods	Welch's periodogram, Lomb-Scargle periodogram (unevenly sampled), Morlet wavelet transform, Hilbert-Huang transform
Particle Drifts	Gradient/curvature drift velocity, 1D Fokker-Planck radial diffusion
Solar Physics	Waldmeier effect, Wolf sunspot number, adiabatic invariants
CME Kinematics	Height-time fit (linear/quadratic), running difference, GCS parameter estimation

The orchestrator can route "compute this formula" queries to the formulas skill, which retrieves the formula from the registry, validates inputs against schema, computes the result, checks physical plausibility, and returns the output with confidence scoring.

Algorithm Selection & Reasoning

The agent no longer applies a fixed algorithm — it chooses the right method based on data characteristics:

• Filter Selection: Analyzes SNR, outlier count, coefficient of variation, and roughness to recommend median/Savgol/Butterworth/Wiener filters automatically. When ambiguous, runs all 4 and picks by reconstruction error.
• Forecast Model Selection: Checks data length, stationarity, and periodicity to recommend ARIMA/SARIMA/Holt-Winters/naive models. Validates with ADF test before fitting.
• Formula Selection: Given available plasma parameters (density, temperature, B-field), suggests which formulas are computable and what fallbacks to apply for missing inputs.
• Context-Based Formula Suggestion: From a user query like "geomagnetic storm", suggests relevant formulas (Burton equation, Akasofu epsilon, dynamic pressure) with reasoning.

The Algorithm Registry (19 entries) provides human-readable explanations of why a particular method was chosen:

"Used ARIMA(2,1,2) because 30 data points are available with strong 27-day periodicity. Confidence: 0.85."

Data Quality Pipeline

Every tool call can pass through a validation pipeline:

• Schema Validation: Per-tool input schemas coerce types, clamp ranges, and fill defaults — returning warnings for assumptions made.
• Graceful Degradation: The @degradable decorator wraps any tool so that failures return a fallback result with error metadata instead of crashing.
• Gap Filling: Auto-detects missing/None values and gaps in time-series data, applying linear interpolation (<3pts), cubic spline (3-10pts), or forward fill (>10pts) with full gap reporting.

Adaptive Thresholds & Self-Tuning

Hard-coded thresholds are replaced with data-driven values:

• IQR multiplier: Adjusted based on distribution skewness and kurtosis (2.0 for skewed, 1.2 for heavy-tailed, 1.5 default)
• Filter parameters: Window sizes auto-detected via autocorrelation; polynomial order selected by RMSE minimization
• SNR estimation: From FFT — dominant peak power vs noise floor in top 10% frequency band

Confidence Scoring & Uncertainty

Every computed result includes a confidence score and, where applicable, uncertainty bounds:

• Confidence Heuristics: Start at 1.0, subtract for defaults used (-0.15 each), warnings (-0.1 each), high variance (-0.1), stale data (-0.1/hr), unphysical results (-0.3)
• Error Propagation: Standard formulas for product, ratio, power, sum, and general (via partial derivatives) — returns value ± uncertainty with 95% confidence interval

Physical Plausibility

Post-processing validation against known physical ranges prevents silent garbage outputs:

• Range Checks: Validates against 9 parameter ranges (solar wind speed 200-2500 km/s, plasma beta 0.001-100, etc.)
• Cross-Parameter Consistency: If beta < 0.1, checks B field is non-zero; if Kp > 5, checks Bz would be southward; if Alfven speed > solar wind speed, checks consistency with beta

Smart Caching with Invalidation

• Cache Policies: Different TTLs per data source — DONKI 1h, SWPC 5min, GOES 1min, SDO 1h, derived parameters until input changes
• Invalidation Graph: When a source API (e.g., get_coronal_mass_ejection) returns fresh data, all cached analyses that depend on it (forecast_flare_probability, predict_cme_arrival_time, etc.) are automatically cleared

API Resilience

• Retry Strategy: 3 attempts with exponential backoff (1s, 4s, 16s); handles 429 (rate limit), 5xx, and connection errors
• Mock Data Layer: When APIs are unreachable, generates physically plausible mock data tagged with {"mock": true, "generated_at": timestamp} — never silently returns synthetic data

White-Box Transparency

Every decision made by the AI agents is visible in real-time:

• Chain-of-Thought Streaming: Agent reasoning steps are streamed via Server-Sent Events (SSE) to the frontend as they happen
• Thinking Trace Panel: A dedicated UI panel shows each step with expandable detail — including tool calls, API responses, and intermediate computations
• Model Selection Feedback: The UI displays which Gemini model is actively processing (primary vs. fallback) and shows a thinking indicator during computation

File Upload & Analysis

Users can upload data files for custom analysis:

• Supported Formats: CSV, JSON, Excel (.xlsx/.xls), TSV, TXT, SRT, FITS
• Automatic Detection: The system detects file type, parses headers, and normalizes data into NumPy arrays
• Context-Aware Processing: Uploaded data is included in the orchestrator's context, enabling hybrid queries that combine NASA data with user-provided datasets

Academic Report Generation

• 8-Section Structure: Each report follows formal astrophysics journal conventions — Abstract, Introduction, Methodology, Data Acquisition, Data Analysis & Results, Discussion, Conclusion, References
• Embedded Figures: Two consolidated 2×2 subplot dashboards (Time-Domain Analysis and Frequency & Statistical Analysis) are generated as high-resolution base64-encoded PNG images and embedded directly into the report
• Multi-Format Export: Reports can be downloaded as PDF (via weasyprint with fpdf2 fallback), DOC (HTML-based), or raw Markdown
• Professional Styling: PDF output uses A4 layout, Times New Roman, proper margins, numbered pages, CSS-styled figures/tables, and academic formatting
• Literature Integration: Optional literature context from NASA ADS/arXiv can be included in the Discussion section

Live Space Weather Media

• Solar Dynamics Observatory Feed: Live 304Å extreme ultraviolet video from NASA's SDO, showing real-time solar activity including flares and coronal structures
• Astronomy Picture of the Day: Daily APOD image with title, description, and HD link — fetched at most once per day (persistent file cache survives restarts, plus browser localStorage cache)
• Auto-Fallback: Media cards gracefully degrade on connection issues — SDO shows a loading spinner, APOD displays a placeholder with error messaging

APOD Caching Behavior

User visits page → frontend checks localStorage (instant if cached today)
                → calls GET /api/apod → backend checks persistent_cache.json (disk)
                                      → if miss: calls NASA API, caches until midnight
                                      → same-date requests: cache hit, no NASA call

• APOD is fetched from NASA at most once per day regardless of user count
• persistent_cache.json is file-backed — survives server restarts
• On ephemeral deployments (e.g. Hugging Face Spaces): first user after deploy triggers one fetch, then cached for all subsequent users that day
• Frontend also caches in localStorage for instant display on repeat visits

8-Tier Caching System

Cache	Type	Default TTL	Contents
Gemini API	TTL	10 min	Raw API responses
Intent	TTL	5 min	Parsed query intents
Signal	TTL	15 min	FFT results, metrics
NASA API	LRU+TTL	10 min	DONKI/EONET/APOD responses
Spectrogram	TTL	30 min	Generated plot images
Report	TTL	20 min	Generated report text
Persistent	File-backed	Until midnight	APOD, daily data (survives restarts)
Alert State	File-backed	Persistent	Registered alert rules

Each cache exposes hit/miss rates via /api/cache/stats for monitoring.

Model Fallback & Resilience

• Primary Model: gemini-2.5-flash (agentic capabilities, $0.30/$2.50 per 1M tokens)
• Fallback Model: gemini-2.5-flash-lite (higher free tier limits, $0.10/$0.40 per 1M tokens)
• Automatic Detection: If the primary model returns a 429 (rate limit) or 503 (overloaded), the system seamlessly switches to the fallback for the remainder of the request
• Configurable: Both model names can be overridden via GEMINI_MODEL_PRIMARY and GEMINI_MODEL_FALLBACK environment variables

Skill Auto-Discovery System

Skills are automatically discovered at startup by scanning backend/skills/ for Skill subclasses. No manual registration is required.

# Any .py file in backend/skills/ with a Skill subclass is auto-loaded
from backend.skills.registry import discover_skills
skills = discover_skills()  # Returns dict of {name: SkillClass}

The orchestrator uses skill_intent_map to route queries to the appropriate skills, and TOOL_DESCRIPTIONS provides the LLM with structured tool metadata including parameter schemas and descriptions.

Data Export & Persistence

• PDF Generation: Primary path uses weasyprint for CSS-styled academic PDFs with proper page numbering, margins, and typography; falls back to fpdf2 if weasyprint is unavailable
• HTML Export: Reports can be exported as standalone HTML documents with embedded styling
• Markdown Export: Raw markdown output for further editing or integration with other tools
• Scientific Format Export: Export processed data to HDF5, FITS-like structure, CSV, JSON via the data_export skill
• Report History: All generated reports are stored in memory with unique IDs, accessible via the reports list endpoint

Secure Code Execution

• Sandboxed Environment: User-provided Python scripts run in an isolated exec() context with restricted globals
• Safety Constraints: Math operations, string manipulation, and data transformation are permitted; file I/O, network access, and system calls are blocked
• Timeout Protection: Scripts exceeding 30 seconds are automatically terminated
• Result Capture: stdout, stderr, and return values are captured and returned as structured JSON

---

Tech Stack

Layer	Technology
Backend	FastAPI (Python 3.12), Uvicorn
Agent Framework	Google ADK 2.3 + Gemini API
Frontend	HTML5, CSS3, Vanilla JS
Signal Processing	NumPy, SciPy, Matplotlib
Forecasting	statsmodels (ARIMA), XGBoost (optional)
ML Models	XGBoost ONNX, scikit-learn Isolation Forest
Document Retrieval	TF-IDF Vectorization (scikit-learn)
Scientific Export	h5py, FITS-like structure
Formula Engine	30+ custom physics formulas (Burton, MHD, reconnection, spectral)
Algorithm Selection	Decision-tree filter/forecast/formula recommender
Confidence & Uncertainty	Custom heuristic scoring + analytic error propagation
Data Sources	NASA DONKI, NASA EONET, NASA APOD, NOAA SWPC, NASA ADS, arXiv
PDF Export	weasyprint (primary), fpdf2 (fallback)
Sandboxing	Python exec with restricted globals + subprocess fallback with timeout
Deployment	Docker (multi-stage), docker-compose, Hugging Face Spaces
Caching	Custom TTL-based multi-level cache + persistent file cache + invalidation graph + adaptive TTL

---

Project Structure

Project-A.R.I.E.S/
├── backend/
│   ├── app.py                      # FastAPI server — API routes + static file serving
│   ├── cache.py                    # 8-tier caching layer (TTL + persistent) with stats
│   ├── pdf_generator.py            # PDF / HTML / DOC export engine (weasyprint + fpdf2)
│   ├── sanitize.py                 # Error sanitization
│   ├── requirements.txt
│   ├── .env / .env.example         # API keys (GOOGLE_API_KEY, NASA_API_KEY)
│   │
│   ├── agents/                     # Multi-agent cognitive pipeline
│   │   ├── orchestrator.py         # Root LLM agent — intent parsing, routing, skill dispatch, fallback
│   │   ├── data_processor.py       # Data ingestion & normalization
│   │   ├── academic_writer.py      # 5-section report generation
│   │   ├── intent_parser.py        # Natural language intent classification
│   │   ├── intent_types.py         # Intent enum + keyword mapping
│   │   ├── data_fetcher.py         # API source selector
│   │   ├── manager.py              # Agent registry
│   │   ├── api_selector.py         # API endpoint routing
│   │   ├── code_generator.py       # Math script generator
│   │   ├── validator_agent.py      # Result validation
│   │   ├── visualization_agent.py  # Plot generation coordination
│   │   ├── role_data_collector.py  # Role: Data Collector (Section 22)
│   │   ├── role_analyst.py         # Role: Analyst (Section 22)
│   │   ├── role_validator.py       # Role: Validator (Section 22)
│   │   ├── role_interpreter.py     # Role: Interpreter (Section 22)
│   │   ├── role_reporter.py        # Role: Reporter (Section 22)
│   │   └── role_reviewer.py        # Role: Reviewer (Section 22)
│   │
│   ├── skills/                     # 19 auto-discovered skill modules
│   │   ├── __init__.py             # Skill base class (ABC)
│   │   ├── registry.py             # Auto-discovery, loading, unloading
│   │   ├── data_ingestion.py       # NASA API ingestion
│   │   ├── signal_processing.py    # Signal processing
│   │   ├── visualization.py        # Plot generation
│   │   ├── forecasting.py          # Time-series forecasting
│   │   ├── heliophysics.py         # Plasma parameter derivation
│   │   ├── impact_assessment.py    # Space weather impact assessment
│   │   ├── data_quality.py         # Data validation & quality
│   │   ├── historical_mining.py    # Historical data mining
│   │   ├── monitoring.py           # Real-time monitoring & alerts
│   │   ├── solar_image_analysis.py # Solar image analysis
│   │   ├── data_export.py          # Scientific format export
│   │   ├── multilingual.py         # Multi-language support
│   │   ├── literature_review.py    # Paper search & synthesis
│   │   ├── education.py            # Tutorial & explanation
│   │   ├── citizen_science.py      # Amateur radio data ingestion
│   │   ├── radio_detection.py      # Radio burst detection
│   │   ├── ml_inference.py         # ML model inference
│   │   ├── multi_spacecraft.py     # Multi-spacecraft analysis
│   │   └── formulas.py             # 18-tool wrapper over formula registry
│   │
│   ├── tools/                      # 17+ tool modules (functional implementations)
│   │   ├── nasa_mcp.py             # DONKI / EONET / APOD / SWPC API wrappers
│   │   ├── signal_processor.py     # Filters, FFT, spectrograms
│   │   ├── sandbox_executor.py     # Isolated Python sandbox
│   │   ├── forecasting.py          # ARIMA, DBM CME arrival, storm forecast
│   │   ├── heliophysics.py         # Plasma physics formulas
│   │   ├── impact.py               # G-scale, radiation, GIC, satellite risk
│   │   ├── data_quality.py         # Validation, gaps, outliers
│   │   ├── historical.py           # Solar cycle stats, light curves
│   │   ├── monitoring.py           # Solar wind, flare monitor, alerts
│   │   ├── solar_imaging.py        # SDO fetch, bright regions, magnetic class
│   │   ├── data_export.py          # CSV/JSON/HDF5/FITS export
│   │   ├── multilingual.py         # Language detection, translation
│   │   ├── literature.py           # ADS/arXiv search, finding extraction
│   │   ├── education.py            # Concept explanations, tutorials
│   │   ├── citizen_science.py      # Spectrum parsing, calibration
│   │   ├── radio.py                # Burst detection, classification
│   │   ├── ml_inference.py         # ONNX/sklearn model inference
│   │   ├── multi_spacecraft.py     # Calibration, triangulation
│   │   ├── algorithm_selector.py   # Auto-selects filters/forecast/formula
│   │   ├── algorithm_registry.py   # 19-entry decision reasoning engine
│   │   ├── data_quality_pipeline.py# Schema validation, @degradable, gap filling
│   │   ├── adaptive_thresholds.py  # IQR multiplier, filter auto-tuning, SNR estimation
│   │   ├── plausibility.py         # Physical range + cross-parameter checks
│   │   ├── confidence.py           # Confidence scoring + error propagation
│   │   ├── api_resilience.py       # Retry with backoff + mock data generation
│   │   └── formulas/               # 9 modules, 30+ physics formulas
│   │       ├── magnetosphere.py    # Burton equation, epsilon, standoff, dynamic pressure
│   │       ├── reconnection.py     # Lundquist, Sweet-Parker, Petschek
│   │       ├── waves.py            # Appleton-Hartree, cyclotron, MHD wave speeds
│   │       ├── turbulence.py       # Parker spiral, Elsasser, spectral index
│   │       ├── instabilities.py    # Firehose, mirror, Troyon beta limit
│   │       ├── spectral.py         # Welch, Lomb-Scargle, wavelet, Hilbert-Huang
│   │       ├── drift.py            # Guiding-center drift, Fokker-Planck
│   │       ├── solar.py            # Waldmeier, Wolf number, invariants
│   │       └── cme_kinematics.py   # Height-time fit, running difference, GCS
│   │
│   ├── adk_agents/                 # Google ADK agent definitions (Section 16)
│   │   ├── brain.py                # Top-level controller (plan→reason→route→reflect loop)
│   │   ├── planner.py              # Query decomposition into steps
│   │   ├── reasoner.py             # Chain-of-thought parameter resolution
│   │   ├── router.py               # Step dispatch to 14 agent types
│   │   ├── reflector.py            # Quality review with retry logic
│   │   ├── tools.py                # Adapter layer to all agents + role agents
│   │   └── __init__.py
│   │
│   ├── ml/                         # ML models (Section 2)
│   │   ├── flare_predictor.py      # XGBoost flare prediction + statistical fallback
│   │   └── anomaly_detector.py     # Isolation Forest anomaly detection
│   │
│   ├── security/                   # Safety layer (Section 14)
│   │   ├── __init__.py
│   │   ├── input_screener.py       # Query sanitization
│   │   ├── pii_redactor.py         # PII redaction
│   │   ├── execution_guard.py      # Sandbox restrictions
│   │   └── audit_logger.py         # Security event audit trail
│   │
│   ├── parsers/                    # Data format parsers
│   │   └── eonet_parser.py         # EONET event parser
│   │
│   ├── prompts/                    # Centralized prompt templates (Section 23)
│   │   ├── orchestrator.json       # Root orchestrator prompt
│   │   ├── data_collector.json     # Data collector role prompt
│   │   ├── analyst.json            # Analyst role prompt
│   │   ├── validator.json          # Validator role prompt
│   │   ├── interpreter.json        # Interpreter role prompt
│   │   ├── reporter.json           # Reporter role prompt
│   │   ├── reviewer.json           # Reviewer role prompt
│   │   ├── adk_planner.json        # ADK planner prompt
│   │   ├── adk_reasoner.json       # ADK reasoner prompt
│   │   └── adk_reflector.json      # ADK reflector prompt
│   │
│   ├── knowledge/                  # RAG knowledge base documents (Section 7)
│   │   └── space_weather_basics.txt
│   │
│   ├── tool_registry.py            # Unified 124+ tool registry (Section 15)
│   ├── tool_plan_executor.py       # LLM tool plan executor (Section 15)
│   ├── prompt_manager.py           # Prompt template manager (Section 23)
│   ├── parallel_executor.py        # Parallel tool execution (Section 6)
│   ├── embedding_retrieval.py      # TF-IDF tool retrieval (Section 1)
│   ├── rag_knowledge_base.py       # RAG knowledge base (Section 7)
│   ├── hypothesis_engine.py        # Hypothesis formulation (Section 9)
│   ├── iterative_analyzer.py       # Multi-depth analysis (Section 9)
│   ├── dag_workflow.py             # DAG workflow planner (Section 10)
│   ├── self_assessment.py          # Quality self-assessment (Section 11)
│   ├── evidence_graph.py           # Cross-skill evidence graph (Section 12)
│   └── workflow/
│       └── dag.py                  # Analysis DAG definitions
│
├── frontend/
│   ├── assets/                     # Logo, video backgrounds
│   ├── index.html                  # Single-page application
│   ├── css/
│   │   └── style.css               # Deep-space theme, glassmorphism, cosmic animations
│   └── js/
│       ├── animations.js           # Starfield, nebula canvas, scroll effects
│       ├── api.js                  # API client wrapper
│       └── main.js                 # UI logic, SSE streaming, tab management
│
├── Dockerfile
├── requirements.txt
├── implement.md                    # Robustness implementation plan
├── pic.md                          # Image reference links
└── README.md

---

Quick Start

Prerequisites

• Python 3.12+
• pip

1. Clone and install

cd Project-A.R.I.E.S
pip install -r requirements.txt

2. Configure API keys

Create backend/.env:

GOOGLE_API_KEY=your_gemini_api_key
NASA_API_KEY=DEMO_KEY

Key	Required	Source
GOOGLE_API_KEY	Yes for AI responses	Google AI Studio
NASA_API_KEY	No (defaults to DEMO_KEY, 30 req/hr, no APOD without real key)	api.nasa.gov

Without API keys, the system runs in simulated mode with pre-built mock responses.

3. Start the server

Option A — Direct:

python -m backend.app

Option B — Docker:

docker compose up --build

Visit http://localhost:8080

4. Run tests

pytest tests/ -v

---

API Endpoints

Method	Path	Description
GET	/	Frontend SPA
GET	/api/health	Health check (includes tool count, cache stats, API status)
GET	/api/cache/stats	Cache hit/miss rates per tier
POST	/api/query	Full pipeline: intent → action routing (fetch/compute/report)
POST	/api/query/stream	SSE-streamed version with white-box chain-of-thought
POST	/api/adk/process	ADK Brain (plan→reason→route→reflect loop) via SSE
POST	/api/analyze	Direct data analysis by event type
POST	/api/upload	Upload CSV / JSON / Excel / TSV / FITS
GET	/api/apod	NASA Astronomy Picture of the Day (cached until midnight)
GET	/api/agents	List of all 14 agent types
GET	/api/sessions/{id}	Get session history
GET	/api/reports	List of generated reports
POST	/api/report/generate-pdf	Generate PDF from report markdown
POST	/api/report/export	Export report as MD / DOC / PDF
POST	/api/execute	Execute Python math script in sandbox
GET	/{path}	Static file serving (catch-all)

---

Frontend Overview

Section	Content
Hero	Animated pulsar rings, deep-space video background, key stats
Live Media	NASA SDO 304Å solar video feed + Astronomy Picture of the Day (once-per-day cache)
Explorer	Query input, suggestion chips, file upload, thinking trace panel, result tabs (Data / Visuals / Report)
System Architecture	Agent cards with descriptions and tech tags
Reports	List of generated reports with download links

All sections feature full-screen ambient video backgrounds, canvas-based starfield & nebula particle systems, and scroll-triggered reveal animations.