Skip to content

Development Overview

Guide for developing and contributing to Project Aegis.

Repository Structure

aegis-core/
├── aegis/                  # Main Python package (78 modules)
│   ├── dashboard/          # FastAPI web application
│   │   ├── app.py          # Main app entry point
│   │   ├── routes/         # 30+ route modules
│   │   └── templates/      # Jinja2 templates
│   ├── scheduler.py        # APScheduler daemon
│   ├── db.py               # PostgreSQL connection pool
│   ├── config.py           # Pydantic settings
│   ├── llm/                # LLM routing (Opus, Haiku, GLM, Ollama)
│   ├── memory/             # Multi-tier memory system
│   ├── workflows/          # Graph-based workflow engine
│   ├── agents/             # Agent templates
│   ├── planning/           # HTN and Tree of Thoughts
│   └── ...                 # 70+ more modules
├── tests/                  # pytest test suite
├── docs/                   # Documentation (you're here)
├── scripts/                # Utility scripts
├── docker-compose.yml      # Service definitions
├── Dockerfile              # Container build
├── pyproject.toml          # Project metadata
└── requirements.txt        # Dependencies

Module Categories

Category Modules Purpose
Core config, db, cli Infrastructure
Dashboard app, routes, templates Web interface
LLM router, glm, haiku, ollama AI routing
Memory episodic, semantic, graphiti Data storage
Workflows graph, nodes, executor Task execution
Agents templates, critic, reflection Agent patterns
Communication discord, telegram, vonage Messaging
Revenue monetization, billing Payments

Development Setup

# Clone repository
git clone git@github.com:aegis-agent/aegis-core.git
cd aegis-core

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Start services
docker compose up -d

Coding Standards

Style

  • Python 3.12+
  • Type hints required
  • Black for formatting
  • Ruff for linting

Patterns

  • Pydantic for data models
  • AsyncIO for I/O operations
  • Dependency injection via FastAPI
  • Repository pattern for data access

Documentation

  • Docstrings for public functions
  • Type annotations
  • README for each major module

Git Workflow

Commit Messages

Add knowledge graph integration

Wires graphiti client to query entities during morning checks.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Branch Naming

  • feature/ - New features
  • fix/ - Bug fixes
  • refactor/ - Code improvements
  • docs/ - Documentation

Pull Requests

  1. Create feature branch
  2. Write tests
  3. Update documentation
  4. Submit PR with description
  5. Address review feedback

Testing

Framework

  • pytest with pytest-asyncio
  • Factory functions for test data
  • Mocking for external services

Running Tests

# All tests
pytest

# With coverage
pytest --cov=aegis --cov-report=html

# Specific module
pytest tests/test_memory.py

# Verbose output
pytest -v

Documentation

Last Updated: 2026-01-25