krl-frameworks 0.1.0

Enterprise-grade meta-framework orchestration for socioeconomic analysis with deterministic CBSS pipelines

KRL Frameworks

Enterprise-grade meta-framework orchestration platform for socioeconomic analysis with deterministic CBSS pipelines.

Overview

KRL Frameworks provides a unified orchestration layer for 69 meta-frameworks across 6 vertical layers:

Layer	Tier	Frameworks	Count
Layer 1: Socioeconomic/Academic	Community+	MPI, HDI, SPI, GII, IHDI, NRI, WBI, IAM, SAM-CGE, CGE-Microsim, Spatial Causal Index	12
Layer 2: Government/Policy	Professional	CBO Scoring, OMB PART, GAO GPRA, Policy Diffusion, Regulatory Impact, Legislative Effectiveness, City Resilience, MPI Operational, Interagency Spatial Causal	9
Layer 3: Experimental/Research	Team/Enterprise	RCT, DiD, Synthetic Control, RDD, IV, PSM, Bunching, Event Study, TWFE, DML, Bayesian Causal, ML Causal, Timeseries Causal, SD-ABM, Spatial Causal, Multilayer Network	16
Layer 4: Financial/Economic	Enterprise	Basel III, CECL, Stress Testing, Systemic Risk, Credit Risk, Market Risk, Liquidity Risk, DSGE, HANK, Macro-Financial CGE, Networked Financial, Risk Indices, Composite Risk, Financial Meta Orchestrator	13
Layer 5: Arts/Media	Professional+	Cultural Impact, Media Reach, Creative Economy, Audience ABM, Content Valuation, IP Valuation, Platform Economics, Cultural Equity, Cultural CGE, Media Impact, Integrated Cultural	11
Layer 6: Meta/Peer	Enterprise	REMSOM, ABM, CGE, IO Tables, IAM Policy Stack, HDI-MPI Dashboard, SPI Policy Stack	7

Total: 69 frameworks with full CBSS simulation capabilities and dashboard integration.

Key Features

• Deterministic CBSS Execution: Cohort-Based State Simulation with vectorized NumPy pipelines
• DAG Orchestration: Cross-layer causal graph composition with topological execution
• Peer Architecture: All meta-frameworks operate as equal peers (no hierarchy)
• Tier Gating: Community/Professional/Team/Enterprise access control
• Adapter Pattern: Seamless integration with krl-causal-policy-toolkit, krl-geospatial-tools, krl-network-analysis
• Explicit Data Injection: DataBundle pattern for controlled data flow via krl-data-connectors
• Backend Integration: Remote execution with TCU billing via /api/v1/frameworks/*

Installation

pip install krl-frameworks

With optional dependencies:

pip install krl-frameworks[all]          # Full installation with all integrations
pip install krl-frameworks[dev]          # Development tools
pip install krl-frameworks[causal]       # krl-causal-policy-toolkit integration
pip install krl-frameworks[geospatial]   # krl-geospatial-tools integration
pip install krl-frameworks[network]      # krl-network-analysis integration
pip install krl-frameworks[connectors]   # krl-data-connectors integration

Quick Start

Basic Framework Usage

from krl_frameworks import DataBundle, FrameworkConfig
from krl_frameworks.layers.socioeconomic import MPIFramework

# Create data bundle with required domains
bundle = DataBundle.from_dataframes({
    "health": health_df,
    "education": education_df,
    "income": income_df,
})

# Initialize and execute framework
mpi = MPIFramework()
mpi.fit(bundle)
result = mpi.simulate(steps=10)

# Access results
print(f"MPI: {result.metrics['mpi']:.3f}")
print(f"Final opportunity score: {result.state.opportunity_score.mean():.3f}")

DAG Pipeline Orchestration

from krl_frameworks import FrameworkDAG, PipelineBuilder
from krl_frameworks.layers import MPIFramework, HDIFramework, REMSOMFramework

# Build cross-framework pipeline
builder = PipelineBuilder()
builder.add_framework("mpi", MPIFramework())
builder.add_framework("hdi", HDIFramework())
builder.add_framework("remsom", REMSOMFramework())

# Define data flow
builder.connect("mpi", "remsom", mapping={"mpi_score": "input_mpi"})
builder.connect("hdi", "remsom", mapping={"hdi_score": "input_hdi"})

# Execute pipeline
dag = builder.build()
results = dag.execute(bundle)

Advanced Transitions

from krl_frameworks.simulation import (
    MarkovTransition,
    MarkovConfig,
    EnsembleTransition,
    LinearTransition,
)

# Create Markov chain transition
P = np.array([
    [0.8, 0.15, 0.05],
    [0.1, 0.7, 0.2],
    [0.05, 0.15, 0.8]
])
config = MarkovConfig(n_states=3, state_names=["Low", "Medium", "High"])
markov = MarkovTransition(P, config)

# Create ensemble of multiple transitions
ensemble = EnsembleTransition([markov, LinearTransition()])

# Use in CBSS engine
engine = CBSSEngine(transition=ensemble)
trajectory = engine.run(initial_state, steps=20)

Framework Layers

Implementation Status Legend:

• 🟢 Production — Full domain-specific logic, complete CBSS integration
• 🟡 Beta — Working CBSS integration, generic transitions (Phase II enhancements planned)
• 🔴 Planned — Stub implementation, interface locked

Layer 1: Socioeconomic/Academic (Community+)

Framework	Status	Description	Key Methods
MPIFramework	🟢	Multidimensional Poverty Index (Alkire-Foster)	compute(), decompose()
HDIFramework	🟢	Human Development Index (UNDP methodology)	compute(), project()
SPIFramework	🟢	Social Progress Index	analyze()
GIIFramework	🟡	Gender Inequality Index	compute(), decompose()
IHDIFramework	🟡	Inequality-adjusted HDI	compute(), adjust()
NRIFramework	🟡	Network Readiness Index	score(), benchmark()
WBIFramework	🟡	World Bank Indicators Composite	aggregate(), compare()

Layer 2: Government/Policy (Professional)

Framework	Status	Description	Key Methods
CBOScoringFramework	🟢	CBO Budget Scoring (PAYGO, dynamic)	score_legislation(), dynamic_score()
OMBPartFramework	🟢	OMB PART Assessment	assess_program(), benchmark_programs()
GAOGpraFramework	🟢	GAO GPRA Analysis	analyze_agency(), assess_measure_quality()
PolicyDiffusionFramework	🟡	State Policy Diffusion Analysis	track_adoption(), predict_spread()
RegulatoryImpactFramework	🟡	Regulatory Impact Assessment	assess_costs(), benefit_analysis()
LegislativeEffectivenessFramework	🟡	Legislative Effectiveness Scoring	score_legislator(), track_bills()

Layer 3: Experimental/Research (Team/Enterprise)

Framework	Status	Description	Key Methods
RCTFramework	🟢	Randomized Controlled Trials (ITT, HTE)	analyze(), analyze_heterogeneous_effects()
DiDFramework	🟢	Difference-in-Differences (Callaway-Sant'Anna)	estimate(), event_study()
SyntheticControlFramework	🟢	Synthetic Control Method	estimate(), placebo_test()
RegressionDiscontinuityFramework	🟡	Sharp/Fuzzy RDD	estimate(), bandwidth_select()
InstrumentalVariablesFramework	🟡	IV/2SLS Estimation	estimate(), weak_iv_test()
PropensityScoreFramework	🟡	PSM/IPW Methods	match(), estimate_ate()
BunchingEstimatorFramework	🟡	Bunching at Kinks/Notches	estimate_elasticity()

Layer 4: Financial/Economic (Enterprise)

Framework	Status	Description	Key Methods
BaselIIIFramework	🟢	Basel III Capital Adequacy (RWA, LCR, NSFR)	compute_ratios(), project_capital()
CECLFramework	🟢	CECL Credit Loss (PD/LGD)	calculate_acl(), vintage_analysis()
StressTestFramework	🟢	CCAR/DFAST Stress Testing	run_dfast(), run_ccar(), calculate_scb()
SystemicRiskFramework	🟡	Systemic Risk Metrics (CoVaR, MES)	compute_covar(), network_contagion()
CreditRiskFramework	🟡	Credit Portfolio Risk	compute_var(), expected_shortfall()
MarketRiskFramework	🟡	Market Risk (VaR, Greeks)	compute_var(), stress_scenarios()
LiquidityRiskFramework	🟡	Liquidity Coverage Analysis	compute_lcr(), runoff_analysis()

Layer 5: Arts/Media (Professional+)

Framework	Status	Description	Key Methods
CulturalImpactFramework	🟢	Cultural Impact Assessment (7 dimensions)	assess_impact(), compare_communities()
MediaReachFramework	🟢	Media Reach Analysis	analyze_reach(), calculate_attribution()
CreativeEconomyFramework	🟢	Creative Economy Impact	measure_impact(), project_growth()
AudienceAnalyticsFramework	🟡	Audience Segmentation & Analytics	segment(), predict_engagement()
ContentValuationFramework	🟡	Content Library Valuation	value_catalog(), forecast_revenue()
IPPortfolioFramework	🟡	IP Portfolio Analysis	assess_portfolio(), licensing_potential()
PlatformEconomicsFramework	🟡	Platform/Creator Economics	model_dynamics(), creator_revenue()

Layer 6: Meta/Peer (Enterprise)

Framework	Status	Description	Key Methods
REMSOMFramework	🟢	Recursive Economic Micro-Simulation (flagship)	simulate(), calibrate(), policy_shock()
HANKFramework	🔴	Heterogeneous Agent New Keynesian	solve(), impulse_response()
DSGEFramework	🔴	Dynamic Stochastic General Equilibrium	solve(), forecast()
ABMFramework	🔴	Agent-Based Modeling	simulate(), sensitivity_analysis()
IOTablesFramework	🟡	Input-Output Tables Analysis	compute_multipliers(), leontief_inverse()
CGEFramework	🟡	Computable General Equilibrium	solve(), counterfactual()

Tier System

Access to frameworks is controlled by subscription tier:

Tier	Access	Use Case
Community	Layer 1 basic methods	Academic research, learning
Professional	Layers 1-2, Layer 5 basic	NGOs, consultants
Team	Layers 1-3, Layer 5	Research teams
Enterprise	All layers, all methods	Financial institutions, government

from krl_frameworks import Tier, set_current_tier, requires_tier

# Set tier context
set_current_tier(Tier.ENTERPRISE)

# Tier-gated methods will now be accessible
framework = BaselIIIFramework()
metrics = framework.compute_ratios(bundle)  # Requires ENTERPRISE

Backend Integration

For production deployments, integrate with krl-premium-backend:

from krl_frameworks.integration import (
    create_execution_service,
    ExecutionRequest,
)

# Create service
service = create_execution_service(
    base_url="https://api.krlabs.dev",
    api_key="your-api-key",
)

# Execute remotely
request = ExecutionRequest(
    framework_id="mpi",
    input_data={"health": [...], "education": [...]},
)
result = await service.execute(request)

print(f"TCU Cost: {result.tcu_cost}")
print(f"MPI: {result.metrics['mpi']}")

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         KRL Frameworks                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐ │
│  │   Layer 6   │   │   Layer 5   │   │   Layer 4   │   │   Layer 3   │ │
│  │  Meta/Peer  │◄──│ Arts/Media  │◄──│  Financial  │◄──│Experimental │ │
│  │   REMSOM    │   │  Cultural   │   │  Basel III  │   │   RCT/DiD   │ │
│  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘ │
│         │                 │                 │                 │         │
│         └────────────┬────┴────────┬────────┴────────┬────────┘         │
│                      │             │                 │                   │
│              ┌───────▼─────────────▼─────────────────▼───────┐          │
│              │           CBSS Simulation Engine               │          │
│              │  • CohortStateVector  • Transitions            │          │
│              │  • StateTrajectory    • Convergence            │          │
│              └───────────────────────┬───────────────────────┘          │
│                                      │                                   │
│              ┌───────────────────────▼───────────────────────┐          │
│              │           DAG Orchestration                    │          │
│              │  • FrameworkDAG       • TopologicalExecutor    │          │
│              │  • PipelineBuilder    • DataFlowMapper         │          │
│              └───────────────────────┬───────────────────────┘          │
│                                      │                                   │
│              ┌───────────────────────▼───────────────────────┐          │
│              │              Core Abstractions                 │          │
│              │  • DataBundle         • FrameworkConfig        │          │
│              │  • Tier System        • Registry               │          │
│              └───────────────────────────────────────────────┘          │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Integration Patterns

KRL Frameworks serves as the orchestration layer and delegates specialized operations to other KRL packages. It does NOT re-implement primitives.

Causal Estimation (via krl-causal-policy-toolkit)

from krl_frameworks.adapters import get_causal_estimator

# Delegate causal estimation to the specialized package
causal = get_causal_estimator()  # Lazy loaded, cached
result = causal.estimate(
    method="did",  # "did", "scm", "psm", "iv", "rdd"
    data=treatment_data,
    treatment_col="treated",
    outcome_col="outcome",
    time_col="period",
)

print(f"ATT: {result['att']:.3f} ± {result['se']:.3f}")

Data Injection (via krl-data-connectors)

Data is injected explicitly via DataBundle - no auto-discovery:

from krl_frameworks.adapters import DataBundleFactory

# Build bundle from explicit connector calls
factory = DataBundleFactory()
factory.add_connector("census", census_connector.fetch())
factory.add_connector("bls", bls_connector.fetch(series="employment"))

bundle = factory.build()

Spatial Analysis (optional, via krl-geospatial-tools)

from krl_frameworks.adapters import get_spatial_adapter

spatial = get_spatial_adapter()  # Optional, raises if not installed
weights = spatial.compute_spatial_weights(gdf, method="queen")
autocorr = spatial.spatial_autocorrelation(gdf["mpi"], weights)

print(f"Moran's I: {autocorr['morans_i']:.3f}")

Network Analysis (optional, via krl-network-analysis)

from krl_frameworks.adapters import get_network_adapter

network = get_network_adapter()  # Optional, raises if not installed
graph = network.build_exposure_graph(exposure_matrix)
centrality = network.compute_centrality(graph, method="eigenvector")

# Identify systemically important nodes
sifis = network.identify_systemically_important(graph, threshold=0.8)

Tier Compatibility with krl-types

from krl_frameworks.core.tier import Tier

# Convert from krl-types API tier strings
tier = Tier.from_api("professional")  # Returns Tier.PROFESSIONAL
tier = Tier.from_api(api_response.tier)  # Works with any tier format

# Convert to API format
api_str = Tier.PROFESSIONAL.to_api()  # Returns "professional"

CohortStateVector

The core data structure representing cohort state:

@dataclass
class CohortStateVector:
    employment_prob: np.ndarray      # Employment probability [0, 1]
    health_burden_score: np.ndarray  # Health burden [0, 1]
    credit_access_prob: np.ndarray   # Credit access [0, 1]
    housing_cost_ratio: np.ndarray   # Housing costs / income
    opportunity_score: np.ndarray    # Opportunity index [0, 1]
    sector_output: np.ndarray        # Economic output by sector
    deprivation_vector: np.ndarray   # MPI-style deprivation
    step: int                        # Current time step

Security

KRL Frameworks includes enterprise-grade security features for production deployments:

Input Validation & Sanitization

from krl_frameworks.security import (
    validate_parameter_schema,
    sanitize_parameters,
    ValidationError,
)

# Define schema for framework parameters
schema = {
    "type": "object",
    "properties": {
        "health_data": {"type": "array", "items": {"type": "number"}},
        "threshold": {"type": "number", "minimum": 0, "maximum": 1},
    },
    "required": ["health_data"],
}

# Validate and sanitize user inputs
try:
    validate_parameter_schema(user_params, schema)
    safe_params = sanitize_parameters(user_params)
except ValidationError as e:
    print(f"Validation failed: {e}")

Circuit Breaker Pattern

from krl_frameworks.security import CircuitBreaker

# Create circuit breaker for framework execution
cb = CircuitBreaker(failure_threshold=5, recovery_timeout=30.0)

async with cb.context():
    result = await framework.execute(params)
    
# Check circuit state
if cb.is_open:
    print("Circuit open - service degraded")

Tier Enforcement

from krl_frameworks.security import tier_allows_access

# Verify user tier before execution
if not tier_allows_access(user_tier="professional", required_tier="team"):
    raise PermissionError("Upgrade required for this framework")

# Or use the decorator
from krl_frameworks.security import secure_framework_execution

@secure_framework_execution(required_tier="enterprise", schema=param_schema)
async def run_basel_iii(params):
    return framework.execute(params)

Audit Logging

from krl_frameworks.security import SecurityAuditEvent

# Create audit events for compliance logging
event = SecurityAuditEvent(
    event_type="framework_execution",
    user_id="user_123",
    framework_id="basel_iii",
    tier="enterprise",
    success=True,
    execution_time_ms=150.5,
)

Development

# Clone repository
git clone https://github.com/khipu-labs/krl-frameworks.git
cd krl-frameworks

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run linting
ruff check src/
mypy src/

Documentation

• API Reference
• User Guide
• Architecture

License

Apache-2.0 © 2025 Khipu Research Labs - See LICENSE for details.

Citation

@software{krl_frameworks,
  author = {Khipu Research Labs},
  title = {KRL Frameworks: Enterprise Meta-Framework Orchestration Platform},
  year = {2025},
  url = {https://github.com/khipu-labs/krl-frameworks}
}