Project-Specific Context: Pluggable Intelligence Strategies

This file describes the pluggable intelligence strategy pattern used by the Policy Intelligence Engine and how to add a new check or strategy.

---

1. Overview

• IntelligenceStrategy (protocol in logic/intelligence_strategies/base.py):
  Contract for a single analytics “strategy” that runs on the policy repository and writes results into the overlay.

• PolicyIntelligenceEngine (logic/policy_intelligence.py):
  Holds a registry of strategies and runs them in a fixed order via run_all(enabled_strategy_ids=None, params=None).

• Settings (“Recommendation / Consolidation”):
  User can enable/disable each strategy via checkboxes; the list is persisted as enabled_intelligence_checks (list of strategy_ids; None or [] = all enabled).

• Recommendations tab:
  Calls policy_intelligence.run_all(enabled_strategy_ids=..., params=...) with params (e.g. risk reduction %, consolidation strategy names for workbench cross-link).

The same coding standards and pattern as the Consolidation Workbench strategies apply: protocol in base, implementations in separate modules, engine does not depend on concrete classes in its public API.

---

2. Strategy Protocol and Overlay Contract

Each strategy has:

• strategy_id (str): Unique machine-readable id (e.g. 'risk_scores', 'invalid_statements'). Used in settings and run order.

• display_name (str): Human-readable name for Settings checkboxes and UI.

• category (str): One of 'risk', 'overlap', 'cleanup', 'consolidation_suggestion', 'recommendation'. Used for grouping and run order.

• run(repo, overlay, params) (method): Runs the strategy and mutates overlay. Receives params (e.g. where_clause_reduction_pct, engine reference for compartment index, consolidation_strategy_names).

Overlay keys by category:

Category	Overlay key / shape
risk	overlay['risk_scores'] (list of dicts)
overlap	overlay['overlaps'] (list)
cleanup	overlay.setdefault('cleanup_items', {})[strategy_id] = ... (one key per cleanup strategy)
consolidation_suggestion	overlay['consolidations'] (list of dicts)
recommendation	overlay['recommendations'] (list of dicts)

Run order is fixed in the engine (DEFAULT_STRATEGY_RUN_ORDER) so that e.g. cleanup runs before recommendations (recommendations aggregate cleanup and consolidation).

---

3. How to Add a New Intelligence Check

1. Implement the strategy

   • Create a new module under logic/intelligence_strategies/ (e.g. cleanup_my_check.py).

   • Implement the IntelligenceStrategy protocol: strategy_id, display_name, category, and run(repo, overlay, params).

   • For cleanup: write to overlay.setdefault('cleanup_items', {})[self.strategy_id] = <list>.

   • For other categories: write to the appropriate overlay key (see table above).

   • Use the same style (dataclass, docstrings, logger) as existing strategies in logic/intelligence_strategies/.

2. Register the strategy

   • In logic/intelligence_strategies/__init__.py:

     • Import the new strategy class.

     • Add an instance to the list returned by get_default_intelligence_strategies() in the correct position (e.g. cleanup strategies together, before OverallRecommendationStrategy).

   • Add the new strategy_id to DEFAULT_STRATEGY_RUN_ORDER in logic/policy_intelligence.py in the desired position.

3. Settings

   • The Settings tab builds checkboxes from policy_intelligence.get_strategies_for_settings(), which returns all registered strategies in run order. No hand-wiring needed: the new strategy will appear as a checkbox in “Recommendation / Consolidation” once registered.

4. Recommendations tab

   • If the new strategy writes to an existing overlay key (e.g. cleanup_items[my_check]), the existing Cleanup/Fix tab logic that iterates over cleanup.get('invalid_statements', []), etc. will need to handle the new key (e.g. add a branch in _get_cleanup_issues() for cleanup.get('my_check', []) and the columns/labels for that type).

   • If the new strategy introduces a new overlay key or subtab, add the corresponding table/section and read from that key.

5. Optional: discovery

   • To avoid editing __init__.py for every new strategy, you could add a registry pattern (e.g. strategies register themselves via a decorator or entry point). The current design keeps the default list explicit in get_default_intelligence_strategies().

---

4. Consolidation Workbench Cross-Link

• When consolidation opportunities are present, the overall recommendations strategy adds a recommendation that directs the user to the Consolidation Workbench and suggests strategy names (e.g. “Consider Move to Root Compartment or Statement Density (Pack Policies)”).

• Strategy names are passed into the engine via params['consolidation_strategy_names'], which the recommendations tab sets from app.consolidation_engine.get_strategy_display_names() so the intelligence layer does not depend on the consolidation engine instance.

---

5. Key Files

Purpose	Path
Protocol	logic/intelligence_strategies/base.py
Default strategy list	logic/intelligence_strategies/__init__.py (get_default_intelligence_strategies)
Run order	logic/policy_intelligence.py (DEFAULT_STRATEGY_RUN_ORDER)
Engine registry	logic/policy_intelligence.py (run_all, register_strategy, get_strategies_for_settings)
Settings UI	ui/settings_tab.py (“Recommendation / Consolidation” frame)
Invocation	ui/policy_recommendations_tab.py (reload_all_analytics → run_all)