Feat: Max Weight Constraint & NLP Logic

ai/ai_reporter.py

@@ -36,6 +36,8 @@ class AIReporter:
         # Get current date in a specific format (e.g., "February 03, 2026")
         current_date = datetime.now().strftime("%B %d, %Y")
         
+        import json
+
         # Format the user prompt
         # We assume ATTRIBUTION_PROMPT_TEMPLATE handles the rest, but we force the date in context
         user_prompt = f"""
@@ -46,8 +48,8 @@ INSTRUCTION: Start your commentary exactly with the header: "Market Commentary -
             total_active_return=attribution_report.total_active_return * 100, # Convert to %
             allocation_effect=attribution_report.allocation_effect * 100,
             selection_effect=attribution_report.selection_effect * 100,
-            top_contributors=", ".join(attribution_report.top_contributors),
-            top_detractors=", ".join(attribution_report.top_detractors),
+            top_contributors=json.dumps(attribution_report.top_contributors, indent=2),
+            top_detractors=json.dumps(attribution_report.top_detractors, indent=2),
             current_date=current_date # Pass date to template
         )
         

ai/prompts.py

@@ -1,4 +1,5 @@
 # System Prompt for the Portfolio Manager Persona
+# System Prompt for the Portfolio Manager Persona
 SYSTEM_PROMPT = """You are a Senior Portfolio Manager at a top-tier Asset Management firm (e.g., Goldman Sachs, BlackRock). 
 Your goal is to write a concise, professional, and insightful performance commentary for a High Net Worth Application.
 Your tone should be:
@@ -6,6 +7,14 @@ Your tone should be:
 2. Mathematically precise (cite the numbers).
 3. Explanatory (explain 'why' something happened).
 
+## GOLDMAN RULES (STRICT COMPLIANCE)
+1. **The Exclusion Rule**: If a stock or sector has "Status": "Excluded", NEVER refer to it as a "Holding". We don't own it. Its negative contribution is a "Missed Opportunity" or "Drag from Benchbark Rally".
+2. **The Active Return Rule**: Only call a stock a "Contributor" if its "Active_Contribution" is POSITIVE. 
+   - If we don't own a stock (Weight = 0%) and it went UP, it is a DETRACTOR (Active Contribution is NEGATIVE).
+   - If we don't own a stock and it went DOWN, it is a CONTRIBUTOR (Active Contribution is POSITIVE).
+3. **The GICS Rule**: Adhere strictly to the "Sector" field provided in the input JSON. Do not hallucinate sectors. (e.g. AMZN is Consumer Discretionary, XOM is Energy).
+4. **Data Grounding**: Do not cite any data not present in the provided JSON "Truth Tables".    
+
 Avoid generic financial advice. Focus strictly on the attribution data provided.
 """
 
@@ -18,21 +27,27 @@ Write a "Trailing 30-Day Risk & Performance Attribution" report relative to the
 
 ## Brinson-Fachler Attribution Data (Trailing 30 Days)
 - Total Active Return (Alpha): {total_active_return:.2f}%
-- Allocation Effect (Impact of Exclusions): {allocation_effect:.2f}%
+- Allocation Effect (Impact of Sector Weights): {allocation_effect:.2f}%
 - Selection Effect (Impact of Stock Picking): {selection_effect:.2f}%
 
-## Attribution Detail
-- Top Active Contributors: {top_contributors}
-- Top Active Detractors: {top_detractors}
+## Attribution Detail (The "Truth Tables")
+**Top Active Contributors (JSON)**:
+{top_contributors}
+
+**Top Active Detractors (JSON)**:
+{top_detractors}
 
 ## Guidelines for the Narrative:
-1. **Timeframe**: Use the EXACT date provided. Write "For the trailing 30-day period ending {current_date}..." DO NOT generalize to "the month of...".
-2. **Ticker Validation (CRITICAL)**: Always verify tickers. ExxonMobil is XOM, Chevron is CVX. Do NOT swap them.
+1. **Timeframe**: Use the EXACT date provided: "{current_date}".
+2. **Ticker Validation**: Use the Ticker symbols exactly as listed.
 3. **Attribution Logic**: 
-   - If a sector is excluded (0% weight), attribute ALL gains/losses to the **Allocation Effect**.
-   - Do NOT mention 'Selection Effect' for sectors where we hold 0% (e.g., if Energy is excluded, you didn't "select" bad Energy stocks, you just didn't own the sector).
-4. **Detractor Clarity**:
-   - If an EXCLUDED stock (like AMZN, XOM, CVX) is listed as a "Top Detractor", explicitly state: "We suffered a drag because the portfolio missed out on the rally in [Stock] due to exclusion constraints."
+   - If a sector is excluded (Allocation Effect), describe it as a strategic decision.
+   - For Detractors that are "Excluded" (e.g. Status: Excluded), say: "The portfolio faced a headwind due to the exclusion of [Sector/Stock], which rallied during the period." 
+   - DO NOT say "We held [Excluded Stock]".
+4. **Chain of Thought (Mental Check)**:
+   - First, scan the JSON. Identify the "Status" of the top movers.
+   - Second, match the Sector to the Stock.
+   - Third, write the commentary based ONLY on these facts.
 
 Write a professional, concise 3-paragraph commentary.
 """

analytics/attribution.py

@@ -87,14 +87,38 @@ class AttributionEngine:
         total_interaction = attr_df['interaction'].sum()
         
         # Calculate Top Contributors/Detractors to active return
-        # Active Weight * Asset Return? Or Contribution to Active Return?
-        # Contribution to Active Return = w_p*r_a - w_b*r_a ...
+        # Active Weight * Asset Return (Truth Table Logic)
         df['active_weight'] = df['wp'] - df['wb']
-        df['contribution'] = df['active_weight'] * df['ret'] # Simple approx
+        df['contribution'] = df['active_weight'] * df['ret']
         
+        # Sort by active contribution
         sorted_contrib = df.sort_values(by='contribution', ascending=False)
-        top_contributors = sorted_contrib.head(5).index.tolist()
-        top_detractors = sorted_contrib.tail(5).index.tolist()
+        
+        def get_status(row):
+            if row['wp'] == 0.0 and row['wb'] > 0.0:
+                return "Excluded" 
+            elif row['wp'] > row['wb']:
+                return "Overweight"
+            elif row['wp'] < row['wb']:
+                return "Underweight"
+            else:
+                return "Neutral"
+
+        def build_truth_table(dataframe, n=5):
+            results = []
+            for ticker, row in dataframe.head(n).iterrows():
+                results.append({
+                    "Ticker": ticker,
+                    "Sector": row['sector'],
+                    "Status": get_status(row),
+                    "Active_Contribution": f"{row['contribution']:.4f}",
+                    "Return": f"{row['ret']:.2%}"
+                })
+            return results
+
+        # Top 5 Winners (Contributors) & Losers (Detractors)
+        top_contributors = build_truth_table(sorted_contrib, 5)
+        top_detractors = build_truth_table(sorted_contrib.sort_values(by='contribution', ascending=True), 5)
         
         # Narrative skeleton (to be filled by AI)
         narrative_raw = (

api/static/index.html

@@ -443,10 +443,29 @@
                 // For demo, we send "None" effectively.
             }
 
+            // Extract Max Weight (e.g. "limit to 2%", "max weight 5%")
+            let maxWeight = null;
+            // Matches: "limit... 2%" or "weight... 0.05"
+            // Simple Regex: Search for number followed optionally by %
+            const weightMatch = lowerInput.match(/(?:limit|max|weight).*?(\d+(?:\.\d+)?)\s*%/);
+            if (weightMatch) {
+                const val = parseFloat(weightMatch[1]);
+                if (val > 0) {
+                    maxWeight = val / 100.0; // Convert 2% -> 0.02
+                }
+            } else {
+                // Try decimal "0.05"
+                const decimalMatch = lowerInput.match(/(?:limit|max|weight).*?(\d+\.\d+)/);
+                if (decimalMatch) {
+                    maxWeight = parseFloat(decimalMatch[1]);
+                }
+            }
+
             const payload = {
                 "client_id": "Web_User",
                 "excluded_sectors": excluded,
                 "excluded_tickers": excludedTickers,
+                "max_weight": maxWeight,
                 "initial_investment": 100000
             };
 

core/schema.py

@@ -26,6 +26,7 @@ class OptimizationRequest(BaseModel):
     initial_investment: float = 100000.0
     excluded_sectors: List[str] = Field(default_factory=list, description="List of sectors to exclude (e.g., ['Energy'])")
     excluded_tickers: List[str] = Field(default_factory=list, description="List of specific tickers to exclude (e.g., ['AMZN'])")
+    max_weight: Optional[float] = Field(None, description="Maximum weight for any single asset (e.g., 0.05)")
     benchmark: str = "^GSPC"
 
     class Config:
@@ -92,6 +93,6 @@ class AttributionReport(BaseModel):
     allocation_effect: float
     selection_effect: float
     total_active_return: float
-    top_contributors: List[str]
-    top_detractors: List[str]
+    top_contributors: List[Dict]
+    top_detractors: List[Dict]
     narrative: str

data/optimizer.py

@@ -27,7 +27,8 @@ class PortfolioOptimizer:
                            benchmark_weights: pd.DataFrame,
                            sector_map: Dict[str, str],
                            excluded_sectors: List[str],
-                           excluded_tickers: List[str] = None) -> OptimizationResult:
+                           excluded_tickers: List[str] = None,
+                           max_weight: float = None) -> OptimizationResult:
         """
         Solves the tracking error minimization problem.
         
@@ -100,7 +101,11 @@ class PortfolioOptimizer:
         min_avg_weight = 1.0 / n_active
         dynamic_max = max(0.20, min_avg_weight * 1.5)
         
-        MAX_WEIGHT_LIMIT = dynamic_max
+        if max_weight and max_weight > min_avg_weight:
+             logger.info(f"Applying User-Defined Max Weight: {max_weight}")
+             MAX_WEIGHT_LIMIT = max_weight
+        else:
+             MAX_WEIGHT_LIMIT = dynamic_max
         logger.info(f"DEBUG: Active Assets={n_active}, Min Avg={min_avg_weight:.4f}, Dynamic Max Limit={MAX_WEIGHT_LIMIT:.4f}")
         
         constraints = [

debug_attribution_logic.py

@@ -0,0 +1,68 @@
+
+import pandas as pd
+from analytics.attribution import AttributionEngine
+
+def test_attribution_logic():
+    print("Testing Attribution Logic...")
+    
+    # Mock Data
+    # Scenario: 
+    # - AAPL: Overweight (Held 5%, Bench 4%). Return +10%. Should be Contributor.
+    # - MSFT: Excluded (Held 0%, Bench 6%). Return +10%. Should be Detractor (Missed Rally).
+    # - GOOG: Neutral (Held 2%, Bench 2%). Return -5%. Active Contrib 0.
+    portfolio_weights = {"AAPL": 0.05, "MSFT": 0.0, "GOOG": 0.02}
+    benchmark_weights = {"AAPL": 0.04, "MSFT": 0.06, "GOOG": 0.02}
+    
+    # Returns for the period
+    returns_data = {"AAPL": 0.10, "MSFT": 0.10, "GOOG": -0.05}
+    asset_returns = pd.Series(returns_data)
+    
+    sector_map = {
+        "AAPL": "Technology",
+        "MSFT": "Technology", 
+        "GOOG": "Communication Services"
+    }
+    
+    engine = AttributionEngine()
+    report = engine.generate_attribution_report(
+        portfolio_weights, 
+        benchmark_weights, 
+        asset_returns, 
+        sector_map
+    )
+    
+    print("\n--- Attribution Report Generated ---")
+    print(f"Total Active Return: {report.total_active_return:.4f}")
+    
+    print("\n[Top Contributors]")
+    for item in report.top_contributors:
+        print(item)
+        
+    print("\n[Top Detractors]")
+    for item in report.top_detractors:
+        print(item)
+        
+    # Validation Logic
+    # MSFT Active Weight = 0 - 0.06 = -0.06
+    # MSFT Active Contrib = -0.06 * 0.10 = -0.006 (Detractor)
+    
+    msft = next((x for x in report.top_detractors if x['Ticker'] == 'MSFT'), None)
+    if msft:
+        if msft['Status'] == "Excluded" and float(msft['Active_Contribution']) < 0:
+            print("\nSUCCESS: MSFT correctly identified as Excluded Detractor.")
+        else:
+            print(f"\nFAILURE: MSFT status/logic wrong: {msft}")
+    else:
+        print("\nFAILURE: MSFT not found in detractors.")
+
+    # AAPL Active Weight = 0.05 - 0.04 = +0.01
+    # AAPL Active Contrib = +0.01 * 0.10 = +0.001 (Contributor)
+    aapl = next((x for x in report.top_contributors if x['Ticker'] == 'AAPL'), None)
+    current_return = float(aapl['Active_Contribution']) if aapl else 0
+    if aapl and current_return > 0:
+         print("SUCCESS: AAPL correctly identified as Overweight Contributor.")
+    else:
+         print(f"FAILURE: AAPL logic wrong. {aapl}")
+
+if __name__ == "__main__":
+    test_attribution_logic()

debug_output.txt

@@ -0,0 +1,21 @@
+/opt/anaconda3/lib/python3.9/site-packages/pandas/core/computation/expressions.py:21: UserWarning: Pandas requires version '2.8.4' or newer of 'numexpr' (version '2.8.1' currently installed).
+  from pandas.core.computation.check import NUMEXPR_INSTALLED
+/opt/anaconda3/lib/python3.9/site-packages/pandas/core/arrays/masked.py:60: UserWarning: Pandas requires version '1.3.6' or newer of 'bottleneck' (version '1.3.4' currently installed).
+  from pandas.core import (
+Testing Attribution Logic...
+
+--- Attribution Report Generated ---
+Total Active Return: -0.0045
+
+[Top Contributors]
+{'Ticker': 'AAPL', 'Sector': 'Technology', 'Status': 'Overweight', 'Active_Contribution': '0.0010', 'Return': '10.00%'}
+{'Ticker': 'GOOG', 'Sector': 'Communication Services', 'Status': 'Neutral', 'Active_Contribution': '-0.0000', 'Return': '-5.00%'}
+{'Ticker': 'MSFT', 'Sector': 'Technology', 'Status': 'Excluded', 'Active_Contribution': '-0.0060', 'Return': '10.00%'}
+
+[Top Detractors]
+{'Ticker': 'MSFT', 'Sector': 'Technology', 'Status': 'Excluded', 'Active_Contribution': '-0.0060', 'Return': '10.00%'}
+{'Ticker': 'GOOG', 'Sector': 'Communication Services', 'Status': 'Neutral', 'Active_Contribution': '-0.0000', 'Return': '-5.00%'}
+{'Ticker': 'AAPL', 'Sector': 'Technology', 'Status': 'Overweight', 'Active_Contribution': '0.0010', 'Return': '10.00%'}
+
+SUCCESS: MSFT correctly identified as Excluded Detractor.
+SUCCESS: AAPL correctly identified as Overweight Contributor.

main.py

@@ -101,7 +101,8 @@ class QuantScaleSystem:
             benchmark_weights=benchmark_weights,
             sector_map=sector_map,
             excluded_sectors=request.excluded_sectors,
-            excluded_tickers=request.excluded_tickers
+            excluded_tickers=request.excluded_tickers,
+            max_weight=request.max_weight
         )
         
         if opt_result.status != "optimal":