<!-- markdownlint-disable MD033 MD041 MD060 --> <p align="center"> <a href="https://github.com/docxology/codomyrmex/actions/workflows/ci.yml"><img src="https://github.com/docxology/codomyrmex/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/docxology/codomyrmex/actions/workflows/security.yml"><img src="https://github.com/docxology/codomyrmex/actions/workflows/security.yml/badge.svg" alt="Security"></a> <a href="https://github.com/docxology/codomyrmex/actions/workflows/auto-merge.yml"><img src="https://github.com/docxology/codomyrmex/actions/workflows/auto-merge.yml/badge.svg" alt="Auto-Merge"></a> <br> <img src="https://img.shields.io/badge/Codomyrmex-v1.3.0-blue?style=for-the-badge" alt="Version"> <img src="https://img.shields.io/badge/Modules-132-green?style=for-the-badge" alt="Modules"> <img src="https://img.shields.io/badge/MCP_Runtime-622-orange?style=for-the-badge" alt="MCP runtime tools"> <img src="https://img.shields.io/badge/Workflows-38-purple?style=for-the-badge" alt="Workflows"> <img src="https://img.shields.io/badge/Zero--Mock-policy-brightgreen?style=for-the-badge" alt="Zero Mock policy"> <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"> <br> <a href="https://github.com/docxology/codomyrmex/stargazers"><img src="https://img.shields.io/github/stars/docxology/codomyrmex?style=flat-square&color=gold" alt="Stars"></a> <a href="https://github.com/docxology/codomyrmex/network/members"><img src="https://img.shields.io/github/forks/docxology/codomyrmex?style=flat-square&color=blue" alt="Forks"></a> <a href="https://github.com/docxology/codomyrmex/commits/main"><img src="https://img.shields.io/github/last-commit/docxology/codomyrmex?style=flat-square&color=green" alt="Last Commit"></a> <a href="https://github.com/docxology/codomyrmex/issues"><img src="https://img.shields.io/github/issues/docxology/codomyrmex?style=flat-square&color=orange" alt="Issues"></a> <img src="https://img.shields.io/github/repo-size/docxology/codomyrmex?style=flat-square&color=lightgrey" alt="Repo Size"> <img src="https://img.shields.io/badge/python-≥3.11-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/code%20style-ruff-D7FF64?style=flat-square&logo=ruff&logoColor=black" alt="Ruff"> <img src="https://img.shields.io/badge/types-ty-blue?style=flat-square" alt="ty"> <img src="https://img.shields.io/badge/tests-37%2C060-brightgreen?style=flat-square" alt="Tests"> </p>

🐜 Codomyrmex

A comprehensive, modular, agentic Python ecosystem for software engineering, personal AI infrastructure, and multi-agent orchestration.

Codomyrmex is a modular library of 132 top-level modules under src/codomyrmex/ spanning AI agents, cloud infrastructure, security, finance, multimedia, and more. The count is honest (every directory has an __init__.py) — roughly 25 modules are substantial production surfaces (agents, llm, cloud, security, coding, documentation, orchestrator, etc.), ~75 are legitimate but narrower utilities, and ~30 are teaching/exploratory modules (dpo, nas, ssm, softmax_opt, etc.) that demonstrate techniques rather than ship production workflows. A documented Zero-Mock policy governs the active test suites, while the measured quality gates and inventory describe what was actually checked in a given run; they do not imply that every method is complete or production-safe. In the complete locked dependency profile, the ecosystem exposes 622 runtime MCP tools in the generated manifest and 632 production @mcp_tool decorator lines in Python sources for Claude, Gemini, GPT, and any Model Context Protocol client (docs/reference/inventory.md). It includes 3,000+ Python files, 37,060 collected tests (uv run --locked --all-extras --group docs python scripts/doc_inventory.py --pytest), 1,217 Markdown files under docs/, and 38 GitHub Actions workflows (.github/workflows/*.yml). These are measured snapshot values for that dependency profile; refresh the linked inventory before treating them as current.

Technical report

The source-bound Codomyrmex v1.3.0 technical report is archived as a Zenodo record family: concept DOI 10.5281/zenodo.21750800, version DOI 10.5281/zenodo.21750801, and GitHub release v1.3.0-paper. The report documents implementation contracts and controlled fixtures; it does not claim external effectiveness, calibration, or production safety.

# Install
git clone https://github.com/docxology/codomyrmex.git && cd codomyrmex
uv sync --locked --all-groups

# Verify
uv run codomyrmex doctor --all

---

📋 Table of Contents

• Documentation Hub
• System Architecture
• Module Inventory
• Module Dependency Architecture
• Agent Orchestration Pipeline
• Project Structure
• Aggregate Statistics
• LLM Provider Matrix
• Agent Dispatch Architecture
• Testing Philosophy
• Configuration Architecture
• Personal AI Dashboard
• Quick Start
• Documentation Standards
• GitHub Actions Workflows
• License

---

✨ Why Codomyrmex?

| | | |---|---| | 🧩 132 Top-Level Modules | Packages under src/codomyrmex/ — modular interfaces with scoped zero-mock tests | | 🤖 622 Runtime MCP Tools | Complete locked dependency profile; 632 source @mcp_tool decorator lines; see inventory | | 🧪 37,060 Collected Tests | Complete locked dependency profile; uv run --locked --all-extras --group docs python scripts/doc_inventory.py --pytest; zero-mock policy | | 🔒 Security First | GitGuardian, SBOM, GGSHIELD pre-commit, detect-secrets integration | | 🎛️ 13+ Agent Providers | Claude, Gemini, GPT-4o, DeepSeek, Mistral, Jules, Codex, Pi, and more | | 🔬 ML Research Ready | LoRA, RLHF, DPO, distillation, quantization, NAS, Mamba SSM, autograd | | 🏠 Personal AI Infrastructure | Email, calendar, finance, wallet, dashboard — full PAI toolbox | | 📦 PyPI Ready | uv build + twine check verified, Python 3.11–3.14 | | 🦎 Zero Config to Start | uv sync → codomyrmex doctor → done |

---

📚 Documentation Hub

Top-Level Documents

| Document | Description | |:---|:---| | docs/README.md | Documentation home — full directory guide | | docs/ARCHITECTURE.md | System architecture, dependency layers, design patterns | | docs/AGENTS.md | Agent coordination rules and autonomous workflows | | docs/SPEC.md | Technical specification, API contracts, schemas | | docs/PAI.md | Personal AI Infrastructure integration reference | | docs/PAI_DASHBOARD.md | PAI dashboard GUI reference and tab guide | | docs/index.md | MkDocs site index and navigation entry point | | TODO.md | Authoritative backlog — what to do next (single source of truth for open work) |

Documentation Directories

| Directory | Files | Description | |:---|:---:|:---| | docs/getting-started/ | 9 | Quick start, installation, setup, tutorials | | docs/development/ | 10 | Dev environment, testing strategy, contribution guides | | docs/reference/ | 16 | API reference, CLI reference, troubleshooting | | docs/modules/ | 132 pkgs | Per-module documentation (README, SPEC, AGENTS, PAI per module) | | docs/agents/ | 118 | Agent rules, coordination, per-provider docs (mirror src/codomyrmex/agents/) | | docs/integration/ | 11 | External service integration (Google, GitHub, etc.) | | docs/deployment/ | 5 | Production deployment guides and checklists | | docs/security/ | 11 | Security theory, threat models, audit procedures | | docs/pai/ | 10 | PAI dashboard, email, calendar, skill management | | docs/bio/ | 15 | Biological & myrmecological perspectives | | docs/cognitive/ | 11 | Cognitive science & engineering perspectives | | docs/agi/ | 14 | AGI theory, emergence, recursive self-improvement | | docs/compliance/ | 5 | Audit reports, policy compliance, SOC2 | | docs/examples/ | 8 | Code examples, integration demos, walkthroughs | | docs/project/ | 9 | Architecture, roadmap, contributing, governance | | docs/project_orchestration/ | 11 | Multi-project workflow guides and pipelines | | docs/skills/ | 9 | Skill system lifecycle, governance, authoring | | docs/plans/ | 6 | Implementation plans and integration roadmaps |

---

📐 System Architecture

graph TB
    subgraph Core["🧠 Core Intelligence"]
        LLM["LLM Subsystem"]
        Agents["Agent Framework"]
        Cerebrum["Cerebrum Reasoning"]
        Orchestrator["Orchestrator"]
        MCP["Model Context Protocol"]
    end

    subgraph AI["🤖 AI & ML"]
        EvolutionaryAI["Evolutionary AI"]
        GraphRAG["Graph RAG"]
        PromptEng["Prompt Engineering"]
        VectorStore["Vector Store"]
        Coding["Coding Agents"]
        Skills["Skills Engine"]
    end

    subgraph Infra["☁️ Infrastructure"]
        Cloud["Cloud (AWS/GCP/Azure)"]
        Containerization["Containerization"]
        CICD["CI/CD Automation"]
        Deployment["Deployment"]
        EdgeComputing["Edge Computing"]
        Networking["Networking"]
    end

    subgraph Data["💾 Data & Storage"]
        DB["Database Management"]
        Cache["Cache Layer"]
        DataLineage["Data Lineage"]
        Serialization["Serialization"]
        Documents["Documents"]
        FeatureStore["Feature Store"]
    end

    subgraph Security["🔒 Security"]
        Auth["Authentication"]
        Crypto["Cryptography"]
        Encryption["Encryption"]
        Privacy["Privacy"]
        Defense["Defense"]
        Identity["Identity"]
    end

    subgraph Media["🎨 Multimedia"]
        Audio["Audio"]
        Video["Video"]
        Multimodal["Multimodal"]
        DataViz["Data Visualization"]
        Meme["Meme Generator"]
    end

    subgraph PAI["🏠 Personal AI"]
        Email["Email"]
        Calendar["Calendar"]
        Finance["Finance"]
        Wallet["Wallet"]
        Website["Website"]
        PAIDash["PAI Dashboard"]
    end

    subgraph DevTools["🛠️ Developer Tools"]
        CLI["CLI"]
        IDE["IDE Integration"]
        GitOps["Git Operations"]
        GitAnalysis["Git Analysis"]
        TreeSitter["Tree-sitter"]
        StaticAnalysis["Static Analysis"]
        Terminal["Terminal Interface"]
    end

    Core --> AI
    Core --> Infra
    Core --> Data
    Core --> Security
    Core --> Media
    Core --> PAI
    Core --> DevTools

    LLM --> Agents
    Agents --> Orchestrator
    Orchestrator --> MCP
    MCP --> Skills

---

🗂️ Complete Module Inventory

Every module links directly to its source, docs, config, and scripts directories. 132 top-level modules across 10 capability layers — from foundation utilities to ML training primitives.

🧠 Core Intelligence Modules

| Module | Py | Tests | Docs | Config | S