Aegis

Aegis is a modular Python framework for composing controlled agent workflows, registries, memory, tool execution, policies, and evaluation.

The project currently provides a runnable command-line interface that executes tasks through the built-in Aegis orchestration layer.

Current capabilities

• Typed agent and tool registries
• Planner, task agent, and evaluator workflow
• Runtime orchestration layer
• User-facing aegis run CLI
• Human-readable and structured JSON output
• Agent and workflow selection
• Execution step limits
• Stable process exit codes
• Pydantic-based contracts
• Ruff, mypy, and pytest validation
• Deterministic evaluation of task results

Installation

Clone from Hugging Face

This repository is currently private. You must authenticate with Hugging Face before cloning it.

hf auth login

git clone https://huggingface.co/jayc1978/aegis
cd aegis

python -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"

Verify the installation:

aegis run --help
aegis run "Run the default Aegis workflow"

CLI usage

Run the default workflow:

aegis run "Review this repository"

Run a specific agent:

aegis run --agent default-task "Review this repository"

Return structured JSON:

aegis run --output json "Review this repository"

Limit execution steps:

aegis run --max-steps 10 "Review this repository"

Development

Run the full validation suite:

pytest
ruff check .
mypy src

Current verified baseline:

• 56 tests passed
• Ruff passed
• mypy passed

Current limitations

• Memory is currently in-process only.
• No Ollama or Hugging Face inference provider is connected yet.
• The default workflow is deterministic.
• Tool integrations and policy enforcement remain limited.
• No persistent database, API server, or web interface is included yet.

Project direction

Aegis is intended to become an auditable, policy-controlled runtime for AI-agent automation.

Its purpose is to control:

• which tools an agent may use
• what data an agent may access
• when human approval is required
• how agent actions are evaluated
• how execution history is recorded

License

This project is licensed under the MIT License. See LICENSE for details.