aegis-qa 0.2.0

Aegis — The AI Quality Control Plane

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