This guide is the short path from a fresh checkout to a useful local development loop for Agentic Titan.
Use Python 3.11 or newer. The CI matrix covers Python 3.11 and 3.12.
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev,dashboard,auth,ratelimit]"
If you use uv, the equivalent local command is:
uv run --python 3.11 --with '.[dev,dashboard,auth,ratelimit]' pytest
Run these before opening a pull request:
ruff check .
mypy .
pytest
For the same coverage mode used in CI:
pytest --cov=. --cov-report=xml --cov-report=term --cov-report=html
The repo is organized as root-level Python packages:
| Path | Purpose |
|---|---|
titan/ |
CLI, API, orchestration, safety, learning, and workflow code. |
hive/ |
Collective behavior primitives: memory, topology, stigmergy, and experiments. |
agents/ |
Agent archetypes and reusable agent behaviors. |
adapters/ |
LLM provider adapters and routing. |
runtime/ |
Local and isolated execution backends. |
dashboard/ |
FastAPI dashboard and templates. |
.ci/ |
Local governance and quality scripts used by CI. |
For a narrow fix, start with the relevant test file:
pytest tests/test_hive/test_perceptual_gating.py
pytest tests/ci/test_ai_quality_gate.py
Then run the broader gates before pushing:
ruff check .
mypy .
pytest --cov=. --cov-report=xml --cov-report=term --cov-report=html
This repo participates in ORGAN-IV orchestration. Keep dependencies flowing in
the approved direction, do not commit secrets, and do not bypass the
branch-protection dependency validation status. If a pull request is blocked on
validate-dependencies, run the canonical dependency validator and publish a
status only after it passes.