# 📚 Codomyrmex API Reference

> **"Complete API documentation for all Codomyrmex modules and functionality"**

This comprehensive API reference provides detailed documentation for all Codomyrmex modules, including function signatures, parameters, return values, examples, and integration patterns.

## 🏗️ **API Architecture Overview**

Codomyrmex provides **4 distinct API layers** to accommodate different integration needs:

### **1. 🐍 Python Module APIs** {#module-apis}

- **Direct imports** and function calls from Python code
- **Type-safe interfaces** with comprehensive documentation
- **Modular design** - import only what you need
- **Extensive examples** and usage patterns

### **2. 💻 CLI APIs**

- **Command-line interface** for all functionality
- **Scripting support** for automation workflows
- **Rich output formatting** with JSON/structured data
- **Comprehensive help system** and examples

### **3. 🤖 MCP Tool APIs**

- **Model Context Protocol** tools for AI/LLM integration
- **Standardized tool calling** interface
- **AI agent compatibility** with OpenAI, Anthropic, and other providers
- **Tool discovery** and metadata

### **4. 🌐 REST APIs** *(Planned)*

- **HTTP endpoints** for web integration
- **JSON-based communication**
- **Authentication and authorization**
- **Rate limiting and monitoring**

---

## 📋 **API Status Legend**

| Status | Description | Stability |
|--------|-------------|-----------|
| **✅ Stable** | Production-ready, fully tested | High - Breaking changes rare |
| **🔄 Evolving** | Feature-complete, minor updates | Medium - Minor changes possible |
| **🚧 Developing** | Core functionality, active development | Low - API may change |
| **📝 Planned** | Not yet implemented | N/A - Subject to change |

---

## 🏗️ **Module API Index**

### **🏗️ Foundation Modules**

These modules provide essential infrastructure used by all other Codomyrmex modules.

#### **[📋 logging_monitoring](../../src/codomyrmex/logging_monitoring/API_SPECIFICATION.md)**

**Centralized logging and monitoring system**

| Function | Description | Status |
|----------|-------------|--------|
| **`setup_logging()`** | Initialize structured logging system | ✅ Stable |
| **`get_logger(name)`** | Get logger instance with proper configuration | ✅ Stable |
| **`log_performance(func)`** | Decorator for automatic performance logging | ✅ Stable |
| **`StructuredLogger`** | Advanced logging with JSON formatting | ✅ Stable |

**Quick Example:**

```python
from codomyrmex.logging_monitoring import setup_logging, get_logger

# Initialize logging (call once at startup)
setup_logging()

# Get logger for your module
logger = get_logger(__name__)
logger.info("Application started successfully")
```

#### **[🌱 environment_setup](../../src/codomyrmex/environment_setup/API_SPECIFICATION.md)**

**Development environment validation and setup automation**

| Function | Description | Status |
|----------|-------------|--------|
| **`ensure_dependencies_installed()`** | Validate all required dependencies | ✅ Stable |
| **`check_and_setup_env_vars(root_path)`** | Environment variable validation and setup | ✅ Stable |
| **`setup_development_environment()`** | Complete development environment setup | ✅ Stable |
| **`validate_environment()`** | Comprehensive environment health check | ✅ Stable |

**Quick Example:**

```python
from codomyrmex.environment_setup import ensure_dependencies_installed, validate_environment

# Ensure all dependencies are available
ensure_dependencies_installed()

# Validate environment configuration
env_status = validate_environment()
print(f"Environment: {'✅ Good' if env_status['valid'] else '❌ Issues found'}")
```

#### **[🔗 model_context_protocol](../../src/codomyrmex/model_context_protocol/API_SPECIFICATION.md)**

**Standardized AI/LLM communication framework**

| Component | Description | Status |
|-----------|-------------|--------|
| **`MCPToolCall`** | Schema for AI tool invocation requests | ✅ Stable |
| **`MCPToolResult`** | Schema for tool execution responses | ✅ Stable |
| **`validate_mcp_tool()`** | Tool definition validation | ✅ Stable |
| **`MCPServer`** | Server implementation for MCP tools | 🔄 Evolving |

**Quick Example:**

```python
from codomyrmex.model_context_protocol import MCPToolCall, MCPToolResult

# Create a tool call (as would be sent by an AI)
tool_call = MCPToolCall(
    tool_name="generate_code_snippet",
    parameters={"prompt": "Create a hello world function", "language": "python"}
)

# Execute tool and return result
result = MCPToolResult(
    success=True,
    result={"generated_code": "def hello(): print('Hello, World!')"},
    metadata={"execution_time": 0.5}
)
```

### **🤖 AI & Intelligence Modules**

#### **[🤖 agents](../../src/codomyrmex/agents/API_SPECIFICATION.md)**

**AI-powered code generation, refactoring, and analysis**

| Function | Description | Status | Example |
|----------|-------------|--------|---------|
| **`generate_code_snippet()`** | Generate code from natural language | 🔄 Evolving | `generate_code_snippet("Create fibonacci function", "python")` |
| **`refactor_code_snippet()`** | Refactor existing code | 🔄 Evolving | `refactor_code_snippet(code, "optimize", "python")` |
| **`analyze_code_quality()`** | Analyze code quality and suggest improvements | 🔄 Evolving | `analyze_code_quality(code, "python")` |
| **`explain_code()`** | Generate code explanations | 🔄 Evolving | `explain_code(code, "python")` |
| **`generate_documentation()`** | Auto-generate code documentation | 🔄 Evolving | `generate_documentation(code, "python")` |

**Quick Example:**

```python
from codomyrmex.agents import generate_code_snippet

# Generate a complete function
result = generate_code_snippet(
    prompt="Create a secure user authentication system",
    language="python",
    provider="openai"
)

if result["status"] == "success":
    print("🤖 Generated Code:")
    print(result["generated_code"])
    print(f"⏱️ Generated in {result['execution_time']:.2f}s")
```

#### **[📊 data_visualization](../../src/codomyrmex/data_visualization/API_SPECIFICATION.md)**

**Rich plotting and charting capabilities**

| Function | Description | Status | Example |
|----------|-------------|--------|---------|
| **`create_line_plot()`** | Line charts for trends and time series | ✅ Stable | `create_line_plot(x_data, y_data, title="Trends")` |
| **`create_bar_chart()`** | Bar charts for comparisons and rankings | ✅ Stable | `create_bar_chart(categories, values)` |
| **`create_scatter_plot()`** | Scatter plots for correlations | ✅ Stable | `create_scatter_plot(x_data, y_data)` |
| **`create_histogram()`** | Histograms for distributions | ✅ Stable | `create_histogram(data, bins=50)` |
| **`create_heatmap()`** | Heatmaps for 2D data patterns | ✅ Stable | `create_heatmap(data_matrix, x_labels, y_labels)` |
| **`create_advanced_dashboard()`** | Multi-chart interactive dashboards | 🔄 Evolving | `create_advanced_dashboard(datasets, layout)` |

**Quick Example:**

```python
from codomyrmex.data_visualization import create_bar_chart
import numpy as np

# Create sample data
languages = ["Python", "JavaScript", "Java", "C++", "Go"]
popularity = [85, 72, 65, 58, 45]

# Create a beautiful bar chart
create_bar_chart(
    categories=languages,
    values=popularity,
    title="Programming Language Popularity (2024)",
    x_label="Programming Language",
    y_label="Popularity Score",
    output_path="language_popularity.png",
    color_palette="viridis"
)
```

#### **[🔍 static_analysis](../../src/codomyrmex/static_analysis/API_SPECIFICATION.md)**

**Multi-language code quality and security analysis**

| Function | Description | Status | Example |
|----------|-------------|--------|---------|
| **`run_pyrefly_analysis()`** | Python-specific static analysis | 🔄 Evolving | `run_pyrefly_analysis(["src/"], ".")` |
| **`analyze_code_quality()`** | General code quality assessment | 🔄 Evolving | `analyze_code_quality(code, "python")` |
| **`check_security_issues()`** | Security vulnerability scanning | 🔄 Evolving | `check_security_issues(codebase_path)` |
| **`analyze_dependencies()`** | Dependency analysis and suggestions | 🔄 Evolving | `analyze_dependencies("pyproject.toml")` |

**Quick Example:**

```python
from codomyrmex.coding.static_analysis import run_pyrefly_analysis

# Analyze your Python project
analysis = run_pyrefly_analysis(
    target_paths=["src/codomyrmex/"],
    project_root="."
)

print(f"📊 Analysis Results:")
print(f"📁 Files analyzed: {analysis.get('files_analyzed', 0)}")
print(f"🚨 Issues found: {analysis.get('issue_count', 0)}")
print(f"⚡ Performance score: {analysis.get('performance_score', 'N/A')}")
```

#### **[🏃 code](../../src/codomyrmex/coding/README.md)**

**Secure multi-language code execution**

| Function | Description | Status | Example |
|----------|-------------|--------|---------|
| **`execute_code()`** | Execute code in secure Docker containers | ✅ Stable | `execute_code("python", "print('Hello')")` |
| **`validate_language()`** | Check if language is supported | ✅ Stable | `validate_language("python")` |
| **`list_supported_languages()`** | Get all supported languages | ✅ Stable | `list_supported_languages()` |
| **`CodeExecutor`** | Advanced code execution with resource limits | 🔄 Evolving | `CodeExecutor(language="python", timeout=30)` |

**Quick Example:**

```python
from codomyrmex.coding import execute_code

# Execute Python code safely
result = execute_code(
    language="python",
    code="print('Hello from Codomyrmex!')",
    timeout=10  # 10 second timeout
)

print(f"✅ Success: {result['success']}")
print(f"📄 Output: {result['output']}")
print(f"⏱️ Execution time: {result['execution_time']:.3f}s")
```

### **🛡️ Secure Cognitive Modules**

#### **[identity](../../src/codomyrmex/identity/README.md)**

- **`IdentityManager`**: Manage 3-tier personas (Blue/Grey/Black)
- **`verify_persona(tier)`**: Bio-cognitive verification
- **Status**: ✅ Stable

#### **[wallet](../../src/codomyrmex/wallet/README.md)**

- **`WalletCore`**: Self-custody key management
- **`recover_access(shards)`**: Natural Ritual recovery
- **Status**: ✅ Stable

#### **[defense](../../src/codomyrmex/defense/README.md)**

- **`DefenseCore`**: Active defense system
- **`detect_exploit(context)`**: Cognitive exploit detection
- **Status**: ✅ Stable

#### **[market](../../src/codomyrmex/market/README.md)**

- **`MarketCore`**: Anonymous marketplace access
- **`post_demand(item)`**: Reverse auction demand posting
- **Status**: ✅ Stable

#### **[privacy](../../src/codomyrmex/privacy/README.md)**

- **`PrivacyCore`**: Digital exhaust management
- **`scrub_crumbs(data)`**: Metadata sanitization
- **Status**: ✅ Stable

### **Service Modules**

#### **[deployment](../../src/codomyrmex/deployment/API_SPECIFICATION.md)**

- **`trigger_build(target, config)`**: Build automation
- **`synthesize_code_component(template, params)`**: Code generation
- **`BuildOrchestrator`**: Main build class
- **MCP Tools**: `trigger_build`, `synthesize_code_component`
- **Status**: 🔄 Evolving API

#### **[git_operations](../../src/codomyrmex/git_operations/API_SPECIFICATION.md)**

- **`repository_manager`**: Repository management functions
- **`metadata_cli`**: CLI for metadata operations
- **`repo_cli`**: Repository CLI operations
- **Status**: 🔄 Evolving API

#### **[documentation](../../src/codomyrmex/documentation/API_SPECIFICATION.md)**

- **`generate_documentation_website()`**: Website generation
- **`build_static_site()`**: Static site building
- **`DocumentationGenerator`**: Main documentation class
- **Status**: 🔄 Evolving API

## 🔌 MCP Tool Reference

Model Context Protocol tools for AI integration:

### **AI Code Editing Tools**

```typescript
interface GenerateCodeSnippet {
  name: "generate_code_snippet"
  parameters: {
    prompt: string
    language: string
    provider?: "openai" | "anthropic" | "google"
    model_name?: string
  }
  returns: {
    status: "success" | "error"
    generated_code?: string
    explanation?: string
    error_message?: string
  }
}

interface RefactorCodeSnippet {
  name: "refactor_code_snippet"
  parameters: {
    code_snippet: string
    refactoring_instruction: string
    language: string
  }
  returns: {
    status: "success" | "error"
    refactored_code?: string
    explanation?: string
    error_message?: string
  }
}
```

### **Code Execution Tools**

```typescript
interface ExecuteCode {
  name: "execute_code"
  parameters: {
    language: string
    code: string
    timeout?: number
    input_data?: string
  }
  returns: {
    status: "success" | "error"
    stdout?: string
    stderr?: string
    exit_code?: number
    execution_time?: number
    error_message?: string
  }
}
```

### **Build Synthesis Tools**

```typescript
interface TriggerBuild {
  name: "trigger_build"
  parameters: {
    target: string
    config?: object
  }
  returns: {
    status: "success" | "error"
    build_result?: object
    artifacts?: string[]
    error_message?: string
  }
}

interface SynthesizeCodeComponent {
  name: "synthesize_code_component"
  parameters: {
    template: string
    parameters: object
  }
  returns: {
    status: "success" | "error"
    generated_files?: string[]
    component_info?: object
    error_message?: string
  }
}
```

## 🌐 CLI API Reference

Complete command-line interface. See [CLI Reference](cli.md) for full details.

### **Core Commands**

- **`codomyrmex check`**: System health verification
- **`codomyrmex info`**: Project information display
- **`codomyrmex setup`**: Environment configuration

### **AI Commands**

- **`codomyrmex generate`**: AI-powered code generation
- **`codomyrmex refactor`**: AI-assisted code refactoring

### **Analysis Commands**

- **`codomyrmex analyze`**: Static code analysis
- **`codomyrmex visualize`**: Data visualization creation

### **Execution Commands**

- **`codomyrmex execute`**: Safe code execution
- **`codomyrmex test`**: Test execution and validation

## 📊 Usage Patterns

### **Basic Module Usage**

```python
# Foundation setup
from codomyrmex.logging_monitoring import setup_logging, get_logger
from codomyrmex.environment_setup import ensure_dependencies_installed

# Initialize environment
setup_logging()
logger = get_logger(__name__)
ensure_dependencies_installed()

# Use core modules
from codomyrmex.data_visualization import create_line_plot
from codomyrmex.agents import generate_code_snippet

# Create visualization
plot_result = create_line_plot(x_data, y_data, title="My Plot")

# Generate code with AI
code_result = generate_code_snippet("Create a sorting function", "python")
```

### **MCP Integration Pattern**

```python
from codomyrmex.model_context_protocol import MCPToolCall, MCPToolResult

# Create tool call
tool_call = MCPToolCall(
    tool_name="generate_code_snippet",
    parameters={
        "prompt": "Create a data processing function",
        "language": "python",
        "provider": "openai"
    }
)

# Execute tool (handled by MCP framework)
result = mcp_framework.execute_tool(tool_call)
```

### **CLI Integration Pattern**

```bash
# Scripted workflow
codomyrmex generate "data processor" --language python --output processor.py
codomyrmex analyze processor.py --type security --format json --output analysis.json
codomyrmex execute processor.py --input data.txt --output results.txt
```

## 🔍 API Discovery

### **Programmatic Discovery**

```python
from codomyrmex.system_discovery import SystemDiscovery

discovery = SystemDiscovery()
modules = discovery.discover_modules()

for module_name, module_info in modules.items():
    print(f"Module: {module_name}")
    print(f"API Functions: {len(module_info.functions)}")
    print(f"MCP Tools: {len(module_info.mcp_tools)}")
    print(f"Status: {'✅' if module_info.is_importable else '❌'}")
```

### **CLI Discovery**

```bash
# Discover available APIs
codomyrmex discover --detailed --output api-inventory.json

# List available MCP tools
codomyrmex info --modules --format json | jq '.modules[].mcp_tools'

# Show specific module API
codomyrmex docs generate --module agents --format markdown
```

## 📚 Documentation Links

### **Module-Specific API Documentation**

| Module | API Reference | MCP Tools | Status |
|--------|---------------|-----------|--------|
| **agents** | [API Docs](../../src/codomyrmex/agents/API_SPECIFICATION.md) | [MCP Tools](../../src/codomyrmex/agents/MCP_TOOL_SPECIFICATION.md) | 🔄 Evolving |
| **data_visualization** | [API Docs](../../src/codomyrmex/data_visualization/API_SPECIFICATION.md) | None | ✅ Stable |
| **code** | [API Docs](../../src/codomyrmex/coding/README.md) | [MCP Tools](../../src/codomyrmex/coding/README.md#mcp-tools) | 🔄 Evolving |
| **static_analysis** | [API Docs](../../src/codomyrmex/static_analysis/API_SPECIFICATION.md) | [MCP Tools](../../src/codomyrmex/static_analysis/MCP_TOOL_SPECIFICATION.md) | 🔄 Evolving |
| **deployment** | [API Docs](../../src/codomyrmex/deployment/API_SPECIFICATION.md) | [MCP Tools](../../src/codomyrmex/deployment/MCP_TOOL_SPECIFICATION.md) | 🔄 Evolving |
| **pattern_matching** | [API Docs](../../src/codomyrmex/coding/pattern_matching/README.md) | [MCP Tools](../../src/codomyrmex/coding/pattern_matching/MCP_TOOL_SPECIFICATION.md) | 🔄 Evolving |
| **git_operations** | [API Docs](../../src/codomyrmex/git_operations/API_SPECIFICATION.md) | [MCP Tools](../../src/codomyrmex/git_operations/MCP_TOOL_SPECIFICATION.md) | 🔄 Evolving |
| **documentation** | [API Docs](../../src/codomyrmex/documentation/API_SPECIFICATION.md) | None | 🔄 Evolving |
| **logging_monitoring** | [API Docs](../../src/codomyrmex/logging_monitoring/API_SPECIFICATION.md) | None | ✅ Stable |
| **environment_setup** | [API Docs](../../src/codomyrmex/environment_setup/API_SPECIFICATION.md) | None | ✅ Stable |
| **model_context_protocol** | [API Docs](../../src/codomyrmex/model_context_protocol/API_SPECIFICATION.md) | Schema Only | ✅ Stable |

### **Additional References**

- **[CLI Reference](cli.md)**: Complete command-line interface documentation
- **[Module Overview](../modules/overview.md)**: Module system architecture
- **[Module Relationships](../modules/relationships.md)**: Inter-module dependencies
- **[Architecture Guide](../project/architecture.md)**: System design principles

## 🚀 Getting Started with APIs

### **New Users**

1. Start with [Installation Guide](../getting-started/installation.md)
2. Try [Quick Start Examples](../getting-started/quickstart.md)
3. Explore [Module Overview](../modules/overview.md)

### **API Developers**

1. Read [Architecture Guide](../project/architecture.md)
2. Study [Module Relationships](../modules/relationships.md)
3. Follow [Module Creation Tutorial](../getting-started/tutorials/creating-a-module.md)

### **Integration Developers**

1. Review MCP Tool Specifications (each module has `MCP_TOOL_SPECIFICATION.md` in its directory)
2. Examine [CLI Reference](cli.md)
3. Check Usage Examples (each module has `USAGE_EXAMPLES.md` in its directory)

---

**Version**: 0.1.0
**Last Updated**: March 2026
**API Stability**: See individual module documentation for stability guarantees

## Navigation Links

- **Parent**: [Project Overview](../README.md)
- **Module Index**: [All Agents](../../AGENTS.md)
- **Documentation**: [Reference Guides](../../docs/README.md)
- **Home**: [Repository Root](../../README.md)
