Skip to main content

Aegis

CI PyPI Docker API Docs

The AI Quality Control Plane

Aegis is a lightweight orchestration layer that unifies AI-powered QA tools into a single control plane. It coordinates route discovery, test generation, bug triage, and fix proposals across your development workflow.

Architecture

graph TB
    subgraph Aegis["Aegis — Control Plane"]
        API[FastAPI API<br/>Typed OpenAPI Spec]
        WF[Workflow Engine]
        REG[Service Registry]
        EV[Event System<br/>Emitter · Log · Webhooks]
        HIST[History<br/>SQLite / In-Memory]
        HP[Health Endpoint<br/>Version · Uptime · Config]
        LP[Landing Page]
    end

    SDK[Python SDK<br/>AegisClient · AsyncAegisClient] --> API

    subgraph Tools["QA Tool Suite"]
        QA[QA Agent<br/>Route Discovery · Risk Analysis<br/>Test Generation · Orchestration]
        BUG[Bugalizer<br/>Bug Triage · Code Localization<br/>Duplicate Detection]
    end

    subgraph LLM["LLM Backend"]
        OLL[Ollama<br/>qwen2.5-coder:7b]
    end

    API --> WF
    WF --> REG
    WF --> HIST
    WF --> EV
    REG --> QA
    REG --> BUG
    QA --> OLL
    BUG --> OLL
    LP --> API
    EV -->|webhooks| EXT[External Systems]

Quick Start

# Install from PyPI
pip install aegis-qa

# Or install from source (for development)
pip install -e ".[dev]"

# Configure
cp .aegis.yaml.example .aegis.yaml
# Edit .aegis.yaml with your service URLs

# Check service status
aegis status

# Run the full QA pipeline
aegis run full_pipeline

# Start the API server + landing page
aegis serve

Python SDK

The SDK is included when you pip install aegis-qa — no extra dependency needed.

from aegis_qa.client import AegisClient

# Sync client
with AegisClient(base_url="http://localhost:8000") as client:
    health = client.health()
    print(f"Status: {health.status}, uptime: {health.uptime_seconds}s")

    services = client.list_services()
    for svc in services:
        print(f"  {svc.name}: {svc.status}")

    result = client.run_workflow("full_pipeline")
    print(f"Pipeline {'passed' if result.success else 'failed'}")
from aegis_qa.client import AsyncAegisClient

# Async client
async with AsyncAegisClient(api_key="your-key") as client:
    workflows = await client.list_workflows()
    history = await client.recent_history(limit=5)

Deployment

Docker

# Pull the latest image
docker pull ghcr.io/jblacketter/aegis:latest

# Or build locally
docker build -t aegis .

# Run the server
docker run -p 8000:8000 aegis

# Verify it's running
curl http://localhost:8000/health

Docker Compose

# Start with SQLite persistence and config mounting
docker compose up

# Run in background
docker compose up -d

The compose file mounts .aegis.yaml (read-only) and persists the SQLite database on a named volume.

Environment Variables

Variable Description Default
AEGIS_DB_PATH Override SQLite database path Value from .aegis.yaml

Tools

Tool Description Features
QA Agent Route discovery, risk analysis, test generation & orchestration Route Discovery, Risk Assessment, Test Generation, Test Orchestration, Branch Board
Bugalizer AI-powered bug triage, code localization & fix proposals Bug Triage, Code Localization, Duplicate Detection

CLI Commands

Command Description
aegis status Show all services and their health status
aegis serve Start API server and serve landing page
aegis run <workflow> Execute a named workflow pipeline
aegis openapi Export OpenAPI spec as JSON
aegis config show Print resolved configuration

API Endpoints

Endpoint Method Description
/health GET Health check with version, uptime, and config summary
/api/services GET List services with health status
/api/services/{name}/health GET Live health check for one service
/api/workflows GET List all configured workflows
/api/workflows/{name} GET Get a specific workflow definition
/api/workflows/{name}/run POST Trigger a named workflow
/api/workflows/{name}/history GET Execution history for a workflow
/api/history GET Recent execution history across all workflows
/api/events GET Recent events (filterable by type)
/api/portfolio GET Tool metadata for landing page

Configuration

Aegis uses .aegis.yaml for configuration. See .aegis.yaml.example for the full schema.

Environment variables can be interpolated using ${VAR_NAME} syntax:

services:
  qaagent:
    url: ${QAAGENT_URL:-http://localhost:8080}

License

MIT

Metadata

Release files for aegis-qa 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aegis-qa 0.2.0
File Size Uploaded Provenance Actions
aegis_qa-0.2.0.tar.gz 66.9 kB With provenance Details for aegis_qa-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aegis-qa 0.2.0
File Interpreter ABI Platform Actions
aegis_qa-0.2.0-py3-none-any.whl Python 3 none any Details for aegis_qa-0.2.0-py3-none-any.whl

Total release size: 117.1 kB

Release files / aegis_qa-0.2.0.tar.gz

Download URL aegis_qa-0.2.0.tar.gz
Size 66.9 kB
Tags Source
SHA-256 checksum
How to use checksums
a96eaa1f4f25a992f86a6c2d7c44ef1c30c16ecd2dcbbe3129cdf5b5f986e3b1
BLAKE2b-256 checksum
How to use checksums
df4c2816e8b9601bb5a2011809721008e6ca84bf971e24c1756cd4ef7cac157c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 4, 2026.

Transparency log

Release files / aegis_qa-0.2.0-py3-none-any.whl

Download URL aegis_qa-0.2.0-py3-none-any.whl
Size 50.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
98dbc3e3eaea984d884f7aed344c3c03f46fb389ccb2f7a118bdea69940bf704
BLAKE2b-256 checksum
How to use checksums
066a363c20b459117cf1a0fee5502bcdcdda6f63c4bea7bf7414499d57273e75
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 4, 2026.

Transparency log

Security for aegis-qa 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aegis_qa-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page