feat(spp_simulation): add simulation engine for program scenario modeling

spp_simulation/README.rst

@@ -0,0 +1,141 @@
+.. image:: https://odoo-community.org/readme-banner-image
+   :target: https://odoo-community.org/get-involved?utm_source=readme
+   :alt: Odoo Community Association
+
+============================
+OpenSPP Targeting Simulation
+============================
+
+.. 
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:fd3e34b59c516e27a1d09522eca711429d907a328efb7a60b408f4edb71d552f
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Alpha-red.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Alpha
+.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
+    :alt: License: LGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OpenSPP%2FOpenSPP2-lightgray.png?logo=github
+    :target: https://github.com/OpenSPP/OpenSPP2/tree/19.0/spp_simulation
+    :alt: OpenSPP/OpenSPP2
+
+|badge1| |badge2| |badge3|
+
+Targeting Simulation & Fairness Analysis
+========================================
+
+Simulate targeting scenarios, analyze fairness and distribution, and
+compare different targeting strategies before committing to criteria.
+
+Key Features
+------------
+
+- **Scenario Builder**: Define targeting criteria using CEL expressions
+  with live preview counts
+- **Template Library**: Pre-built templates for common targeting
+  patterns (elderly pension, female-headed households, etc.)
+- **Distribution Analysis**: Gini coefficient, Lorenz curve, percentile
+  breakdown
+- **Fairness Analysis**: Disparity ratios across gender, disability,
+  location with traffic-light status indicators
+- **Targeting Efficiency**: Confusion matrix, leakage rate,
+  undercoverage against ideal populations
+- **Budget Simulation**: Fixed cap and proportional reduction strategies
+- **Scenario Comparison**: Side-by-side comparison of multiple targeting
+  approaches with overlap analysis
+- **Custom Metrics**: Define CEL-based aggregate, coverage, and ratio
+  metrics
+
+Privacy
+-------
+
+Only aggregated counts, percentages, and metrics are stored. No
+individual beneficiary records are persisted in simulation results.
+
+Models
+------
+
++--------------------------------------+----------------------------------+
+| Model                                | Description                      |
++======================================+==================================+
+| ``spp.simulation.scenario.template`` | Pre-built targeting scenario     |
+|                                      | templates                        |
++--------------------------------------+----------------------------------+
+| ``spp.simulation.scenario``          | Targeting scenario definitions   |
++--------------------------------------+----------------------------------+
+| ``spp.simulation.entitlement.rule``  | Amount calculation rules         |
++--------------------------------------+----------------------------------+
+| ``spp.simulation.run``               | Aggregated simulation results    |
+|                                      | (non-deletable)                  |
++--------------------------------------+----------------------------------+
+| ``spp.simulation.comparison``        | Side-by-side run comparisons     |
++--------------------------------------+----------------------------------+
+| ``spp.simulation.metric``            | Custom evaluation metrics        |
++--------------------------------------+----------------------------------+
+
+Security Groups
+---------------
+
+================== ===============================================
+Group              Access
+================== ===============================================
+Simulation Viewer  Read-only access to all simulation data
+Simulation Officer Create/edit scenarios, run simulations
+Simulation Manager Full access including comparisons and archiving
+================== ===============================================
+
+Menu Path
+---------
+
+Social Protection > Simulation > Scenarios / Results / Comparisons
+
+Configuration: Social Protection > Simulation > Configuration >
+Templates / Custom Metrics
+
+.. IMPORTANT::
+   This is an alpha version, the data model and design can change at any time without warning.
+   Only for development or testing purpose, do not use in production.
+   `More details on development status <https://odoo-community.org/page/development-status>`_
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OpenSPP/OpenSPP2/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us to smash it by providing a detailed and welcomed
+`feedback <https://github.com/OpenSPP/OpenSPP2/issues/new?body=module:%20spp_simulation%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Do not contact contributors directly about support or help with technical issues.
+
+Credits
+=======
+
+Authors
+-------
+
+* OpenSPP.org
+
+Maintainers
+-----------
+
+.. |maintainer-jeremi| image:: https://github.com/jeremi.png?size=40px
+    :target: https://github.com/jeremi
+    :alt: jeremi
+
+Current maintainer:
+
+|maintainer-jeremi| 
+
+This module is part of the `OpenSPP/OpenSPP2 <https://github.com/OpenSPP/OpenSPP2/tree/19.0/spp_simulation>`_ project on GitHub.
+
+You are welcome to contribute.

spp_simulation/__init__.py

@@ -0,0 +1,5 @@
+# Part of OpenSPP. See LICENSE file for full copyright and licensing details.
+
+from . import models
+from . import services
+from . import wizard

spp_simulation/__manifest__.py

@@ -0,0 +1,56 @@
+# pylint: disable=pointless-statement
+# Part of OpenSPP. See LICENSE file for full copyright and licensing details.
+{
+    "name": "OpenSPP Targeting Simulation",
+    "summary": "Simulate targeting scenarios, analyze fairness and distribution, "
+    "and compare different targeting strategies before committing to criteria.",
+    "category": "OpenSPP/Targeting",
+    "version": "19.0.2.0.0",
+    "author": "OpenSPP.org",
+    "website": "https://github.com/OpenSPP/OpenSPP2",
+    "license": "LGPL-3",
+    "development_status": "Alpha",
+    "maintainers": ["jeremi"],
+    "depends": [
+        "base",
+        "mail",
+        "spp_programs",
+        "spp_cel_domain",
+        "spp_cel_widget",
+        "spp_security",
+        "spp_aggregation",
+        "spp_metrics_core",
+    ],
+    "data": [
+        # Security
+        "security/simulation_security.xml",
+        "security/ir.model.access.csv",
+        # Data
+        "data/scenario_templates.xml",
+        # Views
+        "views/simulation_scenario_template_views.xml",
+        "views/simulation_scenario_views.xml",
+        "views/simulation_run_views.xml",
+        "views/simulation_comparison_views.xml",
+        "views/simulation_metric_views.xml",
+        "views/menu.xml",
+        # Wizard
+        "wizard/compare_wizard_views.xml",
+        # Report
+        "report/simulation_report_views.xml",
+        "report/simulation_report.xml",
+    ],
+    "assets": {
+        "web.assets_backend": [
+            "spp_simulation/static/src/results_summary/*",
+            "spp_simulation/static/src/fairness_table/*",
+            "spp_simulation/static/src/comparison_table/*",
+            "spp_simulation/static/src/overlap_table/*",
+        ],
+    },
+    "demo": [],
+    "images": [],
+    "application": True,
+    "installable": True,
+    "auto_install": False,
+}

spp_simulation/data/scenario_templates.xml

@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<odoo noupdate="1">
+    <record id="template_elderly_pension" model="spp.simulation.scenario.template">
+        <field name="name">Elderly Pension (Age 60+)</field>
+        <field
+            name="description"
+        >Target elderly individuals aged 60 and above for pension benefits.</field>
+        <field name="category">age</field>
+        <field name="target_type">individual</field>
+        <field name="targeting_expression">age_years(r.birthdate) >= 60</field>
+        <field name="default_amount">1000</field>
+        <field name="default_amount_mode">fixed</field>
+        <field name="icon">fa-hourglass-half</field>
+        <field name="sequence">10</field>
+    </record>
+
+    <record id="template_children_under_5" model="spp.simulation.scenario.template">
+        <field name="name">Households with Children Under 5</field>
+        <field
+            name="description"
+        >Target households that have at least one child under 5 years of age.</field>
+        <field name="category">age</field>
+        <field name="target_type">group</field>
+        <field
+            name="targeting_expression"
+        >members.any(m, age_years(m.birthdate) &lt; 5)</field>
+        <field name="default_amount">500</field>
+        <field name="default_amount_mode">fixed</field>
+        <field name="icon">fa-child</field>
+        <field name="sequence">20</field>
+    </record>
+
+    <record id="template_female_headed" model="spp.simulation.scenario.template">
+        <field name="name">Female-Headed Households</field>
+        <field
+            name="description"
+        >Target households where the head of household is female.</field>
+        <field name="category">vulnerability</field>
+        <field name="target_type">group</field>
+        <field name="targeting_expression">is_female(head.gender_id)</field>
+        <field name="default_amount">750</field>
+        <field name="default_amount_mode">fixed</field>
+        <field name="icon">fa-female</field>
+        <field name="sequence">30</field>
+    </record>
+
+    <record id="template_rural_households" model="spp.simulation.scenario.template">
+        <field name="name">Rural Households</field>
+        <field name="description">Target households located in rural areas.</field>
+        <field name="category">geographic</field>
+        <field name="target_type">group</field>
+        <field name="targeting_expression">has_area_tag('RURAL')</field>
+        <field name="default_amount">600</field>
+        <field name="default_amount_mode">fixed</field>
+        <field name="icon">fa-tree</field>
+        <field name="sequence">40</field>
+    </record>
+
+    <record id="template_disability_targeted" model="spp.simulation.scenario.template">
+        <field name="name">Disability-Targeted</field>
+        <field
+            name="description"
+        >Target households with at least one member with a disability.</field>
+        <field name="category">vulnerability</field>
+        <field name="target_type">group</field>
+        <field
+            name="targeting_expression"
+        >members.any(m, m.disability_id != false)</field>
+        <field name="default_amount">800</field>
+        <field name="default_amount_mode">fixed</field>
+        <field name="icon">fa-wheelchair</field>
+        <field name="sequence">50</field>
+    </record>
+
+    <record id="template_large_households" model="spp.simulation.scenario.template">
+        <field name="name">Large Households (5+ Members)</field>
+        <field
+            name="description"
+        >Target households with 5 or more members. Amount scales with household size.</field>
+        <field name="category">categorical</field>
+        <field name="target_type">group</field>
+        <field name="targeting_expression">size(members) >= 5</field>
+        <field name="default_amount">200</field>
+        <field name="default_amount_mode">multiplier</field>
+        <field name="icon">fa-users</field>
+        <field name="sequence">60</field>
+    </record>
+</odoo>