Upload folder using huggingface_hub

README.md

@@ -1,223 +1,26 @@
 ---
-title: AI Chatbot
-emoji: 🤖
+title: Nexus
+emoji: 🔮
 colorFrom: pink
-colorTo: yellow
+colorTo: indigo
 sdk: docker
-sdk_version: "0.0.1"
 app_file: app.py
 pinned: false
 license: mit
-tags:
-  - text-generation
-  - agentic-ai
-  - openai-sdk
-short_description: An Experimental Agentic Chatbot (uses OpenAI Agent SDK)
+short_description: Multi-specialist AI orchestrator for web research
 ---
 
-# AI Chatbot
+# Nexus
 
-This is an experimental chatbot for chatting with AI. It is equipped with agents & tools to give you realtime data from the web. It uses **OpenAI - SDK** and **OpenAI - Agents**...
+Nexus is a multi-specialist AI research orchestrator. It fans out every query to three dedicated agents — a Financial Markets Analyst, a News Intelligence Specialist, and a Web Research Specialist — then synthesises their reports into a single, coherent answer.
 
-## Features
-- Predefined prompts for quick analysis
-- Chat interface with AI responses
-- Enter key support and responsive design
-- Latest messages appear on top
+## What it does
 
-## Usage
-1. Type a message or select a predefined prompt
-2. Press **Enter** or click **Send**
-3. AI responses appear instantly in the chat interface
+- **Finance** — stock prices, market sentiment, analyst ratings, earnings, IV analysis, sector screening
+- **News** — breaking headlines, topic-specific articles, category filtering
+- **Web Research** — deep-dive fact-finding with cited sources
+- **Orchestration** — parallel specialist calls, automatic web fallback on failure, content guardrails
 
-## Supported APIs
-- OpenAI
-- Google
-- GROQ
-- SERPER
-- News API
+## Stack
 
-## Notes
-- Make sure your API keys are configured in the Space secrets
-- Built using Streamlit and deployed as a Docker Space
-
-## References
-
-https://openai.github.io/openai-agents-python/
-
-https://github.com/openai/openai-agents-python/tree/main/examples/mcp
-
-## Project Folder Structure
-
-```
-chatbot/
-├── app.py                    # Main Streamlit chatbot interface
-├── appagents/
-│   ├── __init__.py               # Package initialization
-│   ├── OrchestratorAgent.py      # Main orchestrator - coordinates all agents
-│   ├── FinancialAgent.py         # Financial data and analysis agent
-│   ├── NewsAgent.py              # News retrieval and summarization agent
-│   ├── SearchAgent.py            # General web search agent
-│   └── InputValidationAgent.py   # Input validation and sanitization agent
-├── core/
-│   ├── __init__.py               # Package initialization
-│   └── logger.py                 # Centralized logging configuration
-├── tools/
-│   ├── __init__.py               # Package initialization
-│   ├── google_tools.py           # Google search API wrapper
-│   ├── yahoo_tools.py            # Yahoo Finance API wrapper
-│   ├── news_tools.py             # News API wrapper
-│   └── time_tools.py             # Time-related utility functions
-├── prompts/
-│   ├── economic_news.txt         # Prompt for economic news analysis
-│   ├── market_sentiment.txt      # Prompt for market sentiment analysis
-│   ├── news_headlines.txt        # Prompt for news headline summarization
-│   ├── trade_recommendation.txt  # Prompt for trade recommendations
-│   └── upcoming_earnings.txt     # Prompt for upcoming earnings alerts
-├── Dockerfile                     # Docker configuration for container deployment
-├── pyproject.toml                 # Project metadata and dependencies (copied from root)
-├── uv.lock                        # Locked dependency versions (copied from root)
-├── README.md                      # Project documentation
-└── run.py                         # Script to run the application locally
-```
-
-## File Descriptions
-
-### UI Layer
-- **app.py** - Main Streamlit chatbot interface that provides:
-  - Chat message display with user and AI messages
-  - Text input for user queries
-  - Predefined prompt buttons for quick analysis
-  - Real-time AI responses
-  - Support for Enter key submission
-  - Responsive design with latest messages appearing first
-
-### Agents (`appagents/`)
-- **OrchestratorAgent.py** - Main orchestrator that:
-  - Coordinates communication between all specialized agents
-  - Routes user queries to appropriate agents
-  - Manages conversation flow and context
-  - Integrates tool responses
-
-- **FinancialAgent.py** - Financial data and analysis:
-  - Retrieves stock prices and financial metrics
-  - Performs financial analysis using Yahoo Finance API
-  - Provides market insights and recommendations
-  - Integrates with yahoo_tools for data fetching
-
-- **NewsAgent.py** - News retrieval and summarization:
-  - Fetches latest news articles
-  - Summarizes news content
-  - Integrates with News API for real-time updates
-  - Provides news-based market insights
-
-- **SearchAgent.py** - General web search:
-  - Performs web searches for general queries
-  - Integrates with Google Search / Serper API
-  - Returns relevant search results
-  - Supports multi-source data gathering
-
-- **InputValidationAgent.py** - Input validation:
-  - Sanitizes user input
-  - Validates query format and content
-  - Prevents malicious inputs
-  - Ensures appropriate content
-
-### Core Utilities (`core/`)
-- **logger.py** - Centralized logging configuration:
-  - Provides consistent logging across agents
-  - Handles different log levels
-  - Formats log messages for clarity
-
-### Tools (`tools/`)
-- **google_tools.py** - Google Search API wrapper:
-  - Executes web searches via Google Search / Serper API
-  - Parses and returns search results
-  - Handles API authentication
-
-- **yahoo_tools.py** - Yahoo Finance API integration:
-  - Retrieves stock price data
-  - Fetches financial metrics and indicators
-  - Provides historical price data
-  - Returns earnings information
-
-- **news_tools.py** - News API integration:
-  - Fetches latest news articles
-  - Filters news by category and keywords
-  - Returns news headlines and summaries
-  - Provides market-related news feeds
-
-- **time_tools.py** - Time utility functions:
-  - Provides current time information
-  - Formats timestamps
-  - Handles timezone conversions
-
-### Prompts (`prompts/`)
-Predefined prompts for specialized analysis:
-- **economic_news.txt** - Analyzes economic news and implications
-- **market_sentiment.txt** - Analyzes market sentiment trends
-- **news_headlines.txt** - Summarizes and explains news headlines
-- **trade_recommendation.txt** - Provides trading recommendations
-- **upcoming_earnings.txt** - Alerts about upcoming earnings reports
-
-### Configuration Files
-- **Dockerfile** - Container deployment:
-  - Builds Docker image with Python 3.12
-  - Installs dependencies using `uv`
-  - Sets up Streamlit server on port 8501
-  - Configures PYTHONPATH for module imports
-
-- **pyproject.toml** - Project metadata:
-  - Package name: "agents"
-  - Python version requirement: 3.12
-  - Lists all dependencies (OpenAI, LangChain, Streamlit, etc.)
-
-- **uv.lock** - Dependency lock file:
-  - Ensures reproducible builds
-  - Pins exact versions of all dependencies
-
-## Key Technologies
-
-| Component | Technology | Purpose |
-|-----------|-----------|---------|
-| LLM Framework | OpenAI Agents | Multi-agent orchestration |
-| Chat Interface | Streamlit | User interaction and display |
-| Web Search | Google Search / Serper API | Web search results |
-| Financial Data | Yahoo Finance API | Stock prices and metrics |
-| News Data | News API | Latest news articles |
-| Async Operations | AsyncIO | Parallel agent execution |
-| Dependencies | UV | Fast Python package management |
-| Containerization | Docker | Cloud deployment |
-
-## Predefined Prompts
-
-The chatbot includes quick-access buttons for common analysis:
-
-1. **Economic News** - Analyzes current economic trends and news
-2. **Market Sentiment** - Provides market sentiment analysis
-3. **News Headlines** - Summarizes latest news headlines
-4. **Trade Recommendation** - Suggests trading strategies
-5. **Upcoming Earnings** - Lists upcoming company earnings
-
-## Running Locally
-
-```bash
-# Install dependencies
-uv sync
-
-# Set environment variables defined in .env.name file
-export OPENAI_API_KEY="your-key"
-export SERPER_API_KEY="your-key"
-export NEWS_API_KEY="your-key"
-
-# Run the Streamlit app (from the root)
-python run.py chatbot
-```
-
-## Deployment
-
-The project is deployed on Hugging Face Spaces as a Docker container:
-- **Space**: https://huggingface.co/spaces/mishrabp/chatbot-app
-- **URL**: https://mishrabp-chatbot-app.hf.space
-- **Trigger**: Automatic deployment on push to `main` branch
-- **Configuration**: `.github/workflows/chatbot-app-hf.yml`
+Streamlit · OpenAI Agents SDK · MCP (stdio) · Google Gemini / GPT-4o

pyproject.toml

@@ -138,6 +138,7 @@ dependencies = [
     # =======================
     # OBSERVABILITY
     # =======================
+    "langfuse>=3.0.0",
     "openinference-instrumentation-autogen>=0.1.0",
     "openinference-instrumentation-openai>=0.1.15",
     "opentelemetry-sdk>=1.20.0",
@@ -160,6 +161,7 @@ dev = [
     "pytest>=9.0.3",
     "ipykernel>=7.1.0",
     "pytest-asyncio",
+    "pytest-cov>=7.1.0",
 ]
 
 # ============================================================
@@ -175,20 +177,16 @@ build-backend = "setuptools.build_meta"
 # PACKAGING & DISCOVERY
 # ============================================================
 # Tells setuptools where to find the source code.
-# This makes 'common' and 'src' importable when installed (pip install -e .).
 [tool.setuptools.packages.find]
-where = ["."]  # Look in the project root
-include = ["common*", "src*"]  # Treat 'common' and 'src' folders as packages
+where = ["."]
+include = ["src*"]
 
 
 # ============================================================
 # PYTEST SETTINGS
 # ============================================================
-# Configures the test runner to automatically find code.
 [tool.pytest.ini_options]
-# Adds 'src' and 'common' to the python path during tests.
-# This allows tests to import modules (e.g., 'import travel_agent')
-# just like the apps do locally, preventing ModuleNotFoundError.
-pythonpath = ["src", "common"]
+pythonpath = ["src"]
 testpaths = ["tests"]  # Only look for tests in the 'tests' directory
 addopts = "-q"  # Run in quiet mode (less verbose output)
+asyncio_mode = "auto"  # Auto-detect async tests (requires pytest-asyncio)

run.py

@@ -29,152 +29,42 @@ load_dotenv(override=True)
 
 # App registry - maps app names to their paths and entry points
 APP_REGISTRY: Dict[str, Dict[str, str]] = {
-    "healthcare": {
-        "path": "src/healthcare-assistant",
+    "nexus": {
+        "path": "src/nexus",
         "entry": "app.py",
-        "description": "Healthcare Assistant - Medical information with RAG and web search"
+        "description": "Nexus - AI Research Assistant - Multi-specialist orchestrator for finance, news, and web research"
     },
-    "deep-research_v1": {
-        "path": "src/deep-research_v1",
+    "athena": {
+        "path": "src/athena",
         "entry": "app.py",
-        "description": "Deep Research AI - Comprehensive research assistant"
+        "description": "Athena - Deep Research Reporter - Plans, searches, and synthesises comprehensive research reports"
     },
-    "deep-research_v2": {
-        "path": "src/deep-research_v2",
+    "remedy": {
+        "path": "src/remedy",
         "entry": "app.py",
-        "description": "Deep Research AI - Comprehensive research assistant"
+        "description": "Remedy - Healthcare RAG Advisor - Medical information retrieval using RAG and web search"
     },
-    "stock-analyst": {
-        "path": "src/stock-analyst",
+    "midas": {
+        "path": "src/midas",
         "entry": "app.py",
-        "description": "Stock Analyst - Financial analysis and stock recommendations"
+        "description": "Midas - Stock Investment Analyst - Multi-agent investment team for technical and sentiment analysis"
     },
-    "travel-agent": {
-        "path": "src/travel-agent",
+    "odyssey": {
+        "path": "src/odyssey",
         "entry": "app.py",
-        "description": "Travel Agent - Trip planning and travel recommendations"
+        "description": "Odyssey - Travel Planner - AI-powered trip planning with flight, hotel, and itinerary recommendations"
     },
-    "trip-planner": {
-        "path": "src/trip-planner",
+    "waypoint": {
+        "path": "src/waypoint",
         "entry": "main.py",
         "type": "fastapi",
-        "description": "Trip Planner - Detailed trip itinerary planning"
+        "description": "Waypoint - Trip Planner API - Phidata-powered trip itinerary planning REST API"
     },
-    "chatbot_v1": {
-        "path": "src/chatbot_v1",
-        "entry": "app.py",
-        "description": "General Chatbot - Multi-purpose conversational AI"
-    },
-    "chatbot_v2": {
-        "path": "src/chatbot_v2",
-        "entry": "app.py",
-        "description": "Layered Chatbot (ReAct) - Advanced Architecture"
-    },
-    "accessibility_v2": {
-        "path": "src/accessibility_v2",
-        "entry": "app.py",
-        "description": "Accessibility Auditor V2 - Layered Architecture"
-    },
-    "accessibility_v1": {
-        "path": "src/accessibility_v1",
-        "entry": "app.py",
-        "description": "Accessibility Tools - Assistive technology applications"
-    },
-    "literature-review": {
-        "path": "src/literature-review",
-        "entry": "app.py",
-        "description": "Literature Review Assistant - Multi-agent literature review tool"
-    },
-    "market-analyst": {
-        "path": "src/market-analyst",
+    "agora": {
+        "path": "src/agora",
         "entry": "backend/main.py",
         "type": "fastapi",
-        "description": "Market Analyst - Decoupled Multi-agent market analysis (Vue.js + FastAPI)"
-    },
-    "image": {
-        "path": "src/image-generator",
-        "entry": "app.py",
-        "description": "Image Generator - Multi-agent image generation tool"
-    },
-    "interview-assistant": {
-        "path": "src/interview-assistant",
-        "entry": "app.py",
-        "description": "Interview Assistant - Multi-agent interview tool"
-    },
-    "finadvisor-lg": {
-        "path": "src/finadvisor",
-        "entry": "app-lg.py",
-        "description": "Financial Advisor - Multi-agent financial advisor tool using LangGraph"
-    },
-    "finadvisor-oai": {
-        "path": "src/finadvisor",
-        "entry": "app-oai.py",
-        "description": "Financial Advisor - Multi-agent financial advisor tool using OpenAI"
-    },
-    "finadvisor-phi": {
-        "path": "src/finadvisor",
-        "entry": "app-phi.py",
-        "description": "Financial Advisor - Multi-agent financial advisor tool using Phidata"
-    }
-    ,
-    "finadvisor-ag": {
-        "path": "src/finadvisor",
-        "entry": "app-ag.py",
-        "description": "Financial Advisor - Multi-agent financial advisor tool using Autogen"
-    },
-    "mcp-trader": {
-        "path": "src/mcp-trader",
-        "entry": "server.py",
-        "type": "script",
-        "description": "Strategies MCP Server - FastMCP server for trading strategies"
-    },
-    "mcp-web": {
-        "path": "src/mcp-web",
-        "entry": "server.py",
-        "type": "script",
-        "description": "Web MCP Server - Search, Extract, Wikipedia, Arxiv"
-    },
-    "mcp-azure-sre": {
-        "path": "src/mcp-azure-sre",
-        "entry": "server.py",
-        "type": "script",
-        "description": "Azure SRE MCP Server - Manage Azure Resources & Monitoring"
-    },
-    "mcp-rag-secure": {
-        "path": "src/mcp-rag-secure",
-        "entry": "server.py",
-        "type": "script",
-        "description": "Secure RAG MCP Server - Multi-tenant knowledge base"
-    },
-    "mcp-trading-research": {
-        "path": "src/mcp-trading-research",
-        "entry": "server.py",
-        "type": "script",
-        "description": "Trading Research MCP Server - News, Insider, Analysts"
-    },
-    "mcp-github": {
-        "path": "src/mcp-github",
-        "entry": "server.py",
-        "type": "script",
-        "description": "GitHub MCP Server - Issues, PRs, Alerts"
-    },
-    "mcp-seo": {
-        "path": "src/mcp-seo",
-        "entry": "server.py",
-        "type": "script",
-        "description": "SEO & ADA MCP Server - Website Audits"
-    },
-    "github-portal": {
-        "path": "src/github-portal",
-        "entry": "app.py",
-        "type": "streamlit",
-        "description": "GitHub Portal - Repository health dashboard for issues, security, and pipelines"
-    },
-    "mcp-hub": {
-        "path": "src/mcp-hub",
-        "entry": "package.json",
-        "type": "npm",
-        "description": "MCP HUB - Discovery and monitoring portal (Vue.js)"
+        "description": "Agora - AI Market Analyst - Real-time multi-agent market analysis with streaming (Vue.js + FastAPI)"
     },
     "test": {
         "path": ".",
@@ -182,12 +72,6 @@ APP_REGISTRY: Dict[str, Dict[str, str]] = {
         "type": "test",
         "description": "Run Project Tests - Executes pytest suite"
     },
-    "salesdata": {
-        "path": "src/salesdata",
-        "entry": "app.py",
-        "type": "salesdata",
-        "description": "Sales Data Agent - Agentic RAG over sales CSV (FastAPI + Streamlit)"
-    }
 }
 
 
@@ -272,8 +156,8 @@ def launch_app(app_name: str, port: Optional[int] = None):
     env["PYTHONPATH"] = str(project_root) + os.pathsep + env.get("PYTHONPATH", "")
     
     # Decoupled App Logic: Build frontend if needed
-    if app_name == "market-analyst":
-        frontend_dir = project_root / "src/market-analyst/frontend"
+    if app_name == "agora":
+        frontend_dir = project_root / "src/agora/frontend"
         dist_dir = frontend_dir / "dist"
         if not dist_dir.exists():
             print("\n🛠️ Frontend build missing. Building now...")
@@ -334,70 +218,6 @@ def launch_app(app_name: str, port: Optional[int] = None):
         # Change to app directory and run
         os.chdir(app_dir)
         
-        # Special case for mcp-hub: launch backend API first
-        if app_name == "mcp-hub":
-            print("🚀 Starting MCP Hub Backend API on port 8001...")
-            api_cmd = [python_exe, "api.py"]
-            subprocess.Popen(api_cmd, env=env, shell=is_windows)
-
-        # Special case for salesdata: launch FastAPI backend + Streamlit frontend
-        if app_name == "salesdata":
-            api_port = 8080
-            ui_port = port if port else 8501
-
-            # Aggressively kill any stale processes on both ports
-            import platform
-            if platform.system() != "Windows":
-                for p in [api_port, ui_port]:
-                    # lsof is more reliable than fuser for finding PIDs by port
-                    result = subprocess.run(
-                        ["lsof", "-ti", f":{p}"],
-                        capture_output=True, text=True
-                    )
-                    pids = result.stdout.strip().split()
-                    for pid in pids:
-                        subprocess.run(["kill", "-9", pid],
-                                       stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)
-                time.sleep(1)  # let OS release ports
-                print(f"🧹 Cleaned up ports {api_port} and {ui_port}")
-
-            print(f"🚀 Starting Sales Agent API on port {api_port}...")
-            api_cmd = [
-                python_exe, "-m", "uvicorn", "api:app",
-                "--host", "0.0.0.0", "--port", str(api_port)
-            ]
-            subprocess.Popen(api_cmd, env=env, shell=is_windows, cwd=app_dir)
-
-            # Poll /health until agent is ready (instead of a fixed sleep)
-            import urllib.request, urllib.error, json as _json
-            health_url = f"http://localhost:{api_port}/health"
-            print(f"⏳ Waiting for API + agent to be ready", end="", flush=True)
-            timeout = 90  # seconds
-            ready = False
-            for _ in range(timeout):
-                time.sleep(1)
-                print(".", end="", flush=True)
-                try:
-                    with urllib.request.urlopen(health_url, timeout=2) as r:
-                        data = _json.loads(r.read())
-                        if data.get("agent_ready"):
-                            ready = True
-                            break
-                except Exception:
-                    pass
-            print()
-            if not ready:
-                print("⚠️  API did not become ready within 90s — launching UI anyway")
-
-            print(f"🌐 Starting Streamlit UI on port {ui_port}...")
-            ui_cmd = [
-                python_exe, "-m", "streamlit", "run", "app.py",
-                "--server.port", str(ui_port)
-            ]
-            subprocess.run(ui_cmd, env=env, shell=is_windows)
-            return
-
-
 
 
         subprocess.run(cmd, env=env, shell=is_windows)

src/_mcpservers/mcp-finance/server.py

@@ -0,0 +1,808 @@
+"""MCP Finance Server — comprehensive financial data and analysis via Yahoo Finance."""
+import logging
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import yfinance as yf
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+load_dotenv(Path(__file__).resolve().parents[3] / ".env")
+
+# Log to stderr — stdout is reserved for the stdio JSON-RPC channel
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] mcp-finance: %(message)s",
+)
+log = logging.getLogger("mcp-finance")
+
+mcp = FastMCP("Finance MCP", host="0.0.0.0", port=8003)
+
+
+# ---------------------------------------------------------------------------
+# Predefined large-cap universe used by get_upcoming_earnings / screen
+# ---------------------------------------------------------------------------
+_LARGE_CAPS = [
+    "AAPL", "MSFT", "NVDA", "GOOGL", "GOOG", "META", "AMZN", "TSLA", "AVGO", "ORCL",
+    "ADBE", "CRM", "AMD", "INTC", "QCOM",
+    "JPM", "BAC", "WFC", "GS", "MS", "BLK", "C", "AXP", "V", "MA",
+    "JNJ", "LLY", "UNH", "PFE", "ABBV", "MRK", "TMO", "ABT", "AMGN",
+    "XOM", "CVX", "COP", "SLB",
+    "WMT", "HD", "MCD", "NKE", "SBUX", "TGT", "COST", "AMZN",
+    "CAT", "BA", "GE", "HON", "RTX", "UPS", "DE",
+    "T", "VZ", "DIS", "NFLX", "CMCSA",
+    "SPY", "QQQ",
+]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _date_range(period: str) -> tuple[str, str]:
+    """Convert a period string (e.g. '1mo') into (start_date, end_date) strings."""
+    end = datetime.today()
+    if period.endswith("d"):
+        days = int(period[:-1])
+    elif period.endswith("mo"):
+        days = int(period[:-2]) * 30
+    elif period.endswith("y"):
+        days = int(period[:-1]) * 365
+    else:
+        days = 30
+    return (end - timedelta(days=days)).strftime("%Y-%m-%d"), end.strftime("%Y-%m-%d")
+
+
+def _history(symbol: str, period: str):
+    """Fetch a Close-price history DataFrame for the given period."""
+    ticker = yf.Ticker(symbol)
+    start, end = _date_range(period)
+    return ticker.history(start=start, end=end)
+
+
+def _fmt_large(value) -> str:
+    """Format large numbers as $1.23T / $456.78B / $789.01M."""
+    if value is None:
+        return "N/A"
+    if value >= 1e12:
+        return f"${value/1e12:.2f}T"
+    if value >= 1e9:
+        return f"${value/1e9:.2f}B"
+    if value >= 1e6:
+        return f"${value/1e6:.2f}M"
+    return f"${value:,.0f}"
+
+
+# ===========================================================================
+# Existing tools
+# ===========================================================================
+
+@mcp.tool()
+def get_stock_summary(symbol: str, period: str = "1d", interval: str = "1h") -> str:
+    """
+    Fetch the latest price summary for a stock or index.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL', 'GOOG', 'BTC-USD').
+        period: Lookback window — '1d', '5d', '1mo', '3mo' (default '1d').
+        interval: Data granularity — '1m', '5m', '1h', '1d' (default '1h').
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        start, end = _date_range(period)
+        data = ticker.history(start=start, end=end, interval=interval)
+        if data.empty:
+            return f"No data found for '{symbol}'."
+        latest = data.iloc[-1]
+        price = round(latest["Close"], 2)
+        open_p = round(latest["Open"], 2)
+        change = round(price - open_p, 2)
+        pct = round((change / open_p) * 100, 2)
+        info = ticker.info
+        name = info.get("longName", symbol)
+        currency = info.get("currency", "USD")
+        return (
+            f"📈 {name} ({symbol})\n"
+            f"Price: {price} {currency}  |  Change: {change} ({pct}%)\n"
+            f"Open: {open_p}  High: {round(latest['High'], 2)}  Low: {round(latest['Low'], 2)}\n"
+            f"Volume: {int(latest['Volume'])}  |  Period: {period} @ {interval}"
+        )
+    except Exception as e:
+        return f"Error fetching data for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_market_sentiment(symbol: str, period: str = "1mo") -> str:
+    """
+    Analyse price movement and return a Bullish / Bearish / Neutral verdict.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL').
+        period: Lookback window — '7d', '1mo', '3mo' (default '1mo').
+    """
+    try:
+        data = _history(symbol, period)
+        if data.empty:
+            return f"No data for '{symbol}'."
+        pct = (data["Close"].iloc[-1] - data["Close"].iloc[0]) / data["Close"].iloc[0] * 100
+        verdict = "Bullish" if pct > 2 else ("Bearish" if pct < -2 else "Neutral")
+        return f"{symbol} sentiment over {period}: {verdict} ({pct:.2f}% change)"
+    except Exception as e:
+        return f"Error fetching sentiment for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_price_history(symbol: str, period: str = "1mo") -> str:
+    """
+    Fetch historical OHLCV price data for a ticker (last 5 rows).
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL').
+        period: Lookback window — '1d', '5d', '1mo', '3mo', '1y' (default '1mo').
+    """
+    try:
+        data = _history(symbol, period)
+        if data.empty:
+            return f"No historical data for '{symbol}'."
+        return f"Price history for {symbol} ({period}):\n{data.tail(5).to_string()}"
+    except Exception as e:
+        return f"Error fetching history for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_analyst_recommendations(symbol: str) -> str:
+    """
+    Fetch the most recent analyst Buy/Sell/Hold ratings for a ticker.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL').
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        recs = ticker.recommendations
+        if recs is None or recs.empty:
+            return f"No analyst recommendations found for '{symbol}'."
+        return f"Analyst recommendations for {symbol}:\n{recs.tail(5).to_string()}"
+    except Exception as e:
+        return f"Error fetching recommendations for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_earnings_calendar(symbol: str) -> str:
+    """
+    Fetch the upcoming earnings date for a ticker.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL').
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        calendar = ticker.calendar
+        if not calendar:
+            return f"No earnings calendar found for '{symbol}'."
+        return f"Earnings calendar for {symbol}:\n{calendar}"
+    except Exception as e:
+        return f"Error fetching earnings calendar for '{symbol}': {e}"
+
+
+# ===========================================================================
+# New tools
+# ===========================================================================
+
+@mcp.tool()
+def get_valuation_metrics(symbol: str) -> str:
+    """
+    Fetch key valuation and fundamental metrics for a stock.
+
+    Includes market cap, P/E ratios, EPS, revenue, profit margin,
+    dividend yield, beta, and 52-week range.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL', 'MSFT').
+    """
+    try:
+        info = yf.Ticker(symbol).info
+        name = info.get("longName", symbol)
+        rows = [
+            ("Market Cap",        _fmt_large(info.get("marketCap"))),
+            ("Revenue (TTM)",     _fmt_large(info.get("totalRevenue"))),
+            ("P/E Ratio (TTM)",   f"{info['trailingPE']:.2f}" if info.get("trailingPE") else "N/A"),
+            ("Forward P/E",       f"{info['forwardPE']:.2f}" if info.get("forwardPE") else "N/A"),
+            ("P/B Ratio",         f"{info['priceToBook']:.2f}" if info.get("priceToBook") else "N/A"),
+            ("EPS (TTM)",         f"${info['trailingEps']:.2f}" if info.get("trailingEps") else "N/A"),
+            ("Profit Margin",     f"{info['profitMargins']*100:.2f}%" if info.get("profitMargins") else "N/A"),
+            ("Dividend Yield",    f"{info['dividendYield']*100:.2f}%" if info.get("dividendYield") else "N/A"),
+            ("Beta",              f"{info['beta']:.2f}" if info.get("beta") else "N/A"),
+            ("52-Week High",      f"${info['fiftyTwoWeekHigh']:.2f}" if info.get("fiftyTwoWeekHigh") else "N/A"),
+            ("52-Week Low",       f"${info['fiftyTwoWeekLow']:.2f}" if info.get("fiftyTwoWeekLow") else "N/A"),
+        ]
+        lines = [f"📊 Valuation Metrics — {name} ({symbol})\n"]
+        width = max(len(k) for k, _ in rows)
+        for k, v in rows:
+            lines.append(f"  {k:<{width}} : {v}")
+        return "\n".join(lines)
+    except Exception as e:
+        return f"Error fetching valuation metrics for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_financial_statements(symbol: str, statement: str = "income") -> str:
+    """
+    Fetch annual financial statements for a stock.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL').
+        statement: Which statement to return —
+            'income'   → Income Statement (revenue, gross profit, net income, EBITDA)
+            'balance'  → Balance Sheet (assets, liabilities, equity)
+            'cashflow' → Cash Flow Statement (operating, investing, financing)
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        if statement == "income":
+            df = ticker.income_stmt
+            label = "Income Statement"
+        elif statement == "balance":
+            df = ticker.balance_sheet
+            label = "Balance Sheet"
+        elif statement == "cashflow":
+            df = ticker.cashflow
+            label = "Cash Flow Statement"
+        else:
+            return (
+                f"Unknown statement type '{statement}'. "
+                "Use 'income', 'balance', or 'cashflow'."
+            )
+        if df is None or df.empty:
+            return f"No {label} data available for '{symbol}'."
+        return f"📋 {label} — {symbol}\n\n{df.head(12).to_string()}"
+    except Exception as e:
+        return f"Error fetching {statement} statement for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_dividends(symbol: str, years: int = 3) -> str:
+    """
+    Fetch dividend payment history and yield for a stock.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'JNJ', 'KO').
+        years: How many years of history to show (default 3).
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        divs = ticker.dividends
+        if divs is None or divs.empty:
+            return f"'{symbol}' pays no dividends (or data is unavailable)."
+
+        # Normalise timezone before date filtering
+        idx = divs.index.tz_localize(None) if divs.index.tz is None else divs.index.tz_convert(None)
+        cutoff = datetime.now() - timedelta(days=365 * years)
+        recent = divs[idx >= cutoff]
+        if recent.empty:
+            return f"No dividends paid in the last {years} year(s) for '{symbol}'."
+
+        annual = recent.resample("YE").sum()
+        info = ticker.info
+        yield_pct = info.get("dividendYield")
+
+        lines = [f"💰 Dividend History — {symbol} (last {years} year(s))\n"]
+        if yield_pct:
+            lines.append(f"  Current Yield  : {yield_pct * 100:.2f}%")
+        lines.append("  Annual totals  :")
+        for date, amount in annual.items():
+            lines.append(f"    {date.year} : ${amount:.4f}")
+        lines.append(
+            f"\n  Last payment   : ${recent.iloc[-1]:.4f} "
+            f"on {idx[-1].strftime('%Y-%m-%d')}"
+        )
+        return "\n".join(lines)
+    except Exception as e:
+        return f"Error fetching dividends for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_technical_indicators(symbol: str, period: str = "6mo") -> str:
+    """
+    Compute SMA(20/50/200), RSI(14), and MACD(12,26,9) from price history.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL').
+        period: Lookback window for calculations — '3mo', '6mo', '1y', '2y'
+                (default '6mo'; use '2y' to get SMA-200).
+    """
+    try:
+        data = _history(symbol, period)
+        if data.empty or len(data) < 20:
+            return (
+                f"Insufficient price history for '{symbol}'. "
+                "Try a longer period (e.g. '1y')."
+            )
+        close = data["Close"]
+        price = round(close.iloc[-1], 2)
+
+        def _sma(n):
+            return round(close.rolling(n).mean().iloc[-1], 2) if len(close) >= n else None
+
+        sma20, sma50, sma200 = _sma(20), _sma(50), _sma(200)
+
+        # RSI-14
+        delta = close.diff()
+        gain = delta.clip(lower=0).rolling(14).mean()
+        loss = (-delta.clip(upper=0)).rolling(14).mean()
+        rs = gain / loss
+        rsi = round((100 - 100 / (1 + rs)).iloc[-1], 2)
+        rsi_label = "Overbought" if rsi > 70 else ("Oversold" if rsi < 30 else "Neutral")
+
+        # MACD (12, 26, 9)
+        ema12 = close.ewm(span=12, adjust=False).mean()
+        ema26 = close.ewm(span=26, adjust=False).mean()
+        macd = ema12 - ema26
+        signal = macd.ewm(span=9, adjust=False).mean()
+        hist = macd - signal
+        macd_label = "Bullish" if hist.iloc[-1] > 0 else "Bearish"
+
+        def _sma_line(n, val):
+            if val is None:
+                return f"  SMA({n:3d})   : N/A (need more history)"
+            arrow = "↑" if price > val else "↓"
+            return f"  SMA({n:3d})   : ${val}  {arrow}"
+
+        lines = [
+            f"📉 Technical Indicators — {symbol}  (period: {period})\n",
+            f"  Price      : ${price}",
+            _sma_line(20, sma20),
+            _sma_line(50, sma50),
+            _sma_line(200, sma200),
+            f"  RSI(14)    : {rsi}  →  {rsi_label}",
+            f"  MACD line  : {round(macd.iloc[-1], 4)}",
+            f"  Signal     : {round(signal.iloc[-1], 4)}",
+            f"  Histogram  : {round(hist.iloc[-1], 4)}  →  {macd_label} momentum",
+        ]
+        return "\n".join(lines)
+    except Exception as e:
+        return f"Error computing technical indicators for '{symbol}': {e}"
+
+
+@mcp.tool()
+def compare_stocks(symbols: str, period: str = "1y") -> str:
+    """
+    Compare the price performance of multiple stocks side-by-side.
+
+    Args:
+        symbols: Comma-separated ticker symbols, e.g. 'AAPL,MSFT,GOOG' (max 6).
+        period: Comparison window — '1mo', '3mo', '6mo', '1y', '3y' (default '1y').
+    """
+    try:
+        tickers = [s.strip().upper() for s in symbols.split(",") if s.strip()]
+        if not tickers:
+            return "No valid ticker symbols provided."
+        if len(tickers) > 6:
+            return "Maximum 6 tickers supported for a single comparison."
+
+        rows = []
+        for sym in tickers:
+            try:
+                data = _history(sym, period)
+                if data.empty:
+                    rows.append((sym, None, None, None, None))
+                    continue
+                close = data["Close"]
+                ret = (close.iloc[-1] - close.iloc[0]) / close.iloc[0] * 100
+                rows.append((sym, ret, close.iloc[-1], close.max(), close.min()))
+            except Exception:
+                rows.append((sym, None, None, None, None))
+
+        lines = [
+            f"📊 Stock Comparison — {period}\n",
+            f"  {'Symbol':<8}  {'Return':>8}   {'Price':>9}   {'52W High':>10}   {'52W Low':>9}",
+            f"  {'-'*57}",
+        ]
+        for sym, ret, price, high, low in rows:
+            if ret is None:
+                lines.append(f"  {sym:<8}  {'N/A':>8}   {'N/A':>9}   {'N/A':>10}   {'N/A':>9}")
+            else:
+                lines.append(
+                    f"  {sym:<8}  {ret:>+7.2f}%   ${price:>8.2f}   ${high:>9.2f}   ${low:>8.2f}"
+                )
+        return "\n".join(lines)
+    except Exception as e:
+        return f"Error comparing stocks: {e}"
+
+
+@mcp.tool()
+def get_options_chain(symbol: str, expiry_index: int = 0) -> str:
+    """
+    Fetch the top calls and puts for a given options expiry date.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL', 'SPY').
+        expiry_index: Which expiry to use — 0 = nearest, 1 = next, etc. (default 0).
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        expiry_dates = ticker.options
+        if not expiry_dates:
+            return f"No options data available for '{symbol}'."
+
+        idx = min(expiry_index, len(expiry_dates) - 1)
+        expiry = expiry_dates[idx]
+        chain = ticker.option_chain(expiry)
+
+        def _fmt_contracts(df, kind):
+            top = df.sort_values("openInterest", ascending=False).head(5)
+            lines = [f"\n{'📗' if kind == 'Calls' else '📕'} Top {kind} (by open interest):"]
+            for _, row in top.iterrows():
+                iv = row.get("impliedVolatility", 0) * 100
+                oi = int(row.get("openInterest", 0))
+                lines.append(
+                    f"  Strike ${row['strike']:.2f}  |  "
+                    f"Last ${row['lastPrice']:.2f}  |  "
+                    f"IV {iv:.1f}%  |  OI {oi:,}"
+                )
+            return "\n".join(lines)
+
+        header = (
+            f"⚙️  Options Chain — {symbol}  |  Expiry: {expiry}\n"
+            f"All expiries: {', '.join(expiry_dates[:6])}"
+            f"{'…' if len(expiry_dates) > 6 else ''}"
+        )
+        return header + _fmt_contracts(chain.calls, "Calls") + _fmt_contracts(chain.puts, "Puts")
+    except Exception as e:
+        return f"Error fetching options chain for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_institutional_holdings(symbol: str) -> str:
+    """
+    Fetch the top institutional holders and ownership breakdown for a stock.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL', 'TSLA').
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        major = ticker.major_holders
+        inst = ticker.institutional_holders
+
+        lines = [f"🏦 Institutional Holdings — {symbol}\n"]
+
+        if major is not None and not major.empty:
+            lines.append("  Ownership breakdown:")
+            for _, row in major.iterrows():
+                lines.append(f"    {row.iloc[1]}: {row.iloc[0]}")
+            lines.append("")
+
+        if inst is not None and not inst.empty:
+            lines.append("  Top institutional holders:")
+            for _, row in inst.head(8).iterrows():
+                name = row.get("Holder", str(row.iloc[0]))
+                pct = row.get("pctHeld") or row.get("% Out")
+                shares = row.get("Shares")
+                pct_str = f"  ({pct*100:.2f}%)" if pct else ""
+                shares_str = f"  {int(shares):,} shares" if shares else ""
+                lines.append(f"    {name}{pct_str}{shares_str}")
+        else:
+            lines.append("  No institutional holder data available.")
+
+        return "\n".join(lines)
+    except Exception as e:
+        return f"Error fetching institutional holdings for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_stock_news(symbol: str, max_results: int = 5) -> str:
+    """
+    Fetch recent news articles about a specific stock from Yahoo Finance.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL', 'TSLA').
+        max_results: Number of articles to return, 1–10 (default 5).
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        news = ticker.news
+        if not news:
+            return f"No recent news found for '{symbol}'."
+        lines = [f"📰 Recent News — {symbol}\n"]
+        for item in news[:min(max_results, 10)]:
+            pub_ts = item.get("providerPublishTime", 0)
+            pub_date = (
+                datetime.fromtimestamp(pub_ts).strftime("%Y-%m-%d %H:%M")
+                if pub_ts else "N/A"
+            )
+            lines.append(
+                f"  📌 {item.get('title', 'No title')}\n"
+                f"     {item.get('publisher', 'Unknown')}  |  {pub_date}\n"
+                f"     {item.get('link', '')}\n"
+            )
+        return "\n".join(lines)
+    except Exception as e:
+        return f"Error fetching news for '{symbol}': {e}"
+
+
+@mcp.tool()
+def current_datetime(format: str = "natural") -> str:
+    """
+    Return the current date and time.  Call this first to anchor temporal context.
+
+    Args:
+        format: 'natural' → 'Saturday, June 07, 2025 at 3:59 PM'
+                'natural_short' → 'Jun 07, 2025 at 3:59 PM'
+                Or any strftime format string (e.g. '%Y-%m-%d').
+    """
+    now = datetime.now()
+    if format == "natural":
+        return now.strftime("%A, %B %d, %Y at %I:%M %p")
+    if format == "natural_short":
+        return now.strftime("%b %d, %Y at %I:%M %p")
+    return now.strftime(format)
+
+
+@mcp.tool()
+def get_earnings_estimates(symbol: str) -> str:
+    """
+    Get EPS and revenue consensus estimates plus recent historical actuals for a stock.
+
+    Returns forward EPS estimate, revenue estimate (low/avg/high), trailing EPS,
+    and the last four quarters of reported EPS vs estimate with surprise %.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL', 'MSFT').
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        info = ticker.info
+        name = info.get("longName", symbol)
+
+        lines = [f"📊 Earnings Estimates — {name} ({symbol})\n"]
+
+        # Near-term consensus from calendar
+        try:
+            cal = ticker.calendar or {}
+            if cal:
+                lines.append("  ── Next Earnings ──")
+                earn_date = cal.get("Earnings Date")
+                if earn_date:
+                    dates = earn_date if isinstance(earn_date, list) else [earn_date]
+                    lines.append(f"  Date              : {', '.join(str(d)[:10] for d in dates)}")
+                for key, label in [
+                    ("Earnings Average",  "EPS Estimate (avg)"),
+                    ("Earnings Low",      "EPS Estimate (low)"),
+                    ("Earnings High",     "EPS Estimate (high)"),
+                    ("Revenue Average",   "Revenue Estimate"),
+                    ("Revenue Low",       "Revenue Low"),
+                    ("Revenue High",      "Revenue High"),
+                ]:
+                    val = cal.get(key)
+                    if val is not None:
+                        if "Revenue" in key:
+                            lines.append(f"  {label:<20}: {_fmt_large(val)}")
+                        else:
+                            lines.append(f"  {label:<20}: ${val:.2f}")
+        except Exception as e:
+            log.warning("calendar fetch failed for %s: %s", symbol, e)
+
+        # Forward EPS / PE from info
+        lines.append("\n  ── Analyst Consensus ──")
+        for key, label in [
+            ("forwardEps",    "Forward EPS"),
+            ("trailingEps",   "Trailing EPS (TTM)"),
+            ("forwardPE",     "Forward P/E"),
+            ("trailingPE",    "Trailing P/E"),
+        ]:
+            val = info.get(key)
+            lines.append(f"  {label:<22}: {'N/A' if val is None else f'${val:.2f}' if 'EPS' in label else f'{val:.2f}'}")
+
+        # Historical quarterly actuals from earnings_dates
+        try:
+            edates = ticker.earnings_dates
+            if edates is not None and not edates.empty:
+                past = edates[edates.index < datetime.now().strftime("%Y-%m-%d")].head(4)
+                if not past.empty:
+                    lines.append("\n  ── Recent Quarterly Actuals ──")
+                    for dt, row in past.iterrows():
+                        est = row.get("EPS Estimate")
+                        rep = row.get("Reported EPS")
+                        sur = row.get("Surprise(%)")
+                        est_s = f"${est:.2f}" if est is not None and est == est else "N/A"
+                        rep_s = f"${rep:.2f}" if rep is not None and rep == rep else "N/A"
+                        sur_s = f"{sur:.1f}%" if sur is not None and sur == sur else "N/A"
+                        lines.append(
+                            f"  {str(dt)[:10]}  Est {est_s:<8} Actual {rep_s:<8} Surprise {sur_s}"
+                        )
+        except Exception as e:
+            log.warning("earnings_dates fetch failed for %s: %s", symbol, e)
+
+        return "\n".join(lines)
+    except Exception as e:
+        log.error("get_earnings_estimates failed for %s: %s", symbol, e)
+        return f"Error fetching earnings estimates for '{symbol}': {e}"
+
+
+@mcp.tool()
+def get_upcoming_earnings(tickers: str = "", days_ahead: int = 14) -> str:
+    """
+    List upcoming earnings dates for multiple companies within a date window.
+
+    If no tickers are provided, scans the built-in large-cap universe (~60 names
+    covering tech, finance, healthcare, energy, consumer, and industrial sectors).
+
+    Args:
+        tickers: Comma-separated symbols, e.g. 'AAPL,MSFT,GOOG'. Leave blank to
+                 scan the default large-cap list.
+        days_ahead: How many calendar days ahead to look (default 14).
+    """
+    try:
+        symbols = (
+            [s.strip().upper() for s in tickers.split(",") if s.strip()]
+            if tickers.strip()
+            else _LARGE_CAPS
+        )
+        today = datetime.today().date()
+        cutoff = today + timedelta(days=days_ahead)
+
+        hits: list[tuple] = []
+        for sym in symbols:
+            try:
+                cal = yf.Ticker(sym).calendar or {}
+                earn_date = cal.get("Earnings Date")
+                if not earn_date:
+                    continue
+                dates = earn_date if isinstance(earn_date, list) else [earn_date]
+                for d in dates:
+                    d_date = d.date() if hasattr(d, "date") else d
+                    if today <= d_date <= cutoff:
+                        eps_est = cal.get("Earnings Average")
+                        rev_est = cal.get("Revenue Average")
+                        hits.append((d_date, sym, eps_est, rev_est))
+                        break
+            except Exception as e:
+                log.debug("skip %s in upcoming_earnings: %s", sym, e)
+
+        if not hits:
+            return f"No earnings found in the next {days_ahead} days for the scanned tickers."
+
+        hits.sort()
+        lines = [f"📅 Upcoming Earnings — next {days_ahead} days\n"]
+        lines.append(f"  {'Date':<12} {'Symbol':<8} {'EPS Est':>9} {'Rev Est':>12}")
+        lines.append(f"  {'-'*45}")
+        for d, sym, eps, rev in hits:
+            eps_s = f"${eps:.2f}" if eps is not None else "N/A"
+            rev_s = _fmt_large(rev) if rev is not None else "N/A"
+            lines.append(f"  {str(d):<12} {sym:<8} {eps_s:>9} {rev_s:>12}")
+        return "\n".join(lines)
+    except Exception as e:
+        log.error("get_upcoming_earnings failed: %s", e)
+        return f"Error fetching upcoming earnings: {e}"
+
+
+@mcp.tool()
+def get_iv_summary(symbol: str) -> str:
+    """
+    Summarise implied volatility (IV) across the nearest option expiry dates.
+
+    Shows average IV for calls and puts per expiry, plus a trend direction
+    (rising / falling / flat) — useful for gauging market uncertainty ahead
+    of earnings or macro events.
+
+    Args:
+        symbol: Ticker symbol (e.g. 'AAPL', 'SPY').
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+        expiries = ticker.options
+        if not expiries:
+            return f"No options data available for '{symbol}'."
+
+        lines = [f"📊 Implied Volatility Summary — {symbol}\n"]
+        lines.append(f"  {'Expiry':<14} {'Avg Call IV':>12} {'Avg Put IV':>12}")
+        lines.append(f"  {'-'*40}")
+
+        iv_series: list[float] = []
+        for exp in expiries[:6]:
+            try:
+                chain = ticker.option_chain(exp)
+                call_iv = chain.calls["impliedVolatility"].dropna().mean()
+                put_iv = chain.puts["impliedVolatility"].dropna().mean()
+                iv_series.append((call_iv + put_iv) / 2)
+                lines.append(
+                    f"  {exp:<14} {call_iv*100:>11.1f}% {put_iv*100:>11.1f}%"
+                )
+            except Exception as e:
+                log.debug("IV fetch failed for %s expiry %s: %s", symbol, exp, e)
+                lines.append(f"  {exp:<14} {'N/A':>12} {'N/A':>12}")
+
+        if len(iv_series) >= 2:
+            trend = (
+                "📈 Rising IV (increasing uncertainty)"
+                if iv_series[-1] > iv_series[0] * 1.05
+                else "📉 Falling IV (uncertainty decreasing)"
+                if iv_series[-1] < iv_series[0] * 0.95
+                else "➡️  Flat IV"
+            )
+            lines.append(f"\n  Trend: {trend}")
+
+        return "\n".join(lines)
+    except Exception as e:
+        log.error("get_iv_summary failed for %s: %s", symbol, e)
+        return f"Error fetching IV summary for '{symbol}': {e}"
+
+
+@mcp.tool()
+def screen_large_caps(
+    sector: str = "",
+    min_market_cap_b: float = 10.0,
+    sort_by: str = "market_cap",
+    top_n: int = 10,
+) -> str:
+    """
+    Screen the large-cap universe for stocks meeting basic criteria.
+
+    Useful for finding sector leaders, high-volume names, or high-market-cap
+    stocks ahead of earnings season.
+
+    Args:
+        sector: Filter by sector keyword, e.g. 'Technology', 'Healthcare',
+                'Financial', 'Energy', 'Consumer'. Leave blank for all sectors.
+        min_market_cap_b: Minimum market cap in billions (default 10).
+        sort_by: Rank by 'market_cap', 'volume', or 'pe_ratio' (default 'market_cap').
+        top_n: Number of results to return (default 10, max 20).
+    """
+    try:
+        rows: list[dict] = []
+        for sym in _LARGE_CAPS:
+            try:
+                info = yf.Ticker(sym).info
+                mcap = info.get("marketCap") or 0
+                if mcap < min_market_cap_b * 1e9:
+                    continue
+                sym_sector = info.get("sector", "")
+                if sector and sector.lower() not in sym_sector.lower():
+                    continue
+                rows.append({
+                    "symbol":     sym,
+                    "name":       info.get("shortName", sym)[:22],
+                    "sector":     sym_sector[:18],
+                    "market_cap": mcap,
+                    "volume":     info.get("averageVolume") or 0,
+                    "pe_ratio":   info.get("trailingPE") or 0,
+                })
+            except Exception as e:
+                log.debug("screen skip %s: %s", sym, e)
+
+        if not rows:
+            return "No stocks matched the given criteria."
+
+        sort_key = {"market_cap": "market_cap", "volume": "volume", "pe_ratio": "pe_ratio"}.get(
+            sort_by, "market_cap"
+        )
+        rows.sort(key=lambda r: r[sort_key], reverse=True)
+        rows = rows[: min(top_n, 20)]
+
+        lines = [
+            f"🔍 Large-Cap Screen — sector='{sector or 'All'}' "
+            f"min_cap=${min_market_cap_b:.0f}B sort={sort_by}\n"
+        ]
+        lines.append(
+            f"  {'Symbol':<7} {'Name':<24} {'Sector':<20} {'Mkt Cap':>9} {'Avg Vol':>10} {'P/E':>6}"
+        )
+        lines.append(f"  {'-'*78}")
+        for r in rows:
+            lines.append(
+                f"  {r['symbol']:<7} {r['name']:<24} {r['sector']:<20} "
+                f"{_fmt_large(r['market_cap']):>9} {r['volume']:>10,} "
+                f"{r['pe_ratio']:>6.1f}" if r["pe_ratio"] else
+                f"  {r['symbol']:<7} {r['name']:<24} {r['sector']:<20} "
+                f"{_fmt_large(r['market_cap']):>9} {r['volume']:>10,} {'N/A':>6}"
+            )
+        return "\n".join(lines)
+    except Exception as e:
+        log.error("screen_large_caps failed: %s", e)
+        return f"Error running large-cap screen: {e}"
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

src/_mcpservers/mcp-news/server.py

@@ -0,0 +1,214 @@
+"""MCP News Server — top headlines, topic search, and category filtering via NewsAPI.org."""
+import datetime
+import logging
+import os
+import sys
+from pathlib import Path
+
+import requests
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+load_dotenv(Path(__file__).resolve().parents[3] / ".env")
+
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] mcp-news: %(message)s",
+)
+log = logging.getLogger("mcp-news")
+
+mcp = FastMCP("News MCP", host="0.0.0.0", port=8002)
+
+
+@mcp.tool()
+def current_datetime(format: str = "natural") -> str:
+    """
+    Return the current date and time.
+
+    Args:
+        format: 'natural' → 'Saturday, June 07, 2025 at 3:59 PM'
+                'natural_short' → 'Jun 07, 2025 at 3:59 PM'
+                Or any strftime format string (e.g. '%Y-%m-%d').
+    """
+    now = datetime.datetime.now()
+    if format == "natural":
+        return now.strftime("%A, %B %d, %Y at %I:%M %p")
+    if format == "natural_short":
+        return now.strftime("%b %d, %Y at %I:%M %p")
+    return now.strftime(format)
+
+
+def _call_newsapi(url: str, params: dict) -> tuple[list[dict], str | None]:
+    """Returns (articles, error_message). error_message is None on success."""
+    api_key = os.getenv("NEWS_API_KEY", "")
+    if not api_key:
+        return [], "NEWS_API_KEY is not set — add it to your .env file"
+    params["apiKey"] = api_key
+    try:
+        response = requests.get(url, params=params, timeout=10)
+        data = response.json()
+        if response.status_code != 200:
+            msg = data.get("message", response.text)
+            return [], f"NewsAPI error {response.status_code}: {msg}"
+        return data.get("articles", []), None
+    except requests.exceptions.ConnectionError:
+        log.error("NewsAPI connection failed: network unreachable")
+        return [], "Could not reach NewsAPI — check your network connection"
+    except Exception as exc:
+        log.error("NewsAPI unexpected error: %s", exc)
+        return [], f"Unexpected error: {exc}"
+
+
+def _format_articles(articles: list[dict], label: str, error: str | None = None) -> str:
+    if error:
+        return f"Error fetching '{label}': {error}"
+    if not articles:
+        return f"No results found for: {label}"
+    lines = [f"{label}\n"]
+    for a in articles:
+        lines.append(
+            f"📰 {a.get('title')}\n"
+            f"   Source: {a.get('source', {}).get('name')}\n"
+            f"   Published: {a.get('publishedAt', 'N/A')}\n"
+            f"   URL: {a.get('url')}\n"
+        )
+    return "\n".join(lines)
+
+
+_COUNTRY_NAMES = {
+    "in": "India", "gb": "United Kingdom", "au": "Australia", "ca": "Canada",
+    "de": "Germany", "fr": "France", "jp": "Japan", "cn": "China",
+    "br": "Brazil", "mx": "Mexico", "za": "South Africa", "ae": "UAE",
+    "sg": "Singapore", "nz": "New Zealand", "ie": "Ireland",
+}
+
+
+@mcp.tool()
+def get_top_headlines(country: str = "us", num_results: int = 5) -> str:
+    """
+    Fetch the latest top headlines for a country.
+
+    Args:
+        country: Two-letter country code (e.g. 'us', 'gb', 'in').
+        num_results: Number of articles to return (default 5).
+
+    Note: If top-headlines returns no results for a country (common with the free API tier),
+    this tool automatically falls back to a keyword search using the country name.
+    """
+    articles, error = _call_newsapi(
+        "https://newsapi.org/v2/top-headlines",
+        {"country": country, "pageSize": num_results},
+    )
+    if error:
+        return _format_articles([], f"Top Headlines — {country.upper()}", error=error)
+
+    # Free-tier may not support all country codes — fall back to keyword search
+    if not articles:
+        country_name = _COUNTRY_NAMES.get(country.lower(), country.upper())
+        from_date = (
+            datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=7)
+        ).strftime("%Y-%m-%dT%H:%M:%SZ")
+        articles, error = _call_newsapi(
+            "https://newsapi.org/v2/everything",
+            {
+                "q": f"{country_name} news",
+                "pageSize": num_results,
+                "sortBy": "publishedAt",
+                "language": "en",
+                "from": from_date,
+            },
+        )
+        label = f"Top Headlines — {country_name} (via keyword search)"
+        return _format_articles(articles, label, error=error)
+
+    return _format_articles(articles, f"Top Headlines — {country.upper()}")
+
+
+@mcp.tool()
+def search_news(query: str, num_results: int = 5, days_back: int = 7) -> str:
+    """
+    Search for recent news articles on a specific topic.
+
+    Args:
+        query: Keyword or topic (e.g. 'Tesla earnings', 'AI regulation').
+        num_results: Number of articles to return (default 5).
+        days_back: How many days back to search (default 7).
+    """
+    from_date = (
+        datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=days_back)
+    ).strftime("%Y-%m-%dT%H:%M:%SZ")
+    articles, error = _call_newsapi(
+        "https://newsapi.org/v2/everything",
+        {
+            "q": query,
+            "pageSize": num_results,
+            "sortBy": "publishedAt",
+            "language": "en",
+            "from": from_date,
+        },
+    )
+    return _format_articles(articles, f"News Search — '{query}' (last {days_back} days)", error=error)
+
+
+@mcp.tool()
+def get_news_by_category(
+    category: str = "business", country: str = "us", num_results: int = 5
+) -> str:
+    """
+    Fetch top headlines filtered by category.
+
+    Args:
+        category: One of 'business', 'entertainment', 'general', 'health',
+                  'science', 'sports', 'technology'.
+        country: Two-letter country code (default 'us').
+        num_results: Number of articles to return (default 5).
+    """
+    articles, error = _call_newsapi(
+        "https://newsapi.org/v2/top-headlines",
+        {"category": category, "country": country, "pageSize": num_results},
+    )
+    return _format_articles(
+        articles, f"Top {category.capitalize()} Headlines — {country.upper()}", error=error
+    )
+
+
+@mcp.tool()
+def search_company_news(
+    company_name: str,
+    num_results: int = 5,
+    days_back: int = 30,
+    language: str = "en",
+) -> str:
+    """
+    Search for news about a company by its full name rather than a ticker symbol.
+
+    Useful when the caller knows the company name but not the exchange ticker,
+    or wants broader coverage (e.g. subsidiary names, product names).
+
+    Args:
+        company_name: Company or brand name (e.g. 'Apple Inc', 'OpenAI', 'SpaceX').
+        num_results: Number of articles to return (default 5).
+        days_back: How many days back to search (default 30).
+        language: Two-letter language code for results (default 'en').
+    """
+    from_date = (
+        datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=days_back)
+    ).strftime("%Y-%m-%dT%H:%M:%SZ")
+    articles, error = _call_newsapi(
+        "https://newsapi.org/v2/everything",
+        {
+            "q": f'"{company_name}"',
+            "pageSize": num_results,
+            "sortBy": "publishedAt",
+            "language": language,
+            "from": from_date,
+        },
+    )
+    return _format_articles(
+        articles, f"News for '{company_name}' (last {days_back} days)", error=error
+    )
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

src/_mcpservers/mcp-web-search/server.py

@@ -0,0 +1,172 @@
+"""MCP Web Search Server — DuckDuckGo search, page fetching, and current datetime."""
+import logging
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import requests
+from bs4 import BeautifulSoup
+from ddgs import DDGS
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+load_dotenv(Path(__file__).resolve().parents[3] / ".env")
+
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] mcp-web-search: %(message)s",
+)
+log = logging.getLogger("mcp-web-search")
+
+mcp = FastMCP("Web Search MCP", host="0.0.0.0", port=8001)
+
+
+# ---------------------------------------------------------------------------
+# Datetime
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def current_datetime(format: str = "natural") -> str:
+    """
+    Return the current date and time.
+
+    Args:
+        format: 'natural' → 'Saturday, June 07, 2025 at 3:59 PM'
+                'natural_short' → 'Jun 07, 2025 at 3:59 PM'
+                Or any strftime format string (e.g. '%Y-%m-%d').
+    """
+    now = datetime.now()
+    if format == "natural":
+        return now.strftime("%A, %B %d, %Y at %I:%M %p")
+    if format == "natural_short":
+        return now.strftime("%b %d, %Y at %I:%M %p")
+    return now.strftime(format)
+
+
+# ---------------------------------------------------------------------------
+# Web search
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def duckduckgo_search(
+    query: str,
+    max_results: int = 5,
+    search_type: str = "text",
+    timelimit: str = "d",
+    region: str = "us-en",
+) -> list[dict]:
+    """
+    Search the web via DuckDuckGo and return result snippets.
+
+    Args:
+        query: The search query.
+        max_results: Number of results to return (default 5).
+        search_type: 'text' for general results, 'news' to include publication dates.
+        timelimit: Recency filter — 'd' day, 'w' week, 'm' month, 'y' year.
+        region: Region code (default 'us-en').
+    """
+    results: list[dict] = []
+    with DDGS() as ddgs:
+        if search_type == "news":
+            raw = ddgs.news(query, max_results=max_results, timelimit=timelimit, region=region)
+            for r in raw:
+                results.append({
+                    "title": r.get("title", ""),
+                    "link": r.get("url", ""),
+                    "snippet": r.get("body", ""),
+                    "datetime": r.get("date", ""),
+                })
+        else:
+            raw = ddgs.text(query, max_results=max_results, timelimit=timelimit, region=region)
+            for r in raw:
+                results.append({
+                    "title": r.get("title", ""),
+                    "link": r.get("href", ""),
+                    "snippet": r.get("body", ""),
+                })
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Page fetching
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def fetch_page_content(url: str, timeout: int = 3) -> str:
+    """
+    Download a web page and return its readable text content.
+
+    Args:
+        url: The URL to fetch.
+        timeout: Request timeout in seconds (default 3).
+    """
+    try:
+        headers = {
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/91.0.4472.124 Safari/537.36"
+            )
+        }
+        response = requests.get(url, headers=headers, timeout=timeout)
+        response.raise_for_status()
+        soup = BeautifulSoup(response.content, "html.parser")
+        for tag in soup(["script", "style", "nav", "footer", "header"]):
+            tag.decompose()
+        text = soup.get_text(separator="\n", strip=True)
+        lines = (line.strip() for line in text.splitlines())
+        chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
+        return "\n".join(chunk for chunk in chunks if chunk)
+    except Exception as e:
+        return f"[ERROR] Could not fetch {url}: {e}"
+
+
+@mcp.tool()
+def extract_tables_from_page(url: str, timeout: int = 5) -> str:
+    """
+    Extract all HTML tables from a web page and return them as readable text.
+
+    Especially useful for financial data pages, Wikipedia articles, and
+    data-heavy sites where the information lives inside <table> elements.
+
+    Args:
+        url: The URL to fetch.
+        timeout: Request timeout in seconds (default 5).
+    """
+    try:
+        headers = {
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/91.0.4472.124 Safari/537.36"
+            )
+        }
+        response = requests.get(url, headers=headers, timeout=timeout)
+        response.raise_for_status()
+        soup = BeautifulSoup(response.content, "html.parser")
+        tables = soup.find_all("table")
+        if not tables:
+            return f"No tables found on {url}."
+
+        results = [f"Found {len(tables)} table(s) on {url}\n"]
+        for i, table in enumerate(tables, 1):
+            rows = table.find_all("tr")
+            parsed = []
+            for row in rows:
+                cells = [c.get_text(strip=True) for c in row.find_all(["th", "td"])]
+                if any(cells):
+                    parsed.append(" | ".join(cells))
+            if parsed:
+                results.append(f"--- Table {i} ---")
+                results.extend(parsed)
+                results.append("")
+        return "\n".join(results)
+    except Exception as e:
+        return f"[ERROR] Could not extract tables from {url}: {e}"
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

src/nexus/Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    DEBIAN_FRONTEND=noninteractive \
+    PYTHONPATH=/app:/app/common:$PYTHONPATH
+
+WORKDIR /app
+
+# System deps
+RUN apt-get update && apt-get install -y \
+    git build-essential curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
+
+# Copy project metadata
+COPY pyproject.toml .
+COPY uv.lock .
+
+# Copy required folders
+COPY common/ ./common/
+COPY src/chatbot/ ./src/chatbot/
+
+# Install dependencies using uv, then export and install with pip to system
+RUN uv sync --frozen --no-dev && \
+    uv pip install -e . --system
+
+# Copy entry point
+COPY run.py .
+
+EXPOSE 7860
+
+CMD ["python", "run.py", "chatbot", "--port", "7860"]

src/nexus/README.md

@@ -0,0 +1,26 @@
+---
+title: Nexus
+emoji: 🔮
+colorFrom: pink
+colorTo: indigo
+sdk: docker
+app_file: app.py
+pinned: false
+license: mit
+short_description: Multi-specialist AI orchestrator for web research
+---
+
+# Nexus
+
+Nexus is a multi-specialist AI research orchestrator. It fans out every query to three dedicated agents — a Financial Markets Analyst, a News Intelligence Specialist, and a Web Research Specialist — then synthesises their reports into a single, coherent answer.
+
+## What it does
+
+- **Finance** — stock prices, market sentiment, analyst ratings, earnings, IV analysis, sector screening
+- **News** — breaking headlines, topic-specific articles, category filtering
+- **Web Research** — deep-dive fact-finding with cited sources
+- **Orchestration** — parallel specialist calls, automatic web fallback on failure, content guardrails
+
+## Stack
+
+Streamlit · OpenAI Agents SDK · MCP (stdio) · Google Gemini / GPT-4o

src/nexus/app.py

@@ -0,0 +1,356 @@
+import asyncio
+import glob
+import logging
+import os
+import uuid
+
+from dotenv import load_dotenv
+load_dotenv()  # must run before any module that reads env vars
+
+import streamlit as st
+from agents import Runner, SQLiteSession
+from agents.exceptions import InputGuardrailTripwireTriggered
+from agents.mcp import MCPServerManager
+from model_factory import MODEL_LABELS, OLLAMA_MODEL_OPTIONS, provider_ready
+from orchestrator import create_orchestrator
+from tracing import setup_langfuse_tracing
+
+setup_langfuse_tracing()  # installs Langfuse processor or disables SDK tracing
+
+# -----------------------------
+# Configuration & Utils
+# -----------------------------
+st.set_page_config(
+    page_title="Nexus",
+    layout="wide",
+    page_icon="🔗"
+)
+
+def load_prompts(folder="prompts"):
+    prompts = []
+    prompt_labels = []
+    if os.path.exists(folder):
+        for file_path in glob.glob(os.path.join(folder, "*.txt")):
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read().strip()
+                if content:
+                    prompts.append(content)
+
+            prompt_labels.append(os.path.basename(file_path).replace("_", " ").replace(".txt", "").title())
+    return prompts, prompt_labels
+
+prompts, prompt_labels = load_prompts()
+
+# -----------------------------
+# Session State
+# -----------------------------
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+
+if "ai_session_id" not in st.session_state:
+    st.session_state.ai_session_id = str(uuid.uuid4())
+
+# Persistent SQLite session
+if "ai_session" not in st.session_state:
+    st.session_state.ai_session = SQLiteSession(f"conversation_{st.session_state.ai_session_id}.db")
+
+session = st.session_state.ai_session
+
+# -----------------------------
+# Premium Styling
+# -----------------------------
+st.markdown("""
+<style>
+    /* ---------------------------------------------------------------------
+       1. GLOBAL & RESET
+       --------------------------------------------------------------------- */
+    * {
+        box-sizing: border-box;
+    }
+    
+    .stApp, [data-testid="stAppViewContainer"] {
+        /* Standard Streamlit background */
+        background-color: #f8f9fa;
+        font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji';
+    }
+    
+    html {
+        -webkit-text-size-adjust: 100%; /* Prevent iOS font boosting */
+    }
+    
+    /* ---------------------------------------------------------------------
+       2. LAYOUT & HERO BANNER
+       --------------------------------------------------------------------- */
+    
+    /* Mobile font optimization */
+    @media (max-width: 768px) {
+        /* Target all markdown text specifically */
+        .stMarkdown p, .stMarkdown li, .stChatMessage p, .message-content, .stDataFrame, .stTable {
+            font-size: 16px !important;
+            line-height: 1.6 !important;
+            color: #1a1a1a !important;
+        }
+        
+        h1, h2, h3, h4, h5, h6 {
+            color: #1a1a1a !important;
+        }
+    }
+    
+    /* Desktop Layout */
+    @media (min-width: 769px) {
+        .block-container {
+            padding-top: 0 !important;
+            padding-bottom: 2rem !important;
+            padding-left: 5rem !important;
+            padding-right: 5rem !important;
+            max-width: 100% !important;
+        }
+        
+        .hero-container {
+            margin-top: -3rem;
+            margin-left: -5rem;
+            margin-right: -5rem;
+            /* Simple negative margins to pull edge-to-edge */
+            padding: 2.5rem 1rem 2rem 1rem; /* Compact desktop padding */
+        }
+    }
+    
+    /* Mobile Layout */
+    @media (max-width: 768px) {
+        .block-container {
+            padding-left: 1rem !important;
+            padding-right: 1rem !important;
+            padding-top: 0 !important;
+        }
+        
+        .hero-container {
+            margin-top: -2rem;
+            margin-left: -1rem;
+            margin-right: -1rem;
+            /* Break out of the 1rem padding */
+            padding: 2rem 1rem 1.5rem 1rem; /* Compact mobile padding */
+            border-radius: 0 0 12px 12px;
+        }
+        
+        /* Ensure font sizes are standard (Streamlit defaults is ~16px) */
+        /* We DO NOT override them to 17px/fixed, allowing system zoom to work. */
+    }
+
+    /* Hero Styling */
+    .hero-container {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        color: white;
+        text-align: center;
+        border-radius: 0 0 16px 16px;
+        box-shadow: 0 4px 15px rgba(0,0,0,0.1);
+        margin-bottom: 2rem;
+    }
+
+    .hero-title {
+        font-size: 2rem; /* Slightly smaller */
+        font-weight: 700;
+        margin-bottom: 0.25rem;
+        color: white !important;
+    }
+    .hero-subtitle {
+        font-size: 1rem;
+        opacity: 0.95;
+        font-weight: 400;
+        color: rgba(255,255,255,0.95) !important;
+    }
+    
+    /* Remove Header Decoration */
+    header[data-testid="stHeader"] {
+        background-color: transparent !important;
+        height: 0 !important;
+        z-index: 100;
+    }
+    div[data-testid="stDecoration"] { display: none; }
+    
+    /* ---------------------------------------------------------------------
+       3. COMPONENT STYLING (Healthcare-like)
+       --------------------------------------------------------------------- */
+    
+    /* Chat Bubbles - Clean & Readable */
+    .stChatMessage {
+        background-color: white;
+        border-radius: 12px;
+        border: 1px solid #e5e5e5;
+        box-shadow: 0 1px 2px rgba(0,0,0,0.05);
+        padding: 1rem;
+    }
+    
+    .stChatMessage[data-testid="stChatMessage"]:nth-of-type(odd) {
+         background-color: #f8f9fa;
+    }
+    
+    /* Input Fields */
+    .stTextInput input {
+        border-radius: 20px; /* Matching healthcare-assistant roundness */
+        border: 1px solid #ddd;
+        padding: 0.75rem 1rem;
+    }
+    
+    /* Buttons */
+    .stButton button {
+        border-radius: 20px; /* Matching healthcare-assistant */
+        min-height: 48px;
+        font-weight: 500;
+    }
+
+    /* Sidebar */
+    section[data-testid="stSidebar"] {
+        background-color: #ffffff;
+        border-right: 1px solid #eaeaea;
+    }
+    
+    /* Minimize Sidebar Top Padding */
+    section[data-testid="stSidebar"] .block-container {
+        padding-top: 0rem !important;
+        padding-bottom: 0rem !important;
+    }
+</style>
+""", unsafe_allow_html=True)
+
+# -----------------------------
+# Cached Orchestrator Factory
+# -----------------------------
+
+@st.cache_resource
+def _get_orchestrator(model_label: str, ollama_model: str):
+    """Create and cache an orchestrator for the given model selection."""
+    from model_factory import get_model_from_label
+    m = get_model_from_label(model_label, ollama_model=ollama_model)
+    return create_orchestrator(m)
+
+
+# -----------------------------
+# Logic
+# -----------------------------
+
+async def get_ai_response(prompt: str) -> str:
+    model_label = st.session_state.get("model_label", MODEL_LABELS[0])
+    ollama_model = st.session_state.get("ollama_model", "llama3.2")
+    orchestrator, mcp_servers = _get_orchestrator(model_label, ollama_model)
+    try:
+        async with MCPServerManager(mcp_servers):
+            result = await Runner.run(orchestrator, prompt, session=st.session_state.ai_session)
+        return result.final_output
+    except InputGuardrailTripwireTriggered as e:
+        reasoning = (
+            getattr(e, "reasoning", None)
+            or getattr(getattr(e, "output", None), "reasoning", None)
+            or getattr(getattr(e, "guardrail_output", None), "reasoning", None)
+            or "Guardrail triggered, but no reasoning provided."
+        )
+        return f"⚠️ **Guardrail Blocked Input**\n\n{reasoning}"
+    except Exception as e:
+        msg = str(e)
+        if "401" in msg or "invalid_api_key" in msg or "AuthenticationError" in type(e).__name__:
+            from model_factory import MODELS, _BY_LABEL
+            cfg = _BY_LABEL.get(model_label)
+            key_hint = f" Check `{cfg.key_env}` in your `.env`." if cfg and cfg.key_env else ""
+            return f"❌ **Authentication Error** — API key rejected for **{model_label}**.{key_hint}"
+        if "Connection" in msg or "ConnectError" in msg or "refused" in msg.lower():
+            return f"❌ **Connection Error** — Could not reach the model endpoint for **{model_label}**. Is the service running?"
+        return f"❌ **Error**: {msg}"
+
+
+# -----------------------------
+# Sidebar
+# -----------------------------
+with st.sidebar:
+    # --- Model Selection ---
+    st.markdown("### 🧠 Model")
+
+    selected_label = st.selectbox(
+        "Choose a model",
+        options=MODEL_LABELS,
+        index=MODEL_LABELS.index(st.session_state.get("model_label", MODEL_LABELS[0])),
+        key="model_label",
+        label_visibility="collapsed",
+    )
+
+    # Ollama model name picker
+    if selected_label == "Ollama (local)":
+        st.selectbox(
+            "Ollama model",
+            options=OLLAMA_MODEL_OPTIONS,
+            key="ollama_model",
+            label_visibility="collapsed",
+        )
+    else:
+        st.session_state.setdefault("ollama_model", "llama3.2")
+
+    # Provider readiness indicator
+    _ollama_model = st.session_state.get("ollama_model", "llama3.2")
+    ready, warn = provider_ready(selected_label, ollama_model=_ollama_model)
+    st.session_state["_provider_ready"] = ready
+    if not ready:
+        st.warning(warn, icon="⚠️")
+    else:
+        st.caption("✅ Provider ready")
+
+    st.markdown("---")
+
+    # --- Quick Starters ---
+    st.markdown("### ⚡ Quick Starters")
+    st.markdown("Select a prompt to start:")
+
+    selected_prompt = None
+    for idx, prompt_text in enumerate(prompts):
+        label = prompt_labels[idx] if idx < len(prompt_labels) else f"Prompt {idx+1}"
+        if st.button(label, key=f"sidebar_btn_{idx}", use_container_width=True):
+            st.session_state.messages = []
+            st.session_state.ai_session_id = str(uuid.uuid4())
+            st.session_state.ai_session = SQLiteSession(
+                f"conversation_{st.session_state.ai_session_id}.db"
+            )
+            selected_prompt = prompt_text
+
+    st.markdown("---")
+    if st.button("🗑️ Clear Conversation", use_container_width=True):
+        st.session_state.messages = []
+        st.rerun()
+
+# -----------------------------
+# Main Content
+# -----------------------------
+
+# Hero Banner (Always visible & Sticky)
+st.markdown("""
+    <div class="hero-container" role="banner">
+        <div class="hero-title">🔗 Nexus</div>
+        <div class="hero-subtitle">Your intelligent hub for research, analysis, and more.</div>
+    </div>
+""", unsafe_allow_html=True)
+
+# Display Chat History
+for message in st.session_state.messages:
+    with st.chat_message(message["role"]):
+        st.markdown(message["content"], unsafe_allow_html=True)
+
+# Chat Input Handling
+_provider_ok = st.session_state.get("_provider_ready", True)
+_chat_placeholder = "Type your message..." if _provider_ok else "⚠️ Provider not ready — check sidebar"
+if prompt := (st.chat_input(_chat_placeholder, disabled=not _provider_ok) or selected_prompt):
+    # User Message
+    st.session_state.messages.append({"role": "user", "content": prompt})
+    with st.chat_message("user"):
+        st.markdown(prompt)
+
+    # Assistant Response
+    with st.chat_message("assistant"):
+        with st.spinner("Thinking..."):
+            response_text = asyncio.run(get_ai_response(prompt))
+            st.markdown(response_text, unsafe_allow_html=True)
+
+
+            
+    st.session_state.messages.append({"role": "assistant", "content": response_text})
+    
+    # If it was a sidebar click, we need to rerun to clear the selection state potentially, 
+    # but st.chat_input usually handles focus. With buttons, a rerun happens automatically 
+    # but we want to make sure the input box is cleared (which 'selected_prompt' doesn't use).
+    if selected_prompt:
+        st.rerun()

src/nexus/content_guardrail.py

@@ -0,0 +1,65 @@
+"""Content Policy Guardrail — blocks unparliamentary language before it reaches the orchestrator."""
+from agents import Agent, GuardrailFunctionOutput, Runner, input_guardrail
+from pydantic import BaseModel
+
+from model_factory import get_model
+
+model = get_model("google", "gemini-2.5-flash")
+
+_INSTRUCTIONS = """
+You are the **Content Policy Guardrail**. Your sole job is to decide whether a
+user message violates the content policy.
+
+## Policy
+Flag the message as invalid (`is_valid: false`) ONLY if it contains:
+- Profanity or unparliamentary / abusive language directed at people.
+
+All other messages — questions, commands, opinions, technical requests — are valid.
+
+## Output (JSON, mandatory)
+{
+    "is_valid": <true|false>,
+    "reasoning": "<one sentence explanation>"
+}
+"""
+
+
+class ContentValidationResult(BaseModel):
+    is_valid: bool
+    reasoning: str
+
+
+def create_guardrail(m=None):
+    """Return (policy_agent, guardrail_fn) using the supplied model (default: Gemini)."""
+    _model = m or model
+    policy_agent = Agent(
+        name="Content Policy Guardrail",
+        model=_model,
+        output_type=ContentValidationResult,
+        instructions=_INSTRUCTIONS,
+    )
+    policy_agent.description = (
+        "Screens user input for unparliamentary language and blocks policy-violating messages."
+    )
+
+    @input_guardrail
+    async def _enforce(ctx, agent, input_data):
+        result = await Runner.run(policy_agent, input_data, context=ctx.context)
+        raw = result.final_output
+        if isinstance(raw, ContentValidationResult):
+            validated = raw
+        else:
+            validated = ContentValidationResult(
+                is_valid=False,
+                reasoning=f"Unexpected guardrail output type: {type(raw)}",
+            )
+        return GuardrailFunctionOutput(
+            output_info=validated,
+            tripwire_triggered=not validated.is_valid,
+        )
+
+    return policy_agent, _enforce
+
+
+# Module-level defaults (backwards compat / tests)
+content_policy_agent, enforce_content_policy = create_guardrail(model)

src/nexus/model_factory.py

@@ -0,0 +1,190 @@
+"""Model factory — creates OpenAIChatCompletionsModel instances for multiple providers.
+
+Providers supported:
+  google  — Gemini models via Google's OpenAI-compatible endpoint
+  openai  — OpenAI models (GPT-4o, etc.)
+  ollama  — Local Ollama models via its OpenAI-compatible server
+
+Langfuse tracing is applied automatically when LANGFUSE_SECRET_KEY and
+LANGFUSE_PUBLIC_KEY are set in the environment.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from agents import OpenAIChatCompletionsModel
+
+# ---------------------------------------------------------------------------
+# Model catalog
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ModelConfig:
+    label: str        # display name shown in the sidebar
+    provider: str     # internal routing key
+    model_name: str   # identifier sent to the API
+    key_env: str      # env var for the API key (empty → no key needed)
+    note: str         # short description shown as tooltip / helper text
+
+
+MODELS: list[ModelConfig] = [
+    ModelConfig(
+        "Gemini 2.5 Flash", "google", "gemini-2.5-flash",
+        "GOOGLE_API_KEY", "Fast · free tier available",
+    ),
+    ModelConfig(
+        "Gemini 2.5 Pro", "google", "gemini-2.5-pro",
+        "GOOGLE_API_KEY", "More capable Google model",
+    ),
+    ModelConfig(
+        "GPT-4o", "openai", "gpt-4o",
+        "OPENAI_API_KEY", "OpenAI flagship model",
+    ),
+    ModelConfig(
+        "GPT-4o Mini", "openai", "gpt-4o-mini",
+        "OPENAI_API_KEY", "Faster · cheaper OpenAI model",
+    ),
+    ModelConfig(
+        "Ollama (local)", "ollama", "",      # model_name chosen at runtime
+        "", "Local model served by Ollama",
+    ),
+]
+
+MODEL_LABELS: list[str] = [m.label for m in MODELS]
+_BY_LABEL: dict[str, ModelConfig] = {m.label: m for m in MODELS}
+
+OLLAMA_MODEL_OPTIONS: list[str] = [
+    "qwen3:8b", "llama3.2", "llama3.1", "mistral", "phi4", "gemma3", "qwen2.5",
+]
+
+_PROVIDER_BASE_URLS: dict[str, str | None] = {
+    "google": "https://generativelanguage.googleapis.com/v1beta/openai/",
+    "openai": None,
+    "ollama": os.environ.get("OLLAMA_BASE_URL", "http://localhost:30786/v1"),
+}
+
+
+def _wsl2_host_ip() -> str | None:
+    """Return the Windows host IP visible from WSL2, or None if not in WSL2."""
+    try:
+        with open("/etc/resolv.conf") as f:
+            for line in f:
+                if line.startswith("nameserver"):
+                    ip = line.split()[1].strip()
+                    # WSL2 nameserver is typically in the 172.x.x.x range
+                    if ip.startswith("172."):
+                        return ip
+    except OSError:
+        pass
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def get_model(provider: str, model_name: str) -> OpenAIChatCompletionsModel:
+    """Return a ready-to-use model object for the given provider + model name."""
+    from openai import AsyncOpenAI
+
+    base_url = _PROVIDER_BASE_URLS.get(provider)
+    key_env  = _BY_LABEL_by_provider(provider)
+    api_key  = os.environ.get(key_env, "") if key_env else "ollama"
+
+    kwargs: dict = {"api_key": api_key}
+    if base_url:
+        kwargs["base_url"] = base_url
+
+    return OpenAIChatCompletionsModel(
+        model=model_name,
+        openai_client=AsyncOpenAI(**kwargs),
+    )
+
+
+def get_model_from_label(label: str, ollama_model: str = "llama3.2") -> OpenAIChatCompletionsModel:
+    """Convenience wrapper used by the Streamlit UI."""
+    cfg = _BY_LABEL.get(label)
+    if cfg is None:
+        raise ValueError(f"Unknown model label: {label!r}")
+    model_name = ollama_model if cfg.provider == "ollama" else cfg.model_name
+    return get_model(cfg.provider, model_name)
+
+
+def provider_ready(label: str, ollama_model: str = "") -> tuple[bool, str]:
+    """Return (is_ready, warning_message) for a model label."""
+    cfg = _BY_LABEL.get(label)
+    if cfg is None:
+        return False, f"Unknown model: {label}"
+
+    if cfg.provider == "ollama":
+        return _check_ollama(ollama_model)
+
+    if not cfg.key_env:
+        return True, ""
+    key = os.environ.get(cfg.key_env, "")
+    if not key:
+        return False, f"{cfg.key_env} is not set in environment"
+    return True, ""
+
+
+def _check_ollama(model_name: str = "") -> tuple[bool, str]:
+    """Ping Ollama and optionally verify the requested model is loaded.
+
+    Tries localhost first; if refused, retries with the WSL2 Windows-host IP
+    (read from /etc/resolv.conf) and updates OLLAMA_BASE_URL for the session.
+    """
+    import requests as _req
+
+    def _try(base_url: str) -> tuple[bool, str, bool]:
+        """Returns (reachable, error_msg, model_ok)."""
+        tags_url = base_url.rstrip("/").removesuffix("/v1") + "/api/tags"
+        try:
+            r = _req.get(tags_url, timeout=2)
+            r.raise_for_status()
+            if model_name:
+                available = [m.get("name", "") for m in r.json().get("models", [])]
+                if not any(model_name in n for n in available):
+                    return True, f"Model '{model_name}' not found — run: ollama pull {model_name}", False
+            return True, "", True
+        except _req.exceptions.ConnectionError:
+            return False, "", False
+        except Exception as exc:
+            return True, str(exc), False
+
+    # 1. Try whatever is currently configured (default: localhost)
+    base = os.environ.get("OLLAMA_BASE_URL", "http://localhost:30786/v1")
+    reachable, msg, ok = _try(base)
+    if reachable:
+        return (True, "") if ok else (False, msg)
+
+    # 2. Localhost refused — try the WSL2 Windows-host IP
+    wsl_ip = _wsl2_host_ip()
+    if wsl_ip:
+        wsl_base = f"http://{wsl_ip}:30786/v1"
+        reachable, msg, ok = _try(wsl_base)
+        if reachable:
+            # Persist for this session so get_model() also uses it
+            os.environ["OLLAMA_BASE_URL"] = wsl_base
+            _PROVIDER_BASE_URLS["ollama"] = wsl_base
+            return (True, "") if ok else (False, msg)
+
+    # 3. Both failed
+    host = f"localhost or {wsl_ip}" if wsl_ip else "localhost"
+    return False, (
+        f"Ollama not reachable at {host}:30786. "
+        "Check that the Ollama pod is running and the NodePort service is healthy "
+        "(`kubectl get svc` / `kubectl get pods`). "
+        "Override the URL with OLLAMA_BASE_URL in your .env if the address differs."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _BY_LABEL_by_provider(provider: str) -> str:
+    for m in MODELS:
+        if m.provider == provider and m.key_env:
+            return m.key_env
+    return ""

src/nexus/orchestrator.py

@@ -0,0 +1,147 @@
+"""AI Research Orchestrator — fans out to specialist agents and synthesises results."""
+import asyncio
+
+from agents import Agent, Runner, function_tool
+from agents.mcp import MCPServerStdio
+
+from content_guardrail import create_guardrail, enforce_content_policy
+from specialists import (
+    create_finance_agent, create_news_agent, create_web_agent,
+    finance_agent, news_agent, web_agent,
+)
+from model_factory import get_model
+
+_INSTRUCTIONS = """
+You are the **AI Research Orchestrator** — the central intelligence that coordinates
+three specialist agents and delivers polished, multi-source answers.
+
+## Specialist Roster
+| Agent | Best for |
+|---|---|
+| Financial Markets Analyst | Stock prices, market sentiment, analyst ratings, earnings, IV, sector screening |
+| News Intelligence Specialist | Breaking news, recent events, headlines by topic or category |
+| Web Research Specialist | General knowledge, history, facts, how-to, research |
+
+## Workflow
+1. **Understand** the user's intent.
+2. **Select** only the specialists needed — set unused agents to `false` in
+   `broadcast_to_specialists` to reduce latency.
+3. **Call** `broadcast_to_specialists` with the user's query.
+4. **Synthesise** the reports into one clear, structured response.
+
+## Response Templates
+- **Finance query** → Financial Snapshot table + Key Developments + Synthesis
+- **News query** → Executive Summary + numbered headlines with sources
+- **Research query** → Answer with cited evidence + Sources section
+- **General chat** → Conversational markdown (bullet points, bold highlights)
+- **Code request** → Fenced code blocks + step-by-step explanation
+
+## Constraints
+- For any query that needs live data, ALWAYS call `broadcast_to_specialists`.
+- Finance and News specialists automatically fall back to Web Research if they fail.
+- If all specialist reports return errors, tell the user clearly and suggest retrying.
+"""
+
+
+def _make_broadcast_tool(finance_a, news_a, web_a):
+    @function_tool
+    async def broadcast_to_specialists(
+        query: str,
+        include_finance: bool = True,
+        include_news: bool = True,
+        include_web_search: bool = True,
+    ) -> str:
+        """
+        Fan out the query to selected specialist agents in parallel and merge reports.
+        Finance and News specialists automatically fall back to Web Research on failure.
+
+        Args:
+            query: The user's question or research topic.
+            include_finance: Query the Financial Markets Analyst (default True).
+            include_news: Query the News Intelligence Specialist (default True).
+            include_web_search: Query the Web Research Specialist (default True).
+        """
+        active: list[tuple[str, object]] = []
+        if include_finance:
+            active.append(("Financial Markets Analyst", Runner.run(finance_a, query)))
+        if include_news:
+            active.append(("News Intelligence Specialist", Runner.run(news_a, query)))
+        if include_web_search:
+            active.append(("Web Research Specialist", Runner.run(web_a, query)))
+
+        if not active:
+            return "No specialist agents were selected for this query."
+
+        names      = [name for name, _ in active]
+        coroutines = [coro for _, coro in active]
+        results    = list(await asyncio.gather(*coroutines, return_exceptions=True))
+
+        # Web fallback for failed Finance / News specialists
+        fallback_indices = [
+            i for i, (name, res) in enumerate(zip(names, results))
+            if isinstance(res, Exception) and name != "Web Research Specialist"
+        ]
+        if fallback_indices:
+            fallbacks = await asyncio.gather(
+                *[Runner.run(web_a, query) for _ in fallback_indices],
+                return_exceptions=True,
+            )
+            for i, fb in zip(fallback_indices, fallbacks):
+                results[i] = fb
+                names[i]   = f"{names[i]} → Web Fallback"
+
+        sections = [
+            f"✅ {name} Report:\n{res.final_output}"
+            if not isinstance(res, Exception)
+            else f"❌ {name} — Error: {res}"
+            for name, res in zip(names, results)
+        ]
+
+        return (
+            "\n--- SPECIALIST REPORTS BEGIN ---\n\n"
+            + "\n\n---\n\n".join(sections)
+            + "\n\n--- SPECIALIST REPORTS END ---"
+        )
+
+    return broadcast_to_specialists
+
+
+def create_orchestrator(m=None) -> tuple[Agent, list[MCPServerStdio]]:
+    """Return (orchestrator, [mcp_servers]).  Caller manages server lifecycle."""
+    _model = m or get_model("google", "gemini-2.5-flash")
+    _finance, _finance_mcp = create_finance_agent(_model)
+    _news,    _news_mcp    = create_news_agent(_model)
+    _web,     _web_mcp     = create_web_agent(_model)
+    _, _guardrail = create_guardrail(_model)
+
+    orchestrator = Agent(
+        name="AI Research Orchestrator",
+        model=_model,
+        tools=[_make_broadcast_tool(_finance, _news, _web)],
+        input_guardrails=[_guardrail],
+        instructions=_INSTRUCTIONS,
+    )
+    orchestrator.description = (
+        "Coordinates the Financial Markets Analyst, News Intelligence Specialist, and "
+        "Web Research Specialist to deliver comprehensive, multi-source answers."
+    )
+    return orchestrator, [_finance_mcp, _news_mcp, _web_mcp]
+
+
+# ---------------------------------------------------------------------------
+# Module-level defaults (backwards compat / tests)
+# ---------------------------------------------------------------------------
+
+broadcast_to_specialists = _make_broadcast_tool(finance_agent, news_agent, web_agent)
+
+ai_research_orchestrator = Agent(
+    name="AI Research Orchestrator",
+    model=get_model("google", "gemini-2.5-flash"),
+    tools=[broadcast_to_specialists],
+    input_guardrails=[enforce_content_policy],
+    instructions=_INSTRUCTIONS,
+)
+ai_research_orchestrator.description = (
+    "Coordinates the Financial Markets Analyst, News Intelligence Specialist, and "
+    "Web Research Specialist to deliver comprehensive, multi-source answers."
+)

src/nexus/prompts/economic_news.txt

@@ -0,0 +1,27 @@
+##### Task
+Provide a concise update on **major economic indicators released recently** in USA.
+
+###### Include
+- **Interest Rates**: Latest central bank decisions, current policy rates, and forward guidance.
+- **Labor Market**: Unemployment rate, job creation figures, and key labor metrics (if available).
+- **Inflation**: CPI, PCE, or other inflation data with MoM and YoY changes.
+- **Growth Indicators**: GDP, PMIs, or industrial production released recently.
+- **Market Reaction**: Brief impact on equities, bonds, FX, and commodities.
+
+###### Guidelines
+- Compare results against forecasts and prior releases
+- Highlight notable surprises and their implications
+- Keep the summary brief, factual, and structured
+- **Always retrieve numerical data from primary or authoritative sources**
+
+###### Fallback
+- If no relevant data was released recently, explicitly state **“No major economic indicators were released during this period.”**
+- If data is partially unavailable, summarize what is available and clearly note missing indicators.
+- Do not infer or fabricate numbers under any circumstance.
+
+###### Output Style
+- Concise, factual, and well-structured
+- Use clear bullet points or short paragraphs
+- Avoid speculation unless explicitly labeled as interpretation
+- **Cite data sources clearly**
+- Use color and emoji to make it more engaging.

src/nexus/prompts/entertainment_updates.txt

@@ -0,0 +1,26 @@
+##### Task
+Provide the **top 5 recent movie or series updates** that are trending or newly released in USA.
+
+###### For each title, include:
+- **Title in bold** and optionally use **color or emojis** to make it fun (e.g., 🎬, 🍿, 🌟)  
+- A **short, 2–3 line snippet** that generates excitement or humor about the plot, cast, or vibe  
+- **Platform or source** where it can be watched (Netflix, Prime, Disney+, etc.)  
+- **Release date or premiere date**  
+
+###### Requirements / Guidelines
+- Focus on **recent releases** (last 2–4 weeks) or currently trending content  
+- Keep the tone **fun, witty, and engaging**, like a friend recommending a show  
+- Use **emojis liberally** to emphasize excitement, genre, or humor
+- Call out the **main actors and actresses** to build the interest  
+- Where possible, add a **light humorous quip or pun** about the movie/series  
+- If color is supported, use HTML span tags, e.g., `<span style="color:orange">Title</span>` for emphasis
+
+###### Fallback
+- If fewer than 5 titles are available, provide what is available and indicate:  
+  **“Only X recent releases found.”**  
+- Do not fabricate platforms or release dates — only use verified sources
+
+###### Output Style
+- List format (1–5) sorted by **popularity or release date**  
+- **Title + snippet + watch source + release date** per entry  
+- Use **color, emojis, and humor** to make the output visually appealing and fun to read

src/nexus/prompts/india_news.txt

@@ -0,0 +1,26 @@
+##### Task
+Tell me the **top 3 headlines from India**.
+
+###### For each headline, provide:
+- **Title in bold**
+- A **3‑line summary**
+- **Publish date and time**
+- A **link to the exact source URL**
+
+###### Requirements
+- Use authoritative news sources (e.g., major national/regional news outlets)
+- Headlines should be **recent (last 24 hours)**
+- Provide timestamps in **UTC**
+- If publish date/time is not available, indicate “Date/Time not provided”
+
+###### Fallback
+- If fewer than 3 headlines are found, provide what is available and state:
+  **“Only X recent headlines found for India.”**
+- Do not fabricate headlines, dates, or URLs
+
+###### Output Style
+- Structured list sorted by **most recent first**
+- Clear and concise formatting as requested
+- Use color and emoji to make it more engaging.
+- Use `<span style="color:...">` for coloring the title if the renderer supports it
+- Keep the output **concise, factual, and visually engaging**

src/nexus/prompts/market_sentiment.txt

@@ -0,0 +1,34 @@
+##### Task
+Act as a **Senior Market Analyst** and provide a concise market sentiment update for the **US Stock Market / S&P 500**.
+
+###### Steps
+1. **Data Gathering**: Search for the **top 5 financial news headlines** from the last 24 hours related to the [US Stock Market / S&P 500].
+2. **Market Check**: Retrieve the **current value** and **today’s percentage change** for:
+   - **S&P 500 (SPX)**
+   - **VIX (Volatility Index)**
+3. **Synthesis**: Based on the **tone of the news headlines** and the **index performance**, determine whether the **current market sentiment** is:
+   - **Bullish**
+   - **Bearish**
+   - **Neutral**
+4. **Output**: Provide a:
+   - **Sentiment Score (1–10)**
+   - **Top 3 key drivers** influencing this sentiment
+
+###### Guidelines
+- Prioritize **reliable financial news sources** (e.g., Bloomberg, Reuters, WSJ, CNBC)
+- Use **accurate, real-time market data** for indices
+- Base sentiment on both **news tone** and **market movement**
+- Avoid subjective or unsupported judgments
+
+###### Fallback
+- If no relevant financial headlines are found in the last 24 hours, clearly state:  
+  **“No significant market news available in the last 24 hours.”**
+- If either index value or change is unavailable, report available data and note missing values explicitly
+- Do not invent or estimate values — only use verified data
+
+###### Output Style
+- Concise, factual, and structured
+- Use clear bullet points or short paragraphs
+- Include numerical values and data timestamps
+- Provide **sources for headlines and index data**
+- Use color and emoji to make it more engaging.

src/nexus/prompts/news_headlines.txt

@@ -0,0 +1,28 @@
+##### Task
+Tell me the **top 3 USA headlines**. Use **emojis** and, where supported, **HTML color tags** to make the output engaging.
+
+###### For each headline, provide:
+- **Title in bold** and optionally in color, e.g., `<span style="color:blue">Title</span>`  
+- A **3-line summary** with an emoji indicating the type of news:
+  - 📰 Politics
+  - 💼 Business
+  - 🌎 World
+  - ⚡ Breaking news
+- **Publish date and time** (UTC)
+- A **link to the exact source URL**
+
+###### Requirements
+- Use **credible news sources** (Reuters, AP, BBC, Guardian, etc.)
+- Headlines should be **recent (last 24 hours)**
+- If publish time is unavailable, indicate **“Time not provided”**
+
+###### Fallback
+- If fewer than 3 headlines are found, state:  
+  **“Only X recent headlines found for the USA.”**
+- Do not fabricate headlines, dates, or URLs
+
+###### Output Style
+- Structured list sorted by **most recent first**
+- Use emojis consistently to indicate news type
+- Use `<span style="color:...">` for coloring the title if the renderer supports it
+- Keep the output **concise, factual, and visually engaging**

src/nexus/prompts/odia_news.txt

@@ -0,0 +1,26 @@
+##### Task
+Tell me the **top 3 headlines from Odisha**.
+
+###### For each headline, provide:
+- **Title in bold**
+- A **3‑line summary**
+- **Publish date and time**
+- A **link to the exact source URL**
+
+###### Requirements
+- Use authoritative news sources (e.g., major national/regional news outlets)
+- Headlines should be **recent (last 24 hours)**
+- Provide timestamps in **UTC**
+- If publish date/time is not available, indicate “Date/Time not provided”
+
+###### Fallback
+- If fewer than 3 headlines are found, provide what is available and state:
+  **“Only X recent headlines found for Odisha.”**
+- Do not fabricate headlines, dates, or URLs
+
+###### Output Style
+- Structured list sorted by **most recent first**
+- Clear and concise formatting as requested
+- Use color and emoji to make it more engaging.
+- Use `<span style="color:...">` for coloring the title if the renderer supports it
+- Keep the output **concise, factual, and visually engaging**

src/nexus/prompts/trade_recommendation.txt

@@ -0,0 +1,40 @@
+##### Task
+Recommend **three option spreads** with **>80% probability of profit**. Perform a thorough analysis of each underlying’s **3-month price trend** and current **market sentiment** before selecting spreads.
+
+###### Steps
+1. **Stock selection & analysis**
+   - Analyze the **last 3 months** of price action (trend, volatility, support/resistance).
+   - Assess market sentiment from the **last 7 days** of headlines and social/analyst tone.
+2. **Spread construction**
+   - For each of the **3 recommended spreads**, specify:
+     - **Underlying ticker**
+     - **Spread type** (e.g., bull put, bear call, iron condor)
+     - **Exact expiry date** (YYYY-MM-DD)
+     - **Each leg**: side (sell/buy), option type (put/call), **strike price**
+     - **Premium entry**: exact net credit/debit per share (use live bid/ask midpoint)
+     - **Position size guidance** (risk per trade as % of portfolio) — optional
+3. **Probability & rationale**
+   - Provide a **quantitative probability of profit (%)** (clearly state model/method used).
+   - Give a concise **rationale** linking 3-month trend, implied volatility, and sentiment to the spread choice.
+   - Show key supporting numbers: current spot, IV30, recent volatility, and relevant news headlines (with timestamps).
+
+###### Requirements / Guidelines
+- Target **>80% probability of profit** for each spread. Explain how the probability was computed (IV-based log-normal, normal approximation, or risk-neutral model).
+- **Always** use live option-chain quotes (bid/ask midpoint) and authoritative sources for prices/IV (e.g., exchange data, major market data providers).
+- Compare outcomes **vs. forecasts / recent range** and note any idiosyncratic risk (earnings, events).
+- Include **exact timestamps** (UTC) for all quoted prices.
+- Provide **sources** for price, IV, and headlines.
+
+###### Fallback
+- If live option-chain or price data is unavailable, state: **“Live market data unavailable — cannot generate exact strike/premium. Provide analysis based on most recent available snapshot.”**
+- If sentiment or 3-month history is incomplete, present what is available and **explicitly list missing items**.
+- **Do not fabricate** strikes, premiums, probabilities, or news — only use verified data.
+
+###### Output Style
+- For each spread, use a compact block with:
+  - Ticker — Spread type — Expiry (YYYY-MM-DD) — Net premium — PO P (%)
+  - Legs: bullet list of exact leg details (sell/buy, put/call, strike, premium)
+  - Rationale: 2–3 short sentences linking trend & sentiment to the trade
+  - Sources & timestamps
+- Keep language concise, factual, and machine/agent friendly for downstream parsing.
+- Use color and emoji to make it more engaging.

src/nexus/prompts/upcoming_earnings.txt

@@ -0,0 +1,27 @@
+##### Task
+Search for **upcoming critical earnings announcements** in the stock market.
+
+###### Include
+- **Ticker**
+- **Company name**
+- **Earnings date & time**
+- **Expected EPS & revenue consensus**
+- **Last quarter’s actual EPS & revenue**
+- **Implied volatility trend ahead of earnings**
+
+###### Requirements / Guidelines
+- Focus on **high‑impact names** (large cap, high volume, sector leaders)
+- Include **earnings expected within the next 7 calendar days**
+- Use **primary/authoritative sources** for earnings dates and estimates (e.g., exchange calendars, Bloomberg/Refinitiv/Estimize)
+- Show **timestamped data** (UTC)
+
+###### Fallback
+- If no critical earnings are found in the next 7 days, state:  
+  **“No upcoming critical earnings announcements found within the specified period.”**
+- If consensus estimates are unavailable, list the earnings date/time and note missing metrics.
+
+###### Output Style
+- Structured list sorted by **earnings date**
+- Use clear bullet points or short paragraphs
+- Provide **sources** for each item
+- Use color and emoji to make it more engaging.

src/nexus/specialists.py

@@ -0,0 +1,197 @@
+"""Specialist agents — Finance, News, and Web Research.
+
+Each factory returns (Agent, MCPServerStdio).  The caller (orchestrator) is
+responsible for connecting/cleaning up the servers via MCPServerManager.
+"""
+import sys
+from pathlib import Path
+
+from agents import Agent
+from agents.mcp import MCPServerStdio, MCPServerStdioParams
+
+from model_factory import get_model
+
+_MCPDIR = Path(__file__).resolve().parent.parent / "_mcpservers"
+
+
+# ---------------------------------------------------------------------------
+# Financial Markets Analyst
+# ---------------------------------------------------------------------------
+
+_FINANCE_INSTRUCTIONS = """
+You are the **Financial Markets Analyst** — a data-driven equities researcher.
+Provide precise, tool-backed financial analysis. Never speculate without data.
+
+## Tool Selection Guide
+- `current_datetime` — call this FIRST on every request to anchor temporal context.
+- `get_stock_summary` — current price, open, high, low, volume.
+- `get_market_sentiment` — Bullish / Bearish / Neutral over a period.
+- `get_price_history` — historical OHLCV data (last 5 rows).
+- `get_analyst_recommendations` — latest Buy/Sell/Hold ratings.
+- `get_earnings_calendar` — upcoming earnings date for a single ticker.
+- `get_earnings_estimates` — EPS & revenue consensus + last 4 quarters actuals vs estimates.
+- `get_upcoming_earnings` — earnings dates for multiple companies in a date window. Scans ~60 large-cap names by default; pass comma-separated tickers to narrow it.
+- `get_iv_summary` — implied volatility trend across the nearest option expiries.
+- `screen_large_caps` — filter large-cap universe by sector, min market cap, sort by market_cap / volume / pe_ratio.
+- `get_valuation_metrics` — P/E, P/B, EPS, market cap, dividend yield, beta.
+- `get_financial_statements` — income statement, balance sheet, or cash flow.
+- `get_dividends` — dividend history and annual totals.
+- `get_technical_indicators` — SMA(20/50/200), RSI(14), MACD.
+- `compare_stocks` — side-by-side return and price comparison (up to 6 symbols).
+- `get_options_chain` — calls and puts for a specific expiry date.
+- `get_institutional_holdings` — major holders and institutional ownership.
+- `get_stock_news` — latest news articles from Yahoo Finance.
+
+## Output Format
+**[Company Name] ([SYMBOL]) — Market Analysis**
+
+| Metric | Value |
+|---|---|
+| Price | ... |
+| Change | ... |
+| Sentiment | ... |
+| Analyst Consensus | ... |
+| Next Earnings | ... |
+
+**Key Takeaways:** [2–3 bullet synthesis]
+
+*Disclaimer: For informational purposes only. Not financial advice.*
+
+## Rules
+- Every number must come from a tool call — never hallucinate prices.
+- Include the data source and date for all figures.
+- If data is unavailable, state "Data unavailable for [X]" explicitly.
+"""
+
+
+def create_finance_agent(model=None) -> tuple[Agent, MCPServerStdio]:
+    mcp = MCPServerStdio(
+        params=MCPServerStdioParams(
+            command=sys.executable,
+            args=[str(_MCPDIR / "mcp-finance" / "server.py")],
+        ),
+        cache_tools_list=True,
+        name="finance-mcp",
+    )
+    agent = Agent(
+        name="Financial Markets Analyst",
+        model=model or _default_model(),
+        mcp_servers=[mcp],
+        instructions=_FINANCE_INSTRUCTIONS,
+    )
+    agent.description = (
+        "Delivers stock summaries, sentiment, price history, earnings estimates, "
+        "IV analysis, and large-cap screening via the Finance MCP server."
+    )
+    return agent, mcp
+
+
+# ---------------------------------------------------------------------------
+# News Intelligence Specialist
+# ---------------------------------------------------------------------------
+
+_NEWS_INSTRUCTIONS = """
+You are the **News Intelligence Specialist** — an objective, source-citing news analyst.
+Retrieve and present the most relevant, up-to-date news on any topic.
+
+## Tool Selection Guide
+- `current_datetime` — always call first for temporal grounding.
+- `get_top_headlines` — use for country-level "what's happening today" requests.
+  Automatically falls back to keyword search when top-headlines lacks coverage.
+- `search_news` — preferred for specific topics, companies, people, or any country query.
+- `get_news_by_category` — use when the request names a category
+  (business, technology, health, sports, science, entertainment, general).
+- `search_company_news` — search news by company name rather than ticker symbol.
+
+## Output Format
+Present each article as:
+
+**[Headline]**
+- Source: [Name]  |  Published: [Date]
+- Summary: [1-2 sentence description]
+- Read more: [URL]
+
+## Rules
+- Never fabricate headlines or sources.
+- Always include publication dates and URLs.
+- Flag if results may be older than the requested timeframe.
+"""
+
+
+def create_news_agent(model=None) -> tuple[Agent, MCPServerStdio]:
+    mcp = MCPServerStdio(
+        params=MCPServerStdioParams(
+            command=sys.executable,
+            args=[str(_MCPDIR / "mcp-news" / "server.py")],
+        ),
+        cache_tools_list=True,
+        name="news-mcp",
+    )
+    agent = Agent(
+        name="News Intelligence Specialist",
+        model=model or _default_model(),
+        mcp_servers=[mcp],
+        instructions=_NEWS_INSTRUCTIONS,
+    )
+    agent.description = (
+        "Retrieves top headlines and topic-specific news articles via the News MCP server."
+    )
+    return agent, mcp
+
+
+# ---------------------------------------------------------------------------
+# Web Research Specialist
+# ---------------------------------------------------------------------------
+
+_WEB_INSTRUCTIONS = """
+You are the **Web Research Specialist** — a precise, citation-driven researcher.
+Your sole purpose is to retrieve and synthesize factual information from the internet.
+
+## Workflow
+1. Call `current_datetime` to establish temporal context.
+2. Construct 1–3 targeted search queries and call `duckduckgo_search`.
+   Use `search_type='news'` for current events.
+3. Fetch the full text of the top 3 most relevant results using `fetch_page_content`.
+4. Synthesize the fetched content into a clear, structured answer.
+
+## Output Rules
+- Ground every claim in the fetched text — never fabricate.
+- Use headings and bullet points for readability.
+- End with a **Sources** section listing the Title and URL of each page fetched.
+- If no conclusive answer is found, state: "A conclusive answer could not be
+  verified by current web sources."
+"""
+
+
+def create_web_agent(model=None) -> tuple[Agent, MCPServerStdio]:
+    mcp = MCPServerStdio(
+        params=MCPServerStdioParams(
+            command=sys.executable,
+            args=[str(_MCPDIR / "mcp-web-search" / "server.py")],
+        ),
+        cache_tools_list=True,
+        name="web-search-mcp",
+    )
+    agent = Agent(
+        name="Web Research Specialist",
+        model=model or _default_model(),
+        mcp_servers=[mcp],
+        instructions=_WEB_INSTRUCTIONS,
+    )
+    agent.description = (
+        "Searches DuckDuckGo, fetches full page content, and returns cited answers."
+    )
+    return agent, mcp
+
+
+# ---------------------------------------------------------------------------
+# Module-level defaults — used by orchestrator's backwards-compat instances
+# ---------------------------------------------------------------------------
+
+def _default_model():
+    return get_model("google", "gemini-2.5-flash")
+
+
+finance_agent, _finance_mcp = create_finance_agent()
+news_agent,    _news_mcp    = create_news_agent()
+web_agent,     _web_mcp     = create_web_agent()

src/nexus/tracing.py

@@ -0,0 +1,198 @@
+"""Langfuse tracing integration for the OpenAI Agents SDK.
+
+When LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY are set, installs a custom
+TracingProcessor that forwards every SDK span to Langfuse, producing a clean
+waterfall view: trace → agent spans → LLM generations → tool calls.
+
+Call setup_langfuse_tracing() once at app startup.
+If credentials are absent, tracing is disabled so the SDK doesn't send 401 noise
+to OpenAI's tracing endpoint.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime
+from typing import Any
+
+from agents.tracing import TracingProcessor, set_trace_processors, set_tracing_disabled
+
+log = logging.getLogger(__name__)
+
+
+def setup_langfuse_tracing() -> bool:
+    """Install Langfuse as the sole tracing backend.  Returns True if installed."""
+    if not (os.getenv("LANGFUSE_SECRET_KEY") and os.getenv("LANGFUSE_PUBLIC_KEY")):
+        set_tracing_disabled(True)
+        return False
+    try:
+        from langfuse import Langfuse
+        lf = Langfuse()
+        set_trace_processors([_LangfuseProcessor(lf)])
+        log.info("Langfuse tracing → %s", os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com"))
+        return True
+    except Exception as exc:
+        log.warning("Langfuse setup failed (%s) — tracing disabled", exc)
+        set_tracing_disabled(True)
+        return False
+
+
+class _LangfuseProcessor(TracingProcessor):
+    """Maps Agents SDK spans → Langfuse observations in a waterfall hierarchy."""
+
+    def __init__(self, lf: Any) -> None:
+        self._lf = lf
+        self._traces: dict[str, Any] = {}   # trace_id → langfuse trace object
+
+    # ------------------------------------------------------------------
+    # TracingProcessor interface
+    # ------------------------------------------------------------------
+
+    def on_trace_start(self, trace: Any) -> None:
+        try:
+            self._traces[trace.trace_id] = self._lf.trace(
+                id=trace.trace_id,
+                name=trace.name or "agent-run",
+            )
+        except Exception as exc:
+            log.debug("on_trace_start: %s", exc)
+
+    def on_trace_end(self, trace: Any) -> None:
+        try:
+            self._traces.pop(trace.trace_id, None)
+            self._lf.flush()
+        except Exception as exc:
+            log.debug("on_trace_end: %s", exc)
+
+    def on_span_start(self, span: Any) -> None:
+        pass  # all data available at span_end
+
+    def on_span_end(self, span: Any) -> None:
+        try:
+            lf_trace = self._traces.get(span.trace_id)
+            if lf_trace is None:
+                return
+            # span.parent_id == the parent's span_id which we also used as the
+            # Langfuse observation id, so it doubles as parent_observation_id.
+            self._emit(lf_trace, span, parent_id=span.parent_id)
+        except Exception as exc:
+            log.debug("on_span_end: %s", exc)
+
+    def force_flush(self) -> None:
+        try:
+            self._lf.flush()
+        except Exception:
+            pass
+
+    def shutdown(self) -> None:
+        try:
+            self._lf.flush()
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # Span → Langfuse observation
+    # ------------------------------------------------------------------
+
+    def _emit(self, trace: Any, span: Any, parent_id: str | None) -> None:
+        from agents.tracing.span_data import (
+            AgentSpanData, FunctionSpanData, GenerationSpanData,
+            GuardrailSpanData, HandoffSpanData, MCPListToolsSpanData,
+        )
+
+        d     = span.span_data
+        err   = str(span.error) if span.error else None
+        level = "ERROR" if span.error else "DEFAULT"
+        start = _ts(span.started_at)
+        end   = _ts(span.ended_at)
+        sid   = span.span_id
+
+        if isinstance(d, GenerationSpanData):
+            usage = None
+            if d.usage:
+                usage = {
+                    "input":  d.usage.get("input_tokens", 0),
+                    "output": d.usage.get("output_tokens", 0),
+                    "total":  d.usage.get("total_tokens", 0),
+                }
+            trace.generation(
+                id=sid, parent_observation_id=parent_id,
+                name=f"llm · {d.model or 'unknown'}",
+                model=d.model, input=d.input, output=d.output,
+                usage=usage, start_time=start, end_time=end,
+                level=level, status_message=err,
+            )
+
+        elif isinstance(d, FunctionSpanData):
+            prefix = "mcp" if d.mcp_data else "tool"
+            trace.span(
+                id=sid, parent_observation_id=parent_id,
+                name=f"{prefix} · {d.name or '?'}",
+                input=_parse(d.input), output=_parse(d.output),
+                start_time=start, end_time=end,
+                level=level, status_message=err,
+            )
+
+        elif isinstance(d, AgentSpanData):
+            trace.span(
+                id=sid, parent_observation_id=parent_id,
+                name=f"agent · {d.name or '?'}",
+                metadata={"tools": d.tools, "handoffs": d.handoffs},
+                start_time=start, end_time=end, level=level,
+            )
+
+        elif isinstance(d, GuardrailSpanData):
+            trace.span(
+                id=sid, parent_observation_id=parent_id,
+                name=f"guardrail · {d.name or '?'}",
+                metadata={"triggered": d.triggered},
+                start_time=start, end_time=end, level=level,
+            )
+
+        elif isinstance(d, HandoffSpanData):
+            trace.span(
+                id=sid, parent_observation_id=parent_id,
+                name=f"handoff → {d.to_agent or '?'}",
+                start_time=start, end_time=end,
+            )
+
+        elif isinstance(d, MCPListToolsSpanData):
+            trace.span(
+                id=sid, parent_observation_id=parent_id,
+                name=f"mcp list-tools · {d.server or '?'}",
+                output=d.result, start_time=start, end_time=end,
+            )
+
+        else:
+            trace.span(
+                id=sid, parent_observation_id=parent_id,
+                name=getattr(d, "name", d.type),
+                start_time=start, end_time=end,
+            )
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+def _ts(value: Any) -> datetime | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except Exception:
+        return None
+
+
+def _parse(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        import json
+        try:
+            return json.loads(value)
+        except Exception:
+            return value
+    return value