feat: initial project setup with dependencies and core infrastructure

Set up Portfolio Intelligence Platform with complete dependency management and core modules:

- Configure pyproject.toml with research-validated dependencies
- pydantic-ai v1.18.0 with native prompt caching
- fastmcp v2.13.0+ for MCP orchestration
- pyportfolioopt v1.5.6 (correct package name)
- quantitative finance libraries (riskfolio-lib, arch, xgboost, quantstats)
- All packages verified for Python 3.13 compatibility

- Create Gradio interface (app.py)
- Portfolio input with example portfolios
- Analysis output placeholder
- Clean, minimal UI ready for MCP integration

- Implement backend infrastructure
- config.py: Pydantic Settings for environment configuration
- database.py: Supabase PostgreSQL connection manager with demo mode
- mcp_router.py: MCP orchestration layer for 6 P0 servers
(Yahoo Finance, FMP, Trading-MCP, FRED, Portfolio Optimizer, Risk Analyzer)

- Establish project structure
- backend/agents/ for Pydantic AI agents
- backend/models/ for quantitative models
- backend/mcp_servers/ for custom MCP implementations
- tests/ directory for testing

All 270 packages installed successfully with uv sync

app.py

@@ -0,0 +1,89 @@
+"""Portfolio Intelligence Platform - Gradio Interface.
+
+Main application file for the hackathon demo.
+"""
+
+import gradio as gr
+from typing import List, Tuple
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def analyse_portfolio(portfolio_input: str) -> str:
+    """Analyse portfolio and return AI insights.
+
+    Args:
+        portfolio_input: Portfolio holdings as text (e.g., "AAPL 50\nTSLA 25 shares")
+
+    Returns:
+        Analysis results with insights and recommendations
+    """
+    # TODO: Integrate with MCP router and agents
+    return f"Analysis placeholder for:\n{portfolio_input}"
+
+
+def create_interface() -> gr.Blocks:
+    """Create the main Gradio interface.
+
+    Returns:
+        Gradio Blocks interface
+    """
+    with gr.Blocks(
+        title="Portfolio Intelligence Platform",
+        theme=gr.themes.Soft(),
+        fill_height=True
+    ) as demo:
+        gr.Markdown("# 📊 Portfolio Intelligence Platform")
+        gr.Markdown("AI-powered portfolio analysis using MCP orchestration")
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("## Enter Your Portfolio")
+
+                portfolio_input = gr.Textbox(
+                    label="Portfolio Holdings",
+                    placeholder="AAPL 50\nTSLA 25 shares\nNVDA $5000\nBTC 0.5",
+                    lines=10,
+                    info="Enter one holding per line"
+                )
+
+                analyse_btn = gr.Button("Analyse Portfolio", variant="primary")
+
+                # Example portfolios
+                gr.Examples(
+                    examples=[
+                        ["AAPL 50\nTSLA 25 shares\nNVDA $5000\nBTC 0.5"],
+                        ["VOO 100 shares\nVTI 75 shares\nSCHD 50 shares"],
+                        ["VTI $25000\nVXUS $15000\nBND $15000\nGLD $5000"],
+                    ],
+                    inputs=portfolio_input,
+                    label="Example Portfolios"
+                )
+
+            with gr.Column(scale=2):
+                gr.Markdown("## Analysis Results")
+
+                output = gr.Markdown(
+                    value="Enter your portfolio and click 'Analyse Portfolio' to get started.",
+                    label="AI Insights"
+                )
+
+        # Event handlers
+        analyse_btn.click(
+            fn=analyse_portfolio,
+            inputs=portfolio_input,
+            outputs=output
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    demo = create_interface()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False
+    )

backend/config.py

@@ -0,0 +1,70 @@
+"""Configuration module for Portfolio Intelligence Platform.
+
+Loads environment variables and provides configuration settings.
+"""
+
+import os
+from typing import Optional
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables.
+
+    Attributes:
+        anthropic_api_key: Anthropic API key for Claude
+        supabase_url: Supabase project URL
+        supabase_key: Supabase anon key
+        fmp_api_key: Financial Modeling Prep API key
+        fred_api_key: FRED (Federal Reserve Economic Data) API key
+        environment: Application environment (development/production)
+        log_level: Logging level
+    """
+
+    # AI/LLM Configuration
+    anthropic_api_key: str = Field(
+        default="",
+        validation_alias="ANTHROPIC_API_KEY"
+    )
+
+    # Database Configuration
+    supabase_url: Optional[str] = Field(
+        default=None,
+        validation_alias="SUPABASE_URL"
+    )
+    supabase_key: Optional[str] = Field(
+        default=None,
+        validation_alias="SUPABASE_KEY"
+    )
+
+    # Financial Data APIs
+    fmp_api_key: Optional[str] = Field(
+        default=None,
+        validation_alias="FMP_API_KEY"
+    )
+    fred_api_key: Optional[str] = Field(
+        default=None,
+        validation_alias="FRED_API_KEY"
+    )
+
+    # Application Settings
+    environment: str = Field(
+        default="development",
+        validation_alias="ENVIRONMENT"
+    )
+    log_level: str = Field(
+        default="INFO",
+        validation_alias="LOG_LEVEL"
+    )
+
+    class Config:
+        """Pydantic config."""
+
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = False
+
+
+# Global settings instance
+settings = Settings()

backend/database.py

@@ -0,0 +1,71 @@
+"""Database module for Portfolio Intelligence Platform.
+
+Handles Supabase PostgreSQL connections and operations.
+"""
+
+from typing import Optional
+from supabase import create_client, Client
+from backend.config import settings
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class Database:
+    """Database connection manager for Supabase PostgreSQL.
+
+    Attributes:
+        client: Supabase client instance
+    """
+
+    def __init__(self):
+        """Initialise database connection."""
+        self.client: Optional[Client] = None
+
+        if settings.supabase_url and settings.supabase_key:
+            try:
+                self.client = create_client(
+                    settings.supabase_url,
+                    settings.supabase_key
+                )
+                logger.info("Supabase client initialised successfully")
+            except Exception as e:
+                logger.warning(f"Failed to initialise Supabase client: {e}")
+                logger.info("Running in demo mode without database")
+        else:
+            logger.info("Supabase credentials not configured - running in demo mode")
+
+    def is_connected(self) -> bool:
+        """Check if database connection is active.
+
+        Returns:
+            True if connected, False otherwise
+        """
+        return self.client is not None
+
+    async def save_analysis(self, user_id: str, portfolio_data: dict, analysis_result: dict) -> bool:
+        """Save portfolio analysis to database.
+
+        Args:
+            user_id: User identifier
+            portfolio_data: Portfolio holdings data
+            analysis_result: Analysis results from AI agents
+
+        Returns:
+            True if saved successfully, False otherwise
+        """
+        if not self.is_connected():
+            logger.warning("Database not connected - skipping save")
+            return False
+
+        try:
+            # TODO: Implement actual database schema and insert logic
+            logger.info(f"Saving analysis for user {user_id}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to save analysis: {e}")
+            return False
+
+
+# Global database instance
+db = Database()

backend/mcp_router.py

@@ -0,0 +1,130 @@
+"""MCP Router for Portfolio Intelligence Platform.
+
+Orchestrates MCP servers for financial data and quantitative analysis.
+"""
+
+from typing import Dict, List, Any, Optional
+from fastmcp import FastMCP
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class MCPRouter:
+    """Router for orchestrating multiple MCP servers.
+
+    Manages connections to:
+    - P0 (Week 1): Yahoo Finance, FMP, Trading-MCP, FRED, Portfolio Optimizer, Risk Analyzer
+    - P1 (Week 2): Ensemble Predictor (if time permits)
+    """
+
+    def __init__(self):
+        """Initialise MCP router with configured servers."""
+        self.servers: Dict[str, Any] = {}
+        self._initialise_servers()
+
+    def _initialise_servers(self):
+        """Initialise connections to MCP servers."""
+        # TODO: Implement actual MCP server connections
+        logger.info("Initialising MCP servers")
+
+        # Placeholder for P0 MCP servers
+        self.servers = {
+            "yahoo_finance": None,  # Real-time pricing, historical data
+            "fmp": None,  # Financial Modeling Prep - fundamentals
+            "trading_mcp": None,  # Technical indicators (RSI, MACD, etc.)
+            "fred": None,  # Macroeconomic data (GDP, unemployment, inflation)
+            "portfolio_optimizer": None,  # HRP, Black-Litterman, Mean-Variance
+            "risk_analyzer": None,  # VaR/CVaR calculations
+        }
+
+        logger.info(f"Initialised {len(self.servers)} MCP servers")
+
+    async def fetch_market_data(self, tickers: List[str]) -> Dict[str, Any]:
+        """Fetch market data for given tickers.
+
+        Args:
+            tickers: List of stock/asset tickers
+
+        Returns:
+            Market data from Yahoo Finance and other sources
+        """
+        # TODO: Implement actual MCP calls
+        logger.info(f"Fetching market data for {len(tickers)} tickers")
+        return {"status": "placeholder", "tickers": tickers}
+
+    async def fetch_fundamentals(self, tickers: List[str]) -> Dict[str, Any]:
+        """Fetch fundamental data from Financial Modeling Prep.
+
+        Args:
+            tickers: List of stock tickers
+
+        Returns:
+            Fundamental data (P/E, margins, revenue, etc.)
+        """
+        # TODO: Implement FMP MCP integration
+        logger.info(f"Fetching fundamentals for {len(tickers)} tickers")
+        return {"status": "placeholder", "tickers": tickers}
+
+    async def fetch_technical_indicators(self, tickers: List[str]) -> Dict[str, Any]:
+        """Fetch technical indicators from Trading-MCP.
+
+        Args:
+            tickers: List of stock tickers
+
+        Returns:
+            Technical indicators (RSI, MACD, Bollinger Bands, etc.)
+        """
+        # TODO: Implement Trading-MCP integration
+        logger.info(f"Fetching technical indicators for {len(tickers)} tickers")
+        return {"status": "placeholder", "tickers": tickers}
+
+    async def fetch_macro_data(self) -> Dict[str, Any]:
+        """Fetch macroeconomic data from FRED.
+
+        Returns:
+            Macroeconomic indicators (GDP, unemployment, inflation, etc.)
+        """
+        # TODO: Implement FRED MCP integration
+        logger.info("Fetching macroeconomic data")
+        return {"status": "placeholder"}
+
+    async def optimize_portfolio(
+        self,
+        historical_prices: Dict[str, List[float]],
+        risk_tolerance: str
+    ) -> Dict[str, Any]:
+        """Optimise portfolio allocation using quantitative models.
+
+        Args:
+            historical_prices: Historical price data for assets
+            risk_tolerance: User's risk tolerance (Conservative/Moderate/Aggressive)
+
+        Returns:
+            Optimised portfolio weights and metrics
+        """
+        # TODO: Implement Portfolio Optimizer MCP
+        logger.info(f"Optimising portfolio with {risk_tolerance} risk tolerance")
+        return {"status": "placeholder", "method": "HRP + Black-Litterman"}
+
+    async def calculate_risk_metrics(
+        self,
+        historical_prices: Dict[str, List[float]],
+        portfolio_weights: Dict[str, float]
+    ) -> Dict[str, Any]:
+        """Calculate risk metrics for portfolio.
+
+        Args:
+            historical_prices: Historical price data
+            portfolio_weights: Current portfolio allocation
+
+        Returns:
+            Risk metrics (VaR, CVaR, volatility, etc.)
+        """
+        # TODO: Implement Risk Analyzer MCP
+        logger.info("Calculating risk metrics")
+        return {"status": "placeholder", "metrics": ["VaR", "CVaR", "Volatility"]}
+
+
+# Global MCP router instance
+mcp_router = MCPRouter()

pyproject.toml

@@ -1,7 +1,69 @@
 [project]
 name = "portfolio-intelligence-platform"
 version = "0.1.0"
-description = "Add your description here"
+description = "AI-powered portfolio analysis platform with MCP orchestration"
 readme = "README.md"
 requires-python = ">=3.12"
-dependencies = []
+dependencies = [
+    # AI Framework
+    "pydantic-ai==1.18.0",
+    "anthropic>=0.39.0",
+    "instructor>=1.6.4",
+
+    # Agent Orchestration
+    "langgraph>=0.1.0",
+
+    # MCP Framework
+    "fastmcp==2.13.0",
+    "mcp>=1.0.0",
+
+    # Frontend
+    "gradio==5.49.1",
+
+    # Backend
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    "pydantic>=2.5.0",
+
+    # Database
+    "supabase>=2.9.0",
+    "psycopg2-binary>=2.9.9",
+
+    # Quantitative Finance (P0 - Deterministic Models)
+    # Research validated: Package name is 'pyportfolioopt', import as 'pypfopt'
+    "pyportfolioopt>=1.5.6",
+    "riskfolio-lib>=7.0.0",
+    "arch>=8.0.0",
+    "quantstats>=0.0.77",
+
+    # Data & Analysis
+    "pandas>=2.2.3",
+    "numpy>=2.0.0",
+    "yfinance>=0.2.40",
+    "scipy>=1.11.0",
+
+    # ML Models (P1 - Optional)
+    "torch>=2.0.0",
+    "xgboost>=3.1.0",
+
+    # Utilities
+    "python-dotenv>=1.0.0",
+    "httpx>=0.25.0",
+    "tenacity>=8.2.0",
+]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "black>=23.11.0",
+    "mypy>=1.7.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["backend"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"