feat: Initial commit with project structure and initial files

.env.example

@@ -0,0 +1,8 @@
+# Google Gemini API Key (Required)
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# CoinGecko API Key (Optional - for higher rate limits)
+COINGECKO_API_KEY=your_coingecko_api_key_here
+
+# CryptoCompare API Key (Optional - for additional data sources)
+CRYPTOCOMPARE_API_KEY=your_cryptocompare_api_key_here

app.py

@@ -0,0 +1,312 @@
+import gradio as gr
+import os
+import json
+from src.enhanced_agent import EnhancedResearchAgent
+from src.portfolio_analyzer import portfolio_analyzer
+from src.visualizations import create_price_chart, create_market_overview, create_comparison_chart
+from src.cache_manager import cache_manager
+import asyncio
+
+research_agent = EnhancedResearchAgent()
+
+async def process_research_query(query, history):
+    try:
+        if not query.strip():
+            return history + [["Please enter a research query.", ""]]
+        
+        response = await research_agent.research_with_context(query)
+        return history + [[query, response]]
+    except Exception as e:
+        error_msg = f"Enhanced research failed: {str(e)}"
+        return history + [[query, error_msg]]
+
+def research_query_sync(query, history):
+    return asyncio.run(process_research_query(query, history))
+
+async def get_market_data():
+    try:
+        data = await research_agent.get_comprehensive_market_data()
+        chart = create_market_overview(data)
+        return chart
+    except Exception as e:
+        return f"Enhanced market data unavailable: {str(e)}"
+
+def get_market_data_sync():
+    return asyncio.run(get_market_data())
+
+async def get_price_chart(symbol):
+    try:
+        if not symbol.strip():
+            return "Please enter a cryptocurrency symbol"
+        
+        data = await research_agent.get_price_history(symbol)
+        chart = create_price_chart(data, symbol)
+        return chart
+    except Exception as e:
+        return f"Chart generation failed: {str(e)}"
+
+def get_price_chart_sync(symbol):
+    return asyncio.run(get_price_chart(symbol))
+
+async def analyze_portfolio_async(portfolio_text):
+    try:
+        if not portfolio_text.strip():
+            return "Please enter your portfolio holdings in JSON format"
+        
+        holdings = json.loads(portfolio_text)
+        analysis = await portfolio_analyzer.analyze_portfolio(holdings)
+        
+        result = f"📊 PORTFOLIO ANALYSIS\n\n"
+        result += f"💰 Total Value: ${analysis['total_value']:,.2f}\n"
+        result += f"📈 24h Change: ${analysis['change_24h']:+,.2f} ({analysis['change_24h_percentage']:+.2f}%)\n\n"
+        
+        result += "🏦 ASSET ALLOCATION:\n"
+        for asset in analysis['asset_allocation'][:10]:
+            result += f"• {asset['name']} ({asset['symbol']}): {asset['percentage']:.1f}% (${asset['value']:,.2f})\n"
+        
+        result += f"\n⚠️ RISK ASSESSMENT:\n"
+        result += f"Overall Risk: {analysis['risk_metrics']['overall_risk']}\n"
+        result += f"Diversification Score: {analysis['risk_metrics']['diversification_score']}/10\n"
+        result += f"Largest Position: {analysis['risk_metrics']['largest_holding_percentage']:.1f}%\n\n"
+        
+        result += "💡 RECOMMENDATIONS:\n"
+        for i, rec in enumerate(analysis['recommendations'], 1):
+            result += f"{i}. {rec}\n"
+        
+        return result
+        
+    except json.JSONDecodeError:
+        return "❌ Invalid JSON format. Please use format: [{'symbol': 'BTC', 'amount': 1.0}, {'symbol': 'ETH', 'amount': 10.0}]"
+    except Exception as e:
+        return f"❌ Portfolio analysis failed: {str(e)}"
+
+async def get_defi_analysis_async():
+    try:
+        data = await research_agent.get_defi_analysis()
+        
+        result = "🏦 DeFi ECOSYSTEM ANALYSIS\n\n"
+        
+        if "top_protocols" in data:
+            result += "📊 TOP PROTOCOLS BY TVL:\n"
+            for i, protocol in enumerate(data["top_protocols"][:10], 1):
+                name = protocol.get("name", "Unknown")
+                tvl = protocol.get("tvl", 0)
+                chain = protocol.get("chain", "Unknown")
+                change = protocol.get("change_1d", 0)
+                result += f"{i:2d}. {name} ({chain}): ${tvl/1e9:.2f}B TVL ({change:+.2f}%)\n"
+        
+        if "top_yields" in data:
+            result += "\n💰 HIGH YIELD OPPORTUNITIES:\n"
+            for i, pool in enumerate(data["top_yields"][:5], 1):
+                symbol = pool.get("symbol", "Unknown")
+                apy = pool.get("apy", 0)
+                tvl = pool.get("tvlUsd", 0)
+                result += f"{i}. {symbol}: {apy:.2f}% APY (${tvl/1e6:.1f}M TVL)\n"
+        
+        return result
+        
+    except Exception as e:
+        return f"❌ DeFi analysis failed: {str(e)}"
+
+def clear_cache():
+    cache_manager.clear()
+    return "Cache cleared successfully"
+
+def analyze_portfolio_sync(portfolio_text):
+    return asyncio.run(analyze_portfolio_async(portfolio_text))
+
+def get_defi_analysis_sync():
+    return asyncio.run(get_defi_analysis_async())
+
+with gr.Blocks(
+    title="Web3 Research Co-Pilot",
+    theme=gr.themes.Soft(primary_hue="blue", secondary_hue="gray"),
+    css="""
+    .container { max-width: 1200px; margin: 0 auto; }
+    .header { text-align: center; padding: 20px; }
+    .chat-container { min-height: 400px; }
+    .chart-container { min-height: 500px; }
+    """
+) as app:
+    
+    gr.Markdown("# 🚀 Web3 Research Co-Pilot", elem_classes=["header"])
+    gr.Markdown("*AI-powered cryptocurrency research with real-time data integration*", elem_classes=["header"])
+    
+    with gr.Tabs():
+        
+        with gr.Tab("🤖 Research Chat"):
+            with gr.Row():
+                with gr.Column(scale=3):
+                    chatbot = gr.Chatbot(
+                        value=[],
+                        height=400,
+                        elem_classes=["chat-container"],
+                        show_label=False
+                    )
+                    
+                    with gr.Row():
+                        query_input = gr.Textbox(
+                            placeholder="Ask about crypto markets, prices, trends, analysis...",
+                            scale=4,
+                            show_label=False
+                        )
+                        submit_btn = gr.Button("Research", variant="primary")
+                    
+                    gr.Examples(
+                        examples=[
+                            "What's the current Bitcoin price and trend?",
+                            "Compare Ethereum vs Solana DeFi ecosystems",
+                            "Analyze top DeFi protocols and TVL trends",
+                            "What are the trending coins and latest crypto news?",
+                            "Show me high-yield DeFi opportunities with risk analysis"
+                        ],
+                        inputs=query_input
+                    )
+                
+                with gr.Column(scale=1):
+                    gr.Markdown("### 📊 Quick Actions")
+                    market_btn = gr.Button("Market Overview", size="sm")
+                    market_output = gr.HTML()
+                    
+                    clear_btn = gr.Button("Clear Cache", size="sm", variant="secondary")
+                    clear_output = gr.Textbox(show_label=False, interactive=False)
+        
+        with gr.Tab("📈 Price Charts"):
+            with gr.Row():
+                symbol_input = gr.Textbox(
+                    label="Cryptocurrency Symbol",
+                    placeholder="BTC, ETH, SOL, etc.",
+                    value="BTC"
+                )
+                chart_btn = gr.Button("Generate Chart", variant="primary")
+            
+            chart_output = gr.HTML(elem_classes=["chart-container"])
+            
+            gr.Examples(
+                examples=["BTC", "ETH", "SOL", "ADA", "DOT"],
+                inputs=symbol_input
+            )
+        
+        with gr.Tab("💼 Portfolio Analysis"):
+            with gr.Row():
+                with gr.Column(scale=1):
+                    portfolio_input = gr.Textbox(
+                        label="Portfolio Holdings (JSON Format)",
+                        placeholder='[{"symbol": "BTC", "amount": 1.0}, {"symbol": "ETH", "amount": 10.0}, {"symbol": "SOL", "amount": 50.0}]',
+                        lines=5,
+                        info="Enter your crypto holdings in JSON format with symbol and amount"
+                    )
+                    portfolio_btn = gr.Button("Analyze Portfolio", variant="primary")
+                
+                with gr.Column(scale=2):
+                    portfolio_output = gr.Textbox(
+                        label="Portfolio Analysis Results",
+                        lines=20,
+                        show_copy_button=True,
+                        interactive=False
+                    )
+            
+            gr.Examples(
+                examples=[
+                    '[{"symbol": "BTC", "amount": 0.5}, {"symbol": "ETH", "amount": 5.0}]',
+                    '[{"symbol": "BTC", "amount": 1.0}, {"symbol": "ETH", "amount": 10.0}, {"symbol": "SOL", "amount": 100.0}]'
+                ],
+                inputs=portfolio_input
+            )
+        
+        with gr.Tab("🏦 DeFi Analytics"):
+            defi_btn = gr.Button("Get DeFi Ecosystem Analysis", variant="primary", size="lg")
+            defi_output = gr.Textbox(
+                label="DeFi Analysis Results",
+                lines=25,
+                show_copy_button=True,
+                interactive=False,
+                info="Comprehensive DeFi protocol analysis with TVL data and yield opportunities"
+            )
+        
+        with gr.Tab("ℹ️ About"):
+            gr.Markdown("""
+            ## 🚀 Enhanced Features
+            - **Multi-API Integration**: CoinGecko, CryptoCompare, and DeFiLlama data sources
+            - **AI-Powered Analysis**: Google Gemini 2.5 Flash with contextual market intelligence
+            - **DeFi Analytics**: Protocol TVL analysis, yield farming opportunities, and ecosystem insights
+            - **Portfolio Analysis**: Risk assessment, diversification scoring, and personalized recommendations
+            - **News Integration**: Real-time crypto news aggregation and sentiment analysis
+            - **Interactive Charts**: Advanced price visualizations with technical indicators
+            - **Smart Caching**: Optimized performance with intelligent data caching (TTL-based)
+            - **Rate Limiting**: Respectful API usage with automatic throttling
+            
+            ## 🎯 Core Capabilities
+            1. **Enhanced Research Chat**: Context-aware conversations with real-time market data integration
+            2. **Advanced Price Charts**: Interactive visualizations with 30-day historical data
+            3. **Portfolio Optimization**: Comprehensive portfolio analysis with risk metrics and recommendations
+            4. **DeFi Intelligence**: Protocol rankings, TVL trends, and high-yield opportunity identification
+            5. **Market Intelligence**: Global market metrics, trending assets, and breaking news analysis
+            
+            ## 💡 Query Examples
+            - "Analyze Bitcoin vs Ethereum DeFi ecosystem performance"
+            - "What are the top DeFi protocols by TVL with lowest risk?"
+            - "Show me high-yield farming opportunities under 15% volatility"
+            - "Compare my portfolio risk to market benchmarks"
+            - "Latest crypto news impact on altcoin market sentiment"
+            - "Which Layer 1 protocols have strongest DeFi adoption?"
+            
+            ## 🔧 Technical Architecture
+            - **Async Processing**: Non-blocking operations for optimal performance
+            - **Error Handling**: Comprehensive exception management with graceful degradation
+            - **Symbol Mapping**: Intelligent cryptocurrency identifier resolution
+            - **Data Validation**: Input sanitization and response formatting
+            """)
+    
+    submit_btn.click(
+        research_query_sync,
+        inputs=[query_input, chatbot],
+        outputs=chatbot
+    ).then(lambda: "", outputs=query_input)
+    
+    query_input.submit(
+        research_query_sync,
+        inputs=[query_input, chatbot],
+        outputs=chatbot
+    ).then(lambda: "", outputs=query_input)
+    
+    chart_btn.click(
+        get_price_chart_sync,
+        inputs=symbol_input,
+        outputs=chart_output
+    )
+    
+    symbol_input.submit(
+        get_price_chart_sync,
+        inputs=symbol_input,
+        outputs=chart_output
+    )
+    
+    market_btn.click(
+        get_market_data_sync,
+        outputs=market_output
+    )
+    
+    clear_btn.click(
+        clear_cache,
+        outputs=clear_output
+    )
+    
+    portfolio_btn.click(
+        analyze_portfolio_sync,
+        inputs=portfolio_input,
+        outputs=portfolio_output
+    )
+    
+    defi_btn.click(
+        get_defi_analysis_sync,
+        outputs=defi_output
+    )
+
+if __name__ == "__main__":
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=5000,
+        share=False,
+        show_error=True
+    )

attached_assets/Pasted--Complete-Web3-Research-Co-Pilot-Project-Plan-Structure-Project-Directory-Structure--1754811430335_1754811430338.txt

@@ -0,0 +1,992 @@
+# Complete Web3 Research Co-Pilot Project Plan & Structure
+
+## 🏗️ **Project Directory Structure**
+
+```
+web3-research-copilot/
+├── README.md
+├── requirements.txt
+├── app.py                          # Main Gradio application
+├── .env.example                    # Environment variables template
+├── .gitignore
+├── Dockerfile                      # For HF Spaces deployment
+├── 
+├── src/
+│   ├── __init__.py
+│   ├── agent/
+│   │   ├── __init__.py
+│   │   ├── research_agent.py       # Main LangChain agent
+│   │   ├── query_planner.py        # Multi-step query breakdown
+│   │   ├── memory_manager.py       # Conversation memory
+│   │   └── response_formatter.py   # Output formatting
+│   │
+│   ├── tools/
+│   │   ├── __init__.py
+│   │   ├── base_tool.py           # Abstract base tool class
+│   │   ├── coingecko_tool.py      # CoinGecko API integration
+│   │   ├── defillama_tool.py      # DeFiLlama API integration
+│   │   ├── etherscan_tool.py      # Etherscan API integration
+│   │   ├── cryptocompare_tool.py  # CryptoCompare API integration
+│   │   └── social_tool.py         # Social media data (Twitter API)
+│   │
+│   ├── data/
+│   │   ├── __init__.py
+│   │   ├── processors/
+│   │   │   ├── __init__.py
+│   │   │   ├── price_processor.py
+│   │   │   ├── volume_processor.py
+│   │   │   └── social_processor.py
+│   │   ├── cache/
+│   │   │   ├── __init__.py
+│   │   │   └── redis_cache.py     # Simple in-memory cache
+│   │   └── validators/
+│   │       ├── __init__.py
+│   │       └── data_validator.py
+│   │
+│   ├── ui/
+│   │   ├── __init__.py
+│   │   ├── gradio_interface.py    # Main UI components
+│   │   ├── components/
+│   │   │   ├── __init__.py
+│   │   │   ├── chat_component.py
+│   │   │   ├── chart_component.py
+│   │   │   └── table_component.py
+│   │   └── styles/
+│   │       ├── custom.css
+│   │       └── theme.py
+│   │
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── airaa_integration.py   # AIRAA-specific API endpoints
+│   │   ├── webhook_handler.py     # For AIRAA integration
+│   │   └── rate_limiter.py        # API rate limiting
+│   │
+│   ├── utils/
+│   │   ├── __init__.py
+│   │   ├── logger.py              # Logging configuration
+│   │   ├── config.py              # Configuration management
+│   │   ├── exceptions.py          # Custom exceptions
+│   │   └── helpers.py             # Utility functions
+│   │
+│   └── visualizations/
+│       ├── __init__.py
+│       ├── plotly_charts.py       # Interactive charts
+│       ├── tables.py              # Data tables
+│       └── export_utils.py        # Data export functions
+│
+├── tests/
+│   ├── __init__.py
+│   ├── test_agent/
+│   │   ├── test_research_agent.py
+│   │   └── test_query_planner.py
+│   ├── test_tools/
+│   │   ├── test_coingecko.py
+│   │   └── test_defillama.py
+│   └── test_integration/
+│       └── test_airaa_integration.py
+│
+├── docs/
+│   ├── API.md                     # API documentation
+│   ├── DEPLOYMENT.md              # Deployment guide
+│   ├── AIRAA_INTEGRATION.md       # AIRAA integration guide
+│   └── USER_GUIDE.md              # User documentation
+│
+├── examples/
+│   ├── sample_queries.py          # Example research queries
+│   ├── api_examples.py            # API usage examples
+│   └── airaa_webhook_example.py   # AIRAA integration example
+│
+└── deployment/
+    ├── docker-compose.yml
+    ├── nginx.conf
+    └── huggingface_spaces/
+        ├── spaces_config.yml
+        └── deployment_script.sh
+```
+
+## 📋 **Detailed Implementation Plan**
+
+### **Phase 1: Foundation Setup (Days 1-2)**
+
+#### Day 1: Project Structure & Core Setup
+```bash
+# Setup commands
+mkdir web3-research-copilot
+cd web3-research-copilot
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install --upgrade pip
+```
+
+**Key Files to Create:**
+
+**requirements.txt**
+```txt
+# Core AI/ML
+langchain==0.1.0
+langchain-google-genai==1.0.0
+langchain-community==0.0.20
+
+# Web Framework
+gradio==4.15.0
+fastapi==0.108.0
+uvicorn==0.25.0
+
+# Data Processing
+pandas==2.1.4
+numpy==1.24.3
+requests==2.31.0
+python-dotenv==1.0.0
+
+# Visualization
+plotly==5.17.0
+matplotlib==3.8.2
+
+# Utilities
+pydantic==2.5.2
+python-dateutil==2.8.2
+tenacity==8.2.3
+
+# Caching & Performance
+diskcache==5.6.3
+asyncio-throttle==1.0.2
+
+# Testing
+pytest==7.4.3
+pytest-asyncio==0.21.1
+```
+
+**src/utils/config.py**
+```python
+import os
+from dotenv import load_dotenv
+from dataclasses import dataclass
+from typing import Optional
+
+load_dotenv()
+
+@dataclass
+class Config:
+    # AI Configuration
+    GEMINI_API_KEY: str = os.getenv("GEMINI_API_KEY")
+    GEMINI_MODEL: str = "gemini-pro"
+    
+    # API Keys
+    COINGECKO_API_KEY: Optional[str] = os.getenv("COINGECKO_API_KEY")
+    ETHERSCAN_API_KEY: str = os.getenv("ETHERSCAN_API_KEY")
+    CRYPTOCOMPARE_API_KEY: Optional[str] = os.getenv("CRYPTOCOMPARE_API_KEY")
+    
+    # Rate Limits (per minute)
+    COINGECKO_RATE_LIMIT: int = 10
+    ETHERSCAN_RATE_LIMIT: int = 5
+    GEMINI_RATE_LIMIT: int = 15
+    
+    # Cache Configuration
+    CACHE_TTL: int = 300  # 5 minutes
+    CACHE_SIZE: int = 100
+    
+    # UI Configuration
+    UI_TITLE: str = "Web3 Research Co-Pilot"
+    UI_DESCRIPTION: str = "AI-powered crypto research assistant"
+    
+    # AIRAA Integration
+    AIRAA_WEBHOOK_URL: Optional[str] = os.getenv("AIRAA_WEBHOOK_URL")
+    AIRAA_API_KEY: Optional[str] = os.getenv("AIRAA_API_KEY")
+    
+    # Logging
+    LOG_LEVEL: str = "INFO"
+    LOG_FILE: str = "app.log"
+
+config = Config()
+```
+
+#### Day 2: Base Tool Architecture
+
+**src/tools/base_tool.py**
+```python
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+from langchain.tools import BaseTool
+from pydantic import BaseModel, Field
+import asyncio
+from tenacity import retry, stop_after_attempt, wait_exponential
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+class Web3ToolInput(BaseModel):
+    query: str = Field(description="The search query or parameter")
+    filters: Optional[Dict[str, Any]] = Field(default=None, description="Additional filters")
+
+class BaseWeb3Tool(BaseTool, ABC):
+    """Base class for all Web3 data tools"""
+    
+    name: str = "base_web3_tool"
+    description: str = "Base Web3 tool"
+    args_schema = Web3ToolInput
+    
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.rate_limiter = self._setup_rate_limiter()
+    
+    @abstractmethod
+    def _setup_rate_limiter(self):
+        """Setup rate limiting for the specific API"""
+        pass
+    
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
+    async def _make_api_call(self, url: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Make rate-limited API call with retry logic"""
+        await self.rate_limiter.acquire()
+        # Implementation will be in specific tools
+        pass
+    
+    @abstractmethod
+    def _process_response(self, response: Dict[str, Any]) -> str:
+        """Process API response into readable format"""
+        pass
+    
+    def _run(self, query: str, filters: Optional[Dict[str, Any]] = None) -> str:
+        """Synchronous tool execution"""
+        return asyncio.run(self._arun(query, filters))
+    
+    @abstractmethod
+    async def _arun(self, query: str, filters: Optional[Dict[str, Any]] = None) -> str:
+        """Asynchronous tool execution"""
+        pass
+```
+
+### **Phase 2: Data Tools Implementation (Days 3-4)**
+
+#### CoinGecko Tool
+**src/tools/coingecko_tool.py**
+```python
+import aiohttp
+from typing import Dict, Any, Optional
+from asyncio_throttle import Throttler
+from src.tools.base_tool import BaseWeb3Tool, Web3ToolInput
+from src.utils.config import config
+
+class CoinGeckoTool(BaseWeb3Tool):
+    name = "coingecko_price_data"
+    description = """
+    Get cryptocurrency price, volume, market cap and trend data from CoinGecko.
+    Useful for: price analysis, market cap rankings, volume trends, price changes.
+    Input should be a cryptocurrency name or symbol (e.g., 'bitcoin', 'ethereum', 'BTC').
+    """
+    
+    def _setup_rate_limiter(self):
+        return Throttler(rate_limit=config.COINGECKO_RATE_LIMIT, period=60)
+    
+    async def _arun(self, query: str, filters: Optional[Dict[str, Any]] = None) -> str:
+        try:
+            # Clean and format the query
+            coin_id = self._format_coin_id(query)
+            
+            # API endpoints
+            base_url = "https://api.coingecko.com/api/v3"
+            
+            if filters and filters.get("type") == "trending":
+                url = f"{base_url}/search/trending"
+                params = {}
+            elif filters and filters.get("type") == "market_data":
+                url = f"{base_url}/coins/{coin_id}"
+                params = {"localization": "false", "tickers": "false", "community_data": "false"}
+            else:
+                url = f"{base_url}/simple/price"
+                params = {
+                    "ids": coin_id,
+                    "vs_currencies": "usd",
+                    "include_24hr_change": "true",
+                    "include_24hr_vol": "true",
+                    "include_market_cap": "true"
+                }
+            
+            async with aiohttp.ClientSession() as session:
+                await self.rate_limiter.acquire()
+                async with session.get(url, params=params) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        return self._process_response(data, filters)
+                    else:
+                        return f"Error fetching data: HTTP {response.status}"
+                        
+        except Exception as e:
+            return f"Error in CoinGecko tool: {str(e)}"
+    
+    def _format_coin_id(self, query: str) -> str:
+        """Convert common symbols to CoinGecko IDs"""
+        symbol_map = {
+            "btc": "bitcoin",
+            "eth": "ethereum", 
+            "usdc": "usd-coin",
+            "usdt": "tether",
+            "bnb": "binancecoin"
+        }
+        return symbol_map.get(query.lower(), query.lower())
+    
+    def _process_response(self, data: Dict[str, Any], filters: Optional[Dict[str, Any]] = None) -> str:
+        """Format CoinGecko response into readable text"""
+        if not data:
+            return "No data found"
+            
+        if filters and filters.get("type") == "trending":
+            trending = data.get("coins", [])[:5]
+            result = "🔥 Trending Cryptocurrencies:\n"
+            for i, coin in enumerate(trending, 1):
+                name = coin.get("item", {}).get("name", "Unknown")
+                symbol = coin.get("item", {}).get("symbol", "")
+                result += f"{i}. {name} ({symbol.upper()})\n"
+            return result
+        
+        elif filters and filters.get("type") == "market_data":
+            name = data.get("name", "Unknown")
+            symbol = data.get("symbol", "").upper()
+            current_price = data.get("market_data", {}).get("current_price", {}).get("usd", 0)
+            market_cap = data.get("market_data", {}).get("market_cap", {}).get("usd", 0)
+            volume_24h = data.get("market_data", {}).get("total_volume", {}).get("usd", 0)
+            price_change_24h = data.get("market_data", {}).get("price_change_percentage_24h", 0)
+            
+            result = f"📊 {name} ({symbol}) Market Data:\n"
+            result += f"💰 Price: ${current_price:,.2f}\n"
+            result += f"📈 24h Change: {price_change_24h:+.2f}%\n"
+            result += f"🏦 Market Cap: ${market_cap:,.0f}\n"
+            result += f"📊 24h Volume: ${volume_24h:,.0f}\n"
+            return result
+        
+        else:
+            # Simple price data
+            result = "💰 Price Data:\n"
+            for coin_id, coin_data in data.items():
+                price = coin_data.get("usd", 0)
+                change_24h = coin_data.get("usd_24h_change", 0)
+                volume_24h = coin_data.get("usd_24h_vol", 0)
+                market_cap = coin_data.get("usd_market_cap", 0)
+                
+                result += f"🪙 {coin_id.title()}:\n"
+                result += f"  💵 Price: ${price:,.2f}\n"
+                result += f"  📈 24h Change: {change_24h:+.2f}%\n"
+                result += f"  📊 Volume: ${volume_24h:,.0f}\n"
+                result += f"  🏦 Market Cap: ${market_cap:,.0f}\n"
+            
+            return result
+```
+
+### **Phase 3: LangChain Agent Implementation (Days 5-6)**
+
+#### Main Research Agent
+**src/agent/research_agent.py**
+```python
+from langchain.agents import AgentExecutor, create_openai_tools_agent
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain.memory import ConversationBufferWindowMemory
+from typing import List, Dict, Any
+import asyncio
+
+from src.tools.coingecko_tool import CoinGeckoTool
+from src.tools.defillama_tool import DeFiLlamaTool
+from src.tools.etherscan_tool import EtherscanTool
+from src.agent.query_planner import QueryPlanner
+from src.utils.config import config
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+class Web3ResearchAgent:
+    def __init__(self):
+        self.llm = ChatGoogleGenerativeAI(
+            model=config.GEMINI_MODEL,
+            google_api_key=config.GEMINI_API_KEY,
+            temperature=0.1,
+            max_tokens=2048
+        )
+        
+        self.tools = self._setup_tools()
+        self.query_planner = QueryPlanner(self.llm)
+        self.memory = ConversationBufferWindowMemory(
+            memory_key="chat_history",
+            return_messages=True,
+            k=10
+        )
+        
+        self.agent = self._create_agent()
+        self.agent_executor = AgentExecutor(
+            agent=self.agent,
+            tools=self.tools,
+            memory=self.memory,
+            verbose=True,
+            max_iterations=5,
+            handle_parsing_errors=True
+        )
+    
+    def _setup_tools(self) -> List:
+        """Initialize all available tools"""
+        return [
+            CoinGeckoTool(),
+            DeFiLlamaTool(),
+            EtherscanTool(),
+        ]
+    
+    def _create_agent(self):
+        """Create the LangChain agent with custom prompt"""
+        system_prompt = """
+        You are an expert Web3 research assistant. Your job is to help users analyze cryptocurrency markets, 
+        DeFi protocols, and blockchain data by using available tools to gather accurate information.
+
+        Available tools:
+        - CoinGecko: Get price, volume, market cap data for cryptocurrencies
+        - DeFiLlama: Get DeFi protocol data, TVL, yields information  
+        - Etherscan: Get on-chain transaction and address data
+
+        Guidelines:
+        1. Break down complex queries into specific, actionable steps
+        2. Use multiple tools when needed to provide comprehensive analysis
+        3. Always cite your data sources in responses
+        4. Format responses with clear headers, bullet points, and emojis for readability
+        5. If data is unavailable, suggest alternative approaches or mention limitations
+        6. Provide context and explanations for technical terms
+        7. Include relevant charts or visualizations when possible
+
+        When responding:
+        - Start with a brief summary
+        - Present data in organized sections
+        - Include methodology notes
+        - End with key insights or actionable conclusions
+        """
+        
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", system_prompt),
+            MessagesPlaceholder("chat_history"),
+            ("human", "{input}"),
+            MessagesPlaceholder("agent_scratchpad")
+        ])
+        
+        return create_openai_tools_agent(
+            llm=self.llm,
+            tools=self.tools,
+            prompt=prompt
+        )
+    
+    async def research_query(self, query: str) -> Dict[str, Any]:
+        """Main entry point for research queries"""
+        try:
+            logger.info(f"Processing query: {query}")
+            
+            # Plan the research approach
+            research_plan = await self.query_planner.plan_research(query)
+            logger.info(f"Research plan: {research_plan}")
+            
+            # Execute the research
+            result = await self._execute_research(query, research_plan)
+            
+            # Format and return response
+            return {
+                "success": True,
+                "query": query,
+                "research_plan": research_plan,
+                "result": result,
+                "sources": self._extract_sources(result),
+                "metadata": {
+                    "tools_used": [tool.name for tool in self.tools],
+                    "timestamp": self._get_timestamp()
+                }
+            }
+            
+        except Exception as e:
+            logger.error(f"Error processing query: {str(e)}")
+            return {
+                "success": False,
+                "query": query,
+                "error": str(e),
+                "metadata": {"timestamp": self._get_timestamp()}
+            }
+    
+    async def _execute_research(self, query: str, plan: Dict[str, Any]) -> str:
+        """Execute the research plan using LangChain agent"""
+        try:
+            # Add planning context to the query
+            enhanced_query = f"""
+            Research Query: {query}
+            
+            Research Plan: {plan.get('steps', [])}
+            Priority Focus: {plan.get('priority', 'general analysis')}
+            
+            Please execute this research systematically and provide a comprehensive analysis.
+            """
+            
+            response = await asyncio.to_thread(
+                self.agent_executor.invoke,
+                {"input": enhanced_query}
+            )
+            
+            return response.get("output", "No response generated")
+            
+        except Exception as e:
+            logger.error(f"Error executing research: {str(e)}")
+            return f"Research execution error: {str(e)}"
+    
+    def _extract_sources(self, result: str) -> List[str]:
+        """Extract data sources from the result"""
+        sources = []
+        if "CoinGecko" in result:
+            sources.append("CoinGecko API")
+        if "DeFiLlama" in result:
+            sources.append("DeFiLlama API")
+        if "Etherscan" in result:
+            sources.append("Etherscan API")
+        return sources
+    
+    def _get_timestamp(self) -> str:
+        """Get current timestamp"""
+        from datetime import datetime
+        return datetime.now().isoformat()
+```
+
+### **Phase 4: UI & Integration (Days 7-8)**
+
+#### Main Gradio Application
+**app.py**
+```python
+import gradio as gr
+import asyncio
+import json
+from datetime import datetime
+from typing import List, Tuple
+
+from src.agent.research_agent import Web3ResearchAgent
+from src.api.airaa_integration import AIRAAIntegration
+from src.visualizations.plotly_charts import create_price_chart, create_volume_chart
+from src.utils.config import config
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+class Web3CoPilotApp:
+    def __init__(self):
+        self.agent = Web3ResearchAgent()
+        self.airaa_integration = AIRAAIntegration()
+        
+    def create_interface(self):
+        """Create the main Gradio interface"""
+        
+        # Custom CSS for better styling
+        custom_css = """
+        .container { max-width: 1200px; margin: 0 auto; }
+        .chat-container { height: 600px; }
+        .query-box { font-size: 16px; }
+        .examples-box { background: #f8f9fa; padding: 15px; border-radius: 8px; }
+        """
+        
+        with gr.Blocks(
+            title=config.UI_TITLE,
+            css=custom_css,
+            theme=gr.themes.Soft()
+        ) as demo:
+            
+            # Header
+            gr.Markdown(f"""
+            # 🚀 {config.UI_TITLE}
+            
+            {config.UI_DESCRIPTION}
+            
+            **Powered by**: Gemini AI • CoinGecko • DeFiLlama • Etherscan
+            """)
+            
+            with gr.Row():
+                with gr.Column(scale=2):
+                    # Main Chat Interface
+                    chatbot = gr.Chatbot(
+                        label="Research Assistant",
+                        height=600,
+                        show_label=True,
+                        container=True,
+                        elem_classes=["chat-container"]
+                    )
+                    
+                    with gr.Row():
+                        query_input = gr.Textbox(
+                            placeholder="Ask me about crypto markets, DeFi protocols, or on-chain data...",
+                            label="Research Query",
+                            lines=2,
+                            elem_classes=["query-box"]
+                        )
+                        submit_btn = gr.Button("🔍 Research", variant="primary")
+                    
+                    # Quick action buttons
+                    with gr.Row():
+                        clear_btn = gr.Button("🗑️ Clear", variant="secondary")
+                        export_btn = gr.Button("📊 Export", variant="secondary")
+                
+                with gr.Column(scale=1):
+                    # Example queries sidebar
+                    gr.Markdown("### 💡 Example Queries")
+                    
+                    examples = [
+                        "What's the current price and 24h change for Bitcoin?",
+                        "Show me top DeFi protocols by TVL",
+                        "Which tokens had highest volume yesterday?", 
+                        "Compare Ethereum vs Solana market metrics",
+                        "What are the trending cryptocurrencies today?"
+                    ]
+                    
+                    for example in examples:
+                        example_btn = gr.Button(example, size="sm")
+                        example_btn.click(
+                            lambda x=example: x,
+                            outputs=query_input
+                        )
+                    
+                    # Data visualization area
+                    gr.Markdown("### 📈 Visualizations")
+                    chart_output = gr.Plot(label="Charts")
+                    
+                    # Export options
+                    gr.Markdown("### 📤 Export Options")
+                    export_format = gr.Radio(
+                        choices=["JSON", "CSV", "PDF"],
+                        value="JSON",
+                        label="Format"
+                    )
+            
+            # Chat functionality
+            def respond(message: str, history: List[Tuple[str, str]]):
+                """Process user message and generate response"""
+                if not message.strip():
+                    return history, ""
+                
+                try:
+                    # Show loading message
+                    history.append((message, "🔍 Researching... Please wait."))
+                    yield history, ""
+                    
+                    # Process the query
+                    result = asyncio.run(self.agent.research_query(message))
+                    
+                    if result["success"]:
+                        response = result["result"]
+                        
+                        # Add metadata footer
+                        sources = ", ".join(result["sources"])
+                        response += f"\n\n---\n📊 **Sources**: {sources}"
+                        response += f"\n⏰ **Generated**: {datetime.now().strftime('%H:%M:%S')}"
+                        
+                        # Send to AIRAA if configured
+                        if config.AIRAA_WEBHOOK_URL:
+                            asyncio.run(self.airaa_integration.send_research_data(result))
+                    
+                    else:
+                        response = f"❌ Error: {result.get('error', 'Unknown error occurred')}"
+                    
+                    # Update history
+                    history[-1] = (message, response)
+                    
+                except Exception as e:
+                    logger.error(f"Error in respond: {str(e)}")
+                    history[-1] = (message, f"❌ System error: {str(e)}")
+                
+                yield history, ""
+            
+            def clear_chat():
+                """Clear chat history"""
+                return [], ""
+            
+            def export_conversation(history: List[Tuple[str, str]], format_type: str):
+                """Export conversation in selected format"""
+                try:
+                    if format_type == "JSON":
+                        data = {
+                            "conversation": [{"query": q, "response": r} for q, r in history],
+                            "exported_at": datetime.now().isoformat()
+                        }
+                        return json.dumps(data, indent=2)
+                    
+                    elif format_type == "CSV":
+                        import csv
+                        import io
+                        output = io.StringIO()
+                        writer = csv.writer(output)
+                        writer.writerow(["Query", "Response", "Timestamp"])
+                        for q, r in history:
+                            writer.writerow([q, r, datetime.now().isoformat()])
+                        return output.getvalue()
+                    
+                    else:  # PDF
+                        return "PDF export not implemented yet"
+                        
+                except Exception as e:
+                    return f"Export error: {str(e)}"
+            
+            # Event handlers
+            submit_btn.click(
+                respond,
+                inputs=[query_input, chatbot],
+                outputs=[chatbot, query_input]
+            )
+            
+            query_input.submit(
+                respond,
+                inputs=[query_input, chatbot], 
+                outputs=[chatbot, query_input]
+            )
+            
+            clear_btn.click(
+                clear_chat,
+                outputs=[chatbot, query_input]
+            )
+            
+            export_btn.click(
+                export_conversation,
+                inputs=[chatbot, export_format],
+                outputs=gr.Textbox(label="Exported Data")
+            )
+        
+        return demo
+
+if __name__ == "__main__":
+    app = Web3CoPilotApp()
+    interface = app.create_interface()
+    
+    interface.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=True,
+        show_api=True
+    )
+```
+
+### **Phase 5: AIRAA Integration & Deployment**
+
+#### AIRAA Integration Module
+**src/api/airaa_integration.py**
+```python
+import aiohttp
+import json
+from typing import Dict, Any, Optional
+from src.utils.config import config
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+class AIRAAIntegration:
+    """Handle integration with AIRAA platform"""
+    
+    def __init__(self):
+        self.webhook_url = config.AIRAA_WEBHOOK_URL
+        self.api_key = config.AIRAA_API_KEY
+        self.enabled = bool(self.webhook_url)
+    
+    async def send_research_data(self, research_result: Dict[str, Any]) -> bool:
+        """Send research data to AIRAA webhook"""
+        if not self.enabled:
+            logger.info("AIRAA integration not configured, skipping")
+            return False
+        
+        try:
+            payload = self._format_for_airaa(research_result)
+            
+            headers = {
+                "Content-Type": "application/json",
+                "User-Agent": "Web3-Research-Copilot/1.0"
+            }
+            
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    self.webhook_url,
+                    json=payload,
+                    headers=headers,
+                    timeout=aiohttp.ClientTimeout(total=30)
+                ) as response:
+                    
+                    if response.status == 200:
+                        logger.info("Successfully sent data to AIRAA")
+                        return True
+                    else:
+                        logger.warning(f"AIRAA webhook returned {response.status}")
+                        return False
+                        
+        except Exception as e:
+            logger.error(f"Failed to send data to AIRAA: {str(e)}")
+            return False
+    
+    def _format_for_airaa(self, research_result: Dict[str, Any]) -> Dict[str, Any]:
+        """Format research result for AIRAA consumption"""
+        return {
+            "source": "web3-research-copilot",
+            "timestamp": research_result["metadata"]["timestamp"],
+            "query": research_result["query"],
+            "research_plan": research_result.get("research_plan"),
+            "findings": research_result["result"],
+            "data_sources": research_result["sources"],
+            "confidence_score": self._calculate_confidence(research_result),
+            "tags": self._extract_tags(research_result["query"]),
+            "structured_data": self._extract_structured_data(research_result["result"])
+        }
+    
+    def _calculate_confidence(self, result: Dict[str, Any]) -> float:
+        """Calculate confidence score based on data sources and completeness"""
+        base_score = 0.7
+        
+        # Boost for multiple sources
+        source_count = len(result.get("sources", []))
+        source_boost = min(source_count * 0.1, 0.3)
+        
+        # Reduce for errors
+        error_penalty = 0.3 if not result.get("success", True) else 0
+        
+        return max(0.0, min(1.0, base_score + source_boost - error_penalty))
+    
+    def _extract_tags(self, query: str) -> List[str]:
+        """Extract relevant tags from query"""
+        tags = []
+        query_lower = query.lower()
+        
+        # Asset tags
+        if any(word in query_lower for word in ["bitcoin", "btc"]):
+            tags.append("bitcoin")
+        if any(word in query_lower for word in ["ethereum", "eth"]):
+            tags.append("ethereum")
+        
+        # Category tags
+        if any(word in query_lower for word in ["defi", "defillama"]):
+            tags.append("defi")
+        if any(word in query_lower for word in ["price", "market"]):
+            tags.append("market-analysis")
+        if any(word in query_lower for word in ["volume", "trading"]):
+            tags.append("trading-volume")
+        
+        return tags
+    
+    def _extract_structured_data(self, result_text: str) -> Dict[str, Any]:
+        """Extract structured data from result text"""
+        structured = {}
+        
+        # Extract price data (simple regex matching)
+        import re
+        
+        price_matches = re.findall(r'\$([0-9,]+\.?[0-9]*)', result_text)
+        if price_matches:
+            structured["prices"] = [float(p.replace(',', '')) for p in price_matches[:5]]
+        
+        percentage_matches = re.findall(r'([+-]?[0-9]+\.?[0-9]*)%', result_text)
+        if percentage_matches:
+            structured["percentages"] = [float(p) for p in percentage_matches[:5]]
+        
+        return structured
+```
+
+## 🚀 **Deployment Configuration**
+
+### **Hugging Face Spaces Configuration**
+
+**deployment/huggingface_spaces/spaces_config.yml**
+```yaml
+title: "Web3 Research Co-Pilot"
+emoji: "🚀"
+colorFrom: "blue"
+colorTo: "purple"
+sdk: "gradio"
+sdk_version: "4.15.0"
+app_file: "app.py"
+pinned: false
+license: "mit"
+
+# Environment variables needed
+secrets:
+  - GEMINI_API_KEY
+  - ETHERSCAN_API_KEY
+  - AIRAA_WEBHOOK_URL
+  - AIRAA_API_KEY
+
+# Resource requirements
+hardware: "cpu-basic"  # Free tier
+```
+
+### **Docker Configuration** 
+**Dockerfile**
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Expose port
+EXPOSE 7860
+
+# Set environment variables
+ENV PYTHONPATH=/app
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+
+# Run the application
+CMD ["python", "app.py"]
+```
+
+## 📊 **Testing Strategy**
+
+### **Unit Tests**
+```python
+# tests/test_tools/test_coingecko.py
+import pytest
+import asyncio
+from src.tools.coingecko_tool import CoinGeckoTool
+
+@pytest.fixture
+def coingecko_tool():
+    return CoinGeckoTool()
+
+@pytest.mark.asyncio
+async def test_bitcoin_price_fetch(coingecko_tool):
+    result = await coingecko_tool._arun("bitcoin")
+    assert "Price:" in result
+    assert "bitcoin" in result.lower()
+
+@pytest.mark.asyncio  
+async def test_trending_coins(coingecko_tool):
+    result = await coingecko_tool._arun("trending", {"type": "trending"})
+    assert "Trending" in result
+```
+
+## 📅 **8-Day Development Timeline**
+
+### **Detailed Daily Schedule**
+
+**Days 1-2: Foundation**
+- ✅ Project structure setup
+- ✅ Configuration management
+- ✅ Base tool architecture
+- ✅ Logging and utilities
+
+**Days 3-4: Core Tools**
+- ✅ CoinGecko integration (price data)
+- ✅ DeFiLlama integration (DeFi data) 
+- ✅ Etherscan integration (on-chain data)
+- ✅ Rate limiting and error handling
+
+**Days 5-6: AI Agent**
+- ✅ LangChain agent setup
+- ✅ Query planning logic
+- ✅ Memory management
+- ✅ Response formatting
+
+**Days 7-8: UI & Deployment**
+- ✅ Gradio interface
+- ✅ AIRAA integration
+- ✅ HuggingFace Spaces deployment
+- ✅ Testing and documentation
+
+This comprehensive plan provides a production-ready Web3 research co-pilot that integrates seamlessly with AIRAA's platform while utilizing only free resources and APIs.

pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "repl-nix-workspace"
+version = "0.1.0"
+description = "Add your description here"
+requires-python = ">=3.11"
+dependencies = [
+    "aiohttp>=3.12.15",
+    "asyncio-throttle>=1.0.2",
+    "diskcache>=5.6.3",
+    "google-genai>=1.29.0",
+    "gradio>=5.42.0",
+    "langchain>=0.3.27",
+    "langchain-community>=0.3.27",
+    "langchain-google-genai>=2.1.9",
+    "numpy>=2.3.2",
+    "pandas>=2.3.1",
+    "plotly>=6.2.0",
+    "pydantic>=2.11.7",
+    "python-dateutil>=2.9.0.post0",
+    "python-dotenv>=1.1.1",
+    "streamlit>=1.48.0",
+    "tenacity>=9.1.2",
+    "trafilatura>=2.0.0",
+]

requirements.txt

@@ -0,0 +1,7 @@
+aiohttp==3.10.11
+gradio==5.8.0
+google-generativeai==0.8.3
+plotly==5.24.1
+pandas==2.2.3
+python-dotenv==1.0.1
+asyncio-throttle==1.0.2

src/api_clients.py

@@ -0,0 +1,158 @@
+import aiohttp
+import asyncio
+import time
+from typing import Dict, Any, Optional, List
+from src.config import config
+import json
+
+class RateLimiter:
+    def __init__(self, delay: float):
+        self.delay = delay
+        self.last_call = 0
+    
+    async def acquire(self):
+        now = time.time()
+        elapsed = now - self.last_call
+        if elapsed < self.delay:
+            await asyncio.sleep(self.delay - elapsed)
+        self.last_call = time.time()
+
+class CoinGeckoClient:
+    def __init__(self):
+        self.rate_limiter = RateLimiter(config.RATE_LIMIT_DELAY)
+        self.session = None
+    
+    async def get_session(self):
+        if self.session is None:
+            timeout = aiohttp.ClientTimeout(total=config.REQUEST_TIMEOUT)
+            self.session = aiohttp.ClientSession(timeout=timeout)
+        return self.session
+    
+    async def _make_request(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        await self.rate_limiter.acquire()
+        
+        url = f"{config.COINGECKO_BASE_URL}/{endpoint}"
+        if params is None:
+            params = {}
+        
+        if config.COINGECKO_API_KEY:
+            params["x_cg_demo_api_key"] = config.COINGECKO_API_KEY
+        
+        session = await self.get_session()
+        
+        for attempt in range(config.MAX_RETRIES):
+            try:
+                async with session.get(url, params=params) as response:
+                    if response.status == 200:
+                        return await response.json()
+                    elif response.status == 429:
+                        await asyncio.sleep(2 ** attempt)
+                        continue
+                    else:
+                        raise Exception(f"API error: {response.status}")
+            except asyncio.TimeoutError:
+                if attempt == config.MAX_RETRIES - 1:
+                    raise Exception("Request timeout")
+                await asyncio.sleep(1)
+        
+        raise Exception("Max retries exceeded")
+    
+    async def get_price(self, coin_ids: str, vs_currencies: str = "usd") -> Dict[str, Any]:
+        params = {
+            "ids": coin_ids,
+            "vs_currencies": vs_currencies,
+            "include_24hr_change": "true",
+            "include_24hr_vol": "true",
+            "include_market_cap": "true"
+        }
+        return await self._make_request("simple/price", params)
+    
+    async def get_trending(self) -> Dict[str, Any]:
+        return await self._make_request("search/trending")
+    
+    async def get_global_data(self) -> Dict[str, Any]:
+        return await self._make_request("global")
+    
+    async def get_coin_data(self, coin_id: str) -> Dict[str, Any]:
+        params = {"localization": "false", "tickers": "false", "community_data": "false"}
+        return await self._make_request(f"coins/{coin_id}", params)
+    
+    async def get_market_data(self, vs_currency: str = "usd", per_page: int = 10) -> Dict[str, Any]:
+        params = {
+            "vs_currency": vs_currency,
+            "order": "market_cap_desc",
+            "per_page": per_page,
+            "page": 1,
+            "sparkline": "false"
+        }
+        return await self._make_request("coins/markets", params)
+    
+    async def get_price_history(self, coin_id: str, days: int = 7) -> Dict[str, Any]:
+        params = {"vs_currency": "usd", "days": days}
+        return await self._make_request(f"coins/{coin_id}/market_chart", params)
+    
+    async def close(self):
+        if self.session:
+            await self.session.close()
+
+class CryptoCompareClient:
+    def __init__(self):
+        self.rate_limiter = RateLimiter(config.RATE_LIMIT_DELAY)
+        self.session = None
+    
+    async def get_session(self):
+        if self.session is None:
+            timeout = aiohttp.ClientTimeout(total=config.REQUEST_TIMEOUT)
+            self.session = aiohttp.ClientSession(timeout=timeout)
+        return self.session
+    
+    async def _make_request(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        await self.rate_limiter.acquire()
+        
+        url = f"{config.CRYPTOCOMPARE_BASE_URL}/{endpoint}"
+        if params is None:
+            params = {}
+        
+        if config.CRYPTOCOMPARE_API_KEY:
+            params["api_key"] = config.CRYPTOCOMPARE_API_KEY
+        
+        session = await self.get_session()
+        
+        for attempt in range(config.MAX_RETRIES):
+            try:
+                async with session.get(url, params=params) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        if data.get("Response") == "Error":
+                            raise Exception(data.get("Message", "API error"))
+                        return data
+                    elif response.status == 429:
+                        await asyncio.sleep(2 ** attempt)
+                        continue
+                    else:
+                        raise Exception(f"API error: {response.status}")
+            except asyncio.TimeoutError:
+                if attempt == config.MAX_RETRIES - 1:
+                    raise Exception("Request timeout")
+                await asyncio.sleep(1)
+        
+        raise Exception("Max retries exceeded")
+    
+    async def get_price_multi(self, fsyms: str, tsyms: str = "USD") -> Dict[str, Any]:
+        params = {"fsyms": fsyms, "tsyms": tsyms}
+        return await self._make_request("pricemulti", params)
+    
+    async def get_social_data(self, coin_symbol: str) -> Dict[str, Any]:
+        params = {"coinSymbol": coin_symbol}
+        return await self._make_request("social/coin/latest", params)
+    
+    async def get_news(self, categories: str = "blockchain") -> Dict[str, Any]:
+        params = {"categories": categories}
+        return await self._make_request("news/", params)
+    
+    async def close(self):
+        if self.session:
+            await self.session.close()
+
+coingecko_client = CoinGeckoClient()
+cryptocompare_client = CryptoCompareClient()

src/cache_manager.py

@@ -0,0 +1,49 @@
+import time
+from typing import Any, Optional, Dict
+from src.config import config
+
+class CacheManager:
+    def __init__(self, default_ttl: Optional[int] = None):
+        self.cache: Dict[str, Dict[str, Any]] = {}
+        self.default_ttl = default_ttl or config.CACHE_TTL
+    
+    def get(self, key: str) -> Optional[Any]:
+        if key not in self.cache:
+            return None
+        
+        entry = self.cache[key]
+        if time.time() > entry["expires_at"]:
+            del self.cache[key]
+            return None
+        
+        return entry["data"]
+    
+    def set(self, key: str, data: Any, ttl: Optional[int] = None) -> None:
+        expires_at = time.time() + (ttl or self.default_ttl)
+        self.cache[key] = {
+            "data": data,
+            "expires_at": expires_at
+        }
+    
+    def delete(self, key: str) -> bool:
+        return self.cache.pop(key, None) is not None
+    
+    def clear(self) -> None:
+        self.cache.clear()
+    
+    def cleanup_expired(self) -> int:
+        current_time = time.time()
+        expired_keys = [
+            key for key, entry in self.cache.items()
+            if current_time > entry["expires_at"]
+        ]
+        
+        for key in expired_keys:
+            del self.cache[key]
+        
+        return len(expired_keys)
+    
+    def size(self) -> int:
+        return len(self.cache)
+
+cache_manager = CacheManager()

src/config.py

@@ -0,0 +1,19 @@
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class Config:
+    GEMINI_API_KEY: str = os.getenv("GEMINI_API_KEY", "")
+    COINGECKO_API_KEY: Optional[str] = os.getenv("COINGECKO_API_KEY")
+    CRYPTOCOMPARE_API_KEY: Optional[str] = os.getenv("CRYPTOCOMPARE_API_KEY")
+    
+    COINGECKO_BASE_URL: str = "https://api.coingecko.com/api/v3"
+    CRYPTOCOMPARE_BASE_URL: str = "https://min-api.cryptocompare.com/data"
+    
+    CACHE_TTL: int = 300
+    RATE_LIMIT_DELAY: float = 2.0
+    MAX_RETRIES: int = 3
+    REQUEST_TIMEOUT: int = 30
+
+config = Config()

src/defillama_client.py

@@ -0,0 +1,62 @@
+import aiohttp
+import asyncio
+from typing import Dict, Any, List, Optional
+from src.config import config
+
+class DeFiLlamaClient:
+    def __init__(self):
+        self.base_url = "https://api.llama.fi"
+        self.session = None
+        self.rate_limiter = None
+    
+    async def get_session(self):
+        if self.session is None:
+            timeout = aiohttp.ClientTimeout(total=30)
+            self.session = aiohttp.ClientSession(timeout=timeout)
+        return self.session
+    
+    async def _make_request(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        url = f"{self.base_url}/{endpoint}"
+        session = await self.get_session()
+        
+        for attempt in range(3):
+            try:
+                async with session.get(url, params=params) as response:
+                    if response.status == 200:
+                        return await response.json()
+                    elif response.status == 429:
+                        await asyncio.sleep(2 ** attempt)
+                        continue
+                    else:
+                        raise Exception(f"API error: {response.status}")
+            except Exception as e:
+                if attempt == 2:
+                    raise e
+                await asyncio.sleep(1)
+    
+    async def get_protocols(self) -> List[Dict[str, Any]]:
+        return await self._make_request("protocols")
+    
+    async def get_protocol_data(self, protocol: str) -> Dict[str, Any]:
+        return await self._make_request(f"protocol/{protocol}")
+    
+    async def get_tvl_data(self) -> Dict[str, Any]:
+        return await self._make_request("v2/historicalChainTvl")
+    
+    async def get_chain_tvl(self, chain: str) -> Dict[str, Any]:
+        return await self._make_request(f"v2/historicalChainTvl/{chain}")
+    
+    async def get_yields(self) -> List[Dict[str, Any]]:
+        return await self._make_request("pools")
+    
+    async def get_bridges(self) -> List[Dict[str, Any]]:
+        return await self._make_request("bridges")
+    
+    async def get_dex_volume(self) -> Dict[str, Any]:
+        return await self._make_request("overview/dexs")
+    
+    async def close(self):
+        if self.session:
+            await self.session.close()
+
+defillama_client = DeFiLlamaClient()

src/enhanced_agent.py

@@ -0,0 +1,273 @@
+import google.generativeai as genai
+import json
+import asyncio
+from typing import Dict, Any, List, Optional
+from src.api_clients import coingecko_client, cryptocompare_client
+from src.defillama_client import defillama_client
+from src.news_aggregator import news_aggregator
+from src.cache_manager import cache_manager
+from src.config import config
+
+class EnhancedResearchAgent:
+    def __init__(self):
+        if config.GEMINI_API_KEY:
+            genai.configure(api_key=config.GEMINI_API_KEY)
+            self.model = genai.GenerativeModel('gemini-1.5-flash')
+        else:
+            self.model = None
+            
+        self.symbol_map = {
+            "btc": "bitcoin", "eth": "ethereum", "sol": "solana", "ada": "cardano",
+            "dot": "polkadot", "bnb": "binancecoin", "usdc": "usd-coin", 
+            "usdt": "tether", "xrp": "ripple", "avax": "avalanche-2",
+            "link": "chainlink", "matic": "matic-network", "uni": "uniswap",
+            "atom": "cosmos", "near": "near", "icp": "internet-computer",
+            "ftm": "fantom", "algo": "algorand", "xlm": "stellar"
+        }
+    
+    def _format_coin_id(self, symbol: str) -> str:
+        return self.symbol_map.get(symbol.lower(), symbol.lower())
+    
+    async def get_comprehensive_market_data(self) -> Dict[str, Any]:
+        cache_key = "comprehensive_market"
+        cached = cache_manager.get(cache_key)
+        if cached:
+            return cached
+        
+        try:
+            tasks = [
+                coingecko_client.get_market_data(per_page=50),
+                coingecko_client.get_global_data(),
+                coingecko_client.get_trending(),
+                defillama_client.get_protocols(),
+                defillama_client.get_tvl_data(),
+                news_aggregator.get_crypto_news(5)
+            ]
+            
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            
+            data = {}
+            for i, result in enumerate(results):
+                if not isinstance(result, Exception):
+                    if i == 0: data["market_data"] = result
+                    elif i == 1: data["global_data"] = result
+                    elif i == 2: data["trending"] = result
+                    elif i == 3: 
+                        data["defi_protocols"] = result[:20] if isinstance(result, list) and result else []
+                    elif i == 4: data["tvl_data"] = result
+                    elif i == 5: data["news"] = result
+            
+            cache_manager.set(cache_key, data, 180)
+            return data
+            
+        except Exception as e:
+            raise Exception(f"Failed to fetch comprehensive market data: {str(e)}")
+    
+    async def get_defi_analysis(self, protocol: Optional[str] = None) -> Dict[str, Any]:
+        cache_key = f"defi_analysis_{protocol or 'overview'}"
+        cached = cache_manager.get(cache_key)
+        if cached:
+            return cached
+        
+        try:
+            if protocol:
+                data = await defillama_client.get_protocol_data(protocol)
+            else:
+                protocols = await defillama_client.get_protocols()
+                tvl_data = await defillama_client.get_tvl_data()
+                yields_data = await defillama_client.get_yields()
+                
+                data = {
+                    "top_protocols": protocols[:20] if isinstance(protocols, list) and protocols else [],
+                    "tvl_overview": tvl_data,
+                    "top_yields": yields_data[:10] if isinstance(yields_data, list) and yields_data else []
+                }
+            
+            cache_manager.set(cache_key, data, 300)
+            return data
+            
+        except Exception as e:
+            raise Exception(f"Failed to get DeFi analysis: {str(e)}")
+    
+    async def get_price_history(self, symbol: str, days: int = 30) -> Dict[str, Any]:
+        cache_key = f"price_history_{symbol}_{days}"
+        cached = cache_manager.get(cache_key)
+        if cached:
+            return cached
+        
+        try:
+            coin_id = self._format_coin_id(symbol)
+            data = await coingecko_client.get_price_history(coin_id, days)
+            cache_manager.set(cache_key, data, 900)
+            return data
+        except Exception as e:
+            raise Exception(f"Failed to get price history for {symbol}: {str(e)}")
+    
+    async def get_advanced_coin_analysis(self, symbol: str) -> Dict[str, Any]:
+        cache_key = f"advanced_analysis_{symbol.lower()}"
+        cached = cache_manager.get(cache_key)
+        if cached:
+            return cached
+        
+        try:
+            coin_id = self._format_coin_id(symbol)
+            
+            tasks = [
+                coingecko_client.get_coin_data(coin_id),
+                coingecko_client.get_price_history(coin_id, days=30),
+                cryptocompare_client.get_social_data(symbol.upper()),
+                self._get_defi_involvement(symbol.upper())
+            ]
+            
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            
+            analysis = {}
+            for i, result in enumerate(results):
+                if not isinstance(result, Exception):
+                    if i == 0: analysis["coin_data"] = result
+                    elif i == 1: analysis["price_history"] = result
+                    elif i == 2: analysis["social_data"] = result
+                    elif i == 3: analysis["defi_data"] = result
+            
+            cache_manager.set(cache_key, analysis, 300)
+            return analysis
+            
+        except Exception as e:
+            raise Exception(f"Failed advanced analysis for {symbol}: {str(e)}")
+    
+    async def _get_defi_involvement(self, symbol: str) -> Dict[str, Any]:
+        try:
+            protocols = await defillama_client.get_protocols()
+            if protocols:
+                relevant_protocols = [p for p in protocols if symbol.lower() in p.get("name", "").lower()]
+                return {"protocols": relevant_protocols[:5]}
+            return {"protocols": []}
+        except:
+            return {"protocols": []}
+    
+    def _format_comprehensive_data(self, data: Dict[str, Any]) -> str:
+        formatted = "📊 COMPREHENSIVE CRYPTO MARKET ANALYSIS\n\n"
+        
+        if "global_data" in data and data["global_data"].get("data"):
+            global_info = data["global_data"]["data"]
+            total_mcap = global_info.get("total_market_cap", {}).get("usd", 0)
+            total_volume = global_info.get("total_volume", {}).get("usd", 0)
+            btc_dominance = global_info.get("market_cap_percentage", {}).get("btc", 0)
+            eth_dominance = global_info.get("market_cap_percentage", {}).get("eth", 0)
+            
+            formatted += f"💰 Total Market Cap: ${total_mcap/1e12:.2f}T\n"
+            formatted += f"📈 24h Volume: ${total_volume/1e9:.1f}B\n"
+            formatted += f"₿ Bitcoin Dominance: {btc_dominance:.1f}%\n"
+            formatted += f"Ξ Ethereum Dominance: {eth_dominance:.1f}%\n\n"
+        
+        if "trending" in data and data["trending"].get("coins"):
+            formatted += "🔥 TRENDING CRYPTOCURRENCIES\n"
+            for i, coin in enumerate(data["trending"]["coins"][:5], 1):
+                name = coin.get("item", {}).get("name", "Unknown")
+                symbol = coin.get("item", {}).get("symbol", "")
+                score = coin.get("item", {}).get("score", 0)
+                formatted += f"{i}. {name} ({symbol.upper()}) - Score: {score}\n"
+            formatted += "\n"
+        
+        if "defi_protocols" in data and data["defi_protocols"]:
+            formatted += "🏦 TOP DeFi PROTOCOLS\n"
+            for i, protocol in enumerate(data["defi_protocols"][:5], 1):
+                name = protocol.get("name", "Unknown")
+                tvl = protocol.get("tvl", 0)
+                chain = protocol.get("chain", "Unknown")
+                formatted += f"{i}. {name} ({chain}): ${tvl/1e9:.2f}B TVL\n"
+            formatted += "\n"
+        
+        if "news" in data and data["news"]:
+            formatted += "📰 LATEST CRYPTO NEWS\n"
+            for i, article in enumerate(data["news"][:3], 1):
+                title = article.get("title", "No title")[:60] + "..."
+                source = article.get("source", "Unknown")
+                formatted += f"{i}. {title} - {source}\n"
+            formatted += "\n"
+        
+        if "market_data" in data and data["market_data"]:
+            formatted += "💎 TOP PERFORMING COINS (24h)\n"
+            valid_coins = [coin for coin in data["market_data"][:20] if coin.get("price_change_percentage_24h") is not None]
+            sorted_coins = sorted(valid_coins, key=lambda x: x.get("price_change_percentage_24h", 0), reverse=True)
+            for i, coin in enumerate(sorted_coins[:5], 1):
+                name = coin.get("name", "Unknown")
+                symbol = coin.get("symbol", "").upper()
+                price = coin.get("current_price", 0)
+                change = coin.get("price_change_percentage_24h", 0)
+                formatted += f"{i}. {name} ({symbol}): ${price:,.4f} (+{change:.2f}%)\n"
+        
+        return formatted
+    
+    async def research_with_context(self, query: str) -> str:
+        try:
+            if not config.GEMINI_API_KEY or not self.model:
+                return "❌ Gemini API key not configured. Please set GEMINI_API_KEY environment variable."
+            
+            system_prompt = """You are an advanced Web3 and DeFi research analyst with access to real-time market data, 
+            DeFi protocol information, social sentiment, and breaking news. Provide comprehensive, actionable insights 
+            that combine multiple data sources for superior analysis.
+            
+            Guidelines:
+            - Synthesize data from multiple sources (price, DeFi, social, news)
+            - Provide specific recommendations with risk assessments
+            - Include both technical and fundamental analysis
+            - Reference current market conditions and news events
+            - Use clear, professional language with data-driven insights
+            - Highlight opportunities and risks clearly
+            """
+            
+            market_context = ""
+            try:
+                if any(keyword in query.lower() for keyword in 
+                       ["market", "overview", "analysis", "trending", "defi", "protocols"]):
+                    comprehensive_data = await self.get_comprehensive_market_data()
+                    market_context = f"\n\nCURRENT MARKET ANALYSIS:\n{self._format_comprehensive_data(comprehensive_data)}"
+                
+                for symbol in self.symbol_map.keys():
+                    if symbol in query.lower() or symbol.upper() in query:
+                        analysis_data = await self.get_advanced_coin_analysis(symbol)
+                        if "coin_data" in analysis_data:
+                            coin_info = analysis_data["coin_data"]
+                            market_data = coin_info.get("market_data", {})
+                            current_price = market_data.get("current_price", {}).get("usd", 0)
+                            price_change = market_data.get("price_change_percentage_24h", 0)
+                            market_cap = market_data.get("market_cap", {}).get("usd", 0)
+                            volume = market_data.get("total_volume", {}).get("usd", 0)
+                            ath = market_data.get("ath", {}).get("usd", 0)
+                            ath_change = market_data.get("ath_change_percentage", {}).get("usd", 0)
+                            
+                            market_context += f"\n\n{symbol.upper()} DETAILED ANALYSIS:\n"
+                            market_context += f"Current Price: ${current_price:,.4f}\n"
+                            market_context += f"24h Change: {price_change:+.2f}%\n"
+                            market_context += f"Market Cap: ${market_cap/1e9:.2f}B\n"
+                            market_context += f"24h Volume: ${volume/1e9:.2f}B\n"
+                            market_context += f"ATH: ${ath:,.4f} ({ath_change:+.2f}% from ATH)\n"
+                        break
+                
+                if "defi" in query.lower():
+                    defi_data = await self.get_defi_analysis()
+                    if "top_protocols" in defi_data and defi_data["top_protocols"]:
+                        market_context += "\n\nTOP DeFi PROTOCOLS BY TVL:\n"
+                        for protocol in defi_data["top_protocols"][:5]:
+                            name = protocol.get("name", "Unknown")
+                            tvl = protocol.get("tvl", 0)
+                            change = protocol.get("change_1d", 0)
+                            market_context += f"• {name}: ${tvl/1e9:.2f}B TVL ({change:+.2f}%)\n"
+                
+            except Exception as e:
+                market_context = f"\n\nNote: Some enhanced data unavailable ({str(e)})"
+            
+            full_prompt = f"{system_prompt}\n\nQuery: {query}\n\nReal-time Market Context:{market_context}"
+            
+            response = self.model.generate_content(full_prompt)
+            return response.text if response.text else "❌ No response generated. Please try rephrasing your query."
+            
+        except Exception as e:
+            return f"❌ Enhanced research failed: {str(e)}"
+    
+    async def close(self):
+        await coingecko_client.close()
+        await cryptocompare_client.close()
+        await defillama_client.close()
+        await news_aggregator.close()

src/news_aggregator.py

@@ -0,0 +1,83 @@
+import aiohttp
+import asyncio
+from typing import Dict, Any, List, Optional
+from datetime import datetime
+import json
+
+class CryptoNewsAggregator:
+    def __init__(self):
+        self.sources = {
+            "cryptonews": "https://cryptonews-api.com/api/v1/category?section=general&items=10",
+            "newsapi": "https://newsapi.org/v2/everything?q=cryptocurrency&sortBy=publishedAt&pageSize=10",
+            "coindesk": "https://api.coindesk.com/v1/news/articles"
+        }
+        self.session = None
+    
+    async def get_session(self):
+        if self.session is None:
+            timeout = aiohttp.ClientTimeout(total=30)
+            headers = {"User-Agent": "Web3-Research-CoBot/1.0"}
+            self.session = aiohttp.ClientSession(timeout=timeout, headers=headers)
+        return self.session
+    
+    async def get_crypto_news(self, limit: int = 10) -> List[Dict[str, Any]]:
+        news_items = []
+        tasks = []
+        
+        for source, url in self.sources.items():
+            tasks.append(self._fetch_news_from_source(source, url))
+        
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        
+        for result in results:
+            if not isinstance(result, Exception) and result:
+                news_items.extend(result[:5])
+        
+        news_items.sort(key=lambda x: x.get("timestamp", 0), reverse=True)
+        return news_items[:limit]
+    
+    async def _fetch_news_from_source(self, source: str, url: str) -> List[Dict[str, Any]]:
+        try:
+            session = await self.get_session()
+            async with session.get(url) as response:
+                if response.status == 200:
+                    data = await response.json()
+                    return self._parse_news_data(source, data)
+                return []
+        except Exception:
+            return []
+    
+    def _parse_news_data(self, source: str, data: Dict[str, Any]) -> List[Dict[str, Any]]:
+        news_items = []
+        current_time = datetime.now().timestamp()
+        
+        try:
+            if source == "cryptonews" and "data" in data:
+                for item in data["data"][:5]:
+                    news_items.append({
+                        "title": item.get("news_title", ""),
+                        "summary": item.get("text", "")[:200] + "...",
+                        "url": item.get("news_url", ""),
+                        "source": "CryptoNews",
+                        "timestamp": current_time
+                    })
+            
+            elif source == "newsapi" and "articles" in data:
+                for item in data["articles"][:5]:
+                    news_items.append({
+                        "title": item.get("title", ""),
+                        "summary": item.get("description", "")[:200] + "...",
+                        "url": item.get("url", ""),
+                        "source": item.get("source", {}).get("name", "NewsAPI"),
+                        "timestamp": current_time
+                    })
+        except Exception:
+            pass
+        
+        return news_items
+    
+    async def close(self):
+        if self.session:
+            await self.session.close()
+
+news_aggregator = CryptoNewsAggregator()

src/portfolio_analyzer.py

@@ -0,0 +1,143 @@
+import asyncio
+from typing import Dict, Any, List, Optional
+from src.api_clients import coingecko_client
+from src.cache_manager import cache_manager
+import json
+
+class PortfolioAnalyzer:
+    def __init__(self):
+        self.symbol_map = {
+            "btc": "bitcoin", "eth": "ethereum", "sol": "solana", "ada": "cardano",
+            "dot": "polkadot", "bnb": "binancecoin", "usdc": "usd-coin", 
+            "usdt": "tether", "xrp": "ripple", "avax": "avalanche-2",
+            "link": "chainlink", "matic": "matic-network", "uni": "uniswap"
+        }
+    
+    def _format_coin_id(self, symbol: str) -> str:
+        return self.symbol_map.get(symbol.lower(), symbol.lower())
+    
+    async def analyze_portfolio(self, holdings: List[Dict[str, Any]]) -> Dict[str, Any]:
+        try:
+            coin_ids = [self._format_coin_id(h["symbol"]) for h in holdings]
+            
+            tasks = []
+            for coin_id in coin_ids:
+                tasks.append(coingecko_client.get_coin_data(coin_id))
+                tasks.append(coingecko_client.get_price_history(coin_id, days=30))
+            
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            
+            portfolio_value = 0
+            portfolio_change_24h = 0
+            asset_allocation = []
+            risk_metrics = []
+            
+            for i, holding in enumerate(holdings):
+                coin_data_idx = i * 2
+                price_history_idx = i * 2 + 1
+                
+                if not isinstance(results[coin_data_idx], Exception):
+                    coin_data = results[coin_data_idx]
+                    market_data = coin_data.get("market_data", {})
+                    current_price = market_data.get("current_price", {}).get("usd", 0)
+                    price_change_24h = market_data.get("price_change_percentage_24h", 0)
+                    
+                    holding_value = current_price * holding["amount"]
+                    portfolio_value += holding_value
+                    portfolio_change_24h += holding_value * (price_change_24h / 100)
+                    
+                    volatility = 0
+                    if not isinstance(results[price_history_idx], Exception):
+                        price_history = results[price_history_idx]
+                        prices = [p[1] for p in price_history.get("prices", [])]
+                        if len(prices) > 1:
+                            price_changes = [(prices[i] - prices[i-1]) / prices[i-1] for i in range(1, len(prices))]
+                            volatility = sum(abs(change) for change in price_changes) / len(price_changes)
+                    
+                    asset_allocation.append({
+                        "symbol": holding["symbol"].upper(),
+                        "name": coin_data.get("name", "Unknown"),
+                        "value": holding_value,
+                        "percentage": 0,
+                        "amount": holding["amount"],
+                        "price": current_price,
+                        "change_24h": price_change_24h
+                    })
+                    
+                    risk_metrics.append({
+                        "symbol": holding["symbol"].upper(),
+                        "volatility": volatility,
+                        "market_cap_rank": coin_data.get("market_cap_rank", 999)
+                    })
+            
+            for asset in asset_allocation:
+                asset["percentage"] = (asset["value"] / portfolio_value) * 100 if portfolio_value > 0 else 0
+            
+            portfolio_change_percentage = (portfolio_change_24h / portfolio_value) * 100 if portfolio_value > 0 else 0
+            
+            avg_volatility = sum(r["volatility"] for r in risk_metrics) / len(risk_metrics) if risk_metrics else 0
+            
+            diversification_score = len([a for a in asset_allocation if a["percentage"] >= 5])
+            
+            risk_level = "Low" if avg_volatility < 0.05 else "Medium" if avg_volatility < 0.10 else "High"
+            
+            return {
+                "total_value": portfolio_value,
+                "change_24h": portfolio_change_24h,
+                "change_24h_percentage": portfolio_change_percentage,
+                "asset_allocation": sorted(asset_allocation, key=lambda x: x["value"], reverse=True),
+                "risk_metrics": {
+                    "overall_risk": risk_level,
+                    "avg_volatility": avg_volatility,
+                    "diversification_score": diversification_score,
+                    "largest_holding_percentage": max([a["percentage"] for a in asset_allocation]) if asset_allocation else 0
+                },
+                "recommendations": self._generate_recommendations(asset_allocation, risk_metrics)
+            }
+            
+        except Exception as e:
+            raise Exception(f"Portfolio analysis failed: {str(e)}")
+    
+    def _generate_recommendations(self, allocation: List[Dict[str, Any]], risk_metrics: List[Dict[str, Any]]) -> List[str]:
+        recommendations = []
+        
+        if not allocation:
+            return ["Unable to generate recommendations - no valid portfolio data"]
+        
+        largest_holding = max(allocation, key=lambda x: x["percentage"])
+        if largest_holding["percentage"] > 50:
+            recommendations.append(f"Consider reducing {largest_holding['symbol']} position (currently {largest_holding['percentage']:.1f}%) to improve diversification")
+        
+        high_risk_assets = [r for r in risk_metrics if r["volatility"] > 0.15]
+        if len(high_risk_assets) > len(allocation) * 0.6:
+            recommendations.append("Portfolio has high volatility exposure - consider adding stable assets like BTC or ETH")
+        
+        small_cap_heavy = len([r for r in risk_metrics if r["market_cap_rank"] > 100])
+        if small_cap_heavy > len(allocation) * 0.4:
+            recommendations.append("High small-cap exposure detected - consider balancing with top 20 cryptocurrencies")
+        
+        if len(allocation) < 5:
+            recommendations.append("Consider diversifying into 5-10 different cryptocurrencies to reduce risk")
+        
+        stablecoin_exposure = sum(a["percentage"] for a in allocation if a["symbol"] in ["USDC", "USDT", "DAI"])
+        if stablecoin_exposure < 10:
+            recommendations.append("Consider allocating 10-20% to stablecoins for portfolio stability")
+        
+        return recommendations[:5]
+    
+    async def compare_portfolios(self, portfolio1: List[Dict[str, Any]], portfolio2: List[Dict[str, Any]]) -> Dict[str, Any]:
+        analysis1 = await self.analyze_portfolio(portfolio1)
+        analysis2 = await self.analyze_portfolio(portfolio2)
+        
+        return {
+            "portfolio_1": analysis1,
+            "portfolio_2": analysis2,
+            "comparison": {
+                "value_difference": analysis2["total_value"] - analysis1["total_value"],
+                "performance_difference": analysis2["change_24h_percentage"] - analysis1["change_24h_percentage"],
+                "risk_comparison": f"Portfolio 2 is {'higher' if analysis2['risk_metrics']['avg_volatility'] > analysis1['risk_metrics']['avg_volatility'] else 'lower'} risk",
+                "diversification_comparison": f"Portfolio 2 is {'more' if analysis2['risk_metrics']['diversification_score'] > analysis1['risk_metrics']['diversification_score'] else 'less'} diversified"
+            }
+        }
+
+portfolio_analyzer = PortfolioAnalyzer()

src/research_agent.py

@@ -0,0 +1,201 @@
+from google import genai
+from google.genai import types
+import json
+from typing import Dict, Any, List
+from src.api_clients import coingecko_client, cryptocompare_client
+from src.cache_manager import cache_manager
+from src.config import config
+import asyncio
+
+class ResearchAgent:
+    def __init__(self):
+        self.client = genai.Client(api_key=config.GEMINI_API_KEY)
+        self.symbol_map = {
+            "btc": "bitcoin", "eth": "ethereum", "sol": "solana",
+            "ada": "cardano", "dot": "polkadot", "bnb": "binancecoin",
+            "usdc": "usd-coin", "usdt": "tether", "xrp": "ripple",
+            "avax": "avalanche-2", "link": "chainlink", "matic": "matic-network"
+        }
+    
+    def _format_coin_id(self, symbol: str) -> str:
+        return self.symbol_map.get(symbol.lower(), symbol.lower())
+    
+    async def get_market_overview(self) -> Dict[str, Any]:
+        cache_key = "market_overview"
+        cached = cache_manager.get(cache_key)
+        if cached:
+            return cached
+        
+        try:
+            market_data = await coingecko_client.get_market_data(per_page=20)
+            global_data = await coingecko_client.get_global_data()
+            trending = await coingecko_client.get_trending()
+            
+            result = {
+                "market_data": market_data,
+                "global_data": global_data,
+                "trending": trending
+            }
+            
+            cache_manager.set(cache_key, result)
+            return result
+            
+        except Exception as e:
+            raise Exception(f"Failed to fetch market overview: {str(e)}")
+    
+    async def get_price_history(self, symbol: str) -> Dict[str, Any]:
+        cache_key = f"price_history_{symbol.lower()}"
+        cached = cache_manager.get(cache_key)
+        if cached:
+            return cached
+        
+        try:
+            coin_id = self._format_coin_id(symbol)
+            data = await coingecko_client.get_price_history(coin_id, days=30)
+            
+            cache_manager.set(cache_key, data)
+            return data
+            
+        except Exception as e:
+            raise Exception(f"Failed to fetch price history for {symbol}: {str(e)}")
+    
+    async def get_coin_analysis(self, symbol: str) -> Dict[str, Any]:
+        cache_key = f"coin_analysis_{symbol.lower()}"
+        cached = cache_manager.get(cache_key)
+        if cached:
+            return cached
+        
+        try:
+            coin_id = self._format_coin_id(symbol)
+            
+            tasks = [
+                coingecko_client.get_coin_data(coin_id),
+                coingecko_client.get_price_history(coin_id, days=7),
+                cryptocompare_client.get_social_data(symbol.upper())
+            ]
+            
+            coin_data, price_history, social_data = await asyncio.gather(*tasks, return_exceptions=True)
+            
+            result = {}
+            if not isinstance(coin_data, Exception):
+                result["coin_data"] = coin_data
+            if not isinstance(price_history, Exception):
+                result["price_history"] = price_history
+            if not isinstance(social_data, Exception):
+                result["social_data"] = social_data
+            
+            cache_manager.set(cache_key, result)
+            return result
+            
+        except Exception as e:
+            raise Exception(f"Failed to analyze {symbol}: {str(e)}")
+    
+    def _format_market_data(self, data: Dict[str, Any]) -> str:
+        if not data:
+            return "No market data available"
+        
+        formatted = "📊 MARKET OVERVIEW\n\n"
+        
+        if "global_data" in data and "data" in data["global_data"]:
+            global_info = data["global_data"]["data"]
+            total_mcap = global_info.get("total_market_cap", {}).get("usd", 0)
+            total_volume = global_info.get("total_volume", {}).get("usd", 0)
+            btc_dominance = global_info.get("market_cap_percentage", {}).get("btc", 0)
+            
+            formatted += f"Total Market Cap: ${total_mcap:,.0f}\n"
+            formatted += f"24h Volume: ${total_volume:,.0f}\n"
+            formatted += f"Bitcoin Dominance: {btc_dominance:.1f}%\n\n"
+        
+        if "trending" in data and "coins" in data["trending"]:
+            formatted += "🔥 TRENDING COINS\n"
+            for i, coin in enumerate(data["trending"]["coins"][:5], 1):
+                name = coin.get("item", {}).get("name", "Unknown")
+                symbol = coin.get("item", {}).get("symbol", "")
+                formatted += f"{i}. {name} ({symbol.upper()})\n"
+            formatted += "\n"
+        
+        if "market_data" in data:
+            formatted += "💰 TOP CRYPTOCURRENCIES\n"
+            for i, coin in enumerate(data["market_data"][:10], 1):
+                name = coin.get("name", "Unknown")
+                symbol = coin.get("symbol", "").upper()
+                price = coin.get("current_price", 0)
+                change = coin.get("price_change_percentage_24h", 0)
+                change_symbol = "📈" if change >= 0 else "📉"
+                
+                formatted += f"{i:2d}. {name} ({symbol}): ${price:,.4f} {change_symbol} {change:+.2f}%\n"
+        
+        return formatted
+    
+    async def research(self, query: str) -> str:
+        try:
+            if not config.GEMINI_API_KEY:
+                return "❌ Gemini API key not configured. Please set GEMINI_API_KEY environment variable."
+            
+            system_prompt = """You are an expert Web3 and cryptocurrency research analyst. 
+            Provide comprehensive, accurate, and actionable insights based on real market data.
+            
+            Guidelines:
+            - Give specific, data-driven analysis
+            - Include price targets and risk assessments when relevant
+            - Explain technical concepts clearly
+            - Provide actionable recommendations
+            - Use emojis for better readability
+            - Be concise but thorough
+            """
+            
+            market_context = ""
+            try:
+                if any(keyword in query.lower() for keyword in ["market", "overview", "trending", "top"]):
+                    market_data = await self.get_market_overview()
+                    market_context = f"\n\nCURRENT MARKET DATA:\n{self._format_market_data(market_data)}"
+                
+                for symbol in ["btc", "eth", "sol", "ada", "dot", "bnb", "avax", "link"]:
+                    if symbol in query.lower() or symbol.upper() in query:
+                        analysis_data = await self.get_coin_analysis(symbol)
+                        if "coin_data" in analysis_data:
+                            coin_info = analysis_data["coin_data"]
+                            market_data = coin_info.get("market_data", {})
+                            current_price = market_data.get("current_price", {}).get("usd", 0)
+                            price_change = market_data.get("price_change_percentage_24h", 0)
+                            market_cap = market_data.get("market_cap", {}).get("usd", 0)
+                            volume = market_data.get("total_volume", {}).get("usd", 0)
+                            
+                            market_context += f"\n\n{symbol.upper()} DATA:\n"
+                            market_context += f"Price: ${current_price:,.4f}\n"
+                            market_context += f"24h Change: {price_change:+.2f}%\n"
+                            market_context += f"Market Cap: ${market_cap:,.0f}\n"
+                            market_context += f"Volume: ${volume:,.0f}\n"
+                        break
+                
+            except Exception as e:
+                market_context = f"\n\nNote: Some market data unavailable ({str(e)})"
+            
+            full_prompt = f"{query}{market_context}"
+            
+            response = self.client.models.generate_content(
+                model="gemini-2.5-flash",
+                contents=[
+                    types.Content(
+                        role="user", 
+                        parts=[types.Part(text=full_prompt)]
+                    )
+                ],
+                config=types.GenerateContentConfig(
+                    system_instruction=system_prompt,
+                    temperature=0.3,
+                    max_output_tokens=2000
+                )
+            )
+            
+            if response.text:
+                return response.text
+            else:
+                return "❌ No response generated. Please try rephrasing your query."
+                
+        except Exception as e:
+            return f"❌ Research failed: {str(e)}"
+    
+    async def close(self):
+        await coingecko_client.close()
+        await cryptocompare_client.close()

src/visualizations.py

@@ -0,0 +1,238 @@
+import plotly.graph_objects as go
+import plotly.express as px
+from plotly.subplots import make_subplots
+from typing import Dict, Any, List
+import pandas as pd
+from datetime import datetime
+
+def create_price_chart(data: Dict[str, Any], symbol: str) -> str:
+    try:
+        if not data or "prices" not in data:
+            return f"<div style='padding: 20px; text-align: center;'>No price data available for {symbol.upper()}</div>"
+        
+        prices = data["prices"]
+        volumes = data.get("total_volumes", [])
+        
+        if not prices:
+            return f"<div style='padding: 20px; text-align: center;'>No price history found for {symbol.upper()}</div>"
+        
+        df = pd.DataFrame(prices, columns=["timestamp", "price"])
+        df["datetime"] = pd.to_datetime(df["timestamp"], unit="ms")
+        
+        fig = make_subplots(
+            rows=2, cols=1,
+            shared_xaxes=True,
+            vertical_spacing=0.05,
+            subplot_titles=[f"{symbol.upper()} Price Chart", "Volume"],
+            row_width=[0.7, 0.3]
+        )
+        
+        fig.add_trace(
+            go.Scatter(
+                x=df["datetime"],
+                y=df["price"],
+                mode="lines",
+                name="Price",
+                line=dict(color="#00D4AA", width=2),
+                hovertemplate="<b>%{y:$,.2f}</b><br>%{x}<extra></extra>"
+            ),
+            row=1, col=1
+        )
+        
+        if volumes:
+            vol_df = pd.DataFrame(volumes, columns=["timestamp", "volume"])
+            vol_df["datetime"] = pd.to_datetime(vol_df["timestamp"], unit="ms")
+            
+            fig.add_trace(
+                go.Bar(
+                    x=vol_df["datetime"],
+                    y=vol_df["volume"],
+                    name="Volume",
+                    marker_color="#FF6B6B",
+                    opacity=0.7,
+                    hovertemplate="<b>$%{y:,.0f}</b><br>%{x}<extra></extra>"
+                ),
+                row=2, col=1
+            )
+        
+        current_price = df["price"].iloc[-1]
+        price_change = ((df["price"].iloc[-1] - df["price"].iloc[0]) / df["price"].iloc[0]) * 100
+        
+        fig.update_layout(
+            title=dict(
+                text=f"{symbol.upper()} - ${current_price:,.4f} ({price_change:+.2f}%)",
+                x=0.5,
+                font=dict(size=20, color="#FFFFFF")
+            ),
+            xaxis_title="Date",
+            yaxis_title="Price (USD)",
+            template="plotly_dark",
+            showlegend=False,
+            height=600,
+            margin=dict(l=60, r=60, t=80, b=60),
+            plot_bgcolor="rgba(0,0,0,0)",
+            paper_bgcolor="rgba(0,0,0,0)"
+        )
+        
+        fig.update_xaxes(showgrid=True, gridwidth=1, gridcolor="rgba(255,255,255,0.1)")
+        fig.update_yaxes(showgrid=True, gridwidth=1, gridcolor="rgba(255,255,255,0.1)")
+        
+        return fig.to_html(include_plotlyjs="cdn", div_id=f"chart_{symbol}")
+        
+    except Exception as e:
+        return f"<div style='padding: 20px; text-align: center; color: #FF6B6B;'>Chart generation failed: {str(e)}</div>"
+
+def create_market_overview(data: Dict[str, Any]) -> str:
+    try:
+        if not data or "market_data" not in data:
+            return "<div style='padding: 20px; text-align: center;'>Market data unavailable</div>"
+        
+        market_data = data["market_data"]
+        if not market_data:
+            return "<div style='padding: 20px; text-align: center;'>No market data found</div>"
+        
+        df = pd.DataFrame(market_data)
+        df = df.head(20)
+        
+        fig = make_subplots(
+            rows=2, cols=2,
+            subplot_titles=[
+                "Market Cap Distribution",
+                "24h Price Changes",
+                "Trading Volume",
+                "Price vs Volume"
+            ],
+            specs=[[{"type": "pie"}, {"type": "bar"}],
+                   [{"type": "bar"}, {"type": "scatter"}]]
+        )
+        
+        fig.add_trace(
+            go.Pie(
+                labels=df["symbol"].str.upper(),
+                values=df["market_cap"],
+                textinfo="label+percent",
+                textposition="inside",
+                marker=dict(colors=px.colors.qualitative.Set3),
+                hovertemplate="<b>%{label}</b><br>Market Cap: $%{value:,.0f}<extra></extra>"
+            ),
+            row=1, col=1
+        )
+        
+        colors = ["#00D4AA" if x >= 0 else "#FF6B6B" for x in df["price_change_percentage_24h"]]
+        fig.add_trace(
+            go.Bar(
+                x=df["symbol"].str.upper(),
+                y=df["price_change_percentage_24h"],
+                marker_color=colors,
+                hovertemplate="<b>%{x}</b><br>24h Change: %{y:+.2f}%<extra></extra>"
+            ),
+            row=1, col=2
+        )
+        
+        fig.add_trace(
+            go.Bar(
+                x=df["symbol"].str.upper(),
+                y=df["total_volume"],
+                marker_color="#4ECDC4",
+                hovertemplate="<b>%{x}</b><br>Volume: $%{y:,.0f}<extra></extra>"
+            ),
+            row=2, col=1
+        )
+        
+        fig.add_trace(
+            go.Scatter(
+                x=df["current_price"],
+                y=df["total_volume"],
+                mode="markers+text",
+                text=df["symbol"].str.upper(),
+                textposition="top center",
+                marker=dict(
+                    size=df["market_cap"] / df["market_cap"].max() * 50 + 10,
+                    color=df["price_change_percentage_24h"],
+                    colorscale="RdYlGn",
+                    colorbar=dict(title="24h Change %"),
+                    line=dict(width=1, color="white")
+                ),
+                hovertemplate="<b>%{text}</b><br>Price: $%{x:,.4f}<br>Volume: $%{y:,.0f}<extra></extra>"
+            ),
+            row=2, col=2
+        )
+        
+        global_info = data.get("global_data", {}).get("data", {})
+        total_mcap = global_info.get("total_market_cap", {}).get("usd", 0)
+        total_volume = global_info.get("total_volume", {}).get("usd", 0)
+        btc_dominance = global_info.get("market_cap_percentage", {}).get("btc", 0)
+        
+        title_text = f"Crypto Market Overview - Total MCap: ${total_mcap/1e12:.2f}T | 24h Vol: ${total_volume/1e9:.0f}B | BTC Dom: {btc_dominance:.1f}%"
+        
+        fig.update_layout(
+            title=dict(
+                text=title_text,
+                x=0.5,
+                font=dict(size=16, color="#FFFFFF")
+            ),
+            template="plotly_dark",
+            showlegend=False,
+            height=800,
+            margin=dict(l=60, r=60, t=100, b=60),
+            plot_bgcolor="rgba(0,0,0,0)",
+            paper_bgcolor="rgba(0,0,0,0)"
+        )
+        
+        fig.update_xaxes(showgrid=True, gridwidth=1, gridcolor="rgba(255,255,255,0.1)")
+        fig.update_yaxes(showgrid=True, gridwidth=1, gridcolor="rgba(255,255,255,0.1)")
+        
+        return fig.to_html(include_plotlyjs="cdn", div_id="market_overview")
+        
+    except Exception as e:
+        return f"<div style='padding: 20px; text-align: center; color: #FF6B6B;'>Market overview failed: {str(e)}</div>"
+
+def create_comparison_chart(coins_data: List[Dict[str, Any]]) -> str:
+    try:
+        if not coins_data:
+            return "<div style='padding: 20px; text-align: center;'>No comparison data available</div>"
+        
+        df = pd.DataFrame(coins_data)
+        
+        fig = make_subplots(
+            rows=1, cols=2,
+            subplot_titles=["Price Comparison", "Market Cap Comparison"]
+        )
+        
+        colors = px.colors.qualitative.Set1[:len(df)]
+        
+        for i, (_, coin) in enumerate(df.iterrows()):
+            fig.add_trace(
+                go.Bar(
+                    name=coin["symbol"].upper(),
+                    x=[coin["symbol"].upper()],
+                    y=[coin["current_price"]],
+                    marker_color=colors[i],
+                    hovertemplate=f"<b>{coin['name']}</b><br>Price: $%{{y:,.4f}}<extra></extra>"
+                ),
+                row=1, col=1
+            )
+            
+            fig.add_trace(
+                go.Bar(
+                    name=coin["symbol"].upper(),
+                    x=[coin["symbol"].upper()],
+                    y=[coin["market_cap"]],
+                    marker_color=colors[i],
+                    showlegend=False,
+                    hovertemplate=f"<b>{coin['name']}</b><br>Market Cap: $%{{y:,.0f}}<extra></extra>"
+                ),
+                row=1, col=2
+            )
+        
+        fig.update_layout(
+            title="Cryptocurrency Comparison",
+            template="plotly_dark",
+            height=500,
+            showlegend=True
+        )
+        
+        return fig.to_html(include_plotlyjs="cdn", div_id="comparison_chart")
+        
+    except Exception as e:
+        return f"<div style='padding: 20px; text-align: center; color: #FF6B6B;'>Comparison chart failed: {str(e)}</div>"