diff --git a/modules/policy-simulator/README.md b/modules/policy-simulator/README.md index 1d9ebce..770efa9 100644 --- a/modules/policy-simulator/README.md +++ b/modules/policy-simulator/README.md @@ -1,4 +1,130 @@ -# Policy Simulator / Fiscal Evaluation -Owner: Andrés Gerli Milian -Goal: run_scenario → KPIs/plots/brief + 2–3 demo scenarios. +# Policy Simulator / Fiscal Evaluation +**Owner:** Andrés Gerli Milian +**Goal:** `run_scenario` → KPIs/plots/brief + 2–3 demo scenarios. +This module is a **policy scenario simulator microservice** focused on business taxation and its effects on **firm dynamics** and **labour outcomes**. + +--- + +## 1) Overview & Scope + +### What this module does (MVP) +The MVP provides a Dockerised FastAPI service that: + +- Accepts a **scenario JSON** (country, sector, time window, tax parameters, run params). +- Returns: + - A **KPI table** (birth/death/net formation, employment index, salary index). + - **Artifact paths** (at least one PNG plot, plus a JSON/Markdown brief). + - A structured **policy brief** (JSON object). + +**Important:** The MVP uses **deterministic dummy logic** (not the final ABM). The goal is to lock the **interface contract** and enable early integration into OpenPolicyStack. + +### Out of scope (later; not implemented in MVP) +- Real ETL from Eurostat / DG TAXUD / OECD / ECB. +- The full ABM of firm entry/exit and hiring. +- DiD/event-study validation around real reforms. + +(These items are intentionally excluded from this MVP to keep it integration-ready and realistic.) + +--- + +## 2) Inputs + +### 2.1 Scenario parameters (required) +`POST /run_scenario` expects a JSON request body: + +| Field | Type | Required | Default | Notes | +|---|---:|---:|---:|---| +| `country` | string | yes | — | ISO 3166-1 alpha-2 (e.g., "FR", "SE", "DE", "NL"). MVP accepts any 2-letter string. | +| `sector` | string | yes | — | MVP: "manufacturing" or "market_services". | +| `start_year` | int | yes | — | Analysis window start year (metadata + future ETL slice). | +| `end_year` | int | yes | — | Analysis window end year (metadata + future ETL slice). | +| `employer_payroll_tax_rate` | float | yes | — | Employer social contributions as a share of gross wage (0–1). | +| `employee_payroll_tax_rate` | float | yes | — | Employee social contributions as a share of gross wage (0–1). | +| `cit_rate` | float | yes | — | Corporate income tax rate (0–1). | +| `seed` | int | no | 42 | Ensures deterministic simulation and artifacts. | +| `timesteps` | int | no | 12 | Number of simulated periods (MVP: for plotting only). | + +### 2.2 Optional calibration reference +The MVP accepts this object to align with future integration, though it does not use it yet: + +```json +"calibration": { + "baseline_year": 2010, + "tax_source": "dummy", + "kpi_source": "dummy" +} +``` +--- + +## 3) How to run + +This module is built with **Python 3.10+** and **FastAPI**. It can be run locally for development or as a containerized service. + +### 3.1 Docker +To ensure the environment matches the production target: + +```bash +# 1. Build the image +docker build -t policy-simulator . + +# 2. Run the container (mapping port 8000) +docker run -p 8000:8000 policy-simulator +``` +### 3.2 Local Development +```bash +# 1. Create a virtual environment +python -m venv venv +source venv/bin/activate # On Windows use: venv\Scripts\activate + +# 2. Install dependencies +pip install -r requirements.txt + +# 3. Run the server (with hot-reload) +uvicorn main:app --reload +``` + +## 4) Example Scenario + +To test the POST /run_scenario endpoint, you can use the Swagger UI or the following curl command. + +### 4.1 Sample JSON Payload +Matches the schema defined in Section 2. + +```json +{ + "country": "FR", + "sector": "manufacturing", + "start_year": 2024, + "end_year": 2026, + "employer_payroll_tax_rate": 0.25, + "employee_payroll_tax_rate": 0.15, + "cit_rate": 0.25, + "seed": 12345, + "timesteps": 12, + "calibration": { + "baseline_year": 2023, + "tax_source": "dummy_defaults", + "kpi_source": "dummy_defaults" + } +} +``` +### 4.2 CURL Command + +```bash +curl -X 'POST' \ + 'http://localhost:8000/run_scenario' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "country": "FR", + "sector": "manufacturing", + "start_year": 2024, + "end_year": 2026, + "employer_payroll_tax_rate": 0.25, + "employee_payroll_tax_rate": 0.15, + "cit_rate": 0.25, + "seed": 12345, + "timesteps": 12 +}' +``` diff --git a/modules/supplychain-risk/README.md b/modules/supplychain-risk/README.md index 9217f8c..2e5cbfc 100644 --- a/modules/supplychain-risk/README.md +++ b/modules/supplychain-risk/README.md @@ -1,4 +1,50 @@ -# Supply-Chain Risk (Quantum tech) +# Supply-Chain Risk (Quantum tech) Owner: Karl M. Kohler -Goal: /score, /brief + demo dataset. + +## Scope +This module provides a first-order supply-chain risk assessment for quantum-technology components and segments. It is designed as an +independent micro-service within OpenPolicyStack, returning a simple risk score, key drivers, and a short policy-oriented brief for +scenario analysis. + +The MVP focuses on reproducibility and a clear interface rather than +final data or models. + +## Inputs (MVP) +- country_or_region + Target economy or region (e.g. EU, US, China). +- segment_or_component + Quantum-technology segment or component (e.g. cryogenics, photonics, + ion-trap components, control electronics). +- optional: scenario + High-level disruption or policy scenario (e.g. export restriction, + supplier disruption). +- optional: year / time window + +## Outputs (MVP) +- risk_score + Relative risk score (0–100). +- risk_level + Categorical label (Low / Medium / High). +- key_drivers + Main contributing factors (e.g. supplier concentration, + geo-exposure, regulatory risk). +- brief + Short text explanation suitable for a policy dashboard or demo. + +## How to run (MVP) +Preferred interface:I chose API. + +My MVP will expose a minimal API endpoint that takes (country_or_region, segment_or_component, optional scenario) and returns the outputs above. Data sources and scoring logic will of course be refined in later phases. + +## Example scenario +Input: +- country_or_region: EU +- segment_or_component: quantum cryogenic systems +- scenario: export restriction + +Output: +- risk_score: 80 +- risk_level: High +- key_drivers: supplier concentration, limited substitution, regulatory exposure +- brief: Short summary of vulnerabilities and potential mitigation options.