| --- |
| tags: |
| - ai-agents |
| - orchestration |
| - python |
| - cli |
| - local-ai |
| license: mit |
| --- |
| |
| # 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. |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| aegis run --help |
| aegis run "Run the default Aegis workflow" |
| ``` |
|
|
| ## CLI usage |
|
|
| Run the default workflow: |
|
|
| ```bash |
| aegis run "Review this repository" |
| ``` |
|
|
| Run a specific agent: |
|
|
| ```bash |
| aegis run --agent default-task "Review this repository" |
| ``` |
|
|
| Return structured JSON: |
|
|
| ```bash |
| aegis run --output json "Review this repository" |
| ``` |
|
|
| Limit execution steps: |
|
|
| ```bash |
| aegis run --max-steps 10 "Review this repository" |
| ``` |
|
|
| ## Development |
|
|
| Run the full validation suite: |
|
|
| ```bash |
| 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. |
|
|
