.

.gitignore

@@ -0,0 +1,29 @@
+target
+local
+__pycache__
+.pytest_cache
+/*.egg-info
+/**/dist
+/**/*.egg-info
+/**/*-stubs
+.venv
+
+# Eclipse, Netbeans and IntelliJ files
+/.*
+!/.github
+!/.ci
+!.gitignore
+!.gitattributes
+!/.mvn
+/nbproject
+*.ipr
+*.iws
+*.iml
+
+# Repository wide ignore mac DS_Store files
+.DS_Store
+*.code-workspace
+CLAUDE.md
+DOCUMENTATION_AUDIT.md
+
+**/.venv/**

Dockerfile

@@ -0,0 +1,24 @@
+# Use Python 3.12 base image
+FROM python:3.12
+
+# Install JDK 21 (required for solverforge-legacy)
+RUN apt-get update && \
+    apt-get install -y wget gnupg2 && \
+    wget -O- https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor > /usr/share/keyrings/adoptium-archive-keyring.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/adoptium-archive-keyring.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" > /etc/apt/sources.list.d/adoptium.list && \
+    apt-get update && \
+    apt-get install -y temurin-21-jdk && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy application files
+COPY . .
+
+# Install the application
+RUN pip install --no-cache-dir -e .
+
+# Expose port 8080
+EXPOSE 8080
+
+# Run the application
+CMD ["run-app"]

README.md

@@ -0,0 +1,11 @@
+---
+title: Portfolio Optimization (Python)
+emoji: 📈
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 8080
+pinned: false
+license: apache-2.0
+short_description: SolverForge Portfolio Optimization Quickstart
+---

logging.conf

@@ -0,0 +1,30 @@
+[loggers]
+keys=root,solverforge_solver
+
+[handlers]
+keys=consoleHandler
+
+[formatters]
+keys=simpleFormatter
+
+[logger_root]
+level=INFO
+handlers=consoleHandler
+
+[logger_solverforge_solver]
+level=INFO
+qualname=solverforge.solver
+handlers=consoleHandler
+propagate=0
+
+[handler_consoleHandler]
+class=StreamHandler
+level=INFO
+formatter=simpleFormatter
+args=(sys.stdout,)
+
+[formatter_simpleFormatter]
+class=uvicorn.logging.ColourizedFormatter
+format={levelprefix:<8} @ {name} : {message}
+style={
+use_colors=True

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "portfolio_optimization"
+version = "1.0.0"
+requires-python = ">=3.10"
+dependencies = [
+    'solverforge-legacy == 1.24.1',
+    'fastapi == 0.111.0',
+    'pydantic == 2.7.3',
+    'uvicorn == 0.30.1',
+    'pytest == 8.2.2',
+]
+
+
+[project.scripts]
+run-app = "portfolio_optimization:main"

src/portfolio_optimization/__init__.py

@@ -0,0 +1,26 @@
+"""
+Portfolio Optimization Quickstart
+
+A SolverForge quickstart demonstrating constraint-based portfolio optimization.
+Combines ML predictions with constraint solving to select an optimal stock portfolio.
+"""
+import uvicorn
+
+from .rest_api import app as app
+
+
+def main():
+    """Run the portfolio optimization REST API server."""
+    config = uvicorn.Config(
+        "portfolio_optimization:app",
+        host="0.0.0.0",
+        port=8080,
+        log_config="logging.conf",
+        use_colors=True,
+    )
+    server = uvicorn.Server(config)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

src/portfolio_optimization/constraints.py

@@ -0,0 +1,232 @@
+"""
+Portfolio Optimization Constraints
+
+This module defines the business rules for portfolio construction:
+
+HARD CONSTRAINTS (must be satisfied):
+1. must_select_target_count: Pick exactly N stocks (configurable, default 20)
+2. sector_exposure_limit: No sector can exceed X stocks (configurable, default 5)
+
+SOFT CONSTRAINTS (optimize for):
+3. penalize_unselected_stock: Drive solver to select stocks (high penalty)
+4. maximize_expected_return: Prefer stocks with higher ML-predicted returns
+
+WHY CONSTRAINT SOLVING BEATS IF/ELSE:
+- With 50 stocks and 5 sectors, there are millions of possible portfolios
+- Multiple constraints interact: selecting high-return stocks might violate sector limits
+- Greedy algorithms get stuck in local optima
+- Constraint solvers explore the solution space systematically
+
+CONFIGURATION:
+- Constraints read thresholds from PortfolioConfig (a problem fact)
+- target_count: Number of stocks to select
+- max_per_sector: Maximum stocks allowed in any single sector
+- unselected_penalty: Soft penalty per unselected stock (drives selection)
+
+FINANCE CONCEPTS:
+- Sector diversification: Don't put all eggs in one basket
+- Expected return: ML model's prediction of future stock performance
+- Equal weight: Each selected stock gets the same percentage (5% for 20 stocks)
+"""
+from typing import Any
+
+from solverforge_legacy.solver.score import (
+    constraint_provider,
+    ConstraintFactory,
+    HardSoftScore,
+    ConstraintCollectors,
+    Constraint,
+)
+
+from .domain import StockSelection, PortfolioConfig
+
+
+@constraint_provider
+def define_constraints(constraint_factory: ConstraintFactory) -> list[Constraint]:
+    """
+    Define all portfolio optimization constraints.
+
+    Returns a list of constraint functions that the solver will enforce.
+    Hard constraints must be satisfied; soft constraints are optimized.
+
+    IMPLEMENTATION NOTE:
+    The stock count is enforced via:
+    1. must_select_exactly_20_stocks - hard constraint, penalizes if MORE than 20 selected
+    2. penalize_unselected_stock - soft constraint with high penalty, drives solver to select stocks
+
+    We don't use a hard "minimum 20" constraint because group_by(count()) on an
+    empty stream returns nothing (not 0). Instead, we rely on the large soft penalty
+    for unselected stocks to push the solver toward selecting exactly 20.
+    """
+    return [
+        # Hard constraints (must be satisfied)
+        must_select_target_count(constraint_factory),  # Max target_count selected
+        sector_exposure_limit(constraint_factory),  # Max per sector
+
+        # Soft constraints (maximize/minimize)
+        penalize_unselected_stock(constraint_factory),  # Drives selection toward target
+        maximize_expected_return(constraint_factory),  # Optimize returns
+
+        # ============================================================
+        # TUTORIAL: Uncomment the constraint below to add sector preference
+        # ============================================================
+        # preferred_sector_bonus(constraint_factory),
+    ]
+
+
+def must_select_target_count(constraint_factory: ConstraintFactory) -> Constraint:
+    """
+    Hard constraint: Must not select MORE than target_count stocks.
+
+    Business rule: "Pick at most N stocks for the portfolio"
+    (N is configurable via PortfolioConfig.target_count, default 20)
+
+    This constraint only fires when count > target_count. Combined with
+    penalize_unselected_stock, ensures the target count is reached.
+
+    Note: We use the 'selected' property which returns True/False based on selection.value
+    """
+    return (
+        constraint_factory.for_each(StockSelection)
+        .filter(lambda stock: stock.selected is True)
+        .group_by(ConstraintCollectors.count())
+        .join(PortfolioConfig)
+        .filter(lambda count, config: count > config.target_count)
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda count, config: count - config.target_count  # Penalty = stocks over target
+        )
+        .as_constraint("Must select target count")
+    )
+
+
+def penalize_unselected_stock(constraint_factory: ConstraintFactory) -> Constraint:
+    """
+    Soft constraint: Penalize each unselected stock.
+
+    This constraint drives the solver to select stocks. Without it,
+    the solver might leave all stocks unselected (0 hard score from
+    other constraints due to empty stream issue).
+
+    We use a LARGE soft penalty (configurable, default 10000) to ensure
+    the solver prioritizes selecting stocks before optimizing returns.
+    This is higher than the max return reward (~2000 per stock).
+
+    With 25 stocks and 20 needed, the optimal has 5 unselected = -50000 soft.
+    """
+    return (
+        constraint_factory.for_each(StockSelection)
+        .filter(lambda stock: stock.selected is False)
+        .join(PortfolioConfig)
+        .penalize(
+            HardSoftScore.ONE_SOFT,
+            lambda stock, config: config.unselected_penalty
+        )
+        .as_constraint("Penalize unselected stock")
+    )
+
+
+def sector_exposure_limit(constraint_factory: ConstraintFactory) -> Constraint:
+    """
+    Hard constraint: No sector can exceed max_per_sector stocks.
+
+    Business rule: "Maximum N stocks from any single sector"
+    (N is configurable via PortfolioConfig.max_per_sector, default 5)
+
+    Why this matters (DIVERSIFICATION):
+    - If Tech sector crashes 50%, you only lose X% * 50% of portfolio
+    - Without this limit, you might pick all Tech stocks (they have highest returns!)
+    - Diversification protects against sector-specific risks
+
+    Example with default (5 stocks max = 25%):
+    - Technology: 6 stocks selected = 30% exposure
+    - Sector limit: 25% (5 stocks max)
+    - Penalty: 6 - 5 = 1 (one stock over limit)
+    """
+    return (
+        constraint_factory.for_each(StockSelection)
+        .filter(lambda stock: stock.selected is True)
+        .group_by(
+            lambda stock: stock.sector,  # Group by sector name
+            ConstraintCollectors.count()  # Count stocks per sector
+        )
+        .join(PortfolioConfig)
+        .filter(lambda sector, count, config: count > config.max_per_sector)
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda sector, count, config: count - config.max_per_sector
+        )
+        .as_constraint("Max stocks per sector")
+    )
+
+
+def maximize_expected_return(constraint_factory: ConstraintFactory) -> Constraint:
+    """
+    Soft constraint: Maximize total expected portfolio return.
+
+    Business rule: "Among all valid portfolios, pick stocks with highest predicted returns"
+
+    Why this is a SOFT constraint:
+    - It's our optimization objective, not a hard rule
+    - We WANT high returns, but we MUST respect sector limits
+    - The solver balances this against hard constraints
+
+    Math:
+    - Portfolio return = sum of (weight * predicted_return) for each stock
+    - With 20 stocks at 5% each: return = sum of (0.05 * predicted_return)
+    - We reward based on predicted_return to prefer high-return stocks
+
+    Example:
+    - Apple: predicted_return = 0.12 (12%)
+    - Weight: 5% = 0.05
+    - Contribution to score: 0.05 * 0.12 * 10000 = 60 points
+
+    Note: We multiply by 10000 to convert decimals to integer scores
+    """
+    return (
+        constraint_factory.for_each(StockSelection)
+        .filter(lambda stock: stock.selected is True)
+        .reward(
+            HardSoftScore.ONE_SOFT,
+            # Reward = predicted return (scaled to integer)
+            # Higher predicted return = higher reward
+            lambda stock: int(stock.predicted_return * 10000)
+        )
+        .as_constraint("Maximize expected return")
+    )
+
+
+# ============================================================
+# TUTORIAL CONSTRAINT: Preferred Sector Bonus
+# ============================================================
+# Uncomment this constraint to give a small bonus to preferred sectors.
+# This demonstrates how to add custom business logic to the optimization.
+#
+# Scenario: Your investment committee wants to slightly favor Technology
+# and Healthcare sectors because they expect these sectors to outperform.
+#
+# def preferred_sector_bonus(constraint_factory: ConstraintFactory):
+#     """
+#     Soft constraint: Give a small bonus to stocks from preferred sectors.
+#
+#     This is a TUTORIAL constraint - uncomment to see how it affects
+#     the portfolio composition.
+#
+#     Business rule: "Slightly prefer Technology and Healthcare stocks"
+#
+#     Note: This is intentionally a SMALL bonus so it doesn't override
+#     the expected return constraint. It just acts as a tiebreaker.
+#     """
+#     PREFERRED_SECTORS = {"Technology", "Healthcare"}
+#     BONUS_POINTS = 50  # Small bonus per preferred stock
+#
+#     return (
+#         constraint_factory.for_each(StockSelection)
+#         .filter(lambda stock: stock.selected is True)
+#         .filter(lambda stock: stock.sector in PREFERRED_SECTORS)
+#         .reward(
+#             HardSoftScore.ONE_SOFT,
+#             lambda stock: BONUS_POINTS
+#         )
+#         .as_constraint("Preferred sector bonus")
+#     )

src/portfolio_optimization/converters.py

@@ -0,0 +1,114 @@
+"""
+Converters between domain objects and REST API models.
+
+These functions handle the transformation between:
+- Domain objects (dataclasses used by the solver)
+- REST models (Pydantic models used by the API)
+"""
+from . import domain
+from .domain import SELECTED, NOT_SELECTED, PortfolioConfig
+
+
+def stock_to_model(stock: domain.StockSelection) -> domain.StockSelectionModel:
+    """Convert a StockSelection domain object to REST model."""
+    # Note: Pydantic model has populate_by_name=True, allowing snake_case field names
+    return domain.StockSelectionModel(  # type: ignore[call-arg]
+        stock_id=stock.stock_id,
+        stock_name=stock.stock_name,
+        sector=stock.sector,
+        predicted_return=stock.predicted_return,
+        selected=stock.selected,  # Uses the @property that returns bool
+    )
+
+
+def plan_to_metrics(plan: domain.PortfolioOptimizationPlan) -> domain.PortfolioMetricsModel | None:
+    """Calculate business metrics from a plan."""
+    if plan.get_selected_count() == 0:
+        return None
+
+    return domain.PortfolioMetricsModel(  # type: ignore[call-arg]
+        expected_return=plan.get_expected_return(),
+        sector_count=plan.get_sector_count(),
+        max_sector_exposure=plan.get_max_sector_exposure(),
+        herfindahl_index=plan.get_herfindahl_index(),
+        diversification_score=plan.get_diversification_score(),
+        return_volatility=plan.get_return_volatility(),
+        sharpe_proxy=plan.get_sharpe_proxy(),
+    )
+
+
+def plan_to_model(plan: domain.PortfolioOptimizationPlan) -> domain.PortfolioOptimizationPlanModel:
+    """Convert a PortfolioOptimizationPlan domain object to REST model."""
+    # Note: Pydantic model has populate_by_name=True, allowing snake_case field names
+    return domain.PortfolioOptimizationPlanModel(  # type: ignore[call-arg]
+        stocks=[stock_to_model(s) for s in plan.stocks],
+        target_position_count=plan.target_position_count,
+        max_sector_percentage=plan.max_sector_percentage,
+        score=str(plan.score) if plan.score else None,
+        solver_status=plan.solver_status.name if plan.solver_status else None,
+        metrics=plan_to_metrics(plan),
+    )
+
+
+def model_to_stock(model: domain.StockSelectionModel) -> domain.StockSelection:
+    """Convert a StockSelectionModel REST model to domain object.
+
+    Note: The REST model uses `selected: bool` but the domain uses
+    `selection: SelectionValue`. We convert here.
+    """
+    # Convert bool to SelectionValue (or None if not set)
+    selection = None
+    if model.selected is True:
+        selection = SELECTED
+    elif model.selected is False:
+        selection = NOT_SELECTED
+    # If model.selected is None, leave selection as None
+
+    return domain.StockSelection(
+        stock_id=model.stock_id,
+        stock_name=model.stock_name,
+        sector=model.sector,
+        predicted_return=model.predicted_return,
+        selection=selection,
+    )
+
+
+def model_to_plan(model: domain.PortfolioOptimizationPlanModel) -> domain.PortfolioOptimizationPlan:
+    """Convert a PortfolioOptimizationPlanModel REST model to domain object.
+
+    Creates a PortfolioConfig from the model's target_position_count and
+    max_sector_percentage so that constraints can access these values.
+    """
+    stocks = [model_to_stock(s) for s in model.stocks]
+
+    # Parse score if provided
+    score = None
+    if model.score:
+        from solverforge_legacy.solver.score import HardSoftScore
+        score = HardSoftScore.parse(model.score)
+
+    # Parse solver status if provided
+    solver_status = domain.SolverStatus.NOT_SOLVING
+    if model.solver_status:
+        solver_status = domain.SolverStatus[model.solver_status]
+
+    # Calculate max_per_sector from max_sector_percentage and target_position_count
+    # Example: 25% of 20 stocks = 5 stocks max per sector
+    target_count = model.target_position_count
+    max_per_sector = max(1, int(model.max_sector_percentage * target_count))
+
+    # Create PortfolioConfig for constraints to access
+    portfolio_config = PortfolioConfig(
+        target_count=target_count,
+        max_per_sector=max_per_sector,
+        unselected_penalty=10000,  # Default penalty
+    )
+
+    return domain.PortfolioOptimizationPlan(
+        stocks=stocks,
+        target_position_count=model.target_position_count,
+        max_sector_percentage=model.max_sector_percentage,
+        portfolio_config=portfolio_config,
+        score=score,
+        solver_status=solver_status,
+    )

src/portfolio_optimization/demo_data.py

@@ -0,0 +1,223 @@
+"""
+Demo Data for Portfolio Optimization
+
+This module provides sample stock data for the portfolio optimization quickstart.
+The data includes 20 stocks across 4 sectors with ML-predicted returns.
+
+In a real application, these predictions would come from an ML model trained
+on historical stock data. For this quickstart, we use hardcoded realistic values.
+
+FINANCE CONCEPTS:
+- predicted_return: Expected percentage gain (0.12 = 12% expected return)
+- sector: Industry classification for diversification
+- Equal weight: Each selected stock gets 100%/20 = 5% of the portfolio
+"""
+from enum import Enum
+from dataclasses import dataclass
+
+from .domain import StockSelection, PortfolioOptimizationPlan, PortfolioConfig
+
+
+class DemoData(Enum):
+    """Available demo datasets."""
+    SMALL = 'SMALL'   # 20 stocks - good for learning
+    LARGE = 'LARGE'   # 50 stocks - more realistic
+
+
+@dataclass
+class DemoDataConfig:
+    """Configuration for demo data generation."""
+    target_position_count: int
+    max_sector_percentage: float
+
+
+demo_data_configs = {
+    DemoData.SMALL: DemoDataConfig(
+        target_position_count=20,
+        max_sector_percentage=0.25,
+    ),
+    DemoData.LARGE: DemoDataConfig(
+        target_position_count=20,
+        max_sector_percentage=0.25,
+    ),
+}
+
+
+# Stock data with realistic ML predictions
+# Format: (ticker, name, sector, predicted_return)
+#
+# SMALL dataset: 25 stocks, need to select 20
+# This is FEASIBLE because we have 5+ stocks in each of 4 sectors (5*4=20 max from limits)
+# Plus we have extra stocks to choose from in each sector
+SMALL_DATASET_STOCKS = [
+    # TECHNOLOGY (7 stocks) - typically higher predicted returns
+    # Solver can pick max 5, so must choose best 5 from 7
+    ("AAPL", "Apple Inc.", "Technology", 0.12),
+    ("GOOGL", "Alphabet (Google)", "Technology", 0.15),
+    ("MSFT", "Microsoft Corp.", "Technology", 0.10),
+    ("NVDA", "NVIDIA Corp.", "Technology", 0.18),
+    ("META", "Meta Platforms", "Technology", 0.08),
+    ("TSLA", "Tesla Inc.", "Technology", 0.20),
+    ("AMD", "AMD Inc.", "Technology", 0.14),
+
+    # HEALTHCARE (6 stocks) - moderate returns
+    # Solver can pick max 5, so must choose best 5 from 6
+    ("JNJ", "Johnson & Johnson", "Healthcare", 0.09),
+    ("UNH", "UnitedHealth Group", "Healthcare", 0.11),
+    ("PFE", "Pfizer Inc.", "Healthcare", 0.07),
+    ("ABBV", "AbbVie Inc.", "Healthcare", 0.10),
+    ("TMO", "Thermo Fisher", "Healthcare", 0.13),
+    ("DHR", "Danaher Corp.", "Healthcare", 0.12),
+
+    # FINANCE (6 stocks) - stable returns
+    # Solver can pick max 5, so must choose best 5 from 6
+    ("JPM", "JPMorgan Chase", "Finance", 0.08),
+    ("BAC", "Bank of America", "Finance", 0.06),
+    ("WFC", "Wells Fargo", "Finance", 0.07),
+    ("GS", "Goldman Sachs", "Finance", 0.09),
+    ("MS", "Morgan Stanley", "Finance", 0.08),
+    ("C", "Citigroup", "Finance", 0.05),
+
+    # ENERGY (6 stocks) - variable returns
+    # Solver can pick max 5, so must choose best 5 from 6
+    ("XOM", "Exxon Mobil", "Energy", 0.04),
+    ("CVX", "Chevron Corp.", "Energy", 0.05),
+    ("COP", "ConocoPhillips", "Energy", 0.06),
+    ("SLB", "Schlumberger", "Energy", 0.03),
+    ("EOG", "EOG Resources", "Energy", 0.07),
+    ("PXD", "Pioneer Natural", "Energy", 0.08),
+]
+
+LARGE_DATASET_STOCKS = SMALL_DATASET_STOCKS + [
+    # Additional TECHNOLOGY (6 more -> 13 total)
+    ("CRM", "Salesforce", "Technology", 0.11),
+    ("ADBE", "Adobe Inc.", "Technology", 0.09),
+    ("ORCL", "Oracle Corp.", "Technology", 0.07),
+    ("CSCO", "Cisco Systems", "Technology", 0.06),
+    ("IBM", "IBM Corp.", "Technology", 0.04),
+    ("QCOM", "Qualcomm", "Technology", 0.13),
+
+    # Additional HEALTHCARE (6 more -> 12 total)
+    ("MRK", "Merck & Co.", "Healthcare", 0.08),
+    ("LLY", "Eli Lilly", "Healthcare", 0.16),
+    ("BMY", "Bristol-Myers", "Healthcare", 0.06),
+    ("AMGN", "Amgen Inc.", "Healthcare", 0.09),
+    ("GILD", "Gilead Sciences", "Healthcare", 0.05),
+    ("ISRG", "Intuitive Surgical", "Healthcare", 0.14),
+
+    # Additional FINANCE (4 more -> 10 total, no duplicates)
+    ("AXP", "American Express", "Finance", 0.10),
+    ("BLK", "BlackRock", "Finance", 0.11),
+    ("SCHW", "Charles Schwab", "Finance", 0.07),
+    ("USB", "U.S. Bancorp", "Finance", 0.04),
+
+    # Additional ENERGY (2 more -> 8 total, no duplicates)
+    ("OXY", "Occidental Petroleum", "Energy", 0.06),
+    ("HAL", "Halliburton", "Energy", 0.05),
+
+    # CONSUMER (new sector - 8 stocks)
+    ("AMZN", "Amazon.com", "Consumer", 0.14),
+    ("WMT", "Walmart", "Consumer", 0.06),
+    ("HD", "Home Depot", "Consumer", 0.08),
+    ("MCD", "McDonald's", "Consumer", 0.07),
+    ("NKE", "Nike Inc.", "Consumer", 0.09),
+    ("SBUX", "Starbucks", "Consumer", 0.05),
+    ("PG", "Procter & Gamble", "Consumer", 0.04),
+    ("KO", "Coca-Cola", "Consumer", 0.05),
+]
+# LARGE total: 25 + 6 + 6 + 4 + 2 + 8 = 51 stocks
+
+
+def generate_demo_data(demo_data: DemoData) -> PortfolioOptimizationPlan:
+    """
+    Generate demo data for portfolio optimization.
+
+    Args:
+        demo_data: Which demo dataset to generate (SMALL or LARGE)
+
+    Returns:
+        PortfolioOptimizationPlan with candidate stocks (all unselected initially)
+
+    Example:
+        >>> plan = generate_demo_data(DemoData.SMALL)
+        >>> len(plan.stocks)
+        20
+        >>> plan.stocks[0].stock_id
+        'AAPL'
+    """
+    config = demo_data_configs[demo_data]
+    stock_data = SMALL_DATASET_STOCKS if demo_data == DemoData.SMALL else LARGE_DATASET_STOCKS
+
+    stocks = [
+        StockSelection(
+            stock_id=ticker,
+            stock_name=name,
+            sector=sector,
+            predicted_return=predicted_return,
+            selection=None,  # To be decided by solver
+        )
+        for ticker, name, sector, predicted_return in stock_data
+    ]
+
+    # Calculate max_per_sector from percentage
+    target_count = config.target_position_count
+    max_per_sector = max(1, int(config.max_sector_percentage * target_count))
+
+    # Create PortfolioConfig for constraints to access
+    portfolio_config = PortfolioConfig(
+        target_count=target_count,
+        max_per_sector=max_per_sector,
+        unselected_penalty=10000,
+    )
+
+    return PortfolioOptimizationPlan(
+        stocks=stocks,
+        target_position_count=config.target_position_count,
+        max_sector_percentage=config.max_sector_percentage,
+        portfolio_config=portfolio_config,
+    )
+
+
+def get_stock_summary(plan: PortfolioOptimizationPlan) -> str:
+    """
+    Generate a human-readable summary of the portfolio.
+
+    Useful for debugging and understanding the solution.
+    """
+    lines = [
+        "=" * 60,
+        "PORTFOLIO SUMMARY",
+        "=" * 60,
+    ]
+
+    selected = plan.get_selected_stocks()
+    if not selected:
+        lines.append("No stocks selected yet.")
+        return "\n".join(lines)
+
+    weight = plan.get_weight_per_stock()
+    expected_return = plan.get_expected_return()
+
+    lines.append(f"Selected: {len(selected)} stocks @ {weight*100:.1f}% each")
+    lines.append(f"Expected Return: {expected_return*100:.2f}%")
+    lines.append("")
+
+    # Group by sector
+    sector_stocks: dict[str, list[StockSelection]] = {}
+    for stock in selected:
+        if stock.sector not in sector_stocks:
+            sector_stocks[stock.sector] = []
+        sector_stocks[stock.sector].append(stock)
+
+    lines.append("BY SECTOR:")
+    for sector, stocks in sorted(sector_stocks.items()):
+        sector_weight = len(stocks) * weight * 100
+        lines.append(f"  {sector}: {len(stocks)} stocks = {sector_weight:.1f}%")
+        for stock in sorted(stocks, key=lambda s: -s.predicted_return):
+            lines.append(f"    - {stock.stock_id}: {stock.stock_name} ({stock.predicted_return*100:.1f}% pred)")
+
+    lines.append("")
+    lines.append(f"Score: {plan.score}")
+    lines.append("=" * 60)
+
+    return "\n".join(lines)

src/portfolio_optimization/domain.py

@@ -0,0 +1,307 @@
+"""
+Portfolio Optimization Domain Model
+
+This module defines the core domain entities for stock portfolio optimization:
+- StockSelection: A stock that can be selected for the portfolio (planning entity)
+- PortfolioOptimizationPlan: The complete portfolio optimization problem (planning solution)
+
+The model uses a Boolean selection approach:
+- Each stock has a `selected` field (True/False)
+- Selected stocks get equal weight (100% / number_selected)
+- This simplifies the optimization while still demonstrating constraint solving
+"""
+from solverforge_legacy.solver import SolverStatus
+from solverforge_legacy.solver.domain import (
+    planning_entity,
+    planning_solution,
+    PlanningId,
+    PlanningVariable,
+    PlanningEntityCollectionProperty,
+    ProblemFactCollectionProperty,
+    ProblemFactProperty,
+    ValueRangeProvider,
+    PlanningScore,
+)
+from solverforge_legacy.solver.score import HardSoftScore
+from typing import Annotated, List, Optional
+from dataclasses import dataclass, field
+from .json_serialization import JsonDomainBase
+from pydantic import Field
+
+
+@dataclass
+class SelectionValue:
+    """
+    Represents a possible selection state for a stock.
+
+    We use this wrapper class instead of raw bool because SolverForge
+    needs a reference type for the value range provider.
+    """
+    value: bool
+
+    def __hash__(self):
+        return hash(self.value)
+
+    def __eq__(self, other):
+        if isinstance(other, SelectionValue):
+            return self.value == other.value
+        return False
+
+
+# Pre-created selection values for the value range
+SELECTED = SelectionValue(True)
+NOT_SELECTED = SelectionValue(False)
+
+
+@dataclass
+class PortfolioConfig:
+    """
+    Configuration parameters for portfolio constraints.
+
+    This is a problem fact that constraints can join against to access
+    configurable threshold values.
+
+    Attributes:
+        target_count: Number of stocks to select (default 20)
+        max_per_sector: Maximum stocks per sector (default 5, which is 25% of 20)
+        unselected_penalty: Soft penalty per unselected stock (default 10000)
+    """
+    target_count: int = 20
+    max_per_sector: int = 5
+    unselected_penalty: int = 10000
+
+    def __hash__(self) -> int:
+        return hash((self.target_count, self.max_per_sector, self.unselected_penalty))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, PortfolioConfig):
+            return (
+                self.target_count == other.target_count
+                and self.max_per_sector == other.max_per_sector
+                and self.unselected_penalty == other.unselected_penalty
+            )
+        return False
+
+
+@planning_entity
+@dataclass
+class StockSelection:
+    """
+    Represents a stock that can be included in the portfolio.
+
+    This is a planning entity - SolverForge decides whether to include
+    each stock by setting the `selection` field.
+
+    Attributes:
+        stock_id: Unique identifier (ticker symbol, e.g., "AAPL")
+        stock_name: Human-readable name (e.g., "Apple Inc.")
+        sector: Industry sector (e.g., "Technology", "Healthcare")
+        predicted_return: ML-predicted return as decimal (0.12 = 12%)
+        selection: Planning variable - SELECTED or NOT_SELECTED
+    """
+    stock_id: Annotated[str, PlanningId]
+    stock_name: str
+    sector: str
+    predicted_return: float  # e.g., 0.12 means 12% expected return
+
+    # THE DECISION: Should we include this stock in the portfolio?
+    # SolverForge will set this to SELECTED or NOT_SELECTED
+    # Note: value_range_provider_refs links to the 'selection_range' field
+    selection: Annotated[
+        SelectionValue | None,
+        PlanningVariable(value_range_provider_refs=["selection_range"])
+    ] = None
+
+    @property
+    def selected(self) -> bool | None:
+        """Convenience property to check if stock is selected."""
+        if self.selection is None:
+            return None
+        return self.selection.value
+
+
+@planning_solution
+@dataclass
+class PortfolioOptimizationPlan:
+    """
+    The complete portfolio optimization problem.
+
+    This is the planning solution that contains:
+    - All candidate stocks (planning entities)
+    - Configuration parameters
+    - The optimization score
+
+    The solver will decide which stocks to select (set selected=True)
+    while respecting constraints and maximizing expected return.
+    """
+    # All stocks we're choosing from (planning entities)
+    stocks: Annotated[
+        list[StockSelection],
+        PlanningEntityCollectionProperty,
+        ValueRangeProvider
+    ]
+
+    # Configuration
+    target_position_count: int = 20  # How many stocks to select
+    max_sector_percentage: float = 0.25  # Max 25% in any sector
+
+    # Constraint configuration (problem fact for constraints to access)
+    # This derives from target_position_count and max_sector_percentage
+    portfolio_config: Annotated[
+        PortfolioConfig,
+        ProblemFactProperty
+    ] = field(default_factory=PortfolioConfig)
+
+    # Value range for the selection
+    # The solver can set `selection` to SELECTED or NOT_SELECTED
+    # Note: id="selection_range" must match the value_range_provider_refs in StockSelection
+    selection_range: Annotated[
+        list[SelectionValue],
+        ValueRangeProvider(id="selection_range"),
+        ProblemFactCollectionProperty
+    ] = field(default_factory=lambda: [SELECTED, NOT_SELECTED])
+
+    # Solution quality score (set by solver)
+    score: Annotated[HardSoftScore | None, PlanningScore] = None
+
+    # Current solver status
+    solver_status: SolverStatus = SolverStatus.NOT_SOLVING
+
+    def get_selected_stocks(self) -> list[StockSelection]:
+        """Return only stocks that are selected for the portfolio."""
+        return [s for s in self.stocks if s.selected is True]
+
+    def get_selected_count(self) -> int:
+        """Return count of selected stocks."""
+        return len(self.get_selected_stocks())
+
+    def get_weight_per_stock(self) -> float:
+        """Calculate equal weight per selected stock (e.g., 20 stocks = 5% each)."""
+        count = self.get_selected_count()
+        return 1.0 / count if count > 0 else 0.0
+
+    def get_sector_weights(self) -> dict[str, float]:
+        """Calculate total weight per sector."""
+        weight = self.get_weight_per_stock()
+        sector_weights: dict[str, float] = {}
+        for stock in self.get_selected_stocks():
+            sector_weights[stock.sector] = sector_weights.get(stock.sector, 0.0) + weight
+        return sector_weights
+
+    def get_expected_return(self) -> float:
+        """Calculate total expected portfolio return."""
+        weight = self.get_weight_per_stock()
+        return sum(s.predicted_return * weight for s in self.get_selected_stocks())
+
+    def get_herfindahl_index(self) -> float:
+        """
+        Calculate the Herfindahl-Hirschman Index (HHI) for sector concentration.
+
+        HHI = sum of (sector_weight)^2
+        - Range: 1/n (perfectly diversified) to 1.0 (all in one sector)
+        - Lower HHI = more diversified
+        - Common thresholds: <0.15 (diversified), 0.15-0.25 (moderate), >0.25 (concentrated)
+        """
+        sector_weights = self.get_sector_weights()
+        if not sector_weights:
+            return 0.0
+        return sum(w * w for w in sector_weights.values())
+
+    def get_diversification_score(self) -> float:
+        """
+        Calculate diversification score as 1 - HHI.
+
+        Range: 0.0 (all in one sector) to 1-1/n (perfectly diversified)
+        Higher = more diversified
+        """
+        return 1.0 - self.get_herfindahl_index()
+
+    def get_max_sector_exposure(self) -> float:
+        """
+        Get the highest single sector weight.
+
+        Returns the weight of the most concentrated sector.
+        Lower is better for diversification.
+        """
+        sector_weights = self.get_sector_weights()
+        if not sector_weights:
+            return 0.0
+        return max(sector_weights.values())
+
+    def get_sector_count(self) -> int:
+        """Return count of unique sectors in selected stocks."""
+        selected = self.get_selected_stocks()
+        return len(set(s.sector for s in selected))
+
+    def get_return_volatility(self) -> float:
+        """
+        Calculate standard deviation of predicted returns (proxy for risk).
+
+        Higher volatility = higher risk portfolio.
+        """
+        selected = self.get_selected_stocks()
+        if len(selected) < 2:
+            return 0.0
+
+        returns = [s.predicted_return for s in selected]
+        mean_return = sum(returns) / len(returns)
+        variance = sum((r - mean_return) ** 2 for r in returns) / len(returns)
+        return variance ** 0.5
+
+    def get_sharpe_proxy(self) -> float:
+        """
+        Calculate a proxy for Sharpe ratio: return / volatility.
+
+        Higher = better risk-adjusted return.
+        Note: This is a simplified proxy, not true Sharpe (no risk-free rate).
+        """
+        volatility = self.get_return_volatility()
+        if volatility == 0:
+            return 0.0
+        return self.get_expected_return() / volatility
+
+
+# ============================================================
+# Pydantic REST Models (for API serialization)
+# ============================================================
+
+class StockSelectionModel(JsonDomainBase):
+    """REST API model for StockSelection."""
+    stock_id: str = Field(..., alias="stockId")
+    stock_name: str = Field(..., alias="stockName")
+    sector: str
+    predicted_return: float = Field(..., alias="predictedReturn")
+    selected: Optional[bool] = None
+
+
+class SolverConfigModel(JsonDomainBase):
+    """REST API model for solver configuration options."""
+    termination_seconds: int = Field(default=30, alias="terminationSeconds", ge=10, le=300)
+
+
+class PortfolioMetricsModel(JsonDomainBase):
+    """
+    REST API model for portfolio business metrics (KPIs).
+
+    These metrics provide business insight beyond the solver score:
+    - Diversification measures (HHI, max sector exposure)
+    - Risk/return measures (expected return, volatility, Sharpe proxy)
+    """
+    expected_return: float = Field(..., alias="expectedReturn")
+    sector_count: int = Field(..., alias="sectorCount")
+    max_sector_exposure: float = Field(..., alias="maxSectorExposure")
+    herfindahl_index: float = Field(..., alias="herfindahlIndex")
+    diversification_score: float = Field(..., alias="diversificationScore")
+    return_volatility: float = Field(..., alias="returnVolatility")
+    sharpe_proxy: float = Field(..., alias="sharpeProxy")
+
+
+class PortfolioOptimizationPlanModel(JsonDomainBase):
+    """REST API model for PortfolioOptimizationPlan."""
+    stocks: List[StockSelectionModel]
+    target_position_count: int = Field(default=20, alias="targetPositionCount")
+    max_sector_percentage: float = Field(default=0.25, alias="maxSectorPercentage")
+    score: Optional[str] = None
+    solver_status: Optional[str] = Field(None, alias="solverStatus")
+    solver_config: Optional[SolverConfigModel] = Field(None, alias="solverConfig")
+    metrics: Optional[PortfolioMetricsModel] = None

src/portfolio_optimization/json_serialization.py

@@ -0,0 +1,42 @@
+"""
+JSON serialization utilities for the Portfolio Optimization quickstart.
+
+Provides Pydantic configuration for REST API models with camelCase support.
+"""
+from solverforge_legacy.solver.score import HardSoftScore
+from typing import Any
+from pydantic import BaseModel, ConfigDict, PlainSerializer, BeforeValidator
+from pydantic.alias_generators import to_camel
+
+
+ScoreSerializer = PlainSerializer(
+    lambda score: str(score) if score is not None else None, return_type=str | None
+)
+
+
+def validate_score(v: Any) -> Any:
+    """Validate and parse score from string or HardSoftScore."""
+    if isinstance(v, HardSoftScore) or v is None:
+        return v
+    if isinstance(v, str):
+        return HardSoftScore.parse(v)
+    raise ValueError('"score" should be a string')
+
+
+ScoreValidator = BeforeValidator(validate_score)
+
+
+class JsonDomainBase(BaseModel):
+    """
+    Base class for Pydantic REST models.
+
+    Provides:
+    - Automatic camelCase conversion for JSON keys
+    - Support for both camelCase and snake_case in input
+    - Attribute access from dataclass instances
+    """
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )

src/portfolio_optimization/rest_api.py

@@ -0,0 +1,189 @@
+"""
+REST API for Portfolio Optimization
+
+This module provides HTTP endpoints for the portfolio optimization quickstart:
+
+Endpoints:
+- GET  /demo-data           - List available demo datasets
+- GET  /demo-data/{id}      - Load a specific demo dataset
+- POST /portfolios          - Submit a portfolio for optimization
+- GET  /portfolios/{id}     - Get current solution for a job
+- GET  /portfolios/{id}/status - Get solving status
+- DELETE /portfolios/{id}   - Stop solving
+- PUT  /portfolios/analyze  - Analyze a submitted portfolio's score
+
+The API follows the same patterns as other SolverForge quickstarts.
+"""
+from fastapi import FastAPI, Request
+from fastapi.staticfiles import StaticFiles
+from uuid import uuid4
+from dataclasses import replace
+from typing import Any
+
+from solverforge_legacy.solver import SolverManager, SolverFactory
+
+from .domain import PortfolioOptimizationPlan, PortfolioOptimizationPlanModel
+from .converters import plan_to_model, model_to_plan
+from .demo_data import DemoData, generate_demo_data
+from .solver import solver_manager, solution_manager, create_solver_config
+from .score_analysis import ConstraintAnalysisDTO, MatchAnalysisDTO
+
+
+app = FastAPI(
+    title="Portfolio Optimization Quickstart",
+    description="SolverForge quickstart for stock portfolio optimization",
+    docs_url='/q/swagger-ui'
+)
+
+# In-memory storage for submitted portfolios and their solver managers
+data_sets: dict[str, PortfolioOptimizationPlan] = {}
+solver_managers: dict[str, SolverManager] = {}
+
+
+@app.get("/demo-data")
+async def demo_data_list() -> list[DemoData]:
+    """List available demo datasets."""
+    return [e for e in DemoData]
+
+
+@app.get("/demo-data/{dataset_id}", response_model_exclude_none=True)
+async def get_demo_data(dataset_id: str) -> PortfolioOptimizationPlanModel:
+    """Load a specific demo dataset."""
+    demo_data = getattr(DemoData, dataset_id)
+    domain_plan = generate_demo_data(demo_data)
+    return plan_to_model(domain_plan)
+
+
+@app.get("/portfolios/{problem_id}", response_model_exclude_none=True)
+async def get_portfolio(problem_id: str) -> PortfolioOptimizationPlanModel:
+    """Get current solution for a portfolio optimization job."""
+    plan = data_sets[problem_id]
+    # Use per-job solver manager if available, otherwise use default
+    manager = solver_managers.get(problem_id, solver_manager)
+    updated_plan = replace(plan, solver_status=manager.get_solver_status(problem_id))
+    return plan_to_model(updated_plan)
+
+
+def update_portfolio(problem_id: str, plan: PortfolioOptimizationPlan) -> None:
+    """Callback to update the stored solution as solver improves it."""
+    global data_sets
+    data_sets[problem_id] = plan
+
+
+@app.post("/portfolios")
+async def solve_portfolio(plan_model: PortfolioOptimizationPlanModel) -> str:
+    """
+    Submit a portfolio for optimization.
+
+    Returns a job ID that can be used to retrieve the solution.
+    Supports custom solver configuration via solverConfig field.
+    """
+    job_id = str(uuid4())
+    plan = model_to_plan(plan_model)
+    data_sets[job_id] = plan
+
+    # Get termination time from config or use default
+    termination_seconds = 30
+    if plan_model.solver_config and plan_model.solver_config.termination_seconds:
+        termination_seconds = plan_model.solver_config.termination_seconds
+
+    # Create solver with dynamic config
+    config = create_solver_config(termination_seconds)
+    manager: SolverManager = SolverManager.create(SolverFactory.create(config))
+    solver_managers[job_id] = manager
+
+    manager.solve_and_listen(
+        job_id,
+        plan,
+        lambda solution: update_portfolio(job_id, solution)
+    )
+    return job_id
+
+
+@app.get("/portfolios")
+async def list_portfolios() -> list[str]:
+    """List all job IDs of submitted portfolios."""
+    return list(data_sets.keys())
+
+
+@app.get("/portfolios/{problem_id}/status")
+async def get_status(problem_id: str) -> dict[str, Any]:
+    """Get the portfolio status and score for a given job ID."""
+    if problem_id not in data_sets:
+        raise ValueError(f"No portfolio found with ID {problem_id}")
+
+    plan = data_sets[problem_id]
+    # Use per-job solver manager if available, otherwise use default
+    manager = solver_managers.get(problem_id, solver_manager)
+    solver_status = manager.get_solver_status(problem_id)
+
+    # Calculate additional metrics
+    selected_count = plan.get_selected_count()
+    expected_return = plan.get_expected_return() if selected_count > 0 else 0
+
+    return {
+        "score": {
+            "hardScore": plan.score.hard_score if plan.score else 0,
+            "softScore": plan.score.soft_score if plan.score else 0,
+        },
+        "solverStatus": solver_status.name,
+        "selectedCount": selected_count,
+        "expectedReturn": expected_return,
+        "sectorWeights": plan.get_sector_weights() if selected_count > 0 else {},
+    }
+
+
+@app.delete("/portfolios/{problem_id}")
+async def stop_solving(problem_id: str) -> PortfolioOptimizationPlanModel:
+    """Terminate solving for a given job ID."""
+    if problem_id not in data_sets:
+        raise ValueError(f"No portfolio found with ID {problem_id}")
+
+    # Use per-job solver manager if available, otherwise use default
+    manager = solver_managers.get(problem_id, solver_manager)
+    try:
+        manager.terminate_early(problem_id)
+    except Exception as e:
+        print(f"Warning: terminate_early failed for {problem_id}: {e}")
+
+    return await get_portfolio(problem_id)
+
+
+@app.put("/portfolios/analyze")
+async def analyze_portfolio(request: Request) -> dict[str, Any]:
+    """Submit a portfolio to analyze its score in detail."""
+    json_data = await request.json()
+
+    # Parse the incoming JSON using Pydantic models
+    plan_model = PortfolioOptimizationPlanModel.model_validate(json_data)
+
+    # Convert to domain model for analysis
+    domain_plan = model_to_plan(plan_model)
+
+    analysis = solution_manager.analyze(domain_plan)
+
+    # Convert to DTOs for proper serialization
+    constraints = []
+    for constraint in getattr(analysis, 'constraint_analyses', []) or []:
+        matches = [
+            MatchAnalysisDTO(
+                name=str(getattr(getattr(match, 'constraint_ref', None), 'constraint_name', "")),
+                score=str(getattr(match, 'score', "0hard/0soft")),
+                justification=str(getattr(match, 'justification', "")),
+            )
+            for match in getattr(constraint, 'matches', []) or []
+        ]
+
+        constraint_dto = ConstraintAnalysisDTO(
+            name=str(getattr(constraint, 'constraint_name', "")),
+            weight=str(getattr(constraint, 'weight', "0hard/0soft")),
+            score=str(getattr(constraint, 'score', "0hard/0soft")),
+            matches=matches,
+        )
+        constraints.append(constraint_dto)
+
+    return {"constraints": [constraint.model_dump() for constraint in constraints]}
+
+
+# Mount static files for the web UI
+app.mount("/", StaticFiles(directory="static", html=True), name="static")

src/portfolio_optimization/score_analysis.py

@@ -0,0 +1,23 @@
+"""
+Score Analysis DTOs for Portfolio Optimization.
+
+These data transfer objects are used for the /analyze endpoint
+to provide detailed constraint-by-constraint score breakdown.
+"""
+from pydantic import BaseModel
+from typing import List
+
+
+class MatchAnalysisDTO(BaseModel):
+    """A single constraint match (violation or reward)."""
+    name: str
+    score: str
+    justification: str
+
+
+class ConstraintAnalysisDTO(BaseModel):
+    """Analysis of a single constraint across all matches."""
+    name: str
+    weight: str
+    score: str
+    matches: List[MatchAnalysisDTO]

src/portfolio_optimization/solver.py

@@ -0,0 +1,59 @@
+"""
+Solver Configuration for Portfolio Optimization
+
+This module sets up the SolverForge solver with:
+- Solution class (PortfolioOptimizationPlan)
+- Entity class (StockSelection)
+- Constraint provider (define_constraints)
+- Termination config (configurable, default 30 seconds)
+
+The solver explores different stock selections and finds the best
+portfolio that satisfies all constraints while maximizing return.
+"""
+from solverforge_legacy.solver import SolverManager, SolverFactory, SolutionManager
+from solverforge_legacy.solver.config import (
+    SolverConfig,
+    ScoreDirectorFactoryConfig,
+    TerminationConfig,
+    Duration,
+)
+
+from .domain import PortfolioOptimizationPlan, StockSelection
+from .constraints import define_constraints
+
+
+def create_solver_config(termination_seconds: int = 30) -> SolverConfig:
+    """
+    Create a solver configuration with specified termination time.
+
+    Args:
+        termination_seconds: How long to run the solver (default 30 seconds)
+
+    Returns:
+        SolverConfig configured for portfolio optimization
+    """
+    return SolverConfig(
+        # The solution class that contains all entities
+        solution_class=PortfolioOptimizationPlan,
+
+        # The entity classes that the solver modifies
+        entity_class_list=[StockSelection],
+
+        # The constraint provider that defines business rules
+        score_director_factory_config=ScoreDirectorFactoryConfig(
+            constraint_provider_function=define_constraints
+        ),
+
+        # How long to run the solver
+        termination_config=TerminationConfig(spent_limit=Duration(seconds=termination_seconds)),
+    )
+
+
+# Default solver config (30 seconds)
+solver_config: SolverConfig = create_solver_config()
+
+# Create default solver manager for handling solve requests
+solver_manager: SolverManager = SolverManager.create(SolverFactory.create(solver_config))
+
+# Create solution manager for analyzing solutions
+solution_manager: SolutionManager = SolutionManager.create(solver_manager)

static/app.js

@@ -0,0 +1,851 @@
+/**
+ * Portfolio Optimization Quickstart - Frontend Application
+ */
+
+// =============================================================================
+// Global State
+// =============================================================================
+
+let autoRefreshIntervalId = null;
+let demoDataId = "SMALL";
+let scheduleId = null;
+let loadedPlan = null;
+
+// Chart instances
+let sectorChart = null;
+let returnsChart = null;
+
+// Sorting state for stock table
+let sortColumn = 'predictedReturn';
+let sortDirection = 'desc';
+
+// Sector colors (consistent across charts and badges)
+const SECTOR_COLORS = {
+    'Technology': '#3b82f6',
+    'Healthcare': '#10b981',
+    'Finance': '#eab308',
+    'Energy': '#ef4444',
+    'Consumer': '#a855f7'
+};
+
+// =============================================================================
+// Initialization
+// =============================================================================
+
+$(document).ready(function() {
+    // Initialize header/footer with nav tabs
+    replaceQuickstartSolverForgeAutoHeaderFooter();
+
+    // Initialize Bootstrap tooltips
+    const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]');
+    [...tooltipTriggerList].map(el => new bootstrap.Tooltip(el));
+
+    // Load initial data
+    loadDemoData();
+
+    // Event handlers
+    $("#solveButton").click(solve);
+    $("#stopSolvingButton").click(stopSolving);
+    $("#analyzeButton").click(analyze);
+    $("#dataSelector").change(function() {
+        demoDataId = $(this).val();
+        loadDemoData();
+    });
+    $("#showSelectedOnly").change(renderAllStocksTable);
+
+    // Sortable table headers
+    $("#allStocksTable").closest("table").find("th[data-sort]").click(function() {
+        const column = $(this).data("sort");
+        if (sortColumn === column) {
+            sortDirection = sortDirection === 'asc' ? 'desc' : 'asc';
+        } else {
+            sortColumn = column;
+            sortDirection = 'desc';
+        }
+        updateSortIndicators();
+        renderAllStocksTable();
+    });
+
+    // Initialize advanced configuration if available (from config.js)
+    if (typeof initAdvancedConfig === 'function') {
+        initAdvancedConfig();
+    }
+});
+
+// =============================================================================
+// jQuery AJAX Extensions
+// =============================================================================
+
+$.ajaxSetup({
+    contentType: "application/json",
+    accepts: {
+        json: "application/json"
+    }
+});
+
+$.put = function(url, data) {
+    return $.ajax({
+        url: url,
+        type: "PUT",
+        data: JSON.stringify(data),
+        contentType: "application/json"
+    });
+};
+
+$.delete = function(url) {
+    return $.ajax({
+        url: url,
+        type: "DELETE"
+    });
+};
+
+// =============================================================================
+// Data Loading
+// =============================================================================
+
+function loadDemoData() {
+    $.getJSON("/demo-data/" + demoDataId)
+        .done(function(data) {
+            loadedPlan = data;
+            scheduleId = null;
+            // Apply advanced config if available (from config.js)
+            if (typeof applyConfigToLoadedPlan === 'function') {
+                applyConfigToLoadedPlan();
+            }
+            refreshUI();
+            updateScore("Score: ?");
+        })
+        .fail(function(xhr) {
+            showError("Failed to load demo data", xhr);
+        });
+}
+
+// =============================================================================
+// Solving
+// =============================================================================
+
+function solve() {
+    if (!loadedPlan) {
+        showSimpleError("Please load demo data first");
+        return;
+    }
+
+    $.ajax({
+        url: "/portfolios",
+        type: "POST",
+        data: JSON.stringify(loadedPlan),
+        contentType: "application/json"
+    })
+    .done(function(data) {
+        scheduleId = data;
+        refreshSolvingButtons(true);
+    })
+    .fail(function(xhr) {
+        showError("Failed to start solver", xhr);
+    });
+}
+
+function stopSolving() {
+    if (!scheduleId) return;
+
+    $.delete("/portfolios/" + scheduleId)
+        .done(function(data) {
+            loadedPlan = data;
+            refreshSolvingButtons(false);
+            refreshUI();
+        })
+        .fail(function(xhr) {
+            showError("Failed to stop solver", xhr);
+        });
+}
+
+function refreshSolvingButtons(solving) {
+    if (solving) {
+        $("#solveButton").hide();
+        $("#stopSolvingButton").show();
+        $("#solvingSpinner").addClass("active");
+        $(".kpi-value").addClass("solving-pulse");
+
+        if (autoRefreshIntervalId == null) {
+            autoRefreshIntervalId = setInterval(refreshSchedule, 2000);
+        }
+    } else {
+        $("#solveButton").show();
+        $("#stopSolvingButton").hide();
+        $("#solvingSpinner").removeClass("active");
+        $(".kpi-value").removeClass("solving-pulse");
+
+        if (autoRefreshIntervalId != null) {
+            clearInterval(autoRefreshIntervalId);
+            autoRefreshIntervalId = null;
+        }
+    }
+}
+
+function refreshSchedule() {
+    if (!scheduleId) return;
+
+    $.getJSON("/portfolios/" + scheduleId)
+        .done(function(data) {
+            loadedPlan = data;
+            refreshUI();
+
+            // Check if solver is done
+            if (data.solverStatus === "NOT_SOLVING") {
+                refreshSolvingButtons(false);
+            }
+        })
+        .fail(function(xhr) {
+            showError("Failed to refresh solution", xhr);
+            refreshSolvingButtons(false);
+        });
+}
+
+// =============================================================================
+// Score Analysis
+// =============================================================================
+
+function analyze() {
+    if (!loadedPlan) {
+        showSimpleError("Please load demo data first");
+        return;
+    }
+
+    $.put("/portfolios/analyze", loadedPlan)
+        .done(function(data) {
+            showConstraintAnalysis(data);
+        })
+        .fail(function(xhr) {
+            showError("Failed to analyze constraints", xhr);
+        });
+}
+
+function showConstraintAnalysis(analysis) {
+    const tbody = $("#weightModalContent tbody");
+    tbody.empty();
+
+    // Update modal label with score
+    const score = loadedPlan.score || "?";
+    $("#weightModalLabel").text(score);
+
+    // Sort constraints: hard first, then by score impact
+    const constraints = analysis.constraints || [];
+    constraints.sort((a, b) => {
+        if (a.type !== b.type) {
+            return a.type === "HARD" ? -1 : 1;
+        }
+        return Math.abs(b.score) - Math.abs(a.score);
+    });
+
+    constraints.forEach(function(c) {
+        const icon = c.score === 0
+            ? '<i class="fas fa-check-circle text-success"></i>'
+            : '<i class="fas fa-exclamation-triangle text-danger"></i>';
+
+        const typeClass = c.type === "HARD" ? "text-danger" : "text-warning";
+        const scoreClass = c.score === 0 ? "text-success" : "text-danger";
+
+        tbody.append(`
+            <tr>
+                <td>${icon}</td>
+                <td>${c.name}</td>
+                <td><span class="${typeClass}">${c.type}</span></td>
+                <td>${c.weight || '-'}</td>
+                <td>${c.matchCount || 0}</td>
+                <td class="${scoreClass}">${c.score}</td>
+            </tr>
+        `);
+    });
+
+    // Show modal
+    const modal = new bootstrap.Modal(document.getElementById('weightModal'));
+    modal.show();
+}
+
+// =============================================================================
+// UI Refresh
+// =============================================================================
+
+function refreshUI() {
+    updateKPIs();
+    updateScore();
+    updateCharts();
+    renderSelectedStocksTable();
+    renderAllStocksTable();
+}
+
+function updateKPIs() {
+    if (!loadedPlan || !loadedPlan.stocks) {
+        resetKPIs();
+        return;
+    }
+
+    const stocks = loadedPlan.stocks;
+    const selected = stocks.filter(s => s.selected);
+    const selectedCount = selected.length;
+
+    // Get target from plan, config module, or default to 20
+    let targetCount = loadedPlan.targetPositionCount || 20;
+    if (typeof getTargetStockCount === 'function') {
+        targetCount = getTargetStockCount();
+    }
+
+    // Selected stocks count (show target)
+    const selectedEl = $("#selectedCount");
+    selectedEl.text(selectedCount + "/" + targetCount);
+    if (selectedCount === targetCount) {
+        selectedEl.removeClass("text-warning").addClass("text-success");
+    } else if (selectedCount > 0) {
+        selectedEl.removeClass("text-success").addClass("text-warning");
+    } else {
+        selectedEl.removeClass("text-success text-warning");
+    }
+    $("#selectedBadge").text(selectedCount + " selected");
+
+    // Stock count badge
+    $("#stockCountBadge").text(stocks.length + " stocks");
+
+    // Use metrics from backend if available
+    if (loadedPlan.metrics) {
+        updateKPIsFromMetrics(loadedPlan.metrics);
+    } else {
+        // Fallback: calculate locally
+        updateKPIsLocally(selected, selectedCount);
+    }
+}
+
+function resetKPIs() {
+    $("#selectedCount").text("0/20");
+    $("#expectedReturn").text("0.00%").removeClass("positive negative");
+    $("#sectorCount").text("0");
+    $("#diversificationScore").text("0%").removeClass("text-success text-warning text-danger");
+    $("#maxSectorExposure").text("0%");
+    $("#returnVolatility").text("0.00%");
+    $("#sharpeProxy").text("0.00");
+    $("#herfindahlIndex").text("0.000");
+    $("#selectedBadge").text("0 selected");
+}
+
+function updateKPIsFromMetrics(metrics) {
+    // Expected return
+    const returnEl = $("#expectedReturn");
+    returnEl.text((metrics.expectedReturn * 100).toFixed(2) + "%");
+    returnEl.removeClass("positive negative");
+    returnEl.addClass(metrics.expectedReturn >= 0 ? "positive" : "negative");
+
+    // Sector count
+    $("#sectorCount").text(metrics.sectorCount);
+
+    // Diversification score (0-100%)
+    const divScore = (metrics.diversificationScore * 100).toFixed(0);
+    const divEl = $("#diversificationScore");
+    divEl.text(divScore + "%");
+    divEl.removeClass("text-success text-warning text-danger");
+    if (metrics.diversificationScore >= 0.7) {
+        divEl.addClass("text-success");
+    } else if (metrics.diversificationScore >= 0.5) {
+        divEl.addClass("text-warning");
+    } else {
+        divEl.addClass("text-danger");
+    }
+
+    // Max sector exposure
+    $("#maxSectorExposure").text((metrics.maxSectorExposure * 100).toFixed(1) + "%");
+
+    // Return volatility
+    $("#returnVolatility").text((metrics.returnVolatility * 100).toFixed(2) + "%");
+
+    // Sharpe proxy
+    const sharpeEl = $("#sharpeProxy");
+    sharpeEl.text(metrics.sharpeProxy.toFixed(2));
+    sharpeEl.removeClass("text-success text-warning text-danger");
+    if (metrics.sharpeProxy >= 1.0) {
+        sharpeEl.addClass("text-success");
+    } else if (metrics.sharpeProxy >= 0.5) {
+        sharpeEl.addClass("text-warning");
+    }
+
+    // HHI (Herfindahl-Hirschman Index)
+    const hhiEl = $("#herfindahlIndex");
+    hhiEl.text(metrics.herfindahlIndex.toFixed(3));
+    hhiEl.removeClass("text-success text-warning text-danger");
+    if (metrics.herfindahlIndex < 0.15) {
+        hhiEl.addClass("text-success");
+    } else if (metrics.herfindahlIndex < 0.25) {
+        hhiEl.addClass("text-warning");
+    } else {
+        hhiEl.addClass("text-danger");
+    }
+}
+
+function updateKPIsLocally(selected, selectedCount) {
+    // Expected return (weighted average)
+    const expectedReturn = selectedCount > 0
+        ? selected.reduce((sum, s) => sum + s.predictedReturn, 0) / selectedCount
+        : 0;
+    const returnEl = $("#expectedReturn");
+    returnEl.text((expectedReturn * 100).toFixed(2) + "%");
+    returnEl.removeClass("positive negative");
+    returnEl.addClass(expectedReturn >= 0 ? "positive" : "negative");
+
+    // Sector count
+    const sectors = new Set(selected.map(s => s.sector));
+    $("#sectorCount").text(sectors.size);
+
+    if (selectedCount > 0) {
+        // Calculate sector weights and HHI locally
+        const sectorCounts = {};
+        selected.forEach(s => {
+            sectorCounts[s.sector] = (sectorCounts[s.sector] || 0) + 1;
+        });
+
+        const sectorWeights = Object.values(sectorCounts).map(c => c / selectedCount);
+        const hhi = sectorWeights.reduce((sum, w) => sum + w * w, 0);
+        const divScore = ((1 - hhi) * 100).toFixed(0);
+        const maxSector = Math.max(...sectorWeights) * 100;
+
+        $("#diversificationScore").text(divScore + "%");
+        $("#maxSectorExposure").text(maxSector.toFixed(1) + "%");
+        $("#herfindahlIndex").text(hhi.toFixed(3));
+
+        // Calculate volatility locally
+        const returns = selected.map(s => s.predictedReturn);
+        const meanReturn = returns.reduce((a, b) => a + b, 0) / returns.length;
+        const variance = returns.reduce((sum, r) => sum + Math.pow(r - meanReturn, 2), 0) / returns.length;
+        const volatility = Math.sqrt(variance);
+
+        $("#returnVolatility").text((volatility * 100).toFixed(2) + "%");
+        $("#sharpeProxy").text(volatility > 0 ? (expectedReturn / volatility).toFixed(2) : "0.00");
+    } else {
+        $("#diversificationScore").text("0%");
+        $("#maxSectorExposure").text("0%");
+        $("#returnVolatility").text("0.00%");
+        $("#sharpeProxy").text("0.00");
+        $("#herfindahlIndex").text("0.000");
+    }
+}
+
+function updateScore() {
+    if (!loadedPlan || !loadedPlan.score) {
+        $("#score").text("Score: ?");
+        return;
+    }
+
+    const score = loadedPlan.score;
+    const match = score.match(/(-?\d+)hard\/(-?\d+)soft/);
+
+    if (match) {
+        const hard = parseInt(match[1]);
+        const soft = parseInt(match[2]);
+        const isFeasible = hard === 0;
+
+        const scoreHtml = `
+            <span class="score-badge ${isFeasible ? 'score-feasible' : 'score-infeasible'}">
+                ${hard}hard
+            </span>
+            <span class="score-badge score-soft ms-1">
+                ${soft}soft
+            </span>
+        `;
+        $("#score").html(scoreHtml);
+    } else {
+        $("#score").text("Score: " + score);
+    }
+}
+
+// =============================================================================
+// Charts
+// =============================================================================
+
+function updateCharts() {
+    updateSectorChart();
+    updateReturnsChart();
+}
+
+function updateSectorChart() {
+    const ctx = document.getElementById('sectorChart');
+    if (!ctx) return;
+
+    if (!loadedPlan || !loadedPlan.stocks) {
+        if (sectorChart) {
+            sectorChart.destroy();
+            sectorChart = null;
+        }
+        return;
+    }
+
+    const selected = loadedPlan.stocks.filter(s => s.selected);
+
+    if (selected.length === 0) {
+        if (sectorChart) {
+            sectorChart.destroy();
+            sectorChart = null;
+        }
+        return;
+    }
+
+    // Calculate sector counts
+    const sectorCounts = {};
+    selected.forEach(s => {
+        sectorCounts[s.sector] = (sectorCounts[s.sector] || 0) + 1;
+    });
+
+    const labels = Object.keys(sectorCounts);
+    const data = labels.map(s => (sectorCounts[s] / selected.length) * 100);
+    const colors = labels.map(s => SECTOR_COLORS[s] || '#64748b');
+
+    if (sectorChart) {
+        sectorChart.destroy();
+    }
+
+    sectorChart = new Chart(ctx, {
+        type: 'doughnut',
+        data: {
+            labels: labels,
+            datasets: [{
+                data: data,
+                backgroundColor: colors,
+                borderWidth: 3,
+                borderColor: '#fff',
+                hoverOffset: 8
+            }]
+        },
+        options: {
+            responsive: true,
+            maintainAspectRatio: false,
+            cutout: '60%',
+            plugins: {
+                legend: {
+                    position: 'right',
+                    labels: {
+                        padding: 16,
+                        usePointStyle: true,
+                        pointStyle: 'circle'
+                    }
+                },
+                tooltip: {
+                    callbacks: {
+                        label: function(context) {
+                            const value = context.raw.toFixed(1);
+                            const count = sectorCounts[context.label];
+                            return `${context.label}: ${value}% (${count} stocks)`;
+                        }
+                    }
+                }
+            }
+        }
+    });
+}
+
+function updateReturnsChart() {
+    const ctx = document.getElementById('returnsChart');
+    if (!ctx) return;
+
+    if (!loadedPlan || !loadedPlan.stocks) {
+        if (returnsChart) {
+            returnsChart.destroy();
+            returnsChart = null;
+        }
+        return;
+    }
+
+    const selected = loadedPlan.stocks.filter(s => s.selected);
+
+    if (selected.length === 0) {
+        if (returnsChart) {
+            returnsChart.destroy();
+            returnsChart = null;
+        }
+        return;
+    }
+
+    // Sort by return and take top 10
+    const top10 = [...selected]
+        .sort((a, b) => b.predictedReturn - a.predictedReturn)
+        .slice(0, 10);
+
+    const labels = top10.map(s => s.stockId);
+    const data = top10.map(s => s.predictedReturn * 100);
+    const colors = top10.map(s => SECTOR_COLORS[s.sector] || '#64748b');
+
+    if (returnsChart) {
+        returnsChart.destroy();
+    }
+
+    returnsChart = new Chart(ctx, {
+        type: 'bar',
+        data: {
+            labels: labels,
+            datasets: [{
+                label: 'Predicted Return (%)',
+                data: data,
+                backgroundColor: colors,
+                borderRadius: 6,
+                borderSkipped: false
+            }]
+        },
+        options: {
+            responsive: true,
+            maintainAspectRatio: false,
+            indexAxis: 'y',
+            plugins: {
+                legend: {
+                    display: false
+                },
+                tooltip: {
+                    callbacks: {
+                        label: function(context) {
+                            const stock = top10[context.dataIndex];
+                            return `${stock.stockName}: ${context.raw.toFixed(2)}%`;
+                        }
+                    }
+                }
+            },
+            scales: {
+                x: {
+                    beginAtZero: true,
+                    grid: {
+                        display: true,
+                        color: 'rgba(0,0,0,0.05)'
+                    },
+                    title: {
+                        display: true,
+                        text: 'Predicted Return (%)',
+                        color: '#64748b'
+                    }
+                },
+                y: {
+                    grid: {
+                        display: false
+                    }
+                }
+            }
+        }
+    });
+}
+
+// =============================================================================
+// Tables
+// =============================================================================
+
+function renderSelectedStocksTable() {
+    const tbody = $("#selectedStocksTable");
+
+    if (!loadedPlan || !loadedPlan.stocks) {
+        tbody.html(`
+            <tr>
+                <td colspan="5" class="text-center text-muted py-4">
+                    <i class="fas fa-info-circle me-2"></i>No data loaded
+                </td>
+            </tr>
+        `);
+        return;
+    }
+
+    const selected = loadedPlan.stocks
+        .filter(s => s.selected)
+        .sort((a, b) => b.predictedReturn - a.predictedReturn);
+
+    if (selected.length === 0) {
+        tbody.html(`
+            <tr>
+                <td colspan="5" class="text-center text-muted py-4">
+                    <i class="fas fa-info-circle me-2"></i>No stocks selected yet
+                </td>
+            </tr>
+        `);
+        return;
+    }
+
+    const weightPerStock = 100 / selected.length;
+
+    tbody.html(selected.map(stock => {
+        const returnClass = stock.predictedReturn >= 0 ? 'return-positive' : 'return-negative';
+        const returnSign = stock.predictedReturn >= 0 ? '+' : '';
+
+        return `
+            <tr class="stock-selected">
+                <td><strong>${stock.stockId}</strong></td>
+                <td>${stock.stockName}</td>
+                <td><span class="sector-badge sector-${stock.sector}">${stock.sector}</span></td>
+                <td class="${returnClass}">${returnSign}${(stock.predictedReturn * 100).toFixed(2)}%</td>
+                <td>${weightPerStock.toFixed(2)}%</td>
+            </tr>
+        `;
+    }).join(''));
+}
+
+function renderAllStocksTable() {
+    const tbody = $("#allStocksTable");
+    const showSelectedOnly = $("#showSelectedOnly").is(":checked");
+
+    if (!loadedPlan || !loadedPlan.stocks) {
+        tbody.html(`
+            <tr>
+                <td colspan="6" class="text-center text-muted py-4">
+                    <i class="fas fa-database me-2"></i>No data loaded
+                </td>
+            </tr>
+        `);
+        return;
+    }
+
+    let stocks = loadedPlan.stocks;
+
+    // Filter if needed
+    if (showSelectedOnly) {
+        stocks = stocks.filter(s => s.selected);
+    }
+
+    // Sort
+    stocks = [...stocks].sort((a, b) => {
+        let aVal = a[sortColumn];
+        let bVal = b[sortColumn];
+
+        // Handle boolean (selected)
+        if (sortColumn === 'selected') {
+            aVal = a.selected ? 1 : 0;
+            bVal = b.selected ? 1 : 0;
+        }
+
+        // Handle strings
+        if (typeof aVal === 'string') {
+            aVal = aVal.toLowerCase();
+            bVal = bVal.toLowerCase();
+        }
+
+        if (aVal < bVal) return sortDirection === 'asc' ? -1 : 1;
+        if (aVal > bVal) return sortDirection === 'asc' ? 1 : -1;
+        return 0;
+    });
+
+    if (stocks.length === 0) {
+        tbody.html(`
+            <tr>
+                <td colspan="6" class="text-center text-muted py-4">
+                    <i class="fas fa-filter me-2"></i>No stocks match the filter
+                </td>
+            </tr>
+        `);
+        return;
+    }
+
+    // Calculate weight per stock
+    const selectedCount = loadedPlan.stocks.filter(s => s.selected).length;
+    const weightPerStock = selectedCount > 0 ? (100 / selectedCount) : 0;
+
+    tbody.html(stocks.map(stock => {
+        const returnClass = stock.predictedReturn >= 0 ? 'return-positive' : 'return-negative';
+        const returnSign = stock.predictedReturn >= 0 ? '+' : '';
+        const rowClass = stock.selected ? 'stock-selected' : '';
+        const weight = stock.selected ? weightPerStock.toFixed(2) : '0.00';
+
+        return `
+            <tr class="${rowClass}">
+                <td>
+                    <span class="badge ${stock.selected ? 'bg-success' : 'bg-secondary'}">
+                        ${stock.selected ? 'Yes' : 'No'}
+                    </span>
+                </td>
+                <td><strong>${stock.stockId}</strong></td>
+                <td>${stock.stockName}</td>
+                <td><span class="sector-badge sector-${stock.sector}">${stock.sector}</span></td>
+                <td class="${returnClass}">${returnSign}${(stock.predictedReturn * 100).toFixed(2)}%</td>
+                <td>${weight}%</td>
+            </tr>
+        `;
+    }).join(''));
+}
+
+function updateSortIndicators() {
+    const table = $("#allStocksTable").closest("table");
+    table.find("th").removeClass("sorted");
+    table.find("th i").removeClass("fa-sort-up fa-sort-down").addClass("fa-sort");
+
+    const th = table.find(`th[data-sort="${sortColumn}"]`);
+    th.addClass("sorted");
+    th.find("i")
+        .removeClass("fa-sort")
+        .addClass(sortDirection === 'asc' ? 'fa-sort-up' : 'fa-sort-down');
+}
+
+// =============================================================================
+// Header/Footer with Nav Tabs
+// =============================================================================
+
+function replaceQuickstartSolverForgeAutoHeaderFooter() {
+    const solverforgeHeader = $("header#solverforge-auto-header");
+    if (solverforgeHeader != null) {
+        solverforgeHeader.css("background-color", "#ffffff");
+        solverforgeHeader.append(
+            $(`<div class="container-fluid">
+                <nav class="navbar sticky-top navbar-expand-lg shadow-sm mb-3" style="background-color: #ffffff;">
+                    <a class="navbar-brand" href="https://www.solverforge.org">
+                        <img src="/webjars/solverforge/img/solverforge-horizontal.svg" alt="SolverForge logo" width="300">
+                    </a>
+                    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
+                        <span class="navbar-toggler-icon"></span>
+                    </button>
+                    <div class="collapse navbar-collapse" id="navbarNav">
+                        <ul class="nav nav-pills ms-4">
+                            <li class="nav-item">
+                                <button class="nav-link active" data-bs-toggle="pill" data-bs-target="#demo" type="button" style="color: #1f2937;">
+                                    <i class="fas fa-chart-pie me-1"></i> Demo
+                                </button>
+                            </li>
+                            <li class="nav-item">
+                                <button class="nav-link" data-bs-toggle="pill" data-bs-target="#rest" type="button" style="color: #1f2937;">
+                                    <i class="fas fa-book me-1"></i> Guide
+                                </button>
+                            </li>
+                            <li class="nav-item">
+                                <button class="nav-link" data-bs-toggle="pill" data-bs-target="#openapi" type="button" style="color: #1f2937;">
+                                    <i class="fas fa-code me-1"></i> REST API
+                                </button>
+                            </li>
+                        </ul>
+                    </div>
+                </nav>
+            </div>`)
+        );
+    }
+
+    const solverforgeFooter = $("footer#solverforge-auto-footer");
+    if (solverforgeFooter != null) {
+        solverforgeFooter.append(
+            $(`<footer class="bg-black text-white-50">
+                <div class="container">
+                    <div class="hstack gap-3 p-4">
+                        <div class="ms-auto"><a class="text-white" href="https://www.solverforge.org">SolverForge</a></div>
+                        <div class="vr"></div>
+                        <div><a class="text-white" href="https://www.solverforge.org/docs">Documentation</a></div>
+                        <div class="vr"></div>
+                        <div><a class="text-white" href="https://github.com/SolverForge/solverforge-legacy">Code</a></div>
+                        <div class="vr"></div>
+                        <div class="me-auto"><a class="text-white" href="mailto:info@solverforge.org">Support</a></div>
+                    </div>
+                </div>
+            </footer>`)
+        );
+    }
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+function copyCode(button) {
+    const codeBlock = $(button).closest('.code-block').find('code');
+    const text = codeBlock.text();
+
+    navigator.clipboard.writeText(text).then(function() {
+        const originalHtml = $(button).html();
+        $(button).html('<i class="fas fa-check"></i> Copied!');
+        setTimeout(function() {
+            $(button).html(originalHtml);
+        }, 2000);
+    });
+}
+
+// Make copyCode available globally
+window.copyCode = copyCode;

static/config.js

@@ -0,0 +1,183 @@
+/**
+ * Advanced Configuration Module
+ *
+ * This module provides advanced configuration options for the portfolio optimization
+ * quickstart, including presets and configurable solver parameters.
+ *
+ * NOTE: This is an optional enhancement. The core quickstart works without this module.
+ * To use it, include this script after app.js and call initAdvancedConfig().
+ */
+
+// =============================================================================
+// Configuration Presets
+// =============================================================================
+
+const PRESETS = {
+    conservative: {
+        targetStocks: 30,
+        maxSector: 15,
+        solverTime: 60,
+        description: "Max diversification: 30 stocks, tight sector limits, longer solve time."
+    },
+    balanced: {
+        targetStocks: 20,
+        maxSector: 25,
+        solverTime: 30,
+        description: "Balanced settings for typical portfolio optimization."
+    },
+    aggressive: {
+        targetStocks: 10,
+        maxSector: 40,
+        solverTime: 30,
+        description: "Concentrated bets: fewer stocks, looser sector limits."
+    },
+    quick: {
+        targetStocks: 20,
+        maxSector: 25,
+        solverTime: 10,
+        description: "Fast iteration: same as balanced but 10s solve time."
+    }
+};
+
+// Current configuration state
+let currentConfig = { ...PRESETS.balanced };
+
+// =============================================================================
+// Initialization
+// =============================================================================
+
+/**
+ * Initialize advanced configuration UI and event handlers.
+ * Call this after the DOM is ready.
+ */
+function initAdvancedConfig() {
+    // Preset selector
+    $("#presetSelector").change(function() {
+        const preset = $(this).val();
+        if (preset !== "custom" && PRESETS[preset]) {
+            // Use Object.assign to mutate in place - preserves window.currentConfig reference
+            Object.assign(currentConfig, PRESETS[preset]);
+            updateConfigSliders();
+            updatePresetDescription(preset);
+            applyConfigToLoadedPlan();
+        }
+    });
+
+    // Target stocks slider
+    $("#targetStocksSlider").on("input", function() {
+        currentConfig.targetStocks = parseInt(this.value);
+        $("#targetStocksValue").text(this.value);
+        markAsCustom();
+        applyConfigToLoadedPlan();
+    });
+
+    // Max sector slider
+    $("#maxSectorSlider").on("input", function() {
+        currentConfig.maxSector = parseInt(this.value);
+        $("#maxSectorValue").text(this.value + "%");
+        markAsCustom();
+        applyConfigToLoadedPlan();
+    });
+
+    // Solver time slider
+    $("#solverTimeSlider").on("input", function() {
+        currentConfig.solverTime = parseInt(this.value);
+        $("#solverTimeValue").text(formatSolverTime(this.value));
+        markAsCustom();
+        applyConfigToLoadedPlan();
+    });
+}
+
+// =============================================================================
+// Configuration UI Updates
+// =============================================================================
+
+function updateConfigSliders() {
+    $("#targetStocksSlider").val(currentConfig.targetStocks);
+    $("#targetStocksValue").text(currentConfig.targetStocks);
+
+    $("#maxSectorSlider").val(currentConfig.maxSector);
+    $("#maxSectorValue").text(currentConfig.maxSector + "%");
+
+    $("#solverTimeSlider").val(currentConfig.solverTime);
+    $("#solverTimeValue").text(formatSolverTime(currentConfig.solverTime));
+}
+
+function formatSolverTime(seconds) {
+    if (seconds >= 60) {
+        const mins = Math.floor(seconds / 60);
+        const secs = seconds % 60;
+        return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`;
+    }
+    return `${seconds}s`;
+}
+
+function markAsCustom() {
+    // Check if current settings match any preset
+    for (const [name, preset] of Object.entries(PRESETS)) {
+        if (preset.targetStocks === currentConfig.targetStocks &&
+            preset.maxSector === currentConfig.maxSector &&
+            preset.solverTime === currentConfig.solverTime) {
+            $("#presetSelector").val(name);
+            updatePresetDescription(name);
+            return;
+        }
+    }
+    // No match - mark as custom
+    $("#presetSelector").val("custom");
+    updatePresetDescription("custom");
+}
+
+function updatePresetDescription(preset) {
+    const descriptions = {
+        conservative: PRESETS.conservative.description,
+        balanced: PRESETS.balanced.description,
+        aggressive: PRESETS.aggressive.description,
+        quick: PRESETS.quick.description,
+        custom: "Custom configuration. Adjust sliders to your needs."
+    };
+    $("#presetDescription").text(descriptions[preset] || descriptions.custom);
+}
+
+// =============================================================================
+// Apply Configuration to Plan
+// =============================================================================
+
+/**
+ * Apply current configuration to the loaded plan.
+ * This updates the plan object that will be sent to the solver.
+ */
+function applyConfigToLoadedPlan() {
+    // loadedPlan is defined in app.js
+    if (typeof loadedPlan !== 'undefined' && loadedPlan) {
+        loadedPlan.targetPositionCount = currentConfig.targetStocks;
+        loadedPlan.maxSectorPercentage = currentConfig.maxSector / 100;
+        loadedPlan.solverConfig = {
+            terminationSeconds: currentConfig.solverTime
+        };
+    }
+}
+
+/**
+ * Get the current configuration.
+ * @returns {Object} Current configuration with targetStocks, maxSector, solverTime
+ */
+function getCurrentConfig() {
+    return { ...currentConfig };
+}
+
+/**
+ * Get target stock count from current configuration.
+ * Used by app.js for KPI display.
+ */
+function getTargetStockCount() {
+    return currentConfig.targetStocks;
+}
+
+// Export for use in app.js
+window.PRESETS = PRESETS;
+window.currentConfig = currentConfig;
+window.initAdvancedConfig = initAdvancedConfig;
+window.applyConfigToLoadedPlan = applyConfigToLoadedPlan;
+window.getCurrentConfig = getCurrentConfig;
+window.getTargetStockCount = getTargetStockCount;

static/index.html

@@ -0,0 +1,672 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+  <title>Portfolio Optimization - SolverForge for Python</title>
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.3/css/bootstrap.min.css">
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css">
+  <link rel="stylesheet" href="/webjars/solverforge/css/solverforge-webui.css">
+  <link rel="icon" href="/webjars/solverforge/img/solverforge-favicon.svg" type="image/svg+xml">
+  <style>
+    /* Solving spinner */
+    #solvingSpinner {
+      display: none;
+      width: 1.25rem;
+      height: 1.25rem;
+      border: 2px solid #10b981;
+      border-top-color: transparent;
+      border-radius: 50%;
+      animation: spin 0.75s linear infinite;
+      vertical-align: middle;
+    }
+    #solvingSpinner.active {
+      display: inline-block;
+    }
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    /* Sector badge colors */
+    .sector-badge {
+      font-size: 0.75rem;
+      padding: 4px 10px;
+      border-radius: 12px;
+      font-weight: 500;
+    }
+    .sector-Technology { background: #3b82f6; color: white; }
+    .sector-Healthcare { background: #10b981; color: white; }
+    .sector-Finance { background: #eab308; color: #1a1a1a; }
+    .sector-Energy { background: #ef4444; color: white; }
+    .sector-Consumer { background: #a855f7; color: white; }
+
+    /* KPI Cards */
+    .kpi-card {
+      background: white;
+      border-radius: 12px;
+      padding: 1.5rem;
+      text-align: center;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+      transition: transform 0.2s ease, box-shadow 0.2s ease;
+    }
+    .kpi-card:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    }
+    .kpi-value {
+      font-size: 2.5rem;
+      font-weight: 700;
+      color: #10b981;
+      line-height: 1.2;
+      transition: all 0.3s ease;
+    }
+    .kpi-value.updating {
+      opacity: 0.5;
+    }
+    .kpi-value.positive { color: #10b981; }
+    .kpi-value.negative { color: #ef4444; }
+    .kpi-label {
+      font-size: 0.85rem;
+      color: #64748b;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      margin-top: 0.5rem;
+    }
+    .kpi-icon {
+      font-size: 1.5rem;
+      color: #94a3b8;
+      margin-bottom: 0.5rem;
+    }
+
+    /* Chart containers */
+    .chart-card {
+      background: white;
+      border-radius: 12px;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+      height: 100%;
+    }
+    .chart-card-header {
+      padding: 1rem 1.25rem;
+      border-bottom: 1px solid #e2e8f0;
+      font-weight: 600;
+      color: #1e293b;
+    }
+    .chart-card-body {
+      padding: 1rem;
+    }
+    .chart-container {
+      position: relative;
+      height: 280px;
+    }
+
+    /* Stock table */
+    .stock-table {
+      font-size: 0.9rem;
+    }
+    .stock-table th {
+      background: #f8fafc;
+      font-weight: 600;
+      text-transform: uppercase;
+      font-size: 0.75rem;
+      letter-spacing: 0.05em;
+      color: #64748b;
+      border-bottom: 2px solid #e2e8f0;
+      cursor: pointer;
+      user-select: none;
+    }
+    .stock-table th:hover {
+      background: #f1f5f9;
+    }
+    .stock-table th i {
+      margin-left: 4px;
+      opacity: 0.5;
+    }
+    .stock-table th.sorted i {
+      opacity: 1;
+      color: #10b981;
+    }
+    .stock-selected {
+      background: #f0fdf4 !important;
+    }
+    .stock-table tr {
+      transition: background-color 0.15s ease;
+    }
+    .stock-table tbody tr:hover {
+      background: #f8fafc;
+    }
+    .return-positive { color: #10b981; font-weight: 600; }
+    .return-negative { color: #ef4444; font-weight: 600; }
+
+    /* Score display */
+    .score-badge {
+      display: inline-block;
+      padding: 6px 12px;
+      border-radius: 8px;
+      font-weight: 600;
+      font-size: 0.9rem;
+    }
+    .score-hard {
+      background: #fef2f2;
+      color: #dc2626;
+      border: 1px solid #fecaca;
+    }
+    .score-soft {
+      background: #f0fdf4;
+      color: #16a34a;
+      border: 1px solid #bbf7d0;
+    }
+    .score-feasible {
+      background: #f0fdf4;
+      color: #16a34a;
+    }
+    .score-infeasible {
+      background: #fef2f2;
+      color: #dc2626;
+    }
+
+    /* Data selector dropdown */
+    .data-selector {
+      background: #10b981;
+      color: white;
+      border: none;
+      border-radius: 1.5rem;
+      padding: 0.5rem 1rem;
+      font-weight: 500;
+    }
+    .data-selector:focus {
+      box-shadow: 0 0 0 3px rgba(16, 185, 129, 0.3);
+    }
+
+    /* Notification panel */
+    #notificationPanel {
+      z-index: 1050;
+    }
+
+    /* Copy button for code blocks */
+    .copy-btn {
+      position: absolute;
+      top: 0.5rem;
+      right: 0.5rem;
+      opacity: 0;
+      transition: opacity 0.2s;
+    }
+    .code-block:hover .copy-btn {
+      opacity: 1;
+    }
+    .code-block {
+      position: relative;
+    }
+
+    /* Progress animation during solving */
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.6; }
+    }
+    .solving-pulse {
+      animation: pulse 1.5s ease-in-out infinite;
+    }
+
+    /* ==========================================================
+       ADVANCED SETTINGS STYLES (OPTIONAL)
+       Remove this section for a simpler quickstart.
+       ========================================================== */
+    .settings-card {
+      background: white;
+      border-radius: 12px;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+    .settings-card .card-body {
+      padding: 1.25rem;
+    }
+    .form-range::-webkit-slider-thumb {
+      background: #10b981;
+    }
+    .form-range::-moz-range-thumb {
+      background: #10b981;
+    }
+    .preset-badge {
+      font-size: 0.7rem;
+      padding: 2px 6px;
+      border-radius: 4px;
+      background: #f1f5f9;
+      color: #64748b;
+      margin-left: 0.5rem;
+    }
+    .config-value {
+      font-weight: 600;
+      color: #10b981;
+    }
+    /* END ADVANCED SETTINGS STYLES */
+  </style>
+</head>
+<body>
+
+<header id="solverforge-auto-header">
+  <!-- Filled by solverforge-webui.js -->
+</header>
+
+<div class="tab-content">
+  <!-- Tab 1: Demo UI -->
+  <div id="demo" class="tab-pane fade show active container-fluid">
+    <div class="sticky-top d-flex justify-content-center align-items-center">
+      <div id="notificationPanel" style="position: absolute; top: .5rem;"></div>
+    </div>
+
+    <h1>Portfolio Optimization</h1>
+    <p>Select optimal stocks to maximize expected returns while meeting sector exposure constraints.</p>
+
+    <!-- Control Bar -->
+    <div class="container-fluid mb-3">
+      <div class="row justify-content-between align-items-center">
+        <div class="col-auto">
+          <ul class="nav nav-pills" role="tablist">
+            <li class="nav-item" role="presentation">
+              <button class="nav-link active" id="portfolioTab" data-bs-toggle="tab" data-bs-target="#portfolioPanel"
+                      type="button" role="tab" aria-controls="portfolioPanel" aria-selected="true">
+                <i class="fas fa-chart-pie me-1"></i> Portfolio
+              </button>
+            </li>
+            <li class="nav-item" role="presentation">
+              <button class="nav-link" id="stocksTab" data-bs-toggle="tab" data-bs-target="#stocksPanel"
+                      type="button" role="tab" aria-controls="stocksPanel" aria-selected="false">
+                <i class="fas fa-list me-1"></i> All Stocks
+              </button>
+            </li>
+          </ul>
+        </div>
+        <div class="col-auto">
+          <select id="dataSelector" class="data-selector me-2">
+            <option value="SMALL">Small (25 stocks)</option>
+            <option value="LARGE">Large (51 stocks)</option>
+          </select>
+          <!-- ============================================================
+               ADVANCED SETTINGS BUTTON (OPTIONAL)
+               Remove this button and the panel below for a simpler quickstart.
+               Also remove config.js script at the bottom of the file.
+               ============================================================ -->
+          <button class="btn btn-outline-secondary btn-sm me-2" type="button"
+                  data-bs-toggle="collapse" data-bs-target="#advancedSettings"
+                  aria-expanded="false" aria-controls="advancedSettings"
+                  id="advancedSettingsBtn">
+            <i class="fas fa-cog"></i> Advanced
+          </button>
+          <!-- END ADVANCED SETTINGS BUTTON -->
+          <button id="solveButton" type="button" class="btn btn-success">
+            <i class="fas fa-play"></i> Solve
+          </button>
+          <button id="stopSolvingButton" type="button" class="btn btn-danger" style="display: none;">
+            <i class="fas fa-stop"></i> Stop
+          </button>
+          <span id="solvingSpinner" class="ms-2"></span>
+          <span id="score" class="ms-2 fw-bold">Score: ?</span>
+          <button id="analyzeButton" type="button" class="btn btn-secondary ms-2" title="Analyze constraints">
+            <i class="fas fa-question"></i>
+          </button>
+        </div>
+      </div>
+
+      <!-- ============================================================
+           ADVANCED SETTINGS PANEL (OPTIONAL)
+           This entire panel can be removed for a simpler quickstart.
+           If removed, also remove:
+           - The "Advanced" button above
+           - config.js script at the bottom of the file
+           ============================================================ -->
+      <div class="collapse mt-3" id="advancedSettings">
+        <div class="settings-card">
+          <div class="card-body">
+            <div class="row g-4">
+              <!-- Preset Selector -->
+              <div class="col-md-3">
+                <label class="form-label fw-bold">
+                  <i class="fas fa-sliders-h me-1 text-muted"></i>Preset
+                </label>
+                <select id="presetSelector" class="form-select">
+                  <option value="balanced" selected>Balanced (Default)</option>
+                  <option value="conservative">Conservative</option>
+                  <option value="aggressive">Aggressive</option>
+                  <option value="quick">Quick Test</option>
+                  <option value="custom">Custom</option>
+                </select>
+              </div>
+
+              <!-- Target Stocks Slider -->
+              <div class="col-md-3">
+                <label class="form-label">
+                  Target Stocks: <span id="targetStocksValue" class="config-value">20</span>
+                </label>
+                <input type="range" class="form-range" id="targetStocksSlider"
+                       min="5" max="50" value="20">
+                <div class="d-flex justify-content-between text-muted" style="font-size: 0.7rem;">
+                  <span>5</span>
+                  <span>50</span>
+                </div>
+              </div>
+
+              <!-- Max Sector Slider -->
+              <div class="col-md-3">
+                <label class="form-label">
+                  Max Sector: <span id="maxSectorValue" class="config-value">25%</span>
+                </label>
+                <input type="range" class="form-range" id="maxSectorSlider"
+                       min="10" max="50" value="25">
+                <div class="d-flex justify-content-between text-muted" style="font-size: 0.7rem;">
+                  <span>10%</span>
+                  <span>50%</span>
+                </div>
+              </div>
+
+              <!-- Solver Time Slider -->
+              <div class="col-md-3">
+                <label class="form-label">
+                  Solver Time: <span id="solverTimeValue" class="config-value">30s</span>
+                </label>
+                <input type="range" class="form-range" id="solverTimeSlider"
+                       min="10" max="300" step="10" value="30">
+                <div class="d-flex justify-content-between text-muted" style="font-size: 0.7rem;">
+                  <span>10s</span>
+                  <span>5min</span>
+                </div>
+              </div>
+            </div>
+
+            <!-- Preset Description -->
+            <div class="mt-3 text-muted" style="font-size: 0.85rem;">
+              <i class="fas fa-info-circle me-1"></i>
+              <span id="presetDescription">Balanced settings for typical portfolio optimization.</span>
+            </div>
+          </div>
+        </div>
+      </div>
+      <!-- END ADVANCED SETTINGS PANEL -->
+    </div>
+
+    <!-- Inner tab content -->
+    <div class="tab-content">
+      <!-- Portfolio View -->
+      <div class="tab-pane fade show active" id="portfolioPanel" role="tabpanel" aria-labelledby="portfolioTab">
+        <!-- KPI Row 1: Core Metrics -->
+        <div class="row mb-3 g-3">
+          <div class="col-md-3 col-sm-6">
+            <div class="kpi-card">
+              <div class="kpi-icon"><i class="fas fa-check-circle"></i></div>
+              <div class="kpi-value" id="selectedCount">0/20</div>
+              <div class="kpi-label">Selected Stocks</div>
+            </div>
+          </div>
+          <div class="col-md-3 col-sm-6">
+            <div class="kpi-card">
+              <div class="kpi-icon"><i class="fas fa-chart-line"></i></div>
+              <div class="kpi-value positive" id="expectedReturn">0.00%</div>
+              <div class="kpi-label">Expected Return</div>
+            </div>
+          </div>
+          <div class="col-md-3 col-sm-6">
+            <div class="kpi-card">
+              <div class="kpi-icon"><i class="fas fa-layer-group"></i></div>
+              <div class="kpi-value" id="sectorCount">0</div>
+              <div class="kpi-label">Sectors</div>
+            </div>
+          </div>
+          <div class="col-md-3 col-sm-6">
+            <div class="kpi-card" id="diversificationTooltip" data-bs-toggle="tooltip" title="Higher = more diversified. Based on Herfindahl-Hirschman Index (HHI).">
+              <div class="kpi-icon"><i class="fas fa-shuffle"></i></div>
+              <div class="kpi-value" id="diversificationScore">0%</div>
+              <div class="kpi-label">Diversification <i class="fas fa-info-circle text-muted" style="font-size: 0.7rem;"></i></div>
+            </div>
+          </div>
+        </div>
+
+        <!-- KPI Row 2: Risk Metrics -->
+        <div class="row mb-4 g-3">
+          <div class="col-md-3 col-sm-6">
+            <div class="kpi-card" data-bs-toggle="tooltip" title="Highest single sector weight. Lower is more diversified.">
+              <div class="kpi-icon"><i class="fas fa-chart-pie"></i></div>
+              <div class="kpi-value" id="maxSectorExposure">0%</div>
+              <div class="kpi-label">Max Sector <i class="fas fa-info-circle text-muted" style="font-size: 0.7rem;"></i></div>
+            </div>
+          </div>
+          <div class="col-md-3 col-sm-6">
+            <div class="kpi-card" data-bs-toggle="tooltip" title="Standard deviation of predicted returns. Lower = less risk.">
+              <div class="kpi-icon"><i class="fas fa-wave-square"></i></div>
+              <div class="kpi-value" id="returnVolatility">0.00%</div>
+              <div class="kpi-label">Volatility <i class="fas fa-info-circle text-muted" style="font-size: 0.7rem;"></i></div>
+            </div>
+          </div>
+          <div class="col-md-3 col-sm-6">
+            <div class="kpi-card" data-bs-toggle="tooltip" title="Return / Volatility ratio. Higher = better risk-adjusted return.">
+              <div class="kpi-icon"><i class="fas fa-scale-balanced"></i></div>
+              <div class="kpi-value" id="sharpeProxy">0.00</div>
+              <div class="kpi-label">Sharpe Proxy <i class="fas fa-info-circle text-muted" style="font-size: 0.7rem;"></i></div>
+            </div>
+          </div>
+          <div class="col-md-3 col-sm-6">
+            <div class="kpi-card" data-bs-toggle="tooltip" title="Herfindahl-Hirschman Index. Lower = more diversified. <0.15 is well-diversified.">
+              <div class="kpi-icon"><i class="fas fa-bullseye"></i></div>
+              <div class="kpi-value" id="herfindahlIndex">0.000</div>
+              <div class="kpi-label">HHI <i class="fas fa-info-circle text-muted" style="font-size: 0.7rem;"></i></div>
+            </div>
+          </div>
+        </div>
+
+        <!-- Charts Row -->
+        <div class="row mb-4 g-3">
+          <div class="col-md-6">
+            <div class="chart-card">
+              <div class="chart-card-header">
+                <i class="fas fa-chart-pie me-2 text-muted"></i>Sector Allocation
+              </div>
+              <div class="chart-card-body">
+                <div class="chart-container">
+                  <canvas id="sectorChart"></canvas>
+                </div>
+              </div>
+            </div>
+          </div>
+          <div class="col-md-6">
+            <div class="chart-card">
+              <div class="chart-card-header">
+                <i class="fas fa-chart-bar me-2 text-muted"></i>Top Returns (Selected)
+              </div>
+              <div class="chart-card-body">
+                <div class="chart-container">
+                  <canvas id="returnsChart"></canvas>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <!-- Selected Stocks Summary -->
+        <div class="row">
+          <div class="col-12">
+            <div class="chart-card">
+              <div class="chart-card-header d-flex justify-content-between align-items-center">
+                <span><i class="fas fa-star me-2 text-warning"></i>Selected Stocks</span>
+                <span class="badge bg-success" id="selectedBadge">0 selected</span>
+              </div>
+              <div class="chart-card-body p-0">
+                <div class="table-responsive">
+                  <table class="table table-hover stock-table mb-0">
+                    <thead>
+                      <tr>
+                        <th>Ticker</th>
+                        <th>Company</th>
+                        <th>Sector</th>
+                        <th>Predicted Return</th>
+                        <th>Weight</th>
+                      </tr>
+                    </thead>
+                    <tbody id="selectedStocksTable">
+                      <tr>
+                        <td colspan="5" class="text-center text-muted py-4">
+                          <i class="fas fa-info-circle me-2"></i>Click "Solve" to optimize your portfolio
+                        </td>
+                      </tr>
+                    </tbody>
+                  </table>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <!-- All Stocks View -->
+      <div class="tab-pane fade" id="stocksPanel" role="tabpanel" aria-labelledby="stocksTab">
+        <div class="chart-card">
+          <div class="chart-card-header d-flex justify-content-between align-items-center">
+            <span><i class="fas fa-list me-2 text-muted"></i>All Available Stocks</span>
+            <div class="d-flex align-items-center gap-3">
+              <div class="form-check form-switch mb-0">
+                <input class="form-check-input" type="checkbox" id="showSelectedOnly">
+                <label class="form-check-label" for="showSelectedOnly">Selected only</label>
+              </div>
+              <span class="badge bg-secondary" id="stockCountBadge">0 stocks</span>
+            </div>
+          </div>
+          <div class="chart-card-body p-0">
+            <div class="table-responsive" style="max-height: 70vh; overflow-y: auto;">
+              <table class="table table-hover stock-table mb-0">
+                <thead class="sticky-top">
+                  <tr>
+                    <th data-sort="selected">Selected <i class="fas fa-sort"></i></th>
+                    <th data-sort="stockId">Ticker <i class="fas fa-sort"></i></th>
+                    <th data-sort="stockName">Company <i class="fas fa-sort"></i></th>
+                    <th data-sort="sector">Sector <i class="fas fa-sort"></i></th>
+                    <th data-sort="predictedReturn">Predicted Return <i class="fas fa-sort"></i></th>
+                    <th>Weight</th>
+                  </tr>
+                </thead>
+                <tbody id="allStocksTable">
+                  <tr>
+                    <td colspan="6" class="text-center text-muted py-4">
+                      <i class="fas fa-database me-2"></i>Loading stock data...
+                    </td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Tab 2: REST API Guide -->
+  <div id="rest" class="tab-pane fade container-fluid">
+    <h2>REST API Guide</h2>
+    <p class="text-muted">Use these endpoints to integrate portfolio optimization into your application.</p>
+
+    <h3 class="mt-4">1. Load demo data</h3>
+    <p>Retrieve a pre-configured portfolio with sample stocks.</p>
+    <div class="code-block">
+      <button class="btn btn-outline-dark btn-sm copy-btn" onclick="copyCode(this)">
+        <i class="fas fa-copy"></i> Copy
+      </button>
+      <pre><code>curl -X GET http://localhost:8080/demo-data/SMALL</code></pre>
+    </div>
+
+    <h3 class="mt-4">2. Submit portfolio for optimization</h3>
+    <p>Start the solver to find the optimal stock selection.</p>
+    <div class="code-block">
+      <button class="btn btn-outline-dark btn-sm copy-btn" onclick="copyCode(this)">
+        <i class="fas fa-copy"></i> Copy
+      </button>
+      <pre><code>curl -X POST -H "Content-Type: application/json" \
+  -d @portfolio.json \
+  http://localhost:8080/portfolios</code></pre>
+    </div>
+
+    <h3 class="mt-4">3. Get current solution</h3>
+    <p>Poll for the latest solution while the solver is running.</p>
+    <div class="code-block">
+      <button class="btn btn-outline-dark btn-sm copy-btn" onclick="copyCode(this)">
+        <i class="fas fa-copy"></i> Copy
+      </button>
+      <pre><code>curl -X GET http://localhost:8080/portfolios/{jobId}</code></pre>
+    </div>
+
+    <h3 class="mt-4">4. Stop solving</h3>
+    <p>Terminate the solver and retrieve the best solution found.</p>
+    <div class="code-block">
+      <button class="btn btn-outline-dark btn-sm copy-btn" onclick="copyCode(this)">
+        <i class="fas fa-copy"></i> Copy
+      </button>
+      <pre><code>curl -X DELETE http://localhost:8080/portfolios/{jobId}</code></pre>
+    </div>
+
+    <h3 class="mt-4">5. Analyze constraints</h3>
+    <p>Get a detailed breakdown of constraint scores for a given solution.</p>
+    <div class="code-block">
+      <button class="btn btn-outline-dark btn-sm copy-btn" onclick="copyCode(this)">
+        <i class="fas fa-copy"></i> Copy
+      </button>
+      <pre><code>curl -X PUT -H "Content-Type: application/json" \
+  -d @portfolio.json \
+  http://localhost:8080/portfolios/analyze</code></pre>
+    </div>
+  </div>
+
+  <!-- Tab 3: OpenAPI Reference -->
+  <div id="openapi" class="tab-pane fade container-fluid">
+    <h2>OpenAPI Reference</h2>
+    <p class="text-muted mb-4">Interactive API documentation powered by Swagger UI.</p>
+    <div class="ratio ratio-1x1">
+      <iframe src="/q/swagger-ui" title="OpenAPI Documentation"></iframe>
+    </div>
+  </div>
+</div>
+
+<!-- Score Analysis Modal -->
+<div class="modal fade" id="weightModal" tabindex="-1" aria-labelledby="weightModalTitle" aria-hidden="true">
+  <div class="modal-dialog modal-lg modal-dialog-scrollable">
+    <div class="modal-content">
+      <div class="modal-header">
+        <h5 class="modal-title" id="weightModalTitle">Constraint Analysis</h5>
+        <span id="weightModalLabel" class="ms-2 badge bg-secondary"></span>
+        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+      </div>
+      <div class="modal-body">
+        <table class="table table-striped" id="weightModalContent">
+          <thead>
+            <tr>
+              <th></th>
+              <th>Constraint</th>
+              <th>Type</th>
+              <th>Weight</th>
+              <th>Matches</th>
+              <th>Score</th>
+            </tr>
+          </thead>
+          <tbody>
+            <!-- Populated by JavaScript -->
+          </tbody>
+        </table>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<footer id="solverforge-auto-footer">
+  <!-- Filled by solverforge-webui.js -->
+</footer>
+
+<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.3/js/bootstrap.bundle.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script>
+<script src="/webjars/solverforge/js/solverforge-webui.js"></script>
+<script src="app.js"></script>
+<!-- ============================================================
+     ADVANCED CONFIGURATION SCRIPT (OPTIONAL)
+     Remove this script for a simpler quickstart.
+     Also remove the "Advanced" button and panel in the HTML above.
+     ============================================================ -->
+<script src="config.js"></script>
+<!-- END ADVANCED CONFIGURATION SCRIPT -->
+</body>
+</html>

static/webjars/solverforge/css/solverforge-webui.css

@@ -0,0 +1,68 @@
+:root {
+    /* Keep in sync with .navbar height on a large screen. */
+    --ts-navbar-height: 109px;
+
+    --ts-green-1-rgb: #10b981;
+    --ts-green-2-rgb: #059669;
+    --ts-violet-1-rgb: #3E00FF;
+    --ts-violet-2-rgb: #3423A6;
+    --ts-violet-3-rgb: #2E1760;
+    --ts-violet-4-rgb: #200F4F;
+    --ts-violet-5-rgb: #000000; /* TODO FIXME */
+    --ts-violet-dark-1-rgb: #b6adfd;
+    --ts-violet-dark-2-rgb: #c1bbfd;
+    --ts-gray-rgb: #666666;
+    --ts-white-rgb: #FFFFFF;
+    --ts-light-rgb: #F2F2F2;
+    --ts-gray-border: #c5c5c5;
+
+    --tf-light-rgb-transparent: rgb(242,242,242,0.5); /* #F2F2F2 = rgb(242,242,242) */
+    --bs-body-bg: var(--ts-light-rgb); /* link to html bg */
+    --bs-link-color: var(--ts-violet-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-2-rgb);
+
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+    --bs-nav-link-font-size: 18px;
+    --bs-nav-link-font-weight: 400;
+    --bs-nav-link-color: var(--ts-white-rgb);
+    --ts-nav-link-hover-border-color: var(--ts-violet-1-rgb);
+}
+.btn {
+    --bs-btn-border-radius: 1.5rem;
+}
+.btn-primary {
+    --bs-btn-bg: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-2-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-2-rgb);
+    --bs-btn-active-bg: var(--ts-violet-2-rgb);
+    --bs-btn-active-border-bg: var(--ts-violet-2-rgb);
+    --bs-btn-disabled-bg: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.btn-outline-primary {
+    --bs-btn-color: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-1-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-active-bg: var(--ts-violet-1-rgb);
+    --bs-btn-active-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.navbar-dark {
+    --bs-link-color: var(--ts-violet-dark-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-dark-2-rgb);
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+}
+.nav-pills {
+    --bs-nav-pills-link-active-bg: var(--ts-green-1-rgb);
+}
+.nav-pills .nav-link:hover {
+    color: var(--ts-green-1-rgb);
+}
+.nav-pills .nav-link.active:hover {
+    color: var(--ts-white-rgb);
+}

static/webjars/solverforge/js/solverforge-webui.js

@@ -0,0 +1,142 @@
+function replaceSolverForgeAutoHeaderFooter() {
+  const solverforgeHeader = $("header#solverforge-auto-header");
+  if (solverforgeHeader != null) {
+    solverforgeHeader.addClass("bg-black")
+    solverforgeHeader.append(
+      $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg navbar-dark shadow mb-3">
+          <a class="navbar-brand" href="https://www.solverforge.org">
+            <img src="/solverforge/img/solverforge-horizontal-white.svg" alt="SolverForge logo" width="200">
+          </a>
+        </nav>
+      </div>`));
+  }
+  const solverforgeFooter = $("footer#solverforge-auto-footer");
+  if (solverforgeFooter != null) {
+    solverforgeFooter.append(
+      $(`<footer class="bg-black text-white-50">
+           <div class="container">
+             <div class="hstack gap-3 p-4">
+               <div class="ms-auto"><a class="text-white" href="https://www.solverforge.org">SolverForge</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://www.solverforge.org/docs">Documentation</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://github.com/SolverForge/solverforge-legacy">Code</a></div>
+               <div class="vr"></div>
+               <div class="me-auto"><a class="text-white" href="mailto:info@solverforge.org">Support</a></div>
+             </div>
+           </div>
+           <div id="applicationInfo" class="container text-center"></div>
+         </footer>`));
+
+      applicationInfo();
+  }
+
+}
+
+function showSimpleError(title) {
+    const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+        .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+        .append($(`<div class="toast-body"/>`)
+            .append($(`<p/>`).text(title))
+        );
+    $("#notificationPanel").append(notification);
+    notification.toast({delay: 30000});
+    notification.toast('show');
+}
+
+function showError(title, xhr) {
+  var serverErrorMessage = !xhr.responseJSON ? `${xhr.status}: ${xhr.statusText}` : xhr.responseJSON.message;
+  var serverErrorCode = !xhr.responseJSON ? `unknown` : xhr.responseJSON.code;
+  var serverErrorId = !xhr.responseJSON ? `----` : xhr.responseJSON.id;
+  var serverErrorDetails = !xhr.responseJSON ? `no details provided` : xhr.responseJSON.details;
+
+  if (xhr.responseJSON && !serverErrorMessage) {
+	  serverErrorMessage = JSON.stringify(xhr.responseJSON);
+	  serverErrorCode = xhr.statusText + '(' + xhr.status + ')';
+	  serverErrorId = `----`;
+  }
+
+  console.error(title + "\n" + serverErrorMessage + " : " + serverErrorDetails);
+  const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+    .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+    .append($(`<div class="toast-body"/>`)
+      .append($(`<p/>`).text(title))
+      .append($(`<pre/>`)
+        .append($(`<code/>`).text(serverErrorMessage + "\n\nCode: " + serverErrorCode + "\nError id: " + serverErrorId))
+      )
+    );
+  $("#notificationPanel").append(notification);
+  notification.toast({delay: 30000});
+  notification.toast('show');
+}
+
+// ****************************************************************************
+// Application info
+// ****************************************************************************
+
+function applicationInfo() {
+  $.getJSON("info", function (info) {
+       $("#applicationInfo").append("<small>" + info.application + " (version: " + info.version + ", built at: " + info.built + ")</small>");
+   }).fail(function (xhr, ajaxOptions, thrownError) {
+       console.warn("Unable to collect application information");
+   });
+}
+
+// ****************************************************************************
+// TangoColorFactory
+// ****************************************************************************
+
+const SEQUENCE_1 = [0x8AE234, 0xFCE94F, 0x729FCF, 0xE9B96E, 0xAD7FA8];
+const SEQUENCE_2 = [0x73D216, 0xEDD400, 0x3465A4, 0xC17D11, 0x75507B];
+
+var colorMap = new Map;
+var nextColorCount = 0;
+
+function pickColor(object) {
+  let color = colorMap[object];
+  if (color !== undefined) {
+    return color;
+  }
+  color = nextColor();
+  colorMap[object] = color;
+  return color;
+}
+
+function nextColor() {
+  let color;
+  let colorIndex = nextColorCount % SEQUENCE_1.length;
+  let shadeIndex = Math.floor(nextColorCount / SEQUENCE_1.length);
+  if (shadeIndex === 0) {
+    color = SEQUENCE_1[colorIndex];
+  } else if (shadeIndex === 1) {
+    color = SEQUENCE_2[colorIndex];
+  } else {
+    shadeIndex -= 3;
+    let floorColor = SEQUENCE_2[colorIndex];
+    let ceilColor = SEQUENCE_1[colorIndex];
+    let base = Math.floor((shadeIndex / 2) + 1);
+    let divisor = 2;
+    while (base >= divisor) {
+      divisor *= 2;
+    }
+    base = (base * 2) - divisor + 1;
+    let shadePercentage = base / divisor;
+    color = buildPercentageColor(floorColor, ceilColor, shadePercentage);
+  }
+  nextColorCount++;
+  return "#" + color.toString(16);
+}
+
+function buildPercentageColor(floorColor, ceilColor, shadePercentage) {
+  let red = (floorColor & 0xFF0000) + Math.floor(shadePercentage * ((ceilColor & 0xFF0000) - (floorColor & 0xFF0000))) & 0xFF0000;
+  let green = (floorColor & 0x00FF00) + Math.floor(shadePercentage * ((ceilColor & 0x00FF00) - (floorColor & 0x00FF00))) & 0x00FF00;
+  let blue = (floorColor & 0x0000FF) + Math.floor(shadePercentage * ((ceilColor & 0x0000FF) - (floorColor & 0x0000FF))) & 0x0000FF;
+  return red | green | blue;
+}

tests/test_business_metrics.py

@@ -0,0 +1,352 @@
+"""
+Tests for business metrics in the Portfolio Optimization quickstart.
+
+These tests verify the financial KPIs calculated by the domain model:
+- Herfindahl-Hirschman Index (HHI) for concentration
+- Diversification score (1 - HHI)
+- Max sector exposure
+- Expected return
+- Return volatility
+- Sharpe proxy (return / volatility)
+
+These metrics provide business insight beyond the solver score.
+"""
+import pytest
+import math
+
+from portfolio_optimization.domain import (
+    StockSelection,
+    PortfolioOptimizationPlan,
+    PortfolioConfig,
+    PortfolioMetricsModel,
+    SELECTED,
+    NOT_SELECTED,
+)
+from portfolio_optimization.converters import plan_to_metrics
+
+
+def create_stock(
+    stock_id: str,
+    sector: str = "Technology",
+    predicted_return: float = 0.10,
+    selected: bool = True
+) -> StockSelection:
+    """Create a test stock with sensible defaults."""
+    return StockSelection(
+        stock_id=stock_id,
+        stock_name=f"{stock_id} Corp",
+        sector=sector,
+        predicted_return=predicted_return,
+        selection=SELECTED if selected else NOT_SELECTED,
+    )
+
+
+def create_plan(stocks: list[StockSelection]) -> PortfolioOptimizationPlan:
+    """Create a test plan with given stocks."""
+    return PortfolioOptimizationPlan(
+        stocks=stocks,
+        target_position_count=20,
+        max_sector_percentage=0.25,
+        portfolio_config=PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=10000),
+    )
+
+
+class TestHerfindahlIndex:
+    """Tests for the Herfindahl-Hirschman Index (HHI) calculation."""
+
+    def test_single_sector_hhi_is_one(self) -> None:
+        """All stocks in one sector should have HHI = 1.0 (max concentration)."""
+        stocks = [create_stock(f"STK{i}", sector="Technology") for i in range(5)]
+        plan = create_plan(stocks)
+
+        # All in one sector: HHI = 1.0^2 = 1.0
+        assert plan.get_herfindahl_index() == 1.0
+
+    def test_two_equal_sectors_hhi(self) -> None:
+        """Two sectors with equal stocks should have HHI = 0.5."""
+        stocks = [
+            *[create_stock(f"TECH{i}", sector="Technology") for i in range(5)],
+            *[create_stock(f"HLTH{i}", sector="Healthcare") for i in range(5)],
+        ]
+        plan = create_plan(stocks)
+
+        # 50% in each sector: HHI = 0.5^2 + 0.5^2 = 0.5
+        assert abs(plan.get_herfindahl_index() - 0.5) < 0.001
+
+    def test_four_equal_sectors_hhi(self) -> None:
+        """Four sectors with equal stocks should have HHI = 0.25."""
+        stocks = [
+            *[create_stock(f"TECH{i}", sector="Technology") for i in range(5)],
+            *[create_stock(f"HLTH{i}", sector="Healthcare") for i in range(5)],
+            *[create_stock(f"FIN{i}", sector="Finance") for i in range(5)],
+            *[create_stock(f"NRG{i}", sector="Energy") for i in range(5)],
+        ]
+        plan = create_plan(stocks)
+
+        # 25% in each sector: HHI = 4 * 0.25^2 = 0.25
+        assert abs(plan.get_herfindahl_index() - 0.25) < 0.001
+
+    def test_empty_portfolio_hhi_is_zero(self) -> None:
+        """Empty portfolio should have HHI = 0."""
+        stocks = [create_stock(f"STK{i}", selected=False) for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_herfindahl_index() == 0.0
+
+    def test_unequal_sectors_hhi(self) -> None:
+        """Unequal sector distribution should give correct HHI."""
+        stocks = [
+            *[create_stock(f"TECH{i}", sector="Technology") for i in range(6)],  # 60%
+            *[create_stock(f"HLTH{i}", sector="Healthcare") for i in range(4)],  # 40%
+        ]
+        plan = create_plan(stocks)
+
+        # HHI = 0.6^2 + 0.4^2 = 0.36 + 0.16 = 0.52
+        assert abs(plan.get_herfindahl_index() - 0.52) < 0.001
+
+
+class TestDiversificationScore:
+    """Tests for the diversification score (1 - HHI)."""
+
+    def test_single_sector_diversification_is_zero(self) -> None:
+        """All stocks in one sector should have diversification = 0."""
+        stocks = [create_stock(f"STK{i}", sector="Technology") for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_diversification_score() == 0.0
+
+    def test_two_equal_sectors_diversification(self) -> None:
+        """Two equal sectors should have diversification = 0.5."""
+        stocks = [
+            *[create_stock(f"TECH{i}", sector="Technology") for i in range(5)],
+            *[create_stock(f"HLTH{i}", sector="Healthcare") for i in range(5)],
+        ]
+        plan = create_plan(stocks)
+
+        assert abs(plan.get_diversification_score() - 0.5) < 0.001
+
+    def test_four_equal_sectors_diversification(self) -> None:
+        """Four equal sectors should have diversification = 0.75."""
+        stocks = [
+            *[create_stock(f"TECH{i}", sector="Technology") for i in range(5)],
+            *[create_stock(f"HLTH{i}", sector="Healthcare") for i in range(5)],
+            *[create_stock(f"FIN{i}", sector="Finance") for i in range(5)],
+            *[create_stock(f"NRG{i}", sector="Energy") for i in range(5)],
+        ]
+        plan = create_plan(stocks)
+
+        # 1 - HHI = 1 - 0.25 = 0.75
+        assert abs(plan.get_diversification_score() - 0.75) < 0.001
+
+
+class TestMaxSectorExposure:
+    """Tests for max sector exposure calculation."""
+
+    def test_single_sector_max_exposure_is_one(self) -> None:
+        """All stocks in one sector should have max exposure = 1.0."""
+        stocks = [create_stock(f"STK{i}", sector="Technology") for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_max_sector_exposure() == 1.0
+
+    def test_two_equal_sectors_max_exposure(self) -> None:
+        """Two equal sectors should have max exposure = 0.5."""
+        stocks = [
+            *[create_stock(f"TECH{i}", sector="Technology") for i in range(5)],
+            *[create_stock(f"HLTH{i}", sector="Healthcare") for i in range(5)],
+        ]
+        plan = create_plan(stocks)
+
+        assert abs(plan.get_max_sector_exposure() - 0.5) < 0.001
+
+    def test_unequal_sectors_max_exposure(self) -> None:
+        """Unequal sectors should return the larger weight."""
+        stocks = [
+            *[create_stock(f"TECH{i}", sector="Technology") for i in range(7)],  # 70%
+            *[create_stock(f"HLTH{i}", sector="Healthcare") for i in range(3)],  # 30%
+        ]
+        plan = create_plan(stocks)
+
+        assert abs(plan.get_max_sector_exposure() - 0.7) < 0.001
+
+    def test_empty_portfolio_max_exposure_is_zero(self) -> None:
+        """Empty portfolio should have max exposure = 0."""
+        stocks = [create_stock(f"STK{i}", selected=False) for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_max_sector_exposure() == 0.0
+
+
+class TestSectorCount:
+    """Tests for sector count calculation."""
+
+    def test_single_sector(self) -> None:
+        """All stocks in one sector should return count = 1."""
+        stocks = [create_stock(f"STK{i}", sector="Technology") for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_sector_count() == 1
+
+    def test_multiple_sectors(self) -> None:
+        """Stocks in multiple sectors should return correct count."""
+        stocks = [
+            create_stock("TECH1", sector="Technology"),
+            create_stock("HLTH1", sector="Healthcare"),
+            create_stock("FIN1", sector="Finance"),
+            create_stock("NRG1", sector="Energy"),
+        ]
+        plan = create_plan(stocks)
+
+        assert plan.get_sector_count() == 4
+
+    def test_empty_portfolio_sector_count_is_zero(self) -> None:
+        """Empty portfolio should have sector count = 0."""
+        stocks = [create_stock(f"STK{i}", selected=False) for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_sector_count() == 0
+
+
+class TestExpectedReturn:
+    """Tests for expected return calculation."""
+
+    def test_uniform_returns(self) -> None:
+        """Stocks with same returns should give that return."""
+        stocks = [create_stock(f"STK{i}", predicted_return=0.10) for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert abs(plan.get_expected_return() - 0.10) < 0.001
+
+    def test_mixed_returns(self) -> None:
+        """Mixed returns should give weighted average."""
+        stocks = [
+            create_stock("STK1", predicted_return=0.10),  # 10%
+            create_stock("STK2", predicted_return=0.20),  # 20%
+        ]
+        plan = create_plan(stocks)
+
+        # Equal weight: (0.10 + 0.20) / 2 = 0.15
+        assert abs(plan.get_expected_return() - 0.15) < 0.001
+
+    def test_empty_portfolio_return_is_zero(self) -> None:
+        """Empty portfolio should have return = 0."""
+        stocks = [create_stock(f"STK{i}", selected=False) for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_expected_return() == 0.0
+
+
+class TestReturnVolatility:
+    """Tests for return volatility (std dev) calculation."""
+
+    def test_uniform_returns_zero_volatility(self) -> None:
+        """All same returns should give volatility = 0."""
+        stocks = [create_stock(f"STK{i}", predicted_return=0.10) for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_return_volatility() == 0.0
+
+    def test_varied_returns_nonzero_volatility(self) -> None:
+        """Varied returns should give positive volatility."""
+        stocks = [
+            create_stock("STK1", predicted_return=0.05),
+            create_stock("STK2", predicted_return=0.10),
+            create_stock("STK3", predicted_return=0.15),
+            create_stock("STK4", predicted_return=0.20),
+        ]
+        plan = create_plan(stocks)
+
+        # Mean = 0.125, variance = ((0.05-0.125)^2 + (0.10-0.125)^2 + (0.15-0.125)^2 + (0.20-0.125)^2) / 4
+        # = (0.005625 + 0.000625 + 0.000625 + 0.005625) / 4 = 0.003125
+        # Std dev = sqrt(0.003125) ≈ 0.0559
+        expected_vol = math.sqrt(0.003125)
+        assert abs(plan.get_return_volatility() - expected_vol) < 0.0001
+
+    def test_single_stock_zero_volatility(self) -> None:
+        """Single stock should have volatility = 0 (need at least 2)."""
+        stocks = [create_stock("STK1", predicted_return=0.10)]
+        plan = create_plan(stocks)
+
+        assert plan.get_return_volatility() == 0.0
+
+
+class TestSharpeProxy:
+    """Tests for Sharpe ratio proxy calculation."""
+
+    def test_positive_sharpe(self) -> None:
+        """Positive return with volatility should give positive Sharpe."""
+        stocks = [
+            create_stock("STK1", predicted_return=0.05),
+            create_stock("STK2", predicted_return=0.10),
+            create_stock("STK3", predicted_return=0.15),
+            create_stock("STK4", predicted_return=0.20),
+        ]
+        plan = create_plan(stocks)
+
+        # Return = 0.125, volatility = 0.0559
+        # Sharpe = 0.125 / 0.0559 ≈ 2.24
+        sharpe = plan.get_sharpe_proxy()
+        assert sharpe > 2.0
+        assert sharpe < 2.5
+
+    def test_zero_volatility_zero_sharpe(self) -> None:
+        """Zero volatility should give Sharpe = 0 (undefined)."""
+        stocks = [create_stock(f"STK{i}", predicted_return=0.10) for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_sharpe_proxy() == 0.0
+
+    def test_empty_portfolio_zero_sharpe(self) -> None:
+        """Empty portfolio should have Sharpe = 0."""
+        stocks = [create_stock(f"STK{i}", selected=False) for i in range(5)]
+        plan = create_plan(stocks)
+
+        assert plan.get_sharpe_proxy() == 0.0
+
+
+class TestPlanToMetrics:
+    """Tests for the plan_to_metrics converter function."""
+
+    def test_metrics_from_valid_portfolio(self) -> None:
+        """plan_to_metrics should return all metrics for valid portfolio."""
+        stocks = [
+            *[create_stock(f"TECH{i}", sector="Technology", predicted_return=0.12) for i in range(5)],
+            *[create_stock(f"HLTH{i}", sector="Healthcare", predicted_return=0.08) for i in range(5)],
+        ]
+        plan = create_plan(stocks)
+
+        metrics = plan_to_metrics(plan)
+
+        assert metrics is not None
+        assert isinstance(metrics, PortfolioMetricsModel)
+        assert metrics.sector_count == 2
+        assert abs(metrics.expected_return - 0.10) < 0.001
+        assert abs(metrics.diversification_score - 0.5) < 0.001
+        assert abs(metrics.herfindahl_index - 0.5) < 0.001
+        assert abs(metrics.max_sector_exposure - 0.5) < 0.001
+
+    def test_metrics_from_empty_portfolio_is_none(self) -> None:
+        """plan_to_metrics should return None for empty portfolio."""
+        stocks = [create_stock(f"STK{i}", selected=False) for i in range(5)]
+        plan = create_plan(stocks)
+
+        metrics = plan_to_metrics(plan)
+
+        assert metrics is None
+
+    def test_metrics_serialization(self) -> None:
+        """Metrics should serialize with camelCase aliases."""
+        stocks = [create_stock(f"STK{i}") for i in range(5)]
+        plan = create_plan(stocks)
+
+        metrics = plan_to_metrics(plan)
+        assert metrics is not None
+
+        data = metrics.model_dump(by_alias=True)
+        assert "expectedReturn" in data
+        assert "sectorCount" in data
+        assert "maxSectorExposure" in data
+        assert "herfindahlIndex" in data
+        assert "diversificationScore" in data
+        assert "returnVolatility" in data
+        assert "sharpeProxy" in data

tests/test_constraints.py

@@ -0,0 +1,381 @@
+"""
+Constraint tests for the Portfolio Optimization quickstart.
+
+Each constraint is tested with both penalizing and non-penalizing scenarios.
+This ensures the constraints correctly encode the business rules.
+
+Test Patterns:
+1. Create minimal test data (just what's needed for the test)
+2. Use constraint_verifier to check penalties/rewards
+3. Provide PortfolioConfig as problem fact for parameterized constraints
+
+Finance Concepts Tested:
+- Stock selection (configurable target, default 20)
+- Sector diversification (configurable max per sector, default 5)
+- Return maximization (prefer high-return stocks)
+"""
+from solverforge_legacy.solver.test import ConstraintVerifier
+
+from portfolio_optimization.domain import (
+    StockSelection,
+    PortfolioOptimizationPlan,
+    PortfolioConfig,
+    SelectionValue,
+    SELECTED,
+    NOT_SELECTED,
+)
+from portfolio_optimization.constraints import (
+    define_constraints,
+    must_select_target_count,
+    penalize_unselected_stock,
+    sector_exposure_limit,
+    maximize_expected_return,
+)
+
+import pytest
+
+
+# Create constraint verifier for testing
+constraint_verifier = ConstraintVerifier.build(
+    define_constraints, PortfolioOptimizationPlan, StockSelection
+)
+
+# Default config matches historical defaults
+DEFAULT_CONFIG = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=10000)
+
+
+# ========================================
+# Helper Functions
+# ========================================
+
+def create_stock(
+    stock_id: str,
+    sector: str = "Technology",
+    predicted_return: float = 0.10,
+    selected: bool = True
+) -> StockSelection:
+    """Create a test stock with sensible defaults.
+
+    Args:
+        stock_id: Unique identifier for the stock
+        sector: Industry sector (default "Technology")
+        predicted_return: ML-predicted return as decimal (default 0.10 = 10%)
+        selected: If True, stock is selected for portfolio. If False, not selected.
+
+    Returns:
+        StockSelection with the specified parameters
+    """
+    # Convert boolean to SelectionValue for the planning variable
+    selection_value = SELECTED if selected else NOT_SELECTED
+
+    return StockSelection(
+        stock_id=stock_id,
+        stock_name=f"{stock_id} Corp",
+        sector=sector,
+        predicted_return=predicted_return,
+        selection=selection_value,
+    )
+
+
+# ========================================
+# Must Select Target Count Tests
+# ========================================
+
+class TestMustSelectTargetCount:
+    """Tests for the must_select_target_count constraint.
+
+    This is a parameterized constraint that reads target_count from PortfolioConfig.
+    Default is 20 stocks. Only penalizes when count EXCEEDS target.
+    """
+
+    def test_exactly_target_no_penalty(self) -> None:
+        """Selecting exactly target_count stocks should not be penalized."""
+        stocks = [create_stock(f"STK{i}", selected=True) for i in range(20)]
+
+        constraint_verifier.verify_that(must_select_target_count).given(
+            *stocks, DEFAULT_CONFIG
+        ).penalizes(0)
+
+    def test_one_over_target_penalizes_1(self) -> None:
+        """Selecting target_count + 1 stocks should be penalized by 1."""
+        stocks = [create_stock(f"STK{i}", selected=True) for i in range(21)]
+
+        constraint_verifier.verify_that(must_select_target_count).given(
+            *stocks, DEFAULT_CONFIG
+        ).penalizes_by(1)
+
+    def test_five_over_target_penalizes_5(self) -> None:
+        """Selecting target_count + 5 stocks should be penalized by 5."""
+        stocks = [create_stock(f"STK{i}", selected=True) for i in range(25)]
+
+        constraint_verifier.verify_that(must_select_target_count).given(
+            *stocks, DEFAULT_CONFIG
+        ).penalizes_by(5)
+
+    def test_under_target_no_penalty(self) -> None:
+        """The max constraint doesn't penalize for too few stocks."""
+        stocks = [create_stock(f"STK{i}", selected=True) for i in range(19)]
+
+        constraint_verifier.verify_that(must_select_target_count).given(
+            *stocks, DEFAULT_CONFIG
+        ).penalizes(0)
+
+    def test_custom_target_10(self) -> None:
+        """Custom target_count=10: 11 stocks should penalize by 1."""
+        config = PortfolioConfig(target_count=10, max_per_sector=5, unselected_penalty=10000)
+        stocks = [create_stock(f"STK{i}", selected=True) for i in range(11)]
+
+        constraint_verifier.verify_that(must_select_target_count).given(
+            *stocks, config
+        ).penalizes_by(1)
+
+    def test_custom_target_30(self) -> None:
+        """Custom target_count=30: exactly 30 stocks should not penalize."""
+        config = PortfolioConfig(target_count=30, max_per_sector=8, unselected_penalty=10000)
+        stocks = [create_stock(f"STK{i}", selected=True) for i in range(30)]
+
+        constraint_verifier.verify_that(must_select_target_count).given(
+            *stocks, config
+        ).penalizes(0)
+
+
+class TestPenalizeUnselectedStock:
+    """Tests for the penalize_unselected_stock soft constraint.
+
+    This is a parameterized constraint that reads unselected_penalty from PortfolioConfig.
+    Default penalty is 10000 per unselected stock.
+    It drives the solver to select stocks without affecting hard feasibility.
+    """
+
+    def test_selected_stock_no_penalty(self) -> None:
+        """A selected stock should not be penalized."""
+        stock = create_stock("STK1", selected=True)
+
+        constraint_verifier.verify_that(penalize_unselected_stock).given(
+            stock, DEFAULT_CONFIG
+        ).penalizes(0)
+
+    def test_unselected_stock_penalized(self) -> None:
+        """An unselected stock should be penalized by unselected_penalty (default 10000)."""
+        stock = create_stock("STK1", selected=False)
+
+        # 1 unselected * 10000 penalty = 10000
+        constraint_verifier.verify_that(penalize_unselected_stock).given(
+            stock, DEFAULT_CONFIG
+        ).penalizes_by(10000)
+
+    def test_mixed_selection(self) -> None:
+        """Mix of selected and unselected stocks - only unselected penalized."""
+        selected = [create_stock(f"SEL{i}", selected=True) for i in range(10)]
+        unselected = [create_stock(f"UNS{i}", selected=False) for i in range(5)]
+
+        # 5 unselected * 10000 penalty = 50000
+        constraint_verifier.verify_that(penalize_unselected_stock).given(
+            *selected, *unselected, DEFAULT_CONFIG
+        ).penalizes_by(50000)
+
+    def test_custom_penalty(self) -> None:
+        """Custom unselected_penalty=5000: 2 unselected should penalize by 10000."""
+        config = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=5000)
+        unselected = [create_stock(f"UNS{i}", selected=False) for i in range(2)]
+
+        # 2 unselected * 5000 penalty = 10000
+        constraint_verifier.verify_that(penalize_unselected_stock).given(
+            *unselected, config
+        ).penalizes_by(10000)
+
+
+# ========================================
+# Sector Exposure Limit Tests
+# ========================================
+
+class TestSectorExposureLimit:
+    """Tests for the sector_exposure_limit constraint.
+
+    This is a parameterized constraint that reads max_per_sector from PortfolioConfig.
+    Default is 5 stocks per sector (= 25% with 20 total stocks).
+    """
+
+    def test_at_limit_no_penalty(self) -> None:
+        """Having exactly max_per_sector stocks in each sector should not be penalized."""
+        # 5 tech + 5 healthcare + 5 finance + 5 energy = 20 stocks, all at limit
+        tech = [create_stock(f"TECH{i}", sector="Technology", selected=True) for i in range(5)]
+        health = [create_stock(f"HLTH{i}", sector="Healthcare", selected=True) for i in range(5)]
+        finance = [create_stock(f"FIN{i}", sector="Finance", selected=True) for i in range(5)]
+        energy = [create_stock(f"NRG{i}", sector="Energy", selected=True) for i in range(5)]
+
+        constraint_verifier.verify_that(sector_exposure_limit).given(
+            *tech, *health, *finance, *energy, DEFAULT_CONFIG
+        ).penalizes(0)
+
+    def test_one_over_limit_penalizes_1(self) -> None:
+        """Having max_per_sector + 1 stocks in a sector should be penalized by 1."""
+        tech = [create_stock(f"TECH{i}", sector="Technology", selected=True) for i in range(6)]
+
+        constraint_verifier.verify_that(sector_exposure_limit).given(
+            *tech, DEFAULT_CONFIG
+        ).penalizes_by(1)
+
+    def test_three_over_limit_penalizes_3(self) -> None:
+        """Having max_per_sector + 3 stocks in a sector should be penalized by 3."""
+        tech = [create_stock(f"TECH{i}", sector="Technology", selected=True) for i in range(8)]
+
+        constraint_verifier.verify_that(sector_exposure_limit).given(
+            *tech, DEFAULT_CONFIG
+        ).penalizes_by(3)
+
+    def test_multiple_sectors_over_limit(self) -> None:
+        """Multiple sectors over limit should each contribute penalty."""
+        # 6 tech (penalty 1) + 7 healthcare (penalty 2) = total penalty 3
+        tech = [create_stock(f"TECH{i}", sector="Technology", selected=True) for i in range(6)]
+        health = [create_stock(f"HLTH{i}", sector="Healthcare", selected=True) for i in range(7)]
+
+        constraint_verifier.verify_that(sector_exposure_limit).given(
+            *tech, *health, DEFAULT_CONFIG
+        ).penalizes_by(3)
+
+    def test_unselected_stocks_not_counted(self) -> None:
+        """Unselected stocks should not count toward sector limits."""
+        # 5 selected tech (at limit) + 5 unselected tech (ignored) = no penalty
+        selected = [create_stock(f"STECH{i}", sector="Technology", selected=True) for i in range(5)]
+        unselected = [create_stock(f"UTECH{i}", sector="Technology", selected=False) for i in range(5)]
+
+        constraint_verifier.verify_that(sector_exposure_limit).given(
+            *selected, *unselected, DEFAULT_CONFIG
+        ).penalizes(0)
+
+    def test_single_sector_at_limit_no_penalty(self) -> None:
+        """A single sector with exactly max_per_sector stocks should not be penalized."""
+        stocks = [create_stock(f"TECH{i}", sector="Technology", selected=True) for i in range(5)]
+
+        constraint_verifier.verify_that(sector_exposure_limit).given(
+            *stocks, DEFAULT_CONFIG
+        ).penalizes(0)
+
+    def test_custom_max_per_sector_3(self) -> None:
+        """Custom max_per_sector=3: 4 stocks should penalize by 1."""
+        config = PortfolioConfig(target_count=15, max_per_sector=3, unselected_penalty=10000)
+        tech = [create_stock(f"TECH{i}", sector="Technology", selected=True) for i in range(4)]
+
+        constraint_verifier.verify_that(sector_exposure_limit).given(
+            *tech, config
+        ).penalizes_by(1)
+
+    def test_custom_max_per_sector_8(self) -> None:
+        """Custom max_per_sector=8: 8 stocks should not penalize."""
+        config = PortfolioConfig(target_count=30, max_per_sector=8, unselected_penalty=10000)
+        tech = [create_stock(f"TECH{i}", sector="Technology", selected=True) for i in range(8)]
+
+        constraint_verifier.verify_that(sector_exposure_limit).given(
+            *tech, config
+        ).penalizes(0)
+
+
+# ========================================
+# Maximize Expected Return Tests
+# ========================================
+
+class TestMaximizeExpectedReturn:
+    """Tests for the maximize_expected_return constraint.
+
+    This constraint rewards selected stocks based on predicted_return * 10000.
+    It does not use PortfolioConfig (not parameterized).
+    """
+
+    def test_high_return_stock_rewarded(self) -> None:
+        """Stock with 12% predicted return should be rewarded 1200 points."""
+        # 0.12 * 10000 = 1200
+        stock = create_stock("AAPL", predicted_return=0.12, selected=True)
+
+        constraint_verifier.verify_that(maximize_expected_return).given(
+            stock
+        ).rewards_with(1200)
+
+    def test_low_return_stock_rewarded_less(self) -> None:
+        """Stock with 5% predicted return should be rewarded 500 points."""
+        # 0.05 * 10000 = 500
+        stock = create_stock("INTC", predicted_return=0.05, selected=True)
+
+        constraint_verifier.verify_that(maximize_expected_return).given(
+            stock
+        ).rewards_with(500)
+
+    def test_multiple_stocks_reward_sum(self) -> None:
+        """Multiple selected stocks should have rewards summed."""
+        # 0.10 * 10000 = 1000, 0.15 * 10000 = 1500, total = 2500
+        stock1 = create_stock("STK1", predicted_return=0.10, selected=True)
+        stock2 = create_stock("STK2", predicted_return=0.15, selected=True)
+
+        constraint_verifier.verify_that(maximize_expected_return).given(
+            stock1, stock2
+        ).rewards_with(2500)
+
+    def test_unselected_stock_not_rewarded(self) -> None:
+        """Unselected stocks should not contribute to reward."""
+        stock = create_stock("STK1", predicted_return=0.20, selected=False)
+
+        constraint_verifier.verify_that(maximize_expected_return).given(
+            stock
+        ).rewards(0)
+
+
+# ========================================
+# Integration Tests
+# ========================================
+
+class TestIntegration:
+    """Integration tests for the complete constraint set."""
+
+    def test_valid_portfolio_no_sector_violations(self) -> None:
+        """A valid portfolio should have 0 hard constraint violations."""
+        # Create valid portfolio: 20 stocks, max 5 per sector
+        tech = [create_stock(f"TECH{i}", sector="Technology", predicted_return=0.15, selected=True) for i in range(5)]
+        health = [create_stock(f"HLTH{i}", sector="Healthcare", predicted_return=0.10, selected=True) for i in range(5)]
+        finance = [create_stock(f"FIN{i}", sector="Finance", predicted_return=0.08, selected=True) for i in range(5)]
+        energy = [create_stock(f"NRG{i}", sector="Energy", predicted_return=0.05, selected=True) for i in range(5)]
+
+        all_stocks = tech + health + finance + energy
+
+        # Verify no hard constraint violations
+        constraint_verifier.verify_that(sector_exposure_limit).given(*all_stocks, DEFAULT_CONFIG).penalizes(0)
+        constraint_verifier.verify_that(must_select_target_count).given(*all_stocks, DEFAULT_CONFIG).penalizes(0)
+
+    def test_high_return_portfolio_preferred(self) -> None:
+        """Higher return stocks should result in higher soft score."""
+        # Portfolio A: all 10% return stocks
+        low_return = [create_stock(f"LOW{i}", predicted_return=0.10, selected=True) for i in range(5)]
+
+        # Portfolio B: all 15% return stocks
+        high_return = [create_stock(f"HIGH{i}", predicted_return=0.15, selected=True) for i in range(5)]
+
+        # Calculate rewards
+        low_reward = 5 * 1000  # 5 stocks * 0.10 * 10000
+        high_reward = 5 * 1500  # 5 stocks * 0.15 * 10000
+
+        constraint_verifier.verify_that(maximize_expected_return).given(*low_return).rewards_with(low_reward)
+        constraint_verifier.verify_that(maximize_expected_return).given(*high_return).rewards_with(high_reward)
+
+        assert high_reward > low_reward, "High return portfolio should have higher reward"
+
+    def test_custom_config_integration(self) -> None:
+        """Test that custom config values are respected across constraints."""
+        # Custom config: target 10 stocks, max 3 per sector
+        config = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=5000)
+
+        # Create portfolio: 10 stocks total, 3 per sector (within limits)
+        tech = [create_stock(f"TECH{i}", sector="Technology", selected=True) for i in range(3)]
+        health = [create_stock(f"HLTH{i}", sector="Healthcare", selected=True) for i in range(3)]
+        finance = [create_stock(f"FIN{i}", sector="Finance", selected=True) for i in range(3)]
+        energy = [create_stock(f"NRG{i}", sector="Energy", selected=True) for i in range(1)]
+        unselected = [create_stock(f"UNS{i}", sector="Other", selected=False) for i in range(2)]
+
+        all_stocks = tech + health + finance + energy + unselected
+
+        # Verify: 10 selected stocks should not penalize target count constraint
+        constraint_verifier.verify_that(must_select_target_count).given(*all_stocks, config).penalizes(0)
+
+        # Verify: 3 per sector should not penalize sector limit
+        constraint_verifier.verify_that(sector_exposure_limit).given(*all_stocks, config).penalizes(0)
+
+        # Verify: 2 unselected * 5000 penalty = 10000
+        constraint_verifier.verify_that(penalize_unselected_stock).given(*all_stocks, config).penalizes_by(10000)

tests/test_feasible.py

@@ -0,0 +1,161 @@
+"""
+Feasibility tests for the Portfolio Optimization quickstart.
+
+These tests verify that the solver can find valid solutions
+for the demo datasets.
+"""
+from solverforge_legacy.solver import SolverFactory
+from solverforge_legacy.solver.config import (
+    SolverConfig,
+    ScoreDirectorFactoryConfig,
+    TerminationConfig,
+    Duration,
+)
+
+from portfolio_optimization.domain import PortfolioOptimizationPlan, StockSelection
+from portfolio_optimization.constraints import define_constraints
+from portfolio_optimization.demo_data import generate_demo_data, DemoData
+
+import pytest
+
+
+def solve_portfolio(plan: PortfolioOptimizationPlan, seconds: int = 5) -> PortfolioOptimizationPlan:
+    """Run the solver on a portfolio for a given number of seconds."""
+    solver_config = SolverConfig(
+        solution_class=PortfolioOptimizationPlan,
+        entity_class_list=[StockSelection],
+        score_director_factory_config=ScoreDirectorFactoryConfig(
+            constraint_provider_function=define_constraints
+        ),
+        termination_config=TerminationConfig(spent_limit=Duration(seconds=seconds)),
+    )
+
+    solver = SolverFactory.create(solver_config).build_solver()
+    return solver.solve(plan)
+
+
+class TestFeasibility:
+    """Test that the solver can find feasible solutions."""
+
+    def test_small_dataset_feasible(self):
+        """The SMALL dataset should be solvable to a feasible solution."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        solution = solve_portfolio(plan, seconds=10)
+
+        # Check that we got a solution
+        assert solution is not None
+        assert solution.score is not None
+
+        # Check feasibility (hard score = 0)
+        assert solution.score.hard_score == 0, \
+            f"Solution should be feasible, got hard score: {solution.score.hard_score}"
+
+        # Check we selected exactly 20 stocks
+        selected_count = solution.get_selected_count()
+        assert selected_count == 20, \
+            f"Should select 20 stocks, got {selected_count}"
+
+    def test_large_dataset_feasible(self):
+        """The LARGE dataset should be solvable to a feasible solution."""
+        plan = generate_demo_data(DemoData.LARGE)
+
+        solution = solve_portfolio(plan, seconds=15)
+
+        # Check that we got a solution
+        assert solution is not None
+        assert solution.score is not None
+
+        # Check feasibility (hard score = 0)
+        assert solution.score.hard_score == 0, \
+            f"Solution should be feasible, got hard score: {solution.score.hard_score}"
+
+        # Check we selected exactly 20 stocks
+        selected_count = solution.get_selected_count()
+        assert selected_count == 20, \
+            f"Should select 20 stocks, got {selected_count}"
+
+    def test_sector_limits_respected(self):
+        """The solver should respect sector exposure limits."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        solution = solve_portfolio(plan, seconds=10)
+
+        # Check sector weights
+        sector_weights = solution.get_sector_weights()
+
+        for sector, weight in sector_weights.items():
+            assert weight <= 0.26, \
+                f"Sector {sector} has {weight*100:.1f}% weight, exceeds 25% limit"
+
+    def test_positive_expected_return(self):
+        """The solver should find a portfolio with positive expected return."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        solution = solve_portfolio(plan, seconds=10)
+
+        expected_return = solution.get_expected_return()
+
+        # With our demo data, we should get at least 5% expected return
+        assert expected_return > 0.05, \
+            f"Expected return should be > 5%, got {expected_return*100:.2f}%"
+
+    def test_expected_return_reasonable(self):
+        """The expected return should be reasonable for valid solutions."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        solution = solve_portfolio(plan, seconds=10)
+
+        # Check expected return is positive
+        expected_return = solution.get_expected_return()
+        assert expected_return > 0, \
+            f"Expected return should be positive, got {expected_return}"
+
+
+class TestDemoData:
+    """Test demo data generation."""
+
+    def test_small_dataset_has_25_stocks(self):
+        """SMALL dataset should have 25 stocks (5+ per sector for feasibility)."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        assert len(plan.stocks) == 25
+
+    def test_large_dataset_has_51_stocks(self):
+        """LARGE dataset should have 51 stocks."""
+        plan = generate_demo_data(DemoData.LARGE)
+
+        assert len(plan.stocks) == 51
+
+    def test_stocks_have_sectors(self):
+        """All stocks should have a sector assigned."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        for stock in plan.stocks:
+            assert stock.sector is not None
+            assert len(stock.sector) > 0
+
+    def test_stocks_have_predictions(self):
+        """All stocks should have predicted returns."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        for stock in plan.stocks:
+            assert stock.predicted_return is not None
+            # Predictions should be reasonable (-10% to +25%)
+            assert -0.10 <= stock.predicted_return <= 0.25
+
+    def test_stocks_initially_unselected(self):
+        """All stocks should start with selected=None."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        for stock in plan.stocks:
+            assert stock.selected is None
+
+    def test_has_multiple_sectors(self):
+        """Demo data should have multiple sectors for diversification testing."""
+        plan = generate_demo_data(DemoData.SMALL)
+
+        sectors = {stock.sector for stock in plan.stocks}
+
+        assert len(sectors) >= 4, \
+            f"Should have at least 4 sectors for diversification, got {len(sectors)}"

tests/test_portfolio_config.py

@@ -0,0 +1,246 @@
+"""
+Tests for PortfolioConfig - the constraint configuration dataclass.
+
+PortfolioConfig holds the threshold values that constraints use:
+- target_count: Number of stocks to select (default 20)
+- max_per_sector: Maximum stocks per sector (default 5)
+- unselected_penalty: Soft penalty per unselected stock (default 10000)
+
+These tests verify:
+1. PortfolioConfig dataclass behavior (defaults, equality, hashing)
+2. Integration with converters (model_to_plan creates correct config)
+3. Integration with demo_data (generate_demo_data creates correct config)
+"""
+import pytest
+from dataclasses import FrozenInstanceError
+
+from portfolio_optimization.domain import (
+    PortfolioConfig,
+    PortfolioOptimizationPlan,
+    PortfolioOptimizationPlanModel,
+    StockSelectionModel,
+)
+from portfolio_optimization.converters import model_to_plan
+from portfolio_optimization.demo_data import generate_demo_data, DemoData
+
+
+class TestPortfolioConfigDataclass:
+    """Tests for the PortfolioConfig dataclass itself."""
+
+    def test_default_values(self) -> None:
+        """PortfolioConfig should have sensible defaults."""
+        config = PortfolioConfig()
+        assert config.target_count == 20
+        assert config.max_per_sector == 5
+        assert config.unselected_penalty == 10000
+
+    def test_custom_values(self) -> None:
+        """PortfolioConfig should accept custom values."""
+        config = PortfolioConfig(
+            target_count=30,
+            max_per_sector=8,
+            unselected_penalty=5000
+        )
+        assert config.target_count == 30
+        assert config.max_per_sector == 8
+        assert config.unselected_penalty == 5000
+
+    def test_equality_same_values(self) -> None:
+        """Two PortfolioConfigs with same values should be equal."""
+        config1 = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=10000)
+        config2 = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=10000)
+        assert config1 == config2
+
+    def test_equality_different_values(self) -> None:
+        """Two PortfolioConfigs with different values should not be equal."""
+        config1 = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=10000)
+        config2 = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=10000)
+        assert config1 != config2
+
+    def test_equality_different_penalty(self) -> None:
+        """PortfolioConfigs with different penalties should not be equal."""
+        config1 = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=10000)
+        config2 = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=5000)
+        assert config1 != config2
+
+    def test_hash_same_values(self) -> None:
+        """Two PortfolioConfigs with same values should have same hash."""
+        config1 = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=10000)
+        config2 = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=10000)
+        assert hash(config1) == hash(config2)
+
+    def test_hash_different_values(self) -> None:
+        """Two PortfolioConfigs with different values should (likely) have different hash."""
+        config1 = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=10000)
+        config2 = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=10000)
+        # Hash collision is possible but unlikely
+        assert hash(config1) != hash(config2)
+
+    def test_usable_as_dict_key(self) -> None:
+        """PortfolioConfig should be usable as a dictionary key."""
+        config = PortfolioConfig(target_count=15, max_per_sector=4, unselected_penalty=8000)
+        d = {config: "value"}
+        assert d[config] == "value"
+
+    def test_usable_in_set(self) -> None:
+        """PortfolioConfig should be usable in a set."""
+        config1 = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=10000)
+        config2 = PortfolioConfig(target_count=10, max_per_sector=3, unselected_penalty=10000)
+        config3 = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=10000)
+
+        s = {config1, config2, config3}
+        # config1 and config2 are equal, so set should have 2 items
+        assert len(s) == 2
+
+
+class TestPortfolioConfigInConverters:
+    """Tests for PortfolioConfig creation in converters.model_to_plan()."""
+
+    def _create_plan_model(
+        self,
+        target_position_count: int = 20,
+        max_sector_percentage: float = 0.25
+    ) -> PortfolioOptimizationPlanModel:
+        """Helper to create a minimal plan model for testing."""
+        return PortfolioOptimizationPlanModel(
+            stocks=[
+                StockSelectionModel(
+                    stock_id="TEST",
+                    stock_name="Test Corp",
+                    sector="Technology",
+                    predicted_return=0.10,
+                    selected=None
+                )
+            ],
+            target_position_count=target_position_count,
+            max_sector_percentage=max_sector_percentage
+        )
+
+    def test_model_to_plan_creates_config(self) -> None:
+        """model_to_plan should create a PortfolioConfig."""
+        model = self._create_plan_model()
+        plan = model_to_plan(model)
+        assert plan.portfolio_config is not None
+        assert isinstance(plan.portfolio_config, PortfolioConfig)
+
+    def test_model_to_plan_config_has_correct_target(self) -> None:
+        """model_to_plan should set target_count from target_position_count."""
+        model = self._create_plan_model(target_position_count=30)
+        plan = model_to_plan(model)
+        assert plan.portfolio_config.target_count == 30
+
+    def test_model_to_plan_config_calculates_max_per_sector(self) -> None:
+        """model_to_plan should calculate max_per_sector from percentage * target."""
+        # 25% of 20 = 5
+        model = self._create_plan_model(target_position_count=20, max_sector_percentage=0.25)
+        plan = model_to_plan(model)
+        assert plan.portfolio_config.max_per_sector == 5
+
+    def test_model_to_plan_config_calculates_max_per_sector_30(self) -> None:
+        """max_per_sector calculation for 30 stocks at 25%."""
+        # 25% of 30 = 7.5 -> 7 (int)
+        model = self._create_plan_model(target_position_count=30, max_sector_percentage=0.25)
+        plan = model_to_plan(model)
+        assert plan.portfolio_config.max_per_sector == 7
+
+    def test_model_to_plan_config_calculates_max_per_sector_40_percent(self) -> None:
+        """max_per_sector calculation for 40% sector limit."""
+        # 40% of 20 = 8
+        model = self._create_plan_model(target_position_count=20, max_sector_percentage=0.40)
+        plan = model_to_plan(model)
+        assert plan.portfolio_config.max_per_sector == 8
+
+    def test_model_to_plan_config_minimum_max_per_sector(self) -> None:
+        """max_per_sector should be at least 1."""
+        # 5% of 10 = 0.5 -> should be clamped to 1
+        model = self._create_plan_model(target_position_count=10, max_sector_percentage=0.05)
+        plan = model_to_plan(model)
+        assert plan.portfolio_config.max_per_sector == 1
+
+    def test_model_to_plan_config_default_penalty(self) -> None:
+        """model_to_plan should set default unselected_penalty of 10000."""
+        model = self._create_plan_model()
+        plan = model_to_plan(model)
+        assert plan.portfolio_config.unselected_penalty == 10000
+
+
+class TestPortfolioConfigInDemoData:
+    """Tests for PortfolioConfig creation in generate_demo_data()."""
+
+    def test_small_demo_creates_config(self) -> None:
+        """generate_demo_data(SMALL) should create a PortfolioConfig."""
+        plan = generate_demo_data(DemoData.SMALL)
+        assert plan.portfolio_config is not None
+        assert isinstance(plan.portfolio_config, PortfolioConfig)
+
+    def test_large_demo_creates_config(self) -> None:
+        """generate_demo_data(LARGE) should create a PortfolioConfig."""
+        plan = generate_demo_data(DemoData.LARGE)
+        assert plan.portfolio_config is not None
+        assert isinstance(plan.portfolio_config, PortfolioConfig)
+
+    def test_small_demo_config_values(self) -> None:
+        """SMALL demo should have default config values (20 target, 5 max per sector)."""
+        plan = generate_demo_data(DemoData.SMALL)
+        assert plan.portfolio_config.target_count == 20
+        assert plan.portfolio_config.max_per_sector == 5
+        assert plan.portfolio_config.unselected_penalty == 10000
+
+    def test_large_demo_config_values(self) -> None:
+        """LARGE demo should have default config values (20 target, 5 max per sector)."""
+        plan = generate_demo_data(DemoData.LARGE)
+        assert plan.portfolio_config.target_count == 20
+        assert plan.portfolio_config.max_per_sector == 5
+        assert plan.portfolio_config.unselected_penalty == 10000
+
+    def test_demo_config_matches_plan_fields(self) -> None:
+        """PortfolioConfig values should match plan's target_position_count."""
+        plan = generate_demo_data(DemoData.SMALL)
+        assert plan.portfolio_config.target_count == plan.target_position_count
+
+    def test_demo_config_max_per_sector_matches_percentage(self) -> None:
+        """max_per_sector should equal max_sector_percentage * target_position_count."""
+        plan = generate_demo_data(DemoData.SMALL)
+        expected = int(plan.max_sector_percentage * plan.target_position_count)
+        assert plan.portfolio_config.max_per_sector == expected
+
+
+class TestPortfolioConfigEdgeCases:
+    """Edge case tests for PortfolioConfig."""
+
+    def test_very_small_target(self) -> None:
+        """PortfolioConfig should work with small target count."""
+        config = PortfolioConfig(target_count=5, max_per_sector=2, unselected_penalty=10000)
+        assert config.target_count == 5
+        assert config.max_per_sector == 2
+
+    def test_very_large_target(self) -> None:
+        """PortfolioConfig should work with large target count."""
+        config = PortfolioConfig(target_count=100, max_per_sector=25, unselected_penalty=10000)
+        assert config.target_count == 100
+        assert config.max_per_sector == 25
+
+    def test_zero_penalty(self) -> None:
+        """PortfolioConfig should allow zero penalty (disables selection driving)."""
+        config = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=0)
+        assert config.unselected_penalty == 0
+
+    def test_large_penalty(self) -> None:
+        """PortfolioConfig should allow large penalties."""
+        config = PortfolioConfig(target_count=20, max_per_sector=5, unselected_penalty=1000000)
+        assert config.unselected_penalty == 1000000
+
+    def test_equality_with_non_config(self) -> None:
+        """PortfolioConfig should not equal non-PortfolioConfig objects."""
+        config = PortfolioConfig()
+        assert config != "not a config"
+        assert config != 20
+        assert config != {"target_count": 20}
+
+    def test_repr(self) -> None:
+        """PortfolioConfig should have a useful repr."""
+        config = PortfolioConfig(target_count=15, max_per_sector=4, unselected_penalty=8000)
+        repr_str = repr(config)
+        assert "15" in repr_str
+        assert "4" in repr_str
+        assert "8000" in repr_str

tests/test_rest_api.py

@@ -0,0 +1,136 @@
+"""
+Tests for REST API endpoints.
+
+Tests that configuration is properly received and applied.
+"""
+import pytest
+from fastapi.testclient import TestClient
+from portfolio_optimization.rest_api import app
+from portfolio_optimization.domain import (
+    PortfolioOptimizationPlanModel,
+    StockSelectionModel,
+    SolverConfigModel,
+)
+
+
+@pytest.fixture
+def client():
+    """Create a test client for the FastAPI app."""
+    return TestClient(app)
+
+
+class TestDemoDataEndpoints:
+    """Tests for demo data endpoints."""
+
+    def test_list_demo_data(self, client):
+        """GET /demo-data should return available datasets."""
+        response = client.get("/demo-data")
+        assert response.status_code == 200
+        data = response.json()
+        assert "SMALL" in data
+        assert "LARGE" in data
+
+    def test_get_small_demo_data(self, client):
+        """GET /demo-data/SMALL should return 25 stocks."""
+        response = client.get("/demo-data/SMALL")
+        assert response.status_code == 200
+        data = response.json()
+        assert "stocks" in data
+        assert len(data["stocks"]) == 25
+
+    def test_get_large_demo_data(self, client):
+        """GET /demo-data/LARGE should return 51 stocks."""
+        response = client.get("/demo-data/LARGE")
+        assert response.status_code == 200
+        data = response.json()
+        assert "stocks" in data
+        assert len(data["stocks"]) == 51
+
+
+class TestSolverConfigEndpoints:
+    """Tests for solver configuration handling."""
+
+    def test_plan_model_accepts_solver_config(self):
+        """PortfolioOptimizationPlanModel should accept solverConfig."""
+        model = PortfolioOptimizationPlanModel(
+            stocks=[
+                StockSelectionModel(
+                    stockId="AAPL",
+                    stockName="Apple",
+                    sector="Technology",
+                    predictedReturn=0.12,
+                    selected=None
+                )
+            ],
+            targetPositionCount=20,
+            maxSectorPercentage=0.25,
+            solverConfig=SolverConfigModel(terminationSeconds=60)
+        )
+        assert model.solver_config is not None
+        assert model.solver_config.termination_seconds == 60
+
+    def test_plan_model_serializes_solver_config(self):
+        """solverConfig should serialize with camelCase aliases."""
+        model = PortfolioOptimizationPlanModel(
+            stocks=[],
+            solverConfig=SolverConfigModel(terminationSeconds=90)
+        )
+        data = model.model_dump(by_alias=True)
+        assert "solverConfig" in data
+        assert data["solverConfig"]["terminationSeconds"] == 90
+
+    def test_plan_model_deserializes_solver_config(self):
+        """solverConfig should deserialize from JSON."""
+        json_data = {
+            "stocks": [
+                {
+                    "stockId": "AAPL",
+                    "stockName": "Apple",
+                    "sector": "Technology",
+                    "predictedReturn": 0.12,
+                    "selected": None
+                }
+            ],
+            "targetPositionCount": 15,
+            "maxSectorPercentage": 0.30,
+            "solverConfig": {
+                "terminationSeconds": 120
+            }
+        }
+        model = PortfolioOptimizationPlanModel.model_validate(json_data)
+        assert model.target_position_count == 15
+        assert model.max_sector_percentage == 0.30
+        assert model.solver_config is not None
+        assert model.solver_config.termination_seconds == 120
+
+    def test_plan_without_solver_config(self):
+        """Plan should work without solverConfig (uses defaults)."""
+        json_data = {
+            "stocks": [],
+            "targetPositionCount": 20,
+            "maxSectorPercentage": 0.25
+        }
+        model = PortfolioOptimizationPlanModel.model_validate(json_data)
+        assert model.solver_config is None  # None is OK, will use default 30s
+
+    def test_post_portfolio_with_solver_config(self, client):
+        """POST /portfolios should accept solverConfig in request body."""
+        # First get demo data
+        demo_response = client.get("/demo-data/SMALL")
+        plan_data = demo_response.json()
+
+        # Add solver config
+        plan_data["solverConfig"] = {
+            "terminationSeconds": 10  # Use short time for test
+        }
+
+        # Submit for solving
+        response = client.post("/portfolios", json=plan_data)
+        assert response.status_code == 200
+        job_id = response.json()
+        assert job_id is not None
+        assert len(job_id) > 0
+
+        # Stop solving immediately (we just want to verify config was accepted)
+        stop_response = client.delete(f"/portfolios/{job_id}")
+        assert stop_response.status_code == 200

tests/test_solver_config.py

@@ -0,0 +1,90 @@
+"""
+Tests for solver configuration functionality.
+
+Tests the create_solver_config factory function and dynamic termination time.
+"""
+import pytest
+from portfolio_optimization.solver import create_solver_config
+from portfolio_optimization.domain import SolverConfigModel
+
+
+class TestCreateSolverConfig:
+    """Tests for the create_solver_config factory function."""
+
+    def test_default_termination(self):
+        """Default solver should terminate after 30 seconds."""
+        config = create_solver_config()
+        assert config.termination_config.spent_limit.seconds == 30
+
+    def test_custom_termination_60s(self):
+        """Custom termination time of 60 seconds should be respected."""
+        config = create_solver_config(termination_seconds=60)
+        assert config.termination_config.spent_limit.seconds == 60
+
+    def test_custom_termination_10s(self):
+        """Minimum termination time of 10 seconds should work."""
+        config = create_solver_config(termination_seconds=10)
+        assert config.termination_config.spent_limit.seconds == 10
+
+    def test_custom_termination_300s(self):
+        """Maximum termination time of 300 seconds (5 min) should work."""
+        config = create_solver_config(termination_seconds=300)
+        assert config.termination_config.spent_limit.seconds == 300
+
+    def test_solver_config_has_correct_solution_class(self):
+        """Solver config should reference PortfolioOptimizationPlan."""
+        from portfolio_optimization.domain import PortfolioOptimizationPlan
+        config = create_solver_config()
+        assert config.solution_class == PortfolioOptimizationPlan
+
+    def test_solver_config_has_correct_entity_class(self):
+        """Solver config should include StockSelection entity."""
+        from portfolio_optimization.domain import StockSelection
+        config = create_solver_config()
+        assert StockSelection in config.entity_class_list
+
+
+class TestSolverConfigModel:
+    """Tests for the SolverConfigModel Pydantic model."""
+
+    def test_default_values(self):
+        """SolverConfigModel should have default termination of 30 seconds."""
+        model = SolverConfigModel()
+        assert model.termination_seconds == 30
+
+    def test_custom_termination(self):
+        """SolverConfigModel should accept custom termination."""
+        model = SolverConfigModel(termination_seconds=60)
+        assert model.termination_seconds == 60
+
+    def test_alias_serialization(self):
+        """SolverConfigModel should serialize with camelCase alias."""
+        model = SolverConfigModel(termination_seconds=45)
+        data = model.model_dump(by_alias=True)
+        assert "terminationSeconds" in data
+        assert data["terminationSeconds"] == 45
+
+    def test_alias_deserialization(self):
+        """SolverConfigModel should deserialize from camelCase."""
+        model = SolverConfigModel.model_validate({"terminationSeconds": 90})
+        assert model.termination_seconds == 90
+
+    def test_minimum_validation(self):
+        """SolverConfigModel should reject termination < 10 seconds."""
+        with pytest.raises(ValueError):
+            SolverConfigModel(termination_seconds=5)
+
+    def test_maximum_validation(self):
+        """SolverConfigModel should reject termination > 300 seconds."""
+        with pytest.raises(ValueError):
+            SolverConfigModel(termination_seconds=400)
+
+    def test_boundary_min(self):
+        """SolverConfigModel should accept exactly 10 seconds."""
+        model = SolverConfigModel(termination_seconds=10)
+        assert model.termination_seconds == 10
+
+    def test_boundary_max(self):
+        """SolverConfigModel should accept exactly 300 seconds."""
+        model = SolverConfigModel(termination_seconds=300)
+        assert model.termination_seconds == 300