AstraGuard AI

AI-Powered Satellite Security & Anomaly Detection System

ECWoC '26 Featured Project

📚 Documentation • 📄 Technical Report • 🧪 Research Lab • 📝 Changelog

🐛 Report Bug • ✨ Request Feature • 💬 Join WhatsApp Group

Bridging the gap between theoretical security concepts and real-world workflows

🌟 Hall of Fame

🏆A huge thank you to all the talented developers who have contributed to AstraGuard AI

Want to see your avatar here? Make your first contribution today!

📋 Table of Contents

🚀 About the Project
🏗️ System Architecture
- Dual-Engine Design
- Data Flow
✨ Key Features
🎯 Project Goals (ECWoC '26)
🤝 Project Admin Commitment
🧠 Mentorship & Support
🛠️ Tech Stack
📂 Project Structure
🚀 Getting Started
🌐 API Documentation
👥 Contributing
- Contributor Roles
- How to Contribute
🛠️ Troubleshooting
📚 Documentation
📞 Community
📄 License

🚀 About the Project

What is AstraGuard AI?

AstraGuard AI is an open-source, mission-critical security system designed specifically for CubeSat and satellite operations. It seamlessly combines AI-assisted threat detection with practical offensive security tooling to create a comprehensive defense platform for space systems.

At its core, AstraGuard AI is:

🛡️ A Security Platform: Built to test applications against simulated threats in controlled environments
🧠 An AI Learning System: Uses local LLMs (Llama 3/Mistral) to analyze attack surfaces and generate smart payloads
📊 A Monitoring Dashboard: Provides real-time visualization of security posture and system health
🎓 A Training Ground: Designed to help learners bridge the gap between theoretical knowledge and real-world security workflows

Why AstraGuard AI?

Traditional security tools often fall into two categories:

Theoretical frameworks that are great for learning but disconnected from reality
Production tools that are powerful but have steep learning curves

AstraGuard AI bridges this gap by providing:

✅ Real-World Context: Security operations modeled after actual CubeSat mission phases
✅ Hands-On Learning: Practical tools with educational guidance built-in
✅ Privacy-First AI: 100% local processing—no data leaves your machine
✅ Production-Ready Code: Clean, well-documented codebase suitable for real deployments
✅ Adaptive Intelligence: Context-aware decisions based on mission phase and historical patterns

Target Audience

AstraGuard AI is designed for:

Audience	What They'll Learn	How They'll Benefit
🎓 Students	Security workflows, API design, ML integration	Hands-on experience with real security tools
👨‍💻 Developers	Offensive security, payload generation, threat modeling	Understanding of attack surfaces and defense strategies
🛡️ Security Practitioners	Automated threat detection, incident response	Practical tools for vulnerability assessment
🚀 Space Enthusiasts	CubeSat operations, telemetry analysis	Understanding of satellite security challenges

🏗️ System Architecture

High-Level Overview

AstraGuard AI uses a dual-engine architecture that separates execution from intelligence:

🏗️ System Architecture

📊 Architecture Overview

AstraGuard AI implements a sophisticated, event-driven architecture for real-time satellite telemetry monitoring and autonomous anomaly recovery. The system leverages vector embeddings, adaptive memory, and AI-powered reasoning to provide intelligent, self-healing capabilities.

graph TB
    subgraph Input["🛰️ Data Ingestion Layer"]
        A[Telemetry Stream<br/>Pathway Real-time Processing]
    end
    
    subgraph Processing["⚙️ Processing Layer"]
        B[Embedding Encoder<br/>Vector Transformation]
        C[Adaptive Memory Store<br/>Context-Aware Storage]
    end
    
    subgraph Intelligence["🧠 Intelligence Layer"]
        D[Anomaly Reasoning Agent<br/>AI-Powered Analysis]
    end
    
    subgraph Action["⚡ Action Layer"]
        E[Response Orchestrator<br/>Action Coordinator]
        F[System Recovery<br/>Self-Healing Mechanisms]
    end
    
    subgraph Monitoring["📊 Observability"]
        G[Dashboard<br/>Real-time Visualization]
    end
    
    A -->|Live Data Feed| B
    B -->|Vector Embeddings| C
    C -->|Historical Context| D
    B -->|Current Event Data| D
    D -->|Recovery Decision| E
    E -->|Automated Actions| F
    F -->|Performance Feedback| C
    
    D -.->|Reasoning Trace| G
    C -.->|Memory State| G
    E -.->|Action Status| G
    
    style A fill:#10b981,stroke:#059669,stroke-width:4px,color:#fff
    style B fill:#3b82f6,stroke:#2563eb,stroke-width:3px,color:#fff
    style C fill:#8b5cf6,stroke:#7c3aed,stroke-width:3px,color:#fff
    style D fill:#f59e0b,stroke:#d97706,stroke-width:4px,color:#fff
    style E fill:#ef4444,stroke:#dc2626,stroke-width:3px,color:#fff
    style F fill:#06b6d4,stroke:#0891b2,stroke-width:3px,color:#fff
    style G fill:#ec4899,stroke:#db2777,stroke-width:3px,color:#fff
    
    classDef inputClass fill:#d1fae5,stroke:#6ee7b7,stroke-width:3px,color:#065f46
    classDef processClass fill:#dbeafe,stroke:#93c5fd,stroke-width:3px,color:#1e40af
    classDef intelligenceClass fill:#fef3c7,stroke:#fcd34d,stroke-width:3px,color:#92400e
    classDef actionClass fill:#fee2e2,stroke:#fca5a5,stroke-width:3px,color:#991b1b
    classDef monitorClass fill:#fce7f3,stroke:#f9a8d4,stroke-width:3px,color:#9f1239
    
    class Input inputClass
    class Processing processClass
    class Intelligence intelligenceClass
    class Action actionClass
    class Monitoring monitorClass

🔧 Core Components

🛰️ Telemetry Stream (Pathway)

Purpose: Real-time data ingestion and stream processing

Key Features:

Continuous satellite telemetry monitoring
High-throughput data streaming (1000+ events/sec)
Protocol support: MQTT, WebSocket, gRPC
Fault-tolerant message queuing

Technologies:

Pathway for real-time streaming
Apache Kafka for message brokering
Protocol Buffers for serialization

# Example: Telemetry ingestion
stream = pathway.io.kafka.read(
    topic="satellite-telemetry",
    schema=TelemetrySchema,
    autocommit_duration_ms=1000
)

📊 Embedding Encoder

Purpose: Transform raw telemetry into semantic vector representations

Key Features:

Multi-modal embedding (numerical, categorical, temporal)
Dimensionality: 768-dimensional vectors
Context-aware encoding with attention mechanisms
Real-time transformation (<10ms latency)

Technologies:

Sentence Transformers
Custom trained embeddings on satellite data
FAISS for vector indexing

# Vector transformation
embeddings = encoder.encode(
    telemetry_data,
    normalize=True,
    batch_size=32
)

# Index for similarity search
index.add(embeddings)

🧠 Adaptive Memory Store

Purpose: Context-aware storage with semantic search capabilities

Key Features:

Vector database with similarity search
Temporal context preservation
Automatic memory consolidation
Query latency: <50ms (p99)

Storage Strategy:

Short-term: Redis (1-hour TTL)
Long-term: PostgreSQL with pgvector
Archive: S3 cold storage

# Semantic search
similar_events = memory.search(
    query_vector=current_embedding,
    top_k=10,
    filters={"timeframe": "24h"}
)

# Pattern retrieval
patterns = memory.get_patterns(
    anomaly_type="temperature_spike"
)

🤖 Anomaly Reasoning Agent

Purpose: AI-powered analysis and decision-making engine

Key Features:

Multi-model ensemble (GPT-4, Claude, custom LSTM)
Chain-of-thought reasoning with explanations
Confidence scoring and uncertainty quantification
Continuous learning from feedback

Detection Capabilities:

✅ Temperature anomalies
✅ Power fluctuations
✅ Communication degradation
✅ Orbital drift patterns
✅ Component failures

# Anomaly detection
result = agent.analyze(
    current_state=telemetry,
    historical_context=memory_context,
    explain=True
)

# Response
{
    "anomaly_detected": True,
    "confidence": 0.94,
    "type": "thermal_anomaly",
    "reasoning": "...",
    "recommended_action": "..."
}

⚡ Response Orchestrator

Purpose: Coordinate and execute recovery workflows

Key Features:

Multi-step workflow orchestration
Parallel action execution
Rollback mechanisms for failed actions
Priority-based task scheduling

Recovery Strategies:

🔄 Automated subsystem restart
🌡️ Thermal management adjustments
📡 Communication protocol switching
🔋 Power redistribution
🛡️ Safe mode activation

# Workflow execution
workflow = Workflow([
    Step("isolate_subsystem"),
    Step("run_diagnostics"),
    Step("apply_fix", 
         rollback="restore_backup"),
    Step("verify_recovery")
])

orchestrator.execute(
    workflow,
    timeout=300,
    retry_policy="exponential"
)

🛰️ System Recovery

Purpose: Self-healing mechanisms and feedback loops

Key Features:

Automated recovery action execution
Health check verification
Performance metrics collection
Feedback loop to improve future decisions

Recovery Metrics:

Mean Time To Detect (MTTD): <2 minutes
Mean Time To Recover (MTTR): <5 minutes
Success Rate: 94.7%
False Positive Rate: <2%

# Recovery execution
recovery.execute_action(
    action=recommended_action,
    validate=True,
    collect_metrics=True
)

# Feedback
recovery.report_outcome(
    success=True,
    recovery_time=180,
    side_effects=None
)

📊 Monitoring Dashboard

Purpose: Real-time visualization and system transparency

Key Features:

Live telemetry visualization
Anomaly detection timeline
Reasoning trace explorer
Action history and audit logs

Metrics Tracked:

System health scores
Anomaly detection rate
Recovery success metrics
Model performance indicators
Resource utilization

// Dashboard real-time updates
dashboard.subscribe([
  'telemetry.live',
  'anomalies.detected',
  'actions.executed',
  'memory.state'
])

// Visualization
dashboard.render({
  charts: ['timeseries', 'heatmap'],
  refresh_rate: '1s'
})

🔄 Data Flow Sequence

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#10b981','primaryTextColor':'#fff','primaryBorderColor':'#059669','lineColor':'#3b82f6','secondaryColor':'#8b5cf6','tertiaryColor':'#f59e0b','noteBkgColor':'#1e293b','noteTextColor':'#fff','noteBorderColor':'#3b82f6'}}}%%
sequenceDiagram
    autonumber
    participant T as 🛰️<br/>Telemetry<br/>Stream
    participant E as 📊<br/>Embedding<br/>Encoder
    participant M as 💾<br/>Adaptive<br/>Memory
    participant A as 🧠<br/>AI Reasoning<br/>Agent
    participant O as ⚡<br/>Response<br/>Orchestrator
    participant R as 🔧<br/>System<br/>Recovery
    participant D as 📈<br/>Real-time<br/>Dashboard
    
    rect rgba(16, 185, 129, 0.15)
    Note over T,E: 🚀 PHASE 1: Data Ingestion & Transformation
    T->>+E: Stream raw telemetry data<br/>(1000+ events/sec)
    E->>E: Validate & normalize data
    E->>E: Generate 768-dim embeddings
    E-->>-T: ACK: Processing complete
    end
    
    rect rgba(59, 130, 246, 0.15)
    Note over E,M: 💾 PHASE 2: Storage & Context Retrieval
    E->>+M: Store vector embeddings<br/>with metadata
    M->>M: Index in FAISS<br/>(O(log n) search)
    M-->>-E: Confirm: Indexed successfully
    
    E->>+A: Forward current event<br/>+ embeddings
    M->>+A: Retrieve historical context<br/>(top-k=10 similar events)
    end
    
    rect rgba(245, 158, 11, 0.15)
    Note over A: 🔍 PHASE 3: Anomaly Detection & Analysis
    A->>A: Compute anomaly score<br/>(ensemble models)
    A->>A: Generate confidence metrics<br/>(0.0 - 1.0)
    
    alt Anomaly Detected (confidence > 0.85)
        A->>A: Execute chain-of-thought<br/>reasoning process
        A->>A: Identify root cause
        A->>+D: Stream reasoning trace<br/>for transparency
        D-->>-A: Logged to dashboard
    else Normal Operation
        A->>D: Update healthy status
        Note over A: Continue monitoring
    end
    end
    
    rect rgba(239, 68, 68, 0.15)
    Note over A,O: 🎯 PHASE 4: Decision Making & Planning
    A->>+O: Send recovery recommendation<br/>with action priority
    O->>O: Validate action feasibility
    O->>O: Build execution workflow<br/>(DAG-based)
    O->>O: Allocate resources
    O-->>-A: Confirm: Workflow ready
    end
    
    rect rgba(6, 182, 212, 0.15)
    Note over O,R: 🔧 PHASE 5: Automated Recovery
    O->>+R: Execute recovery workflow
    
    par Parallel Recovery Actions
        R->>R: Action 1: Isolate subsystem
        R->>R: Action 2: Run diagnostics
        R->>R: Action 3: Apply configuration fix
    and Health Monitoring
        R->>D: Stream recovery status<br/>(real-time updates)
    end
    
    R->>R: Verify system health
    
    alt Recovery Successful ✅
        R->>+M: Report success + metrics<br/>(recovery_time, steps_taken)
        M->>M: Update success patterns
        M-->>-R: Pattern learned
        R->>D: ✅ Recovery completed
    else Recovery Failed ❌
        R->>O: Trigger rollback procedure
        R->>D: ⚠️ Alert: Manual intervention needed
    end
    
    R-->>-O: Recovery outcome reported
    end
    
    rect rgba(139, 92, 246, 0.15)
    Note over M,A: 🔄 PHASE 6: Continuous Learning
    M->>+A: Push updated context<br/>with new patterns
    A->>A: Retrain anomaly detection<br/>(incremental learning)
    A->>A: Adjust confidence thresholds
    A-->>-M: Model updated successfully
    
    Note over T,D: 🔁 System continues monitoring...<br/>Ready for next event
    end
    
    rect rgba(236, 72, 153, 0.15)
    Note over D: 📊 OBSERVABILITY: Continuous Monitoring
    D->>D: Aggregate metrics across all phases
    D->>D: Generate real-time visualizations
    D->>D: Track KPIs: MTTD, MTTR, Success Rate
    end

📋 Sequence Breakdown

Phase	Components	Actions	Duration
🚀 Phase 1 Ingestion	Telemetry → Encoder	• Stream validation • Data normalization • Vector embedding generation	`<50ms`
💾 Phase 2 Storage	Encoder → Memory	• Vector indexing (FAISS) • Context retrieval (k-NN) • Metadata tagging	`<100ms`
🔍 Phase 3 Analysis	Memory + Agent	• Anomaly scoring • Confidence computation • Root cause analysis • Reasoning trace generation	`1-5s`
🎯 Phase 4 Planning	Agent → Orchestrator	• Action validation • Workflow creation (DAG) • Resource allocation • Priority assignment	`500ms-2s`
🔧 Phase 5 Recovery	Orchestrator → Recovery	• Parallel action execution • Health verification • Rollback on failure • Metrics collection	`2-5min`
🔄 Phase 6 Learning	Recovery → Memory → Agent	• Pattern storage • Model retraining • Threshold adjustment • Knowledge consolidation	`Background`

🎯 Key Decision Points

graph LR
    A{Anomaly<br/>Detected?} -->|Yes<br/>conf > 0.85| B[Generate<br/>Recovery Plan]
    A -->|No| C[Continue<br/>Monitoring]
    
    B --> D{Recovery<br/>Successful?}
    D -->|Yes ✅| E[Update<br/>Patterns]
    D -->|No ❌| F[Trigger<br/>Rollback]
    
    E --> G[Learn &<br/>Improve]
    F --> H[Manual<br/>Intervention]
    
    style A fill:#f59e0b,stroke:#d97706,stroke-width:3px,color:#fff
    style B fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
    style C fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style D fill:#f59e0b,stroke:#d97706,stroke-width:3px,color:#fff
    style E fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style F fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style G fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    style H fill:#f97316,stroke:#ea580c,stroke-width:2px,color:#fff

⚡ Performance Metrics

Metric	Target	Actual	Status
End-to-End Latency	<30s	18.4s	✅
Phase 1-2 (Ingestion)	<150ms	127ms	✅
Phase 3 (Analysis)	<5s	3.2s	✅
Phase 4 (Planning)	<2s	1.4s	✅
Phase 5 (Recovery)	<5min	4m 32s	✅
Throughput	1000 events/s	1247 events/s	✅
Success Rate	>95%	94.7%	⚠️

🔄 Feedback Loop Illustration

graph TD
    A[📥 New Telemetry Event] --> B{Processing}
    B --> C[🧠 AI Analysis]
    C --> D{Anomaly?}
    
    D -->|Yes| E[⚡ Execute Recovery]
    D -->|No| F[✅ Normal State]
    
    E --> G{Success?}
    G -->|Yes| H[💾 Learn Pattern]
    G -->|No| I[🔄 Retry/Escalate]
    
    H --> J[🎯 Improve Models]
    F --> K[📊 Update Baseline]
    I --> L[👨‍💻 Human Review]
    
    J --> M[🔁 Next Event]
    K --> M
    L --> M
    
    M --> A
    
    style A fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style C fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style E fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style H fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    style J fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style M fill:#ec4899,stroke:#db2777,stroke-width:2px,color:#fff

⚙️ Technology Stack

Layer	Technologies
Streaming
AI/ML
Vector DB
Storage
Orchestration
Monitoring

📈 Performance Characteristics

Metric	Target	Actual
Ingestion Throughput	1000 events/sec	1,247 events/sec ✅
Detection Latency (p99)	<30s	18.4s ✅
Recovery Time (MTTR)	<5 min	4m 32s ✅
False Positive Rate	<3%	1.8% ✅
System Availability	99.9%	99.94% ✅
Vector Search Latency	<50ms	32ms ✅

🎯 Key Features

⚡ Real-time Processing

Sub-second data ingestion
Continuous stream processing
Zero-downtime deployments
Horizontal scalability

🧠 AI-Powered Intelligence

Multi-model ensemble reasoning
Explainable AI decisions
Confidence scoring
Continuous learning

🔄 Self-Healing

Automated anomaly recovery
Workflow orchestration
Rollback mechanisms
Health verification

📊 Full Observability

Real-time dashboards
Audit trails
Performance metrics
Reasoning transparency

🎯 Adaptive Learning

Feedback-driven improvements
Pattern recognition
Memory consolidation
Model retraining pipelines

🛡️ Production Ready

Fault tolerance
High availability
Security hardening
Comprehensive testing

🚀 Deployment Architecture

graph TB
    subgraph Cloud["☁️ Cloud Infrastructure (AWS/GCP)"]
        subgraph K8s["Kubernetes Cluster"]
            subgraph DataPlane["Data Plane"]
                Stream[Streaming Service<br/>3 replicas]
                Encoder[Encoder Service<br/>5 replicas]
                Agent[AI Agent Service<br/>3 replicas]
            end
            
            subgraph ControlPlane["Control Plane"]
                Orch[Orchestrator<br/>2 replicas]
                API[API Gateway<br/>3 replicas]
            end
        end
        
        subgraph Storage["💾 Storage Layer"]
            Redis[(Redis Cluster<br/>6 nodes)]
            Postgres[(PostgreSQL<br/>Primary + 2 Replicas)]
            Vector[(Vector DB<br/>FAISS Cluster)]
        end
        
        subgraph Monitoring["📊 Monitoring"]
            Grafana[Grafana]
            Prom[Prometheus]
            Logs[Loki]
        end
    end
    
    Ground[🌍 Ground Station] -->|Telemetry| Stream
    Satellite[🛰️ Satellites] -->|Data| Stream
    
    Stream --> Encoder
    Encoder --> Agent
    Agent --> Orch
    Orch --> Redis
    Orch --> Postgres
    Encoder --> Vector
    
    DataPlane -.-> Prom
    ControlPlane -.-> Prom
    Prom --> Grafana
    DataPlane -.-> Logs
    
    style Cloud fill:#0f172a,stroke:#3b82f6,stroke-width:3px,color:#fff
    style K8s fill:#1e293b,stroke:#06b6d4,stroke-width:3px,color:#fff
    style DataPlane fill:#334155,stroke:#10b981,stroke-width:2px,color:#fff
    style ControlPlane fill:#334155,stroke:#f59e0b,stroke-width:2px,color:#fff
    style Storage fill:#1e293b,stroke:#8b5cf6,stroke-width:3px,color:#fff
    style Monitoring fill:#1e293b,stroke:#ec4899,stroke-width:3px,color:#fff
    
    style Stream fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style Encoder fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
    style Agent fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style Orch fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style API fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    
    style Redis fill:#dc2626,stroke:#991b1b,stroke-width:2px,color:#fff
    style Postgres fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#fff
    style Vector fill:#7c3aed,stroke:#6d28d9,stroke-width:2px,color:#fff
    
    style Grafana fill:#f97316,stroke:#ea580c,stroke-width:2px,color:#fff
    style Prom fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style Logs fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    
    style Ground fill:#14b8a6,stroke:#0d9488,stroke-width:2px,color:#fff
    style Satellite fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff

📚 Related Documentation

🔗 Related Repositories

Built with ❤️ for autonomous satellite operations

Dual-Engine Design

1. 🛡️ Core Security Engine (The Muscle)

Technology: Python 3.9+
Purpose: Executes concrete security operations

Capabilities:

Packet Manipulation: Uses Scapy for deep packet inspection and crafting
Network Scanning: Integrates with Nmap for port scanning and service detection
Payload Delivery: Automated injection and testing of security payloads
Traffic Interception: Proxy integration with Burp Suite for man-in-the-middle analysis
Protocol Analysis: Deep inspection of network protocols and data streams

Design Philosophy:

Stateless and robust
Fail-safe by default
Does exactly what it's told—no surprises
Comprehensive logging for audit trails

Example Use Case:

# Security Engine performing network scan
from src.security_engine import NetworkScanner

scanner = NetworkScanner(target="192.168.1.0/24")
results = scanner.scan_ports([80, 443, 8080])
vulnerable_services = scanner.identify_vulnerabilities(results)

2. 🧠 AI Intelligence Layer (The Brain)

Technology: Python (LangChain/Ollama) + Node.js
Purpose: Analyzes context and makes intelligent decisions

Capabilities:

A. Attack Surface Analysis

Reads scan data from the Security Engine
Identifies "interesting" targets based on:
- Service versions with known CVEs
- Unusual port configurations
- Legacy protocols still in use
- Misconfigured services
Prioritizes targets by exploitability

B. Smart Payload Generation

Crafts payloads specific to the target technology stack
Example: "This looks like an older MongoDB instance—try these NoSQL injection vectors"
Adapts to application framework (Django, Flask, Express, etc.)
Considers defense mechanisms detected during reconnaissance

C. Risk Assessment

Scores vulnerabilities based on real-world exploitability
Goes beyond CVSS scores by considering:
- Attack complexity
- Available exploit code
- Patch availability
- Impact on mission objectives
- Current mission phase constraints

D. Contextual Decision Making

Uses historical anomaly patterns from Adaptive Memory Store
Adjusts responses based on mission phase
Learns from previous incidents to improve detection

Privacy Guarantee:

100% Local Processing: All AI models run via Ollama on your machine
No Cloud Calls: Sensitive scan data never leaves your infrastructure
Offline Capable: Works without internet connection
Audit Trail: All AI decisions are logged with reasoning traces

Example Use Case:

# AI Layer analyzing attack surface
from src.ai_agent import ThreatAnalyzer

analyzer = ThreatAnalyzer(model="llama3")
scan_results = load_scan_data("network_scan.json")

analysis = analyzer.analyze_attack_surface(scan_results)
# Output: {
#   "high_priority_targets": [...],
#   "recommended_payloads": [...],
#   "risk_scores": {...},
#   "reasoning": "Detected outdated Apache version 2.4.29..."
# }

Data Flow

Telemetry Ingestion: Satellite telemetry streams into the system via Pathway
Encoding: Data is embedded into vector representations for semantic analysis
Memory Storage: Historical context is stored in the Adaptive Memory Store
Anomaly Detection: AI agent analyzes current data against historical patterns
Policy Evaluation: Mission phase policies determine appropriate response
Action Orchestration: Response orchestrator executes recovery actions
Feedback Loop: Action results feed back into memory for continuous learning
Dashboard Update: Real-time updates pushed to monitoring interface

✨ Key Features

Core Capabilities

Feature	Description	Technology
🤖 AI Threat Assistant	Local LLM-powered vulnerability analysis using Llama 3 or Mistral models	LangChain + Ollama
🛡️ Offensive Tooling Suite	Comprehensive payload generation, injection testing, and security scanning	Python + Scapy + Nmap
📊 Smart Dashboard	Real-time visualization of threats, system health, and security metrics	Streamlit + React
🔬 Research Lab	Integrated environment for testing security hypotheses and verifying findings	Python + Jupyter
⚡ Real-Time Streaming	High-performance telemetry processing with sub-second latency	Pathway
🧠 Adaptive Memory	Context-aware decision making based on historical anomaly patterns	Vector embeddings
🎯 Smart Prioritization	Intelligent target selection based on exploitability and mission impact	AI reasoning
� Explainable Anomaly Insights	Per-anomaly explanations including feature importances, SHAP values, and confidence scores to increase operator trust and transparency	React + visualization components
�📈 Health Monitoring	Component-level degradation tracking with automated failover	Centralized error handling

🚀 Mission-Phase Aware Fault Response

AstraGuard AI understands that CubeSat operations have different constraints at different stages. The same anomaly might trigger different responses depending on the current mission phase.

Phase Definitions & Policies

┌─────────────────────────────────────────────────────────────┐
│                     MISSION PHASES                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  LAUNCH                                                     │
│  ├─ Duration: T-0 to orbit insertion                        │
│  ├─ Priority: System survival                               │
│  ├─ Constraint: Minimal actions to avoid destabilization    │
│  └─ Response: LOG_ONLY (no active interventions)            │
│                                                             │
│  DEPLOYMENT                                                 │
│  ├─ Duration: Orbit insertion to systems checkout           │
│  ├─ Priority: Safe deployment of components                 │
│  ├─ Constraint: Limited responses, avoid disruption         │
│  └─ Response: STABILIZE (conservative recovery)             │
│                                                             │
│  NOMINAL_OPS                                                │
│  ├─ Duration: Normal operational phase                      │
│  ├─ Priority: Performance optimization                      │
│  ├─ Constraint: None (full autonomy)                        │
│  └─ Response: FULL_RECOVERY (all actions available)         │
│                                                             │
│  PAYLOAD_OPS                                                │
│  ├─ Duration: Active science/mission operations             │
│  ├─ Priority: Science data collection                       │
│  ├─ Constraint: Careful with power/attitude changes         │
│  └─ Response: PAYLOAD_SAFE (mission-aware recovery)         │
│                                                             │
│  SAFE_MODE                                                  │
│  ├─ Duration: Critical failure or emergency                 │
│  ├─ Priority: System survival only                          │
│  ├─ Constraint: Minimal subsystem activation                │
│  └─ Response: SURVIVAL_ONLY (log + essential recovery)      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Example: Voltage Anomaly Response by Phase

Scenario: Battery voltage drops to 6.8V (nominal: 7.4V)

Phase	Detection	Response	Reasoning
LAUNCH	✅ Detected	📝 Log only	System under max stress; active response could cause instability
DEPLOYMENT	✅ Detected	⚡ Reduce power draw by 20%	Safe recovery without disrupting deployment sequence
NOMINAL_OPS	✅ Detected	🔄 Full diagnostic + power optimization + alert ground station	Full autonomy to resolve issue
PAYLOAD_OPS	✅ Detected	🎯 Pause non-critical payload, maintain attitude	Protect science mission while addressing power issue
SAFE_MODE	✅ Detected	🛡️ Log + enter deep power-saving mode	Survival takes absolute priority

Configuration

Mission phase policies are fully configurable:

# config/mission_phases.yaml
phases:
  LAUNCH:
    max_actions: 0
    allowed_actions: [LOG_ONLY]
    power_change_limit: 0%
    
  NOMINAL_OPS:
    max_actions: unlimited
    allowed_actions: [LOG, ALERT, RECOVER, OPTIMIZE]
    power_change_limit: 50%

📖 Complete Documentation: Mission-Phase Policies Guide

🛡️ Centralized Error Handling & Graceful Degradation

AstraGuard AI is designed to never crash. The system includes a comprehensive error handling layer that ensures resilience under all failure conditions.

Design Principles

Fail Gracefully: Component failures trigger fallback behavior instead of system crashes
Centralized Handling: All errors flow through a single error handling pipeline
Structured Logging: Errors include full context (component, phase, telemetry state)
Health Tracking: Real-time component health exposed to monitoring dashboard
Smart Fallbacks: Each component has a defined degraded operating mode

Error Handling Architecture

┌──────────────────────────────────────────────────────┐
│              Component Failure Scenarios             │
├──────────────────────────────────────────────────────┤
│                                                      │
│  🧠 AI Model Loading Fails                           │
│  └─► Fallback: Heuristic anomaly detection           │
│                                                      │
│  📊 Memory Store Unavailable                         │
│  └─► Fallback: Stateless operation (no history)      │
│                                                      │
│  🎯 Policy Evaluation Fails                          │
│  └─► Fallback: Safe default (LOG_ONLY mode)          │
│                                                      │
│  ⚡ Action Execution Fails                           │
│  └─► Fallback: Log error + retry with backoff        │
│                                                      │
│  🗄️ Database Connection Lost                         │
│  └─► Fallback: In-memory buffer + reconnect attempt  │
│                                                      │
│  🌐 API Endpoint Unreachable                         │
│  └─► Fallback: Queue request + circuit breaker       │
│                                                      │
└──────────────────────────────────────────────────────┘

Health Monitoring States

Each component reports one of three health states:

🟢 HEALTHY: Operating normally with full functionality
🟡 DEGRADED: Partially operational, using fallback behavior
🔴 FAILED: Component unavailable, critical functions impaired

Example: Handling Model Failure

from src.ai_agent import AnomalyDetector
from src.core.error_handler import handle_component_failure

try:
    detector = AnomalyDetector(model="llama3")
    result = detector.analyze(telemetry)
except ModelLoadError as e:
    # Graceful fallback to heuristic detection
    handle_component_failure("ai_model", e)
    detector = HeuristicDetector()  # Simple threshold-based detection
    result = detector.analyze(telemetry)
    result["mode"] = "degraded"

Dashboard Health View

┌─────────────────────────────────────────────────────┐
│                SYSTEM HEALTH                        │
├─────────────────────────────────────────────────────┤
│  🧠 AI Model              🟢 HEALTHY                │
│  📊 Memory Store          🟢 HEALTHY                │
│  🎯 Policy Engine         🟢 HEALTHY                │
│  ⚡ Action Orchestrator   🟡 DEGRADED (retry mode)  │
│  🗄️ Database              🟢 HEALTHY                │
│  🌐 API Server            🟢 HEALTHY                │
├─────────────────────────────────────────────────────┤
│  Overall Status: OPERATIONAL (1 component degraded) │
└─────────────────────────────────────────────────────┘

📖 Implementation Guide: Error Handling Best Practices

🌐 REST API for External Integration

AstraGuard AI provides a production-ready FastAPI server for programmatic access and integration with external systems.

API Features

✅ Input Validation: Pydantic models with comprehensive data validation
✅ OpenAPI Documentation: Interactive Swagger UI at /docs
✅ CORS Support: Ready for web frontend integration
✅ Batch Processing: Submit 1-1000 telemetry points in a single request
✅ Rate Limiting: Configurable limits to prevent abuse
✅ Authentication: API key support for production deployments
✅ Versioning: /api/v1/ prefix for future compatibility
✅ 100% Test Coverage: 23/23 tests passing

Endpoints Reference

Endpoint	Method	Description	Rate Limit
`/api/v1/telemetry`	POST	Submit single telemetry point	1000/hour
`/api/v1/telemetry/batch`	POST	Submit 1-1000 telemetry points	100/hour
`/api/v1/status`	GET	System health & component status	Unlimited
`/api/v1/phase`	GET	Get current mission phase	Unlimited
`/api/v1/phase`	POST	Update mission phase	50/hour
`/api/v1/memory/stats`	GET	Memory store statistics	500/hour
`/api/v1/history/anomalies`	GET	Query anomaly history (with filters)	200/hour
`/api/v1/history/export`	GET	Export historical data to JSON/CSV	10/hour

Quick Start Example

import requests

# Submit a single telemetry point
response = requests.post('http://localhost:8000/api/v1/telemetry', json={
    "timestamp": "2026-01-04T12:00:00Z",
    "voltage": 7.2,
    "temperature": 35.5,
    "gyro": 0.08,
    "mission_phase": "NOMINAL_OPS"
})

result = response.json()

if result['is_anomaly']:
    print(f"⚠️  ANOMALY DETECTED!")
    print(f"   Type: {result['anomaly_type']}")
    print(f"   Confidence: {result['confidence']:.2%}")
    print(f"   Recommended Action: {result['recommended_action']}")
    print(f"   Reasoning: {result['reasoning']}")
else:
    print("✅ All systems nominal")

Batch Processing Example

# Submit historical data for analysis
telemetry_batch = [
    {"timestamp": "2026-01-04T12:00:00Z", "voltage": 7.4, "temperature": 32.0, "gyro": 0.02},
    {"timestamp": "2026-01-04T12:01:00Z", "voltage": 7.3, "temperature": 32.5, "gyro": 0.03},
    # ... up to 1000 items
]

response = requests.post('http://localhost:8000/api/v1/telemetry/batch', json={
    "items": telemetry_batch
})

result = response.json()
print(f"Processed: {result['processed_count']}/{result['total_count']}")
print(f"Anomalies detected: {result['anomaly_count']}")

Mission Phase Management

# Check current mission phase
response = requests.get('http://localhost:8000/api/v1/phase')
phase_info = response.json()

print(f"Current Phase: {phase_info['phase']}")
print(f"Constraints: {phase_info['constraints']}")

# Update mission phase
response = requests.post('http://localhost:8000/api/v1/phase', json={
    "phase": "PAYLOAD_OPS",
    "reason": "Starting science data collection"
})

Querying Historical Data

# Get anomalies from the last 24 hours
response = requests.get('http://localhost:8000/api/v1/history/anomalies', params={
    "start_time": "2026-01-03T12:00:00Z",
    "end_time": "2026-01-04T12:00:00Z",
    "anomaly_type": "VOLTAGE_DROP",
    "min_confidence": 0.8
})

anomalies = response.json()
for anomaly in anomalies['items']:
    print(f"[{anomaly['timestamp']}] {anomaly['type']} - {anomaly['action_taken']}")

Health Monitoring

# Check system health
response = requests.get('http://localhost:8000/api/v1/status')
status = response.json()

print(f"Overall Status: {status['overall_status']}")
for component, health in status['components'].items():
    icon = "🟢" if health['status'] == "HEALTHY" else "🟡" if health['status'] == "DEGRADED" else "🔴"
    print(f"  {icon} {component}: {health['status']}")

📖 Complete Examples: API Usage Guide
📖 API Reference: Access interactive docs at http://localhost:8000/docs after starting the server

🧠 Operator Feedback Schema (#50)

Purpose: Type-safe data contract for human-in-the-loop learning loop. Enables operators to validate AI-recommended recovery actions and provide feedback for continuous improvement.

Schema - FeedbackEvent:

from models.feedback import FeedbackEvent, FeedbackLabel

event = FeedbackEvent(
    fault_id="power_f001",
    anomaly_type="power_subsystem",
    recovery_action="emergency_power_cycle",
    label=FeedbackLabel.CORRECT,
    mission_phase="NOMINAL_OPS",
    operator_notes="Recovered 2.3s - optimal response",
    confidence_score=0.95
)

Features:

✅ Pydantic v2 validation with strict type checking
✅ Mission phase enum validation (LAUNCH, DEPLOYMENT, NOMINAL_OPS, PAYLOAD_OPS, SAFE_MODE)
✅ Feedback labels for multi-class classification (CORRECT, INSUFFICIENT, WRONG)
✅ Confidence scoring (0.0-1.0) for operator certainty
✅ Optional operator notes (max 500 chars) for context
✅ Automatic timestamp generation with ISO format serialization
✅ 100% test coverage with 12 comprehensive test cases
✅ Compact JSON serialization (<300B/event) for efficient storage

Usage Example:

# Validate operator feedback
from models.feedback import FeedbackEvent, FeedbackLabel

feedback = FeedbackEvent(
    fault_id="thermal_001",
    anomaly_type="thermal_spike",
    recovery_action="heater_cooldown",
    label=FeedbackLabel.CORRECT,
    mission_phase="PAYLOAD_OPS",
    operator_notes="Action worked within 45 seconds"
)

# Serialize to JSON for storage/transmission
json_data = feedback.model_dump_json()
print(f"Event size: {len(json_data)} bytes")

# All validations enforced:
# - fault_id: 1-64 chars
# - anomaly_type: 1-64 chars
# - recovery_action: 1-128 chars
# - mission_phase: must match regex pattern
# - confidence_score: 0.0 ≤ score ≤ 1.0
# - operator_notes: max 500 chars (optional)

Validation Examples:

# ✅ Valid - all constraints satisfied
event = FeedbackEvent(
    fault_id="f123", anomaly_type="power",
    recovery_action="reset", label=FeedbackLabel.INSUFFICIENT,
    mission_phase="NOMINAL_OPS"
)

# ❌ Invalid - mission_phase must be uppercase
FeedbackEvent(..., mission_phase="nominal_ops")

# ❌ Invalid - confidence_score must be 0.0-1.0
FeedbackEvent(..., confidence_score=1.5)

# ❌ Invalid - operator_notes exceeds max_length
FeedbackEvent(..., operator_notes="x" * 501)

Blocking Issues:

#51: @log_feedback decorator integration
#52: Database storage layer
#53: Feedback aggregation analysis
#54: ML model retraining pipeline
#55: Dashboard feedback visualization
#56: Feedback export/reporting

📝 Action Logging with `@log_feedback` Decorator (#51)

Purpose: Automatically capture recovery action results without modifying existing code. Provides non-blocking feedback event logging to pending store.

How It Works:

from security_engine.decorators import log_feedback

# Decorate any recovery function - no changes to logic needed
@log_feedback(fault_id="power_loss_001", anomaly_type="power_subsystem")
def emergency_power_cycle(system_state) -> bool:
    """Recovery action with automatic feedback logging."""
    # ... existing recovery logic ...
    return success  # True/False

Automatic Behavior:

Execution: Function runs with original logic unchanged
Capture: Result (True/False) → confidence score (1.0/0.5)
Store: FeedbackEvent appended to feedback_pending.json
Non-blocking: Errors in logging don't affect recovery

Features:

✅ Thread-safe atomic appends to feedback_pending.json
✅ Auto-extracts mission_phase from system_state
✅ Confidence scoring: success=1.0, failure=0.5
✅ Preserves all return values (True, False, None, etc.)
✅ Non-blocking error handling (logging errors don't break recovery)
✅ 20+ comprehensive tests including concurrency chaos
✅ 100% code coverage

Example - Recovery Action Sequence:

@log_feedback("thermal_spike", "thermal")
def activate_passive_cooling(state):
    return True  # Auto-logged: confidence_score=1.0

@log_feedback("thermal_spike_fail", "thermal")
def thermal_shutdown(state):
    return False  # Auto-logged: confidence_score=0.5

# Usage - both auto-log to feedback_pending.json
state = SystemState(mission_phase="PAYLOAD_OPS")
activate_passive_cooling(state)  # ✅ Logged
thermal_shutdown(state)          # ✅ Logged (even on failure)

Pending Store Format (feedback_pending.json):

[
  {
    "fault_id": "power_loss_001",
    "anomaly_type": "power_subsystem",
    "recovery_action": "emergency_power_cycle",
    "mission_phase": "NOMINAL_OPS",
    "confidence_score": 1.0,
    "timestamp": "2026-01-04T14:30:22.123456"
  }
]

Integration with Policy Engine:

# Any recovery function can be decorated
from security_engine.decorators import log_feedback

# In backend/recovery_orchestrator.py or policy_engine.py:
@log_feedback("circuit_break_001", "circuit_breaker")
async def circuit_recovery(state):
    return await _perform_circuit_reset(state)

@log_feedback("cache_purge_001", "cache")
def cache_recovery(state):
    return _clear_cache(state)

Blocking Issues:

#52: Consume feedback_pending.json via CLI
#53-56: Feedback analytics and retraining pipeline

🎯 Project Goals (ECWoC '26)

As part of Elite Coders Winter of Code 2026, AstraGuard AI has clear deliverables and learning objectives:

Primary Objectives

✅ Stable AI Security Module: Build a production-ready AI assistant for intelligent vulnerability detection
- Target: 95%+ accuracy on test dataset
- Support for 3+ LLM backends (Llama 3, Mistral, GPT-4)
- Response time < 500ms per analysis
✅ Contributor-Friendly Issues: Create 20+ well-scoped issues with learning notes
- 10 beginner issues (documentation, testing, UI)
- 7 intermediate issues (feature implementation, API design)
- 3 advanced issues (ML integration, performance optimization)
✅ Comprehensive Documentation: Improve onboarding and technical docs
- Getting Started guide (< 10 minutes to first run)
- Architecture deep-dive
- API reference with examples
- Contributing guidelines
✅ Automated Testing: Implement CI/CD pipelines
- Unit tests (target: 80%+ coverage)
- Integration tests for API endpoints
- Payload validation tests
- Attack surface analysis tests
✅ Production-Ready MVP: Ship a fully working system
- All core features implemented
- Dashboard with real-time updates
- API with OpenAPI documentation
- Deployment-ready Docker containers

Success Metrics

Metric	Target	Current Status
Test Coverage	80%+	23/23 API tests passing ✅
API Response Time	< 200ms	Achieved ✅
Documentation Pages	10+	12 pages ✅
Contributor Issues	20+	15 open, 8 needed
PR Review Time	< 72 hours	48-hour average ✅
Active Contributors	6-10	4 active, recruiting

Learning Outcomes for Contributors

By the end of ECWoC '26, contributors will have hands-on experience with:

🛡️ Security: Vulnerability assessment, payload generation, threat modeling
🧠 AI/ML: LLM integration, prompt engineering, embedding models
⚙️ Backend: FastAPI, async programming, database design
🎨 Frontend: React, real-time dashboards, data visualization
🔧 DevOps: Docker, CI/CD, automated testing
📚 Best Practices: Code review, documentation, open-source collaboration

🤝 Project Admin Commitment

As maintainers participating in ECWoC '26, we commit to creating a welcoming, educational, and productive environment for all contributors.

Our Commitments

1. ❤️ Active Maintenance

Daily Monitoring: Check issues and PRs at least once per day
Weekly Updates: Post progress updates every Friday
Responsive Communication: Reply to questions within 24 hours
Regular Releases: Ship new features every 2 weeks

2. ⚡ Timely Reviews

Initial Review: First review within 48 hours of PR submission
Final Review: Final decision within 72 hours
Constructive Feedback: Detailed comments with improvement suggestions
Pair Programming: Available for complex features via screen share

3. 📝 Clear Documentation

Issue Templates: Pre-filled templates with all necessary context
Learning Notes: Educational comments explaining why things work
Code Examples: Reference implementations for common patterns
Video Walkthroughs: Screen recordings for complex setup procedures

4. 🤝 Contributor Support

Onboarding Session: 30-minute video call for new contributors
Office Hours: Weekly 1-hour Q&A session on Discord
Mentorship: Direct support from maintainers on assigned issues
Recognition: Shout-outs for quality contributions in release notes

5. 📜 Code of Conduct

Zero Tolerance: Harassment, discrimination, or toxicity results in immediate removal
Inclusive Language: Maintain welcoming, respectful communication
Credit Attribution: Proper recognition for all contributions
Transparent Decisions: Explain reasoning for accepted/rejected PRs

Admin Contact

Primary Maintainer: @sr-857
Response Time: < 24 hours for GitHub mentions
Office Hours: Fridays 6-7 PM IST
Emergency Contact: Via WhatsApp group (see Community section)

📜 ECWoC Code of Conduct: https://elitecoders.xyz/coc

🧠 Mentorship & Support

We want AstraGuard AI to feel like a real training ground, not just a code repository. Our goal is to make your contribution experience meaningful and educational.

What Makes Our Mentorship Different

📚 Comprehensive Onboarding

Week 1: Getting Started

📄 Read CONTRIBUTING.md and project documentation
🛠️ Complete local setup (we'll help debug any issues)
🎯 Choose your first issue from the "good first issue" label
💬 Introduction in WhatsApp group

Week 2: First Contribution

🔍 Work on assigned issue with maintainer guidance
💡 Learn project conventions and coding standards
🔄 Submit first PR with detailed description
👀 Receive thorough code review with learning notes

Week 3+: Regular Contributions

🚀 Take on more complex issues
🎓 Participate in architectural discussions
🤝 Help review other contributors' PRs
🏆 Build portfolio-worthy features

🏷️ Well-Crafted Issues

Every issue includes:

## 📋 Issue Template

### Description
[Clear explanation of what needs to be built/fixed]

### Learning Objectives
[What you'll learn by working on this]

### Technical Context
[Relevant architecture, files, and concepts]

### Implementation Hints
[Guidance on approach, not complete solution]

### Resources
[Links to docs, tutorials, similar implementations]

### Definition of Done
[Specific criteria for completion]

### Estimated Time
[Realistic time estimate]

⚡ Fast PR Reviews

Our review process:

Automated Checks (< 5 minutes): Linting, tests, build verification
Initial Review (< 48 hours): High-level feedback on approach
Detailed Review (< 72 hours): Line-by-line comments with explanations
Final Approval (< 96 hours): Merge or request final changes

Review Quality Promise:

✅ Constructive feedback, never dismissive
✅ Explain why changes are needed, not just what
✅ Provide code examples for complex suggestions
✅ Celebrate good code and creative solutions

💬 Communication Channels

Channel	Purpose	Response Time
GitHub Issues	Bug reports, feature requests	< 24 hours
GitHub Discussions	Technical questions, design discussions	< 48 hours
WhatsApp Group	Quick questions, coordination	< 6 hours
Discord Office Hours	Deep-dive troubleshooting, pair programming	Fridays 6-7 PM IST
Email	Private concerns, admin questions	< 48 hours

🎓 Guided Learning Path

We've organized issues by skill level:

🟢 Beginner (Good First Issue)

Documentation improvements
Test case additions
UI enhancements
Configuration updates

🟡 Intermediate

API endpoint implementation
Dashboard feature additions
Error handling improvements
Performance optimizations

🔴 Advanced

ML model integration
Distributed system features
Security protocol implementation
Architecture redesigns

What We Expect from Contributors

🎯 Commitment: Finish what you start (or communicate blockers early)
💬 Communication: Ask questions when stuck, don't suffer in silence
📚 Learning: Read docs before asking, but do ask if docs are unclear
🤝 Collaboration: Be respectful, help others, give credit
✨ Quality: Submit clean code with tests and documentation

Support Resources

🛠️ Tech Stack

Frontend

Technology	Version	Purpose	Documentation
React	18.2+	UI framework	React Docs
TailwindCSS	3.4+	Styling	Tailwind Docs
Vite	5.0+	Build tool	Vite Docs
Recharts	2.10+	Data visualization	Recharts Docs
React Query	5.0+	Data fetching	TanStack Query

Backend

Technology	Version	Purpose	Documentation
Node.js	16+	JavaScript runtime	Node Docs
FastAPI	0.104+	Python API framework	FastAPI Docs
MongoDB	6.0+	Database	MongoDB Docs
Pathway	0.7+	Stream processing	Pathway Docs
Pydantic	2.5+	Data validation	Pydantic Docs

Security Engine

Technology	Version	Purpose	Documentation
Python	3.9+	Core language	Python Docs
Scapy	2.5+	Packet manipulation	Scapy Docs
Nmap	7.94+	Network scanning	Nmap Docs
ffuf	2.1+	Web fuzzing	ffuf GitHub
Requests	2.31+	HTTP client	Requests Docs

AI/ML Stack

Technology	Version	Purpose	Documentation
LangChain	0.1+	LLM orchestration	LangChain Docs
Ollama	0.1+	Local LLM runtime	Ollama Docs
Sentence Transformers	2.2+	Embeddings	SBERT Docs
NumPy	1.24+	Numerical computing	NumPy Docs
scikit-learn	1.3+	ML utilities	sklearn Docs

DevOps & Tools

Technology	Version	Purpose	Documentation
Docker	24.0+	Containerization	Docker Docs
GitHub Actions	N/A	CI/CD	Actions Docs
pytest	7.4+	Testing framework	pytest Docs
Black	23.0+	Code formatting	Black Docs
Burp Suite	Latest	Traffic analysis	Burp Docs

� Intelligent API Rate Limiting

AstraGuard AI features an advanced, adaptive rate limiting system that protects against abuse while ensuring optimal user experience:

Key Features

🧠 Adaptive Rate Limiting: Automatically adjusts limits based on real-time system health metrics
📊 System Health Integration: Monitors CPU, memory, active connections, and anomaly scores
🎯 Intelligent Queuing: Prioritizes critical requests during high load periods
👤 User Feedback: Provides clear notifications and graceful degradation
🔄 Auto-Retry Logic: Smart retry mechanisms with exponential backoff
⚡ Real-time Monitoring: Live system health indicators and request queue status

How It Works

Health Monitoring: Continuously monitors backend system health via /health/state endpoint
Dynamic Adjustment: Reduces rate limits when system health degrades (healthy → degraded → critical)
Request Queuing: Queues requests intelligently when limits are reached
User Notifications: Shows real-time feedback about rate limiting and system status
Graceful Degradation: Maintains functionality while protecting system stability

Configuration

# Environment Variables
LOG_LEVEL=INFO                    # Backend logging level
NEXT_PUBLIC_LOG_LEVEL=INFO        # Frontend logging level

Demo

Try the interactive API rate limiting demo in the frontend to see the system in action!

�📂 Project Structure

AstraGuard-AI/
│
├── .github/                          # GitHub configuration
│   ├── ISSUE_TEMPLATE/               # Issue templates
│   │   ├── bug_report.yml           # Bug report template
│   │   └── feature_request.yml      # Feature request template
│   └── workflows/                    # GitHub Actions workflows
│       ├── ci.yml                   # Continuous integration
│       └── deploy.yml               # Deployment pipeline
│
├── dashboard/                        # React frontend application
│   ├── public/                      # Static assets
│   ├── src/                         # Source code
│   │   ├── components/              # React components
│   │   │   ├── Dashboard.jsx       # Main dashboard
│   │   │   ├── TelemetryChart.jsx  # Real-time charts
│   │   │   └── HealthMonitor.jsx   # System health display
│   │   ├── hooks/                   # Custom React hooks
│   │   ├── utils/                   # Utility functions
│   │   └── App.jsx                  # Root component
│   ├── package.json                 # Node dependencies
│   └── vite.config.js              # Vite configuration
│
├── research/                         # 🧪 Research Lab & Documentation
│   ├── docs/                        # Technical specifications
│   │   ├── architecture.md         # System architecture
│   │   ├── ai_integration.md       # AI/ML design docs
│   │   └── security_model.md       # Security model
│   ├── reports/                     # Lab reports and findings
│   │   ├── vulnerability_analysis.md
│   │   └── performance_benchmarks.md
│   └── notebooks/                   # Jupyter notebooks for experiments
│       └── anomaly_detection_experiments.ipynb
│
├── src/                             # Core source code
│   ├── security_engine/             # Python-based security tools
│   │   ├── __init__.py
│   │   ├── scanner.py              # Network scanning
│   │   ├── payload_generator.py   # Smart payload creation
│   │   ├── proxy_handler.py       # Traffic interception
│   │   └── vulnerability_db.py    # CVE database interface
│   │
│   ├── ai_agent/                    # LLM integration logic
│   │   ├── __init__.py
│   │   ├── threat_analyzer.py     # Attack surface analysis
│   │   ├── anomaly_detector.py    # AI-powered anomaly detection
│   │   ├── reasoning_engine.py    # Decision-making logic
│   │   └── memory_store.py        # Adaptive memory management
│   │
│   ├── api/                         # FastAPI server
│   │   ├── __init__.py
│   │   ├── main.py                 # API entry point
│   │   ├── routes/                 # API endpoints
│   │   │   ├── telemetry.py       # Telemetry ingestion
│   │   │   ├── phase.py           # Mission phase management
│   │   │   └── history.py         # Historical data queries
│   │   ├── models.py               # Pydantic data models
│   │   └── dependencies.py         # Dependency injection
│   │
│   ├── core/                        # Core system components
│   │   ├── __init__.py
│   │   ├── error_handler.py       # Centralized error handling
│   │   ├── health_monitor.py      # System health tracking
│   │   ├── policy_engine.py       # Mission phase policies
│   │   └── config.py               # Configuration management
│   │
│   └── utils/                       # Shared utilities
│       ├── __init__.py
│       ├── logger.py               # Logging configuration
│       └── validators.py           # Input validation
│
├── tests/                           # Automated test suite
│   ├── unit/                        # Unit tests
│   │   ├── test_scanner.py
│   │   ├── test_anomaly_detector.py
│   │   └── test_policy_engine.py
│   ├── integration/                 # Integration tests
│   │   ├── test_api_endpoints.py
│   │   └── test_end_to_end.py
│   └── fixtures/                    # Test data and mocks
│       └── sample_telemetry.json
│
├── examples/                        # Usage examples
│   ├── api_usage_examples.py       # API integration examples
│   ├── security_scan_example.py    # Security engine usage
│   └── ai_analysis_example.py      # AI agent usage
│
├── docs/                            # Documentation
│   ├── GETTING_STARTED.md          # Quick start guide
│   ├── TECHNICAL.md                # Technical documentation
│   ├── TECHNICAL_REPORT.md         # Detailed technical report
│   ├── ERROR_HANDLING_GUIDE.md     # Error handling best practices
│   ├── API_REFERENCE.md            # API documentation
│   └── ARCHITECTURE.md             # Architecture deep-dive
│
├── config/                          # Configuration files
│   ├── mission_phases.yaml         # Phase definitions
│   ├── security_policies.yaml      # Security policies
│   └── model_config.yaml           # AI model configuration
│
├── scripts/                         # Utility scripts
│   ├── setup_dev_env.sh           # Development environment setup
│   ├── run_tests.sh               # Test runner
│   └── deploy.sh                  # Deployment script
│
├── .env.example                     # Environment variables template
├── .gitignore                       # Git ignore rules
├── CHANGES.md                       # Changelog
├── CONTRIBUTING.md                  # Contribution guidelines
├── LICENSE                          # MIT License
├── README.md                        # This file
├── requirements.txt                 # Python dependencies
├── cli.py                          # Command-line interface
└── run_api.py                      # API server entry point

🚀 Getting Started

Prerequisites

Before installing AstraGuard AI, ensure you have the following:

Software	Minimum Version	Recommended Version	Purpose
Python	3.9	3.11+	Core runtime
Node.js	16.0	20.0+	Frontend & tooling
Git	2.30	Latest	Version control
Docker	20.0 (optional)	Latest	Containerization

System Requirements

OS: Linux, macOS, or Windows (WSL2 recommended)
RAM: 4GB minimum, 8GB recommended
Storage: 2GB free space
Network: Internet connection for initial setup

Installation Steps

Step 1: Clone the Repository

# Clone via HTTPS
git clone https://github.com/sr-857/AstraGuard-AI.git

# Or clone via SSH (if you have SSH keys configured)
git clone git@github.com:sr-857/AstraGuard-AI.git

# Navigate to project directory
cd AstraGuard-AI

# Verify clone was successful
ls -la

Step 2: Set Up Python Environment

Option A: Using venv (Recommended)

# Check Python version (must be 3.9+)
python --version

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Verify activation (you should see (venv) in your prompt)
which python  # Should point to venv/bin/python or venv\Scripts\python.exe

# Upgrade pip to latest version
pip install --upgrade pip

# Install Python dependencies
pip install -r requirements.txt

# Verify installation
python -c "import fastapi, pydantic, scapy; print('✅ All core dependencies installed')"

Option B: Using conda

# Create conda environment
conda create -n astraguard python=3.11 -y

# Activate environment
conda activate astraguard

# Install dependencies
pip install -r requirements.txt

# Verify environment
conda info --envs  # Should show astraguard as active

Step 3: Install Node.js Dependencies (for Dashboard)

# Check Node.js version (must be 16+)
node --version
npm --version

# Navigate to dashboard directory
cd dashboard

# Install Node.js dependencies
npm install

# Verify installation
npm list --depth=0

# Return to project root
cd ..

Step 4: Configure Environment Variables

# Copy example environment file
cp .env.example .env

# Edit .env with your preferred editor
# On Linux/macOS:
nano .env
# On Windows:
notepad .env
# Or use VS Code:
code .env

Required Environment Variables:

# .env file
# ==========================================
# API Configuration
# ==========================================
API_HOST=0.0.0.0
API_PORT=8000
API_DEBUG=True
API_WORKERS=1

# ==========================================
# Database Configuration
# ==========================================
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=astraguard
MONGODB_TIMEOUT=5000

# ==========================================
# AI Model Configuration
# ==========================================
OLLAMA_MODEL=llama3
OLLAMA_HOST=http://localhost:11434
OLLAMA_TIMEOUT=30

# ==========================================
# Mission Configuration
# ==========================================
DEFAULT_MISSION_PHASE=NOMINAL_OPS
MISSION_CONFIG_PATH=config/mission_policies.yaml

# ==========================================
# Logging Configuration
# ==========================================
LOG_LEVEL=INFO
LOG_FILE=logs/astraguard.log
LOG_MAX_SIZE=10MB
LOG_BACKUP_COUNT=5

# ==========================================
# Security Configuration
# ==========================================
SECRET_KEY=your-secret-key-here-change-in-production
JWT_SECRET=your-jwt-secret-here
API_KEY=your-api-key-here

# ==========================================
# Monitoring Configuration
# ==========================================
PROMETHEUS_ENABLED=True
PROMETHEUS_PORT=9090
GRAFANA_ENABLED=True

Step 5: Install and Configure Ollama (for Local AI)

Linux/macOS:

# Download and install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Verify installation
ollama --version

# Start Ollama service (runs in background)
ollama serve &

Windows:

# Download from https://ollama.ai/download
# Install the .exe file
# Start Ollama from Start Menu or command line
ollama serve

Pull Required AI Models:

# Pull Llama 3 model (recommended for best performance)
ollama pull llama3

# Alternative: Pull Mistral model (lighter weight)
ollama pull mistral

# Verify models are available
ollama list

# Expected output:
# NAME                    ID              SIZE    MODIFIED
# llama3:latest           365c0bd3c000    4.7 GB  2 minutes ago
# mistral:latest          61e88e884507    4.1 GB  1 minute ago

Step 6: Set Up Database (MongoDB)

Option A: Using Docker (Recommended)

# Install Docker if not already installed
# Linux/macOS: https://docs.docker.com/get-docker/
# Windows: https://docs.docker.com/docker-for-windows/install/

# Start MongoDB container
docker run -d \
  --name astraguard-mongodb \
  -p 27017:27017 \
  -v mongodb_data:/data/db \
  --restart unless-stopped \
  mongo:latest

# Verify MongoDB is running
docker ps | grep mongodb

# Test connection
docker exec -it astraguard-mongodb mongosh --eval "db.runCommand('ping')"

Option B: Local MongoDB Installation

# Ubuntu/Debian:
sudo apt update
sudo apt install mongodb

# macOS:
brew install mongodb-community
brew services start mongodb-community

# Windows: Download from mongodb.com

# Verify installation
mongod --version

Step 7: Verify Complete Installation

# Run comprehensive health check
python cli.py status

# Expected output should show all components as HEALTHY:
# ✅ Python environment: OK (3.11.0)
# ✅ Dependencies installed: OK
# ✅ Ollama running: OK (llama3 loaded)
# ✅ Database connection: OK
# ✅ Configuration valid: OK
# ✅ All systems operational

# If any component shows FAILED, check the troubleshooting section below

Step 8: Initialize the System (Optional)

# Generate sample telemetry data for testing
python cli.py telemetry --duration 300 --output sample_data.json

# Load mission phase policies
python cli.py config --validate-policies

# Run initial system tests
python cli.py test --suite smoke

Step 9: Build the Application (Optional)

AstraGuard AI provides cross-platform build scripts for automated setup:

Option A: Python Build Script (Recommended - Cross-platform)

# Works on Windows, Linux, and macOS
python build.py

Option B: Bash Script (Linux/macOS)

# Make executable and run
chmod +x build.sh
./build.sh

Option C: Windows Batch Script

# Run on Windows Command Prompt
build.bat

What the build script does:

✅ Checks for required tools (Python, npm)
✅ Installs Python dependencies from requirements.txt
✅ Builds the Next.js frontend in frontend/as_lp/
✅ Validates all installations
✅ Provides clear error messages and next steps

Manual Build (if scripts fail):

# Install Python dependencies
pip install -r requirements.txt

# Build frontend
cd frontend/as_lp
npm install
npm run build
cd ../..

Available Commands

AstraGuard AI provides a unified CLI for all operations:

Basic Commands

# Show help and available commands
python cli.py --help

# Check system status
python cli.py status

# View current configuration
python cli.py config --show

Running the Dashboard

# Start Streamlit dashboard
python cli.py dashboard

# Start on custom port
python cli.py dashboard --port 8502

# Start with specific configuration
python cli.py dashboard --config config/custom.yaml

Access dashboard at: http://localhost:8501

Running the API Server

# Start FastAPI server
python cli.py api

# Start with auto-reload (development mode)
python cli.py api --reload

# Start on custom host/port
python cli.py api --host 0.0.0.0 --port 9000

# Start with specific workers
python cli.py api --workers 4

Access API docs at: http://localhost:8000/docs

Telemetry Operations

# Generate sample telemetry stream
python cli.py telemetry

# Generate with custom parameters
python cli.py telemetry --duration 3600 --interval 1

# Generate and save to file
python cli.py telemetry --output telemetry_data.json

# Import telemetry from file
python cli.py telemetry --import telemetry_data.json

Fault Classification

# Run fault classifier on live data
python cli.py classify

# Classify historical data
python cli.py classify --input data/historical.json

# Run in analysis mode (no actions)
python cli.py classify --analyze-only

Log Management

# View recent logs
python cli.py logs

# Export logs to file
python cli.py logs --export output.json

# Export with filters
python cli.py logs --export output.json --level ERROR --since "2026-01-01"

# Clear old logs
python cli.py logs --clear --before "2025-12-01"

Testing

# Run all tests
python cli.py test

# Run specific test suite
python cli.py test --suite unit
python cli.py test --suite integration

# Run with coverage report
python cli.py test --coverage

# Run specific test file
python cli.py test --file tests/unit/test_scanner.py

Development Tools

# Format code with Black
python cli.py format

# Run linter
python cli.py lint

# Type checking with mypy
python cli.py typecheck

# Security scanning (Bandit + Safety)
python cli.py security

# Run all checks
python cli.py check  # format + lint + typecheck + tests + security

Security Scanning

AstraGuard AI includes automated security scanning to detect vulnerabilities:

# Install security tools
pip install -r config/requirements-dev.txt

# Run Bandit (static security analysis)
bandit -r core anomaly state_machine memory_engine

# Run Safety (dependency vulnerability scanning)
safety check --file=config/requirements.txt
safety check --file=config/requirements-dev.txt

# Run all security checks (via test script)
./run_tests.sh --quality

Docker Setup (Alternative)

For a containerized setup:

# Build Docker image
docker build -t astraguard-ai .

# Run dashboard container
docker run -p 8501:8501 astraguard-ai dashboard

# Run API container
docker run -p 8000:8000 astraguard-ai api

# Run with docker-compose (all services)
docker-compose up -d

Next Steps After Installation

📚 Read the Documentation
🎓 Complete the Tutorial
- Follow the First Steps Tutorial
- Try the API Examples
- Explore the Security Scanner
🤝 Join the Community
- Join our WhatsApp Group
- Check out Good First Issues
- Read Contributing Guidelines

🌐 API Documentation

Quick Start Example

import requests
import json

# Base URL
BASE_URL = "http://localhost:8000/api/v1"

# 1. Check system health
response = requests.get(f"{BASE_URL}/status")
print(json.dumps(response.json(), indent=2))

# 2. Submit telemetry for analysis
telemetry = {
    "timestamp": "2026-01-04T12:00:00Z",
    "voltage": 7.2,
    "temperature": 35.5,
    "gyro": 0.08,
    "mission_phase": "NOMINAL_OPS"
}

response = requests.post(f"{BASE_URL}/telemetry", json=telemetry)
result = response.json()

if result['is_anomaly']:
    print(f"⚠️  ANOMALY DETECTED!")
    print(f"   Type: {result['anomaly_type']}")
    print(f"   Confidence: {result['confidence']:.2%}")
    print(f"   Recommended Action: {result['recommended_action']}")
    print(f"   Reasoning: {result['reasoning']}")
else:
    print("✅ All systems nominal")

# 3. Query historical anomalies
response = requests.get(f"{BASE_URL}/history/anomalies", params={
    "start_time": "2026-01-03T00:00:00Z",
    "end_time": "2026-01-04T23:59:59Z",
    "min_confidence": 0.8
})

anomalies = response.json()
print(f"\nFound {len(anomalies['items'])} high-confidence anomalies")

Endpoints Reference

1. Telemetry Ingestion

Submit Single Telemetry Point

POST /api/v1/telemetry
Content-Type: application/json

{
  "timestamp": "2026-01-04T12:00:00Z",
  "voltage": 7.2,
  "temperature": 35.5,
  "gyro": 0.08,
  "mission_phase": "NOMINAL_OPS"
}

Response:

{
  "is_anomaly": true,
  "anomaly_type": "VOLTAGE_DROP",
  "confidence": 0.94,
  "recommended_action": "POWER_OPTIMIZATION",
  "reasoning": "Voltage dropped below 7.3V threshold during NOMINAL_OPS phase",
  "telemetry_id": "tlm_abc123",
  "processed_at": "2026-01-04T12:00:01Z"
}

Submit Batch Telemetry

POST /api/v1/telemetry/batch
Content-Type: application/json

{
  "items": [
    {"timestamp": "2026-01-04T12:00:00Z", "voltage": 7.4, ...},
    {"timestamp": "2026-01-04T12:01:00Z", "voltage": 7.3, ...},
    ...
  ]
}

Response:

{
  "processed_count": 100,
  "total_count": 100,
  "anomaly_count": 3,
  "processing_time_ms": 247,
  "anomalies": [
    {"index": 15, "type": "VOLTAGE_DROP", "confidence": 0.89},
    {"index": 42, "type": "TEMPERATURE_SPIKE", "confidence": 0.92},
    {"index": 78, "type": "GYRO_DRIFT", "confidence": 0.87}
  ]
}

2. System Health

Get System Status

GET /api/v1/status

Response:

{
  "overall_status": "HEALTHY",
  "timestamp": "2026-01-04T12:00:00Z",
  "uptime_seconds": 86400,
  "components": {
    "ai_model": {"status": "HEALTHY", "details": "Llama3 loaded"},
    "memory_store": {"status": "HEALTHY", "details": "1247 patterns stored"},
    "policy_engine": {"status": "HEALTHY", "details": "All phases configured"},
    "action_orchestrator": {"status": "DEGRADED", "details": "Retry mode active"},
    "database": {"status": "HEALTHY", "details": "Connected to MongoDB"},
    "api_server": {"status": "HEALTHY", "details": "All endpoints operational"}
  },
  "metrics": {
    "total_telemetry_processed": 15234,
    "anomalies_detected": 42,
    "actions_taken": 18,
    "avg_response_time_ms": 156
  }
}

3. Mission Phase Management

Get Current Mission Phase

GET /api/v1/phase

Response:

{
  "phase": "NOMINAL_OPS",
  "set_at": "2026-01-04T08:00:00Z",
  "duration_seconds": 14400,
  "constraints": {
    "max_actions": null,
    "allowed_actions": ["LOG", "ALERT", "RECOVER", "OPTIMIZE"],
    "power_change_limit": "50%",
    "attitude_change_allowed": true
  },
  "next_review": "2026-01-04T16:00:00Z"
}

Update Mission Phase

POST /api/v1/phase
Content-Type: application/json

{
  "phase": "PAYLOAD_OPS",
  "reason": "Starting science data collection"
}

Response:

{
  "previous_phase": "NOMINAL_OPS",
  "new_phase": "PAYLOAD_OPS",
  "changed_at": "2026-01-04T12:00:00Z",
  "reason": "Starting science data collection",
  "constraints_updated": true
}

4. Memory Store

Get Memory Statistics

GET /api/v1/memory/stats

Response:

{
  "total_patterns": 1247,
  "pattern_categories": {
    "VOLTAGE_DROP": 342,
    "TEMPERATURE_SPIKE": 187,
    "GYRO_DRIFT": 156,
    "NORMAL": 562
  },
  "oldest_pattern": "2026-01-01T00:00:00Z",
  "newest_pattern": "2026-01-04T12:00:00Z",
  "storage_size_mb": 12.4,
  "avg_pattern_age_hours": 48.3
}

5. Historical Data

Query Anomaly History

GET /api/v1/history/anomalies?start_time=2026-01-03T00:00:00Z&end_time=2026-01-04T23:59:59Z&anomaly_type=VOLTAGE_DROP&min_confidence=0.8

Response:

{
  "items": [
    {
      "id": "anom_123",
      "timestamp": "2026-01-04T08:15:23Z",
      "type": "VOLTAGE_DROP",
      "confidence": 0.94,
      "telemetry": {"voltage": 6.8, "temperature": 32.1, "gyro": 0.03},
      "mission_phase": "NOMINAL_OPS",
      "action_taken": "POWER_OPTIMIZATION",
      "outcome": "SUCCESS",
      "recovery_time_seconds": 45
    },
    ...
  ],
  "total_count": 15,
  "page": 1,
  "page_size": 50
}

Export Historical Data

GET /api/v1/history/export?format=json&start_time=2026-01-01T00:00:00Z&end_time=2026-01-04T23:59:59Z

Returns downloadable file with all telemetry and anomaly data.

Detailed Usage Examples

Example 1: Real-Time Monitoring

import requests
import time

BASE_URL = "http://localhost:8000/api/v1"

def monitor_telemetry(duration_seconds=3600, interval=1):
    """Monitor telemetry for specified duration"""
    start_time = time.time()
    anomaly_count = 0
    
    while time.time() - start_time < duration_seconds:
        # Simulate getting telemetry (replace with actual sensor readings)
        telemetry = {
            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
            "voltage": 7.2 + (time.time() % 10) / 100,  # Simulated
            "temperature": 32.0 + (time.time() % 20) / 10,
            "gyro": 0.02 + (time.time() % 5) / 1000
        }
        
        # Submit to API
        response = requests.post(f"{BASE_URL}/telemetry", json=telemetry)
        result = response.json()
        
        if result['is_anomaly']:
            anomaly_count += 1
            print(f"⚠️  Anomaly #{anomaly_count}: {result['anomaly_type']}")
            print(f"   Action: {result['recommended_action']}")
        else:
            print("✅ Normal")
        
        time.sleep(interval)
    
    print(f"\nMonitoring complete. Detected {anomaly_count} anomalies.")

# Run monitoring
monitor_telemetry(duration_seconds=300)  # 5 minutes

Example 2: Batch Historical Analysis

import requests
import json

BASE_URL = "http://localhost:8000/api/v1"

def analyze_historical_data(filepath):
    """Analyze historical telemetry from file"""
    
    # Load historical data
    with open(filepath, 'r') as f:
        data = json.load(f)
    
    # Submit in batches of 100
    batch_size = 100
    total_anomalies = 0
    
    for i in range(0, len(data), batch_size):
        batch = data[i:i+batch_size]
        
        response = requests.post(f"{BASE_URL}/telemetry/batch", json={
            "items": batch
        })
        
        result = response.json()
        total_anomalies += result['anomaly_count']
        
        print(f"Batch {i//batch_size + 1}: {result['anomaly_count']} anomalies")
    
    print(f"\nTotal anomalies in dataset: {total_anomalies}")

# Run analysis
analyze_historical_data("data/historical_telemetry.json")

Example 3: Mission Phase Transition

import requests

BASE_URL = "http://localhost:8000/api/v1"

def transition_mission_phase(new_phase, reason):
    """Safely transition to new mission phase"""
    
    # Get current phase
    current = requests.get(f"{BASE_URL}/phase").json()
    print(f"Current phase: {current['phase']}")
    
    # Update to new phase
    response = requests.post(f"{BASE_URL}/phase", json={
        "phase": new_phase,
        "reason": reason
    })
    
    if response.status_code == 200:
        result = response.json()
        print(f"✅ Transitioned to {result['new_phase']}")
        print(f"   Reason: {result['reason']}")
        print(f"   New constraints: {result['constraints_updated']}")
    else:
        print(f"❌ Transition failed: {response.json()['detail']}")

# Example transitions
transition_mission_phase("PAYLOAD_OPS", "Starting science data collection")
transition_mission_phase("SAFE_MODE", "Critical battery low warning")

Example 4: Anomaly Pattern Analysis

import requests
from collections import Counter
import matplotlib.pyplot as plt

BASE_URL = "http://localhost:8000/api/v1"

def analyze_anomaly_patterns(days=7):
    """Analyze anomaly patterns over time"""
    
    # Query last N days of anomalies
    end_time = "2026-01-04T23:59:59Z"
    start_time = f"2026-01-{4-days:02d}T00:00:00Z"
    
    response = requests.get(f"{BASE_URL}/history/anomalies", params={
        "start_time": start_time,
        "end_time": end_time
    })
    
    anomalies = response.json()['items']
    
    # Count by type
    type_counts = Counter(a['type'] for a in anomalies)
    
    # Count by mission phase
    phase_counts = Counter(a['mission_phase'] for a in anomalies)
    
    print(f"Anomaly Analysis ({days} days)")
    print(f"Total anomalies: {len(anomalies)}")
    print("\nBy Type:")
    for type_, count in type_counts.most_common():
        print(f"  {type_}: {count}")
    
    print("\nBy Mission Phase:")
    for phase, count in phase_counts.most_common():
        print(f"  {phase}: {count}")
    
    # Visualization
    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
    
    ax1.bar(type_counts.keys(), type_counts.values())
    ax1.set_title("Anomalies by Type")
    ax1.set_xlabel("Type")
    ax1.set_ylabel("Count")
    ax1.tick_params(axis='x', rotation=45)
    
    ax2.pie(phase_counts.values(), labels=phase_counts.keys(), autopct='%1.1f%%')
    ax2.set_title("Anomalies by Mission Phase")
    
    plt.tight_layout()
    plt.savefig("anomaly_analysis.png")
    print("\nVisualization saved to anomaly_analysis.png")

# Run analysis
analyze_anomaly_patterns(days=7)

📖 More Examples: See examples/api_usage_examples.py for complete code

👥 Contributing

How to Contribute

We welcome contributions of all types! Here's how to get started:

1. 🔍 Find an Issue

Browse our issue tracker:

🟢 Good First Issue: Perfect for newcomers
🟡 Help Wanted: Need community assistance
🔴 High Priority: Urgent items for the project

2. 🙋 Claim an Issue

Comment on the issue with:

I'd like to work on this! 
Expected completion: [date]

Maintainers will assign it to you within 24 hours.

3. 🍴 Fork & Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/AstraGuard-AI.git
cd AstraGuard-AI

# Add upstream remote
git remote add upstream https://github.com/sr-857/AstraGuard-AI.git

4. 🌿 Create a Branch

# Create feature branch
git checkout -b feature/your-feature-name

# Or bugfix branch
git checkout -b bugfix/issue-number-description

Branch naming convention:

feature/add-health-monitoring
bugfix/123-fix-api-timeout
docs/update-readme
test/add-scanner-tests

5. 💻 Make Changes

Write clean, well-documented code
Follow our Code Style Guide
Add tests for new features
Update documentation if needed

6. ✅ Test Your Changes

# Run all tests
python cli.py test

# Run specific tests
python cli.py test --file tests/unit/test_your_feature.py

# Check code formatting
python cli.py format --check

# Run linter
python cli.py lint

7. 📝 Commit Your Changes

# Stage your changes
git add .

# Commit with descriptive message
git commit -m "feat: add health monitoring endpoint

- Implement GET /api/v1/status endpoint
- Add component health tracking
- Include system metrics in response
- Add comprehensive tests

Closes #123"

Commit message format:

<type>: <short description>

<detailed description>

<footer>

Types: feat, fix, docs, test, refactor, style, chore

8. 🚀 Push & Create PR

# Push to your fork
git push origin feature/your-feature-name

Then create a Pull Request on GitHub with:

PR Title: [Type] Brief description
Example: [Feature] Add health monitoring endpoint

PR Description Template:

## Description
Brief description of changes

## Related Issue
Closes #123

## Type of Change
- [ ] Bug fix
- [x] New feature
- [ ] Documentation update
- [ ] Performance improvement

## Testing
- [x] Unit tests added/updated
- [x] Integration tests added/updated
- [x] Manual testing completed

## Checklist
- [x] Code follows style guide
- [x] Documentation updated
- [x] Tests pass locally
- [x] No breaking changes

9. 👀 Code Review

Respond to reviewer feedback within 48 hours
Make requested changes in new commits
Don't force-push after review starts
Mark conversations as resolved when addressed

10. 🎉 Merge

Once approved, a maintainer will merge your PR. Congratulations! 🎊

Contributor Roles Needed

We're looking for contributors in these areas:

🎨 Frontend Developers (3 positions)

Required Skills:

React 18+ and hooks
TailwindCSS or similar CSS framework
Data visualization (Recharts/D3.js)

Projects:

Real-time telemetry dashboard
Anomaly visualization components
Mission phase control panel
Health monitoring interface

Good First Issues:

#45 - Add dark mode to dashboard
#52 - Improve chart responsiveness
#61 - Create mission phase selector component

⚙️ Backend Developers (3 positions)

Required Skills:

Python 3.9+ (FastAPI experience preferred)
RESTful API design
Database design (MongoDB)
Async programming

Projects:

API endpoint implementation
Database optimization
Authentication system
WebSocket support for real-time updates

Good First Issues:

#38 - Add pagination to anomaly history endpoint
#47 - Implement API rate limiting
#56 - Add authentication middleware

🛡️ Security Researchers (2-4 positions)

Required Skills:

Python for security tooling
Network protocols (TCP/IP, HTTP)
Basic penetration testing knowledge
Familiarity with Scapy/Nmap

Projects:

Payload generator improvements
Vulnerability scanner enhancements
Security test suite
Research lab experiments

Good First Issues:

#42 - Add SQL injection payload templates
#49 - Implement XSS detection
#58 - Create vulnerability database connector

What We Look For

✅ Quality over quantity: One well-tested feature > ten half-finished PRs
✅ Clear communication: Ask questions, share progress, flag blockers
✅ Documentation: Code comments, README updates, API docs
✅ Testing: Unit tests, integration tests, manual verification
✅ Best practices: Follow conventions, write maintainable code

What We Don't Want

❌ Spam PRs (minor formatting changes, typo fixes in non-critical areas)
❌ Uncommented complex code
❌ Breaking changes without discussion
❌ Copy-pasted code without attribution
❌ PRs without associated issues (except docs/typos)

📖 Full Guidelines: CONTRIBUTING.md

🛠️ Troubleshooting

Quick Diagnosis

Before diving into specific issues, run this diagnostic script:

# Create diagnostic script
cat > diagnose.py << 'EOF'
#!/usr/bin/env python3
import sys
import subprocess
import requests
import json

def run_command(cmd, description):
    """Run command and return success status"""
    try:
        result = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=10)
        success = result.returncode == 0
        print(f"{'✅' if success else '❌'} {description}: {'OK' if success else 'FAILED'}")
        if not success:
            print(f"   Error: {result.stderr.strip()}")
        return success
    except Exception as e:
        print(f"❌ {description}: FAILED")
        print(f"   Error: {e}")
        return False

def check_service(url, name):
    """Check if service is responding"""
    try:
        response = requests.get(url, timeout=5)
        success = response.status_code == 200
        print(f"{'✅' if success else '❌'} {name}: {'OK' if success else 'FAILED'}")
        if not success:
            print(f"   Status: {response.status_code}")
        return success
    except Exception as e:
        print(f"❌ {name}: FAILED")
        print(f"   Error: {e}")
        return False

print("🔍 AstraGuard AI Diagnostic Report")
print("=" * 40)

# System checks
print("\n📋 System Requirements:")
run_command("python --version", "Python version (3.9+)")
run_command("node --version", "Node.js version (16+)")
run_command("npm --version", "NPM version")
run_command("docker --version", "Docker version")

# Environment checks
print("\n🐍 Python Environment:")
run_command("python -c 'import fastapi, pydantic, scapy'", "Core dependencies")
run_command("python -c 'import ollama'", "Ollama client")

# Service checks
print("\n🌐 Services:")
check_service("http://localhost:11434/api/version", "Ollama API")
check_service("http://localhost:27017", "MongoDB")
check_service("http://localhost:8000/api/v1/status", "AstraGuard API")
check_service("http://localhost:8501", "Dashboard")

# Configuration checks
print("\n⚙️ Configuration:")
run_command("test -f .env", ".env file exists")
run_command("test -f config/mission_policies.yaml", "Mission policies")
run_command("test -d logs", "Logs directory")

print("\n📝 Next Steps:")
print("1. Fix any FAILED items above")
print("2. Check logs/astraguard.log for errors")
print("3. Run 'python cli.py status' for detailed status")
print("4. See troubleshooting section below for specific issues")
EOF

# Run diagnostic
python diagnose.py

Common Installation Issues

Issue: Installation fails with "Python 3.9+ required"

Solution:

# Check current version
python --version

# If too old, install Python 3.11
# On Ubuntu/Debian:
sudo apt update
sudo apt install python3.11 python3.11-venv

# On macOS:
brew install python@3.11

# On Windows:
# Download from python.org

Verify:

python3.11 --version
python3.11 -m venv venv

📦 Dependency Installation Fails

Issue: pip install -r requirements.txt fails with compilation errors

Solution:

# Upgrade pip and setuptools
pip install --upgrade pip setuptools wheel

# Install system dependencies first
# On Ubuntu/Debian:
sudo apt install python3-dev build-essential

# On macOS:
xcode-select --install

# Retry installation
pip install -r requirements.txt

Alternative: Install dependencies individually to identify problem package

pip install fastapi
pip install pydantic
pip install scapy
# ... etc

🔥 Streamlit Command Not Found

Issue: streamlit: command not found

Solution:

# Ensure virtual environment is activated
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Install Streamlit explicitly
pip install streamlit

# Verify installation
streamlit --version

# If still not found, use module syntax
python -m streamlit run dashboard/app.py

🌐 Port Already in Use

Issue: "Address already in use" when starting dashboard/API

Solution:

# Find process using port 8501 (Streamlit)
lsof -i :8501          # Linux/macOS
netstat -ano | findstr :8501  # Windows

# Kill the process
kill -9 <PID>          # Linux/macOS
taskkill /PID <PID> /F # Windows

# Or run on different port
streamlit run dashboard/app.py --server.port 8502
python cli.py api --port 9000

🤖 Ollama Connection Fails

Issue: "Cannot connect to Ollama server"

Solution:

# Check if Ollama is running
curl http://localhost:11434/api/version

# If not running, start it
# Linux/macOS:
ollama serve

# Check if model is installed
ollama list

# Pull model if missing
ollama pull llama3

# Update .env with correct host
OLLAMA_HOST=http://localhost:11434

🗄️ MongoDB Connection Errors

Issue: "Cannot connect to MongoDB"

Solution:

# Check if MongoDB is running
# Linux:
sudo systemctl status mongodb

# macOS:
brew services list

# If not running, start it
# Linux:
sudo systemctl start mongodb

# macOS:
brew services start mongodb-community

# Or use Docker:
docker run -d -p 27017:27017 --name mongodb mongo:latest

# Verify connection
mongosh  # Should connect successfully

📊 Dashboard Shows No Data

Issue: Dashboard loads but displays no telemetry

Solution:

# Generate sample telemetry
python cli.py telemetry --duration 60

# Check if API is running
curl http://localhost:8000/api/v1/status

# Verify configuration
python cli.py config --show | grep API_

# Check logs for errors
python cli.py logs --level ERROR

# Restart dashboard with debug mode
python cli.py dashboard --debug

⚡ API Tests Failing

Issue: Tests fail with connection or timeout errors

Solution:

# Run tests in verbose mode
pytest -v tests/

# Run specific failing test
pytest tests/integration/test_api.py::test_telemetry_endpoint -v

# Check test environment
python -m pytest --version

# Reset test database
python cli.py test --reset-db

# Ensure no conflicting processes
pkill -f "python.*api"
python cli.py api &
sleep 2
pytest tests/

🔐 Permission Denied Errors

Issue: "Permission denied" when accessing files/directories

Solution:

# Check file permissions
ls -la

# Fix permissions for project directory
chmod -R u+rw .

# For log directory
sudo chown -R $USER:$USER logs/

# For pip installation issues
pip install --user -r requirements.txt

🧠 AI Model Performance Issues

Issue: AI analysis is very slow or times out

Solution:

# Use faster model
ollama pull llama3:70b-instruct-q4_K_M  # Quantized version

# Update config
nano config/model_config.yaml
# Set: model_name: "llama3:70b-instruct-q4_K_M"

# Allocate more resources
# In .env:
OLLAMA_NUM_PARALLEL=4
OLLAMA_MAX_LOADED_MODELS=2

# Monitor resource usage
ollama ps

# Reduce context window
# In model_config.yaml:
context_window: 2048  # Instead of 4096

📦 Docker Build Fails

Issue: Docker image build fails

Solution:

# Clean Docker cache
docker system prune -a

# Build with verbose output
docker build -t astraguard-ai . --progress=plain

# Build with no cache
docker build -t astraguard-ai . --no-cache

# Check Docker disk space
docker system df

# Increase Docker memory
# Docker Desktop -> Settings -> Resources -> Memory: 4GB+

Still Having Issues?

If you're still stuck after trying the solutions above:

📖 Check Documentation: docs/TROUBLESHOOTING.md
🔍 Search Issues: GitHub Issues
💬 Ask Community: WhatsApp Group
🐛 Report Bug: Bug Report Template

When reporting issues, include:

OS and version (systeminfo on Windows, uname -a on Linux/macOS)
Python version (python --version)
Full error message and stack trace
Output of python cli.py status
Recent logs (python cli.py logs --tail 50)
Steps to reproduce the issue
Expected vs actual behavior

Debug Information Script:

# Run this to gather debug info
cat > debug_info.py << 'EOF'
#!/usr/bin/env python3
import sys
import platform
import subprocess

print("🔍 AstraGuard AI Debug Information")
print("=" * 40)

print(f"OS: {platform.system()} {platform.release()}")
print(f"Python: {sys.version}")
print(f"Executable: {sys.executable}")

print("\n📦 Installed Packages:")
try:
    result = subprocess.run([sys.executable, "-m", "pip", "list"], 
                          capture_output=True, text=True)
    for line in result.stdout.split('\n')[:20]:  # First 20 packages
        if line.strip():
            print(f"  {line}")
    if len(result.stdout.split('\n')) > 20:
        print("  ... (truncated)")
except:
    print("  Could not retrieve package list")

print("\n🌐 Environment Variables:")
import os
for key in ['OLLAMA_HOST', 'MONGODB_URI', 'API_HOST', 'API_PORT']:
    value = os.getenv(key, 'Not set')
    print(f"  {key}: {value}")

print("\n🔧 System Status:")
try:
    import requests
    services = [
        ("Ollama", "http://localhost:11434/api/version"),
        ("MongoDB", "http://localhost:27017"),
        ("API", "http://localhost:8000/api/v1/status"),
        ("Dashboard", "http://localhost:8501")
    ]
    for name, url in services:
        try:
            resp = requests.get(url, timeout=3)
            print(f"  {name}: {resp.status_code}")
        except:
            print(f"  {name}: Connection failed")
except:
    print("  Could not check services")

print("\n📁 File Structure:")
import os
files_to_check = ['.env', 'requirements.txt', 'config/mission_policies.yaml', 'logs/']
for file in files_to_check:
    exists = os.path.exists(file)
    print(f"  {file}: {'Exists' if exists else 'Missing'}")
EOF

python debug_info.py

Include this output when asking for help!

📚 Documentation

Core Documentation

Document	Description	Audience
Getting Started	Quick start guide for new users	Everyone
Technical Documentation	Detailed system architecture	Developers
Technical Report	Academic-style technical report	Researchers
API Reference	Complete API documentation	API Users
Contributing Guide	How to contribute to the project	Contributors

Advanced Guides

Document	Description	Audience
Architecture Deep-Dive	System design and patterns	Senior Developers
Error Handling Guide	Error handling best practices	All Developers
Mission-Phase Policies	Phase configuration guide	Operators
Security Model	Security architecture	Security Team
Performance Tuning	Optimization guide	DevOps

Research & Lab Reports

Document	Description	Audience
AI Integration	LLM integration strategy	ML Engineers
Vulnerability Analysis	Security findings	Security Researchers
Performance Benchmarks	System benchmarks	Performance Engineers

Developer Resources

📞 Community & Support

Join Our Community

WhatsApp Group (Primary)

Link: https://chat.whatsapp.com/HZXk0vo62945S33qTXheON

Purpose: Formal team collaboration and project discussion
Rules:

Project-related discussions only
No sensitive data or credentials
Be respectful and professional
Response time: < 6 hours

GitHub Discussions

Link: github.com/sr-857/AstraGuard-AI/discussions

Categories:

💡 Ideas & Feature Requests
❓ Q&A (Technical Questions)
🎓 Show & Tell (Your Implementations)
📢 Announcements

Discord (Coming Soon)

Server invite will be shared once we reach 10 contributors.

Get Help

Need	Where to Go	Response Time
Bug Report	GitHub Issues	< 24 hours
Feature Request	GitHub Issues	< 48 hours
Quick Question	WhatsApp Group	< 6 hours
Technical Discussion	GitHub Discussions	< 48 hours
Security Issue	Email (see SECURITY.md)	< 12 hours

Office Hours

When: Every Friday, 6-7 PM IST
Where: Discord (link in WhatsApp group)
Format: Open Q&A, pair programming, code reviews

Contributors

Thanks to all our amazing contributors! 🎉

See CONTRIBUTORS.md for complete list.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

What This Means

✅ You can:

Use the code commercially
Modify the code
Distribute the code
Use it privately
Sublicense

❌ You must:

Include the license and copyright notice
Not hold us liable

📖 Learn more: MIT License Explained

🌟 Star History

_{Part of Elite Coders Winter of Code '26}
_{Empowering the next generation of open-source contributors}
_{through real-world projects and mentorship.}

Made with ❤️ by the AstraGuard AI Team

Name		Name	Last commit message	Last commit date
Latest commit History 925 Commits
.github		.github
.next/dev		.next/dev
anomaly		anomaly
anomaly_agent		anomaly_agent
api		api
assets		assets
astraguard		astraguard
backend		backend
benchmarks		benchmarks
classifier		classifier
config		config
core		core
dashboard		dashboard
data		data
demo		demo
docker		docker
docs		docs
examples		examples
frontend		frontend
grafana		grafana
helm/astraguard		helm/astraguard
k8s/base		k8s/base
logs		logs
memory_engine		memory_engine
models		models
pages		pages
prometheus		prometheus
research		research
schemas		schemas
security		security
security_engine		security_engine
state_machine		state_machine
tests		tests
tools		tools
.coderabbit-disabled.md		.coderabbit-disabled.md
.gitignore		.gitignore
API_AUTHENTICATION_README.md		API_AUTHENTICATION_README.md
CHANGELOG.md		CHANGELOG.md
CHANGES.md		CHANGES.md
CHECKLIST_397.md		CHECKLIST_397.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COMPLETION_SUMMARY_397.md		COMPLETION_SUMMARY_397.md
COMPLETION_SUMMARY_410.md		COMPLETION_SUMMARY_410.md
COMPLETION_SUMMARY_411.md		COMPLETION_SUMMARY_411.md
COMPLETION_SUMMARY_412.md		COMPLETION_SUMMARY_412.md
COMPLETION_SUMMARY_413.md		COMPLETION_SUMMARY_413.md
COMPLETION_SUMMARY_414.md		COMPLETION_SUMMARY_414.md
COMPLETION_SUMMARY_415.md		COMPLETION_SUMMARY_415.md
COMPLETION_SUMMARY_492.md		COMPLETION_SUMMARY_492.md
COMPLETION_SUMMARY_493.md		COMPLETION_SUMMARY_493.md
COMPLETION_SUMMARY_495.md		COMPLETION_SUMMARY_495.md
COMPLETION_SUMMARY_496.md		COMPLETION_SUMMARY_496.md
CONTRIBUTING.md		CONTRIBUTING.md
DELIVERY_REPORT_414.md		DELIVERY_REPORT_414.md
DELIVERY_REPORT_415.md		DELIVERY_REPORT_415.md
DELIVERY_SUMMARY_413.md		DELIVERY_SUMMARY_413.md
DEVELOPER.md		DEVELOPER.md
ENV_CONFIG_README.md		ENV_CONFIG_README.md
FILE_MANIFEST_397.md		FILE_MANIFEST_397.md
FINAL_FIX_SUMMARY.md		FINAL_FIX_SUMMARY.md
FINAL_SUMMARY_397.md		FINAL_SUMMARY_397.md
FIXES_COMPLETED_SESSION.md		FIXES_COMPLETED_SESSION.md
IMPLEMENTATION_REPORT_397.md		IMPLEMENTATION_REPORT_397.md
IMPLEMENTATION_REPORT_409.md		IMPLEMENTATION_REPORT_409.md
IMPLEMENTATION_REPORT_412.md		IMPLEMENTATION_REPORT_412.md
IMPLEMENTATION_REPORT_413.md		IMPLEMENTATION_REPORT_413.md
IMPLEMENTATION_REPORT_415.md		IMPLEMENTATION_REPORT_415.md
INDEX_397.md		INDEX_397.md
INDEX_413.md		INDEX_413.md
ISSUE_397_IMPLEMENTATION.md		ISSUE_397_IMPLEMENTATION.md
ISSUE_410_IMPLEMENTATION.md		ISSUE_410_IMPLEMENTATION.md
ISSUE_411_IMPLEMENTATION.md		ISSUE_411_IMPLEMENTATION.md
ISSUE_414_IMPLEMENTATION.md		ISSUE_414_IMPLEMENTATION.md
ISSUE_485_COMPLETION.md		ISSUE_485_COMPLETION.md
LICENSE		LICENSE
PR_397_SUMMARY.md		PR_397_SUMMARY.md
PR_405_SUMMARY.md		PR_405_SUMMARY.md
PR_406_SUMMARY.md		PR_406_SUMMARY.md
PR_408_SUMMARY.md		PR_408_SUMMARY.md
PR_409_SUMMARY.md		PR_409_SUMMARY.md
README.md		README.md
RELEASE_NOTES_v3.0.md		RELEASE_NOTES_v3.0.md
SESSION_COMPLETION_API_TESTS_PASSING.md		SESSION_COMPLETION_API_TESTS_PASSING.md
STARTUP_GUIDE.md		STARTUP_GUIDE.md
TODO.md		TODO.md
TODO_auth_implementation.md		TODO_auth_implementation.md
TODO_memory_store_fix.md		TODO_memory_store_fix.md
TODO_secrets.md		TODO_secrets.md
TODO_secrets_implementation.md		TODO_secrets_implementation.md
VERIFICATION_397.md		VERIFICATION_397.md
VERIFICATION_409.md		VERIFICATION_409.md
api.py		api.py
app.py		app.py
build.bat		build.bat
build.py		build.py
build.sh		build.sh
build_log.txt		build_log.txt
cli.py		cli.py
corrupted_file.txt		corrupted_file.txt
deploy.sh		deploy.sh

License

sr-857/AstraGuard-AI

Folders and files

Latest commit

History

Repository files navigation

AstraGuard AI

AI-Powered Satellite Security & Anomaly Detection System

Bridging the gap between theoretical security concepts and real-world workflows

🌟 Hall of Fame

Want to see your avatar here? Make your first contribution today!

📋 Table of Contents

🚀 About the Project

What is AstraGuard AI?

Why AstraGuard AI?

Target Audience

🏗️ System Architecture

High-Level Overview

🏗️ System Architecture

📊 Architecture Overview

🔧 Core Components

🛰️ Telemetry Stream (Pathway)

📊 Embedding Encoder

🧠 Adaptive Memory Store

🤖 Anomaly Reasoning Agent

⚡ Response Orchestrator

🛰️ System Recovery

📊 Monitoring Dashboard

🔄 Data Flow Sequence

📋 Sequence Breakdown

🎯 Key Decision Points

⚡ Performance Metrics

🔄 Feedback Loop Illustration

⚙️ Technology Stack

📈 Performance Characteristics

🎯 Key Features

⚡ Real-time Processing

🧠 AI-Powered Intelligence

🔄 Self-Healing

📊 Full Observability

🎯 Adaptive Learning

🛡️ Production Ready

🚀 Deployment Architecture

📚 Related Documentation

🔗 Related Repositories

Dual-Engine Design

1. 🛡️ Core Security Engine (The Muscle)

2. 🧠 AI Intelligence Layer (The Brain)

Data Flow

✨ Key Features

Core Capabilities

🚀 Mission-Phase Aware Fault Response

Phase Definitions & Policies

Example: Voltage Anomaly Response by Phase

Configuration

🛡️ Centralized Error Handling & Graceful Degradation

Design Principles

Error Handling Architecture

Health Monitoring States

Example: Handling Model Failure

Dashboard Health View

🌐 REST API for External Integration

API Features

Endpoints Reference

Quick Start Example

Batch Processing Example

Mission Phase Management

Querying Historical Data

Health Monitoring

🧠 Operator Feedback Schema (#50)

📝 Action Logging with @log_feedback Decorator (#51)

🎯 Project Goals (ECWoC '26)

Primary Objectives

Success Metrics

Learning Outcomes for Contributors

🤝 Project Admin Commitment

Our Commitments

1. ❤️ Active Maintenance

2. ⚡ Timely Reviews

3. 📝 Clear Documentation

📝 Action Logging with `@log_feedback` Decorator (#51)