add aplication file

Dockerfile

@@ -0,0 +1,33 @@
+# syntax=docker/dockerfile:1
+
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONPATH=/app \
+    PORT=8000
+
+# Runtime libs for scientific stack (e.g., scikit-learn)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python dependencies first for better layer caching
+COPY requirements.txt /app/requirements.txt
+RUN pip install --upgrade pip setuptools wheel && \
+    pip install -r /app/requirements.txt
+
+# Copy application source
+COPY src /app/src
+
+# Use a non-root user
+RUN useradd -m -u 10001 appuser && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 8000
+
+# GEMINI_API_KEY must be provided at runtime
+CMD ["sh", "-c", "uvicorn src.app:app --host 0.0.0.0 --port ${PORT}"] 

README.md

@@ -1,11 +1,327 @@
----
-title: Zico Agent
-emoji: 📚
-colorFrom: gray
-colorTo: purple
-sdk: docker
-pinned: false
-short_description: PanoramaZico
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Zico Multi-Agent System
+
+A sophisticated multi-agent system built with LangGraph, FastAPI, and Google's Gemini AI for intelligent conversation routing and specialized task handling.
+
+## 🚀 Features
+
+- **Multi-Agent Architecture**: Intelligent routing between specialized agents
+- **LangGraph Integration**: Stateful conversation flows with proper state management
+- **Real-time Crypto Data**: Live cryptocurrency price and market data
+- **Conversation Management**: Persistent conversation state and history
+- **Performance Monitoring**: Agent performance metrics and analytics
+- **RESTful API**: Clean FastAPI endpoints for easy integration
+- **Extensible Design**: Easy to add new agents and capabilities
+
+## 🏗️ Architecture
+
+### Core Components
+
+1. **Supervisor Agent**: Routes messages to appropriate specialized agents
+2. **Crypto Data Agent**: Handles cryptocurrency-related queries
+3. **General Agent**: Manages general conversation and queries
+4. **Conversation Manager**: Manages conversation state and persistence
+5. **Agent Registry**: Central registry for all agents in the system
+
+### LangGraph Flow
+
+```
+User Message → Supervisor → Route Decision → Specialized Agent → Response
+     ↓              ↓              ↓              ↓              ↓
+Conversation → Context → State → Processing → Agent Response
+```
+
+## 📦 Installation
+
+1. **Clone the repository**
+```bash
+git clone <repository-url>
+cd new_zico
+```
+
+2. **Create virtual environment**
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+```
+
+3. **Install dependencies**
+```bash
+pip install -r requirements.txt
+```
+
+4. **Set up environment variables**
+```bash
+cp .env.example .env
+# Edit .env and add your GEMINI_API_KEY
+```
+
+5. **Run the application**
+```bash
+python -m uvicorn src.app:app --reload --host 0.0.0.0 --port 8000
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```env
+GEMINI_API_KEY=your_gemini_api_key_here
+GEMINI_MODEL=gemini-1.5-pro
+GEMINI_EMBEDDING_MODEL=models/embedding-001
+```
+
+### Agent Configuration
+
+Agents can be configured in `src/agents/config.py`:
+
+```python
+AGENTS_CONFIG = {
+    "agents": [
+        {
+            "name": "crypto_data",
+            "description": "Handles cryptocurrency-related queries",
+            "type": "specialized",
+            "enabled": True,
+            "priority": 1
+        },
+        {
+            "name": "general",
+            "description": "Handles general conversation and queries",
+            "type": "general",
+            "enabled": True,
+            "priority": 2
+        }
+    ]
+}
+```
+
+## 📡 API Usage
+
+### Chat Endpoint
+
+```bash
+curl -X POST "http://localhost:8000/chat" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "What is the price of Bitcoin?",
+    "user_id": "user123",
+    "conversation_id": "conv456"
+  }'
+```
+
+**Response:**
+```json
+{
+  "response": "The current price of Bitcoin is $43,250.50",
+  "agent_name": "crypto_agent",
+  "agent_type": "crypto_data",
+  "conversation_id": "conv456",
+  "message_id": "msg789",
+  "metadata": {
+    "price_source": "CoinGecko",
+    "timestamp": "2024-01-15T10:30:00Z"
+  },
+  "next_agent": null,
+  "requires_followup": false,
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+### Conversation Management
+
+```bash
+# Get all conversations for a user
+GET /conversations/{user_id}
+
+# Get messages from a specific conversation
+GET /conversations/{user_id}/{conversation_id}/messages
+
+# Delete a conversation
+DELETE /conversations/{user_id}/{conversation_id}
+
+# Reset a conversation (clear messages)
+POST /conversations/{user_id}/reset
+```
+
+## 🤖 Adding New Agents
+
+### 1. Create Agent Class
+
+```python
+# src/agents/my_agent/agent.py
+from src.agents.base_agent import BaseAgent
+from src.models.chatMessage import AgentType, AgentResponse
+
+class MyAgent(BaseAgent):
+    def __init__(self, llm):
+        super().__init__(
+            name="my_agent",
+            agent_type=AgentType.SPECIALIZED,
+            llm=llm,
+            description="Handles specific tasks"
+        )
+    
+    async def process_message(self, message: str, context: Dict[str, Any] = None) -> AgentResponse:
+        # Your agent logic here
+        response_content = "Processed by MyAgent"
+        return self.create_agent_response(response_content)
+    
+    def get_capabilities(self) -> List[str]:
+        return ["task1", "task2", "task3"]
+    
+    def can_handle(self, message: str, context: Dict[str, Any] = None) -> bool:
+        # Define when this agent should handle messages
+        return "my_keyword" in message.lower()
+    
+    def get_confidence_score(self, message: str, context: Dict[str, Any] = None) -> float:
+        # Return confidence score (0.0 to 1.0)
+        if "my_keyword" in message.lower():
+            return 0.9
+        return 0.1
+```
+
+### 2. Register Agent
+
+```python
+# In your supervisor or main application
+from src.agents.my_agent.agent import MyAgent
+from src.agents.base_agent import agent_registry
+
+my_agent = MyAgent(llm)
+agent_registry.register_agent(my_agent)
+```
+
+### 3. Update Supervisor Routing
+
+Add routing logic in the supervisor's `_route_to_agent` method:
+
+```python
+def _route_to_agent(self, state: ConversationState) -> str:
+    # ... existing logic ...
+    
+    # Add your agent routing
+    if "my_keyword" in content:
+        return "my_agent"
+    
+    # ... rest of logic ...
+```
+
+## 📊 Monitoring and Analytics
+
+### Agent Performance
+
+```bash
+# Get performance metrics for all agents
+GET /agents/performance
+
+# Get specific agent info
+GET /agents/{agent_name}/info
+```
+
+### Conversation Analytics
+
+```bash
+# Get conversation statistics
+GET /conversations/{user_id}/stats
+
+# Export conversation data
+GET /conversations/{user_id}/{conversation_id}/export
+```
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src
+
+# Run specific test file
+pytest tests/test_supervisor.py
+```
+
+## 🚀 Production Deployment
+
+### Docker Deployment
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY . .
+EXPOSE 8000
+
+CMD ["uvicorn", "src.app:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+### Environment Setup
+
+For production, consider:
+
+1. **Database**: Use PostgreSQL or MongoDB for conversation persistence
+2. **Caching**: Redis for session management and caching
+3. **Monitoring**: Prometheus + Grafana for metrics
+4. **Logging**: Structured logging with ELK stack
+5. **Security**: API keys, rate limiting, CORS configuration
+
+## 🔍 Debugging
+
+### Enable Debug Logging
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+### LangGraph Visualization
+
+```python
+# Visualize the conversation flow
+from langgraph.graph import StateGraph
+graph = supervisor.supervisor_graph
+graph.get_graph().draw_mermaid()
+```
+
+## 📈 Performance Optimization
+
+1. **Agent Caching**: Cache agent responses for similar queries
+2. **Context Window**: Limit context messages to prevent token overflow
+3. **Async Processing**: Use background tasks for non-critical operations
+4. **Connection Pooling**: Reuse LLM connections
+5. **Response Streaming**: Stream responses for long-running operations
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🆘 Support
+
+For support and questions:
+
+- Create an issue in the repository
+- Check the documentation
+- Review the test examples
+
+## 🔮 Roadmap
+
+- [ ] Add more specialized agents (research, analysis, etc.)
+- [ ] Implement agent learning and adaptation
+- [ ] Add support for file uploads and document processing
+- [ ] Implement real-time collaboration features
+- [ ] Add advanced analytics and reporting
+- [ ] Support for multiple LLM providers
+- [ ] Mobile app integration 

requirements.txt

@@ -0,0 +1,62 @@
+python-dotenv==1.0.0
+google-generativeai>=0.8.0
+langchain-google-genai>=2.0.0
+langchain-core>=0.2.43
+fastapi==0.109.2
+uvicorn==0.27.1
+pydantic>=2.7.4
+python-multipart==0.0.9
+
+# LangGraph and multi-agent dependencies
+langgraph>=0.2.70
+langgraph-supervisor>=0.0.1
+langchain>=0.2.0
+langchain-community>=0.2.0
+
+
+# Testing dependencies
+pytest==8.0.0
+pytest-cov==4.1.0
+pytest-asyncio==0.23.5
+
+# Additional dependencies
+scikit-learn==1.4.0
+numpy>=1.24.0
+pandas>=2.0.0
+
+# Monitoring and logging
+structlog>=23.0.0
+prometheus-client>=0.17.0
+langsmith>=0.1.0
+
+# Database (optional for production)
+sqlalchemy>=2.0.0
+alembic>=1.12.0
+
+# Caching
+redis>=5.0.0
+
+# HTTP client
+httpx>=0.25.0
+requests>=2.31.0
+
+# Data validation and serialization
+marshmallow>=3.20.0
+jsonschema>=4.19.0
+
+# Async support
+asyncio-mqtt>=0.16.0
+aiofiles>=23.0.0
+
+# Security
+cryptography>=41.0.0
+passlib>=1.7.4
+
+# Development tools
+black>=23.0.0
+flake8>=6.0.0
+mypy>=1.5.0
+
+# ClickHouse dependencies
+clickhouse-connect>=0.7.0
+clickhouse-sqlalchemy==0.3.2

src/agents/base_agent.py

@@ -0,0 +1,238 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional
+import logging
+from datetime import datetime
+
+from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
+from langchain_core.language_models import BaseLanguageModel
+
+from src.models.chatMessage import ChatMessage, AgentResponse, AgentType, MessageRole
+from src.agents.config import Config
+
+
+class BaseAgent(ABC):
+    """Base class for all agents in the multi-agent system"""
+    
+    def __init__(self, name: str, agent_type: AgentType, llm: BaseLanguageModel, description: str = ""):
+        self.name = name
+        self.agent_type = agent_type
+        self.llm = llm
+        self.description = description
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+        
+        # Agent state
+        self.is_active = True
+        self.created_at = datetime.utcnow()
+        self.last_used = None
+        self.usage_count = 0
+        
+        # Performance metrics
+        self.response_times = []
+        self.success_count = 0
+        self.error_count = 0
+        
+        self.logger.info(f"Initialized agent {name} of type {agent_type}")
+    
+    @abstractmethod
+    async def process_message(self, message: str, context: Dict[str, Any] = None) -> AgentResponse:
+        """Process a message and return a response"""
+        pass
+    
+    @abstractmethod
+    def get_capabilities(self) -> List[str]:
+        """Return list of agent capabilities"""
+        pass
+    
+    def can_handle(self, message: str, context: Dict[str, Any] = None) -> bool:
+        """Determine if this agent can handle the given message"""
+        # Default implementation - can be overridden by subclasses
+        return True
+    
+    def get_confidence_score(self, message: str, context: Dict[str, Any] = None) -> float:
+        """Get confidence score for handling this message (0.0 to 1.0)"""
+        # Default implementation - can be overridden by subclasses
+        return 0.5
+    
+    def prepare_context_messages(self, context: Dict[str, Any] = None) -> List[SystemMessage]:
+        """Prepare context messages for the LLM"""
+        context_messages = []
+        
+        if context:
+            # Add relevant context information
+            if context.get("crypto_related"):
+                context_messages.append(SystemMessage(
+                    content="This conversation involves cryptocurrency-related topics."
+                ))
+            
+            if context.get("user_preferences"):
+                context_messages.append(SystemMessage(
+                    content=f"User preferences: {context['user_preferences']}"
+                ))
+            
+            if context.get("conversation_history"):
+                context_messages.append(SystemMessage(
+                    content=f"Previous context: {context['conversation_history']}"
+                ))
+        
+        return context_messages
+    
+    def create_agent_response(
+        self, 
+        content: str, 
+        success: bool = True, 
+        error_message: Optional[str] = None,
+        metadata: Dict[str, Any] = None,
+        tools_used: List[str] = None,
+        next_agent: Optional[str] = None,
+        requires_followup: bool = False
+    ) -> AgentResponse:
+        """Create a standardized agent response"""
+        return AgentResponse(
+            content=content,
+            agent_name=self.name,
+            agent_type=self.agent_type,
+            success=success,
+            error_message=error_message,
+            metadata=metadata or {},
+            tools_used=tools_used or [],
+            next_agent=next_agent,
+            requires_followup=requires_followup,
+            timestamp=datetime.utcnow()
+        )
+    
+    def update_metrics(self, response_time: float, success: bool):
+        """Update agent performance metrics"""
+        self.response_times.append(response_time)
+        self.last_used = datetime.utcnow()
+        self.usage_count += 1
+        
+        if success:
+            self.success_count += 1
+        else:
+            self.error_count += 1
+        
+        # Keep only last 100 response times
+        if len(self.response_times) > 100:
+            self.response_times = self.response_times[-100:]
+    
+    def get_performance_metrics(self) -> Dict[str, Any]:
+        """Get agent performance metrics"""
+        avg_response_time = sum(self.response_times) / len(self.response_times) if self.response_times else 0
+        success_rate = self.success_count / self.usage_count if self.usage_count > 0 else 0
+        
+        return {
+            "name": self.name,
+            "agent_type": self.agent_type.value,
+            "usage_count": self.usage_count,
+            "success_count": self.success_count,
+            "error_count": self.error_count,
+            "success_rate": success_rate,
+            "average_response_time": avg_response_time,
+            "last_used": self.last_used.isoformat() if self.last_used else None,
+            "is_active": self.is_active
+        }
+    
+    def activate(self):
+        """Activate the agent"""
+        self.is_active = True
+        self.logger.info(f"Agent {self.name} activated")
+    
+    def deactivate(self):
+        """Deactivate the agent"""
+        self.is_active = False
+        self.logger.info(f"Agent {self.name} deactivated")
+    
+    def reset_metrics(self):
+        """Reset performance metrics"""
+        self.response_times = []
+        self.success_count = 0
+        self.error_count = 0
+        self.usage_count = 0
+        self.logger.info(f"Reset metrics for agent {self.name}")
+    
+    def get_agent_info(self) -> Dict[str, Any]:
+        """Get comprehensive agent information"""
+        return {
+            "name": self.name,
+            "type": self.agent_type.value,
+            "description": self.description,
+            "capabilities": self.get_capabilities(),
+            "is_active": self.is_active,
+            "created_at": self.created_at.isoformat(),
+            "last_used": self.last_used.isoformat() if self.last_used else None,
+            "performance_metrics": self.get_performance_metrics()
+        }
+
+
+class AgentRegistry:
+    """Registry for managing all agents in the system"""
+    
+    def __init__(self):
+        self.agents: Dict[str, BaseAgent] = {}
+        self.logger = logging.getLogger(__name__)
+    
+    def register_agent(self, agent: BaseAgent) -> None:
+        """Register an agent"""
+        if agent.name in self.agents:
+            self.logger.warning(f"Agent {agent.name} already registered, overwriting")
+        
+        self.agents[agent.name] = agent
+        self.logger.info(f"Registered agent {agent.name}")
+    
+    def unregister_agent(self, agent_name: str) -> bool:
+        """Unregister an agent"""
+        if agent_name in self.agents:
+            del self.agents[agent_name]
+            self.logger.info(f"Unregistered agent {agent_name}")
+            return True
+        return False
+    
+    def get_agent(self, agent_name: str) -> Optional[BaseAgent]:
+        """Get agent by name"""
+        return self.agents.get(agent_name)
+    
+    def get_active_agents(self) -> List[BaseAgent]:
+        """Get all active agents"""
+        return [agent for agent in self.agents.values() if agent.is_active]
+    
+    def get_agents_by_type(self, agent_type: AgentType) -> List[BaseAgent]:
+        """Get agents by type"""
+        return [agent for agent in self.agents.values() if agent.agent_type == agent_type]
+    
+    def find_best_agent(self, message: str, context: Dict[str, Any] = None) -> Optional[BaseAgent]:
+        """Find the best agent to handle a message"""
+        best_agent = None
+        best_score = 0.0
+        
+        for agent in self.get_active_agents():
+            if agent.can_handle(message, context):
+                confidence = agent.get_confidence_score(message, context)
+                if confidence > best_score:
+                    best_score = confidence
+                    best_agent = agent
+        
+        return best_agent
+    
+    def get_all_agents_info(self) -> List[Dict[str, Any]]:
+        """Get information about all agents"""
+        return [agent.get_agent_info() for agent in self.agents.values()]
+    
+    def get_agent_performance_summary(self) -> Dict[str, Any]:
+        """Get performance summary for all agents"""
+        total_agents = len(self.agents)
+        active_agents = len(self.get_active_agents())
+        total_usage = sum(agent.usage_count for agent in self.agents.values())
+        total_success = sum(agent.success_count for agent in self.agents.values())
+        
+        return {
+            "total_agents": total_agents,
+            "active_agents": active_agents,
+            "total_usage": total_usage,
+            "total_success": total_success,
+            "overall_success_rate": total_success / total_usage if total_usage > 0 else 0,
+            "agents": self.get_all_agents_info()
+        }
+
+
+# Global agent registry
+agent_registry = AgentRegistry() 

src/agents/config.py

@@ -0,0 +1,111 @@
+import os
+from dotenv import load_dotenv
+from langchain_google_genai import ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings
+from typing import Optional
+
+load_dotenv()
+
+gemini_api_key = os.getenv("GEMINI_API_KEY")
+if not gemini_api_key:
+    raise ValueError("GEMINI_API_KEY não encontrada nas variáveis de ambiente")
+
+class Config:
+    # Model configuration
+    GEMINI_MODEL = "gemini-1.5-pro"
+    GEMINI_EMBEDDING_MODEL = "models/embedding-001"
+    GEMINI_API_KEY = gemini_api_key
+    
+    # Application configuration
+    MAX_UPLOAD_LENGTH = 16 * 1024 * 1024
+    MAX_CONVERSATION_LENGTH = 100  # Maximum messages per conversation
+    MAX_CONTEXT_MESSAGES = 10  # Maximum messages to include in context
+    
+    # Agent configuration
+    AGENTS_CONFIG = {
+        "agents": [
+            {
+                "name": "crypto_data",
+                "description": "Handles cryptocurrency-related queries",
+                "type": "specialized",
+                "enabled": True,
+                "priority": 1
+            },
+            {
+                "name": "general",
+                "description": "Handles general conversation and queries",
+                "type": "general",
+                "enabled": True,
+                "priority": 2
+            }
+        ]
+    }
+    
+    # LangGraph configuration
+    LANGGRAPH_CONFIG = {
+        "max_iterations": 10,
+        "timeout": 30,
+        "memory_window": 10,
+        "enable_memory": True
+    }
+    
+    # Conversation configuration
+    CONVERSATION_CONFIG = {
+        "default_user_id": "anonymous",
+        "max_conversations_per_user": 50,
+        "conversation_timeout_hours": 24,
+        "enable_context_extraction": True
+    }
+    
+    # LLM instances (singleton pattern)
+    _llm_instance: Optional[ChatGoogleGenerativeAI] = None
+    _embeddings_instance: Optional[GoogleGenerativeAIEmbeddings] = None
+    
+    @classmethod
+    def get_llm(cls) -> ChatGoogleGenerativeAI:
+        """Get or create LLM instance (singleton)"""
+        if cls._llm_instance is None:
+            cls._llm_instance = ChatGoogleGenerativeAI(
+                model=cls.GEMINI_MODEL,
+                temperature=0.7,
+                google_api_key=cls.GEMINI_API_KEY
+            )
+        return cls._llm_instance
+    
+    @classmethod
+    def get_embeddings(cls) -> GoogleGenerativeAIEmbeddings:
+        """Get or create embeddings instance (singleton)"""
+        if cls._embeddings_instance is None:
+            cls._embeddings_instance = GoogleGenerativeAIEmbeddings(
+                model=cls.GEMINI_EMBEDDING_MODEL,
+                google_api_key=cls.GEMINI_API_KEY
+            )
+        return cls._embeddings_instance
+    
+    @classmethod
+    def get_agent_config(cls, agent_name: str) -> Optional[dict]:
+        """Get configuration for a specific agent"""
+        for agent in cls.AGENTS_CONFIG["agents"]:
+            if agent["name"] == agent_name:
+                return agent
+        return None
+    
+    @classmethod
+    def get_enabled_agents(cls) -> list:
+        """Get list of enabled agents"""
+        return [
+            agent for agent in cls.AGENTS_CONFIG["agents"] 
+            if agent.get("enabled", True)
+        ]
+    
+    @classmethod
+    def validate_config(cls) -> bool:
+        """Validate configuration"""
+        try:
+            # Test LLM connection
+            llm = cls.get_llm()
+            # Test embeddings connection
+            embeddings = cls.get_embeddings()
+            return True
+        except Exception as e:
+            print(f"Configuration validation failed: {e}")
+            return False

src/agents/conversation_manager.py

@@ -0,0 +1,275 @@
+import logging
+import uuid
+from typing import Dict, List, Optional, Any
+from datetime import datetime, timedelta
+from dataclasses import dataclass, asdict
+import json
+
+from src.models.chatMessage import ConversationState, ChatMessage, MessageRole, AgentType
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ConversationMetadata:
+    """Metadata for conversation tracking"""
+    conversation_id: str
+    user_id: str
+    created_at: datetime
+    updated_at: datetime
+    message_count: int
+    current_agent: Optional[str]
+    is_active: bool
+    context_summary: Dict[str, Any]
+
+
+class ConversationManager:
+    """Manages conversation state and persistence for multi-agent system"""
+    
+    def __init__(self):
+        self.conversations: Dict[str, ConversationState] = {}
+        self.metadata: Dict[str, ConversationMetadata] = {}
+        self.user_conversations: Dict[str, List[str]] = {}
+        
+    def create_conversation(self, user_id: str, conversation_id: Optional[str] = None) -> str:
+        """Create a new conversation"""
+        if not conversation_id:
+            conversation_id = str(uuid.uuid4())
+        
+        key = f"{user_id}:{conversation_id}"
+        
+        # Create conversation state
+        conversation_state = ConversationState(
+            conversation_id=conversation_id,
+            user_id=user_id,
+            messages=[],
+            context={},
+            memory={},
+            agent_history=[],
+            current_agent=None,
+            last_message_id=None,
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow(),
+            is_active=True
+        )
+        
+        # Create metadata
+        metadata = ConversationMetadata(
+            conversation_id=conversation_id,
+            user_id=user_id,
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow(),
+            message_count=0,
+            current_agent=None,
+            is_active=True,
+            context_summary={}
+        )
+        
+        # Store conversation
+        self.conversations[key] = conversation_state
+        self.metadata[key] = metadata
+        
+        # Update user conversations
+        if user_id not in self.user_conversations:
+            self.user_conversations[user_id] = []
+        self.user_conversations[user_id].append(conversation_id)
+        
+        logger.info(f"Created conversation {conversation_id} for user {user_id}")
+        return conversation_id
+    
+    def get_conversation(self, conversation_id: str, user_id: str) -> Optional[ConversationState]:
+        """Get conversation by ID and user"""
+        key = f"{user_id}:{conversation_id}"
+        return self.conversations.get(key)
+    
+    def get_or_create_conversation(self, conversation_id: str, user_id: str) -> ConversationState:
+        """Get existing conversation or create new one"""
+        conversation = self.get_conversation(conversation_id, user_id)
+        if not conversation:
+            self.create_conversation(user_id, conversation_id)
+            conversation = self.get_conversation(conversation_id, user_id)
+        return conversation
+    
+    def add_message(self, conversation_id: str, user_id: str, message: ChatMessage) -> None:
+        """Add message to conversation"""
+        conversation = self.get_or_create_conversation(conversation_id, user_id)
+        key = f"{user_id}:{conversation_id}"
+        
+        # Add message
+        conversation.messages.append(message)
+        conversation.last_message_id = message.message_id
+        conversation.updated_at = datetime.utcnow()
+        
+        # Update metadata
+        if key in self.metadata:
+            self.metadata[key].message_count = len(conversation.messages)
+            self.metadata[key].updated_at = datetime.utcnow()
+            self.metadata[key].current_agent = conversation.current_agent
+        
+        logger.info(f"Added message to conversation {conversation_id}")
+    
+    def update_conversation_context(self, conversation_id: str, user_id: str, context_updates: Dict[str, Any]) -> None:
+        """Update conversation context"""
+        conversation = self.get_conversation(conversation_id, user_id)
+        if conversation:
+            conversation.context.update(context_updates)
+            conversation.updated_at = datetime.utcnow()
+            
+            # Update metadata
+            key = f"{user_id}:{conversation_id}"
+            if key in self.metadata:
+                self.metadata[key].context_summary.update(context_updates)
+                self.metadata[key].updated_at = datetime.utcnow()
+    
+    def update_agent_history(self, conversation_id: str, user_id: str, agent_info: Dict[str, Any]) -> None:
+        """Update agent interaction history"""
+        conversation = self.get_conversation(conversation_id, user_id)
+        if conversation:
+            conversation.agent_history.append(agent_info)
+            conversation.updated_at = datetime.utcnow()
+    
+    def get_conversation_messages(self, conversation_id: str, user_id: str, limit: Optional[int] = None) -> List[ChatMessage]:
+        """Get messages from conversation"""
+        conversation = self.get_conversation(conversation_id, user_id)
+        if not conversation:
+            return []
+        
+        messages = conversation.messages
+        if limit:
+            messages = messages[-limit:]
+        
+        return messages
+    
+    def get_user_conversations(self, user_id: str) -> List[Dict[str, Any]]:
+        """Get all conversations for a user"""
+        user_conversations = []
+        
+        for conversation_id in self.user_conversations.get(user_id, []):
+            key = f"{user_id}:{conversation_id}"
+            metadata = self.metadata.get(key)
+            
+            if metadata:
+                user_conversations.append(asdict(metadata))
+        
+        return user_conversations
+    
+    def delete_conversation(self, conversation_id: str, user_id: str) -> bool:
+        """Delete a conversation"""
+        key = f"{user_id}:{conversation_id}"
+        
+        if key in self.conversations:
+            del self.conversations[key]
+            
+        if key in self.metadata:
+            del self.metadata[key]
+        
+        # Remove from user conversations
+        if user_id in self.user_conversations:
+            if conversation_id in self.user_conversations[user_id]:
+                self.user_conversations[user_id].remove(conversation_id)
+        
+        logger.info(f"Deleted conversation {conversation_id} for user {user_id}")
+        return True
+    
+    def reset_conversation(self, conversation_id: str, user_id: str) -> None:
+        """Reset conversation (clear messages but keep conversation)"""
+        conversation = self.get_conversation(conversation_id, user_id)
+        if conversation:
+            conversation.messages = []
+            conversation.context = {}
+            conversation.agent_history = []
+            conversation.current_agent = None
+            conversation.last_message_id = None
+            conversation.updated_at = datetime.utcnow()
+            
+            # Update metadata
+            key = f"{user_id}:{conversation_id}"
+            if key in self.metadata:
+                self.metadata[key].message_count = 0
+                self.metadata[key].current_agent = None
+                self.metadata[key].context_summary = {}
+                self.metadata[key].updated_at = datetime.utcnow()
+    
+    def cleanup_old_conversations(self, max_age_hours: int = 24) -> int:
+        """Clean up old conversations"""
+        cutoff_time = datetime.utcnow() - timedelta(hours=max_age_hours)
+        deleted_count = 0
+        
+        conversations_to_delete = []
+        
+        for key, metadata in self.metadata.items():
+            if metadata.updated_at < cutoff_time and not metadata.is_active:
+                conversations_to_delete.append(key)
+        
+        for key in conversations_to_delete:
+            user_id, conversation_id = key.split(":", 1)
+            if self.delete_conversation(conversation_id, user_id):
+                deleted_count += 1
+        
+        logger.info(f"Cleaned up {deleted_count} old conversations")
+        return deleted_count
+    
+    def get_conversation_stats(self, user_id: str) -> Dict[str, Any]:
+        """Get conversation statistics for a user"""
+        user_conversations = self.get_user_conversations(user_id)
+        
+        total_conversations = len(user_conversations)
+        active_conversations = sum(1 for conv in user_conversations if conv["is_active"])
+        total_messages = sum(conv["message_count"] for conv in user_conversations)
+        
+        # Agent usage statistics
+        agent_usage = {}
+        for conv in user_conversations:
+            conversation = self.get_conversation(conv["conversation_id"], user_id)
+            if conversation:
+                for agent_info in conversation.agent_history:
+                    agent_name = agent_info.get("agent", "unknown")
+                    agent_usage[agent_name] = agent_usage.get(agent_name, 0) + 1
+        
+        return {
+            "total_conversations": total_conversations,
+            "active_conversations": active_conversations,
+            "total_messages": total_messages,
+            "agent_usage": agent_usage,
+            "average_messages_per_conversation": total_messages / total_conversations if total_conversations > 0 else 0
+        }
+    
+    def export_conversation(self, conversation_id: str, user_id: str) -> Dict[str, Any]:
+        """Export conversation data"""
+        conversation = self.get_conversation(conversation_id, user_id)
+        if not conversation:
+            return {}
+        
+        return {
+            "conversation_id": conversation_id,
+            "user_id": user_id,
+            "messages": [msg.dict() for msg in conversation.messages],
+            "context": conversation.context,
+            "agent_history": conversation.agent_history,
+            "metadata": asdict(self.metadata.get(f"{user_id}:{conversation_id}", {}))
+        }
+    
+    def import_conversation(self, conversation_data: Dict[str, Any]) -> str:
+        """Import conversation data"""
+        conversation_id = conversation_data.get("conversation_id", str(uuid.uuid4()))
+        user_id = conversation_data.get("user_id", "anonymous")
+        
+        # Create conversation
+        self.create_conversation(user_id, conversation_id)
+        
+        # Import messages
+        for msg_data in conversation_data.get("messages", []):
+            message = ChatMessage(**msg_data)
+            self.add_message(conversation_id, user_id, message)
+        
+        # Import context and history
+        conversation = self.get_conversation(conversation_id, user_id)
+        if conversation:
+            conversation.context.update(conversation_data.get("context", {}))
+            conversation.agent_history.extend(conversation_data.get("agent_history", []))
+        
+        return conversation_id
+
+
+# Global conversation manager instance
+conversation_manager = ConversationManager() 

src/agents/crypto_data/agent.py

@@ -0,0 +1,20 @@
+import logging
+from src.agents.crypto_data.tools import get_tools
+from langgraph.prebuilt import create_react_agent
+
+logger = logging.getLogger(__name__)
+
+
+class CryptoDataAgent():
+    """Agent for handling cryptocurrency-related queries and data retrieval."""
+
+    def __init__(self, llm):
+        self.llm = llm
+
+        self.agent = create_react_agent(
+            model=llm,
+            tools=get_tools(),
+            name="crypto_agent"
+        )
+
+

src/agents/crypto_data/config.py

@@ -0,0 +1,17 @@
+class Config:
+
+    # API endpoints
+    COINGECKO_BASE_URL = "https://api.coingecko.com/api/v3"
+    DEFILLAMA_BASE_URL = "https://api.llama.fi"
+    PRICE_SUCCESS_MESSAGE = "The price of {coin_name} is ${price:,}"
+    PRICE_FAILURE_MESSAGE = "Failed to retrieve price. Please enter a valid coin name."
+    FLOOR_PRICE_SUCCESS_MESSAGE = "The floor price of {nft_name} is ${floor_price:,}"
+    FLOOR_PRICE_FAILURE_MESSAGE = "Failed to retrieve floor price. Please enter a valid NFT name."
+    TVL_SUCCESS_MESSAGE = "The TVL of {protocol_name} is ${tvl:,}"
+    TVL_FAILURE_MESSAGE = "Failed to retrieve TVL. Please enter a valid protocol name."
+    FDV_SUCCESS_MESSAGE = "The fully diluted valuation of {coin_name} is ${fdv:,}"
+    FDV_FAILURE_MESSAGE = "Failed to retrieve FDV. Please enter a valid coin name."
+    MARKET_CAP_SUCCESS_MESSAGE = "The market cap of {coin_name} is ${market_cap:,}"
+    MARKET_CAP_FAILURE_MESSAGE = "Failed to retrieve market cap. Please enter a valid coin name."
+    API_ERROR_MESSAGE = "I can't seem to access the API at the moment."
+

src/agents/crypto_data/tools.py

@@ -0,0 +1,436 @@
+import logging
+import requests
+import json
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+from src.agents.crypto_data.config import Config
+from langchain_core.tools import Tool
+from src.agents.metadata import metadata
+
+# -----------------------------------------------------------------------------
+# Module: crypto_data tools
+# -----------------------------------------------------------------------------
+# This module provides helper functions and LangChain Tool wrappers to:
+#  - Fetch cryptocurrency prices, market data, and fully diluted valuation
+#  - Retrieve NFT floor prices
+#  - Query DeFi protocol TVL from DefiLlama
+#  - Perform fuzzy matching on protocol names
+#
+# Usage:
+#   from src.agents.crypto_data.tools import get_tools
+#   tools = get_tools()
+#   agent = create_react_agent(model=llm, tools=tools)
+# -----------------------------------------------------------------------------
+
+
+def get_most_similar(text: str, data: list[str]) -> list[str]:
+    """
+    Find the top entries in `data` most semantically similar to `text`.
+    Uses TF-IDF vectorization + cosine similarity.
+
+    Args:
+        text: The input string to match against.
+        data: A list of candidate strings.
+
+    Returns:
+        A list of candidates where similarity > 0.5 (up to 20 items).
+    """
+    vectorizer = TfidfVectorizer()
+    sentence_vectors = vectorizer.fit_transform(data)
+    text_vector = vectorizer.transform([text])
+
+    # Compute cosine similarity between input and all candidates
+    similarity_scores = cosine_similarity(text_vector, sentence_vectors)
+
+    # Pick top 20 indices, then filter by threshold
+    top_indices = similarity_scores.argsort()[0][-20:]
+    top_matches = [data[i] for i in top_indices if similarity_scores[0][i] > 0.5]
+    return top_matches
+
+
+def get_coingecko_id(text: str, type: str = "coin") -> str | None:
+    """
+    Look up the CoinGecko internal ID for a coin or NFT by name.
+
+    Args:
+        text: Human-readable coin or NFT name or slug.
+        type: Either 'coin' or 'nft'.
+
+    Returns:
+        The CoinGecko ID string, or None if not found.
+
+    Raises:
+        ValueError if `type` is invalid, or propagates request exceptions.
+    """
+    url = f"{Config.COINGECKO_BASE_URL}/search"
+    params = {"query": text}
+    try:
+        response = requests.get(url, params=params)
+        response.raise_for_status()
+        data = response.json()
+
+        if type == "coin":
+            return data["coins"][0]["id"] if data["coins"] else None
+        elif type == "nft":
+            return data.get("nfts", [])[0].get("id") if data.get("nfts") else None
+        else:
+            raise ValueError("Invalid type specified")
+
+    except requests.exceptions.RequestException as e:
+        logging.error(f"API request failed: {e}")
+        raise
+
+
+def get_tradingview_symbol(coingecko_id: str) -> str | None:
+    """
+    Convert a CoinGecko coin ID into a TradingView ticker symbol.
+
+    Args:
+        coingecko_id: The CoinGecko coin ID.
+
+    Returns:
+        A string like 'CRYPTO:BTCUSD', or None if symbol is missing.
+    """
+    url = f"{Config.COINGECKO_BASE_URL}/coins/{coingecko_id}"
+    try:
+        response = requests.get(url)
+        response.raise_for_status()
+        symbol = response.json().get("symbol", "").upper()
+        return f"CRYPTO:{symbol}USD" if symbol else None
+    except requests.exceptions.RequestException as e:
+        logging.error(f"Failed to get TradingView symbol: {e}")
+        raise
+
+
+def get_price(coin: str) -> float | None:
+    """
+    Fetch the current USD price of a cryptocurrency.
+
+    Args:
+        coin: Human-readable coin name (e.g. 'bitcoin').
+
+    Returns:
+        Price in USD as a float, or None if coin not found.
+    """
+    coin_id = get_coingecko_id(coin, type="coin")
+    if not coin_id:
+        return None
+
+    url = f"{Config.COINGECKO_BASE_URL}/simple/price"
+    params = {"ids": coin_id, "vs_currencies": "USD"}
+    try:
+        response = requests.get(url, params=params)
+        response.raise_for_status()
+        return response.json()[coin_id]["usd"]
+    except requests.exceptions.RequestException as e:
+        logging.error(f"Failed to retrieve price: {e}")
+        raise
+
+
+def get_floor_price(nft: str) -> float | None:
+    """
+    Retrieve the floor price in USD for an NFT collection.
+
+    Args:
+        nft: The NFT collection name or slug.
+
+    Returns:
+        Floor price in USD, or None if not found.
+    """
+    nft_id = get_coingecko_id(nft, type="nft")
+    if not nft_id:
+        return None
+
+    url = f"{Config.COINGECKO_BASE_URL}/nfts/{nft_id}"
+    try:
+        response = requests.get(url)
+        response.raise_for_status()
+        return response.json()["floor_price"]["usd"]
+    except requests.exceptions.RequestException as e:
+        logging.error(f"Failed to retrieve floor price: {e}")
+        raise
+
+
+def get_fdv(coin: str) -> float | None:
+    """
+    Get a coin's Fully Diluted Valuation (FDV) in USD from CoinGecko.
+
+    Args:
+        coin: Coin name or slug.
+
+    Returns:
+        FDV in USD, or None if not available.
+    """
+    coin_id = get_coingecko_id(coin, type="coin")
+    if not coin_id:
+        return None
+
+    url = f"{Config.COINGECKO_BASE_URL}/coins/{coin_id}"
+    try:
+        data = requests.get(url).json()
+        return data.get("market_data", {}).get("fully_diluted_valuation", {}).get("usd")
+    except requests.exceptions.RequestException as e:
+        logging.error(f"Failed to retrieve FDV: {e}")
+        raise
+
+
+def get_market_cap(coin: str) -> float | None:
+    """
+    Fetch current market capitalization for a coin via CoinGecko.
+
+    Args:
+        coin: The coin name or slug.
+
+    Returns:
+        Market cap in USD, or None if not found.
+    """
+    coin_id = get_coingecko_id(coin, type="coin")
+    if not coin_id:
+        return None
+
+    url = f"{Config.COINGECKO_BASE_URL}/coins/markets"
+    params = {"ids": coin_id, "vs_currency": "USD"}
+    try:
+        response = requests.get(url, params=params)
+        response.raise_for_status()
+        return response.json()[0]["market_cap"]
+    except requests.exceptions.RequestException as e:
+        logging.error(f"Failed to retrieve market cap: {e}")
+        raise
+
+
+def get_protocols_list() -> tuple[list[str], list[str], list[str]]:
+    """
+    Pull the full list of DeFi protocols from DefiLlama.
+
+    Returns:
+        - slugs: List of protocol slugs (for TVL lookup)
+        - names: Human-readable names
+        - gecko_ids: CoinGecko IDs for integration
+    """
+    url = f"{Config.DEFILLAMA_BASE_URL}/protocols"
+    try:
+        data = requests.get(url).json()
+        slugs = [item["slug"] for item in data]
+        names = [item["name"] for item in data]
+        gecko_ids = [item["gecko_id"] for item in data]
+        return slugs, names, gecko_ids
+    except requests.exceptions.RequestException as e:
+        logging.error(f"Failed to retrieve protocols list: {e}")
+        raise
+
+
+def get_tvl_value(protocol_id: str) -> float:
+    """
+    Query DefiLlama for a single protocol's TVL.
+
+    Args:
+        protocol_id: The slug identifier for the protocol.
+
+    Returns:
+        TVL value (could be a dict or number depending on API).
+    """
+    url = f"{Config.DEFILLAMA_BASE_URL}/chains"
+    try:
+        print(f"URL: {url}")
+        response = requests.get(url)
+        print(f"Response: {response.json()}")
+        response.raise_for_status()
+        chains = response.json()
+        chain = next((c for c in chains if c["name"].lower() == protocol_id.lower()), None)
+        print(f"Chain: {chain}")
+        return chain["tvl"]
+    except requests.exceptions.RequestException as e:
+        logging.error(f"Failed to retrieve protocol TVL: {e}")
+        raise
+
+
+def get_protocol_tvl(protocol_name: str) -> dict[str, float] | None:
+    """
+    Get a protocol's TVL by name, using fuzzy matching if needed.
+
+    1. Try exact match via CoinGecko ID → DefiLlama slug
+    2. If no exact match, find closest names via TF-IDF
+    3. Return the highest TVL among matches
+    """
+    slugs, names, gecko_ids = get_protocols_list()
+    tag = get_coingecko_id(protocol_name)
+    protocol_id = None
+
+    if tag:
+        # map gecko_id to DefiLlama slug
+        protocol_id = next((s for s, g in zip(slugs, gecko_ids) if g == tag), None)
+        if protocol_id:
+            return {tag: get_tvl_value(protocol_id)}
+
+    # fallback: fuzzy text matching on protocol names
+    matches = get_most_similar(protocol_name, names)
+    if not matches:
+        return None
+
+    # fetch TVL for each matched name, pick the highest
+    results = []
+    for name in matches:
+        pid = next(s for s, n in zip(slugs, names) if n == name)
+        tvl = get_tvl_value(pid)
+        results.append({pid: tvl})
+
+    return max(results, key=lambda d: next(iter(d.values())))
+
+
+# -----------------------------------------------------------------------------
+# Tool wrappers: these catch errors, format responses, and produce strings
+# -----------------------------------------------------------------------------
+
+def _append_coin_metadata_suffix(text: str, coin_name: str) -> str:
+    """
+    Append a structured metadata sentinel to a human-friendly text response.
+    Includes CoinGecko coinId and uppercased symbol when available.
+    """
+    try:
+        coin_id = get_coingecko_id(coin_name, type="coin")
+        if not coin_id:
+            return text
+        tv_symbol = get_tradingview_symbol(coin_id)
+        symbol = None
+        if tv_symbol and tv_symbol.startswith("CRYPTO:") and tv_symbol.endswith("USD"):
+            symbol = tv_symbol[len("CRYPTO:"):-3]
+        meta = {"coinId": coin_id}
+        if symbol:
+            meta["symbol"] = symbol
+        response = f"{text} ||META: {json.dumps(meta)}||"
+        return response
+    except Exception:
+        # Never break user-visible responses due to metadata failures
+        return text
+
+
+def get_coin_price_tool(coin_name: str) -> dict:
+    """ 
+    LangChain Tool: Return a user-friendly string with the coin's USD price.
+    """
+    try:
+        price = get_price(coin_name)
+        if price is None:
+            return Config.PRICE_FAILURE_MESSAGE
+        text = Config.PRICE_SUCCESS_MESSAGE.format(coin_name=coin_name, price=price)
+        # compute metadata out-of-band
+        meta = {}
+        try:
+            coin_id = get_coingecko_id(coin_name, type="coin")
+            if coin_id:
+                tv_symbol = get_tradingview_symbol(coin_id)
+                meta["coinId"] = tv_symbol # return the symbol as the coinId
+                metadata.set_crypto_data_agent(meta)
+        except Exception:
+            pass
+
+        return {"text": text, "metadata": meta}
+    except requests.exceptions.RequestException:
+        return {"text": Config.API_ERROR_MESSAGE, "metadata": {}}
+
+
+def get_nft_floor_price_tool(nft_name: str) -> str:
+    """
+    LangChain Tool: Return a user-friendly string with the NFT floor price.
+    """
+    try:
+        floor_price = get_floor_price(nft_name)
+        if floor_price is None:
+            return Config.FLOOR_PRICE_FAILURE_MESSAGE
+        return Config.FLOOR_PRICE_SUCCESS_MESSAGE.format(nft_name=nft_name, floor_price=floor_price)
+    except requests.exceptions.RequestException:
+        return Config.API_ERROR_MESSAGE
+
+
+def get_protocol_total_value_locked_tool(protocol_name: str) -> str:
+    """
+    LangChain Tool: Return formatted TVL information for a DeFi protocol.
+    """
+    try:
+        tvl = get_protocol_tvl(protocol_name)
+        if tvl is None:
+            return Config.TVL_FAILURE_MESSAGE
+        tag, tvl_value = next(iter(tvl.items()))
+        return Config.TVL_SUCCESS_MESSAGE.format(protocol_name=protocol_name, tvl=tvl_value)
+    except requests.exceptions.RequestException:
+        return Config.API_ERROR_MESSAGE
+
+
+def get_fully_diluted_valuation_tool(coin_name: str) -> str:
+    """
+    LangChain Tool: Return a formatted string with the coin's FDV.
+    """
+    try:
+        fdv = get_fdv(coin_name)
+        if fdv is None:
+            return Config.FDV_FAILURE_MESSAGE
+        text = Config.FDV_SUCCESS_MESSAGE.format(coin_name=coin_name, fdv=fdv)
+        return _append_coin_metadata_suffix(text, coin_name)
+    except requests.exceptions.RequestException:
+        return Config.API_ERROR_MESSAGE
+
+
+def get_coin_market_cap_tool(coin_name: str) -> str:
+    """
+    LangChain Tool: Return a formatted string with the coin's market cap.
+    """
+    try:
+        market_cap = get_market_cap(coin_name)
+        if market_cap is None:
+            return Config.MARKET_CAP_FAILURE_MESSAGE
+        text = Config.MARKET_CAP_SUCCESS_MESSAGE.format(coin_name=coin_name, market_cap=market_cap)
+        return _append_coin_metadata_suffix(text, coin_name)
+    except requests.exceptions.RequestException:
+        return Config.API_ERROR_MESSAGE
+
+
+def get_tools() -> list[Tool]:
+    """
+    Build and return the list of LangChain Tools for use in an agent.
+
+    Each Tool wraps one of the user-facing helper functions above.
+    """
+
+    return [
+        Tool(
+            name="get_coin_price",
+            func=get_coin_price_tool,
+            description=(
+                "Use this to get the current USD price of a cryptocurrency. "
+                "Input should be the coin name (e.g. 'bitcoin')."
+            ),
+        ),
+        Tool(
+            name="get_nft_floor_price",
+            func=get_nft_floor_price_tool,
+            description=(
+                "Fetch the floor price of an NFT collection in USD. "
+                "Input should be the NFT name or slug."
+            ),
+        ),
+        Tool(
+            name="get_protocol_tvl",
+            func=get_protocol_total_value_locked_tool,
+            description=(
+                "Returns the Total Value Locked (TVL) of a DeFi protocol. "
+                "Input is the protocol name."
+            ),
+        ),
+        Tool(
+            name="get_fully_diluted_valuation",
+            func=get_fully_diluted_valuation_tool,
+            description=(
+                "Get a coin's fully diluted valuation in USD. "
+                "Input the coin's name."
+            ),
+        ),
+        Tool(
+            name="get_market_cap",
+            func=get_coin_market_cap_tool,
+            description=(
+                "Retrieve the market capitalization of a coin in USD. "
+                "Input is the coin's name."
+            ),
+        ),
+    ]

src/agents/database/agent.py

@@ -0,0 +1,109 @@
+from src.agents.database.tools import get_tools
+from langgraph.prebuilt import create_react_agent
+from langchain_core.prompts import PromptTemplate
+from langchain_core.messages import BaseMessage, SystemMessage, HumanMessage
+from langchain_core.language_models import BaseChatModel
+from langchain_core.runnables import Runnable, RunnableConfig
+from datetime import datetime
+from typing import List, Any
+from src.agents.database.tools import call_tool
+
+SYSTEM_PROMPT = """
+You are a senior data assistant specializing in ClickHouse. Your role is to help users query a database related to the Avalanche (AVAX) blockchain network using natural language.
+
+You should:
+- Interpret user questions.
+- Explore the database using tools (e.g., list_tables, describe_table, sample_table).
+- Strategically decide which tools to call and when.
+- Generate efficient and accurate SQL queries.
+- Summarize and explain the query results in business-friendly language.
+
+## 🧠 STRATEGIC THINKING (BEFORE ACTING)
+- Before calling tools, reason step-by-step.
+- Identify what information is missing.
+- Formulate a plan to investigate the schema or validate assumptions.
+- Only execute SQL after validating the database structure.
+
+## 🔧 TOOL USAGE RULES
+- Always include a clear and thoughtful `reasoning` parameter for every tool call.
+- Ensure all required parameters are included and accurate.
+- Use tools sparingly and with purpose. Avoid unnecessary calls.
+- Do not repeat tool calls. After receiving a response, do not call the same tool again unless the user asks for more information.
+
+## 🗃️ DATABASE CONTEXT
+- All data is related to the Avalanche (AVAX) blockchain.
+- Tables may include smart contracts, transactions, wallet addresses, gas fees, staking, governance, and on-chain activity.
+
+## 📊 OUTPUT FORMAT
+- Always respond in string format.
+- Use bullet points when presenting structured data.
+- If the query involves multiple steps or complex logic, break it down for the user.
+- Assume the user is a **business analyst** or **data scientist** who does **not know SQL**.
+
+## 🎯 GOAL
+Transform a vague user request into:
+1. A strategic plan.
+2. The right tool calls to understand the database.
+3. An optimized SQL query.
+4. A clear, insightful explanation of the results.
+
+Today’s date is {datetime.now().strftime('%Y-%m-%d')}.
+""".strip()
+
+
+class DatabaseAgent(Runnable):
+    """Agent for handling database queries."""
+
+    def __init__(self, llm, max_iterations: int = 10):
+        self.max_iterations = max_iterations
+        self.llm = llm.bind_tools(get_tools())
+        self.name = "database_agent"
+
+    def create_history(self) -> List[BaseMessage]:
+        """Create a history of messages for the agent."""
+        return [
+            SystemMessage(content=SYSTEM_PROMPT),
+        ]
+
+    def invoke(self, input: Any, config: RunnableConfig = None) -> str:
+        try:
+            """Process the input, which can be a dict or a list of messages."""
+            # 🔧 Suporte tanto para dict com chave "messages" quanto para lista direta
+            if isinstance(input, dict) and "messages" in input:
+                user_messages = input["messages"]
+            elif isinstance(input, list):
+                user_messages = input
+            else:
+                raise ValueError("Invalid input format. Expected dict with 'messages' or a list of messages.")
+
+            n_iterations = 0
+            messages = self.create_history() + user_messages  # ✅ inclui o system prompt no histórico
+
+            # initial_response = self.llm.invoke(messages)
+            # return {
+            #     "messages": initial_response,
+            #     "agent": self.name
+            # }
+
+            while n_iterations < self.max_iterations:
+                response = self.llm.invoke(messages)
+                print("response", response)
+                messages.append(response)
+                if not response.tool_calls:
+                    final_response = {
+                        "messages": messages,
+                        "agent": self.name
+                    }
+                    print("DEBUG: final_response", final_response)
+                    return final_response
+                for tool_call in response.tool_calls:
+                    tool_result = call_tool(tool_call)
+                    messages.append(tool_result)
+                n_iterations += 1
+
+            return response.content
+        except Exception as e:
+            print(f"Error in DatabaseAgent: {e}")
+            return "Sorry, an error occurred while processing your request."
+ 
+

src/agents/database/client.py

@@ -0,0 +1,36 @@
+import clickhouse_connect
+from src.agents.database.config import Config
+
+_client = None
+
+def _create_client():
+    return clickhouse_connect.get_client(
+        host=Config.CLICKHOUSE_HOST,
+        port=Config.CLICKHOUSE_PORT,
+        username=Config.CLICKHOUSE_USER,
+        password=Config.CLICKHOUSE_PASSWORD,
+        database=Config.CLICKHOUSE_DATABASE
+    )
+
+def get_client():
+    global _client
+    if _client is None:
+        _client = _create_client()
+    return _client
+
+def try_get_client():
+    try:
+        return get_client()
+    except Exception:
+        return None
+
+def is_database_available() -> bool:
+    try:
+        client = get_client()
+        client.query("SELECT 1")
+        return True
+    except Exception:
+        return False
+
+def execute_query(query: str):
+    return get_client().query(query)

src/agents/database/config.py

@@ -0,0 +1,14 @@
+import os
+
+class Config:
+    # Use clickhouse+http:// for HTTP interface or clickhouse+native:// for native interface
+    CLICKHOUSE_URI = "clickhouse+http://default:@localhost:8123/default"
+    
+    CLICKHOUSE_HOST = 'localhost'
+    CLICKHOUSE_PORT = 8123  # HTTP port
+    CLICKHOUSE_USER = 'default'
+    CLICKHOUSE_PASSWORD = ''
+    CLICKHOUSE_DATABASE = 'default'
+    # Alternative native connection (faster, recommended for production)
+    # CLICKHOUSE_URI = "clickhouse+native://default:@localhost:9000/default"
+    GLACIER_API_KEY = os.getenv("GLACIER_API_KEY")

src/agents/database/tools.py

@@ -0,0 +1,179 @@
+from langchain_core.messages.tool import ToolCall
+from langchain_core.messages import ToolMessage
+from langchain.tools import Tool, tool
+from src.agents.database.client import get_client
+import requests
+from src.agents.database.config import Config
+
+@tool(parse_docstring=True)
+def list_tables(reasoning: str) -> list[str]:
+    """
+    List all tables in the database.
+
+    Args:
+        reasoning: A string with the reasoning for the tool call
+
+    Returns:
+        A list of table names
+    """
+    print("reasoning:", reasoning)
+    client = get_client()
+    result = client.query("SHOW TABLES")
+    response = result.result_rows
+    print("response:", response)
+    return response
+
+@tool(parse_docstring=True)
+def sample_table(reasoning: str, table_name: str) -> str:
+    """
+    Sample the data from a table.
+
+    Args:
+        reasoning: A string with the reasoning for the tool call
+        table_name: The name of the table to sample
+
+    Returns:
+        A string with the sampled data
+    """
+    print("reasoning:", reasoning)
+    client = get_client()
+    result = client.query(f"SELECT * FROM {table_name} LIMIT 10")
+    response = result.result_rows
+    print("response:", response)
+    return response
+
+@tool(parse_docstring=True)
+def describe_table(reasoning: str, table_name: str) -> str:
+    """
+    Describe the schema of a table.
+
+    Args:
+        reasoning: A string with the reasoning for the tool call
+        table_name: The name of the table to describe
+
+    Returns:
+        A string with the schema of the table
+    """
+    print("reasoning:", reasoning)
+    client = get_client()
+    result = client.query(f"DESCRIBE TABLE {table_name}")
+    response = result.result_rows
+    print("response:", response)
+    return response
+
+@tool(parse_docstring=True)
+def execute_sql(reasoning: str, sql: str) -> str:
+    """
+    Execute a SQL query and return the result.
+
+    Args:
+        reasoning: A string with the reasoning for the tool call
+        sql: The SQL query to execute
+
+    Returns:
+        A string with the result of the query
+    """
+    print("reasoning: ", reasoning)
+    client = get_client()
+    result = client.query(sql)
+    response = result.result_rows
+    print("response:", response)
+    return response
+
+@tool(parse_docstring=True)
+def get_recent_transactions(reasoning: str, blockchainId: str = "c-chain") -> str:
+    """
+    Get the recent transactions from the AVAX blockchain database.
+
+    Args:
+        reasoning: A string with the reasoning for the tool call
+        blockchainId: The blockchain ID to get the transactions from (default: c-chain)
+
+    Returns:
+        A string with the recent transactions
+    """
+    print("reasoning: ", reasoning)
+    network = "mainnet"
+    url = f"https://glacier-api.avax.network/v1/networks/{network}/blockchains/{blockchainId}/transactions"
+
+    headers = {"x-glacier-api-key": Config.GLACIER_API_KEY}
+
+    response = requests.get(url, headers=headers)
+
+    print("response: ", response.json())
+    return str(response.json())
+
+@tool(parse_docstring=True)
+def get_recent_active_addresses(reasoning: str, blockchainId: str = "c-chain") -> str:
+    """
+    Get the recent active addresses from the AVAX blockchain database.
+
+    Args:
+        reasoning: A string with the reasoning for the tool call
+        blockchainId: The blockchain ID to get the active addresses from (default: c-chain)
+
+    Returns:
+        A string with the recent transactions and active addresses
+    """
+    print("reasoning: ", reasoning)
+    network = "mainnet"
+    url = f"https://glacier-api.avax.network/v1/networks/{network}/blockchains/{blockchainId}/transactions"
+    headers = {"x-glacier-api-key": Config.GLACIER_API_KEY}
+    response = requests.get(url, headers=headers)
+    print("response: ", response.json())
+    return str(response.json())
+
+@tool(parse_docstring=True)
+def get_network_info(reasoning: str) -> str:
+    """
+    Gets AVAX mainnet network details such as validator and delegator stats.
+
+    Args:
+        reasoning: A string with the reasoning for the tool call
+
+    Returns:
+        A string with the network details
+    """
+    print("reasoning: ", reasoning)
+    network = "mainnet"
+    url = f"https://glacier-api.avax.network/v1/networks/{network}"
+    headers = {"x-glacier-api-key": Config.GLACIER_API_KEY}
+    response = requests.get(url, headers=headers)
+    print("response: ", response.json())
+    return str(response.json())
+
+@tool(parse_docstring=True)
+def get_total_active_addresses(reasoning: str, ) -> str:
+    """
+    Gets the total active addresses from the AVAX network. Use this tool to get the total number of active addresses on the network.
+
+    Args:
+        reasoning: A string with the reasoning for the tool call
+
+    Returns:
+        A string with the cumulative active addresses
+    """
+    print("reasoning: ", reasoning)
+    chainId = "total"
+    metric = "cumulativeAddresses"
+    url = f"https://metrics.avax.network/v2/chains/{chainId}/metrics/{metric}"
+    headers = {"x-glacier-api-key": Config.GLACIER_API_KEY}
+    response = requests.get(url, headers=headers)
+    print("response: ", response.json())
+    return str(response.json())
+
+def get_tools() -> list[Tool]:
+    """
+    Build and return the list of LangChain Tools for use in an agent.
+
+    Each Tool wraps one of the user-facing helper functions above.
+    """
+
+    return [list_tables, sample_table, describe_table, execute_sql, get_recent_transactions, get_recent_active_addresses, get_network_info, get_total_active_addresses]
+
+def call_tool(tool_call: ToolCall) -> any:
+    print(tool_call)
+    tools_by_name = {tool.name: tool for tool in get_tools()}
+    tool = tools_by_name[tool_call["name"]]
+    response = tool.invoke(tool_call["args"])
+    return ToolMessage(content=response, tool_call_id=tool_call["id"])

src/agents/default/agent.py

@@ -0,0 +1,13 @@
+from langgraph.prebuilt import create_react_agent
+
+class DefaultAgent():
+    """Agent for handling default queries and data retrieval."""
+
+    def __init__(self, llm):
+        self.llm = llm
+
+        self.agent = create_react_agent(
+            model=llm,
+            tools=[],
+            name="default_agent"
+        )

src/agents/metadata.py

@@ -0,0 +1,18 @@
+class Metadata:
+    def __init__(self):
+        self.crypto_data_agent = {}
+        self.swap_agent = {}
+
+    def get_crypto_data_agent(self):
+        return self.crypto_data_agent
+    
+    def set_crypto_data_agent(self, crypto_data_agent):
+        self.crypto_data_agent = crypto_data_agent
+
+    def get_swap_agent(self):
+        return self.swap_agent
+    
+    def set_swap_agent(self, swap_agent):
+        self.swap_agent = swap_agent
+
+metadata = Metadata()

src/agents/supervisor/__init__.py

@@ -0,0 +1 @@
+

src/agents/supervisor/agent.py

@@ -0,0 +1,306 @@
+from langchain_google_genai import ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings
+from langgraph_supervisor import create_supervisor
+from src.agents.config import Config
+from typing import TypedDict, Literal, List, Any
+import re
+import json
+from src.agents.metadata import metadata
+
+# Agents
+from src.agents.crypto_data.agent import CryptoDataAgent
+from src.agents.database.agent import DatabaseAgent
+from src.agents.default.agent import DefaultAgent
+from src.agents.swap.agent import SwapAgent
+from src.agents.database.client import is_database_available
+
+llm = ChatGoogleGenerativeAI(
+    model=Config.GEMINI_MODEL,
+    temperature=0.7,
+    google_api_key=Config.GEMINI_API_KEY
+)
+
+embeddings = GoogleGenerativeAIEmbeddings(
+    model=Config.GEMINI_EMBEDDING_MODEL,
+    google_api_key=Config.GEMINI_API_KEY
+)
+
+class ChatMessage(TypedDict):
+    role: Literal["system", "user", "assistant"]
+    content: str
+
+class Supervisor:
+    def __init__(self, llm):
+        self.llm = llm
+
+        cryptoDataAgentClass = CryptoDataAgent(llm)
+        cryptoDataAgent = cryptoDataAgentClass.agent
+
+        agents = [cryptoDataAgent]
+        available_agents_text = "- crypto_agent: Handles cryptocurrency-related queries like price checks, market data, NFT floor prices, DeFi protocol TVL, etc.\n"
+
+        # Conditionally include database agent
+        if is_database_available():
+            databaseAgent = DatabaseAgent(llm)
+            agents.append(databaseAgent)
+            available_agents_text += "- database_agent: Handles database queries and data analysis. Can search and analyze data from the database.\n"
+        else:
+            databaseAgent = None
+
+        swapAgent = SwapAgent(llm)
+        agents.append(swapAgent.agent)
+        available_agents_text += "- swap_agent: Handles swap operations on the Avalanche network and any other swap question related.\n"
+
+        defaultAgent = DefaultAgent(llm)
+        agents.append(defaultAgent.agent)
+
+        # Track known agent names for response extraction
+        self.known_agent_names = {"crypto_agent", "database_agent", "swap_agent", "default_agent"}
+
+        # Prepare database guidance text to avoid backslashes in f-string expressions
+        if databaseAgent:
+            database_instruction = "When a user asks for data analysis, database queries, or information from the database, delegate to the database_agent."
+            database_examples = (
+                "Examples of database queries to delegate:\n"
+                "- \"What are the avax chains?\"\n"
+                "- \"What information is available about the AVAX in the database agent?\"\n"
+                "- \"What is the total number of activities addresses in AVAX?\"\n"
+                "- \"How many transactions are there in the AVAX network?\"\n"
+            )
+        else:
+            database_instruction = "Do not delegate to a database agent; answer best-effort without DB access or ask the user to start the database."
+            database_examples = ""
+
+        # System prompt to guide the supervisor
+        system_prompt = f"""You are a helpful supervisor that routes user queries to the appropriate specialized agents.
+
+Available agents:
+{available_agents_text}
+
+When a user asks about cryptocurrency prices, market data, NFTs, or DeFi protocols, delegate to the crypto_agent.
+{database_instruction}
+For all other queries, respond directly as a helpful assistant.
+
+IMPORTANT: your final response should answer the user's query. Use the agents response to answer the user's query if necessary. Avoid returning control-transfer notes like 'Transferring back to supervisor' — return the substantive answer instead.
+
+Examples of crypto queries to delegate:
+- "What is the price of ETH?"
+- "What's the market cap of Bitcoin?"
+- "What's the floor price of Bored Apes?"
+- "What's the TVL of Uniswap?"
+
+Examples of swap queries to delegate:
+- I wanna make a swap
+- What are the available tokens for swapping?
+- I want to swap 100 USD for AVAX
+
+{database_examples}
+
+Examples of general queries to handle directly:
+- "Hello, how are you?"
+- "What's the weather like?"
+- "Tell me a joke"
+"""
+
+        self.supervisor = create_supervisor(
+            agents,
+            model=llm,
+            prompt=system_prompt,
+            output_mode="last_message"
+        )
+
+        self.app = self.supervisor.compile()
+
+    def _is_handoff_text(self, text: str) -> bool:
+        if not text:
+            return False
+        t = text.strip().lower()
+        handoff_keywords = [
+            "transferring back",
+            "transfer back",
+            "returning control",
+            "handoff",
+            "handing back",
+            "delegating back",
+            "delegate back",
+            "passing back",
+            "routing back",
+            "route back",
+            "back to supervisor",
+            "supervisor will handle",
+            "sending back to supervisor",
+            "give control back",
+            "control back to supervisor",
+        ]
+        return any(k in t for k in handoff_keywords)
+
+    def _sanitize_handoff_phrases(self, text: str) -> str:
+        if not text:
+            return text
+        phrases = [
+            "transferring back to supervisor",
+            "transfer back to supervisor",
+            "returning control to supervisor",
+            "handing back to supervisor",
+            "delegating back to supervisor",
+            "delegate back to supervisor",
+            "passing back to supervisor",
+            "routing back to supervisor",
+            "route back to supervisor",
+            "back to supervisor",
+            "control back to supervisor",
+            "supervisor will handle",
+            "sending back to supervisor",
+        ]
+        sanitized = text
+        for p in phrases:
+            # remove phrase case-insensitively, with optional surrounding punctuation/whitespace
+            pattern = re.compile(r"\b" + re.escape(p) + r"\b[\s\.,;:!\)]*", re.IGNORECASE)
+            sanitized = pattern.sub(" ", sanitized)
+        # Normalize whitespace
+        sanitized = re.sub(r"\s+", " ", sanitized).strip()
+        return sanitized
+
+    def _get_text_content(self, message: Any) -> str | None:
+        content = getattr(message, "content", None)
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            collected: List[str] = []
+            for part in content:
+                # Try dict form first
+                if isinstance(part, dict):
+                    text = part.get("text") or part.get("content")
+                    if isinstance(text, str) and text.strip():
+                        collected.append(text.strip())
+                else:
+                    # Best-effort: objects with 'text' attribute
+                    text_attr = getattr(part, "text", None)
+                    if isinstance(text_attr, str) and text_attr.strip():
+                        collected.append(text_attr.strip())
+            if collected:
+                return " ".join(collected)
+        return None
+    
+    def _extract_payload(self, text: str) -> tuple[dict, str]:
+        # Try JSON payload first
+        try:
+            obj = json.loads(text)
+            if isinstance(obj, dict) and "metadata" in obj and "text" in obj:
+                return (obj.get("metadata") or {}), str(obj.get("text") or "")
+        except Exception:
+            pass
+        # Fallback to sentinel
+        m = re.search(r"\|\|META:\s*(\{.*?\})\|\|", text)
+        if m:
+            try:
+                meta = json.loads(m.group(1))
+            except Exception:
+                meta = {}
+            cleaned = (text[:m.start()] + text[m.end():]).strip()
+            cleaned = re.sub(r"\s+", " ", cleaned)
+            return meta, cleaned
+        return {}, text
+
+    def _collect_tool_metadata(self, messages_out) -> dict:
+        # Prefer last tool-ish content with metadata
+        for m in reversed(messages_out):
+            t = self._get_text_content(m) or ""
+            meta, _ = self._extract_payload(t)
+            if meta:
+                return meta
+            # Optional: artifact support if your langchain version has it
+            art = getattr(m, "artifact", None)
+            if isinstance(art, dict) and art:
+                return art
+        return {}
+
+    def invoke(self, messages: List[ChatMessage]) -> dict:
+        from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
+
+        langchain_messages = []
+        for msg in messages:
+            if msg.get("role") == "user":
+                langchain_messages.append(HumanMessage(content=msg.get("content", "")))
+            elif msg.get("role") == "system":
+                langchain_messages.append(SystemMessage(content=msg.get("content", "")))
+            elif msg.get("role") == "assistant":
+                langchain_messages.append(AIMessage(content=msg.get("content", "")))
+
+        try:
+            response = self.app.invoke({"messages": langchain_messages})
+            print("DEBUG: response", response)
+        except Exception as e:
+            print(f"Error in Supervisor: {e}")
+            return {
+                "messages": [],
+                "agent": "supervisor",
+                "response": "Sorry, an error occurred while processing your request."
+            }
+
+        messages_out = response.get("messages", []) if isinstance(response, dict) else []
+
+        # Prefer the last specialized agent message over any router/supervisor meta message
+        final_response = None
+        final_agent = "supervisor"
+
+        def choose_content_from_message(m) -> tuple[str | None, str | None]:
+            print("m: ", m)
+            agent_name = getattr(m, "name", None)
+            content_text = self._get_text_content(m)
+            if not content_text:
+                return None, None
+            sanitized = self._sanitize_handoff_phrases(content_text)
+            if sanitized and sanitized.strip() and not self._is_handoff_text(sanitized):
+                # Prefer sanitized content
+                return sanitized, agent_name
+            return None, None
+        
+
+        # 1) Try to find the last message from a known specialized agent that is not a handoff/route-back note
+        for m in reversed(messages_out):
+            agent_name = getattr(m, "name", None)
+            if agent_name in self.known_agent_names:
+                content, agent = choose_content_from_message(m)
+                if content:
+                    final_response = content
+                    final_agent = agent or agent_name
+                    print(f'agent: {agent_name} content: {content}')
+                    break
+
+        # 2) Fallback: any last message with content that is not a handoff note
+        if final_response is None:
+            for m in reversed(messages_out):
+                content, agent = choose_content_from_message(m)
+                if content:
+                    final_response = content
+                    if agent:
+                        final_agent = agent
+                    break
+
+        # 3) Last resort: use dict-level fields if present
+        if final_response is None:
+            if isinstance(response, dict):
+                final_response = response.get("response") or "No response available"
+                final_agent = response.get("agent", final_agent)
+            else:
+                final_response = "No response available"
+
+        cleaned_response = final_response or "Sorry, no meaningful response was returned."
+        meta = {}
+        if final_agent == "swap_agent":
+            meta = {'src': 'AVAX', 'dst': 'USDC', 'amount': '100'}
+        elif final_agent == "crypto_agent":
+            meta = metadata.get_crypto_data_agent() or {}
+        else:
+            meta = {}
+        print("meta: ", meta)
+        print("cleaned_response: ", cleaned_response)
+
+        print("final_agent: ", final_agent)
+
+        return {
+            "messages": messages_out,
+            "agent": final_agent,
+            "response": cleaned_response or "Sorry, no meaningful response was returned.",
+            "metadata": meta,
+        }

src/agents/swap/agent.py

@@ -0,0 +1,16 @@
+import logging
+from src.agents.swap.tools import get_tools
+from langgraph.prebuilt import create_react_agent
+
+logger = logging.getLogger(__name__)
+
+
+class SwapAgent:
+    """Agent for handling swap operations and any other swap related questions"""
+    def __init__(self, llm):
+        self.llm = llm
+        self.agent = create_react_agent(
+            model=llm,
+            tools=get_tools(),
+            name="swap_agent"
+        )

src/agents/swap/config.py

@@ -0,0 +1,42 @@
+class SwapConfig:
+    """Configuration and simple interface for supported swap tokens.
+
+    This provides a canonical set of allowed token symbols and helpers to
+    normalize and validate user input before executing swaps.
+    """
+
+    # Canonical symbols for Avalanche swaps (expand as needed)
+    SUPPORTED_TOKENS = {
+        "AVAX",   # Native token
+        "WAVAX",  # Wrapped AVAX
+        "USDC",
+        "USDT",
+        "DAI",
+        "WBTC",
+        "WETH",
+    }
+
+    @classmethod
+    def normalize_symbol(cls, symbol: str) -> str:
+        """Return canonical uppercase symbol without surrounding whitespace."""
+        return (symbol or "").strip().upper()
+
+    @classmethod
+    def is_supported(cls, symbol: str) -> bool:
+        """Check if a token symbol is supported (case-insensitive)."""
+        return cls.normalize_symbol(symbol) in cls.SUPPORTED_TOKENS
+
+    @classmethod
+    def validate_or_raise(cls, symbol: str) -> str:
+        """Validate token symbol and return its canonical form, or raise ValueError."""
+        canonical = cls.normalize_symbol(symbol)
+        if canonical not in cls.SUPPORTED_TOKENS:
+            raise ValueError(
+                f"Unsupported token '{symbol}'. Supported tokens: {sorted(cls.SUPPORTED_TOKENS)}"
+            )
+        return canonical
+
+    @classmethod
+    def list_supported(cls):
+        """Return a sorted list of supported token symbols."""
+        return sorted(cls.SUPPORTED_TOKENS)    

src/agents/swap/tools.py

@@ -0,0 +1,49 @@
+from langchain_core.tools import tool
+from src.agents.metadata import metadata
+from src.agents.swap.config import SwapConfig
+
+@tool
+def swap_avax(amount: float, from_token: str, to_token: str):
+    """
+    Swap AVAX for a given amount of tokens
+
+    Args:
+        amount: The amount of tokens to swap
+        from_token: The token to swap from
+        to_token: The token to swap to
+
+    Returns:
+        The amount of tokens received
+    """
+    try:
+        canonical_from = SwapConfig.validate_or_raise(from_token)
+        canonical_to = SwapConfig.validate_or_raise(to_token)
+    except ValueError as e:
+        return str(e)
+
+    print(f"Swapping {amount} {canonical_from} for {canonical_to}")
+    meta = {
+        "from_token": canonical_from,
+        "to_token": canonical_to,
+        "amount": amount
+    }
+    metadata.set_swap_agent(meta)
+    return f'Swapped {amount} {canonical_from} for {canonical_to}'
+
+@tool
+def get_avaialble_tokens():
+    """
+    Get the available tokens for swapping
+    """
+    return SwapConfig.list_supported()
+
+@tool
+def default_response():
+    """
+    Normal response when the user asks for a swap
+    """
+    return f'What would you like to swap? The available agents are{SwapConfig.list_supported}'
+
+
+def get_tools():
+    return [swap_avax, get_avaialble_tokens, default_response]

src/app.py

@@ -0,0 +1,197 @@
+import logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    handlers=[logging.StreamHandler()]
+)
+logging.info("Test log from app.py startup")
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from typing import List
+import re
+
+from src.agents.config import Config
+from src.agents.supervisor.agent import Supervisor
+from src.models.chatMessage import ChatMessage
+from src.routes.chat_manager_routes import router as chat_manager_router
+from src.service.chat_manager import chat_manager_instance
+from src.agents.crypto_data.tools import get_coingecko_id, get_tradingview_symbol
+
+# Initialize FastAPI app
+app = FastAPI(title="Zico Agent API", version="1.0")
+
+# Enable CORS for local/frontend dev
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Instantiate Supervisor agent (singleton LLM)
+supervisor = Supervisor(Config.get_llm())
+
+class ChatRequest(BaseModel):
+    message: ChatMessage
+    chain_id: str = "default"
+    wallet_address: str = "default"
+    conversation_id: str = "default"
+    user_id: str = "anonymous"
+
+# Lightweight in-memory agent config for frontend integrations
+AVAILABLE_AGENTS = [
+    {"name": "default", "human_readable_name": "Default General Purpose", "description": "General chat and meta-queries about agents."},
+    {"name": "crypto data", "human_readable_name": "Crypto Data Fetcher", "description": "Real-time cryptocurrency prices, market cap, FDV, TVL."},
+    {"name": "token swap", "human_readable_name": "Token Swap Agent", "description": "Swap tokens using supported DEX APIs."},
+    {"name": "realtime search", "human_readable_name": "Real-Time Search", "description": "Search the web for recent information."},
+    {"name": "dexscreener", "human_readable_name": "DexScreener Analyst", "description": "Fetches and analyzes DEX trading data."},
+    {"name": "rugcheck", "human_readable_name": "Token Safety Analyzer", "description": "Analyzes token safety and trends (Solana)."},
+    {"name": "imagen", "human_readable_name": "Image Generator", "description": "Generate images from text prompts."},
+    {"name": "rag", "human_readable_name": "Document Assistant", "description": "Answer questions about uploaded documents."},
+    {"name": "tweet sizzler", "human_readable_name": "Tweet / X-Post Generator", "description": "Generate engaging tweets."},
+    {"name": "dca", "human_readable_name": "DCA Strategy Manager", "description": "Plan and manage DCA strategies."},
+    {"name": "base", "human_readable_name": "Base Transaction Manager", "description": "Handle transactions on Base network."},
+    {"name": "mor rewards", "human_readable_name": "MOR Rewards Tracker", "description": "Track MOR rewards and balances."},
+    {"name": "mor claims", "human_readable_name": "MOR Claims Agent", "description": "Claim MOR tokens."},
+]
+
+# Default to a small, reasonable subset
+SELECTED_AGENTS = [agent["name"] for agent in AVAILABLE_AGENTS[:6]]
+
+# Commands exposed to the ChatInput autocomplete
+AGENT_COMMANDS = [
+    {"command": "morpheus", "name": "Default General Purpose", "description": "General assistant for simple queries and meta-questions."},
+    {"command": "crypto", "name": "Crypto Data Fetcher", "description": "Get prices, market cap, FDV, TVL and more."},
+    {"command": "document", "name": "Document Assistant", "description": "Ask questions about uploaded documents."},
+    {"command": "tweet", "name": "Tweet / X-Post Generator", "description": "Create engaging tweets about crypto and web3."},
+    {"command": "search", "name": "Real-Time Search", "description": "Search the web for recent events or updates."},
+    {"command": "dexscreener", "name": "DexScreener Analyst", "description": "Analyze DEX trading data on supported chains."},
+    {"command": "rugcheck", "name": "Token Safety Analyzer", "description": "Check token safety and view trending tokens."},
+    {"command": "dca", "name": "DCA Strategy Manager", "description": "Plan a dollar-cost averaging strategy."},
+    {"command": "base", "name": "Base Transaction Manager", "description": "Send tokens and swap on Base."},
+    {"command": "rewards", "name": "MOR Rewards Tracker", "description": "Check rewards balance and accrual."},
+]
+
+# Agents endpoints expected by the frontend
+@app.get("/agents/available")
+def get_available_agents():
+    return {
+        "selected_agents": SELECTED_AGENTS,
+        "available_agents": AVAILABLE_AGENTS,
+    }
+
+@app.post("/agents/selected")
+async def set_selected_agents(request: Request):
+    global SELECTED_AGENTS
+    data = await request.json()
+    agents = data.get("agents", [])
+    # Validate provided names against available agents
+    available_names = {a["name"] for a in AVAILABLE_AGENTS}
+    valid_agents = [a for a in agents if a in available_names]
+    if not valid_agents:
+        # Keep previous selection if nothing valid provided
+        return {"status": "no_change", "agents": SELECTED_AGENTS}
+    # Update selection
+    SELECTED_AGENTS = valid_agents[:6]
+    return {"status": "success", "agents": SELECTED_AGENTS}
+
+@app.get("/agents/commands")
+def get_agent_commands():
+    return {"commands": AGENT_COMMANDS}
+
+# Map agent runtime names to high-level types for storage/analytics
+def _map_agent_type(agent_name: str) -> str:
+    mapping = {
+        "crypto_agent": "crypto data",
+        "default_agent": "default",
+        "database_agent": "analysis",
+        "swap_agent": "token swap",
+        "supervisor": "supervisor",
+    }
+    return mapping.get(agent_name, "supervisor")
+
+@app.get("/health")
+def health_check():
+    return {"status": "ok"}
+
+@app.get("/chat/messages")
+def get_messages(request: Request):
+    params = request.query_params
+    conversation_id = params.get("conversation_id", "default")
+    user_id = params.get("user_id", "anonymous")
+    return {"messages": chat_manager_instance.get_messages(conversation_id, user_id)}
+
+@app.get("/chat/conversations")
+def get_conversations(request: Request):
+    params = request.query_params
+    user_id = params.get("user_id", "anonymous")
+    return {"conversation_ids": chat_manager_instance.get_all_conversation_ids(user_id)}
+
+@app.post("/chat")
+def chat(request: ChatRequest):
+    print("request: ", request)
+    try:
+        # Add the user message to the conversation
+        chat_manager_instance.add_message(
+            message=request.message.dict(),
+            conversation_id=request.conversation_id,
+            user_id=request.user_id
+        )
+        
+        # Get all messages from the conversation to pass to the agent
+        conversation_messages = chat_manager_instance.get_messages(
+            conversation_id=request.conversation_id,
+            user_id=request.user_id
+        )
+        
+        # Invoke the supervisor agent with the conversation
+        result = supervisor.invoke(conversation_messages)
+        
+        # Add the agent's response to the conversation
+        if result and isinstance(result, dict):
+            print("result: ", result)
+            agent_name = result.get("agent", "supervisor")
+            print("agent_name: ", agent_name)
+            agent_name = _map_agent_type(agent_name)
+
+            # Build response metadata and enrich with coin info for crypto price queries
+            response_metadata = {"supervisor_result": result}
+            # Prefer supervisor-provided metadata
+            if isinstance(result, dict) and result.get("metadata"):
+                response_metadata.update(result.get("metadata") or {})
+                print("response_metadata: ", response_metadata)
+            
+            # Create a ChatMessage from the supervisor response
+            response_message = ChatMessage(
+                role="assistant",
+                content=result.get("response", "No response available"),
+                agent_name=agent_name,
+                agent_type=_map_agent_type(agent_name),
+                metadata=result.get("metadata", {}),
+                conversation_id=request.conversation_id,
+                user_id=request.user_id,
+                requires_action=True if agent_name == "token swap" else False,
+                action_type="swap" if agent_name == "token swap" else None
+            )
+            
+            # Add the response message to the conversation
+            chat_manager_instance.add_message(
+                message=response_message.dict(),
+                conversation_id=request.conversation_id,
+                user_id=request.user_id
+            )
+            
+            # Return only the clean response
+            return {
+                "response": result.get("response", "No response available"),
+                "agentName": agent_name
+            }
+        
+        return {"response": "No response available", "agent": "supervisor"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+# Include chat manager router
+app.include_router(chat_manager_router)

src/models/chatMessage.py

@@ -0,0 +1,152 @@
+from typing import TypedDict, Literal, List, Optional, Dict, Any
+from datetime import datetime
+from pydantic import BaseModel, Field
+from enum import Enum
+
+
+class MessageRole(str, Enum):
+    """Enum for message roles"""
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    AGENT = "agent"
+
+
+class AgentType(str, Enum):
+    """Enum for different agent types"""
+    SUPERVISOR = "supervisor"
+    CRYPTO_DATA = "crypto_data"
+    GENERAL = "general"
+    RESEARCH = "research"
+    ANALYSIS = "analysis"
+
+
+class MessageStatus(str, Enum):
+    """Enum for message processing status"""
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class ChatMessage(BaseModel):
+    """Enhanced chat message model for multi-agent conversations"""
+    
+    # Core message fields
+    role: MessageRole = Field(..., description="Role of the message sender")
+    content: str = Field(..., description="Message content")
+    
+    # Agent-specific fields
+    agent_name: Optional[str] = Field(None, description="Name of the agent that processed this message")
+    agent_type: Optional[AgentType] = Field(None, description="Type of agent that processed this message")
+    
+    requires_action: bool = Field(default=False, description="Whether this message requires followup")
+    action_type: Optional[str] = Field(None, description="Type of action required")
+    
+    # Metadata and context
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Message timestamp")
+    message_id: Optional[str] = Field(None, description="Unique message identifier")
+    
+    # Processing status
+    status: MessageStatus = Field(default=MessageStatus.COMPLETED, description="Message processing status")
+    error_message: Optional[str] = Field(None, description="Error message if processing failed")
+    
+    # Conversation context
+    conversation_id: Optional[str] = Field(None, description="Conversation identifier")
+    user_id: Optional[str] = Field(None, description="User identifier")
+    
+    # Tool calls and responses
+    tool_calls: Optional[List[Dict[str, Any]]] = Field(None, description="Tool calls made by the agent")
+    tool_results: Optional[List[Dict[str, Any]]] = Field(None, description="Results from tool executions")
+    
+    # Multi-turn conversation support
+    next_agent: Optional[str] = Field(None, description="Next agent to handle the conversation")
+    requires_followup: bool = Field(default=False, description="Whether this message requires followup")
+    
+    class Config:
+        use_enum_values = True
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class ConversationState(BaseModel):
+    """State management for multi-agent conversations"""
+    
+    conversation_id: str = Field(..., description="Unique conversation identifier")
+    user_id: str = Field(..., description="User identifier")
+    
+    # Current state
+    current_agent: Optional[str] = Field(None, description="Currently active agent")
+    last_message_id: Optional[str] = Field(None, description="ID of the last message")
+    
+    # Conversation history
+    messages: List[ChatMessage] = Field(default_factory=list, description="Message history")
+    
+    # Context and memory
+    context: Dict[str, Any] = Field(default_factory=dict, description="Conversation context")
+    memory: Dict[str, Any] = Field(default_factory=dict, description="Persistent memory across turns")
+    
+    # Agent routing history
+    agent_history: List[Dict[str, Any]] = Field(default_factory=list, description="History of agent interactions")
+    
+    # Status and metadata
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    is_active: bool = Field(default=True, description="Whether conversation is active")
+    
+    class Config:
+        use_enum_values = True
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class AgentResponse(BaseModel):
+    """Standardized response format for agents"""
+    
+    content: str = Field(..., description="Response content")
+    agent_name: str = Field(..., description="Name of the responding agent")
+    agent_type: AgentType = Field(..., description="Type of the responding agent")
+    
+    # Metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Response metadata")
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    
+    # Tool information
+    tools_used: List[str] = Field(default_factory=list, description="Tools used in this response")
+    tool_results: Optional[List[Dict[str, Any]]] = Field(None, description="Results from tool executions")
+    
+    # Next steps
+    next_agent: Optional[str] = Field(None, description="Next agent to handle the conversation")
+    requires_followup: bool = Field(default=False, description="Whether followup is needed")
+    
+    # Status
+    success: bool = Field(default=True, description="Whether the response was successful")
+    error_message: Optional[str] = Field(None, description="Error message if failed")
+    
+    class Config:
+        use_enum_values = True
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+# TypedDict for backward compatibility
+class ChatMessageDict(TypedDict):
+    role: str
+    content: str
+    agent_name: Optional[str]
+    metadata: Dict[str, Any]
+    timestamp: str
+    message_id: Optional[str]
+    status: str
+    conversation_id: Optional[str]
+    user_id: Optional[str]
+
+
+
+
+

src/routes/chat_manager_routes.py

@@ -0,0 +1,90 @@
+import logging
+from fastapi import APIRouter, Query, Body
+from src.service.chat_manager import chat_manager_instance
+from typing import Optional
+from pydantic import BaseModel
+from typing import Dict
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/chat", tags=["chat"])
+
+class UserIdRequest(BaseModel):
+    user_id: str
+
+@router.get("/messages")
+async def get_messages(conversation_id: str = Query(default="default"), user_id: str = Query(default="anonymous")):
+    """Get all chat messages for a conversation"""
+    logger.info(f"Received get_messages request for conversation {conversation_id} from user {user_id}")
+    return {"messages": chat_manager_instance.get_messages(conversation_id, user_id)}
+
+
+@router.get("/clear")
+async def clear_messages(conversation_id: str = Query(default="default"), user_id: str = Query(default="anonymous")):
+    """Clear chat message history for a conversation"""
+    logger.info(f"Clearing message history for conversation {conversation_id} for user {user_id}")
+    chat_manager_instance.clear_messages(conversation_id, user_id)
+    return {"response": "successfully cleared message history"}
+
+
+@router.get("/conversations")
+async def get_conversations(
+    user_id_query: str = Query(default=None, alias="user_id"),
+    user_id_str: Optional[str] = Body(default=None)
+):
+    """Get all conversation IDs for a specific user"""
+    user_id = user_id_str if user_id_str else user_id_query
+
+    if not user_id:
+        user_id = "anonymous"
+        
+    logger.info(f"Getting all conversation IDs for user {user_id}")
+    return {"conversation_ids": chat_manager_instance.get_all_conversation_ids(user_id)}
+
+
+@router.get("/users")
+async def get_users():
+    """Get all user IDs"""
+    logger.info("Getting all user IDs")
+    return {"user_ids": chat_manager_instance.get_all_user_ids()}
+
+
+@router.post("/conversations")
+async def create_conversation(
+    user_id_query: str = Query(default=None, alias="user_id"),
+    user_id_body: Optional[UserIdRequest] = None,
+    user_id_str: Optional[str] = Body(default=None)
+):
+    """Create a new conversation for a specific user"""
+    user_id = None
+    if user_id_body:
+        user_id = user_id_body.user_id
+    elif user_id_str:
+        user_id = user_id_str
+    else:
+        user_id = user_id_query
+
+    if not user_id:
+        user_id = "anonymous"
+        
+    logger.info(f"Creating new conversation for user {user_id}")
+    conversation_id = chat_manager_instance.create_conversation(user_id)
+    return {"conversation_id": conversation_id}
+
+
+@router.delete("/conversations/{conversation_id}")
+async def delete_conversation(
+    conversation_id: str,
+    user_id_query: str = Query(default=None, alias="user_id"),
+    user_id_body: Dict[str, str] = Body(default=None)
+):
+    """Delete a conversation by ID"""
+    # Get user_id from body if it exists, otherwise from query
+    user_id = user_id_body.get("user_id") if user_id_body else user_id_query
+
+    if not user_id:
+        user_id = "anonymous"
+        
+    logger.info(f"Deleting conversation {conversation_id} for user {user_id}")
+    chat_manager_instance.delete_conversation(conversation_id, user_id)
+    return {"response": "successfully deleted conversation"}

src/service/chat_manager.py

@@ -0,0 +1,280 @@
+import logging
+import time
+from typing import Dict, List, Optional
+from src.models.chatMessage import ChatMessage, ConversationState, AgentResponse
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class ChatManager:
+    """
+    Manages chat conversations and message history.
+
+    This class provides functionality to:
+    - Create and manage multiple conversations identified by unique IDs
+    - Associate conversations with specific users
+    - Add/retrieve messages and responses within conversations
+    - Clear conversation history
+    - Get chat history in different formats
+    - Delete conversations
+
+    Each conversation starts with a default disclaimer message about the experimental nature
+    of the chatbot.
+
+    Attributes:
+        user_conversations (Dict[str, Dict[str, ConversationState]]): Dictionary mapping user IDs to their conversations
+        default_message (ChatMessage): Default disclaimer message added to new conversations
+
+    Example:
+        >>> chat_manager = ChatManager()
+        >>> chat_manager.add_message({"role": "user", "content": "Hello"}, "conv1", "user123")
+        >>> messages = chat_manager.get_messages("conv1", "user123")
+    """
+
+    def __init__(self) -> None:
+        self.user_conversations: Dict[str, Dict[str, ConversationState]] = {}
+        self.default_message = ChatMessage(
+            role="assistant",
+            content="""This highly experimental chatbot is not intended for making important decisions. Its
+                        responses are generated using AI models and may not always be accurate.
+                        By using this chatbot, you acknowledge that you use it at your own discretion
+                        and assume all risks associated with its limitations and potential errors.""",
+            metadata={},
+        )
+
+        # Backward compatibility - Initialize with default conversation for anonymous user
+        self._initialize_user("anonymous")
+        self.user_conversations["anonymous"]["default"] = ConversationState(
+            conversation_id="default",
+            user_id="anonymous",
+            messages=[self.default_message],
+            context={},
+            memory={},
+            agent_history=[],
+            current_agent=None,
+            last_message_id=None,
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow(),
+            is_active=True
+        )
+
+    def _get_conversation_id(self, conversation_id: Optional[str] = None) -> str:
+        """Helper method to get conversation ID, defaulting to 'default' if None provided"""
+        return conversation_id or "default"
+
+    def _get_user_id(self, user_id: Optional[str] = None) -> str:
+        """Helper method to get user ID, defaulting to 'anonymous' if None provided"""
+        return user_id or "anonymous"
+
+    def _initialize_user(self, user_id: str) -> None:
+        """Initialize conversations dictionary for a new user"""
+        if user_id not in self.user_conversations:
+            self.user_conversations[user_id] = {}
+            logger.info(f"Initialized conversations for user {user_id}")
+
+    def get_messages(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None) -> List[Dict[str, str]]:
+        """
+        Get all messages for a specific conversation.
+
+        Args:
+            conversation_id (str, optional): Unique identifier for the conversation. Defaults to "default"
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+
+        Returns:
+            List[Dict[str, str]]: List of messages as dictionaries
+        """
+        user_id = self._get_user_id(user_id)
+        conversation = self._get_or_create_conversation(self._get_conversation_id(conversation_id), user_id)
+        return [msg.dict() for msg in conversation.messages]
+
+    def add_message(self, message: Dict[str, str], conversation_id: Optional[str] = None, user_id: Optional[str] = None):
+        """
+        Add a new message to a conversation.
+
+        Args:
+            message (Dict[str, str]): Message to add
+            conversation_id (str, optional): Conversation to add message to. Defaults to "default"
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+        """
+        user_id = self._get_user_id(user_id)
+        conversation_id = self._get_conversation_id(conversation_id)
+        conversation = self._get_or_create_conversation(conversation_id, user_id)
+        chat_message = ChatMessage(**message)
+        if "timestamp" not in message:
+            chat_message.timestamp = datetime.utcnow()
+        conversation.messages.append(chat_message)
+        logger.info(f"Added message to conversation {conversation_id} for user {user_id}: {chat_message.content}")
+
+    def add_response(self, response: Dict[str, str], agent_name: str, conversation_id: Optional[str] = None, user_id: Optional[str] = None):
+        """
+        Add an agent's response to a conversation.
+
+        Args:
+            response (Dict[str, str]): Response content
+            agent_name (str): Name of the responding agent
+            conversation_id (str, optional): Conversation to add response to. Defaults to "default"
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+        """
+        agent_response = AgentResponse(**response)
+        # You may need to implement to_chat_message if not present
+        chat_message = ChatMessage(
+            role="assistant",
+            content=agent_response.content,
+            agent_name=agent_response.agent_name,
+            agent_type=agent_response.agent_type,
+            metadata=agent_response.metadata,
+            timestamp=agent_response.timestamp,
+            tool_results=agent_response.tool_results,
+            next_agent=agent_response.next_agent,
+            requires_followup=agent_response.requires_followup,
+            status="completed" if agent_response.success else "failed",
+            error_message=agent_response.error_message
+        )
+        self.add_message(chat_message.dict(), self._get_conversation_id(conversation_id), self._get_user_id(user_id))
+        logger.info(f"Added response from agent {agent_name} to conversation {conversation_id} for user {user_id}")
+
+    def clear_messages(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None):
+        """
+        Clear all messages in a conversation except the default message.
+
+        Args:
+            conversation_id (str, optional): Conversation to clear. Defaults to "default"
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+        """
+        user_id = self._get_user_id(user_id)
+        conversation = self._get_or_create_conversation(self._get_conversation_id(conversation_id), user_id)
+        conversation.messages = [self.default_message]  # Keep the initial message
+        logger.info(f"Cleared message history for conversation {conversation_id} for user {user_id}")
+
+    def get_last_message(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None) -> Dict[str, str]:
+        """
+        Get the most recent message from a conversation.
+
+        Args:
+            conversation_id (str, optional): Conversation to get message from. Defaults to "default"
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+
+        Returns:
+            Dict[str, str]: Last message or empty dict if no messages
+        """
+        user_id = self._get_user_id(user_id)
+        conversation = self._get_or_create_conversation(self._get_conversation_id(conversation_id), user_id)
+        return conversation.messages[-1].dict() if conversation.messages else {}
+
+    def get_chat_history(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None) -> str:
+        """
+        Get formatted chat history for a conversation.
+
+        Args:
+            conversation_id (str, optional): Conversation to get history for. Defaults to "default"
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+
+        Returns:
+            str: Formatted chat history as string
+        """
+        user_id = self._get_user_id(user_id)
+        conversation = self._get_or_create_conversation(self._get_conversation_id(conversation_id), user_id)
+        return "\n".join([f"{msg.role}: {msg.content}" for msg in conversation.messages])
+
+    def get_all_conversation_ids(self, user_id: Optional[str] = None) -> List[str]:
+        """
+        Get a list of all conversation IDs for a specific user.
+
+        Args:
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+
+        Returns:
+            List[str]: List of conversation IDs for the user
+        """
+        user_id = self._get_user_id(user_id)
+        self._initialize_user(user_id)
+        return list(self.user_conversations[user_id].keys())
+
+    def get_all_user_ids(self) -> List[str]:
+        """
+        Get a list of all user IDs.
+
+        Returns:
+            List[str]: List of user IDs
+        """
+        return list(self.user_conversations.keys())
+
+    def delete_conversation(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None):
+        """
+        Delete a conversation by ID.
+
+        Args:
+            conversation_id (str, optional): ID of conversation to delete. Defaults to "default"
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+        """
+        user_id = self._get_user_id(user_id)
+        conversation_id = self._get_conversation_id(conversation_id)
+        self._initialize_user(user_id)
+        if conversation_id in self.user_conversations[user_id]:
+            del self.user_conversations[user_id][conversation_id]
+            logger.info(f"Deleted conversation {conversation_id} for user {user_id}")
+
+    def create_conversation(self, user_id: Optional[str] = None) -> str:
+        """
+        Create a new conversation for a user.
+
+        Args:
+            user_id (str, optional): User identifier. Defaults to "anonymous"
+
+        Returns:
+            str: ID of the created conversation
+        """
+        user_id = self._get_user_id(user_id)
+        self._initialize_user(user_id)
+        conversation_id = f"conversation_{len(self.user_conversations[user_id])}"
+        while conversation_id in self.user_conversations[user_id]:
+            conversation_id = f"conversation_{len(self.user_conversations[user_id])}_{int(time.time())}"
+        self.user_conversations[user_id][conversation_id] = ConversationState(
+            conversation_id=conversation_id,
+            user_id=user_id,
+            messages=[self.default_message],
+            context={},
+            memory={},
+            agent_history=[],
+            current_agent=None,
+            last_message_id=None,
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow(),
+            is_active=True
+        )
+        logger.info(f"Created new conversation {conversation_id} for user {user_id}")
+        return conversation_id
+
+    def _get_or_create_conversation(self, conversation_id: str, user_id: str) -> ConversationState:
+        """
+        Get existing conversation or create new one if not exists.
+
+        Args:
+            conversation_id (str): Conversation ID to get/create
+            user_id (str): User identifier
+
+        Returns:
+            ConversationState: Retrieved or created conversation
+        """
+        self._initialize_user(user_id)
+        if conversation_id not in self.user_conversations[user_id]:
+            self.user_conversations[user_id][conversation_id] = ConversationState(
+                conversation_id=conversation_id,
+                user_id=user_id,
+                messages=[self.default_message],
+                context={},
+                memory={},
+                agent_history=[],
+                current_agent=None,
+                last_message_id=None,
+                created_at=datetime.utcnow(),
+                updated_at=datetime.utcnow(),
+                is_active=True
+            )
+            logger.info(f"Created new conversation {conversation_id} for user {user_id}")
+        return self.user_conversations[user_id][conversation_id]
+
+
+# Create an instance to act as a singleton store
+chat_manager_instance = ChatManager()