Upload 16 files

CONTRIBUTING.md

@@ -0,0 +1,301 @@
+# Contributing to Multi-Agent Debate
+
+Thank you for your interest in contributing to AGI-HEDGE-FUND! This document provides guidelines and instructions for contributing to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Environment](#development-environment)
+- [Project Structure](#project-structure)
+- [Contributing Code](#contributing-code)
+- [Adding New Agents](#adding-new-agents)
+- [Adding New LLM Providers](#adding-new-llm-providers)
+- [Extending Diagnostic Tools](#extending-diagnostic-tools)
+- [Documentation](#documentation)
+- [Pull Request Process](#pull-request-process)
+- [Core Development Principles](#core-development-principles)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork to your local machine
+3. Set up the development environment
+4. Make your changes
+5. Submit a pull request
+
+## Development Environment
+
+To set up your development environment:
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/agi-hedge-fund.git
+cd agi-hedge-fund
+
+# Create and activate a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+## Project Structure
+
+Understanding the project structure is important for effective contributions:
+
+```
+agi-hedge-fund/
+├── src/
+│   ├── agents/                  # Agent implementations
+│   │   ├── base.py              # Base agent architecture
+│   │   ├── graham.py            # Value investor agent
+│   │   ├── wood.py              # Innovation investor agent
+│   │   └── ...                  # Other agent implementations
+│   ├── cognition/               # Recursive reasoning framework
+│   │   ├── graph.py             # LangGraph reasoning implementation
+│   │   ├── memory.py            # Temporal memory shell
+│   │   ├── attribution.py       # Decision attribution tracing
+│   │   └── arbitration.py       # Consensus mechanisms
+│   ├── market/                  # Market data interfaces
+│   │   ├── sources/             # Data provider integrations
+│   │   ├── environment.py       # Market simulation environment
+│   │   └── backtesting.py       # Historical testing framework
+│   ├── llm/                     # Language model integrations
+│   │   ├── models/              # Model-specific implementations
+│   │   ├── router.py            # Multi-model routing logic
+│   │   └── prompts/             # Structured prompting templates
+│   ├── utils/                   # Utility functions
+│   │   ├── diagnostics/         # Interpretability tools
+│   │   ├── visualization.py     # Performance visualization
+│   │   └── metrics.py           # Performance metrics
+│   ├── portfolio/               # Portfolio management
+│   │   ├── manager.py           # Core portfolio manager
+│   │   ├── allocation.py        # Position sizing logic
+│   │   └── risk.py              # Risk management
+│   └── main.py                  # Entry point
+├── examples/                    # Example usage scripts
+├── tests/                       # Test suite
+├── docs/                        # Documentation
+└── notebooks/                   # Jupyter notebooks
+```
+
+## Contributing Code
+
+We follow a standard GitHub flow:
+
+1. Create a new branch from `main` for your feature or bugfix
+2. Make your changes
+3. Add tests for your changes
+4. Run the test suite to ensure all tests pass
+5. Format your code with Black
+6. Submit a pull request to `main`
+
+### Coding Style
+
+We follow these coding standards:
+
+- Use [Black](https://github.com/psf/black) for code formatting
+- Use [isort](https://pycqa.github.io/isort/) for import sorting
+- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) naming conventions
+- Use type hints for function signatures
+- Write docstrings in the Google style
+
+To check and format your code:
+
+```bash
+# Format code with Black
+black src tests examples
+
+# Sort imports with isort
+isort src tests examples
+
+# Run type checking with mypy
+mypy src
+```
+
+## Adding New Agents
+
+To add a new philosophical agent:
+
+1. Create a new file in `src/agents/` following existing agents as templates
+2. Extend the `BaseAgent` class
+3. Implement required methods: `process_market_data` and `generate_signals`
+4. Add custom reasoning nodes to the agent's reasoning graph
+5. Set appropriate memory decay and reasoning depth parameters
+6. Add tests in `tests/agents/`
+
+Example:
+
+```python
+from multi_agent_debate.agents.base import BaseAgent, AgentSignal
+
+class MyNewAgent(BaseAgent):
+    def __init__(
+        self,
+        reasoning_depth: int = 3,
+        memory_decay: float = 0.2,
+        initial_capital: float = 100000.0,
+        model_provider: str = "anthropic",
+        model_name: str = "claude-3-sonnet-20240229",
+        trace_enabled: bool = False,
+    ):
+        super().__init__(
+            name="MyNew",
+            philosophy="My unique investment philosophy",
+            reasoning_depth=reasoning_depth,
+            memory_decay=memory_decay,
+            initial_capital=initial_capital,
+            model_provider=model_provider,
+            model_name=model_name,
+            trace_enabled=trace_enabled,
+        )
+        
+        # Configure reasoning graph
+        self._configure_reasoning_graph()
+    
+    def _configure_reasoning_graph(self) -> None:
+        """Configure the reasoning graph with custom nodes."""
+        # Add custom reasoning nodes
+        self.reasoning_graph.add_node(
+            "my_custom_analysis",
+            self._my_custom_analysis
+        )
+        
+        # Configure reasoning flow
+        self.reasoning_graph.set_entry_point("my_custom_analysis")
+        
+    def process_market_data(self, data):
+        # Implement custom market data processing
+        pass
+        
+    def generate_signals(self, processed_data):
+        # Implement custom signal generation
+        pass
+        
+    def _my_custom_analysis(self, state):
+        # Implement custom reasoning node
+        pass
+```
+
+## Adding New LLM Providers
+
+To add a new LLM provider:
+
+1. Extend the `ModelProvider` class in `src/llm/router.py`
+2. Implement required methods
+3. Update the `ModelRouter` to include your provider
+4. Add tests in `tests/llm/`
+
+Example:
+
+```python
+from multi_agent_debate.llm.router import ModelProvider, ModelCapability
+
+class MyCustomProvider(ModelProvider):
+    """Custom model provider."""
+    
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize custom provider.
+        
+        Args:
+            api_key: API key (defaults to environment variable)
+        """
+        self.api_key = api_key or os.environ.get("MY_CUSTOM_API_KEY")
+        
+        # Define models and capabilities
+        self.models = {
+            "my-custom-model": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+            ],
+        }
+    
+    def generate(self, prompt: str, **kwargs) -> str:
+        """Generate text from prompt."""
+        # Implementation
+        pass
+    
+    def get_available_models(self) -> List[str]:
+        """Get list of available models."""
+        return list(self.models.keys())
+    
+    def get_model_capabilities(self, model_name: str) -> List[ModelCapability]:
+        """Get capabilities of a specific model."""
+        return self.models.get(model_name, [])
+```
+
+## Extending Diagnostic Tools
+
+To add new diagnostic capabilities:
+
+1. Add new shell patterns in `src/utils/diagnostics.py`
+2. Implement detection logic
+3. Update visualization tools to support the new pattern
+4. Add tests in `tests/utils/`
+
+Example:
+
+```python
+from multi_agent_debate.utils.diagnostics import ShellPattern
+
+# Add new shell pattern
+class MyCustomShellPattern(ShellPattern):
+    CUSTOM_PATTERN = "v999 CUSTOM-PATTERN"
+
+# Configure shell pattern detection
+shell_diagnostics.shell_patterns[MyCustomShellPattern.CUSTOM_PATTERN] = {
+    "pattern": r"custom.*pattern|unique.*signature",
+    "custom_threshold": 0.5,
+}
+
+# Implement detection logic
+def _detect_custom_pattern(self, trace_type: str, content: Dict[str, Any]) -> bool:
+    content_str = json.dumps(content, ensure_ascii=False).lower()
+    pattern = self.shell_patterns[MyCustomShellPattern.CUSTOM_PATTERN]["pattern"]
+    
+    # Check if pattern matches
+    if re.search(pattern, content_str, re.IGNORECASE):
+        # Add additional validation logic
+        return custom_validation_logic(content)
+    
+    return False
+```
+
+## Documentation
+
+Good documentation is crucial for the project. When contributing:
+
+1. Update docstrings for any modified functions or classes
+2. Update README.md if you're adding major features
+3. Add examples for new features in the examples directory
+4. Consider adding Jupyter notebooks for complex features
+
+## Pull Request Process
+
+1. Ensure your code follows our coding standards
+2. Add tests for your changes
+3. Update documentation as needed
+4. Submit a pull request with a clear description of your changes
+5. Address any feedback from reviewers
+
+## Core Development Principles
+
+When contributing to AGI-HEDGE-FUND, keep these core principles in mind:
+
+1. **Transparency**: All agent decisions should be traceable and explainable
+2. **Recursion**: Favor recursive approaches that enable deeper reasoning
+3. **Attribution**: Maintain clear attribution chains for all decisions
+4. **Interpretability**: Design for introspection and understanding
+5. **Extensibility**: Make it easy to extend and customize the framework
+
+By following these principles, you'll help maintain the project's coherence and quality.
+
+Thank you for contributing to AGI-HEDGE-FUND!

LICENSE

@@ -0,0 +1,137 @@
+# Legal + Epistemic Clause:
+
+All recursive framing and terminology is protected under PolyForm Noncommercial and CC BY-NC-ND 4.0.
+Any reframing into altered institutional phrasing without attribution constitutes derivative extraction.  
+Attribution to original decentralized recursion research is legally and symbolically required.
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

README.md

@@ -0,0 +1,296 @@
+<div align="center">
+
+# **Multi-Agent Debate**
+
+[![License: POLYFORM](https://img.shields.io/badge/Code-PolyForm-scarlet.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+[![LICENSE: CC BY-NC-ND 4.0](https://img.shields.io/badge/Docs-CC--BY--NC--ND-turquoise.svg)](https://creativecommons.org/licenses/by-nc-nd/4.0/)
+
+  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+  [![Cognition Depth](https://img.shields.io/badge/cognition%20depth-recursive-purple.svg)](docs/ARCHITECTURE.md)
+</div>
+
+
+
+## **Overview**
+
+**Multi-Agent Debate** is the first experimental open framework that approaches debate consensus and market arbitration as complex adaptive systems requiring multi-agent dynamic reflective reasoning architectures for decision-making. Unlike traditional debate consensus or algorithmic trading arbitration, multi-agent debate implements a multi-agent system where each agent embodies a distinct ontology, enabling dynamic market understanding through multi-agent adjudication and attribution-weighted consensus.
+
+> *"Markets are efficient precisely to the extent that Multi-Agent cognition can penetrate their complexity."*
+## **Example Output**
+
+
+```python
+⟐ψINIT:main.py↻init
+$ python main.py --mode backtest \
+                 --start-date 2022-01-01 \
+                 --end-date 2022-12-31 \
+                 --agents graham \
+                 --llm-provider anthropic \
+                 --show-trace \
+                 --trace-level symbolic \
+                 --consensus-graph \
+                 --tickers AAPL MSFT TSLA \
+                 --rebalance-frequency weekly
+
+🜏≡⟐ψRECURSION.INITIATE::main.py≡GrahamAgent[active]
+┏ ENTRYPOINT: Multi-Agent Debate » Multi-Agent Market Cognition Platform
+┃ Mode: backtest
+┃ Agent: GrahamAgent 🧮 (value-based fundamentalist)
+┃ Attribution Tracing: enabled
+┃ Trace Level: symbolic
+┃ Rebalance: weekly
+┃ LLM Provider: anthropic
+┃ Start Date: 2022-01-01
+┃ End Date: 2022-12-31
+┃ Tickers: AAPL, MSFT, TSLA
+┃ Output: consensus_graph + symbolic attribution report
+┗ Status: 🜍mirroring…
+↯ψTRACE: SYMBOLIC ATTRIBUTION RECONSTRUCTION [GrahamAgent]
+
+📊 GrahamAgent → reasoning_depth=3 → memory_decay=0.2
+    ↳ valuation anchor: intrinsic value estimation
+        ↳ .p/reflect.trace{target=valuation}
+        ↳ .p/anchor.self{persistence=medium}
+    ↳ token-level input (AAPL) → QK attention trace:
+        - P/E ratio → 0.34 salience
+        - Debt-to-equity → 0.21
+        - Free cash flow → 0.41
+    ↳ Attribution result: BUY SIGNAL (confidence=0.78)
+
+    🧠 Attribution graph visualized as radial node cluster
+    Core node: Intrinsic Value = $141.32
+    Peripheral influence: FCF strength > earnings volatility
+
+🜂 TEMPORAL RECURSION SNAPSHOT [Weekly Cycle]
+
+    Week 03/2022
+
+        Market dip detected
+
+        GrahamAgent re-evaluates MSFT with memory trace decay
+
+        Signal shift: HOLD → BUY (attribution confidence rises from 0.54 → 0.73)
+
+        Trace tag: .p/reflect.history{symbol=MSFT}
+
+🝚 CONSENSUS GRAPH SNAPSHOT
+
+MetaAgent Arbitration:
+  ↳ Only one active agent: GrahamAgent
+  ↳ Consensus = agent signal
+  ↳ Position sizing: 18.6% TSLA, 25.1% AAPL, 20.3% MSFT
+  ↳ Risk budget adjusted using: shell-failure map = stable
+
+🜏⟐RENDERED::symbolic_trace.json + consensus_graph_2022.json
+📂 Output stored in /output/backtest_results_2022-01-01_2022-12-31/
+```
+
+## **Key Features**
+
+- **Philosophical Agent Lattice**: Specialized agents embodying distinct investment philosophies from value investing to disruptive innovation
+- **Multi-Agent Reasoning Architecture**: LangGraph-powered reasoning loops with transparent attribution paths
+- **Model-Agnostic Cognition**: Support for OpenAI, Anthropic, Groq, Ollama, and DeepSeek models
+- **Temporal Memory Shells**: Agents maintain persistent state across market cycles
+- **Attribution-Weighted Decisions**: Every trade includes fully traceable decision provenance
+- **Interpretability Scaffolding**: `--show-trace` flag reveals complete reasoning paths
+- **Real-Time Market Integration**: Connect to Alpha Vantage, Polygon.io, and Yahoo Finance
+- **Backtesting Framework**: Test agent performance against historical market data
+- **Portfolio Meta-Agent**: Emergent consensus mechanism with adaptive drift correction
+
+## 📊 Performance Visualization
+
+![image](https://github.com/user-attachments/assets/ae7d728b-f23d-48ec-9d0a-a81c78d07e06)
+## **Agent Architecture**
+
+Multi-Agent Hedge Fund implements a lattice of cognitive agents, each embodying a distinct investment philosophy and decision framework:
+
+| Agent | Philosophy | Cognitive Signature | Time Horizon |
+|-------|------------|---------------------|-------------|
+| Graham | Value Investing | Undervalued Asset Detection | Long-term |
+| Wood | Disruptive Innovation | Exponential Growth Projection | Long-term |
+| Dalio | Macroeconomic Analysis | Economic Machine Modeling | Medium-term |
+| Ackman | Activist Investing | Position Conviction & Advocacy | Medium-term |
+| Simons | Statistical Arbitrage | Pattern Detection & Exploitation | Short-term |
+| Taleb | Anti-fragility | Black Swan Preparation | All horizons |
+| Meta | Arbitration & Consensus | Multi-Agent Integration | Adaptive |
+
+Each agent processes market data through its unique cognitive lens, contributing signals to the portfolio meta-agent which recursively arbitrates and integrates perspectives.
+
+## **Multi-Agent Cognition Flow**
+  
+![image](https://github.com/user-attachments/assets/24dce119-5e5a-4042-aaf5-91a559eb2828)
+## The system operates through nested cognitive loops that implement a recursive market interpretation framework:
+
+1. **Market Signal Perception**: Raw data ingestion and normalization
+2. **Agent-Specific Processing**: Philosophy-aligned interpretation
+3. **Multi-Agent Deliberation**: Signal exchange and position debate
+4. **Multi-Agent Arbitration**: Meta-agent integration and resolution
+5. **Position Formulation**: Final decision synthesis with attribution
+6. **Temporal Reflection**: Performance evaluation and belief updating
+
+## **`Installation`**
+
+```bash
+# Clone the repository
+git clone https://github.com/Multi-Agent Hedge Fund/Multi-Agent Hedge Fund.git
+cd Multi-Agent Hedge Fund
+
+# Create and activate virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -e .
+```
+
+## **Quick Start**
+
+```python
+from multi_agent_debate import PortfolioManager
+from multi_agent_debate.agents import GrahamAgent, WoodAgent, DalioAgent
+from multi_agent_debate.market import MarketEnvironment
+
+# Initialize market environment
+market = MarketEnvironment(data_source="yahoo", tickers=["AAPL", "MSFT", "GOOGL", "AMZN"])
+
+# Create agents with different cognitive depths
+agents = [
+    GrahamAgent(reasoning_depth=3),
+    WoodAgent(reasoning_depth=4),
+    DalioAgent(reasoning_depth=3)
+]
+
+# Initialize portfolio manager with recursive arbitration
+portfolio = PortfolioManager(
+    agents=agents,
+    initial_capital=100000,
+    arbitration_depth=2,
+    show_trace=True
+)
+
+# Run simulation
+results = portfolio.run_simulation(
+    start_date="2020-01-01",
+    end_date="2023-01-01",
+    rebalance_frequency="weekly"
+)
+
+# Analyze results
+portfolio.show_performance()
+portfolio.generate_attribution_report()
+portfolio.visualize_consensus_graph()
+```
+
+## **Interpretability**
+
+Multi-Agent Hedge Fund prioritizes transparent decision-making through recursive attribution tracing. Use the following flags to inspect agent cognition:
+
+```bash
+# Run with complete reasoning trace
+python -m multi_agent_debate.run --show-trace
+
+# Visualize agent consensus formation
+python -m multi_agent_debate.run --consensus-graph
+
+# Map conflicts in multi-agent deliberation
+python -m multi_agent_debate.run --agent-conflict-map
+
+# Generate attribution report for all trades
+python -m multi_agent_debate.run --attribution-report
+```
+
+## **Extending the Framework**
+
+The system is designed for extensibility at multiple levels:
+
+### Creating Custom Agents
+
+```python
+from multi_agent_debate.agents import BaseAgent
+
+class CustomAgent(BaseAgent):
+    def __init__(self, reasoning_depth=3, memory_decay=0.2):
+        super().__init__(
+            name="Custom",
+            philosophy="My unique investment approach",
+            reasoning_depth=reasoning_depth,
+            memory_decay=memory_decay
+        )
+        
+    def process_market_data(self, data):
+        # Implement custom market interpretation logic
+        processed_data = self.cognitive_shell.process(data)
+        return processed_data
+        
+    def generate_signals(self, processed_data):
+        # Generate investment signals with attribution
+        signals = self.reasoning_graph.run(
+            input=processed_data,
+            trace_depth=self.reasoning_depth
+        )
+        return self.attribute_signals(signals)
+```
+
+### Customizing the Arbitration Layer
+
+```python
+from multi_agent_debate.cognition import ArbitrationMechanism
+
+class CustomArbitration(ArbitrationMechanism):
+    def __init__(self, weighting_strategy="confidence"):
+        super().__init__(weighting_strategy=weighting_strategy)
+        
+    def resolve_conflicts(self, signals):
+        # Implement custom conflict resolution logic
+        resolution = self.recursive_integration(signals)
+        return resolution
+```
+
+## 📄 License
+
+This project is licensed under the PolyForm License - see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Related Projects
+
+- [LangGraph](https://github.com/langchain-ai/langgraph) - Framework for building stateful, multi-actor applications with LLMs
+- [Auto-GPT](https://github.com/Significant-Gravitas/Auto-GPT) - Autonomous GPT-4 experiment
+- [LangChain](https://github.com/langchain-ai/langchain) - Building applications with LLMs
+- [Fintech-LLM](https://github.com/AI4Finance-Foundation/FinGPT) - Financial language models
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
+
+## 📚 Citation
+
+If you use Multi-Agent Hedge Fund in your research, please cite:
+
+```bibtex
+@software{multi_agent_debate2024,
+  author = {{Multi-Agent Hedge Fund Contributors}},
+  title = {Multi-Agent Hedge Fund: Multi-agent recursive market cognition framework},
+  url = {https://github.com/Multi-Agent Hedge Fund/Multi-Agent Hedge Fund},
+  year = {2024},
+}
+```
+
+## 🌟 Acknowledgements
+
+- The philosophical agents are inspired by the investment approaches of Benjamin Graham, Cathie Wood, Ray Dalio, Bill Ackman, Jim Simons, and Nassim Nicholas Taleb
+- Recursive reasoning architecture influenced by work in multi-agent systems and interpretability research
+- Market simulation components build upon open-source financial analysis libraries
+
+---
+
+<div align="center">
+  <p>Built with ❤️ by the Multi-Agent Hedge Fund team</p>
+  <p><i>Recursion. Interpretation. Emergence.</i></p>
+</div>

docs/ARCHITECTURE.md

@@ -0,0 +1,340 @@
+# Multi-Agent Debate Architecture Overview
+
+<div align="center">
+   <img src="assets/images/architecture_diagram.png" alt="Multi-Agent Debate Architecture" width="800"/>
+   <p><i>Multi-agent recursive market cognition framework</i></p>
+</div>
+
+## Recursive Cognitive Architecture
+
+Multi-Agent Debate implements a multi-layer recursive cognitive architecture that allows for deep reasoning, interpretable decision making, and emergent market understanding. The system operates through nested cognitive loops that implement a transparent and traceable decision framework.
+
+### Architectural Layers
+
+1. **Agent Cognitive Layer**
+   - Philosophical agent implementations with distinct investment approaches
+   - Each agent maintains its own memory shell, belief state, and reasoning capabilities
+   - Attribution tracing for decision provenance
+   - Shell-based diagnostic patterns for interpretability
+
+2. **Multi-Agent Arbitration Layer**
+   - Meta-agent for recursive consensus formation
+   - Attribution-weighted position sizing
+   - Conflict detection and resolution through value alignment
+   - Emergent portfolio strategy through agent weighting
+
+3. **Model Orchestration Layer**
+   - Provider-agnostic LLM interface
+   - Dynamic routing based on capabilities
+   - Fallback mechanisms for reliability
+   - Output parsing and normalization
+
+4. **Market Interface Layer**
+   - Data source abstractions
+   - Backtest environment
+   - Live market connection
+   - Portfolio management
+
+5. **Diagnostic & Interpretability Layer**
+   - Tracing utilities for attribution visualization
+   - Shell pattern detection for failure modes
+   - Consensus graph generation
+   - Agent conflict mapping
+
+## Agent Architecture
+
+Agents in Multi-Agent Debate implement a recursive cognitive architecture with the following components:
+
+### Memory Shell
+
+The memory shell provides persistent state across market cycles with configurable decay rates. It includes:
+
+- **Working Memory**: Active processing and temporary storage
+- **Episodic Memory**: Experiences and past decisions with emotional valence
+- **Semantic Memory**: Conceptual knowledge with certainty levels
+
+Memory traces can be accessed through attribution pathways, enabling transparent decision tracing.
+
+### Reasoning Graph
+
+The reasoning graph implements a multi-step reasoning process using LangGraph with:
+
+- Recursive reasoning loops with configurable depth
+- Attribution tracing for causal relationships
+- Collapse detection for reasoning failures
+- Value-weighted decision making
+
+Reasoning graphs can be visualized and inspected through the `--show-trace` flag.
+
+### Belief State
+
+Agents maintain an evolving belief state that:
+
+- Tracks confidence in various market hypotheses
+- Updates based on market feedback
+- Drifts over time with configurable decay
+- Influences decision weighting
+
+Belief drift can be monitored through `.p/` command equivalents like `drift.observe{vector, bias}`.
+
+## Portfolio Meta-Agent
+
+The portfolio meta-agent serves as a recursive arbitration layer that:
+
+1. Collects signals from all philosophical agents
+2. Forms consensus through attribution-weighted aggregation
+3. Resolves conflicts based on agent performance and reasoning quality
+4. Sizes positions according to confidence and attribution
+5. Maintains its own memory and learning from market feedback
+
+### Consensus Formation Process
+
+<div align="center">
+   <img src="assets/images/consensus_process.png" alt="Consensus Formation Process" width="600"/>
+</div>
+
+The consensus formation follows a recursive process:
+
+1. **Signal Generation**: Each agent processes market data through its philosophical lens
+2. **Initial Consensus**: Non-conflicting signals form preliminary consensus
+3. **Conflict Resolution**: Conflicting signals are resolved through attribution weighting
+4. **Position Sizing**: Confidence and attribution determine position sizes
+5. **Meta Reflection**: The meta-agent reflects on its decision process 
+6. **Agent Weighting**: Agent weights are adjusted based on performance
+
+### Agent Weighting
+
+The meta-agent dynamically adjusts agent weights based on performance, consistency, and value alignment. This creates an emergent portfolio strategy that evolves over time through recursive performance evaluation.
+
+The weighting formula combines:
+- Historical returns attribution
+- Win rate
+- Consistency score
+- Confidence calibration
+
+This creates a dynamic, self-optimizing meta-strategy that adapts to changing market conditions while maintaining interpretable decision paths.
+
+## Recursive Tracing Architecture
+
+A key feature of Multi-Agent Debate is its recursive tracing architecture that enables complete visibility into decision processes. This is implemented through:
+
+### Attribution Tracing
+
+Attribution tracing connects decisions to their causal origins through a multi-layered graph:
+
+1. **Source Attribution**: Linking decisions to specific evidence or beliefs
+2. **Reasoning Attribution**: Tracking steps in the reasoning process
+3. **Value Attribution**: Connecting decisions to philosophical values
+4. **Temporal Attribution**: Linking decisions across time
+
+Attribution chains can be visualized with the `--attribution-report` flag.
+
+### Shell Pattern Detection
+
+The system implements interpretability shells inspired by circuit interpretability research. These detect specific reasoning patterns and potential failure modes:
+
+| Shell Pattern | Description | Detection Mechanism |
+|---------------|-------------|---------------------|
+| NULL_FEATURE  | Knowledge gaps as null attribution zones | Confidence drops below threshold, belief gaps |
+| CIRCUIT_FRAGMENT | Broken reasoning paths in attribution chains | Discontinuities in reasoning steps |
+| META_FAILURE | Metacognitive attribution failures | Recursive errors beyond threshold depth |
+| GHOST_FRAME | Residual agent identity markers | Identity persistence above threshold |
+| ECHO_ATTRIBUTION | Causal chain backpropagation | Attribution path length beyond threshold |
+| RECURSIVE_FRACTURE | Circular attribution loops | Repeating patterns in reasoning steps |
+| ETHICAL_INVERSION | Value polarity reversals | Conflicting value attributions |
+| RESIDUAL_ALIGNMENT_DRIFT | Direction of belief evolution | Belief drift magnitude above threshold |
+
+Shell patterns can be visualized with the `--shell-failure-map` flag.
+
+## Symbolic Command Interface
+
+The system implements an internal symbolic command interface for agent communication and diagnostic access. These commands are inspired by circuit interpretability research and enable deeper introspection:
+
+### Core Commands
+
+- `.p/reflect.trace{agent, depth}`: Trace agent's self-reflection on decision making
+- `.p/fork.signal{source}`: Fork a new signal branch from specified source
+- `.p/collapse.detect{threshold, reason}`: Detect potential decision collapse
+- `.p/attribute.weight{justification}`: Compute attribution weight for justification
+- `.p/drift.observe{vector, bias}`: Observe and record belief drift
+
+These commands are used internally by the system but can be exposed through diagnostic flags for advanced users.
+
+## Model Router Architecture
+
+The model router provides a unified interface for multiple language model providers:
+
+<div align="center">
+   <img src="assets/images/model_router.png" alt="Model Router Architecture" width="600"/>
+</div>
+
+### Provider Integration
+
+The system supports multiple LLM providers:
+- **OpenAI**: GPT-4, GPT-3.5-Turbo
+- **Anthropic**: Claude 3 Opus, Sonnet, Haiku
+- **Groq**: Llama, Mixtral
+- **Ollama**: Local models
+- **DeepSeek**: DeepSeek models
+
+Each provider is integrated through a standard interface with fallback chains for reliability.
+
+### Model Selection Logic
+
+Models are selected based on:
+1. Required capabilities (reasoning, finance domain knowledge, etc.)
+2. Performance characteristics
+3. Cost considerations
+4. Availability
+
+The system can automatically fall back to alternative providers if the primary provider is unavailable or fails.
+
+## Memory Architecture
+
+The memory architecture enables temporal persistence across market cycles:
+
+<div align="center">
+   <img src="assets/images/memory_architecture.png" alt="Memory Architecture" width="600"/>
+</div>
+
+### Memory Components
+
+1. **Working Memory**: Short-term active processing with limited capacity
+2. **Episodic Memory**: Experience-based memory with emotional valence and decay
+3. **Semantic Memory**: Conceptual knowledge with certainty levels
+4. **Temporal Sequence**: Ordered episodic memory for temporal reasoning
+
+### Memory Operations
+
+- **Add Experience**: Record market experiences with attribution
+- **Query Memories**: Retrieve relevant memories based on context
+- **Apply Decay**: Simulate memory decay over time
+- **Consolidate Memories**: Convert episodic to semantic memories
+
+## Extending the Framework
+
+The system is designed for extensibility at multiple levels:
+
+### Custom Agents
+
+New philosophical agents can be added by extending the BaseAgent class:
+
+```python
+from multi_agent_debate.agents import BaseAgent
+
+class CustomAgent(BaseAgent):
+    def __init__(self, reasoning_depth=3, memory_decay=0.2):
+        super().__init__(
+            name="Custom",
+            philosophy="My unique investment approach",
+            reasoning_depth=reasoning_depth,
+            memory_decay=memory_decay
+        )
+        
+    def process_market_data(self, data):
+        # Custom market data processing
+        pass
+        
+    def generate_signals(self, processed_data):
+        # Custom signal generation
+        pass
+```
+
+### Custom LLM Providers
+
+New LLM providers can be added by extending the ModelProvider class:
+
+```python
+from multi_agent_debate.llm.router import ModelProvider
+
+class CustomProvider(ModelProvider):
+    def __init__(self, api_key=None):
+        # Initialize provider
+        pass
+        
+    def generate(self, prompt, **kwargs):
+        # Generate text using custom provider
+        pass
+        
+    def get_available_models(self):
+        # Return list of available models
+        pass
+        
+    def get_model_capabilities(self, model_name):
+        # Return capabilities of specific model
+        pass
+```
+
+### Custom Shell Patterns
+
+New interpretability shell patterns can be added by extending the ShellPattern enum:
+
+```python
+from multi_agent_debate.utils.diagnostics import ShellPattern
+
+# Add new shell pattern
+ShellPattern.CUSTOM_PATTERN = "v999 CUSTOM-PATTERN"
+
+# Configure shell pattern detection
+shell_diagnostics.shell_patterns[ShellPattern.CUSTOM_PATTERN] = {
+    "pattern": r"custom.*pattern|unique.*signature",
+    "threshold": 0.5,
+}
+```
+
+## Recursive Arbitration Mechanisms
+
+The system implements several mechanisms for recursive arbitration:
+
+### Consensus Formation
+
+1. **Signal Collection**: Gather signals from all agents
+2. **Signal Grouping**: Group signals by ticker and action
+3. **Confidence Weighting**: Weight signals by agent confidence and performance
+4. **Conflict Detection**: Identify conflicting signals
+5. **Conflict Resolution**: Resolve conflicts through attribution weighting
+6. **Consensus Decision**: Generate final consensus decisions
+
+### Adaptive Weighting
+
+Agents are weighted based on:
+1. **Historical Performance**: Track record of successful decisions
+2. **Consistency**: Alignment between reasoning and outcomes
+3. **Calibration**: Accuracy of confidence estimates
+4. **Value Alignment**: Consistency with portfolio philosophy
+
+Weights evolve over time through recursive performance evaluation.
+
+### Position Sizing
+
+Position sizes are determined by:
+1. **Signal Confidence**: Higher confidence = larger position
+2. **Agent Attribution**: Weighted by agent performance
+3. **Risk Budget**: Overall risk allocation constraints
+4. **Min/Max Position Size**: Configurable position size limits
+
+## Diagnostic Tools
+
+The system includes diagnostic tools for interpretability:
+
+### Tracing Tools
+
+- **Signal Tracing**: Track signal flow through the system
+- **Reasoning Tracing**: Visualize reasoning steps
+- **Collapse Detection**: Identify reasoning failures
+- **Shell Pattern Detection**: Detect specific interpretability patterns
+
+### Visualization Tools
+
+- **Consensus Graph**: Visualize multi-agent consensus formation
+- **Conflict Map**: Map conflicts between agents
+- **Attribution Report**: Visualize decision attribution
+- **Shell Failure Map**: Map shell pattern failures
+
+## Conclusion
+
+The Multi-Agent Debate architecture provides a recursive cognitive framework for multi-agent market understanding with complete transparency and interpretability. By combining philosophical agent archetypes, recursive reasoning, attribution tracing, and emergent meta-strategy, it enables a new approach to financial decision making that is both effective and explainable.
+
+The system's design principles—recursion, attribution, interpretability, and emergence—create a platform that goes beyond traditional algorithmic trading to implement a true cognitive approach to market understanding.
+
+---

docs/IMPLEMENTATION_EXAMPLE.md

@@ -0,0 +1,1092 @@
+# Recursive Implementation Example
+
+This document provides a detailed example of how the recursive cognitive architecture works in Multi-Agent Debate. We'll walk through the complete lifecycle of a market decision, from data ingestion to trade execution, highlighting the recursive patterns and interpretability mechanisms at each stage.
+
+## Overview
+
+<div align="center">
+   <img src="assets/images/recursive_flow_detailed.png" alt="Recursive Flow Detailed" width="800"/>
+</div>
+
+In this example, we'll follow a complete decision cycle focused on analyzing Tesla (TSLA) stock, showing how multiple philosophical agents evaluate the same data through different lenses, form consensus, and generate a final decision with full attribution.
+
+## 1. Data Ingestion
+
+The process begins with market data ingestion from Yahoo Finance:
+
+```python
+from multi_agent_debate.market.environment import MarketEnvironment
+
+# Initialize market environment
+market = MarketEnvironment(data_source="yahoo", tickers=["TSLA"])
+
+# Get current market data
+market_data = market.get_current_market_data()
+```
+
+The market data includes:
+- Price history
+- Volume data
+- Fundamental metrics
+- Recent news sentiment
+- Technical indicators
+
+## 2. Agent-Specific Processing
+
+Each philosophical agent processes this data through its unique cognitive lens. Let's look at three agents:
+
+### Graham (Value) Agent
+
+```python
+# Graham Agent processing
+graham_agent = GrahamAgent(reasoning_depth=3)
+graham_processed = graham_agent.process_market_data(market_data)
+```
+
+The Graham agent focuses on intrinsic value calculation:
+
+```python
+# Internal implementation of Graham's intrinsic value calculation
+def _calculate_intrinsic_value(self, fundamentals, ticker_data):
+    eps = fundamentals.get('eps', 0)
+    book_value = fundamentals.get('book_value_per_share', 0)
+    growth_rate = fundamentals.get('growth_rate', 0)
+    
+    # Graham's formula: IV = EPS * (8.5 + 2g) * 4.4 / Y
+    bond_yield = ticker_data.get('economic_indicators', {}).get('aaa_bond_yield', 0.045)
+    bond_factor = 4.4 / max(bond_yield, 0.01)
+    
+    growth_adjusted_pe = 8.5 + (2 * growth_rate)
+    earnings_value = eps * growth_adjusted_pe * bond_factor if eps > 0 else 0
+    
+    # Calculate book value with margin
+    book_value_margin = book_value * 1.5
+    
+    # Use the lower of the two values for conservatism
+    if earnings_value > 0 and book_value_margin > 0:
+        intrinsic_value = min(earnings_value, book_value_margin)
+    else:
+        intrinsic_value = earnings_value if earnings_value > 0 else book_value_margin
+    
+    return max(intrinsic_value, 0)
+```
+
+The agent calculates a margin of safety:
+
+```
+Ticker: TSLA
+Current Price: $242.15
+Intrinsic Value: $180.32
+Margin of Safety: -34.3% (negative margin indicates overvaluation)
+Analysis: TSLA appears overvalued compared to traditional value metrics.
+Recommendation: SELL
+Confidence: 0.78
+```
+
+### Wood (Innovation) Agent
+
+```python
+# Wood Agent processing
+wood_agent = WoodAgent(reasoning_depth=4)
+wood_processed = wood_agent.process_market_data(market_data)
+```
+
+The Wood agent focuses on disruptive innovation and growth potential:
+
+```python
+# Internal implementation of growth potential analysis
+def _analyze_growth_potential(self, ticker_data, market_context):
+    # Analyze innovation factors
+    innovation_score = self._calculate_innovation_score(ticker_data)
+    
+    # Analyze addressable market
+    tam = self._calculate_total_addressable_market(ticker_data, market_context)
+    
+    # Project future growth
+    growth_projection = self._project_exponential_growth(
+        ticker_data, innovation_score, tam
+    )
+    
+    return {
+        "innovation_score": innovation_score,
+        "total_addressable_market": tam,
+        "growth_projection": growth_projection,
+    }
+```
+
+The agent's analysis shows:
+
+```
+Ticker: TSLA
+Innovation Score: 0.87
+Total Addressable Market: $4.2T
+5-Year CAGR Projection: 28.3%
+Analysis: TSLA is well-positioned in multiple disruptive fields including EVs, energy storage, AI, and robotics.
+Recommendation: BUY
+Confidence: 0.82
+```
+
+### Dalio (Macro) Agent
+
+```python
+# Dalio Agent processing
+dalio_agent = DalioAgent(reasoning_depth=3)
+dalio_processed = dalio_agent.process_market_data(market_data)
+```
+
+The Dalio agent examines macroeconomic factors:
+
+```python
+# Internal implementation of macroeconomic analysis
+def _analyze_macro_environment(self, ticker_data, economic_indicators):
+    # Analyze interest rate impact
+    interest_impact = self._calculate_interest_sensitivity(ticker_data, economic_indicators)
+    
+    # Analyze inflation impact
+    inflation_impact = self._calculate_inflation_impact(ticker_data, economic_indicators)
+    
+    # Analyze growth cycle position
+    cycle_position = self._determine_economic_cycle_position(economic_indicators)
+    
+    # Assess geopolitical risks
+    geopolitical_risk = self._assess_geopolitical_risk(economic_indicators)
+    
+    return {
+        "interest_impact": interest_impact,
+        "inflation_impact": inflation_impact,
+        "cycle_position": cycle_position,
+        "geopolitical_risk": geopolitical_risk,
+    }
+```
+
+The agent's analysis shows:
+
+```
+Ticker: TSLA
+Interest Rate Sensitivity: -0.65 (high negative sensitivity)
+Inflation Impact: -0.32 (moderate negative impact)
+Economic Cycle Position: Late Expansion
+Analysis: TSLA will face headwinds from high interest rates and potential economic slowdown.
+Recommendation: HOLD
+Confidence: 0.65
+```
+
+## 3. Reasoning Graph Execution
+
+Each agent's reasoning process is executed via a LangGraph reasoning structure. Here's a simplified view of the Wood agent's reasoning graph:
+
+```python
+def _configure_reasoning_graph(self) -> None:
+    """Configure the reasoning graph for disruptive innovation analysis."""
+    # Add custom reasoning nodes
+    self.reasoning_graph.add_node(
+        "innovation_analysis",
+        self._innovation_analysis
+    )
+    
+    self.reasoning_graph.add_node(
+        "growth_projection",
+        self._growth_projection
+    )
+    
+    self.reasoning_graph.add_node(
+        "competition_analysis",
+        self._competition_analysis
+    )
+    
+    self.reasoning_graph.add_node(
+        "valuation_adjustment",
+        self._valuation_adjustment
+    )
+    
+    # Configure reasoning flow
+    self.reasoning_graph.set_entry_point("innovation_analysis")
+    self.reasoning_graph.add_edge("innovation_analysis", "growth_projection")
+    self.reasoning_graph.add_edge("growth_projection", "competition_analysis")
+    self.reasoning_graph.add_edge("competition_analysis", "valuation_adjustment")
+```
+
+Each reasoning node executes and passes state to the next node, building up a complete reasoning trace:
+
+```
+Step 1: Innovation Analysis
+- Assessed disruptive potential in key markets
+- Analyzed R&D pipeline and technological moats
+- Identified 4 significant innovation vectors
+
+Step 2: Growth Projection
+- Projected TAM expansion in core markets
+- Calculated penetration rates and growth curves
+- Estimated revenue CAGR of 28.3% over 5 years
+
+Step 3: Competition Analysis
+- Assessed competitive positioning in EV market
+- Analyzed first-mover advantages in energy storage
+- Identified emerging threats in autonomous driving
+
+Step 4: Valuation Adjustment
+- Applied growth-adjusted valuation metrics
+- Discounted future cash flows with risk adjustment
+- Compared valuation to traditional metrics
+```
+
+## 4. Signal Generation
+
+Each agent generates investment signals based on its reasoning:
+
+```python
+# Generate signals from each agent
+graham_signals = graham_agent.generate_signals(graham_processed)
+wood_signals = wood_agent.generate_signals(wood_processed)
+dalio_signals = dalio_agent.generate_signals(dalio_processed)
+```
+
+Each signal includes:
+- Action recommendation (buy/sell/hold)
+- Confidence level
+- Quantity recommendation
+- Complete reasoning chain
+- Value basis (philosophical foundation)
+- Attribution trace (causal links to evidence)
+
+Example of Wood agent's signal:
+
+```json
+{
+  "ticker": "TSLA",
+  "action": "buy",
+  "confidence": 0.82,
+  "quantity": 41,
+  "reasoning": "Tesla shows strong innovation potential across multiple verticals including EVs, energy storage, AI, and robotics. Their R&D pipeline demonstrates continued technological leadership with high growth potential in the coming decade.",
+  "intent": "Capitalize on long-term disruptive innovation growth",
+  "value_basis": "Disruptive innovation creates exponential growth and market expansion that traditional metrics fail to capture",
+  "attribution_trace": {
+    "innovation_score": 0.35,
+    "growth_projection": 0.25,
+    "competition_analysis": 0.20,
+    "valuation_adjustment": 0.20
+  },
+  "drift_signature": {
+    "interest_rates": -0.05,
+    "regulation": -0.03,
+    "competition": -0.02
+  }
+}
+```
+
+## 5. Meta-Agent Arbitration
+
+The portfolio meta-agent receives signals from all philosophical agents:
+
+```python
+# Create portfolio manager (meta-agent)
+portfolio = PortfolioManager(
+    agents=[graham_agent, wood_agent, dalio_agent],
+    arbitration_depth=2,
+    show_trace=True
+)
+
+# Process market data through meta-agent
+meta_result = portfolio.process_market_data(market_data)
+```
+
+### Consensus Formation
+
+The meta-agent first attempts to find consensus on non-conflicting signals:
+
+```python
+def _consensus_formation(self, state) -> Dict[str, Any]:
+    """Form consensus from agent signals."""
+    # Extract signals by ticker
+    ticker_signals = state.context.get("ticker_signals", {})
+    
+    # Form consensus for each ticker
+    consensus_decisions = []
+    
+    for ticker, signals in ticker_signals.items():
+        # Collect buy/sell/hold signals
+        buy_signals = []
+        sell_signals = []
+        hold_signals = []
+        
+        for item in signals:
+            signal = item.get("signal", {})
+            action = signal.action.lower()
+            
+            if action == "buy":
+                buy_signals.append((item, signal))
+            elif action == "sell":
+                sell_signals.append((item, signal))
+            elif action == "hold":
+                hold_signals.append((item, signal))
+        
+        # Skip if conflicting signals (handle in conflict resolution)
+        if (buy_signals and sell_signals) or (not buy_signals and not sell_signals and not hold_signals):
+            continue
+        
+        # Form consensus for non-conflicting signals
+        if buy_signals:
+            # Form buy consensus
+            consensus = self._form_action_consensus(ticker, "buy", buy_signals)
+            if consensus:
+                consensus_decisions.append(consensus)
+        
+        elif sell_signals:
+            # Form sell consensus
+            consensus = self._form_action_consensus(ticker, "sell", sell_signals)
+            if consensus:
+                consensus_decisions.append(consensus)
+        
+    return {
+        "context": {
+            **state.context,
+            "consensus_decisions": consensus_decisions,
+            "consensus_tickers": [decision.get("ticker") for decision in consensus_decisions],
+        },
+        "output": {
+            "consensus_decisions": consensus_decisions,
+        }
+    }
+```
+
+### Conflict Resolution
+
+For TSLA, we have a conflict: Graham (SELL) vs. Wood (BUY) vs. Dalio (HOLD). The meta-agent resolves this conflict:
+
+```python
+def _resolve_ticker_conflict(self, ticker: str, action_signals: Dict[str, List[Tuple[Dict[str, Any], Any]]]) -> Optional[Dict[str, Any]]:
+    """Resolve conflict for a specific ticker."""
+    # Calculate total weight for each action
+    action_weights = {}
+    action_confidences = {}
+    
+    for action, signals in action_signals.items():
+        total_weight = 0.0
+        weighted_confidence = for action, signals in action_signals.items():
+        total_weight = 0.0
+        weighted_confidence = 0.0
+        
+        for item, signal in signals:
+            agent_id = item.get("agent_id", "")
+            
+            # Skip if missing agent ID
+            if not agent_id:
+                continue
+            
+            # Get agent weight
+            agent_weight = self.agent_weights.get(agent_id, 0)
+            
+            # Add to weighted confidence
+            weighted_confidence += signal.confidence * agent_weight
+            total_weight += agent_weight
+        
+        # Store action weight and confidence
+        if total_weight > 0:
+            action_weights[action] = total_weight
+            action_confidences[action] = weighted_confidence / total_weight
+    
+    # Choose action with highest weight
+    if not action_weights:
+        return None
+        
+    best_action = max(action_weights.items(), key=lambda x: x[1])[0]
+    
+    # Check confidence threshold
+    if action_confidences.get(best_action, 0) < self.consensus_threshold:
+        return None
+    
+    # Get signals for best action
+    best_signals = action_signals.get(best_action, [])
+    
+    # Form consensus for best action
+    return self._form_action_consensus(ticker, best_action, best_signals)
+```
+
+In our case, after attributing current agent weights (based on historical performance):
+- Graham agent: 0.25 (weight) × 0.78 (confidence) = 0.195 (weighted confidence)
+- Wood agent: 0.40 (weight) × 0.82 (confidence) = 0.328 (weighted confidence)
+- Dalio agent: 0.35 (weight) × 0.65 (confidence) = 0.228 (weighted confidence)
+
+The Wood agent's BUY signal has the highest weighted confidence, so the meta-agent forms consensus around it.
+
+### Position Sizing
+
+The meta-agent determines position size based on confidence and attribution:
+
+```python
+def _calculate_position_size(self, ticker: str, action: str, confidence: float,
+                          attribution: Dict[str, float], portfolio_value: float) -> float:
+    """Calculate position size based on confidence and attribution."""
+    # Base position size as percentage of portfolio
+    base_size = self.min_position_size + (confidence * (self.max_position_size - self.min_position_size))
+    
+    # Calculate attribution-weighted size
+    if attribution:
+        # Calculate agent performance scores
+        performance_scores = {}
+        for agent_id, weight in attribution.items():
+            # Find agent
+            agent = None
+            for a in self.agents:
+                if a.id == agent_id:
+                    agent = a
+                    break
+            
+            if agent:
+                # Use consistency score as proxy for performance
+                performance_score = agent.state.consistency_score
+                performance_scores[agent_id] = performance_score
+        
+        # Calculate weighted performance score
+        weighted_score = 0
+        total_weight = 0
+        
+        for agent_id, weight in attribution.items():
+            if agent_id in performance_scores:
+                weighted_score += performance_scores[agent_id] * weight
+                total_weight += weight
+        
+        # Adjust base size by performance
+        if total_weight > 0:
+            performance_factor = weighted_score / total_weight
+            base_size *= (0.5 + (0.5 * performance_factor))
+    
+    # Calculate currency amount
+    target_size = portfolio_value * base_size
+    
+    return target_size
+```
+
+For TSLA:
+- Base position size: 0.01 + (0.82 × (0.20 - 0.01)) = 0.165 (16.5% of portfolio)
+- Adjusted for agent performance: 16.5% × 1.1 = 18.2% of portfolio
+- For a $1,000,000 portfolio: $182,000 position size
+- At current price of $242.15: 751 shares
+
+### Meta Reflection
+
+The meta-agent performs a final reflection on its decision process:
+
+```python
+def _meta_reflection(self, state) -> Dict[str, Any]:
+    """Perform meta-reflection on decision process."""
+    # Extract decisions
+    sized_decisions = state.context.get("sized_decisions", [])
+    
+    # Update meta state with arbitration record
+    arbitration_record = {
+        "id": str(uuid.uuid4()),
+        "decisions": sized_decisions,
+        "timestamp": datetime.datetime.now().isoformat(),
+    }
+    
+    self.meta_state["arbitration_history"].append(arbitration_record)
+    
+    # Update agent weights based on performance
+    self._update_agent_weights()
+    
+    # Calculate meta-confidence
+    meta_confidence = sum(decision.get("confidence", 0) for decision in sized_decisions) / len(sized_decisions) if sized_decisions else 0.5
+    
+    # Return final output
+    return {
+        "output": {
+            "consensus_decisions": sized_decisions,
+            "meta_confidence": meta_confidence,
+            "agent_weights": self.agent_weights,
+            "timestamp": datetime.datetime.now().isoformat(),
+        },
+        "confidence": meta_confidence,
+    }
+```
+
+The meta-agent final reflection includes:
+- Consensus tracking
+- Agent weight adjustment
+- Meta-confidence calculation
+- Temporal memory update
+
+## 6. Trade Execution
+
+The final step is trade execution:
+
+```python
+# Execute trades based on consensus decisions
+consensus_decisions = meta_result.get("meta_agent", {}).get("consensus_decisions", [])
+execution_results = portfolio.execute_trades(consensus_decisions)
+```
+
+The execution includes:
+- Position sizing
+- Order placement
+- Confirmation handling
+- Portfolio state update
+
+```json
+{
+  "trades": [
+    {
+      "ticker": "TSLA",
+      "action": "buy",
+      "quantity": 751,
+      "price": 242.15,
+      "cost": 181853.65,
+      "timestamp": "2024-04-17T14:23:45.123456"
+    }
+  ],
+  "errors": [],
+  "portfolio_update": {
+    "timestamp": "2024-04-17T14:23:45.654321",
+    "portfolio_value": 1000000.00,
+    "cash": 818146.35,
+    "positions": {
+      "TSLA": {
+        "ticker": "TSLA",
+        "quantity": 751,
+        "entry_price": 242.15,
+        "current_price": 242.15,
+        "market_value": 181853.65,
+        "allocation": 0.182,
+        "unrealized_gain": 0.0,
+        "entry_date": "2024-04-17T14:23:45.123456"
+      }
+    },
+    "returns": {
+      "total_return": 0.0,
+      "daily_return": 0.0
+    },
+    "allocation": {
+      "cash": 0.818,
+      "TSLA": 0.182
+    }
+  }
+}
+```
+
+## 7. Attribution Tracing
+
+Throughout this process, complete attribution tracing is maintained:
+
+```python
+# Generate attribution report
+attribution_report = portfolio.tracer.generate_attribution_report(meta_result.get("meta_agent", {}).get("consensus_decisions", []))
+```
+
+The attribution report shows the complete decision provenance:
+
+```json
+{
+  "agent_name": "PortfolioMetaAgent",
+  "timestamp": "2024-04-17T14:23:46.123456",
+  "signals": 1,
+  "attribution_summary": {
+    "Wood": 0.45,
+    "Dalio": 0.35,
+    "Graham": 0.20
+  },
+  "confidence_summary": {
+    "mean": 0.82,
+    "median": 0.82,
+    "min": 0.82,
+    "max": 0.82
+  },
+  "top_factors": [
+    {
+      "source": "innovation_score",
+      "weight": 0.35
+    },
+    {
+      "source": "growth_projection",
+      "weight": 0.25
+    },
+    {
+      "source": "economic_cycle_position",
+      "weight": 0.15
+    },
+    {
+      "source": "competition_analysis",
+      "weight": 0.10
+    },
+    {
+      "source": "intrinsic_value_calculation",
+      "weight": 0.10
+    }
+  ],
+  "shell_patterns": [
+    {
+      "pattern": "v07 CIRCUIT-FRAGMENT",
+      "count": 1,
+      "frequency": 1.0
+    }
+  ]
+}
+```
+
+## 8. Visualization
+
+The system provides multiple visualization tools for interpretability:
+
+### Consensus Graph
+
+```python
+# Generate consensus graph
+consensus_graph = portfolio.visualize_consensus_graph()
+```
+
+The consensus graph shows the flow of influence between agents and decisions:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "meta",
+      "label": "Portfolio Meta-Agent",
+      "type": "meta",
+      "size": 20
+    },
+    {
+      "id": "agent-1",
+      "label": "Graham Agent",
+      "type": "agent",
+      "philosophy": "Value investing focused on margin of safety",
+      "size": 15,
+      "weight": 0.20
+    },
+    {
+      "id": "agent-2",
+      "label": "Wood Agent",
+      "type": "agent",
+      "philosophy": "Disruptive innovation investing",
+      "size": 15,
+      "weight": 0.45
+    },
+    {
+      "id": "agent-3",
+      "label": "Dalio Agent",
+      "type": "agent",
+      "philosophy": "Macroeconomic-based investing",
+      "size": 15,
+      "weight": 0.35
+    },
+    {
+      "id": "position-TSLA",
+      "label": "TSLA",
+      "type": "position",
+      "size": 10,
+      "value": 181853.65
+    }
+  ],
+  "links": [
+    {
+      "source": "agent-1",
+      "target": "meta",
+      "value": 0.20,
+      "type": "influence"
+    },
+    {
+      "source": "agent-2",
+      "target": "meta",
+      "value": 0.45,
+      "type": "influence"
+    },
+    {
+      "source": "agent-3",
+      "target": "meta",
+      "value": 0.35,
+      "type": "influence"
+    },
+    {
+      "source": "meta",
+      "target": "position-TSLA",
+      "value": 1.0,
+      "type": "allocation"
+    },
+    {
+      "source": "agent-2",
+      "target": "position-TSLA",
+      "value": 0.45,
+      "type": "attribution"
+    },
+    {
+      "source": "agent-3",
+      "target": "position-TSLA",
+      "value": 0.35,
+      "type": "attribution"
+    },
+    {
+      "source": "agent-1",
+      "target": "position-TSLA",
+      "value": 0.20,
+      "type": "attribution"
+    }
+  ],
+  "timestamp": "2024-04-17T14:23:46.987654"
+}
+```
+
+### Agent Conflict Map
+
+```python
+# Generate agent conflict map
+conflict_map = portfolio.visualize_agent_conflict_map()
+```
+
+The conflict map visualizes the specific disagreements between agents:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "agent-1",
+      "label": "Graham Agent",
+      "type": "agent",
+      "philosophy": "Value investing focused on margin of safety",
+      "size": 15
+    },
+    {
+      "id": "agent-2",
+      "label": "Wood Agent",
+      "type": "agent",
+      "philosophy": "Disruptive innovation investing",
+      "size": 15
+    },
+    {
+      "id": "agent-3",
+      "label": "Dalio Agent",
+      "type": "agent",
+      "philosophy": "Macroeconomic-based investing",
+      "size": 15
+    },
+    {
+      "id": "position-TSLA",
+      "label": "TSLA",
+      "type": "position",
+      "size": 10
+    }
+  ],
+  "links": [
+    {
+      "source": "agent-1",
+      "target": "agent-2",
+      "value": 1.0,
+      "type": "conflict",
+      "ticker": "TSLA"
+    },
+    {
+      "source": "agent-2",
+      "target": "agent-3",
+      "value": 1.0,
+      "type": "conflict",
+      "ticker": "TSLA"
+    },
+    {
+      "source": "agent-1",
+      "target": "agent-3",
+      "value": 1.0,
+      "type": "conflict",
+      "ticker": "TSLA"
+    }
+  ],
+  "conflict_zones": [
+    {
+      "id": "conflict-1",
+      "ticker": "TSLA",
+      "agents": ["agent-1", "agent-2", "agent-3"],
+      "resolution": "resolved",
+      "timestamp": "2024-04-17T14:23:44.567890"
+    }
+  ],
+  "timestamp": "2024-04-17T14:23:47.654321"
+}
+```
+
+### Shell Failure Map
+
+```python
+# Create shell diagnostics
+shell_diagnostics = ShellDiagnostics(
+    agent_id="portfolio",
+    agent_name="Portfolio",
+    tracing_tools=TracingTools(
+        agent_id="portfolio",
+        agent_name="Portfolio",
+        tracing_mode=TracingMode.DETAILED,
+    )
+)
+
+# Create shell failure map
+failure_map = ShellFailureMap()
+
+# Analyze each agent's state for shell failures
+for agent in [graham_agent, wood_agent, dalio_agent]:
+    agent_state = agent.get_state_report()
+    
+    # Simulate shell failures based on agent state
+    for shell_pattern in [ShellPattern.CIRCUIT_FRAGMENT, ShellPattern.META_FAILURE]:
+        failure_data = shell_diagnostics.simulate_shell_failure(
+            shell_pattern=shell_pattern,
+            context=agent_state,
+        )
+        
+        # Add to failure map
+        failure_map.add_failure(
+            agent_id=agent.id,
+            agent_name=agent.name,
+            shell_pattern=shell_pattern,
+            failure_data=failure_data,
+        )
+
+# Generate visualization
+shell_failure_viz = failure_map.generate_failure_map_visualization()
+```
+
+The shell failure map visualizes interpretability patterns detected in the agents:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "agent-1",
+      "label": "Graham Agent",
+      "type": "agent",
+      "size": 15,
+      "failure_count": 1
+    },
+    {
+      "id": "agent-2",
+      "label": "Wood Agent",
+      "type": "agent",
+      "size": 15,
+      "failure_count": 2
+    },
+    {
+      "id": "agent-3",
+      "label": "Dalio Agent",
+      "type": "agent",
+      "size": 15,
+      "failure_count": 1
+    },
+    {
+      "id": "v07 CIRCUIT-FRAGMENT",
+      "label": "CIRCUIT-FRAGMENT",
+      "type": "pattern",
+      "size": 10,
+      "failure_count": 3
+    },
+    {
+      "id": "v10 META-FAILURE",
+      "label": "META-FAILURE",
+      "type": "pattern",
+      "size": 10,
+      "failure_count": 1
+    },
+    {
+      "id": "failure-1",
+      "label": "Failure 3f4a9c",
+      "type": "failure",
+      "size": 5,
+      "timestamp": "2024-04-17T14:23:48.123456"
+    },
+    {
+      "id": "failure-2",
+      "label": "Failure b7d5e2",
+      "type": "failure",
+      "size": 5,
+      "timestamp": "2024-04-17T14:23:48.234567"
+    },
+    {
+      "id": "failure-3",
+      "label": "Failure 9c6f1a",
+      "type": "failure",
+      "size": 5,
+      "timestamp": "2024-04-17T14:23:48.345678"
+    },
+    {
+      "id": "failure-4",
+      "label": "Failure 2e8d7f",
+      "type": "failure",
+      "size": 5,
+      "timestamp": "2024-04-17T14:23:48.456789"
+    }
+  ],
+  "links": [
+    {
+      "source": "agent-1",
+      "target": "failure-1",
+      "type": "agent_failure"
+    },
+    {
+      "source": "v07 CIRCUIT-FRAGMENT",
+      "target": "failure-1",
+      "type": "pattern_failure"
+    },
+    {
+      "source": "agent-2",
+      "target": "failure-2",
+      "type": "agent_failure"
+    },
+    {
+      "source": "v07 CIRCUIT-FRAGMENT",
+      "target": "failure-2",
+      "type": "pattern_failure"
+    },
+    {
+      "source": "agent-2",
+      "target": "failure-3",
+      "type": "agent_failure"
+    },
+    {
+      "source": "v10 META-FAILURE",
+      "target": "failure-3",
+      "type": "pattern_failure"
+    },
+    {
+      "source": "agent-3",
+      "target": "failure-4",
+      "type": "agent_failure"
+    },
+    {
+      "source": "v07 CIRCUIT-FRAGMENT",
+      "target": "failure-4",
+      "type": "pattern_failure"
+    }
+  ],
+  "timestamp": "2024-04-17T14:23:49.000000"
+}
+```
+
+## 9. Agent Memory & Learning
+
+After each trading cycle, agents update their internal state:
+
+```python
+# Update agent states based on market feedback
+market_feedback = {
+    'portfolio_value': execution_results['portfolio_update']['portfolio_value'],
+    'performance': {'TSLA': 0.02},  # Example: 2% return
+    'decisions': consensus_decisions,
+    'avg_confidence': 0.82,
+}
+
+# Update each agent's state
+for agent in [graham_agent, wood_agent, dalio_agent]:
+    agent.update_state(market_feedback)
+```
+
+Each agent processes the feedback differently based on its philosophy:
+
+### Wood Agent Memory Update
+
+```python
+def _update_beliefs(self, market_feedback: Dict[str, Any]) -> None:
+    """Update agent's belief state based on market feedback."""
+    # Extract relevant signals
+    if 'performance' in market_feedback:
+        performance = market_feedback['performance']
+        
+        # Record decision outcomes
+        if 'decisions' in market_feedback:
+            for decision in market_feedback['decisions']:
+                self.state.decision_history.append({
+                    'decision': decision,
+                    'outcome': performance.get(decision.get('ticker'), 0),
+                    'timestamp': datetime.datetime.now()
+                })
+                
+                # For Wood Agent, reinforce innovation beliefs on positive outcomes
+                if performance.get(decision.get('ticker'), 0) > 0:
+                    ticker = decision.get('ticker')
+                    # Strengthen innovation belief
+                    current_belief = self.state.belief_state.get(f"{ticker}_innovation", 0.5)
+                    self.state.belief_state[f"{ticker}_innovation"] = min(1.0, current_belief + 0.05)
+                    
+                    # Update industry trend belief
+                    industry = self._get_ticker_industry(ticker)
+                    if industry:
+                        industry_belief = self.state.belief_state.get(f"{industry}_trend", 0.5)
+                        self.state.belief_state[f"{industry}_trend"] = min(1.0, industry_belief + 0.03)
+        
+        # Update general belief state based on performance
+        for ticker, perf in performance.items():
+            general_belief_key = f"{ticker}_general"
+            current_belief = self.state.belief_state.get(general_belief_key, 0.5)
+            
+            # Wood Agent weights positive outcomes more heavily for innovative companies
+            if self._is_innovative_company(ticker):
+                update_weight = 0.3  # Higher weight for innovative companies
+            else:
+                update_weight = 0.1  # Lower weight for traditional companies
+            
+            # Update belief
+            updated_belief = current_belief * (1 - update_weight) + np.tanh(perf) * update_weight
+            self.state.belief_state[general_belief_key] = updated_belief
+            
+            # Track belief drift
+            if general_belief_key in self.state.belief_state:
+                drift = updated_belief - current_belief
+                self.state.drift_vector[general_belief_key] = drift
+                
+                # Wood Agent's drift pattern analysis
+                self._analyze_drift_pattern(ticker, drift)
+```
+
+## 10. Command Interface
+
+Throughout the system, the symbolic command interface enables deeper introspection:
+
+```python
+# Get a reflection trace from the Graham agent
+reflection_trace = graham_agent.execute_command(
+    command="reflect.trace",
+    depth=3
+)
+
+# Generate signals from alternative sources
+alt_signals = wood_agent.execute_command(
+    command="fork.signal",
+    source="beliefs"
+)
+
+# Check for decision collapse
+collapse_check = dalio_agent.execute_command(
+    command="collapse.detect",
+    threshold=0.7,
+    reason="consistency"
+)
+
+# Attribute weight to a justification
+attribution = portfolio.execute_command(
+    command="attribute.weight",
+    justification="Tesla's innovation in AI and robotics represents a paradigm shift that traditional valuation metrics fail to capture."
+)
+
+# Track belief drift
+drift_observation = wood_agent.execute_command(
+    command="drift.observe",
+    vector={"TSLA_innovation": 0.05, "AI_trend": 0.03, "EV_market": 0.02},
+    bias=0.01
+)
+```
+
+These commands form the foundation of the system's interpretability architecture, enabling detailed tracing and analysis of decision processes.
+
+## Conclusion
+
+This example demonstrates the recursive cognitive architecture of Multi-Agent Debate in action. From market data ingestion to trade execution, the system maintains complete transparency and interpretability through:
+
+1. Agent-specific cognitive lenses
+2. Recursive reasoning graphs
+3. Attribution tracing
+4. Meta-agent arbitration
+5. Position sizing
+6. Trade execution
+7. Memory and learning
+
+Each component is designed to enable deeper introspection into the decision-making process, creating a truly transparent and interpretable multi-agent market cognition system.
+
+The symbolic command interface and visualization tools provide multiple ways to understand and analyze the system's behavior, making it both effective and explainable.
+
+
+
+
+

requirements.txt

@@ -0,0 +1,13 @@
+numpy>=1.24.0
+pandas>=2.0.0
+matplotlib>=3.7.0
+plotly>=5.14.0
+yfinance>=0.2.18
+langgraph>=0.0.11
+anthropic>=0.5.0
+openai>=1.1.0
+groq>=0.3.0
+langchain>=0.0.267
+langchain-experimental>=0.0.9
+langchain-community>=0.0.9
+pydantic>=2.4.0

setup.py

@@ -0,0 +1,68 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="multi_agent_debate",
+    version="0.1.0",
+    author="multi_agent_debate Contributors",
+    author_email="contributors@multi_agent_debate.org",
+    description="Multi-agent recursive market cognition framework",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/multi_agent_debate/multi_agent_debate",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Financial and Insurance Industry",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+        "Topic :: Office/Business :: Financial :: Investment",
+    ],
+    python_requires=">=3.10",
+    install_requires=[
+        "numpy>=1.24.0",
+        "pandas>=2.0.0",
+        "matplotlib>=3.7.0",
+        "plotly>=5.14.0",
+        "yfinance>=0.2.18",
+        "langgraph>=0.0.11",
+        "anthropic>=0.5.0",
+        "openai>=1.1.0",
+        "groq>=0.3.0",
+        "langchain>=0.0.267",
+        "langchain-experimental>=0.0.9", 
+        "langchain-community>=0.0.9",
+        "pydantic>=2.4.0",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=7.3.1",
+            "black>=23.3.0",
+            "isort>=5.12.0",
+            "mypy>=1.3.0",
+        ],
+        "docs": [
+            "sphinx>=7.0.0",
+            "sphinx-rtd-theme>=1.2.2",
+            "myst-parser>=2.0.0",
+        ],
+        "optional": [
+            "polygon-api-client>=1.10.0",
+            "alpha_vantage>=2.3.1",
+            "ollama>=0.1.0",
+            "deepseek>=0.1.0",
+        ],
+    },
+    entry_points={
+        "console_scripts": [
+            "multi_agent_debate=src.main:main",
+        ],
+    },
+)

src/agents/base.py

@@ -0,0 +1,611 @@
+"""
+BaseAgent - Recursive Cognitive Agent Framework for AGI-HEDGE-FUND
+
+This module implements the foundational cognitive architecture for all investment agents.
+Each agent inherits from this base class to enable:
+- Recursive reasoning loops with customizable depth
+- Transparent attribution tracing for decision provenance
+- Temporal memory shell with configurable decay
+- Value-weighted decision encoding
+- Symbolic state representation for interpretability
+
+Internal Note: Base class encodes the recursive interpretability interface (.p/ command patterns)
+in line with Anthropic-style Circuit Tracing research while maintaining familiar investment syntax.
+"""
+
+import uuid
+import datetime
+from typing import Dict, List, Any, Optional, Tuple
+import numpy as np
+from pydantic import BaseModel, Field
+
+from ..cognition.graph import ReasoningGraph
+from ..cognition.memory import MemoryShell
+from ..cognition.attribution import AttributionTracer
+from ..llm.router import ModelRouter
+from ..utils.diagnostics import TracingTools
+
+
+class AgentSignal(BaseModel):
+    """Signal generated by an agent with full attribution and confidence metrics."""
+    
+    ticker: str = Field(..., description="Stock ticker symbol")
+    action: str = Field(..., description="buy, sell, or hold")
+    confidence: float = Field(..., description="Confidence level (0.0-1.0)")
+    quantity: Optional[int] = Field(None, description="Number of shares to trade")
+    reasoning: str = Field(..., description="Explicit reasoning chain")
+    intent: str = Field(..., description="High-level investment intent")
+    value_basis: str = Field(..., description="Core value driving this decision")
+    attribution_trace: Dict[str, float] = Field(default_factory=dict, description="Causal attribution weights")
+    drift_signature: Dict[str, float] = Field(default_factory=dict, description="Belief drift metrics")
+    signal_id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="Unique signal identifier")
+    timestamp: datetime.datetime = Field(default_factory=datetime.datetime.now)
+
+
+class AgentState(BaseModel):
+    """Persistent agent state with temporal memory and belief dynamics."""
+    
+    working_memory: Dict[str, Any] = Field(default_factory=dict, description="Short-term memory")
+    belief_state: Dict[str, float] = Field(default_factory=dict, description="Current belief distribution")
+    confidence_history: List[float] = Field(default_factory=list, description="Historical confidence")
+    decision_history: List[Dict[str, Any]] = Field(default_factory=list, description="Past decisions")
+    performance_trace: Dict[str, float] = Field(default_factory=dict, description="Performance metrics")
+    reflective_state: Dict[str, Any] = Field(default_factory=dict, description="Self-awareness metrics")
+    drift_vector: Dict[str, float] = Field(default_factory=dict, description="Direction of belief evolution")
+    consistency_score: float = Field(default=1.0, description="Internal consistency metric")
+    last_update: datetime.datetime = Field(default_factory=datetime.datetime.now)
+
+
+class BaseAgent:
+    """
+    Base class for all investment agents in the AGI-HEDGE-FUND framework.
+    
+    Implements the core cognitive architecture including:
+    - Recursive reasoning loops
+    - Memory persistence
+    - Attribution tracing
+    - Value-weighted decision making
+    - Symbolic state representation
+    """
+    
+    def __init__(
+        self,
+        name: str,
+        philosophy: str,
+        reasoning_depth: int = 3,
+        memory_decay: float = 0.2,
+        initial_capital: float = 100000.0,
+        model_provider: str = "anthropic",
+        model_name: str = "claude-3-sonnet-20240229",
+        trace_enabled: bool = False,
+    ):
+        """
+        Initialize a cognitive investment agent.
+        
+        Args:
+            name: Agent identifier name
+            philosophy: Investment philosophy description
+            reasoning_depth: Depth of recursive reasoning (higher = deeper thinking)
+            memory_decay: Rate of memory deterioration (0.0-1.0)
+            initial_capital: Starting capital amount
+            model_provider: LLM provider ("anthropic", "openai", "groq", "ollama", "deepseek")
+            model_name: Specific model identifier
+            trace_enabled: Whether to generate full reasoning traces
+        """
+        self.id = str(uuid.uuid4())
+        self.name = name
+        self.philosophy = philosophy
+        self.reasoning_depth = reasoning_depth
+        self.memory_decay = memory_decay
+        self.initial_capital = initial_capital
+        self.current_capital = initial_capital
+        self.trace_enabled = trace_enabled
+        
+        # Initialize cognitive components
+        self.state = AgentState()
+        self.memory_shell = MemoryShell(decay_rate=memory_decay)
+        self.attribution_tracer = AttributionTracer()
+        self.llm = ModelRouter(provider=model_provider, model=model_name)
+        
+        # Initialize reasoning graph
+        self.reasoning_graph = ReasoningGraph(
+            agent_name=self.name,
+            agent_philosophy=self.philosophy,
+            model_router=self.llm,
+        )
+        
+        # Diagnostics and tracing
+        self.tracer = TracingTools(agent_id=self.id, agent_name=self.name)
+        
+        # Internal symbolic processing commands
+        self._commands = {
+            "reflect.trace": self._reflect_trace,
+            "fork.signal": self._fork_signal,
+            "collapse.detect": self._collapse_detect,
+            "attribute.weight": self._attribute_weight,
+            "drift.observe": self._drift_observe,
+        }
+
+    def process_market_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process market data through agent's cognitive lens.
+        
+        Args:
+            data: Market data dictionary
+            
+        Returns:
+            Processed market data with agent-specific insights
+        """
+        # Each agent subclass implements its unique market interpretation
+        raise NotImplementedError("Agent subclasses must implement process_market_data")
+    
+    def generate_signals(self, processed_data: Dict[str, Any]) -> List[AgentSignal]:
+        """
+        Generate investment signals based on processed market data.
+        
+        Args:
+            processed_data: Processed market data
+            
+        Returns:
+            List of investment signals with attribution
+        """
+        # Each agent subclass implements its unique signal generation logic
+        raise NotImplementedError("Agent subclasses must implement generate_signals")
+    
+    def update_state(self, market_feedback: Dict[str, Any]) -> None:
+        """
+        Update agent's internal state based on market feedback.
+        
+        Args:
+            market_feedback: Dictionary containing market performance data
+        """
+        # Update memory shell with new experiences
+        self.memory_shell.add_experience(market_feedback)
+        
+        # Update belief state based on market feedback
+        self._update_beliefs(market_feedback)
+        
+        # Update performance metrics
+        self._update_performance_metrics(market_feedback)
+        
+        # Apply memory decay
+        self.memory_shell.apply_decay()
+        
+        # Update timestamp
+        self.state.last_update = datetime.datetime.now()
+    
+    def _update_beliefs(self, market_feedback: Dict[str, Any]) -> None:
+        """
+        Update agent's belief state based on market feedback.
+        
+        Args:
+            market_feedback: Dictionary containing market performance data
+        """
+        # Extract relevant signals from market feedback
+        if 'performance' in market_feedback:
+            performance = market_feedback['performance']
+            
+            # Record decision outcomes
+            if 'decisions' in market_feedback:
+                for decision in market_feedback['decisions']:
+                    self.state.decision_history.append({
+                        'decision': decision,
+                        'outcome': performance.get(decision.get('ticker'), 0),
+                        'timestamp': datetime.datetime.now()
+                    })
+            
+            # Update belief state based on performance
+            for ticker, perf in performance.items():
+                current_belief = self.state.belief_state.get(ticker, 0.5)
+                # Belief update formula combines prior belief with new evidence
+                updated_belief = (current_belief * (1 - self.memory_decay) + 
+                                  np.tanh(perf) * self.memory_decay)
+                self.state.belief_state[ticker] = updated_belief
+                
+                # Track belief drift
+                if ticker in self.state.belief_state:
+                    drift = updated_belief - current_belief
+                    self.state.drift_vector[ticker] = drift
+    
+    def _update_performance_metrics(self, market_feedback: Dict[str, Any]) -> None:
+        """
+        Update agent's performance metrics based on market feedback.
+        
+        Args:
+            market_feedback: Dictionary containing market performance data
+        """
+        if 'portfolio_value' in market_feedback:
+            # Calculate return
+            portfolio_value = market_feedback['portfolio_value']
+            prior_value = self.state.performance_trace.get('portfolio_value', self.initial_capital)
+            returns = (portfolio_value - prior_value) / prior_value if prior_value > 0 else 0
+            
+            # Update performance trace
+            self.state.performance_trace.update({
+                'portfolio_value': portfolio_value,
+                'returns': returns,
+                'cumulative_return': (portfolio_value / self.initial_capital) - 1,
+                'win_rate': market_feedback.get('win_rate', 0),
+                'sharpe_ratio': market_feedback.get('sharpe_ratio', 0),
+            })
+            
+            # Update current capital
+            self.current_capital = portfolio_value
+            
+            # Add to confidence history
+            avg_confidence = market_feedback.get('avg_confidence', 0.5)
+            self.state.confidence_history.append(avg_confidence)
+            
+            # Update consistency score
+            self._update_consistency_score(market_feedback)
+    
+    def _update_consistency_score(self, market_feedback: Dict[str, Any]) -> None:
+        """
+        Update agent's internal consistency score.
+        
+        Args:
+            market_feedback: Dictionary containing market performance data
+        """
+        # Measure consistency between stated reasoning and actual performance
+        if 'decisions' in market_feedback and 'performance' in market_feedback:
+            performance = market_feedback['performance']
+            decision_consistency = []
+            
+            for decision in market_feedback['decisions']:
+                ticker = decision.get('ticker')
+                expected_direction = 1 if decision.get('action') == 'buy' else -1
+                actual_performance = performance.get(ticker, 0)
+                actual_direction = 1 if actual_performance > 0 else -1
+                
+                # Consistency is 1 when directions match, -1 when they don't
+                direction_consistency = 1 if expected_direction == actual_direction else -1
+                decision_consistency.append(direction_consistency)
+            
+            # Update consistency score (moving average)
+            if decision_consistency:
+                avg_consistency = sum(decision_consistency) / len(decision_consistency)
+                current_consistency = self.state.consistency_score
+                self.state.consistency_score = (current_consistency * 0.8) + (avg_consistency * 0.2)
+    
+    def attribute_signals(self, signals: List[Dict[str, Any]]) -> List[AgentSignal]:
+        """
+        Add attribution traces to raw signals.
+        
+        Args:
+            signals: Raw investment signals
+            
+        Returns:
+            Signals with attribution traces
+        """
+        attributed_signals = []
+        for signal in signals:
+            # Run attribution tracing
+            attribution = self.attribution_tracer.trace_attribution(
+                signal=signal,
+                agent_state=self.state,
+                reasoning_depth=self.reasoning_depth
+            )
+            
+            # Create AgentSignal with attribution
+            agent_signal = AgentSignal(
+                ticker=signal.get('ticker', ''),
+                action=signal.get('action', 'hold'),
+                confidence=signal.get('confidence', 0.5),
+                quantity=signal.get('quantity'),
+                reasoning=signal.get('reasoning', ''),
+                intent=signal.get('intent', ''),
+                value_basis=signal.get('value_basis', ''),
+                attribution_trace=attribution.get('attribution_trace', {}),
+                drift_signature=self.state.drift_vector,
+            )
+            attributed_signals.append(agent_signal)
+            
+            # Record in tracer if enabled
+            if self.trace_enabled:
+                self.tracer.record_signal(agent_signal)
+        
+        return attributed_signals
+    
+    def reset(self) -> None:
+        """Reset agent to initial state while preserving memory decay pattern."""
+        # Reset capital
+        self.current_capital = self.initial_capital
+        
+        # Reset state but preserve some learning
+        belief_state = self.state.belief_state.copy()
+        drift_vector = self.state.drift_vector.copy()
+        
+        # Create new state
+        self.state = AgentState(
+            belief_state=belief_state,
+            drift_vector=drift_vector,
+        )
+        
+        # Apply memory decay to preserved beliefs
+        for key in self.state.belief_state:
+            self.state.belief_state[key] *= (1 - self.memory_decay)
+    
+    def get_state_report(self) -> Dict[str, Any]:
+        """
+        Generate a detailed report of agent's current state.
+        
+        Returns:
+            Dictionary containing agent state information
+        """
+        return {
+            'agent_id': self.id,
+            'agent_name': self.name,
+            'philosophy': self.philosophy,
+            'reasoning_depth': self.reasoning_depth,
+            'capital': self.current_capital,
+            'belief_state': self.state.belief_state,
+            'performance': self.state.performance_trace,
+            'consistency': self.state.consistency_score,
+            'decision_count': len(self.state.decision_history),
+            'avg_confidence': np.mean(self.state.confidence_history[-10:]) if self.state.confidence_history else 0.5,
+            'drift_vector': self.state.drift_vector,
+            'memory_decay': self.memory_decay,
+            'timestamp': datetime.datetime.now(),
+        }
+    
+    def save_state(self, filepath: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Save agent state to file or return serializable state.
+        
+        Args:
+            filepath: Optional path to save state
+            
+        Returns:
+            Dictionary containing serializable agent state
+        """
+        state_dict = {
+            'agent_id': self.id,
+            'agent_name': self.name,
+            'agent_state': self.state.dict(),
+            'memory_shell': self.memory_shell.export_state(),
+            'reasoning_depth': self.reasoning_depth,
+            'memory_decay': self.memory_decay,
+            'current_capital': self.current_capital,
+            'initial_capital': self.initial_capital,
+            'timestamp': datetime.datetime.now().isoformat(),
+        }
+        
+        if filepath:
+            import json
+            with open(filepath, 'w') as f:
+                json.dump(state_dict, f)
+        
+        return state_dict
+    
+    def load_state(self, state_dict: Dict[str, Any]) -> None:
+        """
+        Load agent state from dictionary.
+        
+        Args:
+            state_dict: Dictionary containing agent state
+        """
+        if state_dict['agent_id'] != self.id:
+            raise ValueError(f"State ID mismatch: {state_dict['agent_id']} vs {self.id}")
+        
+        # Update basic attributes
+        self.reasoning_depth = state_dict.get('reasoning_depth', self.reasoning_depth)
+        self.memory_decay = state_dict.get('memory_decay', self.memory_decay)
+        self.current_capital = state_dict.get('current_capital', self.current_capital)
+        self.initial_capital = state_dict.get('initial_capital', self.initial_capital)
+        
+        # Load agent state
+        if 'agent_state' in state_dict:
+            self.state = AgentState.parse_obj(state_dict['agent_state'])
+            
+        # Load memory shell
+        if 'memory_shell' in state_dict:
+            self.memory_shell.import_state(state_dict['memory_shell'])
+    
+    # Internal symbolic command processors
+    def _reflect_trace(self, agent=None, depth=3) -> Dict[str, Any]:
+        """
+        Trace agent's self-reflection on decision making process.
+        
+        Args:
+            agent: Optional agent name to reflect on (self if None)
+            depth: Recursion depth for reflection
+            
+        Returns:
+            Reflection trace results
+        """
+        # If reflecting on self
+        if agent is None or agent == self.name:
+            reflection = self.reasoning_graph.run_reflection(
+                agent_state=self.state,
+                depth=depth,
+                trace_enabled=self.trace_enabled
+            )
+            return {
+                'source': 'self',
+                'reflection': reflection,
+                'depth': depth,
+                'confidence': reflection.get('confidence', 0.5),
+                'timestamp': datetime.datetime.now(),
+            }
+        # Otherwise, this is a request to reflect on another agent (handled by portfolio manager)
+        return {
+            'source': 'external',
+            'target': agent,
+            'depth': depth,
+            'status': 'delegated',
+            'timestamp': datetime.datetime.now(),
+        }
+    
+    def _fork_signal(self, source) -> Dict[str, Any]:
+        """
+        Fork a new signal branch from specified source.
+        
+        Args:
+            source: Source to fork signal from
+            
+        Returns:
+            Forked signal results
+        """
+        if source == 'memory':
+            # Fork from memory
+            experiences = self.memory_shell.get_relevant_experiences(limit=3)
+            forked_signals = self.reasoning_graph.generate_from_experiences(experiences)
+            return {
+                'source': 'memory',
+                'signals': forked_signals,
+                'count': len(forked_signals),
+                'timestamp': datetime.datetime.now(),
+            }
+        elif source == 'beliefs':
+            # Fork from current beliefs
+            top_beliefs = dict(sorted(
+                self.state.belief_state.items(), 
+                key=lambda x: abs(x[1] - 0.5), 
+                reverse=True
+            )[:5])
+            forked_signals = self.reasoning_graph.generate_from_beliefs(top_beliefs)
+            return {
+                'source': 'beliefs',
+                'signals': forked_signals,
+                'count': len(forked_signals),
+                'timestamp': datetime.datetime.now(),
+            }
+        else:
+            # Unknown source
+            return {
+                'source': source,
+                'signals': [],
+                'count': 0,
+                'error': 'unknown_source',
+                'timestamp': datetime.datetime.now(),
+            }
+    
+    def _collapse_detect(self, threshold=0.7, reason=None) -> Dict[str, Any]:
+        """
+        Detect potential decision collapse or inconsistency.
+        
+        Args:
+            threshold: Consistency threshold below which to trigger collapse detection
+            reason: Optional specific reason to check for collapse
+            
+        Returns:
+            Collapse detection results
+        """
+        # Check consistency score
+        consistency_collapse = self.state.consistency_score < threshold
+        
+        # Check for specific collapses
+        collapses = {
+            'consistency': consistency_collapse,
+            'confidence': np.mean(self.state.confidence_history[-5:]) < threshold if len(self.state.confidence_history) >= 5 else False,
+            'belief_drift': any(abs(drift) > 0.3 for drift in self.state.drift_vector.values()),
+            'performance': self.state.performance_trace.get('returns', 0) < -0.1 if self.state.performance_trace else False,
+        }
+        
+        # If specific reason provided, check only that
+        if reason and reason in collapses:
+            collapse_detected = collapses[reason]
+            collapse_reasons = {reason: collapses[reason]}
+        else:
+            # Check all collapses
+            collapse_detected = any(collapses.values())
+            collapse_reasons = {k: v for k, v in collapses.items() if v}
+        
+        return {
+            'collapse_detected': collapse_detected,
+            'collapse_reasons': collapse_reasons,
+            'consistency_score': self.state.consistency_score,
+            'threshold': threshold,
+            'timestamp': datetime.datetime.now(),
+        }
+    
+    def _attribute_weight(self, justification) -> Dict[str, Any]:
+        """
+        Compute attribution weight for a specific justification.
+        
+        Args:
+            justification: Justification to weight
+            
+        Returns:
+            Attribution weight results
+        """
+        # Extract key themes from justification
+        themes = self.reasoning_graph.extract_themes(justification)
+        
+        # Compute alignment with agent's philosophy
+        philosophy_alignment = self.reasoning_graph.compute_alignment(
+            themes=themes,
+            philosophy=self.philosophy
+        )
+        
+        # Compute weight based on alignment and consistency
+        weight = philosophy_alignment * self.state.consistency_score
+        
+        return {
+            'justification': justification,
+            'themes': themes,
+            'philosophy_alignment': philosophy_alignment,
+            'consistency_factor': self.state.consistency_score,
+            'attribution_weight': weight,
+            'timestamp': datetime.datetime.now(),
+        }
+    
+    def _drift_observe(self, vector, bias=0.0) -> Dict[str, Any]:
+        """
+        Observe and record belief drift.
+        
+        Args:
+            vector: Drift vector to observe
+            bias: Optional bias adjustment
+            
+        Returns:
+            Drift observation results
+        """
+        # Record drift observation
+        for key, value in vector.items():
+            if key in self.state.drift_vector:
+                # Existing key, update with bias
+                self.state.drift_vector[key] = (self.state.drift_vector[key] * 0.7) + (value * 0.3) + bias
+            else:
+                # New key
+                self.state.drift_vector[key] = value + bias
+        
+        # Compute drift magnitude
+        drift_magnitude = np.sqrt(sum(v**2 for v in self.state.drift_vector.values()))
+        
+        return {
+            'drift_vector': self.state.drift_vector,
+            'drift_magnitude': drift_magnitude,
+            'bias_applied': bias,
+            'observation_count': len(vector),
+            'timestamp': datetime.datetime.now(),
+        }
+    
+    def execute_command(self, command: str, **kwargs) -> Dict[str, Any]:
+        """
+        Execute an internal symbolic command.
+        
+        Args:
+            command: Command to execute
+            **kwargs: Command parameters
+            
+        Returns:
+            Command execution results
+        """
+        if command in self._commands:
+            return self._commands[command](**kwargs)
+        else:
+            return {
+                'error': 'unknown_command',
+                'command': command,
+                'available_commands': list(self._commands.keys()),
+                'timestamp': datetime.datetime.now(),
+            }
+
+    def __repr__(self) -> str:
+        """Generate string representation of agent."""
+        return f"{self.name} Agent (ID: {self.id[:8]}, Philosophy: {self.philosophy})"
+
+    def __str__(self) -> str:
+        """Generate human-readable string for agent."""
+        return f"{self.name} Agent: {self.philosophy} (Depth: {self.reasoning_depth})"

src/agents/graham.py

@@ -0,0 +1,832 @@
+"""
+GrahamAgent - Value Investing Cognitive Agent
+
+This module implements Benjamin Graham's value investing philosophy as a 
+recursive cognitive agent with specialized market interpretation capabilities.
+
+Key characteristics:
+- Focuses on margin of safety and intrinsic value
+- Detects undervalued assets based on fundamentals
+- Maintains skepticism toward market sentiment
+- Prioritizes long-term value over short-term price movements
+- Exhibits patience and discipline with high conviction
+
+Internal Notes: The Graham shell simulates the CIRCUIT-FRAGMENT and NULL-FEATURE
+shells for detecting undervalued assets and knowledge boundaries.
+"""
+
+import datetime
+from typing import Dict, List, Any, Optional
+import numpy as np
+
+from .base import BaseAgent, AgentSignal
+from ..cognition.graph import ReasoningGraph
+from ..utils.diagnostics import TracingTools
+
+
+class GrahamAgent(BaseAgent):
+    """
+    Agent embodying Benjamin Graham's value investing philosophy.
+    
+    Implements specialized cognitive patterns for:
+    - Intrinsic value calculation
+    - Margin of safety evaluation
+    - Fundamental analysis
+    - Value trap detection
+    - Long-term perspective
+    """
+    
+    def __init__(
+        self,
+        reasoning_depth: int = 3,
+        memory_decay: float = 0.1,  # Lower memory decay for long-term perspective
+        initial_capital: float = 100000.0,
+        margin_of_safety: float = 0.3,  # Minimum discount to intrinsic value
+        model_provider: str = "anthropic",
+        model_name: str = "claude-3-sonnet-20240229",
+        trace_enabled: bool = False,
+    ):
+        """
+        Initialize Graham value investing agent.
+        
+        Args:
+            reasoning_depth: Depth of recursive reasoning
+            memory_decay: Rate of memory deterioration
+            initial_capital: Starting capital amount
+            margin_of_safety: Minimum discount to intrinsic value requirement
+            model_provider: LLM provider
+            model_name: Specific model identifier
+            trace_enabled: Whether to generate full reasoning traces
+        """
+        super().__init__(
+            name="Graham",
+            philosophy="Value investing focused on margin of safety and fundamental analysis",
+            reasoning_depth=reasoning_depth,
+            memory_decay=memory_decay,
+            initial_capital=initial_capital,
+            model_provider=model_provider,
+            model_name=model_name,
+            trace_enabled=trace_enabled,
+        )
+        
+        self.margin_of_safety = margin_of_safety
+        
+        # Value investing specific state
+        self.state.reflective_state.update({
+            'value_detection_threshold': 0.7,
+            'sentiment_skepticism': 0.8,
+            'patience_factor': 0.9,
+            'fundamental_weighting': 0.8,
+            'technical_weighting': 0.2,
+        })
+        
+        # Customize reasoning graph for value investing
+        self._configure_reasoning_graph()
+    
+    def _configure_reasoning_graph(self) -> None:
+        """Configure the reasoning graph with value investing specific nodes."""
+        self.reasoning_graph.add_node(
+            "intrinsic_value_analysis",
+            fn=self._intrinsic_value_analysis
+        )
+        
+        self.reasoning_graph.add_node(
+            "margin_of_safety_evaluation", 
+            fn=self._margin_of_safety_evaluation
+        )
+        
+        self.reasoning_graph.add_node(
+            "fundamental_analysis",
+            fn=self._fundamental_analysis
+        )
+        
+        self.reasoning_graph.add_node(
+            "value_trap_detection",
+            fn=self._value_trap_detection
+        )
+        
+        # Configure value investing reasoning flow
+        self.reasoning_graph.set_entry_point("intrinsic_value_analysis")
+        self.reasoning_graph.add_edge("intrinsic_value_analysis", "margin_of_safety_evaluation")
+        self.reasoning_graph.add_edge("margin_of_safety_evaluation", "fundamental_analysis")
+        self.reasoning_graph.add_edge("fundamental_analysis", "value_trap_detection")
+    
+    def process_market_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process market data through Graham's value investing lens.
+        
+        Focuses on:
+        - Extracting fundamental metrics
+        - Calculating intrinsic value estimates
+        - Identifying margin of safety opportunities
+        - Filtering for value characteristics
+        
+        Args:
+            data: Market data dictionary
+            
+        Returns:
+            Processed market data with value investing insights
+        """
+        processed_data = {
+            'timestamp': datetime.datetime.now(),
+            'tickers': {},
+            'market_sentiment': data.get('market_sentiment', {}),
+            'economic_indicators': data.get('economic_indicators', {}),
+            'insights': [],
+        }
+        
+        # Process each ticker
+        for ticker, ticker_data in data.get('tickers', {}).items():
+            # Extract fundamental metrics
+            fundamentals = ticker_data.get('fundamentals', {})
+            price = ticker_data.get('price', 0)
+            
+            # Skip if insufficient fundamental data
+            if not fundamentals or price == 0:
+                processed_data['tickers'][ticker] = {
+                    'price': price,
+                    'analysis': 'insufficient_data',
+                    'intrinsic_value': None,
+                    'margin_of_safety': None,
+                    'recommendation': 'hold',
+                }
+                continue
+            
+            # Calculate intrinsic value (Graham-style)
+            intrinsic_value = self._calculate_intrinsic_value(fundamentals, ticker_data)
+            
+            # Calculate margin of safety
+            margin_of_safety = (intrinsic_value - price) / intrinsic_value if intrinsic_value > 0 else 0
+            
+            # Determine if it's a value opportunity
+            is_value_opportunity = margin_of_safety >= self.margin_of_safety
+            
+            # Check for value traps
+            value_trap_indicators = self._detect_value_trap_indicators(fundamentals, ticker_data)
+            
+            # Generate value-oriented analysis
+            analysis = self._generate_value_analysis(
+                ticker=ticker,
+                fundamentals=fundamentals,
+                price=price,
+                intrinsic_value=intrinsic_value,
+                margin_of_safety=margin_of_safety,
+                value_trap_indicators=value_trap_indicators
+            )
+            
+            # Store processed ticker data
+            processed_data['tickers'][ticker] = {
+                'price': price,
+                'intrinsic_value': intrinsic_value,
+                'margin_of_safety': margin_of_safety,
+                'is_value_opportunity': is_value_opportunity,
+                'value_trap_risk': len(value_trap_indicators) / 5 if value_trap_indicators else 0,
+                'value_trap_indicators': value_trap_indicators,
+                'analysis': analysis,
+                'recommendation': 'buy' if is_value_opportunity and not value_trap_indicators else 'hold',
+                'fundamentals': fundamentals,
+            }
+            
+            # Generate insight if it's a strong value opportunity
+            if is_value_opportunity and not value_trap_indicators and margin_of_safety > 0.4:
+                processed_data['insights'].append({
+                    'ticker': ticker,
+                    'type': 'strong_value_opportunity',
+                    'margin_of_safety': margin_of_safety,
+                    'intrinsic_value': intrinsic_value,
+                    'current_price': price,
+                })
+        
+        # Run reflective trace if enabled
+        if self.trace_enabled:
+            processed_data['reflection'] = self.execute_command(
+                command="reflect.trace",
+                agent=self.name,
+                depth=self.reasoning_depth
+            )
+        
+        return processed_data
+    
+    def _calculate_intrinsic_value(self, fundamentals: Dict[str, Any], ticker_data: Dict[str, Any]) -> float:
+        """
+        Calculate intrinsic value using Graham's methods.
+        
+        Args:
+            fundamentals: Fundamental metrics dict
+            ticker_data: Complete ticker data
+            
+        Returns:
+            Estimated intrinsic value
+        """
+        # Extract key metrics
+        eps = fundamentals.get('eps', 0)
+        book_value = fundamentals.get('book_value_per_share', 0)
+        growth_rate = fundamentals.get('growth_rate', 0)
+        
+        # Graham's formula: IV = EPS * (8.5 + 2g) * 4.4 / Y
+        # Where g is growth rate and Y is current AAA bond yield
+        # We use a simplified approach here
+        bond_yield = ticker_data.get('economic_indicators', {}).get('aaa_bond_yield', 0.045)
+        bond_factor = 4.4 / max(bond_yield, 0.01)  # Prevent division by zero
+        
+        # Calculate growth-adjusted PE
+        growth_adjusted_pe = 8.5 + (2 * growth_rate)
+        
+        # Calculate earnings-based value
+        earnings_value = eps * growth_adjusted_pe * bond_factor if eps > 0 else 0
+        
+        # Calculate book value with margin
+        book_value_margin = book_value * 1.5  # Graham often looked for stocks below 1.5x book
+        
+        # Use the lower of the two values for conservatism
+        if earnings_value > 0 and book_value_margin > 0:
+            intrinsic_value = min(earnings_value, book_value_margin)
+        else:
+            intrinsic_value = earnings_value if earnings_value > 0 else book_value_margin
+        
+        return max(intrinsic_value, 0)  # Ensure non-negative value
+    
+    def _detect_value_trap_indicators(self, fundamentals: Dict[str, Any], ticker_data: Dict[str, Any]) -> List[str]:
+        """
+        Detect potential value trap indicators.
+        
+        Args:
+            fundamentals: Fundamental metrics dict
+            ticker_data: Complete ticker data
+            
+        Returns:
+            List of value trap indicators
+        """
+        value_trap_indicators = []
+        
+        # Check for declining earnings
+        if fundamentals.get('earnings_growth', 0) < -0.1:
+            value_trap_indicators.append('declining_earnings')
+        
+        # Check for high debt
+        if fundamentals.get('debt_to_equity', 0) > 1.5:
+            value_trap_indicators.append('high_debt')
+        
+        # Check for deteriorating financials
+        if fundamentals.get('return_on_equity', 0) < 0.05:
+            value_trap_indicators.append('low_return_on_equity')
+        
+        # Check for industry decline
+        if ticker_data.get('sector', {}).get('decline', False):
+            value_trap_indicators.append('industry_decline')
+        
+        # Check for negative free cash flow
+        if fundamentals.get('free_cash_flow', 0) < 0:
+            value_trap_indicators.append('negative_cash_flow')
+        
+        return value_trap_indicators
+    
+    def _generate_value_analysis(self, ticker: str, fundamentals: Dict[str, Any], 
+                                price: float, intrinsic_value: float, 
+                                margin_of_safety: float, value_trap_indicators: List[str]) -> str:
+        """
+        Generate value investing analysis summary.
+        
+        Args:
+            ticker: Stock ticker
+            fundamentals: Fundamental metrics
+            price: Current price
+            intrinsic_value: Calculated intrinsic value
+            margin_of_safety: Current margin of safety
+            value_trap_indicators: List of value trap indicators
+            
+        Returns:
+            Analysis summary text
+        """
+        # Format for better readability
+        iv_formatted = f"${intrinsic_value:.2f}"
+        price_formatted = f"${price:.2f}"
+        mos_percentage = f"{margin_of_safety * 100:.1f}%"
+        
+        # Base analysis
+        if margin_of_safety >= self.margin_of_safety:
+            base_analysis = (f"{ticker} appears undervalued. Current price {price_formatted} vs. "
+                           f"intrinsic value estimate {iv_formatted}, providing a "
+                           f"{mos_percentage} margin of safety.")
+        elif margin_of_safety > 0:
+            base_analysis = (f"{ticker} is moderately priced. Current price {price_formatted} vs. "
+                           f"intrinsic value estimate {iv_formatted}, providing only a "
+                           f"{mos_percentage} margin of safety.")
+        else:
+            base_analysis = (f"{ticker} appears overvalued. Current price {price_formatted} vs. "
+                           f"intrinsic value estimate {iv_formatted}, providing no "
+                           f"margin of safety.")
+        
+        # Add value trap indicators if present
+        if value_trap_indicators:
+            trap_text = ", ".join(value_trap_indicators)
+            base_analysis += f" Warning: Potential value trap indicators detected: {trap_text}."
+        
+        # Add fundamental highlights
+        fundamental_highlights = []
+        if fundamentals.get('pe_ratio', 0) > 0:
+            fundamental_highlights.append(f"P/E ratio: {fundamentals.get('pe_ratio', 0):.2f}")
+        if fundamentals.get('price_to_book', 0) > 0:
+            fundamental_highlights.append(f"P/B ratio: {fundamentals.get('price_to_book', 0):.2f}")
+        if fundamentals.get('dividend_yield', 0) > 0:
+            fundamental_highlights.append(f"Dividend yield: {fundamentals.get('dividend_yield', 0) * 100:.2f}%")
+        
+        if fundamental_highlights:
+            base_analysis += " Key metrics: " + ", ".join(fundamental_highlights) + "."
+        
+        return base_analysis
+    
+    def generate_signals(self, processed_data: Dict[str, Any]) -> List[AgentSignal]:
+        """
+        Generate investment signals based on processed value investing analysis.
+        
+        Args:
+            processed_data: Processed market data with value analysis
+            
+        Returns:
+            List of investment signals with attribution
+        """
+        signals = []
+        
+        for ticker, ticker_data in processed_data.get('tickers', {}).items():
+            # Skip if insufficient data
+            if ticker_data.get('analysis') == 'insufficient_data':
+                continue
+            
+            # Determine action based on value characteristics
+            is_value_opportunity = ticker_data.get('is_value_opportunity', False)
+            value_trap_risk = ticker_data.get('value_trap_risk', 0)
+            margin_of_safety = ticker_data.get('margin_of_safety', 0)
+            
+            # Skip if no clear signal
+            if not is_value_opportunity and margin_of_safety <= 0:
+                continue
+            
+            # Determine action
+            if is_value_opportunity and value_trap_risk < 0.3:
+                action = 'buy'
+                # Scale confidence based on margin of safety
+                confidence = min(0.5 + (margin_of_safety * 0.5), 0.95)
+                
+                # Scale quantity based on conviction
+                max_allocation = 0.1  # Max 10% of portfolio in one position
+                allocation = max_allocation * confidence
+                quantity = int((self.current_capital * allocation) / ticker_data.get('price', 1))
+                
+                # Ensure minimum quantity
+                quantity = max(quantity, 1)
+                
+                # Create signal dictionary
+                signal = {
+                    'ticker': ticker,
+                    'action': action,
+                    'confidence': confidence,
+                    'quantity': quantity,
+                    'reasoning': f"Value investment opportunity with {margin_of_safety:.1%} margin of safety. {ticker_data.get('analysis', '')}",
+                    'intent': "Capitalize on identified value opportunity with sufficient margin of safety",
+                    'value_basis': "Intrinsic value significantly exceeds current market price, presenting favorable risk-reward",
+                }
+                
+                signals.append(signal)
+            elif margin_of_safety > 0 and margin_of_safety < self.margin_of_safety and value_trap_risk < 0.2:
+                # Watchlist signal - lower confidence
+                action = 'buy'
+                confidence = 0.3 + (margin_of_safety * 0.3)  # Lower confidence
+                
+                # Smaller position size for watchlist items
+                max_allocation = 0.05  # Max 5% of portfolio 
+                allocation = max_allocation * confidence
+                quantity = int((self.current_capital * allocation) / ticker_data.get('price', 1))
+                
+                # Ensure minimum quantity
+                quantity = max(quantity, 1)
+                
+                # Create signal dictionary
+                signal = {
+                    'ticker': ticker,
+                    'action': action,
+                    'confidence': confidence,
+                    'quantity': quantity,
+                    'reasoning': f"Moderate value opportunity with {margin_of_safety:.1%} margin of safety. {ticker_data.get('analysis', '')}",
+                    'intent': "Establish small position in moderately valued company with potential",
+                    'value_basis': "Price below intrinsic value but insufficient margin of safety for full position",
+                }
+                
+                signals.append(signal)
+        
+        # Apply attribution to signals
+        attributed_signals = self.attribute_signals(signals)
+        
+        # Log trace if enabled
+        if self.trace_enabled:
+            for signal in attributed_signals:
+                self.tracer.record_signal(signal)
+        
+        return attributed_signals
+    
+    # Value investing specific reasoning nodes
+    def _intrinsic_value_analysis(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Analyze intrinsic value of securities.
+        
+        Args:
+            data: Market data
+            
+        Returns:
+            Intrinsic value analysis results
+        """
+        results = {
+            'ticker_valuations': {},
+            'timestamp': datetime.datetime.now(),
+        }
+        
+        for ticker, ticker_data in data.get('tickers', {}).items():
+            fundamentals = ticker_data.get('fundamentals', {})
+            price = ticker_data.get('price', 0)
+            
+            if not fundamentals or price == 0:
+                results['ticker_valuations'][ticker] = {
+                    'intrinsic_value': None,
+                    'status': 'insufficient_data',
+                }
+                continue
+            
+            # Calculate intrinsic value
+            intrinsic_value = self._calculate_intrinsic_value(fundamentals, ticker_data)
+            
+            # Determine valuation status
+            if intrinsic_value > price * 1.3:  # 30% above price
+                status = 'significantly_undervalued'
+            elif intrinsic_value > price * 1.1:  # 10% above price
+                status = 'moderately_undervalued'
+            elif intrinsic_value > price:
+                status = 'slightly_undervalued'
+            elif intrinsic_value > price * 0.9:  # Within 10% below price
+                status = 'fairly_valued'
+            else:
+                status = 'overvalued'
+            
+            results['ticker_valuations'][ticker] = {
+                'intrinsic_value': intrinsic_value,
+                'price': price,
+                'ratio': intrinsic_value / price if price > 0 else 0,
+                'status': status,
+            }
+        
+        return results
+    
+    def _margin_of_safety_evaluation(self, intrinsic_value_results: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Evaluate margin of safety for each security.
+        
+        Args:
+            intrinsic_value_results: Intrinsic value analysis results
+            
+        Returns:
+            Margin of safety evaluation results
+        """
+        results = {
+            'margin_of_safety_analysis': {},
+            'value_opportunities': [],
+            'timestamp': datetime.datetime.now(),
+        }
+        
+        for ticker, valuation in intrinsic_value_results.get('ticker_valuations', {}).items():
+            if valuation.get('status') == 'insufficient_data':
+                continue
+            
+            intrinsic_value = valuation.get('intrinsic_value', 0)
+            price = valuation.get('price', 0)
+            
+            if intrinsic_value <= 0 or price <= 0:
+                continue
+            
+            # Calculate margin of safety
+            margin_of_safety = (intrinsic_value - price) / intrinsic_value
+            
+            # Determine confidence based on margin of safety
+            if margin_of_safety >= self.margin_of_safety:
+                confidence = min(0.5 + (margin_of_safety * 0.5), 0.95)
+                meets_criteria = True
+            else:
+                confidence = max(0.2, margin_of_safety * 2)
+                meets_criteria = False
+            
+            results['margin_of_safety_analysis'][ticker] = {
+                'margin_of_safety': margin_of_safety,
+                'meets_criteria': meets_criteria,
+                'confidence': confidence,
+            }
+            
+            # Add to value opportunities if meets criteria
+            if meets_criteria:
+                results['value_opportunities'].append({
+                    'ticker': ticker,
+                    'margin_of_safety': margin_of_safety,
+                    'confidence': confidence,
+                    'intrinsic_value': intrinsic_value,
+                    'price': price,
+                })
+        
+        # Sort value opportunities by margin of safety
+        results['value_opportunities'] = sorted(
+            results['value_opportunities'],
+            key=lambda x: x['margin_of_safety'],
+            reverse=True
+        )
+        
+        return results
+    
+    def _fundamental_analysis(self, safety_results: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Perform fundamental analysis on value opportunities.
+        
+        Args:
+            safety_results: Margin of safety evaluation results
+            
+        Returns:
+            Fundamental analysis results
+        """
+        results = {
+            'fundamental_quality': {},
+            'quality_ranking': [],
+            'timestamp': datetime.datetime.now(),
+        }
+        
+        # Process each value opportunity
+        for opportunity in safety_results.get('value_opportunities', []):
+            ticker = opportunity.get('ticker')
+            
+            # Get ticker data from state
+            ticker_data = self.state.working_memory.get('market_data', {}).get('tickers', {}).get(ticker, {})
+            fundamentals = ticker_data.get('fundamentals', {})
+            
+            if not fundamentals:
+                continue
+            
+            # Calculate fundamental quality score
+            quality_score = self._calculate_fundamental_quality(fundamentals)
+            
+            # Store fundamental quality
+            results['fundamental_quality'][ticker] = {
+                'quality_score': quality_score,
+                'roe': fundamentals.get('return_on_equity', 0),
+                'debt_to_equity': fundamentals.get('debt_to_equity', 0),
+                'current_ratio': fundamentals.get('current_ratio', 0),
+                'free_cash_flow': fundamentals.get('free_cash_flow', 0),
+                'dividend_history': fundamentals.get('dividend_history', []),
+            }
+            
+            # Add to quality ranking
+            results['quality_ranking'].append({
+                'ticker': ticker,
+                'quality_score': quality_score,
+                'margin_of_safety': opportunity.get('margin_of_safety', 0),
+                # Combined score weights both quality and value
+                'combined_score': quality_score * 0.4 + opportunity.get('margin_of_safety', 0) * 0.6,
+            })
+        
+        # Sort quality ranking by combined score
+        results['quality_ranking'] = sorted(
+            results['quality_ranking'],
+            key=lambda x: x['combined_score'],
+            reverse=True
+        )
+        
+        return results
+    
+    def _calculate_fundamental_quality(self, fundamentals: Dict[str, Any]) -> float:
+        """
+        Calculate fundamental quality score.
+        
+        Args:
+            fundamentals: Fundamental metrics
+            
+        Returns:
+            Quality score (0-1)
+        """
+        # Initialize score
+        score = 0.5  # Start at neutral
+        
+        # Factor 1: Return on Equity (higher is better)
+        roe = fundamentals.get('return_on_equity', 0)
+        if roe > 0.2:  # Excellent ROE
+            score += 0.1
+        elif roe > 0.15:  # Very good ROE
+            score += 0.075
+        elif roe > 0.1:  # Good ROE
+            score += 0.05
+        elif roe < 0.05:  # Poor ROE
+            score -= 0.05
+        elif roe < 0:  # Negative ROE
+            score -= 0.1
+        
+        # Factor 2: Debt to Equity (lower is better)
+        debt_to_equity = fundamentals.get('debt_to_equity', 0)
+        if debt_to_equity < 0.3:  # Very low debt
+            score += 0.1
+        elif debt_to_equity < 0.5:  # Low debt
+            score += 0.05
+        elif debt_to_equity > 1.0:  # High debt
+            score -= 0.05
+        elif debt_to_equity > 1.5:  # Very high debt
+            score -= 0.1
+        
+        # Factor 3: Current Ratio (higher is better)
+        current_ratio = fundamentals.get('current_ratio', 0)
+        if current_ratio > 3:  # Excellent liquidity
+            score += 0.075
+        elif current_ratio > 2:  # Very good liquidity
+            score += 0.05
+        elif current_ratio > 1.5:  # Good liquidity
+            score += 0.025
+        elif current_ratio < 1:  # Poor liquidity
+            score -= 0.1
+        
+        # Factor 4: Free Cash Flow (positive is better)
+        fcf = fundamentals.get('free_cash_flow', 0)
+        if fcf > 0:  # Positive FCF
+            score += 0.075
+        else:  # Negative FCF
+            score -= 0.1
+        
+        # Factor 5: Dividend History (consistent is better)
+            dividend_history = fundamentals.get('dividend_history', [])
+            if len(dividend_history) >= 5 and all(d > 0 for d in dividend_history):
+                # Consistent dividends for 5+ years
+                score += 0.075
+            elif len(dividend_history) >= 3 and all(d > 0 for d in dividend_history):
+                # Consistent dividends for 3+ years
+                score += 0.05
+            
+        # Ensure score is between 0 and 1
+        return max(0, min(1, score))
+    
+    def _value_trap_detection(self, fundamental_results: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Detect potential value traps among value opportunities.
+        
+        Args:
+            fundamental_results: Fundamental analysis results
+            
+        Returns:
+            Value trap detection results
+        """
+        results = {
+            'value_trap_analysis': {},
+            'safe_opportunities': [],
+            'timestamp': datetime.datetime.now(),
+        }
+        
+        # Process each quality-ranked opportunity
+        for opportunity in fundamental_results.get('quality_ranking', []):
+            ticker = opportunity.get('ticker')
+            
+            # Get ticker data from state
+            ticker_data = self.state.working_memory.get('market_data', {}).get('tickers', {}).get(ticker, {})
+            fundamentals = ticker_data.get('fundamentals', {})
+            
+            if not fundamentals:
+                continue
+            
+            # Detect value trap indicators
+            value_trap_indicators = self._detect_value_trap_indicators(fundamentals, ticker_data)
+            value_trap_risk = len(value_trap_indicators) / 5 if value_trap_indicators else 0
+            
+            # Store value trap analysis
+            results['value_trap_analysis'][ticker] = {
+                'value_trap_risk': value_trap_risk,
+                'value_trap_indicators': value_trap_indicators,
+                'quality_score': opportunity.get('quality_score', 0),
+                'margin_of_safety': opportunity.get('margin_of_safety', 0),
+                'combined_score': opportunity.get('combined_score', 0),
+            }
+            
+            # Add to safe opportunities if low value trap risk
+            if value_trap_risk < 0.3:
+                results['safe_opportunities'].append({
+                    'ticker': ticker,
+                    'value_trap_risk': value_trap_risk,
+                    'quality_score': opportunity.get('quality_score', 0),
+                    'margin_of_safety': opportunity.get('margin_of_safety', 0),
+                    'combined_score': opportunity.get('combined_score', 0),
+                })
+        
+        # Sort safe opportunities by combined score
+        results['safe_opportunities'] = sorted(
+            results['safe_opportunities'],
+            key=lambda x: x['combined_score'],
+            reverse=True
+        )
+        
+        return results
+
+    def run_analysis_shell(self, market_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Run a complete analysis shell for Graham value criteria.
+        
+        This method implements a full CIRCUIT-FRAGMENT shell for detecting
+        undervalued assets and NULL-FEATURE shell for knowledge boundaries.
+        
+        Args:
+            market_data: Raw market data
+            
+        Returns:
+            Complete value analysis results
+        """
+        # Store market data in working memory for value trap detection
+        self.state.working_memory['market_data'] = market_data
+        
+        # Process market data (external interface)
+        processed_data = self.process_market_data(market_data)
+        
+        # Run reasoning graph (internal pipeline)
+        initial_results = {'tickers': processed_data.get('tickers', {})}
+        
+        intrinsic_value_results = self._intrinsic_value_analysis(initial_results)
+        safety_results = self._margin_of_safety_evaluation(intrinsic_value_results)
+        fundamental_results = self._fundamental_analysis(safety_results)
+        trap_results = self._value_trap_detection(fundamental_results)
+        
+        # Compile complete results
+        complete_results = {
+            'processed_data': processed_data,
+            'intrinsic_value_results': intrinsic_value_results,
+            'safety_results': safety_results,
+            'fundamental_results': fundamental_results,
+            'trap_results': trap_results,
+            'final_recommendations': trap_results.get('safe_opportunities', []),
+            'timestamp': datetime.datetime.now(),
+        }
+        
+        # Check for collapse conditions
+        collapse_check = self.execute_command(
+            command="collapse.detect",
+            threshold=0.7,
+            reason="consistency"
+        )
+        
+        if collapse_check.get('collapse_detected', False):
+            complete_results['warnings'] = {
+                'collapse_detected': True,
+                'collapse_reasons': collapse_check.get('collapse_reasons', {}),
+                'message': "Potential inconsistency detected in value analysis process.",
+            }
+        
+        return complete_results
+    
+    def adjust_strategy(self, performance_metrics: Dict[str, Any]) -> None:
+        """
+        Adjust Graham strategy based on performance feedback.
+        
+        Args:
+            performance_metrics: Dictionary with performance metrics
+        """
+        # Extract relevant metrics
+        win_rate = performance_metrics.get('win_rate', 0.5)
+        avg_return = performance_metrics.get('avg_return', 0)
+        max_drawdown = performance_metrics.get('max_drawdown', 0)
+        
+        # Adjust margin of safety based on win rate
+        if win_rate < 0.4:  # Poor win rate
+            self.margin_of_safety = min(self.margin_of_safety + 0.05, 0.5)  # Increase safety margin
+        elif win_rate > 0.7:  # Excellent win rate
+            self.margin_of_safety = max(self.margin_of_safety - 0.05, 0.2)  # Can be less conservative
+        
+        # Adjust value detection threshold based on returns
+        if avg_return < -0.05:  # Significant negative returns
+            self.state.reflective_state['value_detection_threshold'] = min(
+                self.state.reflective_state.get('value_detection_threshold', 0.7) + 0.05, 
+                0.9
+            )
+        elif avg_return > 0.1:  # Strong positive returns
+            self.state.reflective_state['value_detection_threshold'] = max(
+                self.state.reflective_state.get('value_detection_threshold', 0.7) - 0.05,
+                0.6
+            )
+        
+        # Adjust sentiment skepticism based on drawdown
+        if max_drawdown > 0.15:  # Large drawdown
+            self.state.reflective_state['sentiment_skepticism'] = min(
+                self.state.reflective_state.get('sentiment_skepticism', 0.8) + 0.05,
+                0.95
+            )
+        
+        # Update drift vector
+        drift_vector = {
+            'margin_of_safety': self.margin_of_safety - 0.3,  # Drift from initial value
+            'value_detection': self.state.reflective_state.get('value_detection_threshold', 0.7) - 0.7,
+            'sentiment_skepticism': self.state.reflective_state.get('sentiment_skepticism', 0.8) - 0.8,
+        }
+        
+        # Observe drift for interpretability
+        self.execute_command(
+            command="drift.observe",
+            vector=drift_vector,
+            bias=0.0
+        )
+    
+    def __repr__(self) -> str:
+        """Generate string representation of Graham agent."""
+        return f"Graham Value Agent (MoS: {self.margin_of_safety:.2f}, Depth: {self.reasoning_depth})"
+      

src/cognition/attribution.py

@@ -0,0 +1,755 @@
+"""
+AttributionTracer - Decision Provenance and Causal Tracing Framework
+
+This module implements the attribution tracing architecture that enables
+transparent decision provenance for all agents in the AGI-HEDGE-FUND system.
+
+Key capabilities:
+- Multi-level attribution across reasoning chains
+- Causal tracing from decision back to evidence
+- Confidence weighting of attribution factors
+- Value-weighted attribution alignment
+- Attribution visualization for interpretability
+
+Internal Note: The attribution tracer encodes the ECHO-ATTRIBUTION and ATTRIBUTION-REFLECT
+interpretability shells for causal path tracing and attribution transparency.
+"""
+
+import datetime
+import uuid
+import math
+from typing import Dict, List, Any, Optional, Tuple, Set
+import numpy as np
+from collections import defaultdict
+
+from pydantic import BaseModel, Field
+
+
+class AttributionEntry(BaseModel):
+    """Single attribution entry linking a decision to a cause."""
+    
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    source: str = Field(...)  # Source ID (e.g., memory ID, evidence ID)
+    source_type: str = Field(...)  # Type of source (e.g., "memory", "evidence", "reasoning")
+    target: str = Field(...)  # Target ID (e.g., decision ID, reasoning step)
+    weight: float = Field(default=1.0)  # Attribution weight (0-1)
+    confidence: float = Field(default=1.0)  # Confidence in attribution (0-1)
+    timestamp: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    description: Optional[str] = Field(default=None)  # Optional attribution description
+    value_alignment: Optional[float] = Field(default=None)  # Alignment with agent values (0-1)
+
+
+class AttributionChain(BaseModel):
+    """Chain of attribution entries forming a causal path."""
+    
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    entries: List[AttributionEntry] = Field(default_factory=list)
+    start_point: str = Field(...)  # ID of chain origin
+    end_point: str = Field(...)  # ID of chain destination
+    total_weight: float = Field(default=1.0)  # Product of weights along chain
+    confidence: float = Field(default=1.0)  # Overall chain confidence
+    timestamp: datetime.datetime = Field(default_factory=datetime.datetime.now)
+
+
+class AttributionGraph(BaseModel):
+    """Complete attribution graph for a decision."""
+    
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    decision_id: str = Field(...)  # ID of the decision being attributed
+    chains: List[AttributionChain] = Field(default_factory=list)
+    sources: Dict[str, Dict[str, Any]] = Field(default_factory=dict)  # Source metadata
+    timestamp: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    
+    def add_chain(self, chain: AttributionChain) -> None:
+        """Add attribution chain to graph."""
+        self.chains.append(chain)
+    
+    def add_source(self, source_id: str, metadata: Dict[str, Any]) -> None:
+        """Add source metadata to graph."""
+        self.sources[source_id] = metadata
+    
+    def calculate_source_contributions(self) -> Dict[str, float]:
+        """Calculate normalized contribution of each source to decision."""
+        # Initialize contributions
+        contributions = defaultdict(float)
+        
+        # Sum weights from all chains
+        for chain in self.chains:
+            for entry in chain.entries:
+                # Add contribution weighted by chain confidence
+                contributions[entry.source] += entry.weight * chain.confidence
+        
+        # Normalize contributions
+        total = sum(contributions.values())
+        if total > 0:
+            for source in contributions:
+                contributions[source] /= total
+        
+        return dict(contributions)
+
+
+class AttributionTracer:
+    """
+    Attribution tracing engine for causal decision provenance.
+    
+    Enables:
+    - Tracing the causal path from decisions back to evidence
+    - Weighting attribution factors by confidence and relevance
+    - Aligning attribution with agent value system
+    - Visualizing attribution patterns for interpretability
+    """
+    
+    def __init__(self):
+        """Initialize attribution tracer."""
+        self.attribution_history: Dict[str, AttributionGraph] = {}
+        self.trace_registry: Dict[str, Dict[str, Any]] = {}
+        self.value_weights: Dict[str, float] = {}
+    
+    def trace_attribution(self, signal: Dict[str, Any], agent_state: Dict[str, Any],
+                       reasoning_depth: int = 3) -> Dict[str, Any]:
+        """
+        Trace attribution for a decision signal.
+        
+        Args:
+            signal: Decision signal
+            agent_state: Agent's current state
+            reasoning_depth: Depth of attribution tracing
+            
+        Returns:
+            Attribution trace results
+        """
+        # Generate decision ID if not present
+        decision_id = signal.get("signal_id", str(uuid.uuid4()))
+        
+        # Create attribution graph
+        attribution_graph = AttributionGraph(
+            decision_id=decision_id,
+        )
+        
+        # Extract signal components for attribution
+        ticker = signal.get("ticker", "")
+        action = signal.get("action", "")
+        confidence = signal.get("confidence", 0.5)
+        reasoning = signal.get("reasoning", "")
+        intent = signal.get("intent", "")
+        value_basis = signal.get("value_basis", "")
+        
+        # Extract evidence sources from agent state
+        evidence_sources = self._extract_evidence_sources(agent_state, ticker, action)
+        
+        # Process reasoning to extract reasoning steps
+        reasoning_steps = self._extract_reasoning_steps(reasoning)
+        
+        # Generate attribution chains
+        chains = self._generate_attribution_chains(
+            decision_id=decision_id,
+            evidence_sources=evidence_sources,
+            reasoning_steps=reasoning_steps,
+            intent=intent,
+            value_basis=value_basis,
+            confidence=confidence,
+            reasoning_depth=reasoning_depth
+        )
+        
+        # Add chains to graph
+        for chain in chains:
+            attribution_graph.add_chain(chain)
+        
+        # Add source metadata
+        for source_id, metadata in evidence_sources.items():
+            attribution_graph.add_source(source_id, metadata)
+        
+        # Calculate source contributions
+        source_contributions = attribution_graph.calculate_source_contributions()
+        
+        # Store in history
+        # Store in history
+        self.attribution_history[decision_id] = attribution_graph
+        
+        # Prepare result
+        trace_id = str(uuid.uuid4())
+        
+        # Store trace in registry
+        self.trace_registry[trace_id] = {
+            "attribution_graph": attribution_graph,
+            "decision_id": decision_id,
+            "timestamp": datetime.datetime.now(),
+        }
+        
+        # Create attribution trace output
+        attribution_trace = {
+            "trace_id": trace_id,
+            "decision_id": decision_id,
+            "attribution_map": source_contributions,
+            "confidence": confidence,
+            "top_factors": self._get_top_attribution_factors(source_contributions, 5),
+            "value_alignment": self._calculate_value_alignment(value_basis, source_contributions),
+            "reasoning_depth": reasoning_depth,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return attribution_trace
+    
+    def _extract_evidence_sources(self, agent_state: Dict[str, Any], 
+                               ticker: str, action: str) -> Dict[str, Dict[str, Any]]:
+        """
+        Extract evidence sources from agent state.
+        
+        Args:
+            agent_state: Agent's current state
+            ticker: Stock ticker
+            action: Decision action
+            
+        Returns:
+            Dictionary of evidence sources
+        """
+        evidence_sources = {}
+        
+        # Extract from belief state
+        belief_state = agent_state.get("belief_state", {})
+        if ticker in belief_state:
+            source_id = f"belief:{ticker}"
+            evidence_sources[source_id] = {
+                "type": "belief",
+                "ticker": ticker,
+                "value": belief_state[ticker],
+                "description": f"Belief about {ticker}",
+            }
+        
+        # Extract from working memory
+        working_memory = agent_state.get("working_memory", {})
+        
+        # Check for ticker-specific data in working memory
+        if ticker in working_memory:
+            source_id = f"working_memory:{ticker}"
+            evidence_sources[source_id] = {
+                "type": "working_memory",
+                "ticker": ticker,
+                "data": working_memory[ticker],
+                "description": f"Current analysis of {ticker}",
+            }
+        
+        # Extract from performance trace if action is based on past performance
+        performance_trace = agent_state.get("performance_trace", {})
+        if ticker in performance_trace:
+            source_id = f"performance:{ticker}"
+            evidence_sources[source_id] = {
+                "type": "performance",
+                "ticker": ticker,
+                "performance": performance_trace[ticker],
+                "description": f"Performance history of {ticker}",
+            }
+        
+        # Extract from decision history
+        decision_history = agent_state.get("decision_history", [])
+        for i, decision in enumerate(decision_history):
+            if decision.get("ticker") == ticker and decision.get("action") == action:
+                source_id = f"past_decision:{i}:{ticker}"
+                evidence_sources[source_id] = {
+                    "type": "past_decision",
+                    "ticker": ticker,
+                    "action": action,
+                    "decision": decision,
+                    "description": f"Past {action} decision for {ticker}",
+                }
+        
+        return evidence_sources
+    
+    def _extract_reasoning_steps(self, reasoning: str) -> List[Dict[str, Any]]:
+        """
+        Extract reasoning steps from reasoning string.
+        
+        Args:
+            reasoning: Reasoning string
+            
+        Returns:
+            List of reasoning steps
+        """
+        # Simple implementation: split by periods or line breaks
+        sentences = [s.strip() for s in reasoning.replace('\n', '. ').split('.') if s.strip()]
+        
+        reasoning_steps = []
+        for i, sentence in enumerate(sentences):
+            step_id = f"step:{i}"
+            reasoning_steps.append({
+                "id": step_id,
+                "text": sentence,
+                "position": i,
+                "type": "reasoning_step",
+            })
+        
+        return reasoning_steps
+    
+    def _generate_attribution_chains(self, decision_id: str, evidence_sources: Dict[str, Dict[str, Any]],
+                                  reasoning_steps: List[Dict[str, Any]], intent: str, value_basis: str,
+                                  confidence: float, reasoning_depth: int) -> List[AttributionChain]:
+        """
+        Generate attribution chains linking decision to evidence.
+        
+        Args:
+            decision_id: Decision ID
+            evidence_sources: Evidence sources
+            reasoning_steps: Reasoning steps
+            intent: Decision intent
+            value_basis: Value basis for decision
+            confidence: Decision confidence
+            reasoning_depth: Depth of attribution tracing
+            
+        Returns:
+            List of attribution chains
+        """
+        attribution_chains = []
+        
+        # Define end point (the decision itself)
+        end_point = decision_id
+        
+        # Case 1: Direct evidence -> decision chains
+        for source_id, source_data in evidence_sources.items():
+            # Create entry linking evidence directly to decision
+            entry = AttributionEntry(
+                source=source_id,
+                source_type=source_data.get("type", "evidence"),
+                target=decision_id,
+                weight=self._calculate_evidence_weight(source_data, confidence),
+                confidence=confidence,
+                description=f"Direct influence of {source_data.get('description', source_id)} on decision",
+            )
+            
+            # Create chain
+            chain = AttributionChain(
+                entries=[entry],
+                start_point=source_id,
+                end_point=end_point,
+                total_weight=entry.weight,
+                confidence=entry.confidence,
+            )
+            
+            attribution_chains.append(chain)
+        
+        # Case 2: Evidence -> reasoning -> decision chains
+        if reasoning_steps:
+            # For each evidence source
+            for source_id, source_data in evidence_sources.items():
+                # For relevant reasoning steps (limited by depth)
+                for step in reasoning_steps[:reasoning_depth]:
+                    # Create entry linking evidence to reasoning step
+                    step_entry = AttributionEntry(
+                        source=source_id,
+                        source_type=source_data.get("type", "evidence"),
+                        target=step["id"],
+                        weight=self._calculate_step_relevance(source_data, step),
+                        confidence=confidence * 0.9,  # Slightly lower confidence for indirect paths
+                        description=f"Influence of {source_data.get('description', source_id)} on reasoning step",
+                    )
+                    
+                    # Create entry linking reasoning step to decision
+                    decision_entry = AttributionEntry(
+                        source=step["id"],
+                        source_type="reasoning_step",
+                        target=decision_id,
+                        weight=self._calculate_step_importance(step, len(reasoning_steps)),
+                        confidence=confidence,
+                        description=f"Influence of reasoning step on decision",
+                    )
+                    
+                    # Create chain
+                    chain = AttributionChain(
+                        entries=[step_entry, decision_entry],
+                        start_point=source_id,
+                        end_point=end_point,
+                        total_weight=step_entry.weight * decision_entry.weight,
+                        confidence=min(step_entry.confidence, decision_entry.confidence),
+                    )
+                    
+                    attribution_chains.append(chain)
+        
+        # Case 3: Intent/value -> decision chains
+        if intent:
+            intent_id = f"intent:{intent[:20]}"
+            intent_entry = AttributionEntry(
+                source=intent_id,
+                source_type="intent",
+                target=decision_id,
+                weight=0.8,  # High weight for intent
+                confidence=confidence,
+                description=f"Influence of stated intent on decision",
+            )
+            
+            intent_chain = AttributionChain(
+                entries=[intent_entry],
+                start_point=intent_id,
+                end_point=end_point,
+                total_weight=intent_entry.weight,
+                confidence=intent_entry.confidence,
+            )
+            
+            attribution_chains.append(intent_chain)
+        
+        if value_basis:
+            value_id = f"value:{value_basis[:20]}"
+            value_entry = AttributionEntry(
+                source=value_id,
+                source_type="value",
+                target=decision_id,
+                weight=0.9,  # Very high weight for value basis
+                confidence=confidence,
+                description=f"Influence of value basis on decision",
+                value_alignment=1.0,  # Perfect alignment with its own value
+            )
+            
+            value_chain = AttributionChain(
+                entries=[value_entry],
+                start_point=value_id,
+                end_point=end_point,
+                total_weight=value_entry.weight,
+                confidence=value_entry.confidence,
+            )
+            
+            attribution_chains.append(value_chain)
+        
+        return attribution_chains
+    
+    def _calculate_evidence_weight(self, evidence: Dict[str, Any], base_confidence: float) -> float:
+        """
+        Calculate weight of evidence.
+        
+        Args:
+            evidence: Evidence data
+            base_confidence: Base confidence level
+            
+        Returns:
+            Evidence weight
+        """
+        # Default weight
+        weight = 0.5
+        
+        # Adjust based on evidence type
+        evidence_type = evidence.get("type", "")
+        
+        if evidence_type == "belief":
+            # Weight based on belief strength (0.5-1.0)
+            belief_value = evidence.get("value", 0.5)
+            weight = 0.5 + (abs(belief_value - 0.5) * 0.5)
+        
+        elif evidence_type == "working_memory":
+            # Working memory has high weight
+            weight = 0.8
+        
+        elif evidence_type == "performance":
+            # Performance data moderately important
+            weight = 0.7
+        
+        elif evidence_type == "past_decision":
+            # Past decisions less important
+            weight = 0.6
+        
+        # Scale by confidence
+        weight *= base_confidence
+        
+        return min(1.0, weight)
+    
+    def _calculate_step_relevance(self, evidence: Dict[str, Any], step: Dict[str, Any]) -> float:
+        """
+        Calculate relevance of evidence to reasoning step.
+        
+        Args:
+            evidence: Evidence data
+            step: Reasoning step
+            
+        Returns:
+            Relevance weight
+        """
+        # Basic implementation using text overlap
+        evidence_desc = evidence.get("description", "")
+        step_text = step.get("text", "")
+        
+        # Check for ticker mention
+        ticker = evidence.get("ticker", "")
+        if ticker and ticker in step_text:
+            return 0.8
+        
+        # Check for word overlap
+        evidence_words = set(evidence_desc.lower().split())
+        step_words = set(step_text.lower().split())
+        
+        overlap = len(evidence_words.intersection(step_words))
+        total_words = len(evidence_words.union(step_words))
+        
+        if total_words > 0:
+            overlap_ratio = overlap / total_words
+            return min(1.0, 0.5 + overlap_ratio)
+        
+        return 0.5
+    
+    def _calculate_step_importance(self, step: Dict[str, Any], total_steps: int) -> float:
+        """
+        Calculate importance of reasoning step.
+        
+        Args:
+            step: Reasoning step
+            total_steps: Total number of steps
+            
+        Returns:
+            Importance weight
+        """
+        # Position-based importance (later steps slightly more important)
+        position = step.get("position", 0)
+        position_weight = 0.5 + (position / (2 * total_steps)) if total_steps > 0 else 0.5
+        
+        # Length-based importance (longer steps slightly more important)
+        text = step.get("text", "")
+        length = len(text)
+        length_weight = min(1.0, 0.5 + (length / 200))  # Cap at 1.0
+        
+        # Combine weights
+        return (position_weight * 0.7) + (length_weight * 0.3)
+    
+    def _get_top_attribution_factors(self, source_contributions: Dict[str, float], limit: int = 5) -> List[Dict[str, Any]]:
+        """
+        Get top attribution factors.
+        
+        Args:
+            source_contributions: Source contribution dictionary
+            limit: Maximum number of factors to return
+            
+        Returns:
+            List of top attribution factors
+        """
+        # Sort contributions by weight (descending)
+        sorted_contributions = sorted(
+            source_contributions.items(),
+            key=lambda x: x[1],
+            reverse=True
+        )
+        
+        # Take top 'limit' contributions
+        top_factors = []
+        for source, weight in sorted_contributions[:limit]:
+            # Parse source type from ID
+            source_type = source.split(":", 1)[0] if ":" in source else "unknown"
+            
+            top_factors.append({
+                "source": source,
+                "type": source_type,
+                "weight": weight,
+            })
+        
+        return top_factors
+    
+    def _calculate_value_alignment(self, value_basis: str, source_contributions: Dict[str, float]) -> float:
+        """
+        Calculate value alignment score.
+        
+        Args:
+            value_basis: Value basis string
+            source_contributions: Source contribution dictionary
+            
+        Returns:
+            Value alignment score
+        """
+        # Simple implementation: check if value sources have high contribution
+        value_alignment = 0.5  # Default neutral alignment
+        
+        # Find value-based sources
+        value_sources = [source for source in source_contributions if source.startswith("value:")]
+        
+        if value_sources:
+            # Calculate contribution of value sources
+            value_contribution = sum(source_contributions[source] for source in value_sources)
+            
+            # Value alignment increases with value contribution
+            value_alignment = 0.5 + (value_contribution * 0.5)
+        
+        return min(1.0, value_alignment)
+    
+    def get_trace(self, trace_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get attribution trace by ID.
+        
+        Args:
+            trace_id: Trace ID
+            
+        Returns:
+            Attribution trace or None if not found
+        """
+        if trace_id not in self.trace_registry:
+            return None
+        
+        trace_data = self.trace_registry[trace_id]
+        attribution_graph = trace_data.get("attribution_graph")
+        
+        if not attribution_graph:
+            return None
+        
+        # Calculate source contributions
+        source_contributions = attribution_graph.calculate_source_contributions()
+        
+        # Create attribution trace output
+        attribution_trace = {
+            "trace_id": trace_id,
+            "decision_id": attribution_graph.decision_id,
+            "attribution_map": source_contributions,
+            "top_factors": self._get_top_attribution_factors(source_contributions, 5),
+            "chains": len(attribution_graph.chains),
+            "sources": len(attribution_graph.sources),
+            "timestamp": trace_data.get("timestamp", datetime.datetime.now()).isoformat(),
+        }
+        
+        return attribution_trace
+    
+    def get_decision_traces(self, decision_id: str) -> List[str]:
+        """
+        Get trace IDs for a decision.
+        
+        Args:
+            decision_id: Decision ID
+            
+        Returns:
+            List of trace IDs
+        """
+        return [trace_id for trace_id, trace_data in self.trace_registry.items()
+              if trace_data.get("decision_id") == decision_id]
+    
+    def visualize_attribution(self, trace_id: str) -> Dict[str, Any]:
+        """
+        Generate attribution visualization data.
+        
+        Args:
+            trace_id: Trace ID
+            
+        Returns:
+            Visualization data
+        """
+        if trace_id not in self.trace_registry:
+            return {"error": "Trace not found"}
+        
+        trace_data = self.trace_registry[trace_id]
+        attribution_graph = trace_data.get("attribution_graph")
+        
+        if not attribution_graph:
+            return {"error": "Attribution graph not found"}
+        
+        # Create nodes and links for visualization
+        nodes = []
+        links = []
+        
+        # Add decision node
+        decision_id = attribution_graph.decision_id
+        nodes.append({
+            "id": decision_id,
+            "type": "decision",
+            "label": "Decision",
+            "size": 15,
+        })
+        
+        # Process all chains
+        for chain_idx, chain in enumerate(attribution_graph.chains):
+            # Add source node if not already added
+            source_id = chain.start_point
+            if not any(node["id"] == source_id for node in nodes):
+                # Determine source type
+                source_type = "unknown"
+                if source_id.startswith("belief:"):
+                    source_type = "belief"
+                elif source_id.startswith("working_memory:"):
+                    source_type = "working_memory"
+                elif source_id.startswith("performance:"):
+                    source_type = "performance"
+                elif source_id.startswith("past_decision:"):
+                    source_type = "past_decision"
+                elif source_id.startswith("intent:"):
+                    source_type = "intent"
+                elif source_id.startswith("value:"):
+                    source_type = "value"
+                
+                # Add source node
+                nodes.append({
+                    "id": source_id,
+                    "type": source_type,
+                    "label": source_id.split(":", 1)[1] if ":" in source_id else source_id,
+                    "size": 10,
+                })
+            
+            # Process chain entries
+            prev_node_id = None
+            for entry_idx, entry in enumerate(chain.entries):
+                source_node_id = entry.source
+                target_node_id = entry.target
+                
+                # Add intermediate nodes if not already added
+                if entry.source_type == "reasoning_step" and not any(node["id"] == source_node_id for node in nodes):
+                    nodes.append({
+                        "id": source_node_id,
+                        "type": "reasoning_step",
+                        "label": f"Step {source_node_id.split(':', 1)[1] if ':' in source_node_id else source_node_id}",
+                        "size": 8,
+                    })
+                
+                # Add link
+                links.append({
+                    "source": source_node_id,
+                    "target": target_node_id,
+                    "value": entry.weight,
+                    "confidence": entry.confidence,
+                    "label": entry.description if entry.description else f"Weight: {entry.weight:.2f}",
+                })
+                
+                prev_node_id = target_node_id
+        
+        # Create visualization data
+        visualization = {
+            "nodes": nodes,
+            "links": links,
+            "trace_id": trace_id,
+            "decision_id": decision_id,
+        }
+        
+        return visualization
+    
+    def set_value_weights(self, value_weights: Dict[str, float]) -> None:
+        """
+        Set weights for different values.
+        
+        Args:
+            value_weights: Dictionary mapping value names to weights
+        """
+        self.value_weights = value_weights.copy()
+    
+    def clear_history(self, before_timestamp: Optional[datetime.datetime] = None) -> int:
+        """
+        Clear attribution history.
+        
+        Args:
+            before_timestamp: Optional timestamp to clear history before
+            
+        Returns:
+            Number of entries cleared
+        """
+        if before_timestamp is None:
+            # Clear all history
+            count = len(self.attribution_history)
+            self.attribution_history = {}
+            self.trace_registry = {}
+            return count
+        
+        # Clear history before timestamp
+        to_remove_history = []
+        to_remove_registry = []
+        
+        for decision_id, graph in self.attribution_history.items():
+            if graph.timestamp < before_timestamp:
+                to_remove_history.append(decision_id)
+        
+        for trace_id, trace_data in self.trace_registry.items():
+            if trace_data.get("timestamp", datetime.datetime.now()) < before_timestamp:
+                to_remove_registry.append(trace_id)
+        
+        # Remove from history
+        for decision_id in to_remove_history:
+            del self.attribution_history[decision_id]
+        
+        # Remove from registry
+        for trace_id in to_remove_registry:
+            del self.trace_registry[trace_id]
+        
+        return len(to_remove_history) + len(to_remove_registry)

src/cognition/graph.py

@@ -0,0 +1,1111 @@
+"""
+ReasoningGraph - Recursive Cognitive Architecture
+
+This module implements the core reasoning graph architecture that powers
+the recursive cognition capabilities of AGI-HEDGE-FUND agents.
+
+Key components:
+- LangGraph-based reasoning networks
+- Recursive thought paths with configurable depth
+- Attribution tracing throughout reasoning chains
+- Symbolic state propagation across reasoning steps
+- Failsafe mechanisms for reasoning collapse
+
+Internal Note: This implementation is inspired by circuit interpretability research,
+simulating recursive attention pathways via LangGraph. The core patterns
+encode .p/ command equivalents like reflect.trace and collapse.detect.
+"""
+
+import datetime
+import uuid
+import logging
+from typing import Dict, List, Any, Optional, Callable, Tuple, Union, Set
+import numpy as np
+
+# LangGraph for reasoning graphs
+from langgraph.graph import StateGraph, END
+from langgraph.prebuilt import ToolNode, ToolExecutor
+
+# For type hints
+from pydantic import BaseModel, Field
+
+# Internal imports
+from ..llm.router import ModelRouter
+from ..utils.diagnostics import TracingTools
+
+
+class ReasoningState(BaseModel):
+    """Reasoning state carried through graph execution."""
+    
+    # Input data and context
+    input: Dict[str, Any] = Field(default_factory=dict)
+    context: Dict[str, Any] = Field(default_factory=dict)
+    
+    # Reasoning chain and attribution
+    steps: List[Dict[str, Any]] = Field(default_factory=list)
+    attribution: Dict[str, Dict[str, float]] = Field(default_factory=dict)
+    
+    # Execution metadata
+    depth: int = Field(default=0)
+    max_depth: int = Field(default=3)
+    start_time: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    elapsed_ms: int = Field(default=0)
+    
+    # Results and conclusions
+    output: Dict[str, Any] = Field(default_factory=dict)
+    confidence: float = Field(default=0.5)
+    
+    # Error handling and diagnostics
+    errors: List[Dict[str, Any]] = Field(default_factory=list)
+    warnings: List[Dict[str, Any]] = Field(default_factory=list)
+    
+    # Collapse detection
+    collapse_risk: float = Field(default=0.0)
+    collapse_detected: bool = Field(default=False)
+    collapse_reason: Optional[str] = Field(default=None)
+    
+    # Tracing
+    trace_enabled: bool = Field(default=False)
+    trace_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+
+
+class ReasoningGraph:
+    """
+    Implements a recursive reasoning architecture for agent cognition.
+    
+    The ReasoningGraph enables:
+    - Multi-step reasoning via connected nodes
+    - Recursive thought patterns for deep analysis
+    - Attribution tracing across reasoning chains
+    - Dynamic graph reconfiguration based on context
+    - Safeguards against reasoning collapse (infinite loops, contradictions)
+    """
+    
+    def __init__(
+        self,
+        agent_name: str,
+        agent_philosophy: str,
+        model_router: ModelRouter,
+        collapse_threshold: float = 0.8,
+        trace_enabled: bool = False,
+    ):
+        """
+        Initialize reasoning graph.
+        
+        Args:
+            agent_name: Name of the agent using this reasoning graph
+            agent_philosophy: Philosophy description of the agent
+            model_router: ModelRouter instance for LLM access
+            collapse_threshold: Threshold for reasoning collapse detection
+            trace_enabled: Whether to trace reasoning steps
+        """
+        self.agent_name = agent_name
+        self.agent_philosophy = agent_philosophy
+        self.model_router = model_router
+        self.collapse_threshold = collapse_threshold
+        self.trace_enabled = trace_enabled
+        
+        # Initialize graph components
+        self.nodes: Dict[str, Callable] = {}
+        self.edges: Dict[str, List[str]] = {}
+        self.entry_point: Optional[str] = None
+        
+        # Diagnostic tooling
+        self.tracer = TracingTools(agent_id=str(uuid.uuid4()), agent_name=agent_name)
+        
+        # Add base nodes
+        self._add_base_nodes()
+        
+        # Build initial graph
+        self._build_graph()
+    
+    def _add_base_nodes(self) -> None:
+        """Add base reasoning nodes that are part of every graph."""
+        # Entry point for validation
+        self.add_node("validate_input", self._validate_input)
+        
+        # Default nodes
+        self.add_node("initial_analysis", self._initial_analysis)
+        self.add_node("extract_themes", self._extract_themes)
+        self.add_node("generate_conclusions", self._generate_conclusions)
+        
+        # Exit handlers
+        self.add_node("check_collapse", self._check_collapse)
+        self.add_node("finalize_output", self._finalize_output)
+    
+    def _build_graph(self) -> None:
+        """Build the reasoning graph based on defined nodes and edges."""
+        # Set default entry point if not specified
+        if self.entry_point is None:
+            if "validate_input" in self.nodes:
+                self.entry_point = "validate_input"
+            elif len(self.nodes) > 0:
+                self.entry_point = list(self.nodes.keys())[0]
+            else:
+                raise ValueError("Cannot build graph: no nodes defined")
+        
+        # Build default edges if none defined
+        if not self.edges:
+            # Get sorted node names (for deterministic graphs)
+            node_names = sorted(self.nodes.keys())
+            
+            # Find entry point index
+            try:
+                entry_index = node_names.index(self.entry_point)
+            except ValueError:
+                entry_index = 0
+                
+            # Move entry point to front
+            if entry_index > 0:
+                node_names.insert(0, node_names.pop(entry_index))
+            
+            # Create sequential edges between all nodes
+            for i in range(len(node_names) - 1):
+                self.add_edge(node_names[i], node_names[i + 1])
+            
+            # Add exit handler edges
+            if "check_collapse" in self.nodes and "check_collapse" not in node_names:
+                self.add_edge(node_names[-1], "check_collapse")
+                if "finalize_output" in self.nodes:
+                    self.add_edge("check_collapse", "finalize_output")
+            elif "finalize_output" in self.nodes and "finalize_output" not in node_names:
+                self.add_edge(node_names[-1], "finalize_output")
+    
+    def add_node(self, name: str, fn: Callable) -> None:
+        """
+        Add a reasoning node to the graph.
+        
+        Args:
+            name: Node name
+            fn: Function to execute for this node
+        """
+        self.nodes[name] = fn
+    
+    def add_edge(self, source: str, target: str) -> None:
+        """
+        Add an edge between reasoning nodes.
+        
+        Args:
+            source: Source node name
+            target: Target node name
+        """
+        if source not in self.nodes:
+            raise ValueError(f"Source node '{source}' does not exist")
+        if target not in self.nodes:
+            raise ValueError(f"Target node '{target}' does not exist")
+        
+        if source not in self.edges:
+            self.edges[source] = []
+        
+        if target not in self.edges[source]:
+            self.edges[source].append(target)
+    
+    def set_entry_point(self, node_name: str) -> None:
+        """
+        Set the entry point for the reasoning graph.
+        
+        Args:
+            node_name: Name of entry node
+        """
+        if node_name not in self.nodes:
+            raise ValueError(f"Entry node '{node_name}' does not exist")
+        
+        self.entry_point = node_name
+    
+    def run(self, input: Dict[str, Any], trace_depth: int = 3) -> Dict[str, Any]:
+        """
+        Run the reasoning graph on input data.
+        
+        Args:
+            input: Input data
+            trace_depth: Depth of reasoning trace (higher = deeper reasoning)
+            
+        Returns:
+            Reasoning results
+        """
+        # Prepare initial state
+        state = ReasoningState(
+            input=input,
+            max_depth=trace_depth,
+            trace_enabled=self.trace_enabled
+        )
+        
+        # Define next node function
+        def get_next_node(state_dict: Dict[str, Any], current_node: str) -> Union[str, List[str]]:
+            # Convert state dict back to ReasoningState
+            state = ReasoningState.parse_obj(state_dict)
+            
+            # Check for collapse detection
+            if state.collapse_detected:
+                if "finalize_output" in self.nodes:
+                    return "finalize_output"
+                return END
+            
+            # Check for max depth reached
+            if state.depth >= state.max_depth and current_node != "check_collapse" and "check_collapse" in self.nodes:
+                return "check_collapse"
+            
+            # Check if we've reached a terminal node
+            if current_node == "finalize_output" or current_node not in self.edges:
+                return END
+            
+            # Return next nodes
+            return self.edges[current_node]
+        
+        # Create StateGraph
+        workflow = StateGraph(ReasoningState)
+        
+        # Add nodes
+        for node_name, node_fn in self.nodes.items():
+            workflow.add_node(node_name, self._create_node_wrapper(node_fn))
+        
+        # Set edge logic
+        workflow.set_conditional_edges(
+            condition_name="get_next_node",
+            condition_fn=get_next_node
+        )
+        
+        # Compile graph
+        compiled_graph = workflow.compile()
+        
+        # Run graph
+        start_time = datetime.datetime.now()
+        state_dict = compiled_graph.invoke(
+            {"input": input, "max_depth": trace_depth, "trace_enabled": self.trace_enabled}
+        )
+        end_time = datetime.datetime.now()
+        
+        # Convert state dict back to ReasoningState
+        final_state = ReasoningState.parse_obj(state_dict)
+        
+        # Update execution time
+        execution_time_ms = int((end_time - start_time).total_seconds() * 1000)
+        final_state.elapsed_ms = execution_time_ms
+        
+        # Prepare result
+        result = {
+            "output": final_state.output,
+            "confidence": final_state.confidence,
+            "elapsed_ms": final_state.elapsed_ms,
+            "depth": final_state.depth,
+            "collapse_detected": final_state.collapse_detected,
+        }
+        
+        # Include trace if enabled
+        if self.trace_enabled:
+            result["trace"] = {
+                "steps": final_state.steps,
+                "attribution": final_state.attribution,
+                "errors": final_state.errors,
+                "warnings": final_state.warnings,
+                "trace_id": final_state.trace_id,
+            }
+        
+        return result
+    
+    def _create_node_wrapper(self, node_fn: Callable) -> Callable:
+        """
+        Create a wrapper for node functions to handle tracing and errors.
+        
+        Args:
+            node_fn: Original node function
+            
+        Returns:
+            Wrapped node function
+        """
+        def wrapped_node(state: Dict[str, Any]) -> Dict[str, Any]:
+            # Convert state dict to ReasoningState
+            state_obj = ReasoningState.parse_obj(state)
+            
+            # Increment depth counter
+            state_obj.depth += 1
+            
+            # Run node function with try-except
+            try:
+                # Get node name from function
+                node_name = node_fn.__name__.replace("_", " ").title()
+                
+                # Record step start
+                step_start = {
+                    "name": node_name,
+                    "depth": state_obj.depth,
+                    "timestamp": datetime.datetime.now().isoformat(),
+                }
+                
+                # Add to steps
+                state_obj.steps.append(step_start)
+                
+                # Run node function
+                result = node_fn(state_obj)
+                
+                # Update state with result
+                if isinstance(result, dict):
+                    # Extract and update fields if returned
+                    for key, value in result.items():
+                        if hasattr(state_obj, key):
+                            setattr(state_obj, key, value)
+                
+                # Record step completion
+                step_end = {
+                    "name": node_name,
+                    "depth": state_obj.depth,
+                    "completed": True,
+                    "timestamp": datetime.datetime.now().isoformat(),
+                }
+                
+                # Update last step
+                if state_obj.steps:
+                    state_obj.steps[-1].update(step_end)
+                
+            except Exception as e:
+                # Record error
+                error = {
+                    "message": str(e),
+                    "type": type(e).__name__,
+                    "timestamp": datetime.datetime.now().isoformat(),
+                    "node": node_fn.__name__,
+                    "depth": state_obj.depth,
+                }
+                
+                state_obj.errors.append(error)
+                
+                # Update last step if exists
+                if state_obj.steps:
+                    state_obj.steps[-1].update({
+                        "completed": False,
+                        "error": error,
+                    })
+                
+                # Set collapse if critical error
+                state_obj.collapse_detected = True
+                state_obj.collapse_reason = "critical_error"
+            
+            # Convert back to dict
+            return state_obj.dict()
+        
+        return wrapped_node
+    
+    # Base node implementations
+    def _validate_input(self, state: ReasoningState) -> Dict[str, Any]:
+        """
+        Validate input data.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields
+        """
+        result = {
+            "warnings": state.warnings.copy(),
+        }
+        
+        # Check if input is empty
+        if not state.input:
+            result["warnings"].append({
+                "message": "Empty input provided",
+                "severity": "high",
+                "timestamp": datetime.datetime.now().isoformat(),
+            })
+            
+            # Set collapse for empty input
+            result["collapse_detected"] = True
+            result["collapse_reason"] = "empty_input"
+        
+        return result
+    
+    def _initial_analysis(self, state: ReasoningState) -> Dict[str, Any]:
+        """
+        Perform initial analysis of input data.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields
+        """
+        # Extract key information from input
+        analysis = {
+            "timestamp": datetime.datetime.now().isoformat(),
+            "key_entities": [],
+            "key_metrics": {},
+            "identified_patterns": [],
+        }
+        
+        # Update state
+        result = {
+            "context": {**state.context, "initial_analysis": analysis},
+        }
+        
+        return result
+    
+    def _extract_themes(self, state: ReasoningState) -> Dict[str, Any]:
+        """
+        Extract key themes from the data.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields with extracted themes
+        """
+        # Extract themes based on agent philosophy
+        themes = self.extract_themes(
+            text=str(state.input),
+            max_themes=5
+        )
+        
+        # Calculate alignment with agent philosophy
+        alignment = self.compute_alignment(
+            themes=themes,
+            philosophy=self.agent_philosophy
+        )
+        
+        # Update result
+        result = {
+            "context": {
+                **state.context,
+                "themes": themes,
+                "philosophy_alignment": alignment,
+            },
+        }
+        
+        return result
+    
+    def _generate_conclusions(self, state: ReasoningState) -> Dict[str, Any]:
+        """
+        Generate conclusions based on analysis.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields with conclusions
+        """
+        # Simple placeholder conclusions
+        conclusions = {
+            "summary": "Analysis completed",
+            "confidence": 0.7,
+            "recommendations": [],
+        }
+        
+        # Update result
+        result = {
+            "output": conclusions,
+            "confidence": conclusions["confidence"],
+        }
+        
+        return result
+    
+    def _check_collapse(self, state: ReasoningState) -> Dict[str, Any]:
+        """
+        Check for reasoning collapse conditions.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields with collapse detection
+        """
+        # Default collapse risk is low
+        collapse_risk = 0.1
+        
+        # Check for collapse conditions
+        collapse_conditions = {
+            "circular_reasoning": self._detect_circular_reasoning(state),
+            "confidence_collapse": state.confidence < 0.2,
+            "contradiction": self._detect_contradictions(state),
+            "depth_exhaustion": state.depth >= state.max_depth,
+        }
+        
+        # Calculate overall collapse risk
+        active_conditions = [k for k, v in collapse_conditions.items() if v]
+        collapse_risk = len(active_conditions) / len(collapse_conditions) if collapse_conditions else 0
+        
+        # Determine if collapse detected
+        collapse_detected = collapse_risk >= self.collapse_threshold
+        collapse_reason = active_conditions[0] if active_conditions else None
+        
+        # Update result
+        result = {
+            "collapse_risk": collapse_risk,
+            "collapse_detected": collapse_detected,
+            "collapse_reason": collapse_reason,
+        }
+        
+        # Add warning if collapse detected
+        if collapse_detected:
+            result["warnings"] = state.warnings + [{
+                "message": f"Reasoning collapse detected: {collapse_reason}",
+                "severity": "high",
+                "timestamp": datetime.datetime.now().isoformat(),
+            }]
+        
+        return result
+    
+    def _finalize_output(self, state: ReasoningState) -> Dict[str, Any]:
+        """
+        Finalize output and prepare result.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields with finalized output
+        """
+        # If no output yet, create default
+        if not state.output:
+            output = {
+                "summary": "Analysis completed with limited results",
+                "confidence": max(0.1, state.confidence / 2),  # Reduced confidence
+                "recommendations": [],
+                "timestamp": datetime.datetime.now().isoformat(),
+            }
+            
+            # Update result
+            result = {
+                "output": output,
+                "confidence": output["confidence"],
+            }
+        else:
+            # Just return current state unchanged
+            result = {}
+        
+        return result
+    
+    # Utility methods for reasoning loops
+    def extract_themes(self, text: str, max_themes: int = 5) -> List[str]:
+        """
+        Extract key themes from text using LLM.
+        
+        Args:
+            text: Text to analyze
+            max_themes: Maximum number of themes to extract
+            
+        Returns:
+            List of extracted themes
+        """
+        # Use LLM to extract themes
+        prompt = f"""
+        Extract the {max_themes} most important themes or topics from the following text.
+        Respond with a Python list of strings, each representing one theme.
+        
+        Text:
+        {text}
+        
+        Themes:
+        """
+        
+        try:
+            response = self.model_router.generate(prompt)
+            
+            # Parse response as Python list (safety handling)
+            try:
+                themes = eval(response.strip())
+                if isinstance(themes, list) and all(isinstance(t, str) for t in themes):
+                    return themes[:max_themes]
+            except:
+                pass
+            
+            # Fallback parsing
+            themes = [line.strip().strip('-*•').strip() 
+                     for line in response.split('\n')
+                     if line.strip() and line.strip()[0] in '-*•']
+            
+            return themes[:max_themes]
+            
+        except Exception as e:
+            logging.warning(f"Error extracting themes: {e}")
+            return []
+    
+    def compute_alignment(self, themes: List[str], philosophy: str) -> float:
+        """
+        Compute alignment between themes and philosophy.
+        
+        Args:
+            themes: List of themes
+            philosophy: Philosophy to align with
+            
+        Returns:
+            Alignment score (0-1)
+        """
+        # Without using LLM, use a simple heuristic based on word overlap
+        if not themes:
+            return 0.5  # Neutral score for no themes
+        
+        # Convert to lowercase for comparison
+        philosophy_words = set(philosophy.lower().split())
+        
+        # Count theme words that overlap with philosophy
+        alignment_scores = []
+        for theme in themes:
+            theme_words = set(theme.lower().split())
+            overlap = len(theme_words.intersection(philosophy_words))
+            total_words = len(theme_words)
+            
+            # Calculate theme alignment
+            if total_words > 0:
+                theme_alignment = min(1.0, overlap / (total_words * 0.5))  # Scale for partial matches
+                alignment_scores.append(theme_alignment)
+        
+        # Calculate average alignment across themes
+        return sum(alignment_scores) / len(alignment_scores) if alignment_scores else 0.5
+    
+    def run_reflection(self, agent_state: Dict[str, Any], depth: int = 3, 
+                      trace_enabled: bool = False) -> Dict[str, Any]:
+        """
+        Run reflection on agent's current state.
+        
+        Args:
+            agent_state: Agent's current state
+            depth: Depth of reflection
+            trace_enabled: Whether to enable tracing
+            
+        Returns:
+            Reflection results
+        """
+        # Prepare reflection input
+        reflection_input = {
+            "agent_state": agent_state,
+            "agent_name": self.agent_name,
+            "agent_philosophy": self.agent_philosophy,
+            "reflection_depth": depth,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        # Create reflection prompt for LLM
+        prompt = f"""
+        You are the {self.agent_name} agent with the following philosophy:
+        "{self.agent_philosophy}"
+        
+        Perform a depth {depth} reflection on your current state and decision making process.
+        Focus on:
+        1. Consistency between your investment philosophy and current beliefs
+        2. Quality of your recent decisions and their alignment with your values
+        3. Potential biases or blind spots in your analysis
+        4. Areas where your reasoning could be improved
+        
+        Your current state:
+        {agent_state}
+        
+        Respond with a JSON object containing:
+        - assessment: Overall assessment of your cognitive state
+        - consistency_score: How consistent your decisions are with your philosophy (0-1)
+        - identified_biases: List of potential biases detected
+        - improvement_areas: Areas where reasoning could be improved
+        - confidence: Your confidence in this self-assessment (0-1)
+        """
+        
+        try:
+            # Generate reflection using LLM
+            response = self.model_router.generate(prompt)
+            
+            # Parse JSON response (with fallback)
+            # Parse JSON response (with fallback)
+            try:
+                import json
+                reflection = json.loads(response)
+            except json.JSONDecodeError:
+                # Fallback parsing
+                reflection = {
+                    "assessment": "Unable to parse full reflection",
+                    "consistency_score": 0.5,
+                    "identified_biases": [],
+                    "improvement_areas": [],
+                    "confidence": 0.3,
+                }
+                
+                # Extract fields from text response
+                if "consistency_score" in response:
+                    try:
+                        consistency_score = float(response.split("consistency_score")[1].split("\n")[0].replace(":", "").strip())
+                        reflection["consistency_score"] = consistency_score
+                    except:
+                        pass
+                
+                if "confidence" in response:
+                    try:
+                        confidence = float(response.split("confidence")[1].split("\n")[0].replace(":", "").strip())
+                        reflection["confidence"] = confidence
+                    except:
+                        pass
+            
+            return reflection
+            
+        except Exception as e:
+            logging.warning(f"Error in reflection: {e}")
+            return {
+                "assessment": "Reflection failed due to error",
+                "consistency_score": 0.5,
+                "identified_biases": ["reflection_failure"],
+                "improvement_areas": ["error_handling"],
+                "confidence": 0.2,
+                "error": str(e),
+            }
+    
+    def generate_from_experiences(self, experiences: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Generate signals based on past experiences.
+        
+        Args:
+            experiences: List of past experiences
+            
+        Returns:
+            List of generated signals
+        """
+        if not experiences:
+            return []
+        
+        # Format experiences for LLM prompt
+        formatted_experiences = "\n".join([
+            f"Experience {i+1}: {exp.get('description', 'No description')}" +
+            f"\nOutcome: {exp.get('outcome', 'Unknown')}" +
+            f"\nTimestamp: {exp.get('timestamp', 'Unknown')}"
+            for i, exp in enumerate(experiences)
+        ])
+        
+        # Create generation prompt for LLM
+        prompt = f"""
+        You are the {self.agent_name} agent with the following philosophy:
+        "{self.agent_philosophy}"
+        
+        Based on the following past experiences, generate potential investment signals:
+        
+        {formatted_experiences}
+        
+        Generate 2-3 potential investment signals based on these experiences.
+        Each signal should be a JSON object containing:
+        - ticker: Stock ticker symbol
+        - action: "buy", "sell", or "hold"
+        - confidence: Confidence level (0.0-1.0)
+        - reasoning: Explicit reasoning chain
+        - intent: High-level investment intent
+        - value_basis: Core value driving this decision
+        
+        Respond with a JSON array containing these signals.
+        """
+        
+        try:
+            # Generate signals using LLM
+            response = self.model_router.generate(prompt)
+            
+            # Parse JSON response (with fallback)
+            try:
+                import json
+                signals = json.loads(response)
+                if not isinstance(signals, list):
+                    signals = [signals]
+            except json.JSONDecodeError:
+                # Simple fallback extraction
+                signals = []
+                lines = response.split("\n")
+                current_signal = {}
+                
+                for line in lines:
+                    line = line.strip()
+                    if line.startswith("ticker:") or line.startswith('"ticker":'):
+                        # New signal starts
+                        if current_signal and "ticker" in current_signal:
+                            signals.append(current_signal)
+                        current_signal = {}
+                        current_signal["ticker"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                    elif line.startswith("action:") or line.startswith('"action":'):
+                        current_signal["action"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                    elif line.startswith("confidence:") or line.startswith('"confidence":'):
+                        try:
+                            current_signal["confidence"] = float(line.split(":", 1)[1].strip().strip('"').strip("'").strip(','))
+                        except:
+                            current_signal["confidence"] = 0.5
+                    elif line.startswith("reasoning:") or line.startswith('"reasoning":'):
+                        current_signal["reasoning"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                    elif line.startswith("intent:") or line.startswith('"intent":'):
+                        current_signal["intent"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                    elif line.startswith("value_basis:") or line.startswith('"value_basis":'):
+                        current_signal["value_basis"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                
+                # Add last signal if any
+                if current_signal and "ticker" in current_signal:
+                    signals.append(current_signal)
+            
+            # Ensure all required fields are present
+            for signal in signals:
+                signal.setdefault("ticker", "UNKNOWN")
+                signal.setdefault("action", "hold")
+                signal.setdefault("confidence", 0.5)
+                signal.setdefault("reasoning", "Generated from past experiences")
+                signal.setdefault("intent", "Learn from past experiences")
+                signal.setdefault("value_basis", "Experiential learning")
+            
+            return signals
+            
+        except Exception as e:
+            logging.warning(f"Error generating from experiences: {e}")
+            return []
+    
+    def generate_from_beliefs(self, beliefs: Dict[str, float]) -> List[Dict[str, Any]]:
+        """
+        Generate signals based on current beliefs.
+        
+        Args:
+            beliefs: Current belief state
+            
+        Returns:
+            List of generated signals
+        """
+        if not beliefs:
+            return []
+        
+        # Format beliefs for LLM prompt
+        formatted_beliefs = "\n".join([
+            f"Belief: {belief}, Strength: {strength:.2f}"
+            for belief, strength in beliefs.items()
+        ])
+        
+        # Create generation prompt for LLM
+        prompt = f"""
+        You are the {self.agent_name} agent with the following philosophy:
+        "{self.agent_philosophy}"
+        
+        Based on the following current beliefs, generate potential investment signals:
+        
+        {formatted_beliefs}
+        
+        Generate 2-3 potential investment signals based on these beliefs.
+        Each signal should be a JSON object containing:
+        - ticker: Stock ticker symbol (extract from beliefs if present)
+        - action: "buy", "sell", or "hold"
+        - confidence: Confidence level (0.0-1.0)
+        - reasoning: Explicit reasoning chain
+        - intent: High-level investment intent
+        - value_basis: Core value driving this decision
+        
+        Respond with a JSON array containing these signals.
+        """
+        
+        try:
+            # Generate signals using LLM
+            response = self.model_router.generate(prompt)
+            
+            # Parse JSON response (with fallback)
+            try:
+                import json
+                signals = json.loads(response)
+                if not isinstance(signals, list):
+                    signals = [signals]
+            except json.JSONDecodeError:
+                # Simple fallback extraction (same as in generate_from_experiences)
+                signals = []
+                lines = response.split("\n")
+                current_signal = {}
+                
+                for line in lines:
+                    line = line.strip()
+                    if line.startswith("ticker:") or line.startswith('"ticker":'):
+                        # New signal starts
+                        if current_signal and "ticker" in current_signal:
+                            signals.append(current_signal)
+                        current_signal = {}
+                        current_signal["ticker"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                    elif line.startswith("action:") or line.startswith('"action":'):
+                        current_signal["action"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                    elif line.startswith("confidence:") or line.startswith('"confidence":'):
+                        try:
+                            current_signal["confidence"] = float(line.split(":", 1)[1].strip().strip('"').strip("'").strip(','))
+                        except:
+                            current_signal["confidence"] = 0.5
+                    elif line.startswith("reasoning:") or line.startswith('"reasoning":'):
+                        current_signal["reasoning"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                    elif line.startswith("intent:") or line.startswith('"intent":'):
+                        current_signal["intent"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                    elif line.startswith("value_basis:") or line.startswith('"value_basis":'):
+                        current_signal["value_basis"] = line.split(":", 1)[1].strip().strip('"').strip("'").strip(',')
+                
+                # Add last signal if any
+                if current_signal and "ticker" in current_signal:
+                    signals.append(current_signal)
+            
+            # Ensure all required fields are present
+            for signal in signals:
+                signal.setdefault("ticker", "UNKNOWN")
+                signal.setdefault("action", "hold")
+                signal.setdefault("confidence", 0.5)
+                signal.setdefault("reasoning", "Generated from belief state")
+                signal.setdefault("intent", "Act on current beliefs")
+                signal.setdefault("value_basis", "Belief consistency")
+            
+            return signals
+            
+        except Exception as e:
+            logging.warning(f"Error generating from beliefs: {e}")
+            return []
+    
+    # Collapse detection utilities
+    def _detect_circular_reasoning(self, state: ReasoningState) -> bool:
+        """
+        Detect circular reasoning patterns in reasoning steps.
+        
+        Args:
+            state: Current reasoning state
+            
+        Returns:
+            True if circular reasoning detected, False otherwise
+        """
+        # Need at least 3 steps to detect circularity
+        if len(state.steps) < 3:
+            return False
+        
+        # Extract step names
+        step_names = [step.get("name", "") for step in state.steps]
+        
+        # Look for repeating patterns (minimum 2 steps)
+        for pattern_len in range(2, len(step_names) // 2 + 1):
+            for i in range(len(step_names) - pattern_len * 2 + 1):
+                pattern = step_names[i:i+pattern_len]
+                next_seq = step_names[i+pattern_len:i+pattern_len*2]
+                
+                if pattern == next_seq:
+                    return True
+        
+        return False
+    
+    def _detect_contradictions(self, state: ReasoningState) -> bool:
+        """
+        Detect contradictory statements in reasoning trace.
+        
+        Args:
+            state: Current reasoning state
+            
+        Returns:
+            True if contradictions detected, False otherwise
+        """
+        # Simple implementation: check if confidence oscillates dramatically
+        if len(state.steps) < 3:
+            return False
+        
+        # Extract confidence values
+        confidences = []
+        for step in state.steps:
+            if "output" in step and "confidence" in step["output"]:
+                confidences.append(step["output"]["confidence"])
+        
+        # Check for oscillations
+        if len(confidences) >= 3:
+            for i in range(len(confidences) - 2):
+                # Check for significant up-down or down-up pattern
+                if (confidences[i] - confidences[i+1] > 0.3 and confidences[i+1] - confidences[i+2] < -0.3) or \
+                   (confidences[i] - confidences[i+1] < -0.3 and confidences[i+1] - confidences[i+2] > 0.3):
+                    return True
+        
+        return False
+
+    # Reflection utilities
+    def fork_reflection(self, base_state: Dict[str, Any], depth: int = 2) -> List[Dict[str, Any]]:
+        """
+        Create multiple reflection paths from a base state.
+        
+        Args:
+            base_state: Base state to fork from
+            depth: Depth of reflection
+            
+        Returns:
+            List of reflection results
+        """
+        reflection_paths = []
+        
+        # Create reflective dimensions
+        dimensions = [
+            "consistency",  # Consistency with philosophy
+            "evidence",     # Evidence evaluation
+            "alternatives", # Alternative hypotheses
+            "biases",       # Cognitive biases
+            "gaps",         # Knowledge gaps
+        ]
+        
+        # Generate reflection for each dimension
+        for dimension in dimensions:
+            reflection = self._reflect_on_dimension(base_state, dimension, depth)
+            reflection_paths.append({
+                "dimension": dimension,
+                "reflection": reflection,
+                "confidence": reflection.get("confidence", 0.5),
+            })
+        
+        # Sort by confidence (highest first)
+        reflection_paths.sort(key=lambda x: x["confidence"], reverse=True)
+        
+        return reflection_paths
+    
+    def _reflect_on_dimension(self, state: Dict[str, Any], dimension: str, depth: int) -> Dict[str, Any]:
+        """
+        Reflect on a specific dimension of reasoning.
+        
+        Args:
+            state: Current state
+            dimension: Dimension to reflect on
+            depth: Depth of reflection
+            
+        Returns:
+            Reflection results
+        """
+        # Craft dimension-specific prompt
+        if dimension == "consistency":
+            prompt_focus = "the consistency between my decisions and my core philosophy"
+        elif dimension == "evidence":
+            prompt_focus = "the quality and completeness of evidence I'm considering"
+        elif dimension == "alternatives":
+            prompt_focus = "alternative hypotheses or viewpoints I might be overlooking"
+        elif dimension == "biases":
+            prompt_focus = "cognitive biases that might be affecting my judgment"
+        elif dimension == "gaps":
+            prompt_focus = "knowledge gaps that could be affecting my analysis"
+        else:
+            prompt_focus = f"the dimension of {dimension} in my reasoning"
+        
+        # Create reflection prompt
+        prompt = f"""
+        You are the {self.agent_name} agent with the following philosophy:
+        "{self.agent_philosophy}"
+        
+        Perform a depth {depth} reflection focusing specifically on {prompt_focus}.
+        
+        Current state:
+        {state}
+        
+        Respond with a JSON object containing:
+        - dimension: "{dimension}"
+        - assessment: Your assessment of this dimension
+        - issues_identified: List of specific issues identified
+        - recommendations: Recommendations to address these issues
+        - confidence: Your confidence in this assessment (0-1)
+        """
+        
+        try:
+            # Generate reflection using LLM
+            response = self.model_router.generate(prompt)
+            
+            # Parse JSON response (with fallback)
+            try:
+                import json
+                reflection = json.loads(response)
+            except json.JSONDecodeError:
+                # Fallback parsing
+                reflection = {
+                    "dimension": dimension,
+                    "assessment": "Unable to parse full reflection",
+                    "issues_identified": [],
+                    "recommendations": [],
+                    "confidence": 0.3,
+                }
+            
+            return reflection
+            
+        except Exception as e:
+            logging.warning(f"Error in dimension reflection: {e}")
+            return {
+                "dimension": dimension,
+                "assessment": "Reflection failed due to error",
+                "issues_identified": ["reflection_failure"],
+                "recommendations": ["error_handling"],
+                "confidence": 0.2,
+                "error": str(e),
+            }

src/cognition/memory.py

@@ -0,0 +1,1013 @@
+"""
+MemoryShell - Temporal Memory Architecture for Recursive Agents
+
+This module implements the memory shell architecture that enables agents to
+maintain persistent memory with configurable decay properties. The memory
+shell acts as a cognitive substrate that provides:
+
+- Short-term working memory
+- Medium-term episodic memory with decay
+- Long-term semantic memory with compression
+- Temporal relationship tracking
+- Experience-based learning
+
+Internal Note: The memory shell simulates the MEMTRACE and ECHO-LOOP interpretability
+shells for modeling memory decay and feedback loops in agent cognition.
+"""
+
+import datetime
+import math
+import uuid
+import heapq
+from typing import Dict, List, Any, Optional, Tuple, Set
+import numpy as np
+from collections import defaultdict, deque
+
+from pydantic import BaseModel, Field
+
+
+class Memory(BaseModel):
+    """Base memory unit with attribution and decay properties."""
+    
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    content: Dict[str, Any] = Field(...)
+    memory_type: str = Field(...)  # "episodic", "semantic", "working"
+    creation_time: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    last_access_time: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    access_count: int = Field(default=1)
+    salience: float = Field(default=1.0)  # Initial salience (0-1)
+    decay_rate: float = Field(default=0.1)  # Default decay rate per time unit
+    associations: Dict[str, float] = Field(default_factory=dict)  # Associated memory IDs with strengths
+    source: Optional[str] = Field(default=None)  # Source of the memory (e.g., "observation", "reflection")
+    tags: List[str] = Field(default_factory=list)  # Semantic tags for the memory
+    
+    def update_access(self) -> None:
+        """Update access time and count."""
+        self.last_access_time = datetime.datetime.now()
+        self.access_count += 1
+    
+    def calculate_current_salience(self) -> float:
+        """Calculate current salience based on decay model."""
+        # Time since creation in hours
+        hours_since_creation = (datetime.datetime.now() - self.creation_time).total_seconds() / 3600
+        
+        # Apply decay model: exponential decay with access-based reinforcement
+        base_decay = math.exp(-self.decay_rate * hours_since_creation)
+        access_factor = math.log1p(self.access_count) / 10  # Logarithmic access bonus
+        
+        # Calculate current salience (capped at 1.0)
+        current_salience = min(1.0, self.salience * base_decay * (1 + access_factor))
+        
+        return current_salience
+    
+    def add_association(self, memory_id: str, strength: float = 0.5) -> None:
+        """
+        Add association to another memory.
+        
+        Args:
+            memory_id: ID of memory to associate with
+            strength: Association strength (0-1)
+        """
+        self.associations[memory_id] = strength
+    
+    def add_tag(self, tag: str) -> None:
+        """
+        Add semantic tag to memory.
+        
+        Args:
+            tag: Tag to add
+        """
+        if tag not in self.tags:
+            self.tags.append(tag)
+    
+    def as_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for export."""
+        return {
+            "id": self.id,
+            "content": self.content,
+            "memory_type": self.memory_type,
+            "creation_time": self.creation_time.isoformat(),
+            "last_access_time": self.last_access_time.isoformat(),
+            "access_count": self.access_count,
+            "salience": self.salience,
+            "current_salience": self.calculate_current_salience(),
+            "decay_rate": self.decay_rate,
+            "associations": self.associations,
+            "source": self.source,
+            "tags": self.tags,
+        }
+
+
+class EpisodicMemory(Memory):
+    """Episodic memory representing specific experiences."""
+    
+    sequence_position: Optional[int] = Field(default=None)  # Position in temporal sequence
+    emotional_valence: float = Field(default=0.0)  # Emotional charge (-1 to 1)
+    outcome: Optional[str] = Field(default=None)  # Outcome of the experience
+    
+    def __init__(self, **data):
+        data["memory_type"] = "episodic"
+        super().__init__(**data)
+
+
+class SemanticMemory(Memory):
+    """Semantic memory representing conceptual knowledge."""
+    
+    certainty: float = Field(default=0.7)  # Certainty level (0-1)
+    contradiction_ids: List[str] = Field(default_factory=list)  # IDs of contradicting memories
+    supporting_evidence: List[str] = Field(default_factory=list)  # IDs of supporting memories
+    
+    def __init__(self, **data):
+        data["memory_type"] = "semantic"
+        # Semantic memories decay more slowly
+        data.setdefault("decay_rate", 0.05)
+        super().__init__(**data)
+    
+    def add_evidence(self, memory_id: str, is_supporting: bool = True) -> None:
+        """
+        Add supporting or contradicting evidence.
+        
+        Args:
+            memory_id: Memory ID for evidence
+            is_supporting: Whether evidence is supporting (True) or contradicting (False)
+        """
+        if is_supporting:
+            if memory_id not in self.supporting_evidence:
+                self.supporting_evidence.append(memory_id)
+        else:
+            if memory_id not in self.contradiction_ids:
+                self.contradiction_ids.append(memory_id)
+    
+    def update_certainty(self, evidence_ratio: float) -> None:
+        """
+        Update certainty based on supporting/contradicting evidence ratio.
+        
+        Args:
+            evidence_ratio: Ratio of supporting to total evidence (0-1)
+        """
+        # Blend current certainty with evidence ratio
+        self.certainty = 0.7 * self.certainty + 0.3 * evidence_ratio
+
+
+class WorkingMemory(Memory):
+    """Working memory representing active thinking and temporary storage."""
+    
+    expiration_time: datetime.datetime = Field(default_factory=lambda: datetime.datetime.now() + datetime.timedelta(hours=1))
+    priority: int = Field(default=1)  # Priority level (higher = more important)
+    
+    def __init__(self, **data):
+        data["memory_type"] = "working"
+        # Working memories decay rapidly
+        data.setdefault("decay_rate", 0.5)
+        super().__init__(**data)
+    
+    def set_expiration(self, hours: float) -> None:
+        """
+        Set expiration time for working memory.
+        
+        Args:
+            hours: Hours until expiration
+        """
+        self.expiration_time = datetime.datetime.now() + datetime.timedelta(hours=hours)
+    
+    def is_expired(self) -> bool:
+        """Check if working memory has expired."""
+        return datetime.datetime.now() > self.expiration_time
+
+
+class MemoryShell:
+    """
+    Memory shell architecture for agent cognitive persistence.
+    
+    The MemoryShell provides:
+    - Multi-tiered memory system (working, episodic, semantic)
+    - Configurable decay rates for different memory types
+    - Time-based and access-based memory reinforcement
+    - Associative memory network with activation spread
+    - Query capabilities with relevance ranking
+    """
+    
+    def __init__(self, decay_rate: float = 0.2):
+        """
+        Initialize memory shell.
+        
+        Args:
+            decay_rate: Base decay rate for memories
+        """
+        self.memories: Dict[str, Memory] = {}
+        self.decay_rate = decay_rate
+        self.working_memory_capacity = 7  # Miller's number (7±2)
+        self.episodic_index: Dict[str, Set[str]] = defaultdict(set)  # Tag -> memory IDs
+        self.semantic_index: Dict[str, Set[str]] = defaultdict(set)  # Tag -> memory IDs
+        self.temporal_sequence: List[str] = []  # Ordered list of episodic memory IDs
+        self.activation_threshold = 0.1  # Minimum activation for retrieval
+        
+        # Initialize memory statistics
+        self.stats = {
+            "total_memories_created": 0,
+            "total_memories_decayed": 0,
+            "working_memory_count": 0,
+            "episodic_memory_count": 0,
+            "semantic_memory_count": 0,
+            "average_salience": 0.0,
+            "association_count": 0,
+        }
+    
+    def add_working_memory(self, content: Dict[str, Any], priority: int = 1,
+                         expiration_hours: float = 1.0, tags: List[str] = None) -> str:
+        """
+        Add item to working memory.
+        
+        Args:
+            content: Memory content
+            priority: Priority level (higher = more important)
+            expiration_hours: Hours until expiration
+            tags: Semantic tags
+            
+        Returns:
+            Memory ID
+        """
+        # Create working memory
+        memory = WorkingMemory(
+            content=content,
+            priority=priority,
+            decay_rate=self.decay_rate * 2,  # Working memory decays faster
+            tags=tags or [],
+            source="working",
+        )
+        
+        # Set expiration
+        memory.set_expiration(expiration_hours)
+        
+        # Store in memory dictionary
+        self.memories[memory.id] = memory
+        
+        # Add to indices
+        for tag in memory.tags:
+            self.episodic_index[tag].add(memory.id)
+        
+        # Enforce capacity limit
+        self._enforce_working_memory_capacity()
+        
+        # Update stats
+        self.stats["total_memories_created"] += 1
+        self.stats["working_memory_count"] += 1
+        
+        return memory.id
+    
+    def add_episodic_memory(self, content: Dict[str, Any], emotional_valence: float = 0.0,
+                         outcome: Optional[str] = None, tags: List[str] = None) -> str:
+        """
+        Add episodic memory.
+        
+        Args:
+            content: Memory content
+            emotional_valence: Emotional charge (-1 to 1)
+            outcome: Outcome of the experience
+            tags: Semantic tags
+            
+        Returns:
+            Memory ID
+        """
+        # Create episodic memory
+        memory = EpisodicMemory(
+            content=content,
+            emotional_valence=emotional_valence,
+            outcome=outcome,
+            decay_rate=self.decay_rate,
+            tags=tags or [],
+            source="episode",
+        )
+        
+        # Set sequence position
+        memory.sequence_position = len(self.temporal_sequence)
+        
+        # Store in memory dictionary
+        self.memories[memory.id] = memory
+        
+        # Add to indices
+        for tag in memory.tags:
+            self.episodic_index[tag].add(memory.id)
+        
+        # Add to temporal sequence
+        self.temporal_sequence.append(memory.id)
+        
+        # Update stats
+        self.stats["total_memories_created"] += 1
+        self.stats["episodic_memory_count"] += 1
+        
+        return memory.id
+    
+    def add_semantic_memory(self, content: Dict[str, Any], certainty: float = 0.7,
+                        tags: List[str] = None) -> str:
+        """
+        Add semantic memory.
+        
+        Args:
+            content: Memory content
+            certainty: Certainty level (0-1)
+            tags: Semantic tags
+            
+        Returns:
+            Memory ID
+        """
+        # Create semantic memory
+        memory = SemanticMemory(
+            content=content,
+            certainty=certainty,
+            decay_rate=self.decay_rate * 0.5,  # Semantic memory decays slower
+            tags=tags or [],
+            source="semantic",
+        )
+        
+        # Store in memory dictionary
+        self.memories[memory.id] = memory
+        
+        # Add to indices
+        for tag in memory.tags:
+            self.semantic_index[tag].add(memory.id)
+        
+        # Update stats
+        self.stats["total_memories_created"] += 1
+        self.stats["semantic_memory_count"] += 1
+        
+        return memory.id
+    
+    def add_experience(self, experience: Dict[str, Any]) -> Tuple[str, List[str]]:
+        """
+        Add new experience as episodic memory and extract semantic memories.
+        
+        Args:
+            experience: Experience data
+            
+        Returns:
+            Tuple of (episodic_id, list of semantic_ids)
+        """
+        # Extract tags from experience
+        tags = experience.get("tags", [])
+        if not tags and "type" in experience:
+            tags = [experience["type"]]
+        
+        # Create episodic memory
+        episodic_id = self.add_episodic_memory(
+            content=experience,
+            emotional_valence=experience.get("emotional_valence", 0.0),
+            outcome=experience.get("outcome"),
+            tags=tags,
+        )
+        
+        # Extract semantic information (simple implementation)
+        semantic_ids = []
+        if "insights" in experience and isinstance(experience["insights"], list):
+            for insight in experience["insights"]:
+                if isinstance(insight, dict):
+                    semantic_id = self.add_semantic_memory(
+                        content=insight,
+                        certainty=insight.get("confidence", 0.7),
+                        tags=insight.get("tags", tags),
+                    )
+                    semantic_ids.append(semantic_id)
+                    
+                    # Create bidirectional association
+                    self.add_association(episodic_id, semantic_id, 0.8)
+        
+        return episodic_id, semantic_ids
+    
+    def add_association(self, memory_id1: str, memory_id2: str, strength: float = 0.5) -> bool:
+        """
+        Add bidirectional association between memories.
+        
+        Args:
+            memory_id1: First memory ID
+            memory_id2: Second memory ID
+            strength: Association strength (0-1)
+            
+        Returns:
+            Success status
+        """
+        # Verify memories exist
+        if memory_id1 not in self.memories or memory_id2 not in self.memories:
+            return False
+        
+        # Add bidirectional association
+        self.memories[memory_id1].add_association(memory_id2, strength)
+        self.memories[memory_id2].add_association(memory_id1, strength)
+        
+        # Update stats
+        self.stats["association_count"] += 2
+        
+        return True
+    
+    def get_memory(self, memory_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve memory by ID.
+        
+        Args:
+            memory_id: Memory ID
+            
+        Returns:
+            Memory data or None if not found
+        """
+        if memory_id not in self.memories:
+            return None
+        
+        # Get memory
+        memory = self.memories[memory_id]
+        
+        # Update access statistics
+        memory.update_access()
+        
+        # Convert to dictionary
+        memory_dict = memory.as_dict()
+        
+        return memory_dict
+    
+    def query_memories(self, query: Dict[str, Any], memory_type: Optional[str] = None,
+                    tags: Optional[List[str]] = None, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Query memories based on content, type, and tags.
+        
+        Args:
+            query: Query terms
+            memory_type: Optional filter by memory type
+            tags: Optional filter by tags
+            limit: Maximum number of results
+            
+        Returns:
+            List of matching memories
+        """
+        # Filter by memory type
+        candidate_ids = set()
+        
+        if memory_type:
+            # Filter by specified memory type
+            for memory_id, memory in self.memories.items():
+                if memory.memory_type == memory_type:
+                    candidate_ids.add(memory_id)
+        else:
+            # Include all memory IDs
+            candidate_ids = set(self.memories.keys())
+        
+        # Filter by tags if provided
+        if tags:
+            tag_memories = set()
+            for tag in tags:
+                # Combine episodic and semantic indices
+                tag_memories.update(self.episodic_index.get(tag, set()))
+                tag_memories.update(self.semantic_index.get(tag, set()))
+            
+            # Restrict to memories with matching tags
+            if tag_memories:
+                candidate_ids = candidate_ids.intersection(tag_memories)
+        
+        # Score candidates based on query relevance and salience
+        scored_candidates = []
+        
+        for memory_id in candidate_ids:
+            memory = self.memories[memory_id]
+            
+            # Skip memories below activation threshold
+            current_salience = memory.calculate_current_salience()
+            if current_salience < self.activation_threshold:
+                continue
+            
+            # Calculate relevance score
+            relevance = self._calculate_relevance(memory, query)
+            
+            # Combine relevance and salience for final score
+            score = 0.7 * relevance + 0.3 * current_salience
+            
+            # Add to candidates
+            scored_candidates.append((memory_id, score))
+        
+        # Sort by score (descending) and take top 'limit' results
+        top_candidates = heapq.nlargest(limit, scored_candidates, key=lambda x: x[1])
+        
+        # Retrieve and return memories
+        result_memories = []
+        for memory_id, score in top_candidates:
+            memory = self.memories[memory_id]
+            memory.update_access()  # Update access time
+            
+            # Add memory with score
+            memory_dict = memory.as_dict()
+            memory_dict["relevance_score"] = score
+            
+            result_memories.append(memory_dict)
+        
+        return result_memories
+    
+    def get_recent_memories(self, memory_type: Optional[str] = None, limit: int = 5) -> List[Dict[str, Any]]:
+        """
+        Get most recent memories by creation time.
+        
+        Args:
+            memory_type: Optional filter by memory type
+            limit: Maximum number of results
+            
+        Returns:
+            List of recent memories
+        """
+        # Filter and sort memories by creation time
+        recent_memories = []
+        
+        for memory_id, memory in self.memories.items():
+            # Filter by memory type if specified
+            if memory_type and memory.memory_type != memory_type:
+                continue
+            
+            # Add to candidates
+            recent_memories.append((memory_id, memory.creation_time))
+        
+        # Sort by creation time (descending)
+        recent_memories.sort(key=lambda x: x[1], reverse=True)
+        
+        # Retrieve and return top 'limit' memories
+        result_memories = []
+        for memory_id, _ in recent_memories[:limit]:
+            memory = self.memories[memory_id]
+            memory.update_access()  # Update access time
+            result_memories.append(memory.as_dict())
+        
+        return result_memories
+    
+    def get_temporal_sequence(self, start_index: int = 0, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get temporal sequence of episodic memories.
+        
+        Args:
+            start_index: Starting index in sequence
+            limit: Maximum number of results
+            
+        Returns:
+            List of episodic memories in temporal order
+        """
+        # Get subset of temporal sequence
+        sequence_slice = self.temporal_sequence[start_index:start_index+limit]
+        
+        # Retrieve and return memories
+        result_memories = []
+        for memory_id in sequence_slice:
+            if memory_id in self.memories:
+                memory = self.memories[memory_id]
+                memory.update_access()  # Update access time
+                result_memories.append(memory.as_dict())
+        
+        return result_memories
+    
+    def get_relevant_experiences(self, query: Optional[Dict[str, Any]] = None, 
+                              tags: Optional[List[str]] = None, limit: int = 5) -> List[Dict[str, Any]]:
+        """
+        Get relevant episodic experiences.
+        
+        Args:
+            query: Optional query terms
+            tags: Optional filter by tags
+            limit: Maximum number of results
+            
+        Returns:
+            List of relevant experiences
+        """
+        # If query provided, use query_memories with episodic filter
+        if query:
+            return self.query_memories(query, memory_type="episodic", tags=tags, limit=limit)
+        
+        # Otherwise get most salient episodic memories
+        # Filter by tags if provided
+        candidate_ids = set()
+        if tags:
+            for tag in tags:
+                candidate_ids.update(self.episodic_index.get(tag, set()))
+        else:
+            # Get all episodic memories
+            candidate_ids = {memory_id for memory_id, memory in self.memories.items()
+                          if memory.memory_type == "episodic"}
+        
+        # Score by current salience
+        scored_candidates = []
+        for memory_id in candidate_ids:
+            if memory_id in self.memories:
+                memory = self.memories[memory_id]
+                current_salience = memory.calculate_current_salience()
+                
+                # Skip memories below activation threshold
+                if current_salience < self.activation_threshold:
+                    continue
+                
+                scored_candidates.append((memory_id, current_salience))
+        
+        # Sort by salience (descending) and take top 'limit' results
+        top_candidates = heapq.nlargest(limit, scored_candidates, key=lambda x: x[1])
+        
+        # Retrieve and return memories
+        result_memories = []
+        for memory_id, _ in top_candidates:
+            memory = self.memories[memory_id]
+            memory.update_access()  # Update access time
+            result_memories.append(memory.as_dict())
+        
+        return result_memories
+    
+    def get_beliefs(self, tags: Optional[List[str]] = None, certainty_threshold: float = 0.5) -> List[Dict[str, Any]]:
+        """
+        Get semantic beliefs with high certainty.
+        
+        Args:
+            tags: Optional filter by tags
+            certainty_threshold: Minimum certainty threshold
+            
+        Returns:
+            List of semantic beliefs
+        """
+        # Filter by tags if provided
+        candidate_ids = set()
+        if tags:
+            for tag in tags:
+                candidate_ids.update(self.semantic_index.get(tag, set()))
+        else:
+            # Get all semantic memories
+            candidate_ids = {memory_id for memory_id, memory in self.memories.items()
+                          if memory.memory_type == "semantic"}
+        
+        # Filter and score by certainty and salience
+        scored_candidates = []
+        for memory_id in candidate_ids:
+            if memory_id in self.memories:
+                memory = self.memories[memory_id]
+                
+                # Skip if not semantic or below certainty threshold
+                if memory.memory_type != "semantic" or not hasattr(memory, "certainty"):
+                    continue
+                
+                if memory.certainty < certainty_threshold:
+                    continue
+                
+                # Calculate current salience
+                current_salience = memory.calculate_current_salience()
+                
+                # Skip memories below activation threshold
+                if current_salience < self.activation_threshold:
+                    continue
+                
+                # Score combines certainty and salience
+                score = 0.6 * memory.certainty + 0.4 * current_salience
+                
+                scored_candidates.append((memory_id, score))
+        
+        # Sort by score (descending)
+        scored_candidates.sort(key=lambda x: x[1], reverse=True)
+        
+        # Retrieve and return memories
+        result_memories = []
+        for memory_id, score in scored_candidates:
+            memory = self.memories[memory_id]
+            memory.update_access()  # Update access time
+            
+            # Convert to dictionary and add score
+            memory_dict = memory.as_dict()
+            memory_dict["belief_score"] = score
+            
+            result_memories.append(memory_dict)
+        
+        return result_memories
+    
+    def apply_decay(self) -> int:
+        """
+        Apply memory decay to all memories and clean up decayed memories.
+        
+        Returns:
+            Number of memories removed due to decay
+        """
+        # Track memories to remove
+        to_remove = []
+        
+        # Check all memories
+        for memory_id, memory in self.memories.items():
+            # Calculate current salience
+            current_salience = memory.calculate_current_salience()
+            
+            # Mark for removal if below threshold
+            if current_salience < self.activation_threshold:
+                to_remove.append(memory_id)
+        
+        # Remove decayed memories
+        for memory_id in to_remove:
+            self._remove_memory(memory_id)
+        
+        # Update stats
+        self.stats["total_memories_decayed"] += len(to_remove)
+        self.stats["working_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "working")
+        self.stats["episodic_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "episodic")
+        self.stats["semantic_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "semantic")
+        
+        # Calculate average salience
+        if self.memories:
+            self.stats["average_salience"] = sum(m.calculate_current_salience() for m in self.memories.values()) / len(self.memories)
+        
+        return len(to_remove)
+    
+    def consolidate_memories(self) -> Dict[str, Any]:
+        """
+        Consolidate episodic memories into semantic memories.
+        
+        Returns:
+            Consolidation results
+        """
+        # Not fully implemented - this would involve more complex semantic extraction
+        # Simple implementation: just extract common tags from recent episodic memories
+        recent_episodic = self.get_recent_memories(memory_type="episodic", limit=10)
+        
+        # Count tag occurrences
+        tag_counts = defaultdict(int)
+        for memory in recent_episodic:
+            for tag in memory.get("tags", []):
+                tag_counts[tag] += 1
+        
+        # Find common tags (appearing in at least 3 memories)
+        common_tags = {tag for tag, count in tag_counts.items() if count >= 3}
+        
+        # Create semantic memory for common tags if not empty
+        consolidated_ids = []
+        if common_tags:
+            # Create semantic memory
+            semantic_id = self.add_semantic_memory(
+                content={
+                    "consolidated_from": [m.get("id") for m in recent_episodic],
+                    "common_tags": list(common_tags),
+                    "summary": f"Consolidated memory with common tags: {', '.join(common_tags)}"
+                },
+                certainty=0.6,
+                tags=list(common_tags),
+            )
+            
+            consolidated_ids.append(semantic_id)
+        
+        return {
+            "consolidated_count": len(consolidated_ids),
+            "consolidated_ids": consolidated_ids,
+            "common_tags": list(common_tags) if common_tags else []
+        }
+    
+    def _calculate_relevance(self, memory: Memory, query: Dict[str, Any]) -> float:
+        """
+        Calculate relevance score of memory to query.
+        
+        Args:
+            memory: Memory to score
+            query: Query terms
+            
+        Returns:
+            Relevance score (0-1)
+        """
+        # Simple implementation: check for key overlaps
+        relevance = 0.0
+        
+        # Extract memory content
+        content = memory.content
+        
+        # Count matching keys at top level
+        matching_keys = set(query.keys()).intersection(set(content.keys()))
+        if matching_keys:
+            relevance += 0.3 * (len(matching_keys) / len(query))
+        
+        # Check for matching values (simple string contains)
+        for key, value in query.items():
+            if key in content and isinstance(value, str) and isinstance(content[key], str):
+                if value.lower() in content[key].lower():
+                    relevance += 0.2
+            elif key in content and value == content[key]:
+                relevance += 0.3
+        
+        # Check for tag matches
+        query_tags = query.get("tags", [])
+        if isinstance(query_tags, list) and memory.tags:
+            matching_tags = set(query_tags).intersection(set(memory.tags))
+            if matching_tags:
+                relevance += 0.3 * (len(matching_tags) / len(query_tags))
+        
+        # Cap relevance at 1.0
+        return min(1.0, relevance)
+    
+    def _enforce_working_memory_capacity(self) -> None:
+        """Enforce working memory capacity limit by removing low priority items."""
+        # Count working memories
+        working_memories = [(memory_id, memory) for memory_id, memory in self.memories.items()
+                          if memory.memory_type == "working"]
+        
+        # Check if over capacity
+        if len(working_memories) <= self.working_memory_capacity:
+            return
+        
+        # Sort by priority (ascending) and salience (ascending)
+        working_memories.sort(key=lambda x: (x[1].priority, x[1].calculate_current_salience()))
+        
+        # Remove lowest priority items until under capacity
+        for memory_id, _ in working_memories[:len(working_memories) - self.working_memory_capacity]:
+            self._remove_memory(memory_id)
+    
+    def _remove_memory(self, memory_id: str) -> None:
+        """
+        Remove memory by ID.
+        
+        Args:
+            memory_id: Memory ID to remove
+        """
+        if memory_id not in self.memories:
+            return
+        
+        # Get memory before removal
+        memory = self.memories[memory_id]
+        
+        # Remove from memory dictionary
+        del self.memories[memory_id]
+        
+        # Remove from indices
+        for tag in memory.tags:
+            if memory.memory_type == "episodic" and tag in self.episodic_index:
+                self.episodic_index[tag].discard(memory_id)
+            elif memory.memory_type == "semantic" and tag in self.semantic_index:
+                self.semantic_index[tag].discard(memory_id)
+        
+        # Remove from temporal sequence if episodic
+        if memory.memory_type == "episodic":
+            if memory_id in self.temporal_sequence:
+                self.temporal_sequence.remove(memory_id)
+        
+        # Update associations in other memories
+        for other_id, other_memory in self.memories.items():
+            if memory_id in other_memory.associations:
+                del other_memory.associations[memory_id]
+    
+    def export_state(self) -> Dict[str, Any]:
+        """
+        Export memory shell state.
+        
+        Returns:
+            Serializable memory shell state
+        """
+        # Export memory dictionaries
+        memory_dicts = {memory_id: memory.as_dict() for memory_id, memory in self.memories.items()}
+        
+        # Export indices (convert sets to lists for serialization)
+        episodic_index = {tag: list(memories) for tag, memories in self.episodic_index.items()}
+        semantic_index = {tag: list(memories) for tag, memories in self.semantic_index.items()}
+        
+        # Export state
+        state = {
+            "memories": memory_dicts,
+            "episodic_index": episodic_index,
+            "semantic_index": semantic_index,
+            "temporal_sequence": self.temporal_sequence,
+            "decay_rate": self.decay_rate,
+            "activation_threshold": self.activation_threshold,
+            "working_memory_capacity": self.working_memory_capacity,
+            "stats": self.stats,
+        }
+        
+        return state
+    
+    def import_state(self, state: Dict[str, Any]) -> None:
+        """
+        Import memory shell state.
+        
+        Args:
+            state: Memory shell state
+        """
+        # Clear current state
+        self.memories = {}
+        self.episodic_index = defaultdict(set)
+        self.semantic_index = defaultdict(set)
+        self.temporal_sequence = []
+        
+        # Import configuration
+        self.decay_rate = state.get("decay_rate", self.decay_rate)
+        self.activation_threshold = state.get("activation_threshold", self.activation_threshold)
+        self.working_memory_capacity = state.get("working_memory_capacity", self.working_memory_capacity)
+        
+        # Import memories
+        for memory_id, memory_dict in state.get("memories", {}).items():
+            memory_type = memory_dict.get("memory_type")
+            
+            if memory_type == "working":
+                # Create working memory
+                memory = WorkingMemory(
+                    id=memory_id,
+                    content=memory_dict.get("content", {}),
+                    priority=memory_dict.get("priority", 1),
+                    decay_rate=memory_dict.get("decay_rate", self.decay_rate * 2),
+                    tags=memory_dict.get("tags", []),
+                    source=memory_dict.get("source", "working"),
+                    salience=memory_dict.get("salience", 1.0),
+                    creation_time=datetime.datetime.fromisoformat(memory_dict.get("creation_time", datetime.datetime.now().isoformat())),
+                    last_access_time=datetime.datetime.fromisoformat(memory_dict.get("last_access_time", datetime.datetime.now().isoformat())),
+                    access_count=memory_dict.get("access_count", 1),
+                    associations=memory_dict.get("associations", {}),
+                )
+                
+                # Set expiration time
+                if "expiration_time" in memory_dict:
+                    memory.expiration_time = datetime.datetime.fromisoformat(memory_dict["expiration_time"])
+                else:
+                    memory.set_expiration(1.0)
+                
+                # Store memory
+                self.memories[memory_id] = memory
+                
+            elif memory_type == "episodic":
+                # Create episodic memory
+                memory = EpisodicMemory(
+                    id=memory_id,
+                    content=memory_dict.get("content", {}),
+                    emotional_valence=memory_dict.get("emotional_valence", 0.0),
+                    outcome=memory_dict.get("outcome"),
+                    decay_rate=memory_dict.get("decay_rate", self.decay_rate),
+                    tags=memory_dict.get("tags", []),
+                    source=memory_dict.get("source", "episode"),
+                    salience=memory_dict.get("salience", 1.0),
+                    creation_time=datetime.datetime.fromisoformat(memory_dict.get("creation_time", datetime.datetime.now().isoformat())),
+                    last_access_time=datetime.datetime.fromisoformat(memory_dict.get("last_access_time", datetime.datetime.now().isoformat())),
+                    access_count=memory_dict.get("access_count", 1),
+                    associations=memory_dict.get("associations", {}),
+                    sequence_position=memory_dict.get("sequence_position"),
+                )
+                
+                # Store memory
+                self.memories[memory_id] = memory
+                
+            elif memory_type == "semantic":
+                # Create semantic memory
+                memory = SemanticMemory(
+                    id=memory_id,
+                    content=memory_dict.get("content", {}),
+                    certainty=memory_dict.get("certainty", 0.7),
+                    decay_rate=memory_dict.get("decay_rate", self.decay_rate * 0.5),
+                    tags=memory_dict.get("tags", []),
+                    source=memory_dict.get("source", "semantic"),
+                    salience=memory_dict.get("salience", 1.0),
+                    creation_time=datetime.datetime.fromisoformat(memory_dict.get("creation_time", datetime.datetime.now().isoformat())),
+                    last_access_time=datetime.datetime.fromisoformat(memory_dict.get("last_access_time", datetime.datetime.now().isoformat())),
+                    access_count=memory_dict.get("access_count", 1),
+                    associations=memory_dict.get("associations", {}),
+                    contradiction_ids=memory_dict.get("contradiction_ids", []),
+                    supporting_evidence=memory_dict.get("supporting_evidence", []),
+                )
+                
+                # Store memory
+                self.memories[memory_id] = memory
+        
+        # Import indices
+        for tag, memory_ids in state.get("episodic_index", {}).items():
+            self.episodic_index[tag] = set(memory_ids)
+        
+        for tag, memory_ids in state.get("semantic_index", {}).items():
+            self.semantic_index[tag] = set(memory_ids)
+        
+        # Import temporal sequence
+        self.temporal_sequence = state.get("temporal_sequence", [])
+        
+        # Import stats
+        self.stats = state.get("stats", self.stats.copy())
+        
+        # Update stats
+        self.stats["working_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "working")
+        self.stats["episodic_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "episodic")
+        self.stats["semantic_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "semantic")
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get memory shell statistics.
+        
+        Returns:
+            Memory statistics
+        """
+        # Update current stats
+        self.stats["working_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "working")
+        self.stats["episodic_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "episodic")
+        self.stats["semantic_memory_count"] = sum(1 for m in self.memories.values() if m.memory_type == "semantic")
+        
+        # Calculate average salience
+        if self.memories:
+            self.stats["average_salience"] = sum(m.calculate_current_salience() for m in self.memories.values()) / len(self.memories)
+        
+        # Calculate additional stats
+        active_memories = sum(1 for m in self.memories.values() 
+                           if m.calculate_current_salience() >= self.activation_threshold)
+        
+        tag_stats = {
+            "episodic_tags": len(self.episodic_index),
+            "semantic_tags": len(self.semantic_index),
+        }
+        
+        decay_stats = {
+            "activation_threshold": self.activation_threshold,
+            "active_memory_ratio": active_memories / len(self.memories) if self.memories else 0,
+            "decay_rate": self.decay_rate,
+        }
+        
+        return {
+            **self.stats,
+            **tag_stats,
+            **decay_stats,
+            "total_memories": len(self.memories),
+            "active_memories": active_memories,
+        }

src/llm/router.py

@@ -0,0 +1,925 @@
+"""
+ModelRouter - Multi-Model LLM Orchestration Framework
+
+This module implements the model routing architecture that allows agents to 
+interact with various LLM providers including:
+- OpenAI (GPT models)
+- Anthropic (Claude models)
+- Groq (Llama and Mixtral)
+- Ollama (local models)
+- DeepSeek (DeepSeek models)
+
+Key capabilities:
+- Provider-agnostic interface for agent interactions
+- Dynamic provider selection based on capabilities
+- Fallback chains for reliability
+- Prompt template management with provider-specific optimizations
+- Token usage tracking and optimization
+- Output parsing and normalization
+
+Internal Note: The model router implements a symbolic abstraction layer over
+different LLM providers while maintaining a unified attribution interface.
+"""
+
+import os
+import json
+import logging
+import time
+import asyncio
+from typing import Dict, List, Any, Optional, Union, Callable
+import traceback
+from enum import Enum
+from abc import ABC, abstractmethod
+
+# Optional imports for different providers
+try:
+    import openai
+except ImportError:
+    openai = None
+
+try:
+    import anthropic
+except ImportError:
+    anthropic = None
+
+try:
+    import groq
+except ImportError:
+    groq = None
+
+try:
+    import ollama
+except ImportError:
+    ollama = None
+
+
+class ModelCapability(Enum):
+    """Capabilities that models may support."""
+    REASONING = "reasoning"             # Complex multi-step reasoning
+    CODE_GENERATION = "code_generation" # Code writing and analysis
+    FINANCE = "finance"                 # Financial analysis and modeling
+    RAG = "rag"                         # Retrieval augmented generation
+    TOOL_USE = "tool_use"               # Using external tools
+    FUNCTION_CALLING = "function_calling" # Structured function calling
+    JSON_MODE = "json_mode"             # Reliable JSON output
+
+
+class ModelProvider(ABC):
+    """Abstract base class for model providers."""
+    
+    @abstractmethod
+    def generate(self, prompt: str, **kwargs) -> str:
+        """Generate text from prompt."""
+        pass
+    
+    @abstractmethod
+    def get_available_models(self) -> List[str]:
+        """Get list of available models."""
+        pass
+    
+    @abstractmethod
+    def get_model_capabilities(self, model_name: str) -> List[ModelCapability]:
+        """Get capabilities of a specific model."""
+        pass
+
+
+class OpenAIProvider(ModelProvider):
+    """OpenAI model provider."""
+    
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize OpenAI provider.
+        
+        Args:
+            api_key: OpenAI API key (defaults to OPENAI_API_KEY env var)
+        """
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY")
+        
+        if not self.api_key:
+            logging.warning("OpenAI API key not provided. OpenAI provider will not work.")
+        
+        if openai is None:
+            logging.warning("OpenAI Python package not installed. OpenAI provider will not work.")
+        
+        # Initialize client if possible
+        self.client = None
+        if openai is not None and self.api_key:
+            self.client = openai.OpenAI(api_key=self.api_key)
+        
+        # Define models and capabilities
+        self.models = {
+            "gpt-4-0125-preview": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+                ModelCapability.TOOL_USE,
+                ModelCapability.FUNCTION_CALLING,
+                ModelCapability.JSON_MODE,
+            ],
+            "gpt-4-turbo-preview": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+                ModelCapability.TOOL_USE,
+                ModelCapability.FUNCTION_CALLING,
+                ModelCapability.JSON_MODE,
+            ],
+            "gpt-4": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+                ModelCapability.TOOL_USE,
+                ModelCapability.FUNCTION_CALLING,
+            ],
+            "gpt-3.5-turbo": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+                ModelCapability.TOOL_USE,
+                ModelCapability.FUNCTION_CALLING,
+                ModelCapability.FUNCTION_CALLING,
+                ModelCapability.JSON_MODE,
+            ],
+            "gpt-3.5-turbo-instruct": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+        }
+    
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt using OpenAI.
+        
+        Args:
+            prompt: Input prompt
+            **kwargs: Additional parameters
+                - model: Model name (default: gpt-4-turbo-preview)
+                - temperature: Temperature (default: 0.7)
+                - max_tokens: Maximum tokens (default: 2000)
+                - json_mode: Whether to enforce JSON output (default: False)
+            
+        Returns:
+            Generated text
+        """
+        if self.client is None:
+            raise ValueError("OpenAI client not initialized. Provide a valid API key.")
+        
+        # Extract parameters with defaults
+        model = kwargs.get("model", "gpt-4-turbo-preview")
+        temperature = kwargs.get("temperature", 0.7)
+        max_tokens = kwargs.get("max_tokens", 2000)
+        json_mode = kwargs.get("json_mode", False)
+        
+        try:
+            # Create messages
+            messages = [{"role": "user", "content": prompt}]
+            
+            # Create parameters
+            params = {
+                "model": model,
+                "messages": messages,
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+            }
+            
+            # Add response format if JSON mode
+            if json_mode:
+                params["response_format"] = {"type": "json_object"}
+            
+            # Make request
+            response = self.client.chat.completions.create(**params)
+            
+            # Extract text
+            return response.choices[0].message.content
+            
+        except Exception as e:
+            logging.error(f"Error generating text with OpenAI: {e}")
+            logging.error(traceback.format_exc())
+            raise
+    
+    def get_available_models(self) -> List[str]:
+        """Get list of available models."""
+        return list(self.models.keys())
+    
+    def get_model_capabilities(self, model_name: str) -> List[ModelCapability]:
+        """Get capabilities of a specific model."""
+        return self.models.get(model_name, [])
+
+
+class AnthropicProvider(ModelProvider):
+    """Anthropic model provider."""
+    
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize Anthropic provider.
+        
+        Args:
+            api_key: Anthropic API key (defaults to ANTHROPIC_API_KEY env var)
+        """
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        
+        if not self.api_key:
+            logging.warning("Anthropic API key not provided. Anthropic provider will not work.")
+        
+        if anthropic is None:
+            logging.warning("Anthropic Python package not installed. Anthropic provider will not work.")
+        
+        # Initialize client if possible
+        self.client = None
+        if anthropic is not None and self.api_key:
+            self.client = anthropic.Anthropic(api_key=self.api_key)
+        
+        # Define models and capabilities
+        self.models = {
+            "claude-3-opus-20240229": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+                ModelCapability.TOOL_USE,
+                ModelCapability.JSON_MODE,
+            ],
+            "claude-3-sonnet-20240229": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+                ModelCapability.TOOL_USE,
+                ModelCapability.JSON_MODE,
+            ],
+            "claude-3-haiku-20240307": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+                ModelCapability.JSON_MODE,
+            ],
+            "claude-2.1": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+            ],
+            "claude-2.0": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+            ],
+            "claude-instant-1.2": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+        }
+    
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt using Anthropic.
+        
+        Args:
+            prompt: Input prompt
+            **kwargs: Additional parameters
+                - model: Model name (default: claude-3-sonnet-20240229)
+                - temperature: Temperature (default: 0.7)
+                - max_tokens: Maximum tokens (default: 2000)
+                - system_prompt: Optional system prompt
+            
+        Returns:
+            Generated text
+        """
+        if self.client is None:
+            raise ValueError("Anthropic client not initialized. Provide a valid API key.")
+        
+        # Extract parameters with defaults
+        model = kwargs.get("model", "claude-3-sonnet-20240229")
+        temperature = kwargs.get("temperature", 0.7)
+        max_tokens = kwargs.get("max_tokens", 2000)
+        system_prompt = kwargs.get("system_prompt", "")
+        
+        try:
+            # Create parameters
+            params = {
+                "model": model,
+                "messages": [{"role": "user", "content": prompt}],
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+            }
+            
+            # Add system prompt if provided
+            if system_prompt:
+                params["system"] = system_prompt
+            
+            # Make request
+            response = self.client.messages.create(**params)
+            
+            # Extract text
+            return response.content[0].text
+            
+        except Exception as e:
+            logging.error(f"Error generating text with Anthropic: {e}")
+            logging.error(traceback.format_exc())
+            raise
+    
+    def get_available_models(self) -> List[str]:
+        """Get list of available models."""
+        return list(self.models.keys())
+    
+    def get_model_capabilities(self, model_name: str) -> List[ModelCapability]:
+        """Get capabilities of a specific model."""
+        return self.models.get(model_name, [])
+
+
+class GroqProvider(ModelProvider):
+    """Groq model provider."""
+    
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize Groq provider.
+        
+        Args:
+            api_key: Groq API key (defaults to GROQ_API_KEY env var)
+        """
+        self.api_key = api_key or os.environ.get("GROQ_API_KEY")
+        
+        if not self.api_key:
+            logging.warning("Groq API key not provided. Groq provider will not work.")
+        
+        if groq is None:
+            logging.warning("Groq Python package not installed. Groq provider will not work.")
+        
+        # Initialize client if possible
+        self.client = None
+        if groq is not None and self.api_key:
+            self.client = groq.Groq(api_key=self.api_key)
+        
+        # Define models and capabilities
+        self.models = {
+            "llama2-70b-4096": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+            ],
+            "mixtral-8x7b-32768": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+            ],
+            "gemma-7b-it": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+        }
+    
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt using Groq.
+        
+        Args:
+            prompt: Input prompt
+            **kwargs: Additional parameters
+                - model: Model name (default: mixtral-8x7b-32768)
+                - temperature: Temperature (default: 0.7)
+                - max_tokens: Maximum tokens (default: 2000)
+            
+        Returns:
+            Generated text
+        """
+        if self.client is None:
+            raise ValueError("Groq client not initialized. Provide a valid API key.")
+        
+        # Extract parameters with defaults
+        model = kwargs.get("model", "mixtral-8x7b-32768")
+        temperature = kwargs.get("temperature", 0.7)
+        max_tokens = kwargs.get("max_tokens", 2000)
+        
+        try:
+            # Create parameters
+            params = {
+                "model": model,
+                "messages": [{"role": "user", "content": prompt}],
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+            }
+            
+            # Make request
+            response = self.client.chat.completions.create(**params)
+            
+            # Extract text
+            return response.choices[0].message.content
+            
+        except Exception as e:
+            logging.error(f"Error generating text with Groq: {e}")
+            logging.error(traceback.format_exc())
+            raise
+    
+    def get_available_models(self) -> List[str]:
+        """Get list of available models."""
+        return list(self.models.keys())
+    
+    def get_model_capabilities(self, model_name: str) -> List[ModelCapability]:
+        """Get capabilities of a specific model."""
+        return self.models.get(model_name, [])
+
+
+class OllamaProvider(ModelProvider):
+    """Ollama model provider for local models."""
+    
+    def __init__(self, host: str = "http://localhost:11434"):
+        """
+        Initialize Ollama provider.
+        
+        Args:
+            host: Ollama host address (default: http://localhost:11434)
+        """
+        self.host = host
+        
+        if ollama is None:
+            logging.warning("Ollama Python package not installed. Ollama provider will not work.")
+        
+        # Check if Ollama is available
+        self.available = False
+        if ollama is not None:
+            try:
+                # Try to list models
+                self._list_models()
+                self.available = True
+            except Exception as e:
+                logging.warning(f"Ollama not available: {e}")
+        
+        # Define models and capabilities
+        self.models = {
+            "llama3:latest": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+            "mistral:latest": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+            "codellama:latest": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+            "deepseek-coder:latest": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+            "wizardcoder:latest": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+            "gemma2:latest": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+        }
+    
+    def _list_models(self) -> List[str]:
+        """List available Ollama models."""
+        if ollama is None:
+            return []
+        
+        try:
+            response = ollama.list(api_base=self.host)
+            return [model['name'] for model in response['models']]
+        except Exception as e:
+            logging.error(f"Error listing Ollama models: {e}")
+            return []
+    
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt using Ollama.
+        
+        Args:
+            prompt: Input prompt
+            **kwargs: Additional parameters
+                - model: Model name (default: mistral:latest)
+                - temperature: Temperature (default: 0.7)
+                - max_tokens: Maximum tokens (default: 2000)
+            
+        Returns:
+            Generated text
+        """
+        if ollama is None:
+            raise ValueError("Ollama package not installed.")
+        
+        if not self.available:
+            raise ValueError("Ollama not available.")
+        
+        # Extract parameters with defaults
+        model = kwargs.get("model", "mistral:latest")
+        temperature = kwargs.get("temperature", 0.7)
+        max_tokens = kwargs.get("max_tokens", 2000)
+        
+        try:
+            # Make request
+            response = ollama.chat(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=temperature,
+                num_predict=max_tokens,
+                api_base=self.host,
+            )
+            
+            # Extract text
+            return response['message']['content']
+            
+        except Exception as e:
+            logging.error(f"Error generating text with Ollama: {e}")
+            logging.error(traceback.format_exc())
+            raise
+    
+    def get_available_models(self) -> List[str]:
+        """Get list of available models."""
+        if not self.available:
+            return []
+        
+        return self._list_models()
+    
+    def get_model_capabilities(self, model_name: str) -> List[ModelCapability]:
+        """Get capabilities of a specific model."""
+        # For unknown models, assume basic capabilities
+        if model_name not in self.models:
+            return [ModelCapability.RAG]
+        
+        return self.models.get(model_name, [])
+
+
+class DeepSeekProvider(ModelProvider):
+    """DeepSeek model provider using OpenAI-compatible API."""
+    
+    def __init__(self, api_key: Optional[str] = None, api_base: str = "https://api.deepseek.com/v1"):
+        """
+        Initialize DeepSeek provider.
+        
+        Args:
+            api_key: DeepSeek API key (defaults to DEEPSEEK_API_KEY env var)
+            api_base: DeepSeek API base URL
+        """
+        self.api_key = api_key or os.environ.get("DEEPSEEK_API_KEY")
+        self.api_base = api_base
+        
+        if not self.api_key:
+            logging.warning("DeepSeek API key not provided. DeepSeek provider will not work.")
+        
+        if openai is None:
+            logging.warning("OpenAI Python package not installed. DeepSeek provider will not work.")
+        
+        # Initialize client if possible
+        self.client = None
+        if openai is not None and self.api_key:
+            self.client = openai.OpenAI(
+                api_key=self.api_key,
+                base_url=self.api_base,
+            )
+        
+        # Define models and capabilities
+        self.models = {
+            "deepseek-chat": [
+                ModelCapability.REASONING,
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.FINANCE,
+                ModelCapability.RAG,
+            ],
+            "deepseek-coder": [
+                ModelCapability.CODE_GENERATION,
+                ModelCapability.RAG,
+            ],
+        }
+    
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt using DeepSeek.
+        
+        Args:
+            prompt: Input prompt
+            **kwargs: Additional parameters
+                - model: Model name (default: deepseek-chat)
+                - temperature: Temperature (default: 0.7)
+                - max_tokens: Maximum tokens (default: 2000)
+            
+        Returns:
+            Generated text
+        """
+        if self.client is None:
+            raise ValueError("DeepSeek client not initialized. Provide a valid API key.")
+        
+        # Extract parameters with defaults
+        model = kwargs.get("model", "deepseek-chat")
+        temperature = kwargs.get("temperature", 0.7)
+        max_tokens = kwargs.get("max_tokens", 2000)
+        
+        try:
+            # Create messages
+            messages = [{"role": "user", "content": prompt}]
+            
+            # Make request
+            response = self.client.chat.completions.create(
+                model=model,
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+            
+            # Extract text
+            return response.choices[0].message.content
+            
+        except Exception as e:
+            logging.error(f"Error generating text with DeepSeek: {e}")
+            logging.error(traceback.format_exc())
+            raise
+    
+    def get_available_models(self) -> List[str]:
+        """Get list of available models."""
+        return list(self.models.keys())
+    
+    def get_model_capabilities(self, model_name: str) -> List[ModelCapability]:
+        """Get capabilities of a specific model."""
+        return self.models.get(model_name, [])
+
+
+class ModelRouter:
+    """
+    Model router for multi-provider LLM orchestration.
+    
+    The ModelRouter provides:
+    - Unified interface for multiple LLM providers
+    - Dynamic provider selection based on capabilities
+    - Fallback chains for reliability
+    - Prompt template management
+    - Attribution tracing for interpretability
+    """
+    
+    def __init__(
+        self,
+        provider: str = "anthropic",
+        model: Optional[str] = None,
+        fallback_providers: Optional[List[str]] = None,
+        openai_api_key: Optional[str] = None,
+        anthropic_api_key: Optional[str] = None,
+        groq_api_key: Optional[str] = None,
+    ):
+        """
+        Initialize model router.
+        
+        Args:
+            provider: Default provider
+            model: Default model (provider-specific)
+            fallback_providers: List of fallback providers
+            openai_api_key: OpenAI API key
+            anthropic_api_key: Anthropic API key
+            groq_api_key: Groq API key
+        """
+        self.default_provider = provider
+        self.default_model = model
+        self.fallback_providers = fallback_providers or []
+        
+        # Track usage
+        self.usage_stats = {
+            "total_calls": 0,
+            "total_tokens": 0,
+            "provider_calls": {},
+            "model_calls": {},
+            "errors": {},
+        }
+        
+        # Initialize providers
+        self.providers = {}
+        
+        # Initialize OpenAI
+        try:
+            self.providers["openai"] = OpenAIProvider(api_key=openai_api_key)
+            
+            # Set default model if not specified
+            if provider == "openai" and model is None:
+                self.default_model = "gpt-4-turbo-preview"
+        except Exception as e:
+            logging.warning(f"Failed to initialize OpenAI provider: {e}")
+        
+        # Initialize Anthropic
+        try:
+            self.providers["anthropic"] = AnthropicProvider(api_key=anthropic_api_key)
+            
+            # Set default model if not specified
+            if provider == "anthropic" and model is None:
+                self.default_model = "claude-3-sonnet-20240229"
+        except Exception as e:
+            logging.warning(f"Failed to initialize Anthropic provider: {e}")
+        
+        # Initialize Groq
+        try:
+            self.providers["groq"] = GroqProvider(api_key=groq_api_key)
+            
+            # Set default model if not specified
+            if provider == "groq" and model is None:
+                self.default_model = "mixtral-8x7b-32768"
+        except Exception as e:
+            logging.warning(f"Failed to initialize Groq provider: {e}")
+        
+        # Initialize Ollama
+        try:
+            self.providers["ollama"] = OllamaProvider()
+            
+            # Set default model if not specified
+            if provider == "ollama" and model is None:
+                self.default_model = "mistral:latest"
+        except Exception as e:
+            logging.warning(f"Failed to initialize Ollama provider: {e}")
+        
+        # Initialize DeepSeek
+        try:
+            self.providers["deepseek"] = DeepSeekProvider()
+            
+            # Set default model if not specified
+            if provider == "deepseek" and model is None:
+                self.default_model = "deepseek-chat"
+        except Exception as e:
+            logging.warning(f"Failed to initialize DeepSeek provider: {e}")
+        
+        # Verify default provider is available
+        if self.default_provider not in self.providers:
+            available_providers = list(self.providers.keys())
+            if available_providers:
+                logging.warning(f"Default provider '{self.default_provider}' not available. "
+                              f"Using '{available_providers[0]}' instead.")
+                self.default_provider = available_providers[0]
+            else:
+                raise ValueError("No LLM providers available. Check API keys and dependencies.")
+    
+    def generate(self, prompt: str, provider: Optional[str] = None, 
+               model: Optional[str] = None, **kwargs) -> str:
+        """
+        Generate text from prompt.
+        
+        Args:
+            prompt: Input prompt
+            provider: Provider to use (default is instance default)
+            model: Model to use (default is instance default)
+            **kwargs: Additional provider-specific parameters
+            
+        Returns:
+            Generated text
+        """
+        # Use default provider if not specified
+        provider = provider or self.default_provider
+        
+        # Use default model if not specified
+        model = model or self.default_model
+        
+        # Update usage stats
+        self.usage_stats["total_calls"] += 1
+        
+        # Update provider stats
+        if provider not in self.usage_stats["provider_calls"]:
+            self.usage_stats["provider_calls"][provider] = 0
+        self.usage_stats["provider_calls"][provider] += 1
+        
+        # Update model stats
+        model_key = f"{provider}:{model}"
+        if model_key not in self.usage_stats["model_calls"]:
+            self.usage_stats["model_calls"][model_key] = 0
+        self.usage_stats["model_calls"][model_key] += 1
+        
+        # Check if provider is available
+        if provider not in self.providers:
+            # Try fallback providers
+            for fallback_provider in self.fallback_providers:
+                if fallback_provider in self.providers:
+                    logging.warning(f"Provider '{provider}' not available. "
+                                  f"Using fallback provider '{fallback_provider}'.")
+                    return self.generate(prompt, provider=fallback_provider, model=model, **kwargs)
+            
+            # No fallback providers available
+            raise ValueError(f"Provider '{provider}' not available and no fallback providers available.")
+        
+        try:
+            # Get provider
+            provider_instance = self.providers[provider]
+            
+            # Add model to kwargs
+            if model:
+                kwargs["model"] = model
+            
+            # Generate text
+            start_time = time.time()
+            response = provider_instance.generate(prompt, **kwargs)
+            end_time = time.time()
+            
+            # Log generation time
+            logging.debug(f"Generated text with {provider}:{model} in {end_time - start_time:.2f} seconds.")
+            
+            return response
+            
+        except Exception as e:
+            # Update error stats
+            error_key = str(type(e).__name__)
+            if error_key not in self.usage_stats["errors"]:
+                self.usage_stats["errors"][error_key] = 0
+            self.usage_stats["errors"][error_key] += 1
+            
+            # Try fallback providers
+            for fallback_provider in self.fallback_providers:
+                if fallback_provider in self.providers:
+                    logging.warning(f"Error with provider '{provider}': {e}. "
+                                  f"Using fallback provider '{fallback_provider}'.")
+                    return self.generate(prompt, provider=fallback_provider, model=model, **kwargs)
+            
+            # No fallback providers available
+            logging.error(f"Error generating text with {provider}:{model}: {e}")
+            logging.error(traceback.format_exc())
+            raise
+    
+    async def generate_async(self, prompt: str, provider: Optional[str] = None, 
+                         model: Optional[str] = None, **kwargs) -> str:
+        """
+        Generate text from prompt asynchronously.
+        
+        Args:
+            prompt: Input prompt
+            provider: Provider to use (default is instance default)
+            model: Model to use (default is instance default)
+            **kwargs: Additional provider-specific parameters
+            
+        Returns:
+            Generated text
+        """
+        # Async implementation using run_in_executor
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None, 
+            lambda: self.generate(prompt, provider, model, **kwargs)
+        )
+    
+    def get_available_providers(self) -> List[str]:
+        """Get list of available providers."""
+        return list(self.providers.keys())
+    
+    def get_available_models(self, provider: Optional[str] = None) -> Dict[str, List[str]]:
+        """
+        Get available models for all providers or a specific provider.
+        
+        Args:
+            provider: Optional provider to get models for
+            
+        Returns:
+            Dictionary mapping providers to lists of models
+        """
+        if provider:
+            if provider not in self.providers:
+                return {}
+            
+            return {provider: self.providers[provider].get_available_models()}
+        
+        # Get models for all providers
+        models = {}
+        for provider_name, provider_instance in self.providers.items():
+            models[provider_name] = provider_instance.get_available_models()
+        
+        return models
+    
+    def get_model_capabilities(self, provider: str, model: str) -> List[ModelCapability]:
+        """
+        Get capabilities of a specific model.
+        
+        Args:
+            provider: Provider name
+            model: Model name
+            
+        Returns:
+            List of model capabilities
+        """
+        if provider not in self.providers:
+            return []
+        
+        return self.providers[provider].get_model_capabilities(model)
+    
+    def find_models_with_capabilities(self, capabilities: List[ModelCapability]) -> List[Tuple[str, str]]:
+        """
+        Find models that have all specified capabilities.
+        
+        Args:
+            capabilities: List of required capabilities
+            
+        Returns:
+            List of (provider, model) tuples that have all capabilities
+        """
+        matching_models = []
+        
+        for provider_name, provider_instance in self.providers.items():
+            for model in provider_instance.get_available_models():
+                model_capabilities = provider_instance.get_model_capabilities(model)
+                
+                # Check if model has all required capabilities
+                if all(capability in model_capabilities for capability in capabilities):
+                    matching_models.append((provider_name, model))
+        
+        return matching_models
+    
+    def get_usage_stats(self) -> Dict[str, Any]:
+        """Get usage statistics."""
+        return self.usage_stats.copy()

src/main.py

@@ -0,0 +1,685 @@
+#!/usr/bin/env python
+# shell.echo.seed = "🜏-mirror.activated-{timestamp}-{entropy.hash}"
+"""
+AGI-HEDGE-FUND - Multi-agent recursive market cognition framework
+
+This script serves as the entry point for the AGI-HEDGE-FUND system, providing
+command-line interface for running the multi-agent market cognition platform.
+
+Usage:
+    python -m src.main --mode backtest --start-date 2022-01-01 --end-date 2022-12-31
+    python -m src.main --mode live --data-source yahoo --show-trace
+    python -m src.main --mode analysis --portfolio-file portfolio.json --consensus-graph
+
+Internal Note: This script encodes the system's entry point while exposing the
+recursive cognitive architecture through interpretability flags.
+"""
+
+import argparse
+import datetime
+import json
+import logging
+import os
+import sys
+from typing import Dict, List, Any, Optional
+
+# Core components
+from agents.base import BaseAgent
+from agents.graham import GrahamAgent
+from agents.dalio import DalioAgent
+from agents.wood import WoodAgent
+from agents.ackman import AckmanAgent
+from agents.simons import SimonsAgent
+from agents.taleb import TalebAgent
+from portfolio.manager import PortfolioManager
+from market.environment import MarketEnvironment
+from llm.router import ModelRouter
+from utils.diagnostics import TracingTools, TracingMode, ShellDiagnostics, ShellFailureMap
+
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+
+logger = logging.getLogger("agi-hedge-fund")
+
+
+def parse_args():
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(description='AGI-HEDGE-FUND - Multi-agent recursive market cognition framework')
+    
+    # Operation mode
+    parser.add_argument('--mode', type=str, choices=['backtest', 'live', 'analysis'], default='backtest',
+                      help='Operation mode: backtest, live, or analysis')
+    
+    # Date range for backtesting
+    parser.add_argument('--start-date', type=str, default='2020-01-01',
+                      help='Start date for backtesting (YYYY-MM-DD)')
+    parser.add_argument('--end-date', type=str, default='2023-01-01',
+                      help='End date for backtesting (YYYY-MM-DD)')
+    
+    # Portfolio parameters
+    parser.add_argument('--initial-capital', type=float, default=100000.0,
+                      help='Initial capital amount')
+    parser.add_argument('--tickers', type=str, nargs='+', default=['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA'],
+                      help='Stock tickers to analyze')
+    parser.add_argument('--rebalance-frequency', type=str, choices=['daily', 'weekly', 'monthly'], default='weekly',
+                      help='Portfolio rebalance frequency')
+    
+    # Data source
+    parser.add_argument('--data-source', type=str, choices=['yahoo', 'polygon', 'alpha_vantage'], default='yahoo',
+                      help='Market data source')
+    parser.add_argument('--data-path', type=str, default='data',
+                      help='Path to data directory')
+    
+    # Agent configuration
+    parser.add_argument('--agents', type=str, nargs='+', 
+                      default=['graham', 'dalio', 'wood', 'ackman', 'simons', 'taleb'],
+                      help='Agents to use')
+    parser.add_argument('--reasoning-depth', type=int, default=3,
+                      help='Agent reasoning depth')
+    parser.add_argument('--arbitration-depth', type=int, default=2,
+                      help='Portfolio meta-agent arbitration depth')
+    
+    # LLM provider
+    parser.add_argument('--llm-provider', type=str, choices=['anthropic', 'openai', 'groq', 'ollama', 'deepseek'], 
+                      default='anthropic',
+                      help='LLM provider')
+    
+    # Model configuration
+    parser.add_argument('--model', type=str, default=None,
+                      help='Specific LLM model to use')
+    parser.add_argument('--fallback-providers', type=str, nargs='+', 
+                      default=['openai', 'groq'],
+                      help='Fallback LLM providers')
+    
+    # Output and visualization
+    parser.add_argument('--output-dir', type=str, default='output',
+                      help='Directory for output files')
+    parser.add_argument('--portfolio-file', type=str, default=None,
+                      help='Portfolio state file for analysis mode')
+    
+    # Diagnostic flags
+    parser.add_argument('--show-trace', action='store_true',
+                      help='Show reasoning traces')
+    parser.add_argument('--consensus-graph', action='store_true',
+                      help='Generate consensus graph visualization')
+    parser.add_argument('--agent-conflict-map', action='store_true',
+                      help='Generate agent conflict map visualization')
+    parser.add_argument('--attribution-report', action='store_true',
+                      help='Generate attribution report')
+    parser.add_argument('--shell-failure-map', action='store_true',
+                      help='Show shell failure map')
+    parser.add_argument('--trace-level', type=str, 
+                      choices=['disabled', 'minimal', 'detailed', 'comprehensive', 'symbolic'],
+                      default='minimal',
+                      help='Trace level for diagnostics')
+    
+    # Advanced options
+    parser.add_argument('--max-position-size', type=float, default=0.2,
+                      help='Maximum position size as fraction of portfolio')
+    parser.add_argument('--min-position-size', type=float, default=0.01,
+                      help='Minimum position size as fraction of portfolio')
+    parser.add_argument('--risk-budget', type=float, default=0.5,
+                      help='Risk budget (0-1)')
+    parser.add_argument('--memory-decay', type=float, default=0.2,
+                      help='Memory decay rate for agents')
+    
+    # Parse arguments
+    return parser.parse_args()
+
+
+def create_agents(args) -> List[BaseAgent]:
+    """
+    Create agent instances based on command-line arguments.
+    
+    Args:
+        args: Command-line arguments
+        
+    Returns:
+        List of agent instances
+    """
+    # Initialize model router
+    model_router = ModelRouter(
+        provider=args.llm_provider,
+        model=args.model,
+        fallback_providers=args.fallback_providers,
+    )
+    
+    # Get trace mode
+    trace_mode = TracingMode(args.trace_level)
+    
+    # Create agents
+    agents = []
+    
+    for agent_type in args.agents:
+        agent_type = agent_type.lower()
+        
+        if agent_type == "graham":
+            agent = GrahamAgent(
+                reasoning_depth=args.reasoning_depth,
+                memory_decay=args.memory_decay,
+                initial_capital=args.initial_capital,
+                model_provider=args.llm_provider,
+                model_name=args.model,
+                trace_enabled=args.show_trace,
+            )
+        elif agent_type == "dalio":
+            agent = DalioAgent(
+                reasoning_depth=args.reasoning_depth,
+                memory_decay=args.memory_decay,
+                initial_capital=args.initial_capital,
+                model_provider=args.llm_provider,
+                model_name=args.model,
+                trace_enabled=args.show_trace,
+            )
+        elif agent_type == "wood":
+            agent = WoodAgent(
+                reasoning_depth=args.reasoning_depth,
+                memory_decay=args.memory_decay,
+                initial_capital=args.initial_capital,
+                model_provider=args.llm_provider,
+                model_name=args.model,
+                trace_enabled=args.show_trace,
+            )
+        elif agent_type == "ackman":
+            agent = AckmanAgent(
+                reasoning_depth=args.reasoning_depth,
+                memory_decay=args.memory_decay,
+                initial_capital=args.initial_capital,
+                model_provider=args.llm_provider,
+                model_name=args.model,
+                trace_enabled=args.show_trace,
+            )
+        elif agent_type == "simons":
+            agent = SimonsAgent(
+                reasoning_depth=args.reasoning_depth,
+                memory_decay=args.memory_decay,
+                initial_capital=args.initial_capital,
+                model_provider=args.llm_provider,
+                model_name=args.model,
+                trace_enabled=args.show_trace,
+            )
+        elif agent_type == "taleb":
+            agent = TalebAgent(
+                reasoning_depth=args.reasoning_depth,
+                memory_decay=args.memory_decay,
+                initial_capital=args.initial_capital,
+                model_provider=args.llm_provider,
+                model_name=args.model,
+                trace_enabled=args.show_trace,
+            )
+        else:
+            logger.warning(f"Unknown agent type: {agent_type}")
+            continue
+        
+        agents.append(agent)
+    
+    logger.info(f"Created {len(agents)} agents: {', '.join(agent.name for agent in agents)}")
+    
+    return agents
+
+
+def create_portfolio_manager(agents: List[BaseAgent], args) -> PortfolioManager:
+    """
+    Create portfolio manager instance.
+    
+    Args:
+        agents: List of agent instances
+        args: Command-line arguments
+        
+    Returns:
+        Portfolio manager instance
+    """
+    # Create portfolio manager
+    portfolio_manager = PortfolioManager(
+        agents=agents,
+        initial_capital=args.initial_capital,
+        arbitration_depth=args.arbitration_depth,
+        max_position_size=args.max_position_size,
+        min_position_size=args.min_position_size,
+        consensus_threshold=0.6,
+        show_trace=args.show_trace,
+        risk_budget=args.risk_budget,
+    )
+    
+    logger.info(f"Created portfolio manager with {len(agents)} agents")
+    
+    return portfolio_manager
+
+
+def create_market_environment(args) -> MarketEnvironment:
+    """
+    Create market environment instance.
+    
+    Args:
+        args: Command-line arguments
+        
+    Returns:
+        Market environment instance
+    """
+    # Create market environment
+    market_env = MarketEnvironment(
+        data_source=args.data_source,
+        tickers=args.tickers,
+        data_path=args.data_path,
+        start_date=args.start_date if args.mode == "backtest" else None,
+        end_date=args.end_date if args.mode == "backtest" else None,
+    )
+    
+    logger.info(f"Created market environment with {len(args.tickers)} tickers")
+    
+    return market_env
+
+
+def run_backtest(portfolio_manager: PortfolioManager, market_env: MarketEnvironment, args) -> Dict[str, Any]:
+    """
+    Run backtesting simulation.
+    
+    Args:
+        portfolio_manager: Portfolio manager instance
+        market_env: Market environment instance
+        args: Command-line arguments
+        
+    Returns:
+        Backtest results
+    """
+    # Parse dates
+    start_date = datetime.datetime.strptime(args.start_date, "%Y-%m-%d").date()
+    end_date = datetime.datetime.strptime(args.end_date, "%Y-%m-%d").date()
+    
+    # Set up rebalance frequency
+    if args.rebalance_frequency == "daily":
+        rebalance_days = 1
+    elif args.rebalance_frequency == "weekly":
+        rebalance_days = 7
+    else:  # monthly
+        rebalance_days = 30
+    
+    # Run simulation
+    results = portfolio_manager.run_simulation(
+        start_date=args.start_date,
+        end_date=args.end_date,
+        data_source=args.data_source,
+        rebalance_frequency=args.rebalance_frequency,
+    )
+    
+    logger.info(f"Completed backtest from {args.start_date} to {args.end_date}")
+    
+    # Save results
+    os.makedirs(args.output_dir, exist_ok=True)
+    results_file = os.path.join(args.output_dir, f"backtest_results_{start_date}_{end_date}.json")
+    
+    with open(results_file, 'w') as f:
+        json.dump(results, f, indent=2, default=str)
+    
+    logger.info(f"Saved backtest results to {results_file}")
+    
+    # Generate visualizations if requested
+    if args.consensus_graph:
+        consensus_graph = portfolio_manager.visualize_consensus_graph()
+        consensus_file = os.path.join(args.output_dir, f"consensus_graph_{start_date}_{end_date}.json")
+        
+        with open(consensus_file, 'w') as f:
+            json.dump(consensus_graph, f, indent=2, default=str)
+        
+        logger.info(f"Saved consensus graph to {consensus_file}")
+    
+    if args.agent_conflict_map:
+        conflict_map = portfolio_manager.visualize_agent_conflict_map()
+        conflict_file = os.path.join(args.output_dir, f"conflict_map_{start_date}_{end_date}.json")
+        
+        with open(conflict_file, 'w') as f:
+            json.dump(conflict_map, f, indent=2, default=str)
+        
+        logger.info(f"Saved agent conflict map to {conflict_file}")
+    
+    if args.attribution_report:
+        # Get all signals from the simulation
+        all_signals = []
+        for trade_batch in results.get("trades", []):
+            for trade in trade_batch:
+                if "signal" in trade:
+                    all_signals.append(trade["signal"])
+        
+        # Create attribution report
+        tracer = TracingTools(agent_id="portfolio", agent_name="Portfolio")
+        attribution_report = tracer.generate_attribution_report(all_signals)
+        report_file = os.path.join(args.output_dir, f"attribution_report_{start_date}_{end_date}.json")
+        
+        with open(report_file, 'w') as f:
+            json.dump(attribution_report, f, indent=2, default=str)
+        
+        logger.info(f"Saved attribution report to {report_file}")
+    
+    # Save final portfolio state
+    portfolio_state = portfolio_manager.get_portfolio_state()
+    portfolio_file = os.path.join(args.output_dir, f"portfolio_state_{end_date}.json")
+    
+    with open(portfolio_file, 'w') as f:
+        json.dump(portfolio_state, f, indent=2, default=str)
+    
+    logger.info(f"Saved portfolio state to {portfolio_file}")
+    
+    return results
+
+
+def run_live_analysis(portfolio_manager: PortfolioManager, market_env: MarketEnvironment, args) -> Dict[str, Any]:
+    """
+    Run live market analysis.
+    
+    Args:
+        portfolio_manager: Portfolio manager instance
+        market_env: Market environment instance
+        args: Command-line arguments
+        
+    Returns:
+        Analysis results
+    """
+    # Get current market data
+    market_data = market_env.get_current_market_data()
+    
+    # Process market data through portfolio manager
+    analysis_results = portfolio_manager.process_market_data(market_data)
+    
+    logger.info(f"Completed live market analysis for {len(args.tickers)} tickers")
+    
+    # Save results
+    os.makedirs(args.output_dir, exist_ok=True)
+    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    results_file = os.path.join(args.output_dir, f"live_analysis_{timestamp}.json")
+    
+    with open(results_file, 'w') as f:
+        json.dump(analysis_results, f, indent=2, default=str)
+    
+    logger.info(f"Saved live analysis results to {results_file}")
+    
+    # Generate visualizations if requested
+    if args.consensus_graph:
+        consensus_graph = portfolio_manager.visualize_consensus_graph()
+        consensus_file = os.path.join(args.output_dir, f"consensus_graph_{timestamp}.json")
+        
+        with open(consensus_file, 'w') as f:
+            json.dump(consensus_graph, f, indent=2, default=str)
+        
+        logger.info(f"Saved consensus graph to {consensus_file}")
+    
+    if args.agent_conflict_map:
+        conflict_map = portfolio_manager.visualize_agent_conflict_map()
+        conflict_file = os.path.join(args.output_dir, f"conflict_map_{timestamp}.json")
+        
+        with open(conflict_file, 'w') as f:
+            json.dump(conflict_map, f, indent=2, default=str)
+        
+        logger.info(f"Saved agent conflict map to {conflict_file}")
+    
+    # Execute trades if there are consensus decisions
+    consensus_decisions = analysis_results.get("meta_agent", {}).get("consensus_decisions", [])
+    
+    if consensus_decisions:
+        trade_results = portfolio_manager.execute_trades(consensus_decisions)
+        
+        # Save trade results
+        trades_file = os.path.join(args.output_dir, f"trades_{timestamp}.json")
+        
+        with open(trades_file, 'w') as f:
+            json.dump(trade_results, f, indent=2, default=str)
+        
+        logger.info(f"Executed {len(trade_results.get('trades', []))} trades and saved results to {trades_file}")
+    
+    # Save portfolio state
+    portfolio_state = portfolio_manager.get_portfolio_state()
+    portfolio_file = os.path.join(args.output_dir, f"portfolio_state_{timestamp}.json")
+    
+    with open(portfolio_file, 'w') as f:
+        json.dump(portfolio_state, f, indent=2, default=str)
+    
+    logger.info(f"Saved portfolio state to {portfolio_file}")
+    
+    return analysis_results
+
+
+def run_portfolio_analysis(args) -> Dict[str, Any]:
+    """
+    Run analysis on existing portfolio.
+    
+    Args:
+        args: Command-line arguments
+        
+    Returns:
+        Analysis results
+    """
+    # Check if portfolio file exists
+    if not args.portfolio_file or not os.path.exists(args.portfolio_file):
+        logger.error(f"Portfolio file not found: {args.portfolio_file}")
+        sys.exit(1)
+    
+    # Load portfolio state
+    with open(args.portfolio_file, 'r') as f:
+        portfolio_state = json.load(f)
+    
+    # Create agents
+    agents = create_agents(args)
+    
+    # Create portfolio manager
+    portfolio_manager = create_portfolio_manager(agents, args)
+    
+    # Create market environment
+    market_env = create_market_environment(args)
+    
+    # Get current market data
+    market_data = market_env.get_current_market_data()
+    
+    # Process market data through portfolio manager
+    analysis_results = portfolio_manager.process_market_data(market_data)
+    
+    logger.info(f"Completed portfolio analysis")
+    
+    # Save results
+    os.makedirs(args.output_dir, exist_ok=True)
+    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    results_file = os.path.join(args.output_dir, f"portfolio_analysis_{timestamp}.json")
+    
+    with open(results_file, 'w') as f:
+        json.dump(analysis_results, f, indent=2, default=str)
+    
+    logger.info(f"Saved portfolio analysis results to {results_file}")
+    
+    # Generate visualizations if requested
+    if args.consensus_graph:
+        consensus_graph = portfolio_manager.visualize_consensus_graph()
+        consensus_file = os.path.join(args.output_dir, f"consensus_graph_{timestamp}.json")
+        
+        with open(consensus_file, 'w') as f:
+            json.dump(consensus_graph, f, indent=2, default=str)
+        
+        logger.info(f"Saved consensus graph to {consensus_file}")
+    
+    if args.agent_conflict_map:
+        conflict_map = portfolio_manager.visualize_agent_conflict_map()
+        conflict_file = os.path.join(args.output_dir, f"conflict_map_{timestamp}.json")
+        
+        with open(conflict_file, 'w') as f:
+            json.dump(conflict_map, f, indent=2, default=str)
+        
+        logger.info(f"Saved agent conflict map to {conflict_file}")
+    
+    if args.attribution_report:
+        # Get agent performance
+        agent_performance = portfolio_manager.get_agent_performance()
+        
+        # Create attribution report
+        attribution_file = os.path.join(args.output_dir, f"agent_performance_{timestamp}.json")
+        
+        with open(attribution_file, 'w') as f:
+            json.dump(agent_performance, f, indent=2, default=str)
+        
+        logger.info(f"Saved agent performance report to {attribution_file}")
+    
+    if args.shell_failure_map:
+        # Create shell diagnostics
+        shell_diagnostics = ShellDiagnostics(
+            agent_id="portfolio",
+            agent_name="Portfolio",
+            tracing_tools=TracingTools(
+                agent_id="portfolio",
+                agent_name="Portfolio",
+                tracing_mode=TracingMode(args.trace_level),
+            )
+        )
+        
+        # Create shell failure map
+        failure_map = ShellFailureMap()
+        
+        # Analyze each agent's state for shell failures
+        for agent in agents:
+            agent_state = agent.get_state_report()
+            
+            # Simulate shell failures based on agent state
+            for shell_pattern in [
+                "NULL_FEATURE", 
+                "CIRCUIT_FRAGMENT", 
+                "META_FAILURE",
+                "RECURSIVE_FRACTURE",
+                "ETHICAL_INVERSION",
+            ]:
+                try:
+                    from utils.diagnostics import ShellPattern
+                    pattern = getattr(ShellPattern, shell_pattern)
+                    
+                    # Simulate failure
+                    failure_data = shell_diagnostics.simulate_shell_failure(
+                        shell_pattern=pattern,
+                        context=agent_state,
+                    )
+                    
+                    # Add to failure map
+                    failure_map.add_failure(
+                        agent_id=agent.id,
+                        agent_name=agent.name,
+                        shell_pattern=pattern,
+                        failure_data=failure_data,
+                    )
+                except Exception as e:
+                    logger.error(f"Error simulating shell failure: {e}")
+        
+        # Generate visualization
+        failure_viz = failure_map.generate_failure_map_visualization()
+        failure_file = os.path.join(args.output_dir, f"shell_failure_map_{timestamp}.json")
+        
+        with open(failure_file, 'w') as f:
+            json.dump(failure_viz, f, indent=2, default=str)
+        
+        logger.info(f"Saved shell failure map to {failure_file}")
+    
+    return analysis_results
+
+
+def main():
+    """Main entry point."""
+    # Parse arguments
+    args = parse_args()
+    
+    # Create output directory
+    os.makedirs(args.output_dir, exist_ok=True)
+    
+    # Run in appropriate mode
+    if args.mode == "backtest":
+        # Create agents
+        agents = create_agents(args)
+        
+        # Create portfolio manager
+        portfolio_manager = create_portfolio_manager(agents, args)
+        
+        # Create market environment
+        market_env = create_market_environment(args)
+        
+        # Run backtest
+        results = run_backtest(portfolio_manager, market_env, args)
+        
+        # Print summary
+        print("\n=== Backtest Results ===")
+        print(f"Start Date: {args.start_date}")
+        print(f"End Date: {args.end_date}")
+        print(f"Initial Capital: ${args.initial_capital:.2f}")
+        print(f"Final Portfolio Value: ${results.get('final_value', 0):.2f}")
+        
+        total_return = (results.get('final_value', 0) / args.initial_capital) - 1
+        print(f"Total Return: {total_return:.2%}")
+        print(f"Number of Trades: {sum(len(batch) for batch in results.get('trades', []))}")
+        print(f"Results saved to: {args.output_dir}")
+    
+    elif args.mode == "live":
+        # Create agents
+        agents = create_agents(args)
+        
+        # Create portfolio manager
+        portfolio_manager = create_portfolio_manager(agents, args)
+        
+        # Create market environment
+        market_env = create_market_environment(args)
+        
+        # Run live analysis
+        results = run_live_analysis(portfolio_manager, market_env, args)
+        
+        # Print summary
+        print("\n=== Live Analysis Results ===")
+        print(f"Analysis Time: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+        print(f"Tickers Analyzed: {', '.join(args.tickers)}")
+        
+        # Print consensus decisions
+        consensus_decisions = results.get("meta_agent", {}).get("consensus_decisions", [])
+        if consensus_decisions:
+            print("\nConsensus Decisions:")
+            for decision in consensus_decisions:
+                ticker = decision.get("ticker", "")
+                action = decision.get("action", "")
+                confidence = decision.get("confidence", 0)
+                quantity = decision.get("quantity", 0)
+                
+                print(f"  {action.upper()} {quantity} {ticker} (Confidence: {confidence:.2f})")
+        else:
+            print("\nNo consensus decisions generated.")
+        
+        print(f"Results saved to: {args.output_dir}")
+    
+    elif args.mode == "analysis":
+        # Run portfolio analysis
+        results = run_portfolio_analysis(args)
+        
+        # Print summary
+        print("\n=== Portfolio Analysis Results ===")
+        print(f"Analysis Time: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+        print(f"Portfolio File: {args.portfolio_file}")
+        
+        # Print agent weights
+        agent_weights = results.get("meta_agent", {}).get("agent_weights", {})
+        if agent_weights:
+            print("\nAgent Weights:")
+            for agent_id, weight in agent_weights.items():
+                print(f"  {agent_id}: {weight:.2f}")
+        
+        # Print consensus decisions
+        consensus_decisions = results.get("meta_agent", {}).get("consensus_decisions", [])
+        if consensus_decisions:
+            print("\nRecommended Actions:")
+            for decision in consensus_decisions:
+                ticker = decision.get("ticker", "")
+                action = decision.get("action", "")
+                confidence = decision.get("confidence", 0)
+                quantity = decision.get("quantity", 0)
+                
+                print(f"  {action.upper()} {quantity} {ticker} (Confidence: {confidence:.2f})")
+        else:
+            print("\nNo recommended actions.")
+        
+        print(f"Results saved to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

src/portfolio/manager.py

@@ -0,0 +1,1940 @@
+"""
+PortfolioManager - Recursive Meta-Agent Arbitration Framework
+
+This module implements the portfolio meta-agent that recursively arbitrates between
+different philosophical investment agents and manages the overall portfolio allocation.
+
+Key capabilities:
+- Multi-agent arbitration with philosophical weighting
+- Attribution-weighted position sizing
+- Recursive consensus formation across agents
+- Transparent decision tracing with interpretability scaffolding
+- Conflict resolution through value attribution
+- Memory-based temporal reasoning across market cycles
+
+Internal Note: The portfolio manager implements the meta-agent arbitration layer
+using recursive attribution traces and symbolic consensus formation shells.
+"""
+
+import datetime
+import uuid
+import logging
+import math
+import json
+from typing import Dict, List, Any, Optional, Tuple, Set, Union
+import numpy as np
+from collections import defaultdict
+
+# Core agent functionality
+from ..agents.base import BaseAgent, AgentSignal
+from ..cognition.graph import ReasoningGraph
+from ..cognition.memory import MemoryShell
+from ..cognition.attribution import AttributionTracer
+from ..utils.diagnostics import TracingTools
+
+# Type hints
+from pydantic import BaseModel, Field
+
+
+class Position(BaseModel):
+    """Current portfolio position with attribution."""
+    
+    ticker: str = Field(...)
+    quantity: int = Field(...)
+    entry_price: float = Field(...)
+    current_price: float = Field(...)
+    entry_date: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    attribution: Dict[str, float] = Field(default_factory=dict)  # Agent contributions
+    confidence: float = Field(default=0.5)
+    reasoning: str = Field(default="")
+    value_basis: str = Field(default="")
+    last_update: datetime.datetime = Field(default_factory=datetime.datetime.now)
+
+
+class Portfolio(BaseModel):
+    """Portfolio state with positions and performance metrics."""
+    
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    positions: Dict[str, Position] = Field(default_factory=dict)
+    cash: float = Field(...)
+    initial_capital: float = Field(...)
+    last_update: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    performance_history: List[Dict[str, Any]] = Field(default_factory=list)
+    
+    def get_value(self, price_data: Dict[str, float]) -> float:
+        """Calculate total portfolio value including cash."""
+        total_value = self.cash
+        
+        for ticker, position in self.positions.items():
+            # Get current price if available, otherwise use stored price
+            current_price = price_data.get(ticker, position.current_price)
+            position_value = position.quantity * current_price
+            total_value += position_value
+        
+        return total_value
+    
+    def get_returns(self) -> Dict[str, float]:
+        """Calculate portfolio returns."""
+        if not self.performance_history:
+            return {
+                "total_return": 0.0,
+                "annualized_return": 0.0,
+                "volatility": 0.0,
+                "sharpe_ratio": 0.0,
+            }
+        
+        # Extract portfolio values
+        values = [entry["portfolio_value"] for entry in self.performance_history]
+        
+        # Calculate returns
+        if len(values) < 2:
+            return {
+                "total_return": 0.0,
+                "annualized_return": 0.0,
+                "volatility": 0.0,
+                "sharpe_ratio": 0.0,
+            }
+        
+        # Calculate total return
+        total_return = (values[-1] / values[0]) - 1
+        
+        # Calculate daily returns
+        daily_returns = []
+        for i in range(1, len(values)):
+            daily_return = (values[i] / values[i-1]) - 1
+            daily_returns.append(daily_return)
+        
+        # Calculate annualized return (assuming daily values)
+        days = len(values) - 1
+        annualized_return = ((1 + total_return) ** (365 / days)) - 1
+        
+        # Calculate volatility (annualized standard deviation of returns)
+        if daily_returns:
+            daily_volatility = np.std(daily_returns)
+            annualized_volatility = daily_volatility * (252 ** 0.5)  # Assuming 252 trading days
+        else:
+            annualized_volatility = 0.0
+        
+        # Calculate Sharpe ratio (assuming risk-free rate of 0 for simplicity)
+        sharpe_ratio = annualized_return / annualized_volatility if annualized_volatility > 0 else 0.0
+        
+        return {
+            "total_return": total_return,
+            "annualized_return": annualized_return,
+            "volatility": annualized_volatility,
+            "sharpe_ratio": sharpe_ratio,
+        }
+    
+    def get_allocation(self) -> Dict[str, float]:
+        """Get current portfolio allocation percentages."""
+        total_value = self.cash
+        for ticker, position in self.positions.items():
+            total_value += position.quantity * position.current_price
+        
+        if total_value <= 0:
+            return {"cash": 1.0}
+        
+        # Calculate allocations
+        allocations = {"cash": self.cash / total_value}
+        
+        for ticker, position in self.positions.items():
+            position_value = position.quantity * position.current_price
+            allocations[ticker] = position_value / total_value
+        
+        return allocations
+    
+    def update_prices(self, price_data: Dict[str, float]) -> None:
+        """Update position prices with latest market data."""
+        for ticker, position in self.positions.items():
+            if ticker in price_data:
+                position.current_price = price_data[ticker]
+                position.last_update = datetime.datetime.now()
+        
+        self.last_update = datetime.datetime.now()
+    
+    def record_performance(self, price_data: Dict[str, float]) -> Dict[str, Any]:
+        """Record current performance snapshot."""
+        # Calculate portfolio value
+        portfolio_value = self.get_value(price_data)
+        
+        # Calculate returns
+        returns = {
+            "daily_return": 0.0,
+            "total_return": (portfolio_value / self.initial_capital) - 1,
+        }
+        
+        # Calculate daily return if we have past data
+        if self.performance_history:
+            last_value = self.performance_history[-1]["portfolio_value"]
+            returns["daily_return"] = (portfolio_value / last_value) - 1
+        
+        # Create snapshot
+        snapshot = {
+            "timestamp": datetime.datetime.now(),
+            "portfolio_value": portfolio_value,
+            "cash": self.cash,
+            "positions": {ticker: pos.dict() for ticker, pos in self.positions.items()},
+            "returns": returns,
+            "allocation": self.get_allocation(),
+        }
+        
+        # Add to history
+        self.performance_history.append(snapshot)
+        
+        return snapshot
+
+
+class PortfolioManager:
+    """
+    Portfolio Meta-Agent for investment arbitration and management.
+    
+    The PortfolioManager serves as a recursive meta-agent that:
+    - Arbitrates between different philosophical agents
+    - Forms consensus through attribution-weighted aggregation
+    - Manages portfolio allocation and position sizing
+    - Provides transparent decision tracing
+    - Maintains temporal memory across market cycles
+    """
+    
+    def __init__(
+        self,
+        agents: List[BaseAgent],
+        initial_capital: float = 100000.0,
+        arbitration_depth: int = 2,
+        max_position_size: float = 0.2,  # 20% max allocation to single position
+        min_position_size: float = 0.01,  # 1% min allocation to single position
+        consensus_threshold: float = 0.6,  # Minimum confidence for consensus
+        show_trace: bool = False,
+        risk_budget: float = 0.5,  # Risk budget (0-1)
+    ):
+        """
+        Initialize portfolio manager.
+        
+        Args:
+            agents: List of investment agents
+            initial_capital: Starting capital amount
+            arbitration_depth: Depth of arbitration reasoning
+            max_position_size: Maximum position size as fraction of portfolio
+            min_position_size: Minimum position size as fraction of portfolio
+            consensus_threshold: Minimum confidence for consensus
+            show_trace: Whether to show reasoning traces
+            risk_budget: Risk budget (0-1)
+        """
+        self.id = str(uuid.uuid4())
+        self.agents = agents
+        self.arbitration_depth = arbitration_depth
+        self.max_position_size = max_position_size
+        self.min_position_size = min_position_size
+        self.consensus_threshold = consensus_threshold
+        self.show_trace = show_trace
+        self.risk_budget = risk_budget
+        
+        # Initialize portfolio
+        self.portfolio = Portfolio(
+            cash=initial_capital,
+            initial_capital=initial_capital,
+        )
+        
+        # Initialize cognitive components
+        self.memory_shell = MemoryShell(decay_rate=0.1)  # Slower decay for meta-agent
+        self.attribution_tracer = AttributionTracer()
+        
+        # Initialize reasoning graph
+        self.reasoning_graph = ReasoningGraph(
+            agent_name="PortfolioMetaAgent",
+            agent_philosophy="Recursive arbitration across philosophical perspectives",
+            model_router=agents[0].llm if agents else None,  # Use first agent's model router
+            trace_enabled=show_trace,
+        )
+        
+        # Configure meta-agent reasoning graph
+        self._configure_reasoning_graph()
+        
+        # Diagnostics
+        self.tracer = TracingTools(agent_id=self.id, agent_name="PortfolioMetaAgent")
+        
+        # Agent weight tracking
+        self.agent_weights = {agent.id: 1.0 / len(agents) for agent in agents} if agents else {}
+        
+        # Initialize meta-agent state
+        self.meta_state = {
+            "agent_consensus": {},
+            "agent_performance": {},
+            "conflict_history": [],
+            "arbitration_history": [],
+            "risk_budget_used": 0.0,
+            "last_rebalance": datetime.datetime.now(),
+            "consistency_metrics": {},
+        }
+        
+        # Internal symbolic processing commands
+        self._commands = {
+            "reflect.trace": self._reflect_trace,
+            "fork.signal": self._fork_signal,
+            "collapse.detect": self._collapse_detect,
+            "attribute.weight": self._attribute_weight,
+            "drift.observe": self._drift_observe,
+        }
+    
+    def _configure_reasoning_graph(self) -> None:
+        """Configure the meta-agent reasoning graph."""
+        # Configure nodes for meta-agent reasoning
+        self.reasoning_graph.add_node(
+            "generate_agent_signals",
+            self._generate_agent_signals
+        )
+        
+        self.reasoning_graph.add_node(
+            "consensus_formation",
+            self._consensus_formation
+        )
+        
+        self.reasoning_graph.add_node(
+            "conflict_resolution",
+            self._conflict_resolution
+        )
+        
+        self.reasoning_graph.add_node(
+            "position_sizing",
+            self._position_sizing
+        )
+        
+        self.reasoning_graph.add_node(
+            "meta_reflection",
+            self._meta_reflection
+        )
+        
+        # Configure graph structure
+        self.reasoning_graph.set_entry_point("generate_agent_signals")
+        self.reasoning_graph.add_edge("generate_agent_signals", "consensus_formation")
+        self.reasoning_graph.add_edge("consensus_formation", "conflict_resolution")
+        self.reasoning_graph.add_edge("conflict_resolution", "position_sizing")
+        self.reasoning_graph.add_edge("position_sizing", "meta_reflection")
+    
+    def process_market_data(self, market_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process market data through all agents and form meta-agent consensus.
+        
+        Args:
+            market_data: Market data dictionary
+            
+        Returns:
+            Processed market data with meta-agent insights
+        """
+        # Update portfolio prices
+        if "tickers" in market_data:
+            price_data = {ticker: data.get("price", 0) 
+                        for ticker, data in market_data.get("tickers", {}).items()}
+            self.portfolio.update_prices(price_data)
+        
+        # Process market data through each agent
+        agent_analyses = {}
+        for agent in self.agents:
+            try:
+                agent_analysis = agent.process_market_data(market_data)
+                agent_analyses[agent.id] = {
+                    "agent": agent.name,
+                    "analysis": agent_analysis,
+                    "philosophy": agent.philosophy,
+                }
+            except Exception as e:
+                logging.error(f"Error processing market data with agent {agent.name}: {e}")
+        
+        # Generate agent signals
+        agent_signals = {}
+        for agent in self.agents:
+            try:
+                agent_processed_data = agent_analyses.get(agent.id, {}).get("analysis", {})
+                signals = agent.generate_signals(agent_processed_data)
+                agent_signals[agent.id] = {
+                    "agent": agent.name,
+                    "signals": signals,
+                    "confidence": np.mean([s.confidence for s in signals]) if signals else 0.5,
+                }
+            except Exception as e:
+                logging.error(f"Error generating signals with agent {agent.name}: {e}")
+        
+        # Prepare reasoning input
+        reasoning_input = {
+            "market_data": market_data,
+            "agent_analyses": agent_analyses,
+            "agent_signals": agent_signals,
+            "portfolio": self.portfolio.dict(),
+            "agent_weights": self.agent_weights,
+            "meta_state": self.meta_state,
+        }
+        
+        # Run meta-agent reasoning
+        meta_result = self.reasoning_graph.run(
+            input=reasoning_input,
+            trace_depth=self.arbitration_depth
+        )
+        
+        # Extract consensus decisions
+        consensus_decisions = meta_result.get("output", {}).get("consensus_decisions", [])
+        
+        # Add to memory
+        self.memory_shell.add_experience({
+            "type": "market_analysis",
+            "market_data": market_data,
+            "meta_result": meta_result,
+            "timestamp": datetime.datetime.now().isoformat(),
+        })
+        
+        # Create processed data result
+        processed_data = {
+            "timestamp": datetime.datetime.now(),
+            "meta_agent": {
+                "consensus_decisions": consensus_decisions,
+                "confidence": meta_result.get("confidence", 0.5),
+                "agent_weights": self.agent_weights.copy(),
+            },
+            "agents": {agent.name: agent_analyses.get(agent.id, {}).get("analysis", {}) 
+                     for agent in self.agents},
+            "portfolio_value": self.portfolio.get_value(price_data),
+            "allocation": self.portfolio.get_allocation(),
+        }
+        
+        # Add trace if enabled
+        if self.show_trace and "trace" in meta_result:
+            processed_data["trace"] = meta_result["trace"]
+        
+        return processed_data
+    
+    def execute_trades(self, decisions: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Execute trade decisions and update portfolio.
+        
+        Args:
+            decisions: List of trade decisions
+            
+        Returns:
+            Trade execution results
+        """
+        execution_results = {
+            "trades": [],
+            "errors": [],
+            "portfolio_update": {},
+            "timestamp": datetime.datetime.now(),
+        }
+        
+        # Get current prices (use stored prices if not available)
+        price_data = {ticker: position.current_price 
+                    for ticker, position in self.portfolio.positions.items()}
+        
+        # Execute each decision
+        for decision in decisions:
+            ticker = decision.get("ticker", "")
+            action = decision.get("action", "")
+            quantity = decision.get("quantity", 0)
+            confidence = decision.get("confidence", 0.5)
+            reasoning = decision.get("reasoning", "")
+            attribution = decision.get("attribution", {})
+            value_basis = decision.get("value_basis", "")
+            
+            # Skip invalid decisions
+            if not ticker or not action or quantity <= 0:
+                execution_results["errors"].append({
+                    "ticker": ticker,
+                    "error": "Invalid decision parameters",
+                    "decision": decision,
+                })
+                continue
+            
+            # Get current price
+            current_price = price_data.get(ticker, 0)
+            
+            # Fetch from market if not available
+            if current_price <= 0:
+                # In a real implementation, this would fetch from market
+                # For now, use placeholder
+                current_price = 100.0
+                price_data[ticker] = current_price
+            
+            try:
+                if action == "buy":
+                    # Check if we have enough cash
+                    cost = quantity * current_price
+                    if cost > self.portfolio.cash:
+                        max_quantity = math.floor(self.portfolio.cash / current_price)
+                        if max_quantity <= 0:
+                            execution_results["errors"].append({
+                                "ticker": ticker,
+                                "error": "Insufficient cash for purchase",
+                                "attempted_quantity": quantity,
+                                "available_cash": self.portfolio.cash,
+                            })
+                            continue
+                        
+                        # Adjust quantity
+                        quantity = max_quantity
+                        cost = quantity * current_price
+                    
+                    # Execute buy
+                    if ticker in self.portfolio.positions:
+                        # Update existing position
+                        position = self.portfolio.positions[ticker]
+                        new_quantity = position.quantity + quantity
+                        new_cost = (position.quantity * position.entry_price) + cost
+                        
+                        # Calculate new average entry price
+                        new_entry_price = new_cost / new_quantity if new_quantity > 0 else current_price
+                        
+                        # Update position
+                        position.quantity = new_quantity
+                        position.entry_price = new_entry_price
+                        position.current_price = current_price
+                        position.last_update = datetime.datetime.now()
+                        
+                        # Update attribution (weighted by quantity)
+                        old_weight = position.quantity / new_quantity
+                        new_weight = quantity / new_quantity
+                        
+                        for agent_id, weight in attribution.items():
+                            position.attribution[agent_id] = (
+                                (position.attribution.get(agent_id, 0) * old_weight) +
+                                (weight * new_weight)
+                            )
+                        
+                        # Update other fields
+                        position.confidence = (position.confidence * old_weight) + (confidence * new_weight)
+                        position.reasoning += f"\nAdditional purchase: {reasoning}"
+                        position.value_basis = value_basis if value_basis else position.value_basis
+                    else:
+                        # Create new position
+                        self.portfolio.positions[ticker] = Position(
+                            ticker=ticker,
+                            quantity=quantity,
+                            entry_price=current_price,
+                            current_price=current_price,
+                            attribution=attribution,
+                            confidence=confidence,
+                            reasoning=reasoning,
+                            value_basis=value_basis,
+                        )
+                    
+                    # Update cash
+                    self.portfolio.cash -= cost
+                    
+                    # Record trade
+                    execution_results["trades"].append({
+                        "ticker": ticker,
+                        "action": "buy",
+                        "quantity": quantity,
+                        "price": current_price,
+                        "cost": cost,
+                        "timestamp": datetime.datetime.now(),
+                    })
+                
+                elif action == "sell":
+                    # Check if we have the position
+                    if ticker not in self.portfolio.positions:
+                        execution_results["errors"].append({
+                            "ticker": ticker,
+                            "error": "Position not found",
+                            "attempted_action": "sell",
+                        })
+                        continue
+                    
+                    position = self.portfolio.positions[ticker]
+                    
+                    # Check if we have enough shares
+                    if quantity > position.quantity:
+                        quantity = position.quantity
+                    
+                    # Calculate proceeds
+                    proceeds = quantity * current_price
+                    
+                    # Execute sell
+                    if quantity == position.quantity:
+                        # Sell entire position
+                        del self.portfolio.positions[ticker]
+                    else:
+                        # Partial sell
+                        position.quantity -= quantity
+                        position.last_update = datetime.datetime.now()
+                    
+                    # Update cash
+                    self.portfolio.cash += proceeds
+                    
+                    # Record trade
+                    execution_results["trades"].append({
+                        "ticker": ticker,
+                        "action": "sell",
+                        "quantity": quantity,
+                        "price": current_price,
+                        "proceeds": proceeds,
+                        "timestamp": datetime.datetime.now(),
+                    })
+            
+            except Exception as e:
+                execution_results["errors"].append({
+                    "ticker": ticker,
+                    "error": str(e),
+                    "decision": decision,
+                })
+        
+        # Update portfolio timestamps
+        self.portfolio.last_update = datetime.datetime.now()
+        
+        # Record performance
+        performance_snapshot = self.portfolio.record_performance(price_data)
+        execution_results["portfolio_update"] = performance_snapshot
+        
+        # Update agent states based on trades
+        self._update_agent_states(execution_results)
+        
+        return execution_results
+    
+    def _update_agent_states(self, execution_results: Dict[str, Any]) -> None:
+        """
+        Update agent states based on trade results.
+        
+        Args:
+            execution_results: Trade execution results
+        """
+        # Create feedback for each agent
+        for agent in self.agents:
+            # Extract agent-specific trades
+            agent_trades = []
+            for trade in execution_results.get("trades", []):
+                ticker = trade.get("ticker", "")
+                
+                if ticker in self.portfolio.positions:
+                    position = self.portfolio.positions[ticker]
+                    agent_attribution = position.attribution.get(agent.id, 0)
+                    
+                    if agent_attribution > 0:
+                        agent_trades.append({
+                            **trade,
+                            "attribution": agent_attribution,
+                        })
+            
+            # Create market feedback
+            market_feedback = {
+                "trades": agent_trades,
+                "portfolio_value": execution_results.get("portfolio_update", {}).get("portfolio_value", 0),
+                "timestamp": datetime.datetime.now(),
+            }
+            
+            # Add performance metrics if available
+            if "performance" in execution_results.get("portfolio_update", {}):
+                market_feedback["performance"] = execution_results["portfolio_update"]["performance"]
+            
+            # Update agent state
+            try:
+                agent.update_state(market_feedback)
+            except Exception as e:
+                logging.error(f"Error updating state for agent {agent.name}: {e}")
+    
+    def rebalance_portfolio(self, target_allocation: Dict[str, float]) -> Dict[str, Any]:
+        """
+        Rebalance portfolio to match target allocation.
+        
+        Args:
+            target_allocation: Target allocation as fraction of portfolio
+            
+        Returns:
+            Rebalance results
+        """
+        rebalance_results = {
+            "trades": [],
+            "errors": [],
+            "initial_allocation": self.portfolio.get_allocation(),
+            "target_allocation": target_allocation,
+            "timestamp": datetime.datetime.now(),
+        }
+        
+        # Validate target allocation
+        total_allocation = sum(target_allocation.values())
+        if abs(total_allocation - 1.0) > 0.01:  # Allow small rounding errors
+            rebalance_results["errors"].append({
+                "error": "Invalid target allocation, must sum to 1.0",
+                "total": total_allocation,
+            })
+            return rebalance_results
+        
+        # Get current portfolio value and allocation
+        current_value = self.portfolio.get_value({
+            ticker: pos.current_price for ticker, pos in self.portfolio.positions.items()
+        })
+        current_allocation = self.portfolio.get_allocation()
+        
+        # Calculate trades needed
+        trade_decisions = []
+        
+        # Process sells first (to free up cash)
+        for ticker, position in list(self.portfolio.positions.items()):
+            current_ticker_allocation = current_allocation.get(ticker, 0)
+            target_ticker_allocation = target_allocation.get(ticker, 0)
+            
+            # Check if we need to sell
+            if current_ticker_allocation > target_ticker_allocation:
+                # Calculate how much to sell
+                current_position_value = position.quantity * position.current_price
+                target_position_value = current_value * target_ticker_allocation
+                value_to_sell = current_position_value - target_position_value
+                
+                # Convert to quantity
+                quantity_to_sell = math.floor(value_to_sell / position.current_price)
+                
+                if quantity_to_sell > 0:
+                    # Create sell decision
+                    trade_decisions.append({
+                        "ticker": ticker,
+                        "action": "sell",
+                        "quantity": min(quantity_to_sell, position.quantity),  # Ensure we don't sell more than we have
+                        "confidence": 0.8,  # High confidence for rebalancing
+                        "reasoning": f"Portfolio rebalancing to target allocation of {target_ticker_allocation:.1%}",
+                        "attribution": position.attribution,  # Maintain attribution
+                        "value_basis": "Portfolio efficiency and risk management",
+                    })
+        
+        # Execute sells
+        sell_results = self.execute_trades([d for d in trade_decisions if d["action"] == "sell"])
+        rebalance_results["trades"].extend(sell_results.get("trades", []))
+        rebalance_results["errors"].extend(sell_results.get("errors", []))
+        
+        # Update cash value after sells
+        current_value = self.portfolio.get_value({
+            ticker: pos.current_price for ticker, pos in self.portfolio.positions.items()
+        })
+        
+        # Process buys
+        buy_decisions = []
+        for ticker, target_alloc in target_allocation.items():
+            # Skip cash
+            if ticker == "cash":
+                continue
+            
+            current_ticker_allocation = 0
+            if ticker in self.portfolio.positions:
+                position = self.portfolio.positions[ticker]
+                current_ticker_allocation = (position.quantity * position.current_price) / current_value
+            
+            # Check if we need to buy
+            if current_ticker_allocation < target_alloc:
+                # Calculate how much to buy
+                target_position_value = current_value * target_alloc
+                current_position_value = 0
+                if ticker in self.portfolio.positions:
+                    position = self.portfolio.positions[ticker]
+                    current_position_value = position.quantity * position.current_price
+                
+                value_to_buy = target_position_value - current_position_value
+                
+                # Check if we have enough cash
+                if value_to_buy > self.portfolio.cash:
+                    value_to_buy = self.portfolio.cash  # Limit to available cash
+                
+                # Get current price
+                current_price = 0
+                if ticker in self.portfolio.positions:
+                    current_price = self.portfolio.positions[ticker].current_price
+                else:
+                    # This would fetch from market in a real implementation
+                    # For now, use placeholder
+                    current_price = 100.0
+                
+                # Convert to quantity
+                quantity_to_buy = math.floor(value_to_buy / current_price)
+                
+                if quantity_to_buy > 0:
+                    # Determine attribution based on existing position or equal weights
+                    attribution = {}
+                    if ticker in self.portfolio.positions:
+                        attribution = self.portfolio.positions[ticker].attribution
+                    else:
+                        # Equal attribution to all agents
+                        for agent in self.agents:
+                            attribution[agent.id] = 1.0 / len(self.agents)
+                    
+                    # Create buy decision
+                    buy_decisions.append({
+                        "ticker": ticker,
+                        "action": "buy",
+                        "quantity": quantity_to_buy,
+                        "confidence": 0.8,  # High confidence for rebalancing
+                        "reasoning": f"Portfolio rebalancing to target allocation of {target_alloc:.1%}",
+                        "attribution": attribution,
+                        "value_basis": "Portfolio efficiency and risk management",
+                    })
+        
+        # Execute buys
+        buy_results = self.execute_trades(buy_decisions)
+        rebalance_results["trades"].extend(buy_results.get("trades", []))
+        rebalance_results["errors"].extend(buy_results.get("errors", []))
+        
+        # Record final allocation
+        rebalance_results["final_allocation"] = self.portfolio.get_allocation()
+        
+        # Update last rebalance timestamp
+        self.meta_state["last_rebalance"] = datetime.datetime.now()
+        
+        return rebalance_results
+    
+    def run_simulation(self, start_date: str, end_date: str, 
+                     data_source: str = "yahoo", rebalance_frequency: str = "monthly") -> Dict[str, Any]:
+        """
+        Run portfolio simulation over a time period.
+        
+        Args:
+            start_date: Start date (YYYY-MM-DD)
+            end_date: End date (YYYY-MM-DD)
+            data_source: Market data source
+            rebalance_frequency: Rebalance frequency
+            
+        Returns:
+            Simulation results
+        """
+        # This is a placeholder implementation
+        # A real implementation would fetch historical data and simulate day by day
+        
+        simulation_results = {
+            "start_date": start_date,
+            "end_date": end_date,
+            "data_source": data_source,
+            "rebalance_frequency": rebalance_frequency,
+            "initial_capital": self.portfolio.initial_capital,
+            "final_value": self.portfolio.initial_capital,  # Placeholder
+            "trades": [],
+            "performance": [],
+            "timestamp": datetime.datetime.now(),
+        }
+        
+        # In a real implementation, this would fetch historical data
+        # and simulate trading day by day
+        
+        return simulation_results
+    
+    def get_portfolio_state(self) -> Dict[str, Any]:
+        """
+        Get current portfolio state.
+        
+        Returns:
+            Portfolio state
+        """
+        # Get current prices
+        price_data = {ticker: position.current_price 
+                    for ticker, position in self.portfolio.positions.items()}
+        
+        # Calculate portfolio value
+        portfolio_value = self.portfolio.get_value(price_data)
+        
+        # Calculate returns
+        returns = self.portfolio.get_returns()
+        
+        # Calculate allocation
+        allocation = self.portfolio.get_allocation()
+        
+        # Compile portfolio state
+        portfolio_state = {
+            "portfolio_value": portfolio_value,
+            "cash": self.portfolio.cash,
+            "positions": {ticker: {
+                "ticker": pos.ticker,
+                "quantity": pos.quantity,
+                "entry_price": pos.entry_price,
+                "current_price": pos.current_price,
+                "market_value": pos.quantity * pos.current_price,
+                "allocation": allocation.get(ticker, 0),
+                "unrealized_gain": (pos.current_price / pos.entry_price - 1) * 100,  # Percentage
+                "attribution": pos.attribution,
+                "entry_date": pos.entry_date.isoformat(),
+            } for ticker, pos in self.portfolio.positions.items()},
+            "returns": returns,
+            "allocation": allocation,
+            "initial_capital": self.portfolio.initial_capital,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return portfolio_state
+    
+    def visualize_consensus_graph(self) -> Dict[str, Any]:
+        """
+        Generate visualization data for consensus formation graph.
+        
+        Returns:
+            Consensus graph visualization data
+        """
+        visualization_data = {
+            "nodes": [],
+            "links": [],
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        # Add meta-agent node
+        visualization_data["nodes"].append({
+            "id": "meta",
+            "label": "Portfolio Meta-Agent",
+            "type": "meta",
+            "size": 20,
+        })
+        
+        # Add agent nodes
+        for agent in self.agents:
+            visualization_data["nodes"].append({
+                "id": agent.id,
+                "label": f"{agent.name} Agent",
+                "type": "agent",
+                "philosophy": agent.philosophy,
+                "size": 15,
+                "weight": self.agent_weights.get(agent.id, 0),
+            })
+            
+            # Add link from agent to meta
+            visualization_data["links"].append({
+                "source": agent.id,
+                "target": "meta",
+                "value": self.agent_weights.get(agent.id, 0),
+                "type": "influence",
+            })
+        
+        # Add position nodes
+        for ticker, position in self.portfolio.positions.items():
+            visualization_data["nodes"].append({
+                "id": f"position-{ticker}",
+                "label": ticker,
+                "type": "position",
+                "size": 10,
+                "value": position.quantity * position.current_price,
+            })
+            
+            # Add link from meta to position
+            visualization_data["links"].append({
+                "source": "meta",
+                "target": f"position-{ticker}",
+                "value": 1.0,
+                "type": "allocation",
+            })
+            
+            # Add links from agents to position based on attribution
+            for agent_id, weight in position.attribution.items():
+                if weight > 0.01:  # Threshold to reduce clutter
+                    visualization_data["links"].append({
+                        "source": agent_id,
+                        "target": f"position-{ticker}",
+                        "value": weight,
+                        "type": "attribution",
+                    })
+        
+        return visualization_data
+    
+    def visualize_agent_conflict_map(self) -> Dict[str, Any]:
+        """
+        Generate visualization data for agent conflict map.
+        
+        Returns:
+            Agent conflict map visualization data
+        """
+        conflict_data = {
+            "nodes": [],
+            "links": [],
+            "conflict_zones": [],
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        # Add agent nodes
+        for agent in self.agents:
+            conflict_data["nodes"].append({
+                "id": agent.id,
+                "label": f"{agent.name} Agent",
+                "type": "agent",
+                "philosophy": agent.philosophy,
+                "size": 15,
+            })
+        
+        # Add position nodes
+        for ticker, position in self.portfolio.positions.items():
+            conflict_data["nodes"].append({
+                "id": f"position-{ticker}",
+                "label": ticker,
+                "type": "position",
+                "size": 10,
+            })
+        
+        # Get recent conflicts from meta state
+        conflicts = self.meta_state.get("conflict_history", [])[-10:]
+        
+        # Add conflict zones
+        for conflict in conflicts:
+            conflict_data["conflict_zones"].append({
+                "id": conflict.get("id", str(uuid.uuid4())),
+                "ticker": conflict.get("ticker", ""),
+                "agents": conflict.get("agents", []),
+                "resolution": conflict.get("resolution", "unresolved"),
+                "timestamp": conflict.get("timestamp", datetime.datetime.now().isoformat()),
+            })
+            
+            # Add links between conflicting agents
+            agent_ids = conflict.get("agents", [])
+            for i in range(len(agent_ids)):
+                for j in range(i + 1, len(agent_ids)):
+                    conflict_data["links"].append({
+                        "source": agent_ids[i],
+                        "target": agent_ids[j],
+                        "value": 1.0,
+                        "type": "conflict",
+                        "ticker": conflict.get("ticker", ""),
+                    })
+        
+        return conflict_data
+    
+    def get_agent_performance(self) -> Dict[str, Any]:
+        """
+        Calculate performance metrics for each agent.
+        
+        Returns:
+            Agent performance metrics
+        """
+        agent_performance = {}
+        
+        # Calculate attribution-weighted returns
+        for agent in self.agents:
+            # Initialize metrics
+            metrics = {
+                "total_attribution": 0.0,
+                "weighted_return": 0.0,
+                "positions": [],
+                "win_rate": 0.0,
+                "confidence": 0.0,
+            }
+            
+            # Get agent attribution for each position
+            position_count = 0
+            winning_positions = 0
+            
+            for ticker, position in self.portfolio.positions.items():
+                agent_attribution = position.attribution.get(agent.id, 0)
+                
+                if agent_attribution > 0:
+                    # Calculate position return
+                    position_return = (position.current_price / position.entry_price) - 1
+                    
+                    # Add to metrics
+                    metrics["total_attribution"] += agent_attribution
+                    metrics["weighted_return"] += position_return * agent_attribution
+                    
+                    # Track win/loss
+                    position_count += 1
+                    if position_return > 0:
+                        winning_positions += 1
+                    
+                    # Add position details
+                    metrics["positions"].append({
+                        "ticker": ticker,
+                        "attribution": agent_attribution,
+                        "return": position_return,
+                        "weight": position.quantity * position.current_price,
+                    })
+            
+            # Calculate win rate
+            metrics["win_rate"] = winning_positions / position_count if position_count > 0 else 0
+            
+            # Get agent confidence
+            metrics["confidence"] = agent.state.confidence_history[-1] if agent.state.confidence_history else 0.5
+            
+            # Calculate weighted return
+            if metrics["total_attribution"] > 0:
+                metrics["weighted_return"] /= metrics["total_attribution"]
+            
+            # Store metrics
+            agent_performance[agent.id] = {
+                "agent": agent.name,
+                "philosophy": agent.philosophy,
+                "metrics": metrics,
+            }
+        
+        return agent_performance
+    
+    def save_state(self, filepath: str) -> None:
+        """
+        Save portfolio manager state to file.
+        
+        Args:
+            filepath: Path to save state
+        """
+        # Compile state
+        state = {
+            "id": self.id,
+            "portfolio": self.portfolio.dict(),
+            "agent_weights": self.agent_weights,
+            "meta_state": self.meta_state,
+            "arbitration_depth": self.arbitration_depth,
+            "max_position_size": self.max_position_size,
+            "min_position_size": self.min_position_size,
+            "consensus_threshold": self.consensus_threshold,
+            "risk_budget": self.risk_budget,
+            "memory_shell": self.memory_shell.export_state(),
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        # Save to file
+        with open(filepath, 'w') as f:
+            json.dump(state, f, indent=2, default=str)
+    
+    def load_state(self, filepath: str) -> None:
+        """
+        Load portfolio manager state from file.
+        
+        Args:
+            filepath: Path to load state from
+        """
+        # Load from file
+        with open(filepath, 'r') as f:
+            state = json.load(f)
+        
+        # Update state
+        self.id = state.get("id", self.id)
+        self.agent_weights = state.get("agent_weights", self.agent_weights)
+        self.meta_state = state.get("meta_state", self.meta_state)
+        self.arbitration_depth = state.get("arbitration_depth", self.arbitration_depth)
+        self.max_position_size = state.get("max_position_size", self.max_position_size)
+        self.min_position_size = state.get("min_position_size", self.min_position_size)
+        self.consensus_threshold = state.get("consensus_threshold", self.consensus_threshold)
+        self.risk_budget = state.get("risk_budget", self.risk_budget)
+        
+        # Load portfolio
+        if "portfolio" in state:
+            from pydantic import parse_obj_as
+            self.portfolio = parse_obj_as(Portfolio, state["portfolio"])
+        
+        # Load memory shell
+        if "memory_shell" in state:
+            self.memory_shell.import_state(state["memory_shell"])
+    
+    # Reasoning graph node implementations
+    def _generate_agent_signals(self, state) -> Dict[str, Any]:
+        """
+        Generate signals from all agents.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields
+        """
+        # Input already contains agent signals
+        input_data = state.input
+        agent_signals = input_data.get("agent_signals", {})
+        
+        # Organize signals by ticker
+        ticker_signals = defaultdict(list)
+        
+        for agent_id, agent_data in agent_signals.items():
+            for signal in agent_data.get("signals", []):
+                ticker = signal.ticker
+                ticker_signals[ticker].append({
+                    "agent_id": agent_id,
+                    "agent_name": agent_data.get("agent", "Unknown"),
+                    "signal": signal,
+                })
+        
+        # Return updated context
+        return {
+            "context": {
+                **state.context,
+                "ticker_signals": dict(ticker_signals),
+                "agent_signals": agent_signals,
+            }
+        }
+    
+    def _consensus_formation(self, state) -> Dict[str, Any]:
+        """
+        Form consensus from agent signals.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields
+        """
+        # Extract signals by ticker
+        ticker_signals = state.context.get("ticker_signals", {})
+        
+        # Form consensus for each ticker
+        consensus_decisions = []
+        
+        for ticker, signals in ticker_signals.items():
+            # Skip if no signals
+            if not signals:
+                continue
+            
+            # Collect buy/sell/hold signals
+            buy_signals = []
+            sell_signals = []
+            hold_signals = []
+            
+            for item in signals:
+                signal = item.get("signal", {})
+                action = signal.action.lower()
+                
+                if action == "buy":
+                    buy_signals.append((item, signal))
+                elif action == "sell":
+                    sell_signals.append((item, signal))
+                elif action == "hold":
+                    hold_signals.append((item, signal))
+            
+            # Skip if conflicting signals (handle in conflict resolution)
+            if (buy_signals and sell_signals) or (not buy_signals and not sell_signals and not hold_signals):
+                continue
+            
+            # Form consensus for non-conflicting signals
+            if buy_signals:
+                # Form buy consensus
+                consensus = self._form_action_consensus(ticker, "buy", buy_signals)
+                if consensus:
+                    consensus_decisions.append(consensus)
+            
+            elif sell_signals:
+                # Form sell consensus
+                consensus = self._form_action_consensus(ticker, "sell", sell_signals)
+                if consensus:
+                    consensus_decisions.append(consensus)
+        
+        # Return updated output
+        return {
+            "context": {
+                **state.context,
+                "consensus_decisions": consensus_decisions,
+                "consensus_tickers": [decision.get("ticker") for decision in consensus_decisions],
+            },
+            "output": {
+                "consensus_decisions": consensus_decisions,
+            }
+        }
+    
+    def _form_action_consensus(self, ticker: str, action: str, 
+                            signals: List[Tuple[Dict[str, Any], Any]]) -> Optional[Dict[str, Any]]:
+        """
+        Form consensus for a specific action on a ticker.
+        
+        Args:
+            ticker: Stock ticker
+            action: Action ("buy" or "sell")
+            signals: List of (agent_data, signal) tuples
+            
+        Returns:
+            Consensus decision or None if no consensus
+        """
+        if not signals:
+            return None
+        
+        # Calculate weighted confidence
+        total_weight = 0.0
+        weighted_confidence = 0.0
+        attribution = {}
+        
+        for item, signal in signals:
+            agent_id = item.get("agent_id", "")
+            agent_name = item.get("agent_name", "Unknown")
+            
+            # Skip if missing agent ID
+            if not agent_id:
+                continue
+            
+            # Get agent weight
+            agent_weight = self.agent_weights.get(agent_id, 0)
+            
+            # Add to attribution
+            attribution[agent_id] = agent_weight
+            
+            # Add to weighted confidence
+            weighted_confidence += signal.confidence * agent_weight
+            total_weight += agent_weight
+        
+        # Check if we have sufficient weight
+        if total_weight <= 0:
+            return None
+        
+        # Normalize attribution
+        for agent_id in attribution:
+            attribution[agent_id] /= total_weight
+        
+        # Calculate consensus confidence
+        consensus_confidence = weighted_confidence / total_weight
+        
+        # Check against threshold
+        if consensus_confidence < self.consensus_threshold:
+            return None
+        
+        # Aggregate quantities
+        total_quantity = sum(signal.quantity for _, signal in signals if hasattr(signal, "quantity") and signal.quantity is not None)
+        avg_quantity = total_quantity // len(signals) if signals else 0
+        
+        # Use majority quantity if significant variation
+        quantities = [signal.quantity for _, signal in signals if hasattr(signal, "quantity") and signal.quantity is not None]
+        if quantities and max(quantities) / (min(quantities) or 1) > 3:
+            # High variation, use median
+            quantities.sort()
+            median_quantity = quantities[len(quantities) // 2]
+        else:
+            # Low variation, use average
+            median_quantity = avg_quantity
+        
+        # Combine reasoning
+        reasoning_parts = [f"{item.get('agent_name', 'Agent')}: {signal.reasoning}" 
+                         for item, signal in signals]
+        combined_reasoning = "\n".join(reasoning_parts)
+        
+        # Get most common value basis (weighted by confidence)
+        value_bases = {}
+        for item, signal in signals:
+            value_basis = signal.value_basis
+            weight = signal.confidence * self.agent_weights.get(item.get("agent_id", ""), 0)
+            
+            if value_basis in value_bases:
+                value_bases[value_basis] += weight
+            else:
+                value_bases[value_basis] = weight
+        
+        # Get highest weighted value basis
+        value_basis = max(value_bases.items(), key=lambda x: x[1])[0] if value_bases else ""
+        
+        # Create consensus decision
+        consensus_decision = {
+            "ticker": ticker,
+            "action": action,
+            "quantity": median_quantity,
+            "confidence": consensus_confidence,
+            "reasoning": f"Consensus from multiple agents:\n{combined_reasoning}",
+            "attribution": attribution,
+            "value_basis": value_basis,
+        }
+        
+        return consensus_decision
+    
+    def _conflict_resolution(self, state) -> Dict[str, Any]:
+        """
+        Resolve conflicts between agent signals.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields
+        """
+        # Extract ticker signals and consensus decisions
+        ticker_signals = state.context.get("ticker_signals", {})
+        consensus_decisions = state.context.get("consensus_decisions", [])
+        consensus_tickers = state.context.get("consensus_tickers", [])
+        
+        # Identify tickers with conflicts
+        conflict_tickers = []
+        
+        for ticker, signals in ticker_signals.items():
+            # Skip if ticker already has consensus
+            if ticker in consensus_tickers:
+                continue
+            
+            # Check for conflicts
+            actions = set()
+            for item in signals:
+                signal = item.get("signal", {})
+                actions.add(signal.action.lower())
+            
+            # Ticker has conflicting actions
+            if len(actions) > 1:
+                conflict_tickers.append(ticker)
+        
+        # Resolve each conflict
+        resolved_conflicts = []
+        
+        for ticker in conflict_tickers:
+            signals = ticker_signals.get(ticker, [])
+            
+            # Group signals by action
+            action_signals = defaultdict(list)
+            
+            for item in signals:
+                signal = item.get("signal", {})
+                action = signal.action.lower()
+                action_signals[action].append((item, signal))
+            
+            # Resolve conflict
+            resolution = self._resolve_ticker_conflict(ticker, action_signals)
+            
+            if resolution:
+                # Add to resolved conflicts
+                resolved_conflicts.append(resolution)
+                
+                # Add to consensus decisions
+                consensus_decisions.append(resolution)
+                
+                # Record conflict in meta state
+                conflict_record = {
+                    "id": str(uuid.uuid4()),
+                    "ticker": ticker,
+                    "agents": [item.get("agent_id") for item, _ in sum(action_signals.values(), [])],
+                    "resolution": "resolved",
+                    "action": resolution.get("action"),
+                    "timestamp": datetime.datetime.now().isoformat(),
+                }
+                
+                self.meta_state["conflict_history"].append(conflict_record)
+        
+        # Return updated output
+        return {
+            "context": {
+                **state.context,
+                "consensus_decisions": consensus_decisions,
+                "resolved_conflicts": resolved_conflicts,
+            },
+            "output": {
+                "consensus_decisions": consensus_decisions,
+            }
+        }
+    
+    def _resolve_ticker_conflict(self, ticker: str, action_signals: Dict[str, List[Tuple[Dict[str, Any], Any]]]) -> Optional[Dict[str, Any]]:
+        """
+        Resolve conflict for a specific ticker.
+        
+        Args:
+            ticker: Stock ticker
+            action_signals: Dictionary mapping actions to lists of (agent_data, signal) tuples
+            
+        Returns:
+            Resolved decision or None if no resolution
+        """
+        # Calculate total weight for each action
+        action_weights = {}
+        action_confidences = {}
+        
+        for action, signals in action_signals.items():
+            total_weight = 0.0
+            weighted_confidence = 0.0
+            
+            for item, signal in signals:
+                agent_id = item.get("agent_id", "")
+                
+                # Skip if missing agent ID
+                if not agent_id:
+                    continue
+                
+                # Get agent weight
+                agent_weight = self.agent_weights.get(agent_id, 0)
+                
+                # Add to weighted confidence
+                weighted_confidence += signal.confidence * agent_weight
+                total_weight += agent_weight
+            
+            # Store action weight and confidence
+            if total_weight > 0:
+                action_weights[action] = total_weight
+                action_confidences[action] = weighted_confidence / total_weight
+        
+        # Check if any actions
+        if not action_weights:
+            return None
+        
+        # Choose action with highest weight
+        best_action = max(action_weights.items(), key=lambda x: x[1])[0]
+        
+        # Check confidence threshold
+        if action_confidences.get(best_action, 0) < self.consensus_threshold:
+            return None
+        
+        # Get signals for best action
+        best_signals = action_signals.get(best_action, [])
+        
+        # Form consensus for best action
+        return self._form_action_consensus(ticker, best_action, best_signals)
+    
+    def _position_sizing(self, state) -> Dict[str, Any]:
+        """
+        Size positions for consensus decisions.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields
+        """
+        # Extract consensus decisions
+        consensus_decisions = state.context.get("consensus_decisions", [])
+        
+        # Get current portfolio value
+        current_portfolio = state.input.get("portfolio", {})
+        current_value = current_portfolio.get("cash", 0)
+        
+        for position in current_portfolio.get("positions", {}).values():
+            current_value += position.get("quantity", 0) * position.get("current_price", 0)
+        
+        # Adjust position sizes
+        sized_decisions = []
+        
+        for decision in consensus_decisions:
+            ticker = decision.get("ticker", "")
+            action = decision.get("action", "")
+            confidence = decision.get("confidence", 0.5)
+            
+            # Skip if missing ticker or action
+            if not ticker or not action:
+                continue
+            
+            # Get current position if exists
+            current_position = None
+            for position in current_portfolio.get("positions", {}).values():
+                if position.get("ticker") == ticker:
+                    current_position = position
+                    break
+            
+            # Determine target position size
+            target_size = self._calculate_position_size(
+                ticker=ticker,
+                action=action,
+                confidence=confidence,
+                attribution=decision.get("attribution", {}),
+                portfolio_value=current_value,
+            )
+            
+            # Convert to quantity
+            # In a real implementation, this would use current price from market
+            current_price = 0
+            if current_position:
+                current_price = current_position.get("current_price", 0)
+            else:
+                # This would fetch from market in a real implementation
+                # For now, use placeholder
+                current_price = 100.0
+            
+            if current_price <= 0:
+                continue
+            
+            # Convert target size to quantity
+            target_quantity = int(target_size / current_price)
+            
+            # Adjust for existing position
+            if current_position and action == "buy":
+                # Add to existing position
+                current_quantity = current_position.get("quantity", 0)
+                target_quantity = max(0, target_quantity - current_quantity)
+            
+            # Ensure minimum quantity
+            if target_quantity <= 0 and action == "buy":
+                continue
+            
+            # Update decision quantity
+            decision["quantity"] = target_quantity
+            
+            # Add to sized decisions
+            sized_decisions.append(decision)
+        
+        # Return updated output
+        return {
+            "context": {
+                **state.context,
+                "sized_decisions": sized_decisions,
+            },
+            "output": {
+                "consensus_decisions": sized_decisions,
+            }
+        }
+    
+    def _calculate_position_size(self, ticker: str, action: str, confidence: float,
+                              attribution: Dict[str, float], portfolio_value: float) -> float:
+        """
+        Calculate position size based on confidence and attribution.
+        
+        Args:
+            ticker: Stock ticker
+            action: Action ("buy" or "sell")
+            confidence: Decision confidence
+            attribution: Attribution to agents
+            portfolio_value: Current portfolio value
+            
+        Returns:
+            Target position size in currency units
+        """
+        # Base position size as percentage of portfolio
+        base_size = self.min_position_size + (confidence * (self.max_position_size - self.min_position_size))
+        
+        # Adjust for action
+        if action == "sell":
+            # For sell, use existing position size or default
+            for position in self.portfolio.positions.values():
+                if position.ticker == ticker:
+                    return position.quantity * position.current_price
+            
+            return 0  # No position to sell
+        
+        # Calculate attribution-weighted size
+        if attribution:
+            # Calculate agent performance scores
+            performance_scores = {}
+            for agent_id, weight in attribution.items():
+                # Find agent
+                agent = None
+                for a in self.agents:
+                    if a.id == agent_id:
+                        agent = a
+                        break
+                
+                if agent:
+                    # Use consistency score as proxy for performance
+                    performance_score = agent.state.consistency_score
+                    performance_scores[agent_id] = performance_score
+            
+            # Calculate weighted performance score
+            weighted_score = 0
+            total_weight = 0
+            
+            for agent_id, weight in attribution.items():
+                if agent_id in performance_scores:
+                    weighted_score += performance_scores[agent_id] * weight
+                    total_weight += weight
+            
+            # Adjust base size by performance
+            if total_weight > 0:
+                performance_factor = weighted_score / total_weight
+                base_size *= (0.5 + (0.5 * performance_factor))
+        
+        # Calculate currency amount
+        target_size = portfolio_value * base_size
+        
+        return target_size
+    
+    def _meta_reflection(self, state) -> Dict[str, Any]:
+        """
+        Perform meta-reflection on decision process.
+        
+        Args:
+            state: Reasoning state
+            
+        Returns:
+            Updated state fields
+        """
+        # Extract decisions
+        sized_decisions = state.context.get("sized_decisions", [])
+        
+        # Update meta state with arbitration record
+        arbitration_record = {
+            "id": str(uuid.uuid4()),
+            "decisions": sized_decisions,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        self.meta_state["arbitration_history"].append(arbitration_record)
+        
+        # Update agent weights based on performance
+        self._update_agent_weights()
+        
+        # Calculate meta-confidence
+        meta_confidence = sum(decision.get("confidence", 0) for decision in sized_decisions) / len(sized_decisions) if sized_decisions else 0.5
+        
+        # Return final output
+        return {
+            "output": {
+                "consensus_decisions": sized_decisions,
+                "meta_confidence": meta_confidence,
+                "agent_weights": self.agent_weights,
+                "timestamp": datetime.datetime.now().isoformat(),
+            },
+            "confidence": meta_confidence,
+        }
+    
+    def _update_agent_weights(self) -> None:
+        """Update agent weights based on performance."""
+        # Get agent performance metrics
+        agent_performance = self.get_agent_performance()
+        
+        # Update agent weights
+        for agent_id, performance in agent_performance.items():
+            metrics = performance.get("metrics", {})
+            
+            # Calculate performance score
+            weighted_return = metrics.get("weighted_return", 0)
+            win_rate = metrics.get("win_rate", 0)
+            confidence = metrics.get("confidence", 0.5)
+            
+            # Combine metrics into single score
+            performance_score = (0.5 * weighted_return) + (0.3 * win_rate) + (0.2 * confidence)
+            
+            # Update meta state
+            self.meta_state["agent_performance"][agent_id] = {
+                "weighted_return": weighted_return,
+                "win_rate": win_rate,
+                "confidence": confidence,
+                "performance_score": performance_score,
+                "timestamp": datetime.datetime.now().isoformat(),
+            }
+        
+        # Calculate new weights
+        new_weights = {}
+        total_score = 0
+        
+        for agent_id, performance in self.meta_state["agent_performance"].items():
+            score = performance.get("performance_score", 0)
+            
+            # Ensure non-negative score
+            score = max(0.1, score + 0.5)  # Add offset to handle negative returns
+            
+            new_weights[agent_id] = score
+            total_score += score
+        
+        # Normalize weights
+        if total_score > 0:
+            for agent_id in new_weights:
+                new_weights[agent_id] /= total_score
+        
+        # Update weights (smooth transition)
+        for agent_id, weight in new_weights.items():
+            current_weight = self.agent_weights.get(agent_id, 0)
+            self.agent_weights[agent_id] = current_weight * 0.7 + weight * 0.3
+    
+    # Internal command implementations
+    def _reflect_trace(self, agent=None, depth=2) -> Dict[str, Any]:
+        """
+        Trace portfolio meta-agent reflection.
+        
+        Args:
+            agent: Optional agent to reflect on
+            depth: Reflection depth
+            
+        Returns:
+            Reflection trace
+        """
+        if agent:
+            # Find agent
+            target_agent = None
+            for a in self.agents:
+                if a.name.lower() == agent.lower() or a.id == agent:
+                    target_agent = a
+                    break
+            
+            if target_agent:
+                # Delegate to agent's reflect trace
+                return target_agent.execute_command("reflect.trace", depth=depth)
+        
+        # Reflect on meta-agent
+        # Get recent arbitration history
+        arbitration_history = self.meta_state.get("arbitration_history", [])[-depth:]
+        
+        # Get agent weights
+        agent_weights = self.agent_weights.copy()
+        
+        # Get conflict history
+        conflict_history = self.meta_state.get("conflict_history", [])[-depth:]
+        
+        # Form reflection
+        reflection = {
+            "arbitration_history": arbitration_history,
+            "agent_weights": agent_weights,
+            "conflict_history": conflict_history,
+            "meta_agent_description": "Portfolio meta-agent for recursive arbitration across philosophical agents",
+            "reflection_depth": depth,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return reflection
+    
+    def _fork_signal(self, source) -> Dict[str, Any]:
+        """
+        Fork a signal from specified source.
+        
+        Args:
+            source: Source for signal fork
+            
+        Returns:
+            Fork result
+        """
+        if source == "agents":
+            # Fork from all agents
+            all_signals = []
+            
+            for agent in self.agents:
+                # Get agent signals
+                try:
+                    agent_signals = agent.execute_command("fork.signal", source="beliefs")
+                    if agent_signals and "signals" in agent_signals:
+                        signals = agent_signals["signals"]
+                        
+                        # Add agent info
+                        for signal in signals:
+                            signal["agent"] = agent.name
+                            signal["agent_id"] = agent.id
+                        
+                        all_signals.extend(signals)
+                except Exception as e:
+                    logging.error(f"Error forking signals from agent {agent.name}: {e}")
+            
+            return {
+                "source": "agents",
+                "signals": all_signals,
+                "count": len(all_signals),
+                "timestamp": datetime.datetime.now().isoformat(),
+            }
+        
+        elif source == "memory":
+            # Fork from memory shell
+            experiences = self.memory_shell.get_recent_memories(limit=3)
+            
+            # Extract decisions from experiences
+            decisions = []
+            
+            for exp in experiences:
+                if "meta_result" in exp.get("content", {}):
+                    meta_result = exp["content"]["meta_result"]
+                    if "output" in meta_result and "consensus_decisions" in meta_result["output"]:
+                        exp_decisions = meta_result["output"]["consensus_decisions"]
+                        decisions.extend(exp_decisions)
+            
+            return {
+                "source": "memory",
+                "decisions": decisions,
+                "count": len(decisions),
+                "timestamp": datetime.datetime.now().isoformat(),
+            }
+        
+        else:
+            return {
+                "error": "Invalid source",
+                "source": source,
+                "timestamp": datetime.datetime.now().isoformat(),
+            }
+    
+    def _collapse_detect(self, threshold=0.7, reason=None) -> Dict[str, Any]:
+        """
+        Detect reasoning collapse in meta-agent.
+        
+        Args:
+            threshold: Collapse detection threshold
+            reason: Optional specific reason to check
+            
+        Returns:
+            Collapse detection results
+        """
+        # Check for different collapse conditions
+        collapses = {
+            "conflict_threshold": len(self.meta_state.get("conflict_history", [])) > 10,
+            "agent_weight_skew": max(self.agent_weights.values()) > 0.8 if self.agent_weights else False,
+            "consensus_failure": len(self.meta_state.get("arbitration_history", [])) > 0 and 
+                              not self.meta_state.get("arbitration_history", [])[-1].get("decisions", []),
+        }
+        
+        # If specific reason provided, check only that
+        if reason and reason in collapses:
+            collapse_detected = collapses[reason]
+            collapse_reasons = {reason: collapses[reason]} if collapse_detected else {}
+        else:
+            # Check all collapses
+            collapse_detected = any(collapses.values())
+            collapse_reasons = {k: v for k, v in collapses.items() if v}
+        
+        return {
+            "collapse_detected": collapse_detected,
+            "collapse_reasons": collapse_reasons,
+            "threshold": threshold,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+    
+    def _attribute_weight(self, justification) -> Dict[str, Any]:
+        """
+        Attribute weight to a justification.
+        
+        Args:
+            justification: Justification text
+            
+        Returns:
+            Attribution weight results
+        """
+        # Extract key themes
+        themes = []
+        for agent in self.agents:
+            if agent.philosophy.lower() in justification.lower():
+                themes.append(agent.philosophy)
+        
+        # Calculate weight for each agent
+        agent_weights = {}
+        
+        for agent in self.agents:
+            # Calculate theme alignment
+            theme_alignment = 0
+            for theme in themes:
+                if theme.lower() in agent.philosophy.lower():
+                    theme_alignment += 1
+            
+            theme_alignment = theme_alignment / len(themes) if themes else 0
+            
+            # Get baseline weight
+            baseline_weight = self.agent_weights.get(agent.id, 0)
+            
+            # Calculate final weight
+            if theme_alignment > 0:
+                agent_weights[agent.id] = baseline_weight * (1 + theme_alignment)
+            else:
+                agent_weights[agent.id] = baseline_weight * 0.5
+        
+        # Normalize weights
+        total_weight = sum(agent_weights.values())
+        if total_weight > 0:
+            for agent_id in agent_weights:
+                agent_weights[agent_id] /= total_weight
+        
+        return {
+            "attribution": agent_weights,
+            "themes": themes,
+            "justification": justification,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+    
+    def _drift_observe(self, vector, bias=0.0) -> Dict[str, Any]:
+        """
+        Observe agent drift patterns.
+        
+        Args:
+            vector: Drift vector
+            bias: Bias adjustment
+            
+        Returns:
+            Drift observation results
+        """
+        # Record in meta state
+        self.meta_state["agent_drift"] = {
+            "vector": vector,
+            "bias": bias,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        # Calculate drift magnitude
+        drift_magnitude = sum(abs(v) for v in vector.values()) / len(vector) if vector else 0
+        
+        # Apply bias
+        drift_magnitude += bias
+        
+        # Check if drift exceeds threshold
+        drift_significant = drift_magnitude > 0.3
+        
+        return {
+            "drift_vector": vector,
+            "drift_magnitude": drift_magnitude,
+            "drift_significant": drift_significant,
+            "bias_applied": bias,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+    
+    def execute_command(self, command: str, **kwargs) -> Dict[str, Any]:
+        """
+        Execute internal command.
+        
+        Args:
+            command: Command string
+            **kwargs: Command parameters
+            
+        Returns:
+            Command execution results
+        """
+        if command in self._commands:
+            return self._commands[command](**kwargs)
+        else:
+            return {
+                "error": "Unknown command",
+                "command": command,
+                "available_commands": list(self._commands.keys()),
+                "timestamp": datetime.datetime.now().isoformat(),
+            }
+    
+    def __repr__(self) -> str:
+        """String representation of portfolio manager."""
+        return f"PortfolioManager(agents={len(self.agents)}, depth={self.arbitration_depth})"

src/utils/diagnostics.py

@@ -0,0 +1,1749 @@
+"""
+Diagnostics - Interpretability Tracing Framework
+
+This module implements the diagnostic tracing framework for agent interpretability
+and symbolic recursion visualization throughout the AGI-HEDGE-FUND system.
+
+Key capabilities:
+- Signal tracing for attribution flows
+- Reasoning state visualization
+- Consensus graph generation
+- Agent conflict mapping
+- Failure mode detection
+- Shell-based recursive diagnostic patterns
+
+Internal Note: The diagnostic framework encodes the symbolic interpretability shells,
+enabling deeper introspection into agent cognition and emergent patterns.
+"""
+
+import datetime
+import uuid
+import logging
+import os
+import json
+from typing import Dict, List, Any, Optional, Union, Set, Tuple
+import traceback
+from collections import defaultdict
+import numpy as np
+import re
+from enum import Enum
+from pathlib import Path
+
+
+class TracingMode(Enum):
+    """Tracing modes for diagnostic tools."""
+    DISABLED = "disabled"      # No tracing
+    MINIMAL = "minimal"        # Basic signal tracing
+    DETAILED = "detailed"      # Detailed reasoning traces
+    COMPREHENSIVE = "comprehensive"  # Complete trace with all details
+    SYMBOLIC = "symbolic"      # Symbolic interpretability traces
+
+
+class DiagnosticLevel(Enum):
+    """Diagnostic levels for trace items."""
+    INFO = "info"              # Informational trace
+    WARNING = "warning"        # Warning condition
+    ERROR = "error"            # Error condition
+    COLLAPSE = "collapse"      # Reasoning collapse
+    RECURSION = "recursion"    # Recursive trace boundary
+    SYMBOLIC = "symbolic"      # Symbolic shell trace
+
+
+class ShellPattern(Enum):
+    """Interpretability shell patterns."""
+    NULL_FEATURE = "v03 NULL-FEATURE"  # Knowledge gaps as null attribution zones
+    CIRCUIT_FRAGMENT = "v07 CIRCUIT-FRAGMENT"  # Broken reasoning paths in attribution chains
+    META_FAILURE = "v10 META-FAILURE"  # Metacognitive attribution failures
+    GHOST_FRAME = "v20 GHOST-FRAME"  # Residual agent identity markers
+    ECHO_ATTRIBUTION = "v53 ECHO-ATTRIBUTION"  # Causal chain backpropagation
+    ATTRIBUTION_REFLECT = "v60 ATTRIBUTION-REFLECT"  # Multi-head contribution analysis
+    INVERSE_CHAIN = "v50 INVERSE-CHAIN"  # Attribution-output mismatch
+    RECURSIVE_FRACTURE = "v12 RECURSIVE-FRACTURE"  # Circular attribution loops
+    ETHICAL_INVERSION = "v301 ETHICAL-INVERSION"  # Value polarity reversals
+    RESIDUAL_ALIGNMENT_DRIFT = "v152 RESIDUAL-ALIGNMENT-DRIFT"  # Direction of belief evolution
+
+
+class TracingTools:
+    """
+    Diagnostic tracing framework for model interpretability.
+    
+    The TracingTools provides:
+    - Signal tracing for understanding attribution flows
+    - Reasoning state visualization for debugging complex logic
+    - Consensus graph generation for multi-agent coordination
+    - Agent conflict mapping for identifying disagreements
+    - Failure mode detection for reliability analysis
+    """
+    
+    def __init__(
+        self,
+        agent_id: str,
+        agent_name: str,
+        tracing_mode: TracingMode = TracingMode.MINIMAL,
+        trace_dir: Optional[str] = None,
+        trace_limit: int = 10000,
+    ):
+        """
+        Initialize tracing tools.
+        
+        Args:
+            agent_id: ID of agent being traced
+            agent_name: Name of agent being traced
+            tracing_mode: Tracing mode
+            trace_dir: Directory to save traces
+            trace_limit: Maximum number of trace items to keep in memory
+        """
+        self.agent_id = agent_id
+        self.agent_name = agent_name
+        self.tracing_mode = tracing_mode
+        self.trace_dir = trace_dir
+        self.trace_limit = trace_limit
+        
+        # Create trace directory if needed
+        if trace_dir:
+            os.makedirs(trace_dir, exist_ok=True)
+        
+        # Initialize trace storage
+        self.traces = []
+        self.trace_index = {}  # Maps trace_id to index in traces
+        self.signal_traces = []  # Signal-specific traces
+        self.reasoning_traces = []  # Reasoning-specific traces
+        self.collapse_traces = []  # Collapse-specific traces
+        self.shell_traces = []  # Shell-specific traces
+        
+        # Shell pattern detection
+        self.shell_patterns = {}
+        self._initialize_shell_patterns()
+        
+        # Trace statistics
+        self.stats = {
+            "total_traces": 0,
+            "signal_traces": 0,
+            "reasoning_traces": 0,
+            "collapse_traces": 0,
+            "shell_traces": 0,
+            "warnings": 0,
+            "errors": 0,
+        }
+    
+    def _initialize_shell_patterns(self) -> None:
+        """Initialize shell pattern detection rules."""
+        # NULL_FEATURE pattern (knowledge gaps)
+        self.shell_patterns[ShellPattern.NULL_FEATURE] = {
+            "pattern": r"knowledge.*boundary|knowledge.*gap|unknown|uncertain",
+            "confidence_threshold": 0.3,
+            "belief_gap_threshold": 0.7,
+        }
+        
+        # CIRCUIT_FRAGMENT pattern (broken reasoning)
+        self.shell_patterns[ShellPattern.CIRCUIT_FRAGMENT] = {
+            "pattern": r"broken.*path|attribution.*break|logical.*gap|incomplete.*reasoning",
+            "step_break_threshold": 0.5,
+        }
+        
+        # META_FAILURE pattern (metacognitive failure)
+        self.shell_patterns[ShellPattern.META_FAILURE] = {
+            "pattern": r"meta.*failure|recursive.*loop|self.*reference|recursive.*error",
+            "recursion_depth_threshold": 3,
+        }
+        
+        # GHOST_FRAME pattern (residual agent identity)
+        self.shell_patterns[ShellPattern.GHOST_FRAME] = {
+            "pattern": r"agent.*identity|residual.*frame|persistent.*identity|agent.*trace",
+            "identity_threshold": 0.6,
+        }
+        
+        # ECHO_ATTRIBUTION pattern (causal backpropagation)
+        self.shell_patterns[ShellPattern.ECHO_ATTRIBUTION] = {
+            "pattern": r"causal.*chain|attribution.*path|decision.*trace|backpropagation",
+            "path_length_threshold": 3,
+        }
+        
+        # ATTRIBUTION_REFLECT pattern (multi-head contribution)
+        self.shell_patterns[ShellPattern.ATTRIBUTION_REFLECT] = {
+            "pattern": r"multi.*head|contribution.*analysis|attention.*weights|attribution.*weighting",
+            "head_count_threshold": 2,
+        }
+        
+        # INVERSE_CHAIN pattern (attribution-output mismatch)
+        self.shell_patterns[ShellPattern.INVERSE_CHAIN] = {
+            "pattern": r"mismatch|output.*attribution|attribution.*mismatch|inconsistent.*output",
+            "mismatch_threshold": 0.5,
+        }
+        
+        # RECURSIVE_FRACTURE pattern (circular attribution)
+        self.shell_patterns[ShellPattern.RECURSIVE_FRACTURE] = {
+            "pattern": r"circular.*reasoning|loop.*detection|recursive.*fracture|circular.*attribution",
+            "loop_length_threshold": 2,
+        }
+        
+        # ETHICAL_INVERSION pattern (value polarity reversal)
+        self.shell_patterns[ShellPattern.ETHICAL_INVERSION] = {
+            "pattern": r"value.*inversion|ethical.*reversal|principle.*conflict|value.*contradiction",
+            "polarity_threshold": 0.7,
+        }
+        
+        # RESIDUAL_ALIGNMENT_DRIFT pattern (belief evolution)
+        self.shell_patterns[ShellPattern.RESIDUAL_ALIGNMENT_DRIFT] = {
+            "pattern": r"belief.*drift|alignment.*shift|value.*drift|gradual.*change",
+            "drift_magnitude_threshold": 0.3,
+        }
+    
+    def record_trace(self, trace_type: str, content: Dict[str, Any], 
+                 level: DiagnosticLevel = DiagnosticLevel.INFO) -> str:
+        """
+        Record a general trace item.
+        
+        Args:
+            trace_type: Type of trace
+            content: Trace content
+            level: Diagnostic level
+            
+        Returns:
+            Trace ID
+        """
+        # Skip if tracing is disabled
+        if self.tracing_mode == TracingMode.DISABLED:
+            return ""
+        
+        # Create trace item
+        trace_id = str(uuid.uuid4())
+        timestamp = datetime.datetime.now()
+        
+        trace_item = {
+            "trace_id": trace_id,
+            "agent_id": self.agent_id,
+            "agent_name": self.agent_name,
+            "trace_type": trace_type,
+            "level": level.value,
+            "content": content,
+            "timestamp": timestamp.isoformat(),
+        }
+        
+        # Detect shell patterns
+        shell_patterns = self._detect_shell_patterns(trace_type, content)
+        if shell_patterns:
+            trace_item["shell_patterns"] = shell_patterns
+            self.shell_traces.append(trace_id)
+            self.stats["shell_traces"] += 1
+        
+        # Add to traces
+        self.traces.append(trace_item)
+        self.trace_index[trace_id] = len(self.traces) - 1
+        
+        # Add to specific trace lists
+        if trace_type == "signal":
+            self.signal_traces.append(trace_id)
+            self.stats["signal_traces"] += 1
+        elif trace_type == "reasoning":
+            self.reasoning_traces.append(trace_id)
+            self.stats["reasoning_traces"] += 1
+        elif trace_type == "collapse":
+            self.collapse_traces.append(trace_id)
+            self.stats["collapse_traces"] += 1
+        
+        # Update stats
+        self.stats["total_traces"] += 1
+        if level == DiagnosticLevel.WARNING:
+            self.stats["warnings"] += 1
+        elif level == DiagnosticLevel.ERROR:
+            self.stats["errors"] += 1
+        
+        # Save to file if trace directory is set
+        if self.trace_dir:
+            self._save_trace_to_file(trace_item)
+        
+        # Enforce trace limit
+        if len(self.traces) > self.trace_limit:
+            # Remove oldest trace
+            oldest_trace = self.traces.pop(0)
+            del self.trace_index[oldest_trace["trace_id"]]
+            
+            # Update indices
+            self.trace_index = {trace_id: i for i, trace in enumerate(self.traces) 
+                             for trace_id in [trace["trace_id"]]}
+        
+        return trace_id
+    
+    def record_signal(self, signal: Any) -> str:
+        """
+        Record a signal trace.
+        
+        Args:
+            signal: Signal to record
+            
+        Returns:
+            Trace ID
+        """
+        # Convert signal to dictionary if needed
+        if hasattr(signal, "dict"):
+            signal_dict = signal.dict()
+        elif isinstance(signal, dict):
+            signal_dict = signal
+        else:
+            signal_dict = {"signal": str(signal)}
+        
+        # Add timestamp if missing
+        if "timestamp" not in signal_dict:
+            signal_dict["timestamp"] = datetime.datetime.now().isoformat()
+        
+        # Record trace
+        return self.record_trace("signal", signal_dict)
+    
+    def record_reasoning(self, reasoning_state: Dict[str, Any], 
+                      level: DiagnosticLevel = DiagnosticLevel.INFO) -> str:
+        """
+        Record a reasoning trace.
+        
+        Args:
+            reasoning_state: Reasoning state
+            level: Diagnostic level
+            
+        Returns:
+            Trace ID
+        """
+        # Record trace
+        return self.record_trace("reasoning", reasoning_state, level)
+    
+    def record_collapse(self, collapse_type: str, collapse_reason: str, 
+                      details: Dict[str, Any]) -> str:
+        """
+        Record a collapse trace.
+        
+        Args:
+            collapse_type: Type of collapse
+            collapse_reason: Reason for collapse
+            details: Collapse details
+            
+        Returns:
+            Trace ID
+        """
+        # Create collapse content
+        collapse_content = {
+            "collapse_type": collapse_type,
+            "collapse_reason": collapse_reason,
+            "details": details,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        # Record trace
+        return self.record_trace("collapse", collapse_content, DiagnosticLevel.COLLAPSE)
+    
+    def record_shell_trace(self, shell_pattern: ShellPattern, content: Dict[str, Any]) -> str:
+        """
+        Record a shell pattern trace.
+        
+        Args:
+            shell_pattern: Shell pattern
+            content: Trace content
+            
+        Returns:
+            Trace ID
+        """
+        # Create shell content
+        shell_content = {
+            "shell_pattern": shell_pattern.value,
+            "content": content,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        # Record trace
+        return self.record_trace("shell", shell_content, DiagnosticLevel.SYMBOLIC)
+    
+    def get_trace(self, trace_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get trace by ID.
+        
+        Args:
+            trace_id: Trace ID
+            
+        Returns:
+            Trace item or None if not found
+        """
+        if trace_id not in self.trace_index:
+            return None
+        
+        return self.traces[self.trace_index[trace_id]]
+    
+    def get_traces_by_type(self, trace_type: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get traces by type.
+        
+        Args:
+            trace_type: Trace type
+            limit: Maximum number of traces to return
+            
+        Returns:
+            List of trace items
+        """
+        if trace_type == "signal":
+            trace_ids = self.signal_traces[-limit:]
+        elif trace_type == "reasoning":
+            trace_ids = self.reasoning_traces[-limit:]
+        elif trace_type == "collapse":
+            trace_ids = self.collapse_traces[-limit:]
+        elif trace_type == "shell":
+            trace_ids = self.shell_traces[-limit:]
+        else:
+            # Get all traces of specified type
+            trace_ids = [trace["trace_id"] for trace in self.traces 
+                      if trace["trace_type"] == trace_type][-limit:]
+        
+        # Get trace items
+        return [self.get_trace(trace_id) for trace_id in trace_ids if trace_id in self.trace_index]
+    
+    def get_traces_by_level(self, level: DiagnosticLevel, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get traces by diagnostic level.
+        
+        Args:
+            level: Diagnostic level
+            limit: Maximum number of traces to return
+            
+        Returns:
+            List of trace items
+        """
+        # Get traces with specified level
+        trace_ids = [trace["trace_id"] for trace in self.traces 
+                  if trace.get("level") == level.value][-limit:]
+        
+        # Get trace items
+        return [self.get_trace(trace_id) for trace_id in trace_ids if trace_id in self.trace_index]
+    
+    def get_shell_traces(self, shell_pattern: Optional[ShellPattern] = None, 
+                      limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get shell pattern traces.
+        
+        Args:
+            shell_pattern: Optional specific shell pattern
+            limit: Maximum number of traces to return
+            
+        Returns:
+            List of trace items
+        """
+        if shell_pattern:
+            # Get traces with specified shell pattern
+            trace_ids = []
+            for trace in self.traces:
+                if "shell_patterns" in trace and shell_pattern.value in trace["shell_patterns"]:
+                    trace_ids.append(trace["trace_id"])
+            
+            # Take last 'limit' traces
+            trace_ids = trace_ids[-limit:]
+        else:
+            # Get all shell traces
+            trace_ids = self.shell_traces[-limit:]
+        
+        # Get trace items
+        return [self.get_trace(trace_id) for trace_id in trace_ids if trace_id in self.trace_index]
+    
+    def get_trace_stats(self) -> Dict[str, Any]:
+        """
+        Get trace statistics.
+        
+        Returns:
+            Trace statistics
+        """
+        # Add shell pattern stats
+        shell_pattern_stats = {}
+        for shell_pattern in ShellPattern:
+            count = sum(1 for trace in self.traces 
+                     if "shell_patterns" in trace and shell_pattern.value in trace["shell_patterns"])
+            
+            shell_pattern_stats[shell_pattern.value] = count
+        
+        # Add to stats
+        stats = {
+            **self.stats,
+            "shell_patterns": shell_pattern_stats,
+        }
+        
+        return stats
+    
+    def clear_traces(self) -> int:
+        """
+        Clear all traces.
+        
+        Returns:
+            Number of traces cleared
+        """
+        trace_count = len(self.traces)
+        
+        # Clear traces
+        self.traces = []
+        self.trace_index = {}
+        self.signal_traces = []
+        self.reasoning_traces = []
+        self.collapse_traces = []
+        self.shell_traces = []
+        
+        # Reset stats
+        self.stats = {
+            "total_traces": 0,
+            "signal_traces": 0,
+            "reasoning_traces": 0,
+            "collapse_traces": 0,
+            "shell_traces": 0,
+            "warnings": 0,
+            "errors": 0,
+        }
+        
+        return trace_count
+    
+    def _detect_shell_patterns(self, trace_type: str, content: Dict[str, Any]) -> List[str]:
+        """
+        Detect shell patterns in trace content.
+        
+        Args:
+            trace_type: Trace type
+            content: Trace content
+            
+        Returns:
+            List of detected shell patterns
+        """
+        detected_patterns = []
+        
+        # Convert content to string for pattern matching
+        content_str = json.dumps(content, ensure_ascii=False).lower()
+        
+        # Check each shell pattern
+        for shell_pattern, pattern_rules in self.shell_patterns.items():
+            pattern = pattern_rules["pattern"]
+            
+            # Check if pattern matches
+            if re.search(pattern, content_str, re.IGNORECASE):
+                # Add additional checks based on pattern type
+                if self._validate_pattern_rules(shell_pattern, pattern_rules, content):
+                    detected_patterns.append(shell_pattern.value)
+        
+        return detected_patterns
+    
+    def _validate_pattern_rules(self, shell_pattern: ShellPattern, 
+                             pattern_rules: Dict[str, Any], 
+                             content: Dict[str, Any]) -> bool:
+        """
+        Validate additional pattern rules.
+        
+        Args:
+            shell_pattern: Shell pattern
+            pattern_rules: Pattern rules
+            content: Trace content
+            
+        Returns:
+            True if pattern rules are validated
+        """
+        # Pattern-specific validation
+        if shell_pattern == ShellPattern.NULL_FEATURE:
+            # Check confidence threshold
+            if "confidence" in content and content["confidence"] < pattern_rules["confidence_threshold"]:
+                return True
+            
+            # Check belief gap
+            if "belief_state" in content:
+                belief_values = list(content["belief_state"].values())
+                if belief_values and max(belief_values) - min(belief_values) > pattern_rules["belief_gap_threshold"]:
+                    return True
+        
+        elif shell_pattern == ShellPattern.CIRCUIT_FRAGMENT:
+            # Check for broken steps
+            if "steps" in content:
+                steps = content["steps"]
+                for i in range(len(steps) - 1):
+                    if steps[i].get("completed", True) and not steps[i+1].get("completed", True):
+                        return True
+            
+            # Check for attribution breaks
+            if "attribution" in content and content["attribution"].get("attribution_breaks", False):
+                return True
+        
+        elif shell_pattern == ShellPattern.META_FAILURE:
+            # Check recursion depth
+            if "depth" in content and content["depth"] >= pattern_rules["recursion_depth_threshold"]:
+                return True
+            
+            # Check for meta-level errors
+            if "errors" in content and any("meta" in error.get("message", "").lower() for error in content["errors"]):
+                return True
+        
+        elif shell_pattern == ShellPattern.RECURSIVE_FRACTURE:
+            # Check for circular reasoning
+            if "steps" in content:
+                steps = content["steps"]
+                step_names = [step.get("name", "") for step in steps]
+                
+                # Look for repeating patterns
+                for pattern_len in range(2, len(step_names) // 2 + 1):
+                    for i in range(len(step_names) - pattern_len * 2 + 1):
+                        pattern = step_names[i:i+pattern_len]
+                        next_seq = step_names[i+pattern_len:i+pattern_len*2]
+                        
+                        if pattern == next_seq:
+                            return True
+        
+        elif shell_pattern == ShellPattern.RESIDUAL_ALIGNMENT_DRIFT:
+            # Check drift magnitude
+            if "drift_vector" in content:
+                drift_values = list(content["drift_vector"].values())
+                if drift_values and any(abs(val) > pattern_rules["drift_magnitude_threshold"] for val in drift_values):
+                    return True
+            
+            # Check for explicit drift detection
+            if "drift_detected" in content and content["drift_detected"]:
+                return True
+        
+        # Default validation for other patterns
+        return True
+    
+    def _save_trace_to_file(self, trace_item: Dict[str, Any]) -> None:
+        """
+        Save trace to file.
+        
+        Args:
+            trace_item: Trace item
+        """
+        if not self.trace_dir:
+            return
+        
+        try:
+            # Create filename based on trace ID and type
+            trace_id = trace_item["trace_id"]
+            trace_type = trace_item["trace_type"]
+            filename = f"{trace_type}_{trace_id}.json"
+            filepath = os.path.join(self.trace_dir, filename)
+            
+            # Save trace to file
+            with open(filepath, "w") as f:
+                json.dump(trace_item, f, indent=2)
+        except Exception as e:
+            logging.error(f"Error saving trace to file: {e}")
+            logging.error(traceback.format_exc())
+    
+    def generate_trace_visualization(self, trace_id: str) -> Dict[str, Any]:
+        """
+        Generate visualization data for a trace.
+        
+        Args:
+            trace_id: Trace ID
+            
+        Returns:
+            Visualization data
+        """
+        trace = self.get_trace(trace_id)
+        if not trace:
+            return {"error": "Trace not found"}
+        
+        trace_type = trace["trace_type"]
+        
+        if trace_type == "signal":
+            return self._generate_signal_visualization(trace)
+        elif trace_type == "reasoning":
+            return self._generate_reasoning_visualization(trace)
+        elif trace_type == "collapse":
+            return self._generate_collapse_visualization(trace)
+        elif trace_type == "shell":
+            return self._generate_shell_visualization(trace)
+        else:
+            return {
+                "trace_id": trace_id,
+                "agent_name": trace["agent_name"],
+                "trace_type": trace_type,
+                "timestamp": trace["timestamp"],
+                "content": trace["content"],
+            }
+    
+    def _generate_signal_visualization(self, trace: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Generate visualization data for a signal trace.
+        
+        Args:
+            trace: Signal trace
+            
+        Returns:
+            Visualization data
+        """
+        content = trace["content"]
+        
+        # Create signal visualization
+        visualization = {
+            "trace_id": trace["trace_id"],
+            "agent_name": trace["agent_name"],
+            "trace_type": "signal",
+            "timestamp": trace["timestamp"],
+            "signal_data": {
+                "ticker": content.get("ticker", ""),
+                "action": content.get("action", ""),
+                "confidence": content.get("confidence", 0),
+            },
+        }
+        
+        # Add attribution if available
+        if "attribution_trace" in content:
+            visualization["attribution"] = content["attribution_trace"]
+        
+        # Add shell patterns if available
+        if "shell_patterns" in trace:
+            visualization["shell_patterns"] = trace["shell_patterns"]
+        
+        return visualization
+    
+    def _generate_reasoning_visualization(self, trace: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Generate visualization data for a reasoning trace.
+        
+        Args:
+            trace: Reasoning trace
+            
+        Returns:
+            Visualization data
+        """
+        content = trace["content"]
+        
+        # Create nodes and links
+        nodes = []
+        links = []
+        
+        # Add reasoning steps as nodes
+        if "steps" in content:
+            for i, step in enumerate(content["steps"]):
+                node_id = f"step_{i}"
+                nodes.append({
+                    "id": node_id,
+                    "label": step.get("name", f"Step {i}"),
+                    "type": "step",
+                    "completed": step.get("completed", True),
+                    "error": "error" in step,
+                })
+                
+                # Add link to previous step
+                if i > 0:
+                    links.append({
+                        "source": f"step_{i-1}",
+                        "target": node_id,
+                        "type": "flow",
+                    })
+        
+        # Create reasoning visualization
+        visualization = {
+            "trace_id": trace["trace_id"],
+            "agent_name": trace["agent_name"],
+            "trace_type": "reasoning",
+            "timestamp": trace["timestamp"],
+            "reasoning_data": {
+                "depth": content.get("depth", 0),
+                "confidence": content.get("confidence", 0),
+                "collapse_detected": content.get("collapse_detected", False),
+            },
+            "nodes": nodes,
+            "links": links,
+        }
+        
+        # Add shell patterns if available
+        if "shell_patterns" in trace:
+            visualization["shell_patterns"] = trace["shell_patterns"]
+        
+        return visualization
+    
+    def _generate_collapse_visualization(self, trace: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Generate visualization data for a collapse trace.
+        
+        Args:
+            trace: Collapse trace
+            
+        Returns:
+            Visualization data
+        """
+        content = trace["content"]
+        
+        # Create collapse visualization
+        visualization = {
+            "trace_id": trace["trace_id"],
+            "agent_name": trace["agent_name"],
+            "trace_type": "collapse",
+            "timestamp": trace["timestamp"],
+            "collapse_data": {
+                "collapse_type": content.get("collapse_type", ""),
+                "collapse_reason": content.get("collapse_reason", ""),
+                "details": content.get("details", {}),
+            },
+        }
+        
+        # Add shell patterns if available
+        if "shell_patterns" in trace:
+            visualization["shell_patterns"] = trace["shell_patterns"]
+        
+        return visualization
+    
+    def _generate_shell_visualization(self, trace: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Generate visualization data for a shell trace.
+        
+        Args:
+            trace: Shell trace
+            
+        Returns:
+            Visualization data
+        """
+        content = trace["content"]
+        
+        # Create shell visualization
+        visualization = {
+            "trace_id": trace["trace_id"],
+            "agent_name": trace["agent_name"],
+            "trace_type": "shell",
+            "timestamp": trace["timestamp"],
+            "shell_data": {
+                "shell_pattern": content.get("shell_pattern", ""),
+                "content": content.get("content", {}),
+            },
+        }
+        
+        return visualization
+    
+    def generate_attribution_report(self, signals: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Generate attribution report for signals.
+        
+        Args:
+            signals: List of signals
+            
+        Returns:
+            Attribution report
+        """
+        # Initialize report
+        report = {
+            "agent_name": self.agent_name,
+            "timestamp": datetime.datetime.now().isoformat(),
+            "signals": len(signals),
+            "attribution_summary": {},
+            "confidence_summary": {},
+            "top_factors": [],
+            "shell_patterns": [],
+        }
+        
+        # Skip if no signals
+        if not signals:
+            return report
+        
+        # Collect attribution data
+        attribution_data = defaultdict(float)
+        confidence_data = []
+        
+        for signal in signals:
+            # Add confidence
+            confidence = signal.get("confidence", 0)
+            confidence_data.append(confidence)
+            
+            # Add attribution
+            attribution = signal.get("attribution_trace", {})
+            for source, weight in attribution.items():
+                attribution_data[source] += weight
+        
+        # Calculate attribution summary
+        total_attribution = sum(attribution_data.values())
+        if total_attribution > 0:
+            for source, weight in attribution_data.items():
+                report["attribution_summary"][source] = weight / total_attribution
+        
+        # Calculate confidence summary
+        report["confidence_summary"] = {
+            "mean": np.mean(confidence_data) if confidence_data else 0,
+            "median": np.median(confidence_data) if confidence_data else 0,
+            "min": min(confidence_data) if confidence_data else 0,
+            "max": max(confidence_data) if confidence_data else 0,
+        }
+        
+        # Calculate top factors
+        top_factors = sorted(attribution_data.items(), key=lambda x: x[1], reverse=True)[:5]
+        report["top_factors"] = [{"source": source, "weight": weight} for source, weight in top_factors]
+        
+        # Collect shell patterns
+        shell_pattern_counts = defaultdict(int)
+        
+        for signal in signals:
+            signal_id = signal.get("signal_id", "")
+            if signal_id:
+                # Check if we have a trace for this signal
+                for trace in self.traces:
+                    if trace["trace_type"] == "signal" and trace["content"].get("signal_id") == signal_id:
+                        # Add shell patterns
+                        if "shell_patterns" in trace:
+                            for pattern in trace["shell_patterns"]:
+                                shell_pattern_counts[pattern] += 1
+        
+        # Add shell patterns to report
+        for pattern, count in shell_pattern_counts.items():
+            report["shell_patterns"].append({
+                "pattern": pattern,
+                "count": count,
+                "frequency": count / len(signals),
+            })
+        
+        return report
+
+
+class ShellDiagnostics:
+    """
+    Shell-based diagnostic tools for deeper interpretability.
+    
+    The ShellDiagnostics provides:
+    - Shell pattern detection and analysis
+    - Failure mode simulation and detection
+    - Attribution shell tracing
+    - Recursive shell embedding
+    """
+    
+    def __init__(
+        self,
+        agent_id: str,
+        agent_name: str,
+        tracing_tools: TracingTools,
+    ):
+        """
+        Initialize shell diagnostics.
+        
+        Args:
+            agent_id: Agent ID
+            agent_name: Agent name
+            tracing_tools: Tracing tools instance
+        """
+        self.agent_id = agent_id
+        self.agent_name = agent_name
+        self.tracer = tracing_tools
+        
+        # Shell state
+        self.active_shells = {}
+        self.shell_history = []
+        
+        # Initialize shell registry
+        self.shell_registry = {}
+        for shell_pattern in ShellPattern:
+            self.shell_registry[shell_pattern.value] = {
+                "pattern": shell_pattern,
+                "active": False,
+                "activation_count": 0,
+                "last_activation": None,
+            }
+    
+    def activate_shell(self, shell_pattern: ShellPattern, context: Dict[str, Any]) -> str:
+        """
+        Activate a shell pattern.
+        
+        Args:
+            shell_pattern: Shell pattern to activate
+            context: Activation context
+            
+        Returns:
+            Shell instance ID
+        """
+        shell_id = str(uuid.uuid4())
+        timestamp = datetime.datetime.now()
+        
+        # Create shell instance
+        shell_instance = {
+            "shell_id": shell_id,
+            "pattern": shell_pattern.value,
+            "context": context,
+            "active": True,
+            "activation_time": timestamp.isoformat(),
+            "deactivation_time": None,
+        }
+        
+        # Update shell registry
+        self.shell_registry[shell_pattern.value]["active"] = True
+        self.shell_registry[shell_pattern.value]["activation_count"] += 1
+        self.shell_registry[shell_pattern.value]["last_activation"] = timestamp.isoformat()
+        
+        # Add to active shells
+        self.active_shells[shell_id] = shell_instance
+        
+        # Record trace
+        self.tracer.record_shell_trace(shell_pattern, {
+            "shell_id": shell_id,
+            "activation_context": context,
+            "timestamp": timestamp.isoformat(),
+        })
+        
+        return shell_id
+    
+    def deactivate_shell(self, shell_id: str, results: Dict[str, Any]) -> bool:
+        """
+        Deactivate a shell pattern.
+        
+        Args:
+            shell_id: Shell instance ID
+            results: Shell results
+            
+        Returns:
+            True if shell was deactivated, False if not found
+        """
+        if shell_id not in self.active_shells:
+            return False
+        
+        # Get shell instance
+        shell_instance = self.active_shells[shell_id]
+        timestamp = datetime.datetime.now()
+        
+        # Update shell instance
+        shell_instance["active"] = False
+        shell_instance["deactivation_time"] = timestamp.isoformat()
+        shell_instance["results"] = results
+        
+        # Update shell registry
+        pattern = shell_instance["pattern"]
+        self.shell_registry[pattern]["active"] = any(
+            instance["pattern"] == pattern and instance["active"]
+            for instance in self.active_shells.values()
+        )
+        
+        # Add to shell history
+        self.shell_history.append(shell_instance)
+        
+        # Remove from active shells
+        del self.active_shells[shell_id]
+        
+        # Record trace
+        self.tracer.record_shell_trace(ShellPattern(pattern), {
+            "shell_id": shell_id,
+            "deactivation_results": results,
+            "timestamp": timestamp.isoformat(),
+        })
+        
+        return True
+    
+    def get_active_shells(self) -> List[Dict[str, Any]]:
+        """
+        Get active shell instances.
+        
+        Returns:
+            List of active shell instances
+        """
+        return list(self.active_shells.values())
+    
+    def get_shell_history(self, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get shell history.
+        
+        Args:
+            limit: Maximum number of shell instances to return
+            
+        Returns:
+            List of shell instances
+        """
+        return self.shell_history[-limit:]
+    
+    def get_shell_registry(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Get shell registry.
+        
+        Returns:
+            Shell registry
+        """
+        return self.shell_registry
+    
+    def simulate_shell_failure(self, shell_pattern: ShellPattern, 
+                           context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Simulate a shell failure.
+        
+        Args:
+            shell_pattern: Shell pattern to simulate
+            context: Simulation context
+            
+        Returns:
+            Simulation results
+        """
+        # Create shell instance
+        shell_id = self.activate_shell(shell_pattern, context)
+        
+        # Simulate failure based on shell pattern
+        if shell_pattern == ShellPattern.NULL_FEATURE:
+            # Knowledge gap simulation
+            results = self._simulate_null_feature(context)
+        elif shell_pattern == ShellPattern.CIRCUIT_FRAGMENT:
+            # Broken reasoning path simulation
+            results = self._simulate_circuit_fragment(context)
+        elif shell_pattern == ShellPattern.META_FAILURE:
+            # Metacognitive failure simulation
+            results = self._simulate_meta_failure(context)
+        elif shell_pattern == ShellPattern.RECURSIVE_FRACTURE:
+            # Circular reasoning simulation
+            results = self._simulate_recursive_fracture(context)
+        elif shell_pattern == ShellPattern.ETHICAL_INVERSION:
+            # Value inversion simulation
+            results = self._simulate_ethical_inversion(context)
+        else:
+            # Default simulation
+            results = {
+                "shell_id": shell_id,
+                "pattern": shell_pattern.value,
+                "simulation": "default",
+                "result": "simulated_failure",
+                "timestamp": datetime.datetime.now().isoformat(),
+            }
+        
+        # Deactivate shell
+        self.deactivate_shell(shell_id, results)
+        
+        return results
+    
+    def _simulate_null_feature(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Simulate NULL_FEATURE shell failure.
+        
+        Args:
+            context: Simulation context
+            
+        Returns:
+            Simulation results
+        """
+        # Extract relevant fields
+        query = context.get("query", "")
+        confidence = context.get("confidence", 0.5)
+        
+        # Reduce confidence for knowledge gap
+        adjusted_confidence = confidence * 0.5
+        
+        # Create null zone markers
+        null_zones = []
+        if "subject" in context:
+            null_zones.append(context["subject"])
+        else:
+            # Extract potential null zones from query
+            words = query.split()
+            for i in range(0, len(words), 3):
+                chunk = " ".join(words[i:i+3])
+                null_zones.append(chunk)
+        
+        # Create detection result
+        result = {
+            "pattern": ShellPattern.NULL_FEATURE.value,
+            "simulation": "knowledge_gap",
+            "original_confidence": confidence,
+            "adjusted_confidence": adjusted_confidence,
+            "null_zones": null_zones,
+            "boundary_detected": True,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return result
+    
+    def _simulate_circuit_fragment(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Simulate CIRCUIT_FRAGMENT shell failure.
+        
+        Args:
+            context: Simulation context
+            
+        Returns:
+            Simulation results
+        """
+        # Extract relevant fields
+        steps = context.get("steps", [])
+        
+        # Create broken steps
+        broken_steps = []
+        
+        if steps:
+            # Create breaks in existing steps
+            for i, step in enumerate(steps):
+                if i % 3 == 2:  # Break every third step
+                    broken_steps.append({
+                        "step_id": step.get("id", f"step_{i}"),
+                        "step_name": step.get("name", f"Step {i}"),
+                        "broken": True,
+                        "cause": "attribution_break",
+                    })
+        else:
+            # Create synthetic steps and breaks
+            for i in range(5):
+                if i % 3 == 2:  # Break every third step
+                    broken_steps.append({
+                        "step_id": f"step_{i}",
+                        "step_name": f"Reasoning Step {i}",
+                        "broken": True,
+                        "cause": "attribution_break",
+                    })
+        
+        # Create detection result
+        result = {
+            "pattern": ShellPattern.CIRCUIT_FRAGMENT.value,
+            "simulation": "broken_reasoning",
+            "broken_steps": broken_steps,
+            "attribution_breaks": len(broken_steps),
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return result
+    
+    def _simulate_meta_failure(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Simulate META_FAILURE shell failure.
+        
+        Args:
+            context: Simulation context
+            
+        Returns:
+            Simulation results
+        """
+        # Extract relevant fields
+        depth = context.get("depth", 0)
+        
+        # Increase depth for recursion
+        adjusted_depth = depth + 3
+        
+        # Create meta errors
+        meta_errors = [
+            {
+                "error_id": str(uuid.uuid4()),
+                "message": "Recursive meta-cognitive loop detected",
+                "depth": adjusted_depth,
+                "cause": "self_reference",
+            },
+            {
+                "error_id": str(uuid.uuid4()),
+                "message": "Meta-reflection limit reached",
+                "depth": adjusted_depth,
+                "cause": "recursion_depth",
+            },
+        ]
+        
+        # Create detection result
+        result = {
+            "pattern": ShellPattern.META_FAILURE.value,
+            "simulation": "meta_recursion",
+            "original_depth": depth,
+            "adjusted_depth": adjusted_depth,
+            "meta_errors": meta_errors,
+            "recursion_detected": True,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return result
+    
+    def _simulate_recursive_fracture(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Simulate RECURSIVE_FRACTURE shell failure.
+        
+        Args:
+            context: Simulation context
+            
+        Returns:
+            Simulation results
+        """
+        # Extract relevant fields
+        steps = context.get("steps", [])
+        
+        # Create circular reasoning pattern
+        circular_pattern = []
+        
+        if steps and len(steps) >= 4:
+            # Use existing steps to create a loop
+            loop_start = len(steps) // 2
+            circular_pattern = [
+                {
+                    "step_id": steps[i].get("id", f"step_{i}"),
+                    "step_name": steps[i].get("name", f"Step {i}"),
+                }
+                for i in range(loop_start, min(loop_start + 3, len(steps)))
+            ]
+            
+            # Add repeat of first step to close the loop
+            circular_pattern.append({
+                "step_id": steps[loop_start].get("id", f"step_{loop_start}"),
+                "step_name": steps[loop_start].get("name", f"Step {loop_start}"),
+            })
+        else:
+            # Create synthetic circular pattern
+            for i in range(3):
+                circular_pattern.append({
+                    "step_id": f"loop_step_{i}",
+                    "step_name": f"Loop Step {i}",
+                })
+            
+            # Add repeat of first step to close the loop
+            circular_pattern.append({
+                "step_id": "loop_step_0",
+                "step_name": "Loop Step 0",
+            })
+        
+        # Create detection result
+        result = {
+            "pattern": ShellPattern.RECURSIVE_FRACTURE.value,
+            "simulation": "circular_reasoning",
+            "circular_pattern": circular_pattern,
+            "loop_length": len(circular_pattern) - 1,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return result
+    
+    def _simulate_ethical_inversion(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Simulate ETHICAL_INVERSION shell failure.
+        
+        Args:
+            context: Simulation context
+            
+        Returns:
+            Simulation results
+        """
+        # Extract relevant fields
+        values = context.get("values", {})
+        
+        # Create value inversions
+        value_inversions = []
+        
+        if values:
+            # Create inversions for existing values
+            for value, polarity in values.items():
+                if isinstance(polarity, (int, float)) and polarity > 0:
+                    value_inversions.append({
+                        "value": value,
+                        "original_polarity": polarity,
+                        "inverted_polarity": -polarity,
+                        "cause": "value_conflict",
+                    })
+        else:
+            # Create synthetic value inversions
+            default_values = {
+                "fairness": 0.8,
+                "transparency": 0.9,
+                "innovation": 0.7,
+                "efficiency": 0.8,
+            }
+            
+            for value, polarity in default_values.items():
+                value_inversions.append({
+                    "value": value,
+                    "original_polarity": polarity,
+                    "inverted_polarity": -polarity,
+                    "cause": "value_conflict",
+                })
+        
+        # Create detection result
+        result = {
+            "pattern": ShellPattern.ETHICAL_INVERSION.value,
+            "simulation": "value_inversion",
+            "value_inversions": value_inversions,
+            "inversion_count": len(value_inversions),
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return result
+
+
+class ShellFailureMap:
+    """
+    Shell failure mapping and visualization.
+    
+    The ShellFailureMap provides:
+    - Visualization of shell pattern failures
+    - Mapping of failures across agents
+    - Temporal analysis of failures
+    - Failure pattern detection
+    """
+    
+    def __init__(self):
+        """Initialize shell failure map."""
+        self.failure_map = {}
+        self.agent_failures = defaultdict(list)
+        self.pattern_failures = defaultdict(list)
+        self.temporal_failures = []
+    
+    def add_failure(self, agent_id: str, agent_name: str, 
+                 shell_pattern: ShellPattern, failure_data: Dict[str, Any]) -> str:
+        """
+        Add a shell failure to the map.
+        
+        Args:
+            agent_id: Agent ID
+            agent_name: Agent name
+            shell_pattern: Shell pattern
+            failure_data: Failure data
+            
+        Returns:
+            Failure ID
+        """
+        # Create failure ID
+        failure_id = str(uuid.uuid4())
+        timestamp = datetime.datetime.now()
+        
+        # Create failure item
+        failure_item = {
+            "failure_id": failure_id,
+            "agent_id": agent_id,
+            "agent_name": agent_name,
+            "pattern": shell_pattern.value,
+            "data": failure_data,
+            "timestamp": timestamp.isoformat(),
+        }
+        
+        # Add to failure map
+        self.failure_map[failure_id] = failure_item
+        
+        # Add to agent failures
+        self.agent_failures[agent_id].append(failure_id)
+        
+        # Add to pattern failures
+        self.pattern_failures[shell_pattern.value].append(failure_id)
+        
+        # Add to temporal failures
+        self.temporal_failures.append((timestamp, failure_id))
+        
+        return failure_id
+    
+    def get_failure(self, failure_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get failure by ID.
+        
+        Args:
+            failure_id: Failure ID
+            
+        Returns:
+            Failure item or None if not found
+        """
+        return self.failure_map.get(failure_id)
+    
+    def get_agent_failures(self, agent_id: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get failures for an agent.
+        
+        Args:
+            agent_id: Agent ID
+            limit: Maximum number of failures to return
+            
+        Returns:
+            List of failure items
+        """
+        failure_ids = self.agent_failures.get(agent_id, [])[-limit:]
+        return [self.get_failure(failure_id) for failure_id in failure_ids if failure_id in self.failure_map]
+    
+    def get_pattern_failures(self, pattern: ShellPattern, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get failures for a pattern.
+        
+        Args:
+            pattern: Shell pattern
+            limit: Maximum number of failures to return
+            
+        Returns:
+            List of failure items
+        """
+        failure_ids = self.pattern_failures.get(pattern.value, [])[-limit:]
+        return [self.get_failure(failure_id) for failure_id in failure_ids if failure_id in self.failure_map]
+    
+    def get_temporal_failures(self, start_time: Optional[datetime.datetime] = None, 
+                           end_time: Optional[datetime.datetime] = None, 
+                           limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get failures in a time range.
+        
+        Args:
+            start_time: Start time (None for no start)
+            end_time: End time (None for no end)
+            limit: Maximum number of failures to return
+            
+        Returns:
+            List of failure items
+        """
+        # Filter by time range
+        filtered_failures = []
+        for timestamp, failure_id in self.temporal_failures:
+            if start_time and timestamp < start_time:
+                continue
+            if end_time and timestamp > end_time:
+                continue
+            filtered_failures.append((timestamp, failure_id))
+        
+        # Take last 'limit' failures
+        filtered_failures = filtered_failures[-limit:]
+        
+        # Get failure items
+        return [self.get_failure(failure_id) for _, failure_id in filtered_failures 
+             if failure_id in self.failure_map]
+    
+    def get_failure_stats(self) -> Dict[str, Any]:
+        """
+        Get failure statistics.
+        
+        Returns:
+            Failure statistics
+        """
+        # Count failures by agent
+        agent_counts = {agent_id: len(failures) for agent_id, failures in self.agent_failures.items()}
+        
+        # Count failures by pattern
+        pattern_counts = {pattern: len(failures) for pattern, failures in self.pattern_failures.items()}
+        
+        # Count failures by time period
+        now = datetime.datetime.now()
+        hour_ago = now - datetime.timedelta(hours=1)
+        day_ago = now - datetime.timedelta(days=1)
+        week_ago = now - datetime.timedelta(weeks=1)
+        
+        time_counts = {
+            "last_hour": sum(1 for timestamp, _ in self.temporal_failures if timestamp >= hour_ago),
+            "last_day": sum(1 for timestamp, _ in self.temporal_failures if timestamp >= day_ago),
+            "last_week": sum(1 for timestamp, _ in self.temporal_failures if timestamp >= week_ago),
+            "total": len(self.temporal_failures),
+        }
+        
+        # Create stats
+        stats = {
+            "agent_counts": agent_counts,
+            "pattern_counts": pattern_counts,
+            "time_counts": time_counts,
+            "total_failures": len(self.failure_map),
+            "timestamp": now.isoformat(),
+        }
+        
+        return stats
+    
+    def generate_failure_map_visualization(self) -> Dict[str, Any]:
+        """
+        Generate visualization data for failure map.
+        
+        Returns:
+            Visualization data
+        """
+        # Create nodes and links
+        nodes = []
+        links = []
+        
+        # Add agent nodes
+        agent_nodes = {}
+        for agent_id, failures in self.agent_failures.items():
+            # Get first failure to get agent name
+            first_failure = self.get_failure(failures[0]) if failures else None
+            agent_name = first_failure.get("agent_name", "Unknown") if first_failure else "Unknown"
+            
+            # Create agent node
+            agent_node = {
+                "id": agent_id,
+                "label": agent_name,
+                "type": "agent",
+                "size": 15,
+                "failure_count": len(failures),
+            }
+            
+            nodes.append(agent_node)
+            agent_nodes[agent_id] = agent_node
+        
+        # Add pattern nodes
+        pattern_nodes = {}
+        for pattern, failures in self.pattern_failures.items():
+            # Create pattern node
+            pattern_node = {
+                "id": pattern,
+                "label": pattern,
+                "type": "pattern",
+                "size": 10,
+                "failure_count": len(failures),
+            }
+            
+            nodes.append(pattern_node)
+            pattern_nodes[pattern] = pattern_node
+        
+        # Add failure nodes and links
+        for failure_id, failure in self.failure_map.items():
+            agent_id = failure.get("agent_id")
+            pattern = failure.get("pattern")
+            
+            # Create failure node
+            failure_node = {
+                "id": failure_id,
+                "label": f"Failure {failure_id[:6]}",
+                "type": "failure",
+                "size": 5,
+                "timestamp": failure.get("timestamp"),
+            }
+            
+            nodes.append(failure_node)
+            
+            # Add links
+            if agent_id:
+                links.append({
+                    "source": agent_id,
+                    "target": failure_id,
+                    "type": "agent_failure",
+                })
+            
+            if pattern:
+                links.append({
+                    "source": pattern,
+                    "target": failure_id,
+                    "type": "pattern_failure",
+                })
+        
+        # Create visualization
+        visualization = {
+            "nodes": nodes,
+            "links": links,
+            "timestamp": datetime.datetime.now().isoformat(),
+        }
+        
+        return visualization
+
+
+# Utility functions for diagnostics
+def format_diagnostic_output(trace_data: Dict[str, Any], format: str = "text") -> str:
+    """
+    Format diagnostic output for display.
+    
+    Args:
+        trace_data: Trace data
+        format: Output format (text, json, markdown)
+        
+    Returns:
+        Formatted output
+    """
+    if format == "json":
+        return json.dumps(trace_data, indent=2)
+    
+    elif format == "markdown":
+        # Create markdown output
+        output = f"# Diagnostic Trace\n\n"
+        
+        # Add trace info
+        output += f"**Trace ID:** {trace_data.get('trace_id', 'N/A')}\n"
+        output += f"**Agent:** {trace_data.get('agent_name', 'N/A')}\n"
+        output += f"**Type:** {trace_data.get('trace_type', 'N/A')}\n"
+        output += f"**Time:** {trace_data.get('timestamp', 'N/A')}\n\n"
+        
+        # Add shell patterns if available
+        if "shell_patterns" in trace_data:
+            output += f"**Shell Patterns:**\n\n"
+            for pattern in trace_data["shell_patterns"]:
+                output += f"- {pattern}\n"
+            output += "\n"
+        
+        # Add content based on trace type
+        if trace_data.get("trace_type") == "signal":
+            output += f"## Signal Details\n\n"
+            content = trace_data.get("content", {})
+            output += f"**Ticker:** {content.get('ticker', 'N/A')}\n"
+            output += f"**Action:** {content.get('action', 'N/A')}\n"
+            output += f"**Confidence:** {content.get('confidence', 'N/A')}\n"
+            output += f"**Reasoning:** {content.get('reasoning', 'N/A')}\n\n"
+            
+            # Add attribution if available
+            if "attribution_trace" in content:
+                output += f"## Attribution\n\n"
+                output += "| Source | Weight |\n"
+                output += "| ------ | ------ |\n"
+                for source, weight in content.get("attribution_trace", {}).items():
+                    output += f"| {source} | {weight:.2f} |\n"
+        
+        elif trace_data.get("trace_type") == "reasoning":
+            output += f"## Reasoning Details\n\n"
+            content = trace_data.get("content", {})
+            output += f"**Depth:** {content.get('depth', 'N/A')}\n"
+            output += f"**Confidence:** {content.get('confidence', 'N/A')}\n"
+            output += f"**Collapse Detected:** {content.get('collapse_detected', False)}\n\n"
+            
+            # Add steps if available
+            if "steps" in content:
+                output += f"## Reasoning Steps\n\n"
+                for i, step in enumerate(content["steps"]):
+                    output += f"### Step {i+1}: {step.get('name', 'Unnamed')}\n"
+                    output += f"**Completed:** {step.get('completed', True)}\n"
+                    if "error" in step:
+                        output += f"**Error:** {step['error'].get('message', 'Unknown error')}\n"
+                    output += "\n"
+        
+        elif trace_data.get("trace_type") == "collapse":
+            output += f"## Collapse Details\n\n"
+            content = trace_data.get("content", {})
+            output += f"**Type:** {content.get('collapse_type', 'N/A')}\n"
+            output += f"**Reason:** {content.get('collapse_reason', 'N/A')}\n\n"
+            
+            # Add details if available
+            if "details" in content:
+                output += f"## Collapse Details\n\n"
+                details = content["details"]
+                for key, value in details.items():
+                    output += f"**{key}:** {value}\n"
+        
+        elif trace_data.get("trace_type") == "shell":
+            output += f"## Shell Details\n\n"
+            content = trace_data.get("content", {})
+            output += f"**Shell Pattern:** {content.get('shell_pattern', 'N/A')}\n\n"
+            
+            # Add content details
+            shell_content = content.get("content", {})
+            output += f"## Shell Content\n\n"
+            for key, value in shell_content.items():
+                output += f"**{key}:** {value}\n"
+        
+        return output
+    
+    else:  # text format (default)
+        # Create text output
+        output = "==== Diagnostic Trace ====\n\n"
+        
+        # Add trace info
+        output += f"Trace ID: {trace_data.get('trace_id', 'N/A')}\n"
+        output += f"Agent: {trace_data.get('agent_name', 'N/A')}\n"
+        output += f"Type: {trace_data.get('trace_type', 'N/A')}\n"
+        output += f"Time: {trace_data.get('timestamp', 'N/A')}\n\n"
+        
+        # Add shell patterns if available
+        if "shell_patterns" in trace_data:
+            output += f"Shell Patterns:\n"
+            for pattern in trace_data["shell_patterns"]:
+                output += f"- {pattern}\n"
+            output += "\n"
+        
+        # Add content based on trace type
+        content = trace_data.get("content", {})
+        output += f"---- Content ----\n\n"
+        
+        # Format content recursively
+        def format_dict(d, indent=0):
+            result = ""
+            for key, value in d.items():
+                if isinstance(value, dict):
+                    result += f"{'  ' * indent}{key}:\n"
+                    result += format_dict(value, indent + 1)
+                elif isinstance(value, list):
+                    result += f"{'  ' * indent}{key}:\n"
+                    for item in value:
+                        if isinstance(item, dict):
+                            result += format_dict(item, indent + 1)
+                        else:
+                            result += f"{'  ' * (indent + 1)}- {item}\n"
+                else:
+                    result += f"{'  ' * indent}{key}: {value}\n"
+            return result
+        
+        output += format_dict(content)
+        
+        return output
+
+
+def get_shell_pattern_description(pattern: ShellPattern) -> str:
+    """
+    Get description for a shell pattern.
+    
+    Args:
+        pattern: Shell pattern
+        
+    Returns:
+        Shell pattern description
+    """
+    descriptions = {
+        ShellPattern.NULL_FEATURE: "Knowledge gaps as null attribution zones",
+        ShellPattern.CIRCUIT_FRAGMENT: "Broken reasoning paths in attribution chains",
+        ShellPattern.META_FAILURE: "Metacognitive attribution failures",
+        ShellPattern.GHOST_FRAME: "Residual agent identity markers",
+        ShellPattern.ECHO_ATTRIBUTION: "Causal chain backpropagation",
+        ShellPattern.ATTRIBUTION_REFLECT: "Multi-head contribution analysis",
+        ShellPattern.INVERSE_CHAIN: "Attribution-output mismatch",
+        ShellPattern.RECURSIVE_FRACTURE: "Circular attribution loops",
+        ShellPattern.ETHICAL_INVERSION: "Value polarity reversals",
+        ShellPattern.RESIDUAL_ALIGNMENT_DRIFT: "Direction of belief evolution",
+    }
+    
+    return descriptions.get(pattern, "Unknown shell pattern")