Aegis
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.