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

docs/architecture/causal-graphs.md

@@ -0,0 +1,41 @@
+# Causal Graph Architecture
+
+Architecture for causal graph representation and manipulation.
+
+## Overview
+
+Causal graphs are represented as directed acyclic graphs (DAGs) with nodes for variables and edges for causal relationships.
+
+## Mathematical Foundation
+
+A causal graph $G = (V, E)$ where:
+- $V$: Set of variables
+- $E$: Set of causal edges $(X \to Y)$
+
+The graph must satisfy acyclicity:
+
+$$\nexists \text{ path } X \to \cdots \to X$$
+
+## Graph Operations
+
+### Path Finding
+
+Find all paths from $X$ to $Y$:
+
+$$Paths(X, Y) = \{p : X \to^* Y\}$$
+
+### Confounder Identification
+
+Identify confounders $Z$ for relationship $X \to Y$:
+
+$$Z \in Confounders(X, Y) \iff Z \to X \text{ and } Z \to Y$$
+
+### Adjustment Sets
+
+Find valid adjustment set for $X \to Y$:
+
+$$Z \text{ valid } \iff Z \text{ blocks all backdoor paths}$$
+
+## Next Steps
+
+- [LLM Integration](llm-integration.md) - LLM integration architecture

docs/architecture/data-flow.md

@@ -0,0 +1,29 @@
+# Data Flow
+
+Data flow through the CR-CA system.
+
+## Causal Analysis Flow
+
+```mermaid
+graph LR
+    Input[Natural Language Input] --> Extract[Variable Extraction]
+    Extract --> Graph[Causal Graph Construction]
+    Graph --> SCM[SCM Fitting]
+    SCM --> Inference[Causal Inference]
+    Inference --> Counterfactual[Counterfactual Generation]
+    Counterfactual --> Output[Results]
+```
+
+## Mathematical Flow
+
+1. **Input**: Natural language task $T$
+2. **Extraction**: Variables $V = \{V_1, \ldots, V_n\}$
+3. **Graph**: Causal DAG $G = (V, E)$
+4. **SCM**: Structural equations $F = \{f_1, \ldots, f_n\}$
+5. **Inference**: Causal effects $E[Y | do(X=x)]$
+6. **Counterfactuals**: $P(Y_{x'} | X=x, Y=y)$
+
+## Next Steps
+
+- [Modular Structure](modular-structure.md) - Modular architecture
+- [Hybrid Agent](hybrid-agent/overview.md) - Hybrid agent architecture

docs/architecture/design-principles.md

@@ -0,0 +1,33 @@
+# Design Principles
+
+CR-CA is designed following key principles for maintainability and extensibility.
+
+## Principles
+
+### 1. Modularity
+
+Each component is self-contained with clear interfaces:
+
+$$M_i: I_i \to O_i$$
+
+Where $M_i$ is module $i$ with inputs $I_i$ and outputs $O_i$.
+
+### 2. Separation of Concerns
+
+- **Causal Reasoning**: Core SCM computation
+- **LLM Integration**: Natural language processing
+- **Application Logic**: Domain-specific implementations
+
+### 3. Extensibility
+
+New agents can be created by extending base classes:
+
+$$Agent_{new} = BaseAgent \oplus Mixins \oplus CustomLogic$$
+
+### 4. Mathematical Rigor
+
+All causal operations are mathematically grounded in Pearl's framework.
+
+## Next Steps
+
+- [Data Flow](data-flow.md) - Data flow diagrams

docs/architecture/hybrid-agent/components.md

@@ -0,0 +1,38 @@
+# Hybrid Agent Components
+
+Breakdown of hybrid agent components.
+
+## Core Components
+
+### Consistency Engine
+
+Ensures logical consistency across reasoning steps.
+
+### Conversation Manager
+
+Manages multi-turn conversations and context.
+
+### Explanation Generator
+
+Generates explanations for reasoning steps.
+
+### Task Decomposer
+
+Decomposes complex tasks into subtasks.
+
+### Self Verifier
+
+Verifies reasoning steps for correctness.
+
+## Mathematical Foundation
+
+Each component contributes to the overall reasoning:
+
+$$P(Correct | Components) = \prod_{i=1}^n P(Correct | C_i)$$
+
+Where $C_i$ are components.
+
+## Next Steps
+
+- [Consistency](consistency.md) - Consistency mechanisms
+- [Reasoning](reasoning.md) - Reasoning architecture

docs/architecture/hybrid-agent/consistency.md

@@ -0,0 +1,26 @@
+# Consistency Mechanisms
+
+How the hybrid agent ensures consistency across reasoning steps.
+
+## Overview
+
+Consistency mechanisms verify that reasoning steps are logically consistent and don't contradict previous conclusions.
+
+## Mathematical Foundation
+
+Consistency is checked using:
+
+$$\text{Consistent}(S_1, S_2) = \begin{cases}
+1 & \text{if } S_1 \not\models \neg S_2 \\
+0 & \text{otherwise}
+\end{cases}$$
+
+Where $S_1, S_2$ are reasoning steps.
+
+## Usage
+
+The consistency engine automatically checks consistency during reasoning.
+
+## Next Steps
+
+- [Reasoning](reasoning.md) - Reasoning architecture

docs/architecture/hybrid-agent/overview.md

@@ -0,0 +1,44 @@
+# Hybrid Agent Architecture
+
+The hybrid agent architecture combines multiple reasoning components.
+
+## Overview
+
+Hybrid agent integrates consistency engine, conversation manager, explanation generator, and other components.
+
+## Architecture
+
+```mermaid
+graph TB
+    HA[Hybrid Agent]
+    CE[Consistency Engine]
+    CM[Conversation Manager]
+    EG[Explanation Generator]
+    TD[Task Decomposer]
+    SV[Self Verifier]
+    
+    HA --> CE
+    HA --> CM
+    HA --> EG
+    HA --> TD
+    HA --> SV
+```
+
+## Mathematical Foundation
+
+Hybrid agent combines multiple reasoning modes:
+
+$$R_{hybrid} = \alpha R_{LLM} + \beta R_{deterministic} + \gamma R_{symbolic}$$
+
+Where $\alpha + \beta + \gamma = 1$ and each $R_i$ is a reasoning component.
+
+## Components
+
+- **[Consistency Engine](../features/hybrid-agent/consistency-engine.md)**: Ensures consistency
+- **[Conversation Manager](../features/hybrid-agent/conversation-manager.md)**: Manages dialogue
+- **[Task Decomposer](../features/hybrid-agent/task-decomposer.md)**: Decomposes tasks
+
+## Next Steps
+
+- [Components](components.md) - Component breakdown
+- [Consistency](consistency.md) - Consistency mechanisms

docs/architecture/hybrid-agent/reasoning.md

@@ -0,0 +1,22 @@
+# Reasoning Architecture
+
+The hybrid agent's reasoning architecture.
+
+## Overview
+
+Reasoning architecture combines multiple reasoning modes for robust inference.
+
+## Mathematical Foundation
+
+Reasoning combines:
+
+$$R_{final} = \arg\max_{r} \sum_{i} w_i P(r | M_i)$$
+
+Where:
+- $M_i$: Different reasoning modes
+- $w_i$: Weights for each mode
+- $P(r | M_i)$: Probability of result $r$ under mode $M_i$
+
+## Next Steps
+
+- [Causal Graphs](../causal-graphs.md) - Causal graph architecture

docs/architecture/llm-integration.md

@@ -0,0 +1,26 @@
+# LLM Integration Architecture
+
+Architecture for integrating large language models with causal reasoning.
+
+## Overview
+
+LLM integration enables natural language understanding and causal reasoning through language models.
+
+## Mathematical Foundation
+
+LLM-based causal inference approximates:
+
+$$P(Y | do(X=x)) \approx LLM(T, X, Y, Context)$$
+
+Where $T$ is the task description and $Context$ includes relevant information.
+
+## Integration Points
+
+1. **Variable Extraction**: Extract variables from natural language
+2. **Relationship Identification**: Identify causal relationships
+3. **Causal Inference**: Approximate causal effects
+4. **Explanation Generation**: Generate explanations
+
+## Next Steps
+
+- [Policy Engine Architecture](policy-engine-arch.md) - Policy engine architecture

docs/architecture/modular-structure.md

@@ -0,0 +1,37 @@
+# Modular Structure
+
+CR-CA's modular architecture enables flexible composition and extension.
+
+## Module Organization
+
+```
+CR-CA/
+├── CRCA.py              # Core agent
+├── utils/               # Utilities
+├── templates/          # Agent templates
+├── schemas/            # Data schemas
+├── branches/           # Specialized branches
+├── features/           # Feature modules
+└── architecture/       # Architecture components
+```
+
+## Module Dependencies
+
+Modules follow a dependency hierarchy:
+
+$$Core \to Utils \to Templates \to Branches$$
+
+Where each layer depends only on lower layers.
+
+## Mathematical Foundation
+
+Modules communicate through well-defined interfaces:
+
+$$f: M_1 \times M_2 \times \cdots \times M_n \to O$$
+
+Where $M_i$ are input modules and $O$ is the output.
+
+## Next Steps
+
+- [Hybrid Agent](hybrid-agent/overview.md) - Hybrid agent architecture
+- [Causal Graphs](causal-graphs.md) - Causal graph architecture

docs/architecture/overview.md

@@ -0,0 +1,69 @@
+# Architecture Overview
+
+CR-CA follows a modular architecture with clear separation of concerns.
+
+## System Architecture
+
+```mermaid
+graph TB
+    subgraph "Application Layer"
+        SD[CRCA-SD]
+        CG[CRCA-CG]
+        Q[CRCA-Q]
+    end
+    
+    subgraph "Core Layer"
+        CA[CRCAAgent]
+        CG2[Causal Graph]
+        SCM[SCM Engine]
+    end
+    
+    subgraph "Utils Layer"
+        U[Utils]
+        T[Tools]
+        TM[Templates]
+    end
+    
+    SD --> CA
+    CG --> CA
+    Q --> CA
+    CA --> CG2
+    CA --> SCM
+    CA --> U
+    CA --> T
+```
+
+## Mathematical Foundation
+
+The architecture implements a layered causal reasoning system:
+
+**Layer 1 - Application**: Domain-specific agents
+**Layer 2 - Core**: Causal reasoning engine with SCMs
+**Layer 3 - Utils**: Supporting utilities and tools
+
+The causal reasoning follows:
+
+$$Y = f(Pa(Y), U_Y)$$
+
+Where structural equations are defined at the core layer.
+
+## Key Components
+
+- **CRCAAgent**: Core causal reasoning agent
+- **Causal Graph**: DAG representation of causal relationships
+- **SCM Engine**: Structural causal model computation
+- **Utils**: Supporting utilities
+- **Templates**: Agent creation framework
+
+## Documentation
+
+- **[Design Principles](design-principles.md)**: Design principles
+- **[Data Flow](data-flow.md)**: Data flow diagrams
+- **[Modular Structure](modular-structure.md)**: Modular architecture
+- **[Hybrid Agent](hybrid-agent/overview.md)**: Hybrid agent architecture
+- **[Causal Graphs](causal-graphs.md)**: Causal graph architecture
+
+## Next Steps
+
+- [Design Principles](design-principles.md) - Design principles
+- [Data Flow](data-flow.md) - Data flow

docs/architecture/policy-engine-arch.md

@@ -0,0 +1,29 @@
+# Policy Engine Architecture
+
+Architecture for the policy engine system.
+
+## Overview
+
+Policy engine implements Model Predictive Control (MPC) for autonomous system control.
+
+## Mathematical Foundation
+
+Policy engine solves:
+
+$$\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$$
+
+## Components
+
+- **Doctrine**: Policy objectives and constraints
+- **Ledger**: State tracking and event storage
+- **Rollback**: Rollback mechanisms
+- **MPC**: Model Predictive Control solver
+
+## Next Steps
+
+- [API Reference](../api/crca/overview.md) - API documentation

docs/branches/crca-cg/corposwarm.md

@@ -0,0 +1,39 @@
+# CorporateSwarm
+
+CorporateSwarm is a multi-agent system for corporate governance decision-making.
+
+## Overview
+
+CorporateSwarm coordinates multiple specialized agents to make complex corporate governance decisions.
+
+## Architecture
+
+```mermaid
+graph TB
+    CS[CorporateSwarm]
+    A1[Agent 1]
+    A2[Agent 2]
+    A3[Agent 3]
+    CO[Coordinator]
+    
+    CS --> CO
+    CO --> A1
+    CO --> A2
+    CO --> A3
+    A1 --> CS
+    A2 --> CS
+    A3 --> CS
+```
+
+## Usage
+
+```python
+from branches.crca_cg.corposwarm import CorporateSwarm
+
+swarm = CorporateSwarm()
+decision = swarm.make_decision(problem)
+```
+
+## Next Steps
+
+- [ESG Scoring](esg-scoring.md) - ESG scoring system

docs/branches/crca-cg/esg-scoring.md

@@ -0,0 +1,30 @@
+# ESG Scoring
+
+ESG (Environmental, Social, and Governance) scoring system for corporate evaluation.
+
+## Overview
+
+ESG scoring evaluates companies based on environmental, social, and governance factors.
+
+## Mathematical Foundation
+
+ESG score is computed as:
+
+$$\text{ESG} = w_E \cdot S_E + w_S \cdot S_S + w_G \cdot S_G$$
+
+Where:
+- $S_E, S_S, S_G$: Environmental, Social, Governance sub-scores
+- $w_E, w_S, w_G$: Weights (typically $w_E + w_S + w_G = 1$)
+
+## Usage
+
+```python
+from branches.crca_cg.corposwarm import ESGScorer
+
+scorer = ESGScorer()
+score = scorer.compute_esg_score(company_data)
+```
+
+## Next Steps
+
+- [Multi-Agent](multi-agent.md) - Multi-agent orchestration

docs/branches/crca-cg/multi-agent.md

@@ -0,0 +1,35 @@
+# Multi-Agent Orchestration
+
+Multi-agent orchestration coordinates multiple agents for complex corporate governance decisions.
+
+## Overview
+
+Multi-agent systems enable distributed decision-making with specialized agents handling different aspects of governance.
+
+## Mathematical Foundation
+
+Multi-agent coordination can be modeled as:
+
+$$\max_{\{\mathbf{u}_i\}} \sum_{i=1}^n w_i J_i(\mathbf{u}_i, \mathbf{u}_{-i})$$
+
+Subject to:
+
+$$g(\mathbf{u}_1, \ldots, \mathbf{u}_n) \leq 0$$
+
+Where:
+- $\mathbf{u}_i$: Actions of agent $i$
+- $J_i$: Objective of agent $i$
+- $w_i$: Weight for agent $i$
+
+## Usage
+
+```python
+from branches.crca_cg.corposwarm import MultiAgentOrchestrator
+
+orchestrator = MultiAgentOrchestrator()
+decision = orchestrator.coordinate(agents, problem)
+```
+
+## Next Steps
+
+- [General Agent](../general-agent/overview.md) - General purpose agent

docs/branches/crca-cg/overview.md

@@ -0,0 +1,40 @@
+# CRCA-CG Overview
+
+CRCA-CG (CRCA for Corporate Governance) provides corporate governance capabilities with CorporateSwarm, ESG scoring, and multi-agent orchestration.
+
+## Overview
+
+CRCA-CG extends CR-CA for corporate governance applications, enabling multi-agent systems for organizational decision-making.
+
+## Key Features
+
+- **CorporateSwarm**: Multi-agent system for corporate governance
+- **ESG Scoring**: Environmental, Social, and Governance scoring
+- **Multi-Agent Orchestration**: Coordinate multiple agents for complex decisions
+
+## Mathematical Foundation
+
+Corporate governance decisions can be modeled as:
+
+$$\max_{\mathbf{d}} E[V(\mathbf{d}, \mathbf{s})]$$
+
+Subject to:
+
+$$g_i(\mathbf{d}, \mathbf{s}) \leq 0, \quad i = 1, \ldots, m$$
+
+Where:
+- $\mathbf{d}$: Decision vector
+- $\mathbf{s}$: System state
+- $V$: Value function
+- $g_i$: Governance constraints
+
+## Documentation
+
+- **[CorporateSwarm](corposwarm.md)**: CorporateSwarm implementation
+- **[ESG Scoring](esg-scoring.md)**: ESG scoring system
+- **[Multi-Agent](multi-agent.md)**: Multi-agent orchestration
+
+## Next Steps
+
+- [CorporateSwarm](corposwarm.md) - CorporateSwarm system
+- [ESG Scoring](esg-scoring.md) - ESG scoring

docs/branches/crca-q/alternative-data.md

@@ -0,0 +1,55 @@
+# Alternative Data Sources
+
+CRCA-Q integrates alternative data sources for enhanced signal generation.
+
+## Overview
+
+Alternative data includes on-chain metrics, social sentiment, news, GitHub activity, and exchange metrics.
+
+## Data Sources
+
+### On-Chain Metrics
+
+Ethereum/blockchain metrics:
+- Active addresses growth
+- Transaction volume trends
+- Network growth rate
+
+### Social Sentiment
+
+- Twitter sentiment (via Twitter API v2)
+- Reddit sentiment (via Reddit API)
+- Social volume metrics
+
+### News Sentiment
+
+- NewsAPI sentiment scores
+- Headline sentiment analysis
+
+## Mathematical Foundation
+
+Alternative data signals are weighted by confidence:
+
+$$S_{alt} = \sum_{i} w_i S_i$$
+
+Where:
+- $w_i$: Confidence weight for source $i$
+- $S_i$: Signal from source $i$
+
+Confidence weights consider:
+- Freshness (40%)
+- Reliability (40%)
+- Stability (20%)
+
+## Usage
+
+```python
+from branches.CRCA-Q import AltDataClient
+
+client = AltDataClient()
+alt_data = client.fetch_alternative_data("BTC")
+```
+
+## Next Steps
+
+- [Signal Generation](signal-generation.md) - Signal generation

docs/branches/crca-q/architecture.md

@@ -0,0 +1,71 @@
+# CRCA-Q Architecture
+
+CRCA-Q is organized into five major subsystems.
+
+## System Architecture
+
+```mermaid
+graph TB
+    subgraph "Data Layer"
+        MDC[MarketDataClient]
+        ADC[AltDataClient]
+    end
+    
+    subgraph "Signal Generation"
+        TSS[TimeSeriesSignals]
+        VS[VolatilitySignals]
+        LS[LiquiditySignals]
+    end
+    
+    subgraph "Causal Reasoning"
+        CE[CausalEngine]
+        CRCA[CRCAAgent]
+        SV[SignalValidator]
+    end
+    
+    subgraph "Portfolio Optimization"
+        PO[PortfolioOptimizer]
+        CE2[CovarianceEstimator]
+    end
+    
+    subgraph "Risk Management"
+        RM[RiskMonitor]
+        CB[CircuitBreaker]
+    end
+    
+    MDC --> TSS
+    ADC --> TSS
+    TSS --> SV
+    VS --> SV
+    LS --> SV
+    SV --> CE
+    CE --> CRCA
+    CE --> PO
+    PO --> RM
+    RM --> CB
+```
+
+## Data Flow
+
+1. **Data Acquisition**: MarketDataClient and AltDataClient fetch data
+2. **Signal Generation**: Multiple signal classes compute indicators
+3. **Causal Validation**: CausalEngine validates signals using SCMs
+4. **Prediction**: Ensemble models generate predictions
+5. **Portfolio Optimization**: PortfolioOptimizer allocates capital
+6. **Risk Management**: RiskMonitor and CircuitBreaker enforce limits
+7. **Execution**: ExecutionEngine places trades
+
+## Mathematical Foundation
+
+The system implements a causal graph:
+
+$$Sentiment \to Volume \to Liquidity \to Price Impact \to Returns$$
+
+Each relationship is validated using:
+
+$$P(Returns | do(Sentiment = s)) = \sum_{v,l} P(Returns | Sentiment=s, Volume=v, Liquidity=l) P(Volume=v, Liquidity=l | Sentiment=s)$$
+
+## Next Steps
+
+- [Market Data](market-data.md) - Market data client
+- [Signal Generation](signal-generation.md) - Signal generation