# neoCoder Project Structure

## Overview

neoCoder is a scalable AI coding agent with a modular SDK architecture.

## Directory Structure

```
neoCoder/
├── __init__.py              # Package initialization, exports Orchestrator, Extension, WorkingMemory
├── README.md                # Project overview and quick start
├── STRUCTURE.md             # This file
│
├── nca/                     # neoCoder Agent (NCA) - Main agent implementation
│   ├── __init__.py          # Exports NeoCoderAgent, NCAConfig
│   ├── agent.py             # NeoCoderAgent class
│   ├── config.py            # NCAConfig, PRESETS
│   ├── prompts.py           # NCA_SYSTEM_PROMPT, NCA_CODING_PROMPT, etc.
│   └── workflow/            # Workflow management
│       ├── __init__.py
│       ├── manager.py       # WorkflowManager
│       ├── stages.py        # Stage definitions
│       └── display.py       # Display utilities
│
├── sdk/                     # Core SDK components
│   ├── __init__.py
│   ├── orchestrator.py      # Orchestrator, OrchestratorConfig, OrchestratorState
│   │
│   ├── llm/                 # LLM client implementations
│   │   ├── client.py        # ClaudeClient
│   │   ├── base_client.py   # BaseLLMClient
│   │   ├── client_factory.py
│   │   ├── native_client.py
│   │   ├── custom_client.py
│   │   └── output_parser.py
│   │
│   ├── memory/              # Memory management
│   │   ├── working.py       # WorkingMemory
│   │   ├── hierarchical.py  # Hierarchical compression
│   │   └── notes.py         # Note storage
│   │
│   ├── extensions/          # Tool extensions
│   │   ├── base.py          # Extension base class
│   │   ├── bash.py          # BashExtension
│   │   ├── file_edit.py     # FileEditExtension
│   │   ├── file_search.py   # FileSearchExtension
│   │   ├── thinking.py      # ThinkingExtension
│   │   ├── code_review/     # Code review extension
│   │   └── db_context/      # Database context detection & cross-validation
│   │
│   ├── agents/              # Specialized agents
│   │   ├── architect.py     # ArchitectAgent (compression)
│   │   ├── note_taker.py    # NoteTakerAgent
│   │   └── meta_agent.py    # MetaAgent
│   │
│   ├── adaptive_memory/     # Adaptive memory system
│   ├── code_cache/          # Code understanding cache

│   ├── model_loading/       # Model loading utilities
│   ├── monitoring/          # Token tracking and monitoring
│   ├── semantic_compression/# Semantic compression
│   ├── tool_selection/      # Intelligent tool selection
│   └── zenmux_integration/  # ZenMux API integration
│
├── cli/                     # Command-line interface
│   ├── __init__.py
│   └── main.py              # Click-based CLI (entry point)
│
├── mcp/                     # Model Context Protocol server
│   ├── __init__.py
│   └── server.py            # MCP server implementation
│
└── config/                  # Configuration management
    ├── __init__.py
    ├── settings.py          # Settings loader
    └── models.py            # Model definitions
```

## Key Components

### NCA (neoCoder Agent)
- **NeoCoderAgent**: Main agent class with coding-specific features
- **NCAConfig**: Configuration dataclass with presets
- **Prompts**: System prompts for different modes (coding, debug, refactor)

### SDK
- **Orchestrator**: Core agent loop with iterative reasoning
- **Extensions**: Modular tool system (bash, file editing, code search)
- **Memory**: Working memory with hierarchical compression
- **LLM Clients**: Support for Anthropic API and ZenMux

### CLI
- Single task execution
- Interactive mode
- Workflow preset mode
- Rich terminal output

### MCP Server
- Integration with Claude Code
- Tool exposure via Model Context Protocol

## Import Patterns

```python
# Top-level SDK exports
from neoCoder import Orchestrator, Extension, WorkingMemory

# Agent and configuration
from neoCoder.nca import NeoCoderAgent, NCAConfig

# SDK components
from neoCoder.sdk.orchestrator import Orchestrator
from neoCoder.sdk.extensions.base import Extension
from neoCoder.sdk.memory.working import WorkingMemory

# Configuration
from neoCoder.config import load_settings
```

## Usage

```bash
# CLI
python -m neoCoder.cli.main "Create a Python script"
python -m neoCoder.cli.main --mode debug "Fix bug"
python -m neoCoder.cli.main --preset workflow "Build feature"

# MCP Server
python -m neoCoder.mcp.server

# Python API
from neoCoder.nca import NeoCoderAgent, NCAConfig

config = NCAConfig(mode="coding")
agent = NeoCoderAgent(config=config)
result = agent.run("Create a hello world script")
```

## Configuration


Key settings:
- Model selection (Anthropic, ZenMux)
- API keys and endpoints
- Memory thresholds
- Tool timeouts
- Preset configurations
