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

docs/core/crcagent/initialization.md

@@ -0,0 +1,88 @@
+# CRCAAgent Initialization
+
+This guide covers initializing and configuring CRCAAgent instances.
+
+## Basic Initialization
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="my-agent"
+)
+```
+
+## Configuration Parameters
+
+### Required Parameters
+
+- `model_name`: LLM model identifier (e.g., "gpt-4o-mini", "gpt-4")
+- `agent_name`: Unique identifier for the agent
+
+### Optional Parameters
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="configured-agent",
+    
+    # LLM Settings
+    max_loops=5,
+    temperature=0.7,
+    max_tokens=2000,
+    
+    # Causal Reasoning
+    enable_automatic_extraction=True,
+    causal_graph_threshold=0.3,
+    
+    # Simulation
+    simulation_steps=100,
+    simulation_dt=0.01,
+    
+    # Tools
+    use_crca_tools=True,
+    use_image_annotation=False
+)
+```
+
+## Mathematical Configuration
+
+The agent's causal reasoning is configured through structural equations. For a variable $Y$ with parents $Pa(Y)$:
+
+$$Y = f(Pa(Y), U_Y)$$
+
+Where $U_Y$ is an exogenous variable. The agent estimates these functions from data or uses LLM-based inference.
+
+## Mode Selection
+
+### LLM Mode (Default)
+
+Uses LLM for causal reasoning:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    mode="llm"
+)
+```
+
+### Deterministic Mode
+
+Uses mathematical simulation:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    mode="deterministic"
+)
+```
+
+## Advanced Configuration
+
+See [Configuration Guide](../../getting-started/configuration.md) for detailed configuration options.
+
+## Next Steps
+
+- [Automatic Extraction](automatic-extraction.md) - Extract variables automatically
+- [Dual-Mode Operation](dual-mode-operation.md) - Understand mode switching

docs/core/crcagent/optimization.md

@@ -0,0 +1,65 @@
+# Optimization Methods
+
+CRCAAgent includes optimization methods for finding optimal interventions.
+
+## Overview
+
+Optimization methods find interventions that maximize or minimize target outcomes subject to constraints.
+
+## Mathematical Foundation
+
+### Optimization Problem
+
+Find intervention $x^*$ that maximizes expected outcome:
+
+$$x^* = \arg\max_x E[Y | do(X=x)]$$
+
+Subject to constraints:
+
+$$g_i(x) \leq 0, \quad i = 1, \ldots, m$$
+$$h_j(x) = 0, \quad j = 1, \ldots, p$$
+
+### Gradient-Based Optimization
+
+For differentiable objectives:
+
+$$\nabla_x E[Y | do(X=x)] = 0$$
+
+Using gradient descent:
+
+$$x_{t+1} = x_t - \alpha \nabla_x E[Y | do(X=x_t)]$$
+
+Where $\alpha$ is the learning rate.
+
+### Dynamic Programming
+
+For sequential decision problems:
+
+$$V_t(s) = \max_a \left\{ R(s,a) + \gamma \sum_{s'} P(s'|s,a) V_{t+1}(s') \right\}$$
+
+## Usage
+
+### Gradient-Based
+
+```python
+optimal = agent.optimize_intervention(
+    target="income",
+    method="gradient",
+    constraints={"education": (0, 20)}
+)
+```
+
+### Dynamic Programming
+
+```python
+optimal = agent.optimize_intervention(
+    target="income",
+    method="bellman",
+    horizon=10
+)
+```
+
+## Next Steps
+
+- [Time-Series](time-series.md) - Time-series analysis
+- [Bayesian Inference](bayesian-inference.md) - Bayesian methods

docs/core/crcagent/overview.md

@@ -0,0 +1,63 @@
+# CRCAAgent Overview
+
+CRCAAgent is the core causal reasoning agent in the CR-CA framework. It combines structural causal models (SCMs) with large language model (LLM) integration to enable sophisticated causal inference and counterfactual analysis.
+
+## Key Features
+
+- **Automatic Variable Extraction**: Extract variables and causal relationships from natural language
+- **Dual-Mode Operation**: Switch between LLM-based analysis and deterministic simulation
+- **Causal Graph Management**: Build and manage causal directed acyclic graphs (DAGs)
+- **Deterministic Simulation**: Perform mathematical causal simulations
+- **Counterfactual Generation**: Generate "what-if" scenarios
+- **Batch Prediction**: Process multiple scenarios simultaneously
+- **Async Operations**: Concurrent analysis with async/await support
+
+## Mathematical Foundation
+
+CRCAAgent implements Structural Causal Models (SCMs) as defined by Judea Pearl. An SCM is a triple:
+
+$$(U, V, F)$$
+
+Where:
+- $U$: Exogenous (unobserved) variables
+- $V$: Endogenous (observed) variables
+- $F$: Structural equations defining causal relationships
+
+Each structural equation has the form:
+
+$$V_i = f_i(Pa(V_i), U_i)$$
+
+Where $Pa(V_i)$ are the parents of $V_i$ in the causal graph.
+
+## Basic Usage
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="my-agent"
+)
+
+result = agent.run("Analyze the causal relationship between X and Y")
+```
+
+## Core Components
+
+- **[Initialization](initialization.md)**: Agent setup and configuration
+- **[Automatic Extraction](automatic-extraction.md)**: Variable extraction from natural language
+- **[Dual-Mode Operation](dual-mode-operation.md)**: LLM vs deterministic modes
+- **[Causal Graph](causal-graph.md)**: Causal DAG construction and management
+- **[Deterministic Simulation](deterministic-simulation.md)**: Mathematical simulation
+- **[Counterfactuals](counterfactuals.md)**: Counterfactual scenario generation
+- **[Batch Prediction](batch-prediction.md)**: Batch processing capabilities
+- **[Async Operations](async-operations.md)**: Async/await support
+- **[Optimization](optimization.md)**: Optimization methods
+- **[Time-Series](time-series.md)**: Time-series analysis
+- **[Bayesian Inference](bayesian-inference.md)**: Bayesian inference with credible intervals
+
+## Next Steps
+
+- [Initialization](initialization.md) - Configure your agent
+- [Automatic Extraction](automatic-extraction.md) - Extract variables from text
+- [Causal Graph](causal-graph.md) - Work with causal graphs

docs/core/crcagent/time-series.md

@@ -0,0 +1,57 @@
+# Time-Series Analysis
+
+CRCAAgent supports time-series causal analysis including Granger causality and VAR models.
+
+## Overview
+
+Time-series analysis identifies causal relationships in temporal data, accounting for temporal dependencies.
+
+## Mathematical Foundation
+
+### Vector Autoregression (VAR)
+
+A VAR($p$) model for $k$ variables:
+
+$$\mathbf{y}_t = \mathbf{c} + \sum_{i=1}^p \mathbf{\Phi}_i \mathbf{y}_{t-i} + \boldsymbol{\epsilon}_t$$
+
+Where:
+- $\mathbf{y}_t$: Vector of variables at time $t$
+- $\mathbf{\Phi}_i$: Coefficient matrices
+- $\boldsymbol{\epsilon}_t$: Error terms
+
+### Granger Causality
+
+$X$ Granger-causes $Y$ if:
+
+$$E[Y_t | \mathcal{I}_{t-1}] \neq E[Y_t | \mathcal{I}_{t-1} \setminus X_{t-1}]$$
+
+Where $\mathcal{I}_{t-1}$ is the information set at time $t-1$.
+
+## Usage
+
+### VAR Estimation
+
+```python
+# Estimate VAR model
+var_model = agent.estimate_var(
+    data=dataframe,
+    variables=["X", "Y", "Z"],
+    lags=4
+)
+```
+
+### Granger Causality Test
+
+```python
+# Test if X Granger-causes Y
+result = agent.granger_causality_test(
+    data=dataframe,
+    cause="X",
+    effect="Y",
+    max_lag=4
+)
+```
+
+## Next Steps
+
+- [Bayesian Inference](bayesian-inference.md) - Bayesian time-series methods

docs/core/schemas/annotation.md

@@ -0,0 +1,30 @@
+# Annotation Schemas
+
+Schemas for image annotation system.
+
+## Overview
+
+Annotation schemas define data structures for image annotation results, including entities, labels, and relations.
+
+## Key Schemas
+
+- `AnnotationResult`: Complete annotation result
+- `PrimitiveEntity`: Geometric primitive entity
+- `SemanticLabel`: Semantic label for entities
+- `Relation`: Relationship between entities
+
+## Usage
+
+```python
+from schemas.annotation import AnnotationResult, PrimitiveEntity
+
+result = AnnotationResult(
+    entities=[PrimitiveEntity(...)],
+    labels=[],
+    relations=[]
+)
+```
+
+## Next Steps
+
+- [Conversation](conversation.md) - Conversation schemas

docs/core/schemas/core-schemas.md

@@ -0,0 +1,82 @@
+# Core Schemas
+
+Grouped documentation for core data schemas.
+
+## Conversation Schemas
+
+Schemas for conversation management.
+
+### Classes
+
+- `ConversationState`: Current conversation state
+- `Message`: Individual message in conversation
+- `Context`: Conversation context
+
+### Usage
+
+```python
+from schemas.conversation import ConversationState, Message
+
+state = ConversationState(
+    messages=[Message(role="user", content="Hello")]
+)
+```
+
+## Hybrid Agent Schemas
+
+Schemas for hybrid agent architecture.
+
+### Classes
+
+- `HybridAgentState`: Hybrid agent state
+- `ReasoningStep`: Individual reasoning step
+- `ConsistencyCheck`: Consistency check result
+
+### Usage
+
+```python
+from schemas.hybrid import HybridAgentState
+
+state = HybridAgentState(
+    reasoning_steps=[],
+    consistency_checks=[]
+)
+```
+
+## Reasoning Schemas
+
+Schemas for causal reasoning operations and results.
+
+### Classes
+
+- `CausalInferenceResult`: Causal inference result
+- `CounterfactualScenario`: Counterfactual scenario
+- `CausalEffect`: Causal effect estimate
+
+### Mathematical Foundation
+
+Causal effect:
+
+$$\tau = E[Y | do(X=1)] - E[Y | do(X=0)]$$
+
+With confidence interval:
+
+$$CI_{1-\alpha} = [\tau - z_{\alpha/2} \cdot SE, \tau + z_{\alpha/2} \cdot SE]$$
+
+### Usage
+
+```python
+from schemas.reasoning import CausalInferenceResult
+
+result = CausalInferenceResult(
+    treatment="X",
+    outcome="Y",
+    effect=0.5,
+    confidence=0.9
+)
+```
+
+## Next Steps
+
+- [Annotation](annotation.md) - Image annotation schemas
+- [Policy](policy.md) - Policy engine schemas

docs/core/schemas/overview.md

@@ -0,0 +1,30 @@
+# Schemas Overview
+
+The `schemas/` module provides type definitions and data structures for CR-CA.
+
+## Modules
+
+- **[Annotation](annotation.md)**: Image annotation schemas
+- **[Conversation](conversation.md)**: Conversation schemas
+- **[Hybrid](hybrid.md)**: Hybrid agent schemas
+- **[Reasoning](reasoning.md)**: Reasoning schemas
+- **[Policy](policy.md)**: Policy engine schemas
+
+## Usage
+
+Schemas are Pydantic models that provide type safety and validation:
+
+```python
+from schemas.annotation import AnnotationResult
+
+result = AnnotationResult(
+    entities=[],
+    labels=[],
+    relations=[]
+)
+```
+
+## Next Steps
+
+- [Annotation](annotation.md) - Image annotation schemas
+- [Policy](policy.md) - Policy engine schemas

docs/core/schemas/policy.md

@@ -0,0 +1,41 @@
+# Policy Engine Schemas
+
+Schemas for policy engine system.
+
+## Overview
+
+Policy engine schemas define data structures for policy doctrines, ledgers, and policy execution.
+
+## Key Schemas
+
+- `DoctrineV1`: Policy doctrine definition
+- `PolicyState`: Current policy state
+- `PolicyAction`: Policy action
+- `PolicyObservation`: Policy observation
+
+## Mathematical Foundation
+
+Policy doctrine defines objectives and constraints:
+
+$$\min_{u} \sum_{t=0}^{T} \ell(x_t, u_t)$$
+
+Subject to:
+
+$$g(x_t, u_t) \leq 0$$
+$$h(x_t, u_t) = 0$$
+
+## Usage
+
+```python
+from schemas.policy import DoctrineV1
+
+doctrine = DoctrineV1(
+    version="1.0.0",
+    objectives=["maximize_efficiency"],
+    constraints=["budget_limit"]
+)
+```
+
+## Next Steps
+
+- [Tools Overview](../tools/overview.md) - Tools and integrations

docs/core/templates/base-agent.md

@@ -0,0 +1,31 @@
+# Base Specialized Agent
+
+The base specialized agent template provides a foundation for creating custom agents.
+
+## Overview
+
+BaseSpecializedAgent is an abstract base class that provides common functionality for specialized agents.
+
+## Usage
+
+```python
+from templates.base_specialized_agent import BaseSpecializedAgent
+
+class MyAgent(BaseSpecializedAgent):
+    def __init__(self):
+        super().__init__()
+    
+    def process_task(self, task):
+        # Implement custom logic
+        pass
+```
+
+## Features
+
+- Common agent functionality
+- Integration with CR-CA framework
+- Extensible architecture
+
+## Next Steps
+
+- [Feature Mixins](feature-mixins.md) - Add features via mixins

docs/core/templates/feature-mixins.md

@@ -0,0 +1,31 @@
+# Feature Mixins
+
+Feature mixins provide reusable functionality that can be mixed into agent classes.
+
+## Overview
+
+Mixins allow adding features to agents without multiple inheritance complexity.
+
+## Available Mixins
+
+- Policy loop functionality
+- Graph management
+- LLM integration
+- Statistical methods
+
+## Usage
+
+```python
+from templates.base_specialized_agent import BaseSpecializedAgent
+from templates.feature_mixins import PolicyLoopMixin
+
+class MyAgent(BaseSpecializedAgent, PolicyLoopMixin):
+    def __init__(self):
+        super().__init__()
+        # Mixin functionality is now available
+```
+
+## Next Steps
+
+- [Policy Loop](policy-loop.md) - Policy loop mixin
+- [Graph Management](graph-management.md) - Graph management mixin

docs/core/templates/overview.md

@@ -0,0 +1,29 @@
+# Templates Overview
+
+The `templates/` module provides a framework for creating specialized agents.
+
+## Modules
+
+- **[Base Agent](base-agent.md)**: Base specialized agent template
+- **[Feature Mixins](feature-mixins.md)**: Reusable feature mixins
+- **[Policy Loop](policy-loop.md)**: Policy loop mixin
+- **[Graph Management](graph-management.md)**: Graph management mixin
+- **[LLM Integration](llm-integration.md)**: LLM integration mixin
+
+## Creating Custom Agents
+
+Use templates to create specialized agents:
+
+```python
+from templates.base_specialized_agent import BaseSpecializedAgent
+
+class MyAgent(BaseSpecializedAgent):
+    def __init__(self):
+        super().__init__()
+        # Add custom functionality
+```
+
+## Next Steps
+
+- [Base Agent](base-agent.md) - Base template
+- [Feature Mixins](feature-mixins.md) - Reusable features

docs/core/templates/templates-guide.md

@@ -0,0 +1,75 @@
+# Templates Guide
+
+Comprehensive guide to using templates for creating specialized agents.
+
+## Policy Loop Mixin
+
+Policy loop mixin provides policy engine functionality for agents.
+
+### Mathematical Foundation
+
+Policy loop implements Model Predictive Control (MPC):
+
+$$\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{g}(\mathbf{x}_{t+k}, \mathbf{u}_{t+k}) \leq 0$$
+
+### Usage
+
+```python
+from templates.base_specialized_agent import BaseSpecializedAgent
+from templates.policy_loop import PolicyLoopMixin
+
+class PolicyAgent(BaseSpecializedAgent, PolicyLoopMixin):
+    def __init__(self):
+        super().__init__()
+```
+
+## Graph Management Mixin
+
+Graph management mixin provides causal graph management functionality.
+
+### Usage
+
+```python
+from templates.graph_management import GraphManagementMixin
+
+class GraphAgent(BaseSpecializedAgent, GraphManagementMixin):
+    def __init__(self):
+        super().__init__()
+```
+
+## LLM Integration Mixin
+
+LLM integration mixin provides LLM-based reasoning capabilities.
+
+### Usage
+
+```python
+from templates.llm_integration import LLMIntegrationMixin
+
+class LLMAgent(BaseSpecializedAgent, LLMIntegrationMixin):
+    def __init__(self):
+        super().__init__()
+```
+
+## Module Registry
+
+Module registry for managing and discovering modules.
+
+### Usage
+
+```python
+from templates.module_registry import ModuleRegistry
+
+registry = ModuleRegistry()
+registry.register(module)
+```
+
+## Next Steps
+
+- [Base Agent](base-agent.md) - Base template
+- [Feature Mixins](feature-mixins.md) - Reusable features

docs/core/tools/mcp-client.md

@@ -0,0 +1,34 @@
+# MCP Client
+
+MCP (Model Context Protocol) client utilities for CR-CA.
+
+## Overview
+
+MCP client enables CR-CA agents to interact with MCP servers for extended tool capabilities.
+
+## Usage
+
+```python
+from tools.mcp_client import MCPClient
+
+client = MCPClient(
+    server_url="http://localhost:8000",
+    api_key="your-api-key"
+)
+
+# Call MCP tool
+result = client.call_tool(
+    tool_name="causal_analysis",
+    params={"variables": ["X", "Y"]}
+)
+```
+
+## Features
+
+- Tool discovery
+- Tool execution
+- Protocol handling
+
+## Next Steps
+
+- [Branches](../branches/crca-q/overview.md) - Specialized branches

docs/core/tools/overview.md

@@ -0,0 +1,24 @@
+# Tools Overview
+
+The `tools/` module provides external tool integration for CR-CA.
+
+## Modules
+
+- **[MCP Client](mcp-client.md)**: Model Context Protocol client utilities
+
+## MCP Integration
+
+CR-CA integrates with MCP (Model Context Protocol) servers for extended functionality.
+
+## Usage
+
+```python
+from tools.mcp_client import MCPClient
+
+client = MCPClient(server_url="http://localhost:8000")
+result = client.call_tool("tool_name", params={})
+```
+
+## Next Steps
+
+- [MCP Client](mcp-client.md) - MCP client utilities