Metadata-Version: 2.4
Name: aegis-qa
Version: 0.2.0
Summary: Aegis — The AI Quality Control Plane
Author: Jack Blacketter
License: MIT
Project-URL: Homepage, https://jblacketter.github.io/
Project-URL: Repository, https://github.com/jblacketter/aegis
Project-URL: Changelog, https://github.com/jblacketter/aegis/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/jblacketter/aegis/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: PyYAML>=6.0
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: httpx>=0.27
Requires-Dist: aiosqlite>=0.20
Requires-Dist: prometheus_client>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"

# Aegis

[![CI](https://github.com/jblacketter/aegis/actions/workflows/ci.yml/badge.svg)](https://github.com/jblacketter/aegis/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/aegis-qa)](https://pypi.org/project/aegis-qa/)
[![Docker](https://img.shields.io/badge/ghcr.io-aegis-blue)](https://ghcr.io/jblacketter/aegis)
[![API Docs](https://img.shields.io/badge/API_Docs-OpenAPI-6366f1)](http://localhost:8000/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

```mermaid
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

```bash
# 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.

```python
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'}")
```

```python
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

```bash
# 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

```bash
# 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:

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

## License

MIT
