Skip to content

full-setup.md

Latest commit

 

History

History
345 lines (256 loc) · 12.1 KB

full-setup.md

File metadata and controls

345 lines (256 loc) · 12.1 KB

Setup Guide

Installation and development setup for Codomyrmex. For architecture and module reference, see Architecture Overview and Module Reference.

Installation & Setup

Prerequisites

  • Python ≥3.11
  • uv (recommended) or pip

Installation Options

Option 1: Using uv (Recommended)

git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex
uv sync

Option 2: Using pip

git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex
uv pip install -e .

Verify Installation

# Launch interactive shell
./start_here.sh

# Or use the CLI directly
codomyrmex --help

# Discover available modules
uv run python -c "from codomyrmex.system_discovery import SystemDiscovery; SystemDiscovery().discover_modules()"

For detailed installation instructions, see the Installation Guide.

Getting Started Workflow

Typical user journey with Codomyrmex:

flowchart TD
    Start([Start]) --> Install{Install Codomyrmex}

    Install -->|uv sync| Config["Configure Environment"]
    Install -->|uv pip install| Config

    Config --> Setup["Environment Setup"]
    Setup --> Discover["Discover Modules"]

    Discover --> Choose{Choose Workflow}

    Choose -->|CLI Usage| CLI["Use CLI Commands"]
    Choose -->|Interactive| Interactive["Launch Interactive Shell"]
    Choose -->|API| API["Use REST API"]

    CLI --> Modules["Work with Modules"]
    Interactive --> Modules
    API --> Modules

    Modules --> Dev{Development Tasks}

    Dev -->|Code Analysis| Analysis["Static Analysis Code Review"]
    Dev -->|Build & Deploy| Build["CI/CD Automation & Deployment"]
    Dev -->|AI Assistance| AI["AI Code Editing Pattern Matching"]
    Dev -->|Visualization| Viz["Data Visualization 3D Modeling"]
    Dev -->|Infrastructure| Infra["Container Management Database Operations"]

    Analysis --> Extend["Extend & Customize"]
    Build --> Extend
    AI --> Extend
    Viz --> Extend
    Infra --> Extend

    Extend --> Contrib{Contribute Back}

    Contrib -->|Bug Reports| Issues["File Issues in GitHub"]
    Contrib -->|Features| PR["Create Pull Requests"]
    Contrib -->|Documentation| Docs["Improve Documentation"]

    Issues --> End([End])
    PR --> End
    Docs --> End

    Modules --> End
Loading

Project Structure

codomyrmex/
├── /src/codomyrmex/          # Core source modules
│   ├── /src/codomyrmex/coding/              # Code interaction and sandboxing
│   ├── /src/codomyrmex/coding/static_analysis/ # Code quality analysis
│   ├── /src/codomyrmex/logging_monitoring/  # Centralized logging
│   └── ...                  # 128 top-level modules
├── /scripts/                 # Maintenance and automation utilities
│   ├── /scripts/documentation/       # Documentation maintenance scripts
│   ├── /scripts/development/         # Development utilities
│   ├── /scripts/examples/            # Example scripts and demonstrations
│   └── ...                  # 30+ module orchestrators
├── /docs/                    # Project documentation
│   ├── /docs/getting-started/     # Installation and quickstart guides
│   ├── /docs/modules/             # Module system documentation
│   ├── /docs/project/             # Architecture and contributing guides
│   └── /docs/reference/           # API reference and troubleshooting
├── /src/codomyrmex/tests/    # Test suites
│   ├── /src/codomyrmex/tests/unit/                # Unit tests
│   └── /src/codomyrmex/tests/integration/         # Integration tests
├── /config/                  # Configuration templates and examples
│   ├── /config/examples/            # Configuration examples
│   └── /config/templates/           # Configuration templates
├── /cursorrules/             # Coding standards and automation rules
│   ├── /cursorrules/modules/             # Module-specific rules
│   ├── /cursorrules/cross-module/        # Cross-module coordination rules
│   └── /cursorrules/file-specific/       # File-specific rules
├── /projects/                # Project workspace and templates
│   └── /projects/test_project/        # Example project structure
└── /output/                 # Generated output and reports

Repository Organization

graph TD
    subgraph corePlatform ["Core Platform"]
        CoreSrc["src/codomyrmex/ 88 Modules"]
        CoreScripts["scripts/ Automation & Orchestration"]
        CoreTests["src/codomyrmex/tests/ Unit & Integration Tests"]
    end

    subgraph docsConfig ["Documentation & Config"]
        Docs["docs/ User & Developer Guides"]
        Config["config/ Templates & Examples"]
        Rules["cursorrules/ Coding Standards"]
        Projects["projects/ Project Templates"]
    end

    subgraph examplesOutput ["Examples & Output"]
        ModuleExamples["scripts/[module]/examples/ Module Examples"]
        Output["output/ Generated Reports"]
        ScriptsExamples["scripts/examples/ General Examples"]
    end

    CoreSrc --> Docs
    CoreScripts --> Docs
    CoreTests --> Docs
    Config --> CoreSrc
    Rules --> CoreSrc
    Projects --> CoreScripts
    ModuleExamples --> CoreSrc
    ScriptsExamples --> CoreScripts
    CoreSrc --> Output
    CoreScripts --> Output
Loading

Signposting

Navigation Links:

Documentation

Comprehensive documentation for users, developers, and contributors. All documentation is organized in the docs/ directory.

Getting Started

Architecture & Design

Development Resources

Integration

Reference

Deployment

Workflow Orchestration

Examples

See Documentation Hub for complete documentation index.

Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/codomyrmex --cov-report=html

# Run specific test suite
uv run pytest src/codomyrmex/tests/unit/
uv run pytest src/codomyrmex/tests/integration/

Code Quality

# Format code
uv run black src/

# Lint code
uv run ruff check src/

# Type checking
uv run ty check src/

Module Development

See Creating a Module Tutorial for detailed guidance on developing new modules.

Contributing

We welcome contributions! Please see our Contributing Guide for:

  • Code standards and best practices
  • Development workflow
  • Pull request process
  • Testing requirements
  • Documentation guidelines

Security

Security is a priority. See SECURITY.md for:

  • Vulnerability reporting
  • Security best practices
  • Module-specific security considerations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 The Codomyrmex Contributors (@docxology)

Key Metrics

  • Lines of Code: ~100K+ across 128 top-level modules
  • Test Coverage: Run uv run pytest --cov=src/codomyrmex (gate in pyproject.toml)
  • Module Count: 128 top-level packages — see reference/inventory.md and codomyrmex modules for health
  • Language Support: Python, JavaScript, Go, Rust, Java
  • AI Integration: 5+ LLM providers supported
  • Documentation: 200+ pages across all modules

Links

Built with a focus on modularity, clarity, and professional development practices.

Navigation Links

Example Usage

# CLI usage (primary entry point)
codomyrmex check                 # Verify environment setup
codomyrmex modules               # List available modules
codomyrmex status                # System status dashboard
codomyrmex shell                 # Interactive shell

# Python API usage
uv run python -c "
from codomyrmex.system_discovery import SystemDiscovery
sd = SystemDiscovery()
sd.discover_modules()
"