GaiaOS

An Agentic Planetary Risk Intelligence Platform.

Status

Phase 1, Phase 2, Phase 3, Phase 4, Phase 5, Phase 6, Phase 7, and the v0.7.x Explainability, Ecosystem & Governance Series — Complete

Milestone	Scope / Deliverable	Status
Phase 1	Foundation, FastAPI, PostgreSQL (PostGIS + pgvector), Docker, Gateway	Complete
Phase 2	Multi-Agent Reasoning Core, LangGraph, Literature RAG, Scorer	Complete
Phase 3 — Milestones 1–10	JWT/API Key Auth, Redis Rate Limiting, RQ Workers, SSE Stream, Eval Suite, Replan Loop, PostGIS, Ingestion, Metrics	Complete
Phase 4 — Milestones 1–10	CI Integrity, Auth Review, Monitoring/Alerting, Citation IDs, Geocoding, Disaster Recovery, Worker Scaling, Agent Contribution Framework, Admin UI, OpenAPI Publishing	Complete
v0.4.1–v0.4.4	Open Source Readiness Series (Governance, Security Policy, Issue/PR Templates, Contributor Onboarding)	Complete
v0.5.0	Phase 5 Milestones 1–2 (Evaluation & Repository Integrity)	Complete
v0.5.1	Phase 5 Milestones 3–5 (Uncertainty Quantification, Multi-Agent Collaboration & Cross-Domain Synthesis)	Complete
v0.5.2	Phase 5 Milestone 6 (Agent Plugin Architecture & Dynamic Extensions)	Complete
v0.5.3	Phase 5 Milestones 7–8 (Read Replica Scaling & SLO Burn-Rate Alerting)	Complete
v0.5.4	Phase 5 Capstone (Public Research API & Dataset Publishing)	Complete
v0.6.0	Phase 6 Milestone 1 (Resilience Layer: Caching, Retry & Circuit Breaker)	Complete
v0.6.1	Phase 6 Milestones 2–3 (Copernicus, ERA5, GDELT Ingestion & OSM Administrative Boundaries)	Complete
v0.6.2	Phase 6 Milestones 4–5 (ArXiv Open-Access Corpus & Offline Simulation Calibration)	Complete
v0.6.3	Phase 6 Milestone 6 (MinIO Self-Hosted Object Storage Option)	Complete
v0.6.4	Phase 6 Operational Readiness & Polish	Complete
v0.7.0	Phase 7 Milestones 1–3 (Explainability & Reasoning Trace Exploration, Pattern Mining, Python SDK)	Complete
v0.7.1	Phase 7 Milestone 4 (CLI Wizard & Developer Tooling)	Complete
v0.7.2	Phase 7 Milestones 5–6 (Horizontal Scaling Evaluation & OpenMetrics Telemetry Enrichment)	Complete
v0.7.3	Phase 7 Milestone 7 (Deployment Governance & Scale Governance)	Complete
v0.7.4	Phase 7 Final Engineering Audit Exit (Persisted Telemetry & Governance Hardening)	Complete
v1.0.0	Phase 8 Capstone & GaiaOS v1.0 General Availability	Complete

Detailed architectural specifications, documentation hub, and milestone scope documents are linked below:

• Documentation Hub: docs/README.md
• Architecture: docs/Architecture.md
• Roadmaps: docs/Roadmap_Phase1.md, docs/Roadmap_Phase2.md, docs/Roadmap_Phase3.md, docs/Roadmap_Phase4.md, docs/Roadmap_Phase5.md, docs/Roadmap_Phase6.md, docs/Roadmap_Phase7.md
• Versioning Strategy: docs/releases/Versioning.md

Core Architecture

GaiaOS is structured into four primary layers:

• API & Gateway (app/, gateway/, auth/): FastAPI REST and SSE endpoints with JWT/API key authentication and Redis rate limiting.
• Reasoning Core (orchestrator/): LangGraph engine coordinating domain-specific risk agents (seismic, atmosphere, ocean, wildfire, air quality, RAG, causal chain, simulation, synthesis, critic).
• Background Worker & Task System (workers/, alerting/, ops/): RQ worker pool for asynchronous investigation jobs, hazard ingestion, alert evaluation, and automated database backups.
• Observability & Operations (metrics/, alerting/, admin_ui/, ops/): Metrics pipeline, threshold alerts, React/TypeScript Admin UI, and operational runbooks.

For repository folder trees and code placement guidance, see Project Structure & Code Placement.

Quick Start

Prerequisites

• Python 3.12 (pinned in .python-version)
• Node.js 18+ & npm (for admin_ui/)
• Docker Engine 24+ & Docker Compose v2

For detailed OS-specific setup (Windows, Linux, macOS), see the Environment Setup Guide.

Setup & Local Execution

# Clone & virtualenv setup
git clone https://github.com/Diyaaa-12/GaiaOS.git
cd GaiaOS
python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .\.venv\Scripts\Activate.ps1

# Install dependencies using pinned lockfile
pip install -r requirements/dev.lock

# Copy environment configs
cp .env.example .env
cp docker-compose.override.yml.example docker-compose.override.yml

# Start full stack via Docker Compose
docker compose up -d --build

Services:

• API Server & OpenAPI UI: http://localhost:8000/docs
• OpenMetrics Prometheus Endpoint: http://localhost:8000/api/v1/admin/metrics/prometheus
• Grafana Dashboard: ops/dashboards/gaiaos-dashboard.json
• Admin Dashboard: http://localhost:3000

Recommended Quickstart (CLI Wizard & Python SDK)

Install the GaiaOS CLI and Python SDK:

pip install -e cli/ -e sdk/python/

Submit an investigation and stream real-time SSE execution events via CLI:

gaiaos auth login
gaiaos investigate "Assess seismic and ocean anomaly risks in the Pacific" --stream

Scaffold a new domain agent plugin:

gaiaos plugin scaffold hydrology

Or interact programmatically via Python SDK:

from gaiaos_sdk import GaiaClient

client = GaiaClient(base_url="http://localhost:8000")
investigation = client.investigations.create("Assess seismic hazard in California")
print(investigation.investigation_id)

(Note: Raw HTTP curl request examples are retained in the API Documentation. For API semver commitments, see the v1.0 API Stability Contract).

For complete production deployment, database migration hooks, MinIO configuration, Grafana dashboard import, and PostgreSQL/Redis operational maintenance, see the Deployment & Operations Runbook.

Development & Local Verification

GaiaOS provides a unified local verification tool (scripts/verify.py) as well as individual verification commands:

# Unified local CI verification
python scripts/verify.py

# Or run individual checks:
ruff check .
mypy .
pytest
python scripts/generate_openapi_spec.py

See the Development & CI Workflow Guide for complete details.

Community & Support

We welcome contributions and community involvement!

• Central Documentation Hub: Explore docs/README.md.
• First-Time Contributors: Read our First PR Guide and explore issues tagged good first issue.
• Step-by-Step How-To Guides: See How-To Guides for adding agents, APIs, models, and tests.
• Domain Agent Contributions: See the Domain Agent Contribution Guide.
• Community Support & Q&A: Read SUPPORT.md.
• Security Policy: Read SECURITY.md.
• Code of Conduct: Read CODE_OF_CONDUCT.md.

Documentation & Navigation

All architectural specifications, contributor guides, API schemas, release notes, operational runbooks, and audit reports are indexed in the Documentation Hub.

• Documentation Hub — Complete index of all project documentation.
• Contributing Guidelines — Governance, branching strategy, and PR requirements.
• Support & Q&A — Community support channels, issue triage taxonomy, and SLA.
• Security Policy — Vulnerability reporting and security disclosures.

Continuous Integration

GitHub Actions workflow (.github/workflows/ci.yml) enforces:

• Ruff linting and Mypy type validation
• Pytest suite execution
• OpenAPI specification drift detection (python scripts/generate_openapi_spec.py vs git diff --exit-code)
• Container image build & health verification (app, worker, scheduler, admin_ui)