causalex 0.0.0

A modular, source-available simulation engine for sovereign policy orchestration, using structural causal graphs (DAGs) to model systemic economic trade-offs.

🏛️ Causalex

A modular, source-available simulation engine for sovereign policy orchestration, using structural causal graphs (DAGs) to model systemic economic trade-offs.

Government Policy Simulation Framework

Causalex is a data-private, modular, source-available simulation engine designed for states, central planners, and public policy institutions. Utilizing Judea Pearl's structural causal frameworks and Directed Acyclic Graphs (DAGs), it allows sovereign entities to simulate the systemic trade-offs of major economic interventions—such as Universal Basic Income (UBI) rollouts, automation taxation, and wealth fund sterilization—without compromising national data security.

Unlike traditional black-box machine learning models or rigid econometric frameworks, Causalex contains NO pre-trained weights, NO built-in data, and NO statistical assumptions about your economy. It is a pure, object-oriented execution sandbox: you bring your own local data, snap together your specific sector plugins, and evaluate policy levers transparently.

---

Key Design Philosophy

• Absolute Data Sovereignty (BYOD): Designed to run entirely in air-gapped, on-premises government networks. Your registries, tax data, and census records never phone home or leave your secure infrastructure.

• Zero-Data Architecture: The core repository is an empty mathematical shell. It provides the graph execution environment, time-lagged loop handling, and validation metrics, leaving the statistical estimation entirely to local teams.

• Radical Transparency: Every causal link is an explicit, readable line of code. Policy decisions can be fully audited down to the exact mathematical equation erning a specific node, eliminating the liability of algorithmic bias.

• The Freedom Parameter: The framework does not attempt to centrally plan prices or manage individual business operations. It focuses on isolating target nodes (e.g., poverty headcounts and baseline purchasing power) while letting intermediate market dynamics flow naturally.

---

✨ Core Principles

🔌 Plug-and-Play Architecture

Causalex is built around independent modules.

Add, remove, or replace sectors, policies, economic mechanisms, and evaluation metrics without modifying the core engine.

from causalex import Simulation

sim = Simulation()

sim.add_module(Taxation())
sim.add_module(Welfare())
sim.add_module(LaborMarket())

results = sim.run(years=10)

---

🐍 Simple Python-First Design

Policy models are written using straightforward Python code.

No domain-specific language. No proprietary tooling. No hidden execution logic.

If you know Python, you can build simulations.

@node
def household_income(wages, transfers):
    return wages + transfers

---

🧩 Modular by Default

Every component is self-contained.

Examples include:

• Tax systems
• Welfare programs
• Labor markets
• Housing systems
• Healthcare systems
• Education systems
• Energy infrastructure
• Industrial policy
• Demographic models
• Environmental systems

Organizations can develop their own internal libraries of reusable policy modules.

---

🔍 Fully Transparent

Every relationship, equation, and assumption remains visible and auditable.

Causalex does not hide decision logic behind black-box models.

Users can inspect:

• Causal relationships
• Equations
• Assumptions
• Dependencies
• Policy interventions
• Simulation outputs

This makes peer review, auditing, and regulatory oversight significantly easier.

---

🔒 Data Sovereignty

Causalex ships with:

• No built-in datasets
• No telemetry
• No external services
• No model weights
• No cloud dependency

Your data remains under your control.

Deploy locally, on-premises, or within air-gapped environments.

---

🏗️ Architecture

Causalex models systems as interconnected graphs of policy-relevant entities.

[ Policy Levers ]
        │
        ▼
[ System Dynamics ]
        │
        ▼
[ Outcomes ]

Examples:

Tax Rate
    ↓
Business Investment
    ↓
Employment
    ↓
Household Income

or

Infrastructure Spending
           ↓
Construction Activity
           ↓
Regional Productivity
           ↓
Economic Growth

Users define the relationships; Causalex manages execution.

---

⏳ Time-Based Simulation

Real-world systems evolve over time.

Causalex supports discrete simulation horizons, allowing users to model:

• Monthly dynamics
• Quarterly dynamics
• Annual dynamics
• Multi-decade projections

results = sim.run(years=25)

This enables analysis of both immediate and long-term consequences of policy interventions.

---

🔄 Scenario Analysis

Evaluate alternative futures by changing assumptions or interventions.

Examples:

Baseline

tax_rate = 15

Scenario A

tax_rate = 25

Scenario B

tax_rate = 35

Compare outcomes side-by-side and identify trade-offs before implementation.

---

🧪 Counterfactual Simulation

Ask questions such as:

• What if a tax reform had never occurred?
• What if infrastructure spending doubled?
• What if a subsidy program was removed?
• What if automation accelerated faster than expected?

Causalex makes it possible to evaluate alternative policy trajectories in a controlled simulation environment.

---

🚀 Quick Start

Install:

pip install causalex

Create a simulation:

from causalex import Simulation

sim = Simulation()

# Add modules
sim.add_module(Taxation())
sim.add_module(Welfare())

# Run simulation
results = sim.run(years=10)

print(results)

---

📦 Example Use Cases

Public Sector

• Economic policy analysis
• Tax reform evaluation
• Welfare program design
• Industrial strategy
• Infrastructure planning
• Energy transition planning
• Healthcare policy

Research Institutions

• Public policy research
• Academic modeling
• Scenario analysis
• Comparative institutional studies

International Organizations

• Development planning
• Impact evaluation
• Long-term forecasting

---

🔨 Extensibility

Create your own module:

from causalex import Module

class CarbonTax(Module):

    def apply(self, state):
        emissions = state["emissions"]
        tax_rate = state["carbon_tax"]

        state["revenue"] += emissions * tax_rate

        return state

Register and use immediately.

sim.add_module(CarbonTax())

No core modifications required.

---

📜 Licensing & Legal Status

Causalex is published under a Dual-License Framework to balance community transparency with sovereign data privacy, while keeping the core engine completely free of financial cost.

1. The Community Tier (GNU AGPL v3)

For researchers, universities, non-commercial projects, and public experimentation, Causalex is completely open-source under the GNU Affero General Public License v3 (AGPL-3.0).

• The Copyleft Constraint: Any derivative work, plugin library, or internal system built using this core engine that is executed over a network must have its full source code made publicly available under the same AGPL license.

2. The Sovereign Government Tier (Zero-Cost Private License)

Because sovereign states and public ministries cannot legally or securely publish their internal infrastructure pipelines to the public internet, Causalex provides an alternative Private Institutional License.

• Zero Financial Cost: This license is entirely free. There are no tier structures, no enterprise paywalls, and no contract renewals. Internal state data teams can clone and deploy the engine privately on air-gapped networks without procurement friction.
• The Condition: While it costs zero financial capital, this private license is completely conditional and non-transferable.

🛡️ The Absolute Right of Refusal & Revocation

The Author retains 100% copyright ownership of the core framework under both licensing tiers.

• Unilateral Veto: The Author explicitly reserves the unconditional right to refuse, deny, or immediately revoke usage, deployment, and execution rights to any individual, corporate entity, or sovereign state at their sole discretion via written notice or repository ban.
• Upstream Contributions: All pull requests or optimizations contributed to this core engine require the execution of a Contributor License Agreement (CLA). This ensures that central copyright and veto rights permanently and exclusively remain with the Author.

For the exact legal terms governing reproduction, modification, and execution, see the full LICENSE.md file in the root of this repository.

---

🎯 Project Goals

Causalex aims to provide a transparent and extensible foundation for policy simulation that is:

• Easy to understand
• Easy to modify
• Easy to deploy
• Easy to audit
• Difficult to lock into

By keeping the core framework lightweight, modular, and Python-native, Causalex enables institutions to focus on policy design rather than software complexity.

---

⚠️ Disclaimer

Causalex is a simulation framework, not an oracle.

Simulation outputs depend entirely on:

• Model structure
• Assumptions
• Input data
• Calibration methods

Policy decisions should always incorporate domain expertise, empirical evidence, and independent review.

---

Build policies before deploying them. Simulate consequences before creating them.