Skip to content

SPEC.md

Latest commit

 

History

History
201 lines (150 loc) · 10.9 KB

SPEC.md

File metadata and controls

201 lines (150 loc) · 10.9 KB

Codomyrmex Functional Specification

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

System Concept

Codomyrmex is an idealized modular workspace designed to facilitate interaction between (pairwise) and among (multiple) humans, people, agents, synthetic systems, embodiments, tools, and things most broadly.

It functions as a cohesive "colony" of specialized modules where each component has a single responsibility, clear boundaries, and standardized interfaces. The system abstracts complexity through layering, ensuring that high-level workflows can be orchestrated without tight coupling to low-level implementations.

Functional Requirements

  • Modularity: The system must allow individual modules to be added, removed, or upgraded without breaking the larger system.
  • Agent-Readability: All components must be self-documenting in a way that is parseable and understandable by AI agents (via AGENTS.md and SPEC.md).
  • Deep Signposting: Every directory must provide clear navigation to its parent, children, and related modules to enable distinct context retrieval.
  • Polyglot Support: The architecture must support tools and code in multiple languages, unified by standard protocols (like MCP and shared config).
  • Safe Execution: Code execution must be sandboxed and observable.
  • Discoverability: All modules must be discoverable via the system_discovery mechanism and registered in the module index.
  • Instrumentation: Every module must integrate with logging_monitoring for structured telemetry and observability.
  • Integration Workspaces: The projects/ surface must support standalone integration projects (including daf-consulting and hermes-paperclip-adapter) without coupling into core module boundaries.

Design Principles

Modularity

  • Each module is a self-contained unit under src/codomyrmex/ with its own implementation, tests, and RASP documentation pattern — four standard files that make every module self-describing:
    • README.md — Module overview, exports, and quick start
    • AGENTS.md — AI agent coordination and operating contracts
    • SPEC.md — Functional specification and design rationale
    • PAI.md — PAI system integration and algorithm phase mapping
  • Modules expose only public APIs; internal implementation details remain encapsulated.
  • Adding, removing, or upgrading a module must not require changes to unrelated modules.

Internal Coherence

  • Consistent directory structure and naming conventions across all 128 top-level modules.
  • Unified documentation patterns: every module carries the same set of specification files.
  • Shared configuration idioms via standardized Config objects and pyproject.toml extras.

Parsimony

  • Include only essential elements; avoid speculative abstractions.
  • Minimize the public API surface area of each module to reduce coupling.
  • Lazy module loading ensures startup cost scales with usage, not with total module count.

Functionality

  • Prioritize working solutions over theoretical completeness.
  • Forward-looking design that accommodates future modules without requiring rewrites.
  • Each module must deliver demonstrable value through its defined interfaces.

Testing

  • Comprehensive test coverage enforced through pytest with structured markers (unit, integration, slow, network, external).
  • 40% line-coverage floor in [tool.coverage.report] fail_under (pyproject.toml). Plain uv run pytest does not collect coverage; make test, CI unit jobs, and explicit --cov=src/codomyrmex --cov-fail-under=40 apply the gate. The experimental meme package is omitted from [tool.coverage.run] measurement.
  • Test-driven development practices encouraged; tests live alongside source in src/codomyrmex/tests/unit/<module>/.
  • Real data analysis required over mocked approximations. Tests use skip-when-unavailable guards for external dependencies.

Documentation

  • Self-documenting code with clear docstrings and type annotations.
  • Complete API specifications (API_SPECIFICATION.md) and MCP tool definitions (MCP_TOOL_SPECIFICATION.md) for applicable modules with AI-callable tools.
  • Living documentation that stays synchronized with implementation through scaffolding tools.

Architecture

The system is organized into four hierarchical layers. Dependencies flow strictly upward: higher layers may depend on lower layers, but never the reverse.

graph TB
    subgraph Application["Application Layer"]
        CLI[cli]
        SD[system_discovery]
    end

    subgraph Service["Service Layer"]
        DOC[documentation]
        API[api]
        CICD[ci_cd_automation]
        CONT[containerization]
        DB[database_management]
        CFG[config_management]
        LOG2[logistics]
        ORCH[orchestrator]
    end

    subgraph Core["Core Layer"]
        AGT[agents]
        COD[coding]
        LLM[llm]
        GIT[git_operations]
        SEC[security]
        PERF[performance]
        DV[data_visualization]
    end

    subgraph Foundation["Foundation Layer"]
        LM[logging_monitoring]
        ES[environment_setup]
        MCP[model_context_protocol]
        TI[terminal_interface]
    end

    Application --> Service
    Service --> Core
    Core --> Foundation
Loading
  • Foundation Layer: Core infrastructure consumed by every other layer. Provides logging, environment validation, MCP interfaces, and terminal formatting.
  • Core Layer: Primary capabilities including agent frameworks, code analysis (within coding/), LLM integration, version control, security scanning, performance profiling, and data visualization.
  • Service Layer: Higher-level orchestration that composes core capabilities into documentation generation, API management, CI/CD pipelines (includes build automation), container management, database operations, configuration, logistics workflows, and workflow orchestration.
  • Application Layer: User-facing entry points. The CLI provides the primary human interface; system_discovery provides module health monitoring and dynamic registration.

API Specifications

Simulation Module (codomyrmex.simulation)

Simulator

  • __init__(config: SimulationConfig = None, agents: List[Agent] = None): Initialize simulation.
  • run() -> SimulationResult: Execute simulation loop.
  • add_agent(agent: Agent): Add agent to environment.
  • remove_agent(agent_id: str): Remove agent from environment.

Agent (Abstract Base Class)

  • act(observation: dict) -> Action: logic for agent decision making.
  • learn(reward: float): logic for agent learning.

Networks Module (codomyrmex.networks)

NetworkGraph

  • add_node(node_id: str, data: Any = None) -> Node: Add node to graph.
  • add_edge(source_id: str, target_id: str, weight: float = 1.0) -> Edge: Add edge between nodes.
  • get_neighbors(node_id: str) -> List[Node]: Get adjacent nodes.
  • shortest_path(start_id: str, end_id: str) -> List[Node]: Find shortest path (Dijkstra).

Quality Standards

  • Coupling: Aim for loose coupling between modules and high cohesion within each module.
  • Modularity Gate: New modules must pass structure validation (RASP documentation — README, AGENTS, SPEC, PAI — plus __init__.py and test file scaffolding) before being committed.
  • Documentation Coverage: 100% of module directories must contain a non-skeletal README.md with accurate content.
  • Interface Stability: Public API changes require a semantic version bump and updated specification documents.
  • Test Coverage: All modules must maintain unit test coverage; integration tests are required for cross-module interactions.

Interface Contracts

  • Entry Points: __init__.py serves as the primary entry point for every module, exporting the public API.
  • Configuration: Modules receive configuration through standardized Config objects and environment variables validated by environment_setup.
  • Output Standards: Consistent return types (e.g., Result objects for operations, structured dicts for data) across all module APIs.
  • MCP Protocol: Modules that expose AI-callable tools must define them in MCP_TOOL_SPECIFICATION.md following the Model Context Protocol schema.
  • Error Handling: Modules must raise domain-specific exceptions and log errors through logging_monitoring rather than silently failing.

Modularity & Interfaces

  • Inputs:
    • User commands (CLI, Shell).
    • AI Agent requests (MCP, Function Calls).
    • Event triggers (File changes, Webhooks).
  • Outputs:
    • Synthesized code and artifacts.
    • Structured logs and telemetry.
    • Visualizations and reports.
    • Executable processes.
  • Boundaries:
    • Modules interact primarily through public APIs defined in src/codomyrmex/.
    • Cross-module dependencies are strictly hierarchical (Foundation -> Core -> Service -> Application).

Implementation Guidelines

  • Scaffolding: Use doc_scaffolder.py to initialize new modules with the correct directory structure and documentation templates.
  • Signposting: Maintain current parent/child navigation links in all markdown files to support agent traversal.
  • Dependency Management: All dependencies are declared in pyproject.toml; module-specific requirements.txt files are deprecated.
  • Refactoring: Regularly audit modules for TODO cleanup, placeholder replacement, and adherence to current conventions.
  • Versioning: All modules follow semantic versioning starting at v0.1.0; version bumps are coordinated at the repository level.

Coherence

This root directory serves as the nexus of the colony. It does not contain business logic itself but defines the structure (skeleton) and rules (membrane) that hold the organism together. The src/ directory contains the organs, docs/ the memory, and scripts/ the reflexive behaviors.

Known Architecture Debt

Active items tracked by sprint target.

Item Status Sprint Target Notes
Circular imports: ~35 pairs across modules Fixed Sprint 17 Sprint 17 audit: --check confirmed 0 circular imports via ci_cd_automation build import fix
Oversized files: 16 non-test files >800 LOC Open Sprint 35 Largest: orchestration.py; ongoing; track in TODO.md
6 optional modules fail import Expected — Cloud (AWS/Azure/GCP), performance.monitoring, lazy_loader, security cert validator — require optional SDKs
Bidirectional PAI↔codomyrmex comms Fixed v1.1.0 agents/pai/pai_webhook.py + agents/pai/pai_client.py added in v1.1.0
Tool versioning: no deprecation timeline UI Open Sprint 35 deprecated_in metadata present but not surfaced in MCP tool list

Navigation Links