# Adam v23.5 Migration Plan

Based on the architectural review of the Adam v23.5 repository, this document outlines the strategic roadmap for transitioning from the legacy v21/v22 architectures to the unified v23.5 "Adaptive System".

## Executive Summary

Adam v23.5 represents a shift from a linear, monolithic chatbot to a Neuro-Symbolic Hybrid system. The goal is to eliminate technical debt ("code bloat"), standardize agent communication, and enforce strict type safety and configuration validation.

## 1. Architectural Refactoring

### Current State
*   **Version Fragmentation**: Coexistence of `v20`, `v21`, `v22`, and `v23` logic and configuration files.
*   **Orchestration Ambiguity**: `AgentOrchestrator` mixes direct `await` execution with message broker publishing.
*   **Directory Structure**: Functional components are scattered across root and `core/` subdirectories.

### Target State
*   **Unified Graph Engine**: All reasoning logic consolidated in `core/engine/` (formerly `v23_graph_engine`).
*   **Standardized Communication**: Clear separation between Synchronous (Direct) and Asynchronous (Broker) workflows, managed by the `MetaOrchestrator`.
*   **Clean Directory Structure**:
    ```
    adam/
    ├── core/
    │   ├── engine/           # Graph-based reasoning (v23)
    │   ├── agents/           # Active, standardized agents
    │   ├── system/           # Orchestrators and brokers
    │   └── simulations/      # Quantum & Monte Carlo
    ├── data/
    │   ├── ontology/         # Knowledge graph definitions
    │   └── ingest/           # Universal Ingestor pipeline
    ├── interfaces/           # UI and API layers
    └── archive/              # v20/v21/v22 legacy code
    ```

## 2. Codebase Improvements

### Immediate Actions
1.  **Configuration Validation**: Implement Pydantic models to validate `config.yaml` and `agents.yaml` on startup. Fail fast if configuration is invalid.
2.  **Naming Convention**: Enforce PEP-8 snake_case for all Python files.
    *   *Action*: Rename/consolidate `Core/agents/specialized/MonteCarloRiskAgent.py` -> `monte_carlo_risk_agent.py`.
3.  **Error Handling**: Replace broad `try-except` blocks in `AgentOrchestrator` (specifically around Semantic Kernel initialization) with specific error handling and explicit fallback states.

## 3. Data & Reliability

*   **HITL Gateways**: Enforce "Human-in-the-Loop" validation for high-stakes actions (e.g., trade execution, final rating publication).
*   **Observability**: Integrate OpenTelemetry tracing into the `MetaOrchestrator` to visualize graph traversal and latency.

## 4. Migration Steps

1.  **Phase 1 (Validation)**: Add Pydantic schemas for configuration.
2.  **Phase 2 (Cleanup)**: Remove duplicate agent files and enforce naming conventions.
3.  **Phase 3 (Refactor)**: Update `AgentOrchestrator` to standard communication patterns.
4.  **Phase 4 (Restructure)**: Move files to the new "Clean" directory structure (requires team approval).

---
*Generated by Agent Jules based on Architectural Analysis.*