LunarGuard AI

AI-powered lunar landing risk and mission decision-support prototype, being prepared for an IBM hackathon.

LunarGuard AI helps a human mission operator interpret synthetic lunar-descent telemetry. It combines anomaly detection, landing-risk estimation, temporal replay, retrieval-augmented generation (RAG), and a mission-control dashboard to turn raw signals into a concise, evidence-grounded mission brief.

The project is a decision-support demonstration. It does not control a spacecraft, issue commands, or process real mission telemetry.

Hackathon vision

Lunar landing operations involve many signals changing at once. An operator must identify unusual behavior, understand whether it increases landing risk, and connect the observation to relevant mission knowledge. LunarGuard demonstrates one way IBM watsonx.ai and conventional machine learning can support that workflow in a single interface.

The prototype is designed to demonstrate:

• Explainable anomaly and risk estimates from multivariate telemetry.
• Time-aware replay of a complete synthetic descent run.
• Knowledge-grounded answers for mission and spacecraft questions.
• A human-in-the-loop workflow that clearly separates evidence, model estimates, and operator judgment.
• Resilient AI-provider handling for a reliable hackathon demonstration.

Core capabilities

Mission overview

Displays the active descent phase and the most important synthetic telemetry values, including altitude, vertical velocity, trajectory error, sensor confidence, and thrust.

Descent replay

Replays one of 50 synthetic landing runs across 100 time steps. The operator can inspect how anomaly probability and predicted risk evolve throughout the descent and identify the first actionable warning.

Anomaly detection

Uses a trained scikit-learn model to estimate whether a telemetry observation is anomalous. The result is a probabilistic ML estimate, not confirmed spacecraft behavior.

Landing-risk estimation

Combines classification and regression models to produce a risk level and numerical score. The dashboard also shows the features that contributed most strongly to the estimate.

AI Knowledge Assistant

Accepts natural-language questions about lunar landing operations, spacecraft systems, anomaly handling, and mission procedures. Relevant passages are retrieved from the local knowledge base and supplied to the configured language model for a concise answer with source citations.

Mission Intelligence

Combines telemetry, anomaly probability, risk estimates, and retrieved knowledge into a plain-language mission brief with four sections:

• Status
• Why the result matters
• What the operator should review
• Confidence and limitations

Recommendations are for human review only and are never spacecraft commands.

System architecture

Synthetic telemetry
        |
        v
Data validation and feature preparation
        |
        +-------------------+
        |                   |
        v                   v
Anomaly detector       Risk predictor
        |                   |
        +---------+---------+
                  |
                  v
        Mission Intelligence
                  |
        +---------+---------+
        |                   |
        v                   v
FAISS knowledge search   LLM generation
        |                   |
        +---------+---------+
                  |
                  v
          FastAPI backend
                  |
                  v
       Next.js mission dashboard

Technology stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript
API	FastAPI, Pydantic, Uvicorn
Machine learning	scikit-learn, pandas, NumPy
Retrieval	FAISS, local Markdown and PDF knowledge base
Primary AI platform	IBM watsonx.ai
Optional provider	Mistral AI; OpenAI can be selected explicitly
Testing	pytest, ESLint

Data and model boundaries

All telemetry in this repository is synthetically generated for demonstration and testing.

• The dataset contains 50 simulated runs with 100 time steps per run.
• Telemetry values are simulation assumptions, not measurements from Chandrayaan or another real mission.
• Anomaly probabilities and risk scores are ML predictions and may be wrong.
• Retrieved documents provide context; retrieval does not prove that a recommendation is correct.
• The final decision always remains with a qualified human operator.

Repository structure

LunarGuard-AI/
|-- backend/                 FastAPI application and API schemas
|-- frontend/                Next.js mission-control dashboard
|-- src/
|   |-- agents/              Mission Intelligence orchestration
|   |-- data/                Data loading and feature preparation
|   |-- ml/                  Anomaly and risk models
|   `-- rag/                 Ingestion, retrieval, prompts, and LLM clients
|-- data/synthetic/          Synthetic telemetry and schema documentation
|-- knowledge_base/          Mission, GNC, anomaly, AI, and operations sources
|-- models/                  Serialized model artifacts
|-- notebooks/               Exploration and model-development notebooks
|-- tests/                   Backend, ML, and RAG tests
|-- reports/                 Validation and implementation reports
|-- configs/config.yaml      Central project configuration
|-- .env.example             Safe environment-variable template
`-- pyproject.toml           Python package and dependency configuration

Local setup

Prerequisites

• Python 3.11 or newer
• Node.js 20 or newer
• npm
• An IBM watsonx.ai project and API key for the primary provider, or a Mistral API key for the optional provider

1. Clone and enter the project

git clone <repository-url>
cd LunarGuard-AI

2. Create the Python environment

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

If PowerShell blocks activation, the environment executable can be used directly:

.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

3. Configure environment variables

Copy-Item .env.example .env

Add credentials only to .env. Never place real keys in .env.example or commit .env.

For IBM watsonx.ai as the primary provider with automatic Mistral fallback:

IBM_WATSONX_APIKEY=your_watsonx_api_key
IBM_WATSONX_PROJECT_ID=your_project_id
IBM_WATSONX_URL=https://eu-gb.ml.cloud.ibm.com
IBM_WATSONX_LLM_MODEL_ID=meta-llama/llama-3-3-70b-instruct

MISTRAL_API_KEY=your_mistral_api_key
MISTRAL_MODEL=mistral-large-latest
LLM_PROVIDER=auto

To use Mistral directly:

MISTRAL_API_KEY=your_mistral_api_key
MISTRAL_MODEL=mistral-large-latest
LLM_PROVIDER=mistral

Provider modes:

LLM_PROVIDER	Behavior
auto	Try IBM watsonx.ai, then Mistral, then local resilience mode
watsonx	Use IBM watsonx.ai; Mistral is used if the Watsonx request fails
mistral	Use Mistral directly
openai	Use the explicitly configured OpenAI-compatible provider

If no live provider is available, LunarGuard returns a deterministic local mission summary rather than failing the entire analysis.

4. Start the backend

Run this command from the repository root:

.\.venv\Scripts\uvicorn.exe backend.main:app --reload --port 8000

The API is available at:

• Health check: http://localhost:8000/health
• Interactive API documentation: http://localhost:8000/docs
• OpenAPI schema: http://localhost:8000/openapi.json

Keep this terminal running.

5. Start the frontend

Open a second terminal:

cd frontend
npm install
npm run dev

Open http://localhost:3000 in a browser. If PowerShell blocks npm.ps1, use npm.cmd run dev.

API endpoints

Method	Endpoint	Purpose
GET	/health	Backend liveness check
GET	/api/system/status	Model, retrieval, and provider readiness
POST	/api/anomaly/predict	Anomaly estimate for one synthetic telemetry row
POST	/api/risk/predict	Landing-risk estimate for one synthetic telemetry row
POST	/api/mission/analyze	Complete ML, retrieval, and Mission Intelligence workflow
POST	/api/mission/replay	Time-ordered replay for a synthetic run
POST	/api/rag/query	Knowledge Assistant question and grounded answer

The FastAPI documentation at /docs contains the current request and response schemas.

Suggested hackathon demo flow

1. Open the dashboard and explain that every telemetry value is synthetic.
2. Run the default nominal Rough Braking example.
3. Review the anomaly probability, risk estimate, and contributing features.
4. Switch to an anomalous preset and compare the result.
5. Use Descent Replay to show how risk changes across a complete run.
6. Ask the Knowledge Assistant a mission-operations question.
7. Show how Mission Intelligence combines ML estimates and retrieved evidence into a human-readable brief.
8. Highlight provider resilience by explaining the Watsonx-to-Mistral fallback.
9. Close with the human-in-the-loop and decision-support boundaries.

Testing and quality checks

Run the Python test suite from the repository root:

.\.venv\Scripts\python.exe -m pytest -q

Run frontend linting and a production build:

cd frontend
npm.cmd run lint
npm.cmd run build

The test suite covers data handling, anomaly inference, risk inference, retrieval behavior, provider fallback, prompt structure, API contracts, and temporal replay.

Knowledge base

The local knowledge base is organized into six areas:

1. Chandrayaan-2 public mission references
2. Chandrayaan-3 public mission references
3. Lunar landing guidance, navigation, and control
4. Spacecraft telemetry anomaly detection
5. AI and machine learning for space operations
6. Mission-operations and contingency references

Sources include Markdown summaries and PDF references. Retrieved passages retain source, category, page, and chunk metadata for traceability. When remote embeddings are unavailable, LunarGuard uses local lexical retrieval and excludes passages with no meaningful query overlap.

Security and responsible use

• Never commit .env or expose API keys in frontend code.
• All provider calls are made by the backend.
• API responses do not include credentials.
• Rotate any key that has been committed, logged, or shared accidentally.
• Treat model output as a suggestion requiring human verification.
• Do not use this prototype for real spacecraft operations or other safety-critical decisions.

Current hackathon status

LunarGuard AI is actively being prepared for an IBM hackathon demonstration. The main end-to-end workflow is implemented: synthetic telemetry can be replayed and analyzed, ML estimates are displayed in the dashboard, local knowledge is retrieved, and an LLM produces a readable decision-support brief.

Remaining submission work may include final UI polish, deployment configuration, demo recording, judging narrative, performance measurements, and final validation of IBM watsonx.ai credentials and quotas.

Future improvements

• Deploy the frontend and backend to a managed environment.
• Add authenticated user sessions and audit logging.
• Evaluate retrieval quality with a curated question set.
• Add model calibration and drift monitoring.
• Improve source-quality ranking and citation verification.
• Add streaming responses and richer replay comparisons.
• Package a reproducible hackathon demo configuration.

License

See LICENSE for repository licensing information.

Acknowledgements

LunarGuard AI is being developed for an IBM hackathon and is designed to demonstrate how IBM watsonx.ai can support explainable, knowledge-grounded, human-centered mission decision support.