Overview

Repo: github.com/ryomenhaider/Aegis

What It Is

Aegis is a risk intelligence platform built on top of the Hermes data layer. It combines a FastAPI backend, Redis-backed caching, ML forecasting, and a Next.js frontend into one runnable application.

Stack

Frontend Screens

The Next.js app (App Router) ships several intelligence screens:

Quick Start

uv sync              # install Python deps
aiges run            # start backend (8000) + frontend (3000)

Requires Python >= 3.11 and Node.js for the frontend. See CLI for all commands.

Architecture

Layout

src/aiges/
├── backend/
│   ├── server.py          # FastAPI app bootstrap
│   ├── redis/redis.py     # Redis client
│   └── api/
│       ├── api.py         # main app: routes, CORS, title
│       └── routes/
│           ├── country.py # /country/{code}
│           └── forcast_api.py
├── cli/cli.py             # typer commands: run, serve, ui
├── config.py              # env loading (NEWS_DATA_API)
└── frontend/              # Next.js 15 App Router app

Data Flow

1. The frontend calls the FastAPI backend on port 8000.
2. Routes use the Hermes facade from the hermes-plt package to fetch country risk features, with a local Parquet cache at src/aiges/backend/hermes_cache.
3. Redis backs transient state; Supabase (Postgres) stores persisted records.
4. ML models (scikit-learn / xgboost / river) run in-process for forecasts and anomaly scoring.

Backend API

aiges.backend.api.api:app is the uvicorn entry point. It mounts CORS for http://localhost:3000 and exposes the platform routes — see API.

Frontend

The Next.js app runs on port 3000 with middleware, shadcn/ui components, and App Router screens (dashboard, country, forecast, anomaly, explain, reports, agent, scenarios).

Processes

Aegis runs as two cooperating processes — API server and Next.js server — orchestrated by the CLI:

aiges run          # both, dev mode
aiges serve        # backend only
aiges ui           # frontend only

API

Base

The API is served by uvicorn on port 8000 (configurable). CORS is enabled for http://localhost:3000.

Endpoints

GET /health

Service health probe.

{ "status": "ok" }

GET /aiges

Platform root — echoes the API name and health status.

{ "api": "aiges", "health": { "status": "ok", "version": "0.1.0" } }

GET /aiges/health

Health with version info.

{ "status": "ok", "version": "0.1.0" }

GET /country/{code}

Country risk features for an ISO3 code, computed through the Hermes facade (from hermes-plt).

import requests

resp = requests.get("http://127.0.0.1:8000/country/UKR")
features = resp.json()  # country risk feature dict

Internally the route builds a Hermes instance pointed at a local cache dir (src/aiges/backend/hermes_cache) and calls the feature pipeline for the requested code.

The OpenSanctions key and NEWS_DATA_API are read from the environment at import time — see Configuration.

Starting the API

aiges serve --host 0.0.0.0 --port 8000

or via the full platform:

aiges run

Interactive docs are available at http://127.0.0.1:8000/docs (FastAPI Swagger UI).

CLI

The aiges command is built with typer.

aiges run

Starts the backend and frontend together — the main entry point.

aiges run
aiges run --host 0.0.0.0 --backend-port 8080 --frontend-port 3100 --prod

The backend runs under uvicorn with --reload (excluding __pycache__* and *corrupt* paths). Both processes start, run, and terminate together on Ctrl+C.

aiges serve

Backend API only.

aiges serve

aiges ui

Next.js frontend only.

aiges ui
aiges ui --prod --port 3100

Fails with an error if the frontend directory (src/aiges/frontend) is missing.

Configuration

Backend Environment

The backend loads a .env file at src/aiges/config.py via dotenv:

The Hermes facade raises KeyError without the OpenSanctions key, and the country routes need NEWS_DATA_API — set both before running.

# in src/aiges/
echo "NEWS_DATA_API=your_key" >> .env

Frontend Environment

The Next.js app reads public env vars from src/aiges/frontend/.env.local:

Hermes Cache

Country feature calls use a local Parquet cache at src/aiges/backend/hermes_cache (set in routes/country.py) — no extra setup needed, but it persists between runs.