Codomyrmex Modules -- Technical Specification Overview

Version: v1.1.9 | Status: Active | Last Updated: March 2026

Overview

This document provides the top-level technical specification for the codomyrmex module system. Each module subdirectory contains its own SPEC.md with detailed functional requirements, interface contracts, and non-functional requirements.

System Architecture

Layered Dependency Model

Dependencies flow upward only. No module may depend on a module in a higher layer.

+-------------------+
| Application Layer | -- CLI, audio, video, domain modules
+-------------------+
| Service Layer     | -- CI/CD, containerization, orchestration, email
+-------------------+
| Core Layer        | -- agents, coding, git_operations, llm, cache
+-------------------+
| Foundation Layer  | -- logging, environment_setup, MCP, terminal, utils
+-------------------+

Module Discovery

• Auto-discovery via pkgutil scan of all mcp_tools.py submodules
• @mcp_tool decorator registers tools with 5-minute TTL cache
• 151 mcp_tools.py files (non-test), 627 production @mcp_tool lines — docs/reference/inventory.md
• Discovery entry point: src/codomyrmex/agents/pai/mcp/discovery.py

Cross-Cutting Requirements

NFR-1: Zero-Mock Policy

All modules shall follow the zero-mock testing policy:

• No unittest.mock, MagicMock, monkeypatch, or pytest-mock
• External dependencies use @pytest.mark.skipif guards
• Production code never returns placeholder data
• Unimplemented features raise NotImplementedError

NFR-2: No Silent Fallbacks

• Fallback patterns that silently degrade functionality are prohibited
• All failures must be explicit and logged
• Error propagation uses exception chaining (raise ... from ...)

NFR-3: Trust Gateway

• All MCP tool invocations pass through the Trust Gateway
• Destructive tools require explicit trust elevation
• Trust state persists to ~/.codomyrmex/trust_ledger.json
• Three levels: UNTRUSTED, VERIFIED, TRUSTED

NFR-4: Configuration

• No hardcoded URLs, ports, or connection strings
• All configurable values use os.getenv() with centralized defaults
• Module-specific configuration via config_management module

NFR-5: Lazy Loading

• Modules load on demand to minimize startup time
• Heavy optional dependencies (cloud SDKs, ML frameworks) are conditionally imported
• ImportError is caught and availability flags are set

NFR-6: RASP Documentation

Every module shall maintain four documentation files:

File	Purpose
README.md	Human-readable module overview
AGENTS.md	Agent integration guide with MCP tool tables
SPEC.md	Technical specification with interface contracts
PAI.md	PAI phase mapping and AI capability description

NFR-7: Test Markers

Tests shall use standardized pytest markers:

• @pytest.mark.unit -- Unit tests
• @pytest.mark.integration -- Integration tests
• @pytest.mark.slow -- Long-running tests
• @pytest.mark.network -- Tests requiring network access
• @pytest.mark.external -- Tests requiring external services

Interface Standards

MCP Tool Interface

All MCP tools shall follow this signature pattern:

@mcp_tool(
    name="module_action",
    description="Clear description of what this tool does",
    schema={
        "type": "object",
        "properties": {
            "param_name": {"type": "string", "description": "Parameter description"}
        },
        "required": ["param_name"]
    }
)
def tool_function(param_name: str) -> dict:
    """Tool implementation."""
    return {"status": "success", "data": result}

Return Value Contract

MCP tools shall return dictionaries with:

• "status": Either "success" or "error"
• "data" or "message": Result payload or error description
• Additional keys as needed by the specific tool

Error Handling Contract

Modules shall:

• Define module-specific exception classes inheriting from a base exception
• Use structured logging via logging_monitoring
• Propagate errors with exception chaining (raise X from Y)
• Never silently swallow exceptions

Module Inventory by Layer

Foundation (6 modules)

Module	Key Interfaces	Spec
environment_setup	check_dependencies(), validate_env()	SPEC
exceptions	Base exception hierarchy	SPEC
logging_monitoring	logging_format_structured()	SPEC
model_context_protocol	inspect_server(), list_registered_tools()	SPEC
terminal_interface	Rich terminal output	SPEC
utils	Shared utilities	SPEC

Core (20 modules)

Module	Key Interfaces	Spec
agents	execute_agent(), list_agents()	SPEC
agentic_memory	memory_put(), memory_get(), memory_search()	SPEC
auth	Token validation, permission checking	SPEC
cache	cache_get(), cache_set(), cache_delete()	SPEC
cerebrum	query_knowledge_base(), add_case_reference()	SPEC
coding	code_execute(), code_review_file()	SPEC
collaboration	swarm_submit_task(), pool_status()	SPEC
compression	compress(), decompress()	SPEC
concurrency	Thread/process pool management	SPEC
config_management	get_config(), set_config()	SPEC
crypto	hash_data(), verify_hash(), generate_key()	SPEC
encryption	Symmetric/asymmetric encryption	SPEC
events	emit_event(), list_event_types()	SPEC
git_operations	35 git automation tools	SPEC
llm	generate_text(), list_local_models()	SPEC
networking	HTTP client utilities	SPEC
search	search_documents(), search_fuzzy()	SPEC
serialization	JSON/YAML/MessagePack	SPEC
static_analysis	Code quality scanning	SPEC
validation	validate_schema(), validate_config()	SPEC

Service (29 modules)

See individual module SPEC.md files for detailed interface contracts.

Application (22 modules)

See individual module SPEC.md files for detailed interface contracts.

Performance Requirements

• Module import time: < 100ms per module (lazy loading)
• MCP tool discovery: < 5s for full scan (cached for 5 minutes)
• MCP tool response: < 30s for non-streaming tools
• Test suite: < 10 minutes for full run (excluding @pytest.mark.slow)

Navigation

• Module index: README.md
• Agent integration: AGENTS.md
• Source modules: src/codomyrmex/