crca 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

docs/branches/crca-sd/core.md

@@ -0,0 +1,84 @@
+# CRCA-SD Core
+
+Core components of CRCA-SD including state vectors, control vectors, and dynamics models.
+
+## State Vector
+
+The state vector represents the socioeconomic system state with 15 variables:
+
+$$\mathbf{x}_t = [P_t, L_t, U_t, W_t, S_t, \ell_t, E_{cap,t}, H_{cap,t}, K_t, I_t, T_{cap,t}, E_{stock,t}, F_{stock,t}, M_{stock,t}, C_t, Y_t]'$$
+
+### Variable Definitions
+
+- $P_t$: Population
+- $L_t$: Labor force
+- $U_t$: Unemployment rate $[0, 1]$
+- $W_t$: Average wage proxy
+- $S_t$: Social stability proxy $[0, 1]$
+- $\ell_t$: Literacy rate $[0, 1]$
+- $E_{cap,t}$: Education capacity
+- $H_{cap,t}$: Healthcare capacity
+- $K_t$: Productive capital stock
+- $I_t$: Infrastructure health index $[0, 1]$
+- $T_{cap,t}$: Transport capacity
+- $E_{stock,t}$: Stored energy
+- $F_{stock,t}$: Food stock
+- $M_{stock,t}$: Critical materials stock
+- $C_t$: Ecological damage (irreversible)
+- $Y_t$: GDP proxy
+
+## Control Vector
+
+The control vector represents budget allocations:
+
+$$\mathbf{u}_t = [b_E, b_F, b_H, b_I, b_K, b_RD, b_welfare, b_security]'$$
+
+Where each $b_i$ is a budget share such that:
+
+$$\sum_i b_i = 1, \quad b_i \geq 0$$
+
+## Dynamics Model
+
+The dynamics model implements discrete-time evolution:
+
+$$\mathbf{x}_{t+1} = f(\mathbf{x}_t, \mathbf{u}_t, \mathbf{w}_t)$$
+
+### Key Dynamics
+
+**Population Growth**:
+$$P_{t+1} = P_t (1 + \beta - \delta + \mu)$$
+
+Where $\beta$ is birth rate, $\delta$ is death rate, and $\mu$ is migration.
+
+**Capital Accumulation**:
+$$K_{t+1} = (1 - \delta_K) K_t + \kappa_K b_K B_t$$
+
+Where $\delta_K$ is depreciation and $\kappa_K$ is investment efficiency.
+
+**Output Production** (Cobb-Douglas with gating):
+$$Y_{t+1} = A_t K_t^\alpha L_t^{1-\alpha} g_E h_T$$
+
+Where $g_E$ and $h_T$ are energy and transport gates.
+
+## Usage
+
+```python
+from branches.crca_sd.crca_sd_core import StateVector, ControlVector, DynamicsModel
+
+# Initialize state
+state = StateVector(P=1000000, L=500000, U=0.05)
+
+# Define control
+control = ControlVector(b_E=0.1, b_F=0.2, b_H=0.15)
+
+# Create dynamics model
+dynamics = DynamicsModel()
+
+# Step forward
+next_state = dynamics.step(state, control)
+```
+
+## Next Steps
+
+- [MPC Solver](mpc-solver.md) - MPC optimization
+- [Governance](governance.md) - Governance systems

docs/branches/crca-sd/governance.md

@@ -0,0 +1,53 @@
+# Governance Systems
+
+CRCA-SD includes governance systems for policy execution, monitoring, and compliance.
+
+## Overview
+
+Governance systems manage policy execution, track performance, ensure compliance, and provide visualization and reporting.
+
+## Components
+
+### Board
+
+Policy-making board that defines objectives and constraints.
+
+### Metrics Collector
+
+Collects and aggregates performance metrics:
+
+$$\bar{M}_t = \frac{1}{T} \sum_{s=t-T+1}^t M_s$$
+
+Where $M_s$ are metrics at time $s$.
+
+### Visualization
+
+Provides visualizations of system state, trajectories, and performance.
+
+## Mathematical Foundation
+
+Governance evaluates policy performance using:
+
+$$J(\pi) = \sum_{t=0}^T \gamma^t r(\mathbf{x}_t, \mathbf{u}_t)$$
+
+Where:
+- $\pi$: Policy
+- $r$: Reward function
+- $\gamma$: Discount factor
+
+## Usage
+
+```python
+from branches.crca_sd.crca_sd_governance import Board, MetricsCollector
+
+board = Board(objectives=["maximize_gdp", "minimize_unemployment"])
+collector = MetricsCollector()
+
+metrics = collector.collect(state, control)
+performance = board.evaluate(metrics)
+```
+
+## Next Steps
+
+- [Overview](overview.md) - Return to overview
+- [CRCA-CG](../crca-cg/overview.md) - Corporate governance

docs/branches/crca-sd/mpc-solver.md

@@ -0,0 +1,65 @@
+# MPC Solver
+
+Model Predictive Control (MPC) solver for CRCA-SD.
+
+## Overview
+
+The MPC solver optimizes control actions over a prediction horizon to achieve policy objectives while satisfying constraints.
+
+## Mathematical Foundation
+
+### MPC Optimization Problem
+
+$$\min_{\mathbf{u}_{t:t+H-1}} \sum_{k=0}^{H-1} \ell(\mathbf{x}_{t+k}, \mathbf{u}_{t+k}) + V(\mathbf{x}_{t+H})$$
+
+Subject to:
+
+$$\mathbf{x}_{t+k+1} = f(\mathbf{x}_{t+k}, \mathbf{u}_{t+k}, \mathbf{w}_{t+k})$$
+$$\mathbf{g}(\mathbf{x}_{t+k}, \mathbf{u}_{t+k}) \leq 0$$
+$$\mathbf{h}(\mathbf{x}_{t+k}, \mathbf{u}_{t+k}) = 0$$
+
+Where:
+- $H$: Prediction horizon
+- $\ell$: Stage cost function
+- $V$: Terminal cost function
+- $f$: System dynamics
+- $\mathbf{g}, \mathbf{h}$: Inequality and equality constraints
+
+### Stage Cost
+
+The stage cost typically includes:
+
+$$\ell(\mathbf{x}, \mathbf{u}) = \|\mathbf{x} - \mathbf{x}_{ref}\|_Q^2 + \|\mathbf{u} - \mathbf{u}_{ref}\|_R^2$$
+
+Where $Q$ and $R$ are weighting matrices.
+
+## Usage
+
+```python
+from branches.crca_sd.crca_sd_mpc import MPCSolver
+
+solver = MPCSolver(
+    horizon=10,
+    state_weights=Q,
+    control_weights=R
+)
+
+# Solve MPC problem
+optimal_controls = solver.solve(
+    current_state=state,
+    reference_state=ref_state,
+    constraints=constraints
+)
+```
+
+## State Estimation
+
+The solver includes state estimation for unobserved variables:
+
+$$\hat{\mathbf{x}}_t = E[\mathbf{x}_t | \mathbf{z}_{0:t}]$$
+
+Where $\mathbf{z}_{0:t}$ are observations up to time $t$.
+
+## Next Steps
+
+- [Governance](governance.md) - Governance systems

docs/branches/crca-sd/overview.md

@@ -0,0 +1,59 @@
+# CRCA-SD Overview
+
+CRCA-SD (CRCA for Socioeconomic Dynamics) is a constrained, stochastic, multi-objective model-predictive control system for socioeconomic dynamics and logistics optimization.
+
+## Overview
+
+CRCA-SD integrates CRCA (Causal Reasoning and Counterfactual Analysis) for:
+- Causal scenario generation
+- Causal policy validation
+- Understanding why policies work
+
+## Key Features
+
+- **State Vector**: 15 core socioeconomic variables
+- **Control Vector**: Budget shares and allocations
+- **Dynamics Model**: Macro system dynamics equations
+- **MPC Solver**: Model Predictive Control optimization
+- **Governance Systems**: Policy execution and monitoring
+- **Real-Time Control**: Real-time data acquisition and control
+
+## Mathematical Foundation
+
+CRCA-SD models socioeconomic systems using state-space representation:
+
+$$\mathbf{x}_{t+1} = f(\mathbf{x}_t, \mathbf{u}_t, \mathbf{w}_t)$$
+
+Where:
+- $\mathbf{x}_t$: State vector (15 variables)
+- $\mathbf{u}_t$: Control vector (budget allocations)
+- $\mathbf{w}_t$: Exogenous shocks
+
+The MPC optimization problem is:
+
+$$\min_{\mathbf{u}_{t:t+H-1}} \sum_{k=0}^{H-1} \ell(\mathbf{x}_{t+k}, \mathbf{u}_{t+k}) + V(\mathbf{x}_{t+H})$$
+
+Subject to:
+
+$$\mathbf{x}_{t+k+1} = f(\mathbf{x}_{t+k}, \mathbf{u}_{t+k}, \mathbf{w}_{t+k})$$
+$$\mathbf{g}(\mathbf{x}_{t+k}, \mathbf{u}_{t+k}) \leq 0$$
+
+## State Variables
+
+The state vector contains 15 variables:
+- **Macro**: Population (P), Labor (L), Unemployment (U), Wage (W), Stability (S)
+- **Human Capital**: Literacy (ℓ), Education Capacity (Ecap), Healthcare Capacity (Hcap)
+- **Capital**: Capital Stock (K), Infrastructure Health (I), Transport Capacity (Tcap)
+- **Stocks**: Energy (E_stock), Food (F_stock), Materials (M_stock), Ecological Damage (C)
+- **Output**: GDP Proxy (Y)
+
+## Documentation
+
+- **[Core](core.md)**: Core CRCA-SD functionality
+- **[MPC Solver](mpc-solver.md)**: Model Predictive Control implementation
+- **[Governance](governance.md)**: Governance systems
+
+## Next Steps
+
+- [Core](core.md) - Core functionality
+- [MPC Solver](mpc-solver.md) - MPC optimization

docs/branches/crca-sd/realtime.md

@@ -0,0 +1,28 @@
+# Real-Time Control
+
+Real-time control system for CRCA-SD.
+
+## Overview
+
+Real-time control enables live operation with data acquisition, state estimation, and automated policy execution.
+
+## Mathematical Foundation
+
+Real-time control uses state estimation:
+
+$$\hat{\mathbf{x}}_t = E[\mathbf{x}_t | \mathbf{z}_{0:t}]$$
+
+Where $\mathbf{z}_{0:t}$ are observations.
+
+## Usage
+
+```python
+from branches.crca_sd.crca_sd_realtime import RealTimeController
+
+controller = RealTimeController()
+controller.start()
+```
+
+## Next Steps
+
+- [TUI](tui.md) - Terminal user interface

docs/branches/crca-sd/tui.md

@@ -0,0 +1,20 @@
+# Terminal User Interface (TUI)
+
+Terminal user interface for CRCA-SD.
+
+## Overview
+
+TUI provides a command-line interface for monitoring and controlling CRCA-SD systems.
+
+## Usage
+
+```python
+from branches.crca_sd.crca_sd_tui import TUI
+
+tui = TUI()
+tui.run()
+```
+
+## Next Steps
+
+- [Overview](overview.md) - Return to overview

docs/branches/general-agent/overview.md

@@ -0,0 +1,37 @@
+# General Agent Overview
+
+GeneralAgent is a flexible general-purpose agent with personality system and multimodal capabilities.
+
+## Overview
+
+GeneralAgent provides a general-purpose agent framework that can be customized for various tasks with personality traits and multimodal support.
+
+## Key Features
+
+- **Personality System**: Configurable personality traits
+- **Multimodal Support**: Text, image, and other modalities
+- **Prompt Building**: Dynamic prompt construction
+- **Flexible Architecture**: Extensible for various use cases
+
+## Usage
+
+```python
+from branches.general_agent.general_agent import GeneralAgent
+
+agent = GeneralAgent(
+    model_name="gpt-4o-mini",
+    enable_multimodal=True
+)
+
+response = agent.run("Analyze this image and text")
+```
+
+## Documentation
+
+- **[Personality](personality.md)**: Personality system
+- **[Prompt Builder](prompt-builder.md)**: Prompt building utilities
+
+## Next Steps
+
+- [Personality](personality.md) - Personality system
+- [Prompt Builder](prompt-builder.md) - Prompt building

docs/branches/general-agent/personality.md

@@ -0,0 +1,36 @@
+# Personality System
+
+GeneralAgent includes a configurable personality system.
+
+## Overview
+
+The personality system allows configuring agent behavior, tone, and response style.
+
+## Usage
+
+```python
+from branches.general_agent.general_agent import GeneralAgent
+from branches.general_agent.personality import Personality
+
+personality = Personality(
+    traits=["analytical", "helpful", "concise"]
+)
+
+agent = GeneralAgent(
+    model_name="gpt-4o-mini",
+    personality=personality
+)
+```
+
+## Personality Traits
+
+Common traits include:
+- Analytical
+- Creative
+- Helpful
+- Concise
+- Detailed
+
+## Next Steps
+
+- [Prompt Builder](prompt-builder.md) - Prompt building utilities

docs/branches/general-agent/prompt-builder.md

@@ -0,0 +1,30 @@
+# Prompt Builder
+
+Prompt building utilities for GeneralAgent.
+
+## Overview
+
+Prompt builder utilities help construct dynamic prompts for agent interactions.
+
+## Usage
+
+```python
+from branches.general_agent.utils.prompt_builder import PromptBuilder
+
+builder = PromptBuilder()
+prompt = builder.build(
+    task="Analyze data",
+    context=context,
+    examples=examples
+)
+```
+
+## Features
+
+- Dynamic prompt construction
+- Context management
+- Example integration
+
+## Next Steps
+
+- [Features](../features/policy-engine/overview.md) - Policy engine features

docs/changelog/index.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to CR-CA will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New features in development
+
+### Changed
+- Changes in development
+
+## [1.4.0] - 2024-01-XX
+
+### Added
+- Comprehensive documentation overhaul
+- Policy Engine System documentation
+- Expanded module documentation
+- Architecture diagrams
+- Integration examples
+- CI/CD documentation
+- Project structure documentation
+
+### Changed
+- Complete README rewrite with 100+ code examples
+
+## [1.3.0] - 2024-01-XX
+
+### Added
+- Automatic variable extraction from natural language (v1.3.0+)
+- Enhanced LLM integration
+- Module expansions
+
+### Changed
+- Comprehensive updates to all modules (utils, tools, templates, schemas)
+- Integration improvements for CRCA-SD, CRCA-CG, and CRCA-Q
+
+## [1.2.0] - 2024-01-XX
+
+### Added
+- Advanced Analysis Suite:
+  - Batch prediction with vectorized operations
+  - Async/await support for concurrent operations
+  - Optimization methods (gradient-based, Bellman dynamic programming)
+  - Time-series analysis (Granger causality, VAR estimation)
+  - Bayesian inference with credible intervals
+  - Information-theoretic measures
+  - Advanced analysis (sensitivity, root cause, Shapley values)
+
+### Changed
+- Performance improvements: Parallel bootstrap sampling
+- Code optimization: Reduced file size while maintaining functionality
+
+## [1.1.0] - 2024-01-XX
+
+### Added
+- Production hardening:
+  - Thread-safe prediction cache with lock protection
+  - Requirements.txt pin list for CI
+  - GitHub Actions sanity workflow
+  - Pytest smoke tests
+  - Cache lock documentation
+
+## [1.0.0] - 2024-01-XX
+
+### Added
+- Initial Release:
+  - Core CRCAAgent with LLM integration
+  - Causal DAG management
+  - Linear SCM evolution
+  - Counterfactual generation
+  - Basic deterministic simulation
+
+---
+
+*This changelog is auto-generated from git history and pyproject.toml. Run `python scripts/generate_changelog.py` to update.*

docs/contributing/code-style.md

@@ -0,0 +1,69 @@
+# Code Style Guide
+
+Follow these guidelines when contributing code to CR-CA.
+
+## Type Annotations
+
+Always use type annotations:
+
+```python
+def calculate_average(numbers: List[float]) -> float:
+    """Calculate average."""
+    return sum(numbers) / len(numbers)
+```
+
+## Docstrings
+
+Use Google-style docstrings:
+
+```python
+def process_data(data: List[int]) -> int:
+    """
+    Process data and return result.
+    
+    Args:
+        data: List of integers to process.
+    
+    Returns:
+        Processed result as integer.
+    
+    Raises:
+        ValueError: If data is empty.
+    """
+    if not data:
+        raise ValueError("Data cannot be empty")
+    return sum(data)
+```
+
+## Logging
+
+Use Loguru for logging:
+
+```python
+from loguru import logger
+
+logger.info("Processing data")
+logger.error(f"Error: {error}")
+```
+
+## Mathematical Documentation
+
+Include mathematical formulations for algorithms:
+
+```python
+def compute_causal_effect(treatment: str, outcome: str) -> float:
+    """
+    Compute causal effect E[Y | do(X=x)].
+    
+    Uses the formula:
+    $$E[Y | do(X=x)] = \sum_{z} E[Y | X=x, Z=z] P(Z=z)$$
+    
+    Where Z are confounders.
+    """
+    # Implementation
+```
+
+## Next Steps
+
+- [Documentation](documentation.md) - Documentation guidelines
+- [Testing](testing.md) - Testing guidelines

docs/contributing/documentation.md

@@ -0,0 +1,43 @@
+# Documentation Contribution Guide
+
+Guide for contributing to CR-CA documentation.
+
+## Documentation Structure
+
+Documentation is organized in `docs/` with:
+- Getting started guides
+- Core module documentation
+- Feature documentation
+- Examples
+- API reference
+
+## Writing Documentation
+
+### Include Mathematical Formulations
+
+All concepts should be explainable mathematically:
+
+```markdown
+The causal effect is:
+
+$$E[Y | do(X=x)] = \sum_{z} E[Y | X=x, Z=z] P(Z=z)$$
+```
+
+### Code Examples
+
+Include working code examples:
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(model_name="gpt-4o-mini")
+result = agent.run("Analyze X -> Y")
+```
+
+### No Emojis
+
+Do not use emojis in documentation. Use text-based symbols if needed.
+
+## Next Steps
+
+- [Testing](testing.md) - Testing guidelines

docs/contributing/overview.md

@@ -0,0 +1,29 @@
+# Contributing to CR-CA
+
+Thank you for your interest in contributing to CR-CA! This guide will help you get started.
+
+## How to Contribute
+
+- Report bugs
+- Suggest features
+- Submit pull requests
+- Improve documentation
+- Write tests
+
+## Getting Started
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Documentation
+
+- **[Code Style](code-style.md)**: Code style guide
+- **[Documentation](documentation.md)**: Documentation contribution guide
+- **[Testing](testing.md)**: Testing guidelines
+
+## Next Steps
+
+- [Code Style](code-style.md) - Follow code style guidelines
+- [Documentation](documentation.md) - Contribute to documentation

docs/contributing/testing.md

@@ -0,0 +1,29 @@
+# Testing Guidelines
+
+Guidelines for writing and running tests.
+
+## Test Structure
+
+Tests are located in `tests/` directory.
+
+## Writing Tests
+
+```python
+import pytest
+from CRCA import CRCAAgent
+
+def test_basic_agent():
+    agent = CRCAAgent(model_name="gpt-4o-mini")
+    result = agent.run("Test task")
+    assert result is not None
+```
+
+## Running Tests
+
+```bash
+pytest tests/
+```
+
+## Next Steps
+
+- [CI/CD Setup](../../getting-started/configuration.md) - CI/CD configuration