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

docs/core/utils/conversation.md

@@ -0,0 +1,27 @@
+# Conversation Management
+
+The conversation module manages conversation state and history for CR-CA agents.
+
+## Overview
+
+Conversation management tracks dialogue context, maintains history, and manages multi-turn interactions.
+
+## Usage
+
+```python
+from utils.conversation import ConversationManager
+
+manager = ConversationManager()
+manager.add_message("user", "Analyze X -> Y")
+manager.add_message("assistant", result)
+```
+
+## Features
+
+- Conversation history tracking
+- Context management
+- Multi-turn dialogue support
+
+## Next Steps
+
+- [Graph Reasoner](graph-reasoner.md) - Graph reasoning utilities

docs/core/utils/graph-reasoner.md

@@ -0,0 +1,29 @@
+# Graph Reasoner
+
+The graph reasoner module provides utilities for reasoning about causal graphs.
+
+## Overview
+
+Graph reasoner utilities help analyze causal graphs, find paths, identify confounders, and compute causal effects.
+
+## Mathematical Foundation
+
+Graph reasoning uses graph algorithms to:
+
+1. **Path Finding**: Find all paths between variables
+2. **Confounder Identification**: Identify variables that confound relationships
+3. **Adjustment Sets**: Find valid adjustment sets for causal identification
+
+## Usage
+
+```python
+from utils.graph_reasoner import GraphReasoner
+
+reasoner = GraphReasoner(graph)
+paths = reasoner.find_paths("X", "Y")
+confounders = reasoner.identify_confounders("X", "Y")
+```
+
+## Next Steps
+
+- [Batch Processor](batch-processor.md) - Batch processing

docs/core/utils/overview.md

@@ -0,0 +1,27 @@
+# Utils Overview
+
+The `utils/` module provides utility functions and extensions for CR-CA.
+
+## Modules
+
+- **[Formatter](formatter.md)**: Text formatting and output utilities
+- **[Router](router.md)**: Request routing and agent selection
+- **[Conversation](conversation.md)**: Conversation management
+- **[Graph Reasoner](graph-reasoner.md)**: Graph reasoning utilities
+- **[Batch Processor](batch-processor.md)**: Batch processing utilities
+- **[Rate Limiter](rate-limiter.md)**: Rate limiting for API calls
+- **[Agent Discovery](agent-discovery.md)**: Agent discovery and registration
+- **[Tool Discovery](tool-discovery.md)**: Tool discovery and registration
+
+## Common Use Cases
+
+- Formatting agent outputs
+- Managing conversations
+- Routing requests to appropriate agents
+- Processing batches of tasks
+- Rate limiting API calls
+
+## Next Steps
+
+- [Formatter](formatter.md) - Format outputs
+- [Router](router.md) - Route requests

docs/core/utils/router.md

@@ -0,0 +1,27 @@
+# Router
+
+The router module provides request routing and agent selection functionality.
+
+## Overview
+
+Router helps select appropriate agents for specific tasks based on capabilities and availability.
+
+## Usage
+
+```python
+from utils.router import Router
+
+router = Router()
+agent = router.select_agent(task="Analyze causal relationships")
+```
+
+## Features
+
+- Agent capability matching
+- Load balancing
+- Fallback mechanisms
+
+## Next Steps
+
+- [Conversation](conversation.md) - Conversation management
+- [Graph Reasoner](graph-reasoner.md) - Graph reasoning

docs/core/utils/utilities.md

@@ -0,0 +1,97 @@
+# Utility Functions
+
+Grouped documentation for smaller utility modules.
+
+## Formatter
+
+Text formatting and output utilities for CR-CA agents.
+
+### Functions
+
+- `format_causal_result()`: Format causal analysis results
+- `format_graph()`: Format causal graph for display
+- `format_counterfactuals()`: Format counterfactual scenarios
+
+### Usage
+
+```python
+from utils.formatter import format_causal_result
+
+result = agent.run("Analyze X -> Y")
+formatted = format_causal_result(result)
+```
+
+## Batch Processor
+
+Batch processing utilities for processing multiple tasks.
+
+### Usage
+
+```python
+from utils.batch_processor import BatchProcessor
+
+processor = BatchProcessor(agent)
+results = processor.process_batch(tasks)
+```
+
+## Rate Limiter
+
+Rate limiting for API calls to prevent exceeding rate limits.
+
+### Usage
+
+```python
+from utils.rate_limiter import RateLimiter
+
+limiter = RateLimiter(max_calls=100, period=60)
+limiter.wait_if_needed()
+```
+
+## Agent Discovery
+
+Agent discovery and registration utilities.
+
+### Usage
+
+```python
+from utils.agent_discovery import AgentDiscovery
+
+discovery = AgentDiscovery()
+agents = discovery.discover_agents()
+```
+
+## Tool Discovery
+
+Tool discovery and registration utilities.
+
+### Usage
+
+```python
+from utils.tool_discovery import ToolDiscovery
+
+discovery = ToolDiscovery()
+tools = discovery.discover_tools()
+```
+
+## Edit Distance
+
+Edit distance algorithms for text correction.
+
+### Mathematical Foundation
+
+Levenshtein distance calculates minimum edit operations:
+
+$$D_{lev}(s_1, s_2) = \min\{Insertions, Deletions, Substitutions\}$$
+
+### Usage
+
+```python
+from utils.edit_distance import levenshtein_distance
+
+distance = levenshtein_distance("hello", "hallo")
+```
+
+## Next Steps
+
+- [Router](router.md) - Request routing
+- [Conversation](conversation.md) - Conversation management

docs/css/custom.css

@@ -0,0 +1,84 @@
+/* EuroSwarms-inspired custom styling for CR-CA documentation */
+
+/* Typography - Serif headings, sans-serif body */
+:root {
+  --md-text-font: "Inter", "Helvetica Neue", Arial, sans-serif;
+  --md-code-font: "Roboto Mono", monospace;
+}
+
+/* Override heading fonts to use serif */
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3,
+.md-typeset h4,
+.md-typeset h5,
+.md-typeset h6 {
+  font-family: "Crimson Text", Georgia, "Times New Roman", serif;
+  font-weight: 600;
+}
+
+/* Background color matching EuroSwarms */
+body {
+  background-color: #F5F7FA;
+}
+
+.md-typeset {
+  color: #1A1A1A;
+}
+
+/* Custom list bullets using ▸ character */
+.md-typeset ul li::marker {
+  content: "▸ ";
+  color: #1A1A1A;
+}
+
+/* Card-based sections with subtle shadows */
+.md-typeset .admonition,
+.md-typeset details {
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+  border-radius: 4px;
+}
+
+/* Code blocks with subtle borders */
+.md-typeset pre {
+  border: 1px solid #E0E0E0;
+  border-radius: 4px;
+}
+
+/* Links with subtle underline on hover */
+.md-typeset a {
+  color: #1A1A1A;
+  text-decoration: none;
+  border-bottom: 1px solid transparent;
+  transition: border-color 0.2s;
+}
+
+.md-typeset a:hover {
+  border-bottom-color: #1A1A1A;
+}
+
+/* Spacing adjustments */
+.md-typeset {
+  line-height: 1.7;
+}
+
+.md-typeset p {
+  margin-bottom: 1em;
+}
+
+/* Navigation styling */
+.md-nav__title {
+  font-family: "Crimson Text", Georgia, "Times New Roman", serif;
+}
+
+/* Math rendering improvements */
+.MathJax {
+  font-size: 1.1em;
+}
+
+/* Responsive adjustments */
+@media screen and (max-width: 76.25em) {
+  .md-nav--primary .md-nav__title {
+    font-family: "Crimson Text", Georgia, "Times New Roman", serif;
+  }
+}

docs/examples/basic-usage.md

@@ -0,0 +1,57 @@
+# Basic Usage Examples
+
+Basic examples for getting started with CR-CA.
+
+## Simple Causal Analysis
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="basic-agent"
+)
+
+result = agent.run("What is the causal relationship between education and income?")
+print(result)
+```
+
+## Causal Graph Construction
+
+```python
+# Add variables
+agent.add_variable("education")
+agent.add_variable("income")
+agent.add_variable("experience")
+
+# Add relationships
+agent.add_causal_relationship("education", "income", strength=0.6)
+agent.add_causal_relationship("experience", "income", strength=0.4)
+
+# View graph
+graph = agent.causal_graph
+print(graph.get_variables())
+```
+
+## Counterfactual Analysis
+
+```python
+counterfactuals = agent.generate_counterfactuals(
+    intervention={"education": "college"},
+    outcome="income"
+)
+
+for cf in counterfactuals:
+    print(f"Expected income: ${cf.expected_outcome:,.2f}")
+```
+
+## Mathematical Foundation
+
+The causal effect is computed as:
+
+$$E[Income | do(Education = college)] = \sum_{z} E[Income | Education = college, Z = z] P(Z = z)$$
+
+## Next Steps
+
+- [General Agent](general-agent/quickstart.md) - General agent examples
+- [Hybrid Agent](hybrid-agent/auto-extraction.md) - Hybrid agent examples

docs/examples/general-agent/general-agent-examples.md

@@ -0,0 +1,50 @@
+# General Agent Examples
+
+Comprehensive examples for GeneralAgent usage.
+
+## Quickstart
+
+Basic usage of GeneralAgent:
+
+```python
+from branches.general_agent.general_agent import GeneralAgent
+
+agent = GeneralAgent(
+    model_name="gpt-4o-mini",
+    enable_multimodal=True
+)
+
+response = agent.run("Hello, how can you help me?")
+```
+
+## Simple Example
+
+Simple example using GeneralAgent:
+
+```python
+agent = GeneralAgent(model_name="gpt-4o-mini")
+response = agent.run("Analyze this data")
+print(response)
+```
+
+## Advanced Usage
+
+Advanced usage with personality and multimodal support:
+
+```python
+from branches.general_agent.general_agent import GeneralAgent
+from branches.general_agent.personality import Personality
+
+personality = Personality(traits=["analytical", "detailed"])
+agent = GeneralAgent(
+    model_name="gpt-4o-mini",
+    enable_multimodal=True,
+    personality=personality
+)
+
+response = agent.run("Analyze this image and provide detailed analysis")
+```
+
+## Next Steps
+
+- [Hybrid Agent Examples](../hybrid-agent/hybrid-agent-examples.md) - Hybrid agent examples

docs/examples/hybrid-agent/hybrid-agent-examples.md

@@ -0,0 +1,56 @@
+# Hybrid Agent Examples
+
+Comprehensive examples for hybrid agent usage.
+
+## Auto Extraction
+
+Automatic variable extraction with hybrid agent:
+
+```python
+from architecture.hybrid.hybrid_agent import HybridAgent
+
+agent = HybridAgent(model_name="gpt-4o-mini")
+
+task = """
+Analyze how increasing minimum wage affects employment.
+Consider inflation, business costs, and consumer spending.
+"""
+
+result = agent.run(task)
+# Variables and relationships are automatically extracted
+```
+
+## Dictionary Demo
+
+Dictionary extraction demo:
+
+```python
+task = "Extract all key-value pairs from the following text..."
+result = agent.run(task)
+```
+
+## Enhanced Features
+
+Enhanced hybrid agent features:
+
+```python
+agent = HybridAgent(
+    model_name="gpt-4o-mini",
+    enable_consistency_checking=True,
+    enable_self_verification=True
+)
+
+result = agent.run("Complex multi-step reasoning task")
+```
+
+## General Knowledge
+
+General knowledge tasks:
+
+```python
+result = agent.run("Explain quantum computing in simple terms")
+```
+
+## Next Steps
+
+- [Image Annotation Examples](../image-annotation/image-annotation-examples.md) - Image annotation examples

docs/examples/image-annotation/image-annotation-examples.md

@@ -0,0 +1,54 @@
+# Image Annotation Examples
+
+Comprehensive examples for image annotation usage.
+
+## Quickstart
+
+Basic annotation:
+
+```python
+from image_annotation import ImageAnnotationEngine
+
+engine = ImageAnnotationEngine()
+result = engine.annotate("image.png", output="all")
+
+print(f"Found {len(result.annotation_graph.entities)} entities")
+print(result.formal_report)
+```
+
+## With CRCAAgent
+
+Integration with CRCAAgent:
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    use_image_annotation=True
+)
+
+response = agent.run("Analyze the image at path/to/image.png")
+```
+
+## Operational Examples
+
+Batch processing and production scenarios:
+
+```python
+engine = ImageAnnotationEngine(
+    cache_enabled=True,
+    parallel_workers=4
+)
+
+# Batch process images
+results = engine.annotate(["img1.png", "img2.png", "img3.png"])
+
+# Analyze results
+for result in results:
+    print(f"Entities: {len(result.annotation_graph.entities)}")
+```
+
+## Next Steps
+
+- [Trading Examples](../trading/trading-examples.md) - Trading examples

docs/examples/integration/integration-examples.md

@@ -0,0 +1,58 @@
+# Integration Examples
+
+Examples of integrating CR-CA with other systems.
+
+## CRCA-SD Integration
+
+Integration with CRCA-SD for socioeconomic dynamics:
+
+```python
+from branches.crca_sd.crca_sd_core import StateVector, DynamicsModel
+from CRCA import CRCAAgent
+
+crca = CRCAAgent(model_name="gpt-4o-mini")
+state = StateVector(P=1000000)
+dynamics = DynamicsModel()
+
+result = crca.run("Analyze policy impact on GDP")
+```
+
+## CRCA-CG Integration
+
+Integration with CRCA-CG for corporate governance:
+
+```python
+from branches.crca_cg.corposwarm import CorporateSwarm
+from CRCA import CRCAAgent
+
+crca = CRCAAgent(model_name="gpt-4o-mini")
+swarm = CorporateSwarm()
+
+result = crca.run("Analyze governance decision impact")
+```
+
+## Palantir Integration
+
+Integration with Palantir systems:
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(model_name="gpt-4o-mini")
+result = agent.run("Analyze data from Palantir system")
+```
+
+## Data Broker Integration
+
+Integration with data broker systems:
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(model_name="gpt-4o-mini")
+result = agent.run("Fetch and analyze data from broker")
+```
+
+## Next Steps
+
+- [Architecture](../architecture/overview.md) - System architecture

docs/examples/overview.md

@@ -0,0 +1,37 @@
+# Examples Overview
+
+This section provides code examples and tutorials for using CR-CA.
+
+## Example Categories
+
+- **[Basic Usage](basic-usage.md)**: Basic agent examples
+- **[General Agent](general-agent/quickstart.md)**: General agent examples
+- **[Hybrid Agent](hybrid-agent/auto-extraction.md)**: Hybrid agent examples
+- **[Image Annotation](image-annotation/quickstart.md)**: Image annotation examples
+- **[Trading](trading/crca-q-basic.md)**: Trading examples
+- **[Integration](integration/crca-sd.md)**: Integration examples
+
+## Quick Examples
+
+### Basic Agent
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(model_name="gpt-4o-mini")
+result = agent.run("Analyze X -> Y")
+```
+
+### Image Annotation
+
+```python
+from image_annotation import ImageAnnotationEngine
+
+engine = ImageAnnotationEngine()
+result = engine.annotate("image.png")
+```
+
+## Next Steps
+
+- [Basic Usage](basic-usage.md) - Start with basics
+- [General Agent](general-agent/quickstart.md) - General agent examples

docs/examples/trading/trading-examples.md

@@ -0,0 +1,46 @@
+# Trading Examples
+
+Comprehensive examples for CRCA-Q quantitative trading.
+
+## Basic Usage
+
+Basic trading with CRCA-Q:
+
+```python
+from branches.CRCA-Q import QuantTradingAgent
+
+agent = QuantTradingAgent(
+    account_size=10000,
+    dry_run=True
+)
+
+result = agent.run("BTC")
+print(result)
+```
+
+## Mathematical Foundation
+
+CRCA-Q uses causal signals validated through:
+
+$$P(Returns | do(Signal = s)) \neq P(Returns)$$
+
+Where signals are validated for causal validity.
+
+## Advanced Trading
+
+Multi-asset and advanced features:
+
+```python
+agent = QuantTradingAgent(
+    account_size=100000,
+    multi_asset_mode=True,
+    asset_rotation_enabled=True
+)
+
+# Multi-asset analysis
+result = agent.run(["BTC", "ETH", "SOL"])
+```
+
+## Next Steps
+
+- [Integration Examples](../integration/integration-examples.md) - Integration examples