compare_portfolios

Instructions

Implementation Reference

• app/tools/analysis.py:353-439 (handler)

  The core handler function for compare_portfolios tool. It retrieves metrics for multiple portfolios, builds comparison structure with key metrics (expected_return, volatility, sharpe_ratio, sortino_ratio, value_at_risk, downside_risk), ranks portfolios by each metric, and identifies the best portfolio per metric.

  @mcp.tool
  def compare_portfolios(names: list[str]) -> dict[str, Any]:
      """Compare multiple portfolios side by side.
  
      Retrieves metrics for multiple portfolios and ranks them
      by key performance indicators.
  
      Args:
          names: List of portfolio names to compare.
  
      Returns:
          Dictionary containing:
          - portfolios: Dict of metrics per portfolio
          - rankings: Rankings by each metric
          - best_by_metric: Best portfolio for each metric
  
      Example:
          ```
          result = compare_portfolios(
              names=["stocks", "crypto", "metals"]
          )
          print(f"Best Sharpe: {result['best_by_metric']['sharpe_ratio']}")
          ```
      """
      if len(names) < 2:
          return {
              "error": "Need at least 2 portfolios to compare",
          }
  
      # Collect metrics for all portfolios
      portfolios_data = {}
      errors = []
  
      for name in names:
          data = store.get(name)
          if data is None:
              errors.append(f"Portfolio '{name}' not found")
              continue
          portfolios_data[name] = data["metrics"]
  
      if errors:
          return {
              "error": "Some portfolios not found",
              "details": errors,
              "found": list(portfolios_data.keys()),
          }
  
      # Build comparison structure
      portfolios = {}
      for name, metrics in portfolios_data.items():
          portfolios[name] = {
              "expected_return": metrics["expected_return"],
              "volatility": metrics["volatility"],
              "sharpe_ratio": metrics["sharpe"],
              "sortino_ratio": metrics["sortino"],
              "value_at_risk": metrics["var"],
              "downside_risk": metrics["downside_risk"],
          }
  
      # Create rankings
      metrics_to_rank = [
          ("expected_return", True),  # Higher is better
          ("volatility", False),  # Lower is better
          ("sharpe_ratio", True),
          ("sortino_ratio", True),
          ("value_at_risk", False),  # Lower (less negative) is better
          ("downside_risk", False),
      ]
  
      rankings = {}
      best_by_metric = {}
  
      for metric, higher_is_better in metrics_to_rank:
          sorted_names = sorted(
              portfolios_data.keys(),
              key=lambda n: portfolios[n][metric],
              reverse=higher_is_better,
          )
          rankings[metric] = sorted_names
          best_by_metric[metric] = sorted_names[0]
  
      return {
          "portfolios": portfolios,
          "rankings": rankings,
          "best_by_metric": best_by_metric,
          "num_portfolios": len(portfolios),
      }

• app/tools/analysis.py:22-31 (registration)

  The registration function `register_analysis_tools` that registers the compare_portfolios function as an MCP tool via the @mcp.tool decorator. This is called from app/server.py to wire up all analysis tools.

  def register_analysis_tools(
      mcp: FastMCP, store: PortfolioStore, cache: RefCache
  ) -> None:
      """Register analysis tools with the FastMCP server.
  
      Args:
          mcp: The FastMCP server instance.
          store: The portfolio store for persistence.
          cache: The RefCache instance for caching large results.
      """

• app/tools/analysis.py:354-368 (schema)

  The schema/type signature for compare_portfolios: takes a list of portfolio names (list[str]) and returns a dict with 'portfolios', 'rankings', 'best_by_metric', and 'num_portfolios'.

  def compare_portfolios(names: list[str]) -> dict[str, Any]:
      """Compare multiple portfolios side by side.
  
      Retrieves metrics for multiple portfolios and ranks them
      by key performance indicators.
  
      Args:
          names: List of portfolio names to compare.
  
      Returns:
          Dictionary containing:
          - portfolios: Dict of metrics per portfolio
          - rankings: Rankings by each metric
          - best_by_metric: Best portfolio for each metric