An operational decision intelligence framework that stress-tests policies under uncertainty, demand shocks, and tail-risk scenarios.

Design Philosophy: Decision quality is defined by robustness under failure — not average performance. POLARIS is built to surface tradeoffs, not hide them.

• 🔁 Multi-policy simulation engine comparing human heuristics, conservative strategies, and constrained RL
• 🌪️ Chaos injection with demand spikes and black swan events
• 📊 Bayesian demand modeling with worst-case estimation
• ⚠️ Risk-aware metrics: CVaR, regret, and expected cost
• 🛑 Human-in-the-loop DecisionGovernor that throttles unsafe orders
• 🗃️ DuckDB analytics pipeline — single source of truth for all runs, metrics, and policy registry
• 📋 Governance framework with explicit failure documentation and traceable decisions

Results vary across runs by design — POLARIS simulates random demand to stress-test policies under uncertainty. But the pattern holds consistently:

RL consistently wins on average cost. The Heuristic consistently wins on tail risk (CVaR). The tradeoff is structural, not a fluke — it holds regardless of the random scenario generated.

The right policy depends on your risk appetite, not just your average performance. POLARIS is built to surface exactly this tension.

polaris/
├── inspect_db.py         # Utility to query and inspect stored results
├── GOVERNANCE.md         # Governance framework and policy documentation
├── README.md
├── requirements.txt
│
├── src/
│   ├── main.py           # Entry point — runs all scenarios and stores results
│   ├── env.py            # Inventory environment (step, cost, stockout logic)
│   ├── simulator.py      # Core simulation loop
│   ├── policies.py       # Human heuristic and AI policy definitions
│   ├── rl.py             # Q-learning policy with tabular state space
│   ├── bayes.py          # Bayesian demand estimator with worst-case projection
│   ├── chaos.py          # Chaos engine — demand spikes and black swan events
│   ├── governor.py       # Human-in-the-loop decision governor
│   ├── learning.py       # Volatility risk band classifier
│   ├── risk.py           # CVaR and tail risk calculations
│   └── db.py             # DuckDB connection and schema initialization
│
├── data/
│   └── polaris.duckdb    # Persistent simulation database
│
└── results/
    ├── simulation_results.csv
    ├── executive_summary.csv
    └── constraint_summary.csv

1. Clone the repository

git clone https://github.com/SWARNIM-TIWARI/polaris.git
cd polaris

2. Create a virtual environment (recommended)

python -m venv venv

3. Activate the virtual environment

• Windows (PowerShell):

  .\venv\Scripts\Activate.ps1

• Windows (CMD):

  .\venv\Scripts\activate.bat

• macOS/Linux:

  source venv/bin/activate

4. Install dependencies

pip install -r requirements.txt

5. Run the simulation

python src/main.py

Note: polaris.duckdb is not included in the repo. Running python src/main.py will automatically generate it inside the data/ folder on first run.

6. Inspect stored results

python inspect_db.py

Demand Scenarios (baseline / high_volatility)
         ↓
   Chaos Engine
   (spikes, black swans)
         ↓
  Bayesian Demand Model
  (worst-case estimation)
         ↓
  ┌──────────────────────────┐
  │  Policy Engine           │
  │  Heuristic | RL_Constrained │
  └──────────────────────────┘
         ↓
  Decision Governor
  (human-in-the-loop throttle)
         ↓
  Inventory Environment
  (cost, stockout, inventory)
         ↓
  DuckDB — runs, daily_metrics, policies

All scenarios include probabilistic demand spikes (5% chance per day) and a simulated black swan window (days 120–130).

POLARIS follows five core governance principles:

1. Policies are explicit and versioned in the database
2. Simulations are traceable with scenario labels
3. DuckDB is the single source of truth
4. Failures are surfaced, not hidden
5. Any automation requires human approval

See GOVERNANCE.md for the full framework including policy table, metrics definitions, and future extensions.

These are documented intentionally:

• RL policy uses a simple tabular Q-learner — not suitable for continuous or high-dimensional state spaces
• Bayesian updater uses exponential smoothing, not a full posterior — fast but approximate
• Fairness and equity considerations across supply chain stakeholders are not modeled
• This system is intended for educational and research purposes, not live operational deployment

• FastAPI endpoints for policy evaluation via REST API
• Airflow pipelines for scheduled compliance and stress-testing
• Cloud deployment (AWS/Azure) for enterprise-scale decision intelligence
• Role-based access control and audit logging

This project is licensed under the MIT License.

Built to demonstrate that constraints, governance, and failure awareness matter as much as model performance in real operational systems. Built to demonstrate that constraints, governance, and failure awareness matter as much as model performance in real operational systems.