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

docs/branches/crca-q/backtesting.md

@@ -0,0 +1,45 @@
+# Backtesting Engine
+
+Backtesting engine for evaluating trading strategies.
+
+## Overview
+
+Backtesting engine performs walk-forward analysis to evaluate strategy performance on historical data.
+
+## Mathematical Foundation
+
+### Walk-Forward Analysis
+
+Rolling window approach:
+
+- Train window: $[T-H, T]$
+- Test window: $[T, T+h]$
+- Step forward: $T \leftarrow T + h$
+
+### Performance Metrics
+
+**Sharpe Ratio**:
+$$Sharpe = \frac{E[R] - R_f}{\sigma(R)}$$
+
+**Sortino Ratio**:
+$$Sortino = \frac{E[R] - R_f}{\sigma_{down}(R)}$$
+
+**Max Drawdown**:
+$$MDD = \max_t \frac{Peak_t - Value_t}{Peak_t}$$
+
+## Usage
+
+```python
+from branches.CRCA-Q import BacktestEngine
+
+engine = BacktestEngine()
+results = engine.backtest(
+    strategy=strategy,
+    data=historical_data,
+    initial_capital=100000
+)
+```
+
+## Next Steps
+
+- [Setup](setup.md) - Setup and configuration

docs/branches/crca-q/causal-engine.md

@@ -0,0 +1,33 @@
+# Causal Reasoning Engine
+
+The causal reasoning engine validates trading signals using causal inference.
+
+## Overview
+
+Causal engine builds Structural Causal Models and validates signals for causal validity rather than just correlation.
+
+## Mathematical Foundation
+
+Causal engine builds SCM:
+
+$$M_t = f_M(U_M, Vol_{t-1})$$
+$$Vol_t = f_Vol(U_Vol, L_t)$$
+$$L_t = f_L(U_L, Volume_t)$$
+$$Price_t = f_Price(U_Price, M_t, Vol_t, L_t)$$
+
+Signal validation checks:
+
+$$P(Returns | do(Signal=s)) \neq P(Returns)$$
+
+## Usage
+
+```python
+from branches.CRCA-Q import CausalEngine
+
+engine = CausalEngine()
+validated = engine.validate_signal(signal, target="returns")
+```
+
+## Next Steps
+
+- [Signal Validation](signal-validation.md) - Signal validation

docs/branches/crca-q/execution.md

@@ -0,0 +1,39 @@
+# Trade Execution
+
+Trade execution system for CRCA-Q.
+
+## Overview
+
+Execution engine places trades on exchanges, handling order placement, fills, and transaction costs.
+
+## Mathematical Foundation
+
+Execution accounts for:
+
+**Transaction Costs**:
+$$TC = Spread + Slippage + Fees$$
+
+Where:
+- $Spread = (Ask - Bid) / Mid$
+- $Slippage = \alpha \cdot \sqrt{Size / Volume}$
+- $Fees = Size \cdot FeeRate$
+
+**Market Impact**:
+$$Impact = 0.5 \cdot \sqrt{\frac{TradeValue}{DailyVolume}}$$
+
+## Usage
+
+```python
+from branches.CRCA-Q import ExecutionEngine
+
+engine = ExecutionEngine(exchange="kraken")
+result = engine.execute_trade(
+    signal='BUY',
+    size_fraction=0.1,
+    base_symbol='ETH'
+)
+```
+
+## Next Steps
+
+- [Backtesting](backtesting.md) - Backtesting engine

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

@@ -0,0 +1,60 @@
+# Market Data Client
+
+MarketDataClient fetches and normalizes market data from multiple sources.
+
+## Overview
+
+MarketDataClient provides a unified interface for accessing market data from various sources, normalizing it to a consistent schema.
+
+## Data Sources
+
+- **Crypto**: CoinGecko API (free tier)
+- **Stocks**: Yahoo Finance (via `yfinance`)
+- **FX/Futures**: Yahoo Finance with symbol transformations
+
+## Unified Schema
+
+All data is normalized to:
+
+```python
+{
+    'date': pd.Timestamp,
+    'price': float,      # Close price
+    'volume': float,     # Trading volume
+    'market_cap': float, # Market capitalization
+    'returns': float     # Computed returns
+}
+```
+
+## Usage
+
+```python
+from branches.CRCA-Q import MarketDataClient
+
+client = MarketDataClient()
+
+# Fetch single asset
+data = client.fetch_price_data("BTC", days=365)
+
+# Fetch multiple assets
+multi_data = client.fetch_multiple_assets(["BTC", "ETH"], days=365)
+
+# Compute covariance
+covariance = client.compute_multi_asset_covariance(multi_data)
+```
+
+## Mathematical Foundation
+
+Returns are computed as:
+
+$$r_t = \frac{P_t - P_{t-1}}{P_{t-1}} = \frac{\Delta P_t}{P_{t-1}}$$
+
+Covariance is estimated using EWMA:
+
+$$\Sigma_t = (1-\alpha) \Sigma_{t-1} + \alpha r_t r_t'$$
+
+Where $\alpha = 0.06$ (decay factor).
+
+## Next Steps
+
+- [Signal Generation](signal-generation.md) - Generate trading signals

docs/branches/crca-q/overview.md

@@ -0,0 +1,58 @@
+# CRCA-Q Overview
+
+CRCA-Q is a quantitative trading system that integrates causal reasoning with traditional quantitative finance techniques.
+
+## Executive Summary
+
+CRCA-Q uses **causal inference** to understand *why* market movements occur, enabling more robust predictions that remain valid across different market regimes. Unlike correlation-based systems, CRCA-Q implements Structural Causal Models (SCMs) based on Judea Pearl's framework.
+
+## Key Features
+
+- **Causal Signal Validation**: Validates trading signals using causal reasoning
+- **Portfolio Optimization**: CVaR-based portfolio optimization
+- **Risk Management**: Multi-layer risk controls and circuit breakers
+- **Alternative Data**: Integration with on-chain, social, and news data
+- **Backtesting**: Walk-forward analysis and performance metrics
+
+## Mathematical Foundation
+
+CRCA-Q implements Structural Causal Models for market variables:
+
+$$M_t = f_M(U_M, Vol_{t-1})$$
+$$Vol_t = f_Vol(U_Vol, L_t)$$
+$$L_t = f_L(U_L, Volume_t)$$
+$$Price_t = f_Price(U_Price, M_t, Vol_t, L_t)$$
+
+Where:
+- $M_t$: Momentum
+- $Vol_t$: Volatility
+- $L_t$: Liquidity
+- $Price_t$: Price
+
+## Philosophy
+
+### Causal vs. Correlational Trading
+
+Traditional systems rely on correlations: "When X happens, Y tends to follow."
+
+CRCA-Q uses causal reasoning: "X *causes* Y through mechanism Z."
+
+This approach is more robust because:
+- It explains *why* relationships exist
+- It predicts behavior under interventions
+- It remains valid across market regimes
+
+## Documentation
+
+- **[Philosophy](philosophy.md)**: Causal vs. correlational trading
+- **[Architecture](architecture.md)**: System architecture
+- **[Market Data](market-data.md)**: Market data client
+- **[Signal Generation](signal-generation.md)**: Signal generation classes
+- **[Portfolio Optimization](portfolio-optimization.md)**: Portfolio optimization
+- **[Risk Management](risk-management.md)**: Risk management framework
+- **[Setup](setup.md)**: Setup and configuration
+
+## Next Steps
+
+- [Philosophy](philosophy.md) - Understand the causal approach
+- [Architecture](architecture.md) - System architecture

docs/branches/crca-q/philosophy.md

@@ -0,0 +1,60 @@
+# Causal vs. Correlational Trading
+
+CRCA-Q's fundamental philosophy is based on causal reasoning rather than correlation-based patterns.
+
+## The Fundamental Problem
+
+Traditional quantitative trading systems rely heavily on **correlational patterns**: "When X happens, Y tends to follow." This approach has critical limitations:
+
+1. **Regime Dependency**: Correlations break down when market regimes change (e.g., bull vs. bear markets)
+2. **Spurious Relationships**: Many correlations are coincidental, not causal
+3. **Lack of Interpretability**: It's unclear *why* a signal works
+4. **Overfitting Risk**: Complex models can memorize patterns without understanding mechanisms
+
+## The Causal Solution
+
+CRCA-Q implements **causal reasoning** based on Judea Pearl's framework:
+
+- **Structural Causal Models (SCMs)**: Represent market variables as nodes in a DAG
+- **Do-Calculus**: Reason about interventions using Pearl's do-operator
+- **Counterfactual Reasoning**: Answer "what would have happened if" questions
+- **Confounder Identification**: Distinguish direct causal effects from spurious correlations
+
+## Mathematical Foundation
+
+### Correlation vs. Causation
+
+**Correlation**: $P(Y | X) \neq P(Y)$
+
+**Causation**: $P(Y | do(X)) \neq P(Y)$
+
+The key difference is the do-operator, which represents intervention rather than observation.
+
+### Causal Effect
+
+The causal effect of $X$ on $Y$ is:
+
+$$E[Y | do(X=x)] = \sum_{z} E[Y | X=x, Z=z] P(Z=z)$$
+
+Where $Z$ are confounders that need to be adjusted for.
+
+## Example: Volume and Price
+
+**Correlational view**: "High volume correlates with price increases"
+
+**Causal view**: "High volume *causes* increased liquidity, which *causes* reduced price impact, which *causes* more efficient price discovery"
+
+The causal view is more robust because it explains *why* the relationship exists and can predict behavior under interventions.
+
+## Why This Matters
+
+Causal models:
+- Explain *why* relationships exist
+- Predict behavior under interventions
+- Remain valid across different market regimes
+- Enable robust counterfactual analysis
+
+## Next Steps
+
+- [Architecture](architecture.md) - System architecture
+- [Signal Generation](signal-generation.md) - Causal signal validation

docs/branches/crca-q/portfolio-optimization.md

@@ -0,0 +1,66 @@
+# Portfolio Optimization
+
+CRCA-Q uses Conditional Value at Risk (CVaR) optimization for portfolio allocation.
+
+## Overview
+
+Portfolio optimization allocates capital based on expected returns, covariance, and risk constraints.
+
+## Mathematical Foundation
+
+### Optimization Problem
+
+Maximize expected return subject to risk constraints:
+
+$$\max_{\mathbf{w}} \boldsymbol{\mu}' \mathbf{w} - \lambda \mathbf{w}' \boldsymbol{\Sigma} \mathbf{w}$$
+
+Subject to:
+
+$$\sum_{i} |w_i| \leq L$$
+$$w_i \geq -L, \quad w_i \leq L$$
+$$\sum_{i \in T} |w_i| \leq L_T$$
+
+Where:
+- $\boldsymbol{\mu}$: Expected returns vector
+- $\boldsymbol{\Sigma}$: Covariance matrix
+- $\mathbf{w}$: Portfolio weights
+- $\lambda$: Risk aversion parameter
+- $L$: Maximum leverage
+- $L_T$: Maximum exposure per asset type $T$
+
+### CVaR Optimization
+
+CVaR (Conditional Value at Risk) measures expected loss in worst-case scenarios:
+
+$$\text{CVaR}_\alpha = E[Loss | Loss \geq \text{VaR}_\alpha]$$
+
+Where $\text{VaR}_\alpha$ is the Value at Risk at confidence level $\alpha$.
+
+## Usage
+
+```python
+from branches.CRCA-Q import PortfolioOptimizer
+
+optimizer = PortfolioOptimizer()
+
+weights = optimizer.optimize(
+    expected_returns=mu,
+    covariance=sigma,
+    risk_aversion=1.0,
+    max_leverage=1.0
+)
+```
+
+## Covariance Estimation
+
+Covariance is estimated using EWMA:
+
+$$\boldsymbol{\Sigma}_t = (1-\alpha) \boldsymbol{\Sigma}_{t-1} + \alpha \mathbf{r}_t \mathbf{r}_t'$$
+
+With shrinkage for stability:
+
+$$\boldsymbol{\Sigma}_{shrink} = \beta \frac{\text{tr}(\boldsymbol{\Sigma})}{n} \mathbf{I} + (1-\beta) \boldsymbol{\Sigma}$$
+
+## Next Steps
+
+- [Risk Management](risk-management.md) - Risk management framework

docs/branches/crca-q/risk-management.md

@@ -0,0 +1,102 @@
+# Risk Management Framework
+
+CRCA-Q implements comprehensive risk management with multiple layers of protection.
+
+## Overview
+
+Risk management includes position limits, leverage constraints, correlation limits, volatility limits, drawdown limits, and circuit breakers.
+
+## Risk Constraints
+
+### Position Size Limits
+
+Maximum position per asset:
+
+$$|w_i| \leq w_{max}$$
+
+Where $w_{max}$ is typically 15-20% of portfolio.
+
+### Leverage Limits
+
+Total leverage constraint:
+
+$$\sum_i |w_i| \leq L_{max}$$
+
+Where $L_{max}$ is maximum leverage (default: 1.0 for no leverage).
+
+### Correlation Limits
+
+Prevent over-concentration:
+
+$$\rho_{i,j} \leq \rho_{max}$$
+
+Where $\rho_{max}$ is typically 0.8.
+
+### Volatility Limits
+
+Portfolio volatility constraint:
+
+$$\sqrt{\mathbf{w}' \boldsymbol{\Sigma} \mathbf{w}} \leq \sigma_{max}$$
+
+Where $\sigma_{max}$ is maximum portfolio volatility (default: 20% annualized).
+
+### Drawdown Limits
+
+Maximum allowed drawdown:
+
+$$\text{DD}_t = \frac{\text{Peak}_t - \text{Value}_t}{\text{Peak}_t} \leq \text{DD}_{max}$$
+
+Where $\text{DD}_{max}$ is typically 15%.
+
+## Circuit Breakers
+
+### Daily Loss Limit
+
+Maximum daily loss:
+
+$$\text{Daily Loss}_t \leq \text{Loss}_{max}$$
+
+Where $\text{Loss}_{max}$ is typically 5% of portfolio.
+
+### Trade Frequency Limit
+
+Maximum trades per day:
+
+$$N_{trades} \leq N_{max}$$
+
+Where $N_{max}$ is typically 50 trades/day.
+
+### Kill Switch
+
+Manual emergency stop via file check.
+
+## Mathematical Foundation
+
+Risk-adjusted returns use Sharpe ratio:
+
+$$\text{Sharpe} = \frac{E[R] - R_f}{\sigma(R)}$$
+
+Where $R_f$ is the risk-free rate.
+
+## Usage
+
+```python
+from branches.CRCA-Q import RiskMonitor
+
+monitor = RiskMonitor(
+    max_position_size=0.15,
+    max_leverage=1.0,
+    max_drawdown=0.15
+)
+
+is_valid, reason, adjusted_size = monitor.pre_trade_check(
+    signal='BUY',
+    position_size=0.20,
+    current_positions={},
+    portfolio_value=10000
+)
+```
+
+## Next Steps
+
+- [Setup](setup.md) - Setup and configuration

docs/branches/crca-q/setup.md

@@ -0,0 +1,65 @@
+# CRCA-Q Setup
+
+Setup and configuration guide for CRCA-Q.
+
+## Installation
+
+```bash
+# Install trading dependencies
+pip install ccxt web3
+
+# Or install all optional dependencies
+pip install crca[trading]
+```
+
+## Environment Variables
+
+Create `.env` file:
+
+```bash
+# Required for LLM
+OPENAI_API_KEY=your_openai_key
+
+# For live trading (Kraken example)
+KRAKEN_API_KEY=your_kraken_key
+KRAKEN_API_SECRET=your_kraken_secret
+
+# For alternative data
+TWITTER_BEARER_TOKEN=your_twitter_token
+NEWSAPI_KEY=your_newsapi_key
+ETHERSCAN_API_KEY=your_etherscan_key
+THEGRAPH_API_KEY=your_thegraph_key
+```
+
+## Configuration
+
+```python
+TRADING_CONFIG = {
+    'account_size': 10000,
+    'max_position_size': 0.3,
+    'max_position_hard_cap': 0.3,
+    'min_trade_value': 5.0,
+    'conservative_mode': True,
+    'stop_loss_pct': -10.0,
+    'stop_gain_pct': 20.0
+}
+```
+
+## Quick Start
+
+```python
+from branches.CRCA-Q import QuantTradingAgent
+
+agent = QuantTradingAgent(
+    account_size=10000,
+    dry_run=True  # Start in demo mode
+)
+
+result = agent.run("BTC")
+print(result)
+```
+
+## Next Steps
+
+- [Overview](overview.md) - Return to overview
+- [Architecture](architecture.md) - System architecture

docs/branches/crca-q/signal-generation.md

@@ -0,0 +1,61 @@
+# Signal Generation
+
+CRCA-Q generates hundreds of signals across multiple categories for trading decisions.
+
+## Signal Categories
+
+### Time-Series Signals
+
+Technical indicators based on price/volume history:
+
+- **Momentum**: $\log(P_t) - \log(P_{t-k})$ for lookback $k$
+- **Reversal**: Negative of recent returns
+- **MA Distance**: Distance from price to moving average
+
+### Volatility Signals
+
+Measure and predict volatility:
+
+- **Realized Volatility**: $\sqrt{\frac{1}{n}\sum_{i=1}^n (r_i - \bar{r})^2}$
+- **GARCH Volatility**: GARCH(1,1) model
+- **Vol of Vol**: Volatility of volatility
+
+### Liquidity Signals
+
+Measure market depth:
+
+- **Amihud Illiquidity**: $\frac{|r_t|}{V_t}$ (price impact per volume)
+- **VPIN**: Volume-synchronized probability of informed trading
+- **Turnover**: $\frac{V_t}{MC_t}$ (volume to market cap ratio)
+
+## Mathematical Foundation
+
+Signals are computed and then validated using causal reasoning. A signal $S$ is causally valid if:
+
+$$P(Returns | do(S=s)) \neq P(Returns)$$
+
+And the relationship is stable across regimes:
+
+$$\text{Var}(P(Returns | do(S=s), Regime=r)) < \epsilon$$
+
+## Signal Validation
+
+Signals are validated using:
+
+1. **Mutual Information**: Information-theoretic relationship
+2. **Regime Invariance**: Stability across market regimes
+3. **Structural Consistency**: Mapping to SCM structure
+
+## Usage
+
+```python
+from branches.CRCA-Q import QuantTradingAgent
+
+agent = QuantTradingAgent()
+signals = agent.compute_signals(data)
+validated = agent.validate_signals(signals)
+```
+
+## Next Steps
+
+- [Portfolio Optimization](portfolio-optimization.md) - Optimize portfolio allocation

docs/branches/crca-q/signal-validation.md

@@ -0,0 +1,43 @@
+# Signal Validation
+
+Signal validation ensures trading signals are causally valid, not just correlated.
+
+## Overview
+
+Signal validation uses causal criteria to filter out spurious signals that may break down in different market regimes.
+
+## Mathematical Foundation
+
+Signals are validated using:
+
+### Causal Score
+
+$$Score(S) = w_1 \cdot MI(S, Y) + w_2 \cdot RI(S, Y) + w_3 \cdot SC(S)$$
+
+Where:
+- $MI$: Mutual information (40% weight)
+- $RI$: Regime invariance (40% weight)
+- $SC$: Structural consistency (20% weight)
+
+### Regime Invariance
+
+$$RI(S, Y) = 1 - \text{Var}(Corr(S, Y | Regime=r))$$
+
+Causal signals should be stable across regimes.
+
+## Usage
+
+```python
+from branches.CRCA-Q import SignalValidator
+
+validator = SignalValidator()
+score = validator.compute_causal_score(
+    signal_name="momentum",
+    signal_values=signals,
+    target=returns
+)
+```
+
+## Next Steps
+
+- [Portfolio Optimization](portfolio-optimization.md) - Portfolio optimization