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

docs/features/image-annotation/integration.md

@@ -0,0 +1,75 @@
+# Integration with Agents
+
+Image annotation integrates seamlessly with CRCAAgent and GeneralAgent.
+
+## CRCAAgent Integration
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    use_image_annotation=True
+)
+
+# Agent automatically has annotate_image and query_image tools
+response = agent.run("Analyze the image at path/to/image.png")
+```
+
+## Available Tools
+
+When `use_image_annotation=True`, the agent gets:
+
+1. **`annotate_image`**: Annotate an image and get structured results
+2. **`query_image`**: Query an annotated image with natural language
+
+## Manual Tool Usage
+
+```python
+annotate_tool = agent.tools_list_dictionary.get("annotate_image")
+query_tool = agent.tools_list_dictionary.get("query_image")
+
+# Use annotate_image
+result = annotate_tool(
+    image_path="path/to/image.png",
+    output_format="all"
+)
+
+# Use query_image
+answer = query_tool(
+    image_path="path/to/image.png",
+    query="What is the largest object?"
+)
+```
+
+## GeneralAgent Integration
+
+```python
+from branches.general_agent.general_agent import GeneralAgent
+
+agent = GeneralAgent(
+    model_name="gpt-4o-mini",
+    enable_multimodal=True  # Enables image annotation
+)
+```
+
+## Combined Analysis
+
+Combine image analysis with causal reasoning:
+
+```python
+task = """
+Analyze the tactical map at path/to/map.png:
+1. Identify all military installations
+2. Measure distances between key targets
+3. Extract causal variables from the map
+4. Perform causal analysis
+"""
+
+response = agent.run(task)
+```
+
+## Next Steps
+
+- [Overview](overview.md) - Return to overview
+- [Policy Engine](../policy-engine/overview.md) - Policy engine features

docs/features/image-annotation/overview.md

@@ -0,0 +1,53 @@
+# Image Annotation Overview
+
+The image annotation system in CR-CA provides automated image analysis with geometric primitive extraction, semantic labeling, and query capabilities.
+
+## Key Features
+
+- **Geometric Primitive Extraction**: Automatically detect circles, lines, contours, and other geometric shapes
+- **Semantic Labeling**: Identify and label objects in images using LLM-based analysis
+- **Natural Language Queries**: Query images with natural language questions
+- **Temporal Tracking**: Track entities across video frames using Kalman filters
+- **Batch Processing**: Process multiple images in parallel
+- **Integration**: Seamless integration with CRCAAgent and GeneralAgent
+
+## Quick Start
+
+```python
+from image_annotation import ImageAnnotationEngine
+
+engine = ImageAnnotationEngine()
+result = engine.annotate("path/to/image.png", output="all")
+
+print(f"Found {len(result.annotation_graph.entities)} entities")
+print(result.formal_report)
+```
+
+## Mathematical Foundation
+
+Image annotation uses computer vision algorithms combined with LLM-based semantic understanding. Geometric primitives are detected using:
+
+- **Circle Detection**: Hough circle transform with parameters $(x_c, y_c, r)$
+- **Line Detection**: Hough line transform detecting lines with parameters $(\rho, \theta)$
+- **Contour Detection**: Edge detection followed by contour extraction
+
+Semantic labeling uses LLM-based classification to assign labels $L_i$ to entities $E_i$:
+
+$$P(L_i | E_i, I) = LLM(E_i, I)$$
+
+Where $I$ is the image context.
+
+## Integration
+
+- **[Quickstart](quickstart.md)**: Get started quickly
+- **[Engine](engine.md)**: AnnotationEngine class details
+- **[Geometric Primitives](geometric-primitives.md)**: Primitive extraction
+- **[Semantic Labeling](semantic-labeling.md)**: Semantic labeling system
+- **[Query Capabilities](query-capabilities.md)**: Natural language queries
+- **[Temporal Tracking](temporal-tracking.md)**: Video frame tracking
+- **[Integration](integration.md)**: Integration with agents
+
+## Next Steps
+
+- [Quickstart](quickstart.md) - Get started in minutes
+- [Engine](engine.md) - Learn about the engine

docs/features/image-annotation/quickstart.md

@@ -0,0 +1,73 @@
+# Image Annotation Quickstart
+
+Get started with image annotation in minutes.
+
+## Basic Annotation
+
+```python
+from image_annotation import ImageAnnotationEngine
+
+engine = ImageAnnotationEngine()
+result = engine.annotate("path/to/image.png", output="all")
+
+print(f"Found {len(result.annotation_graph.entities)} entities")
+print(result.formal_report)
+```
+
+## 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 and identify all objects")
+```
+
+## Supported Input Types
+
+```python
+# File path
+result = engine.annotate("image.png")
+
+# URL
+result = engine.annotate("https://example.com/image.png")
+
+# NumPy array
+import cv2
+img = cv2.imread("image.png")
+result = engine.annotate(img)
+
+# PIL Image
+from PIL import Image
+img = Image.open("image.png")
+result = engine.annotate(img)
+
+# Batch processing
+results = engine.annotate(["img1.png", "img2.png", "img3.png"])
+```
+
+## Output Formats
+
+```python
+# Annotated overlay image
+overlay = engine.annotate("image.png", output="overlay")
+cv2.imwrite("annotated.png", overlay)
+
+# JSON data
+json_data = engine.annotate("image.png", output="json")
+
+# Formal report
+report = engine.annotate("image.png", output="report")
+
+# Complete result object
+result = engine.annotate("image.png", output="all")
+```
+
+## Next Steps
+
+- [Engine](engine.md) - Learn about AnnotationEngine
+- [Geometric Primitives](geometric-primitives.md) - Understand primitive extraction

docs/features/policy-engine/doctrine-ledger.md

@@ -0,0 +1,105 @@
+# Doctrine & Ledger System
+
+Doctrine system defines policy objectives and constraints. Ledger tracks state and events.
+
+## Doctrine System
+
+DoctrineV1 provides a structured way to define what an agent should optimize for and what constraints it must respect.
+
+### Mathematical Foundation
+
+Doctrine defines an optimization problem:
+
+$$\min_{\mathbf{u}} \sum_{i=1}^n w_i J_i(\mathbf{u})$$
+
+Subject to:
+
+$$g_j(\mathbf{u}) \leq 0, \quad j = 1, \ldots, m$$
+$$h_k(\mathbf{u}) = 0, \quad k = 1, \ldots, p$$
+
+### Usage
+
+```python
+from schemas.policy import DoctrineV1
+
+doctrine = DoctrineV1(
+    version="1.0.0",
+    objectives=["maximize_efficiency", "minimize_cost"],
+    constraints=["budget_limit", "resource_availability"]
+)
+```
+
+## Ledger System
+
+Ledger provides persistent storage for policy state, enabling rollback and audit trails.
+
+### Mathematical Foundation
+
+Ledger maintains state history:
+
+$$L_t = \{(\tau_i, s_i, a_i, r_i)\}_{i=1}^t$$
+
+Where:
+- $\tau_i$: Timestamp
+- $s_i$: State at time $i$
+- $a_i$: Action taken
+- $r_i$: Result/outcome
+
+### Usage
+
+```python
+from utils.ledger import Ledger
+
+ledger = Ledger(doctrine=doctrine)
+ledger.record(state=current_state, action=taken_action)
+```
+
+## Rollback Mechanisms
+
+Rollback enables reverting to previous states.
+
+### Mathematical Foundation
+
+Rollback maintains state history:
+
+$$H_t = \{(\tau_i, s_i)\}_{i=1}^t$$
+
+Rollback to time $t'$ restores:
+
+$$s_{current} \leftarrow s_{t'}$$
+
+### Usage
+
+```python
+from utils.rollback import RollbackManager
+
+rollback = RollbackManager()
+rollback.save_state(current_state)
+rollback.rollback_to(timestamp)
+```
+
+## Doctrine Versioning
+
+Doctrine versioning manages compatibility and migration between doctrine versions.
+
+### Mathematical Foundation
+
+Version compatibility:
+
+$$Compatible(v_1, v_2) = \begin{cases}
+1 & \text{if } v_1 = v_2 \text{ or } v_2 \in CompatibleVersions(v_1) \\
+0 & \text{otherwise}
+\end{cases}$$
+
+### Usage
+
+```python
+from utils.doctrine_versioning import DoctrineRegistry
+
+registry = DoctrineRegistry()
+registry.register(doctrine, compatibility=["1.0.0", "1.1.0"])
+```
+
+## Next Steps
+
+- [MPC & Control](mpc-control.md) - MPC and control systems

docs/features/policy-engine/monitoring.md

@@ -0,0 +1,44 @@
+# Monitoring & Drift Detection
+
+Monitoring systems and drift detection for policy engines.
+
+## Overview
+
+Monitoring systems track policy performance and detect when system behavior deviates from expected patterns.
+
+## Drift Detection
+
+Drift detection identifies when system behavior deviates from expected patterns.
+
+### Mathematical Foundation
+
+Drift is detected when:
+
+$$D(\mathbf{x}_t, \mathbf{x}_{expected}) > \theta$$
+
+Where:
+- $D$: Distance metric
+- $\mathbf{x}_t$: Current state
+- $\mathbf{x}_{expected}$: Expected state
+- $\theta$: Drift threshold
+
+### Distance Metrics
+
+**Euclidean Distance**:
+$$D_{Euclidean} = \|\mathbf{x}_t - \mathbf{x}_{expected}\|_2$$
+
+**Mahalanobis Distance**:
+$$D_{Mahalanobis} = \sqrt{(\mathbf{x}_t - \mathbf{x}_{expected})' \Sigma^{-1} (\mathbf{x}_t - \mathbf{x}_{expected})}$$
+
+### Usage
+
+```python
+from templates.drift_detection import DriftDetector
+
+detector = DriftDetector(threshold=0.1)
+drift_detected = detector.check(current_state, expected_state)
+```
+
+## Next Steps
+
+- [Overview](overview.md) - Return to overview

docs/features/policy-engine/mpc-control.md

@@ -0,0 +1,89 @@
+# MPC & Control Systems
+
+Model Predictive Control and policy execution systems.
+
+## Model Predictive Control (MPC)
+
+MPC solves optimization problems over a prediction horizon to determine optimal control actions.
+
+### Mathematical Foundation
+
+MPC 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$$
+
+### Stage Cost
+
+$$\ell(\mathbf{x}, \mathbf{u}) = \|\mathbf{x} - \mathbf{x}_{ref}\|_Q^2 + \|\mathbf{u} - \mathbf{u}_{ref}\|_R^2$$
+
+### Usage
+
+```python
+from templates.mpc_planner import MPCPlanner
+
+planner = MPCPlanner(horizon=10)
+optimal_controls = planner.solve(current_state, reference_state)
+```
+
+## Policy Loop
+
+Policy loop executes policy decisions in a temporal loop.
+
+### Mathematical Foundation
+
+Policy loop implements:
+
+$$\pi_t = \arg\max_{\pi} E\left[\sum_{k=0}^H \gamma^k r_{t+k} | s_t, \pi\right]$$
+
+Where:
+- $\pi_t$: Policy at time $t$
+- $r_{t+k}$: Reward at time $t+k$
+- $\gamma$: Discount factor
+- $H$: Horizon
+
+### Usage
+
+```python
+from templates.policy_loop import PolicyLoopMixin
+
+class PolicyAgent(BaseAgent, PolicyLoopMixin):
+    def __init__(self):
+        super().__init__()
+```
+
+## Sensors & Actuators
+
+Sensors observe system state, actuators execute actions.
+
+### Mathematical Foundation
+
+**Sensors** observe state:
+
+$$o_t = h(s_t, \nu_t)$$
+
+Where:
+- $o_t$: Observation
+- $s_t$: True state
+- $\nu_t$: Observation noise
+
+**Actuators** execute actions:
+
+$$a_t = \pi(o_t)$$
+
+Where $\pi$ is the policy.
+
+### Usage
+
+```python
+observation = sensor.observe()
+actuator.execute(action)
+```
+
+## Next Steps
+
+- [Monitoring](monitoring.md) - Monitoring and drift detection

docs/features/policy-engine/overview.md

@@ -0,0 +1,46 @@
+# Policy Engine Overview
+
+The policy engine system provides autonomous system control using Model Predictive Control (MPC) with policy doctrines, ledgers, and rollback mechanisms.
+
+## Overview
+
+Policy engine enables agents to operate with defined policies, track state through ledgers, and rollback changes when needed.
+
+## Key Features
+
+- **Doctrine System**: Define policy objectives and constraints
+- **Ledger**: Track state and events
+- **Rollback**: Rollback mechanisms for state recovery
+- **MPC**: Model Predictive Control optimization
+- **Drift Detection**: Detect policy drift
+- **Sensors & Actuators**: Interface with external systems
+
+## Mathematical Foundation
+
+Policy engine implements 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$$
+
+Where:
+- $H$: Prediction horizon
+- $\ell$: Stage cost
+- $V$: Terminal cost
+- $f$: System dynamics
+- $\mathbf{g}$: Constraints
+
+## Documentation
+
+- **[Doctrine](doctrine.md)**: Doctrine system (DoctrineV1)
+- **[Ledger](ledger.md)**: Ledger for state tracking
+- **[MPC](mpc.md)**: Model Predictive Control
+- **[Drift Detection](drift-detection.md)**: Drift detection
+
+## Next Steps
+
+- [Doctrine](doctrine.md) - Doctrine system
+- [Ledger](ledger.md) - State tracking

docs/getting-started/configuration.md

@@ -0,0 +1,225 @@
+# Configuration
+
+Configure CR-CA for your specific use case. This guide covers environment setup, agent configuration, and advanced settings.
+
+## Environment Configuration
+
+### Required Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# LLM Configuration
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Model selection (optional, defaults to gpt-4o-mini)
+OPENAI_MODEL=gpt-4o-mini
+```
+
+### Optional Environment Variables
+
+```bash
+# CRCA-Q Trading
+KRAKEN_API_KEY=your_kraken_key
+KRAKEN_API_SECRET=your_kraken_secret
+
+# Alternative Data Sources
+TWITTER_BEARER_TOKEN=your_twitter_token
+NEWSAPI_KEY=your_newsapi_key
+ETHERSCAN_API_KEY=your_etherscan_key
+THEGRAPH_API_KEY=your_thegraph_key
+
+# MCP Servers
+MCP_SERVER_URL=http://localhost:8000
+MCP_API_KEY=your_mcp_api_key
+```
+
+## Agent Configuration
+
+### Basic Configuration
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="my-agent",
+    max_loops=5,
+    temperature=0.7
+)
+```
+
+### Advanced Configuration
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="advanced-agent",
+    
+    # LLM Settings
+    max_loops=10,
+    temperature=0.7,
+    max_tokens=2000,
+    
+    # Causal Reasoning Settings
+    enable_automatic_extraction=True,
+    causal_graph_threshold=0.3,
+    
+    # Simulation Settings
+    simulation_steps=100,
+    simulation_dt=0.01,
+    
+    # Optimization Settings
+    optimization_method="gradient",
+    optimization_max_iter=1000,
+    
+    # Tools
+    use_crca_tools=True,
+    use_image_annotation=False
+)
+```
+
+## Configuration Parameters
+
+### LLM Parameters
+
+- `model_name`: LLM model to use (e.g., "gpt-4o-mini", "gpt-4")
+- `max_loops`: Maximum number of reasoning loops
+- `temperature`: Sampling temperature (0.0-2.0)
+- `max_tokens`: Maximum tokens per response
+
+### Causal Reasoning Parameters
+
+- `enable_automatic_extraction`: Enable automatic variable extraction
+- `causal_graph_threshold`: Minimum strength for causal relationships
+- `enable_counterfactuals`: Enable counterfactual generation
+- `counterfactual_samples`: Number of counterfactual scenarios
+
+### Simulation Parameters
+
+- `simulation_steps`: Number of simulation steps
+- `simulation_dt`: Time step size
+- `simulation_method`: Simulation method ("euler", "rk4")
+
+### Optimization Parameters
+
+- `optimization_method`: Optimization method ("gradient", "bellman")
+- `optimization_max_iter`: Maximum optimization iterations
+- `optimization_tolerance`: Convergence tolerance
+
+## Mode Configuration
+
+### LLM Mode (Default)
+
+Uses LLM for causal reasoning and analysis:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    mode="llm"  # Default
+)
+```
+
+### Deterministic Mode
+
+Uses mathematical simulation without LLM:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    mode="deterministic"
+)
+```
+
+## Policy Engine Configuration
+
+If using the policy engine:
+
+```python
+from schemas.policy import DoctrineV1
+from utils.ledger import Ledger
+
+# Create doctrine
+doctrine = DoctrineV1(
+    version="1.0.0",
+    objectives=["maximize_efficiency", "minimize_cost"],
+    constraints=["budget_limit", "resource_availability"]
+)
+
+# Initialize ledger
+ledger = Ledger(doctrine=doctrine)
+
+# Use with agent
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    policy_ledger=ledger
+)
+```
+
+## Image Annotation Configuration
+
+Enable image annotation:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    use_image_annotation=True,
+    image_annotation_config={
+        "gpt_model": "gpt-4o-mini",
+        "enable_temporal_tracking": False,
+        "cache_enabled": True
+    }
+)
+```
+
+## Logging Configuration
+
+Configure logging:
+
+```python
+from loguru import logger
+
+# Configure loguru
+logger.add(
+    "crca.log",
+    rotation="10 MB",
+    retention="7 days",
+    level="INFO"
+)
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    verbose=True  # Enable verbose logging
+)
+```
+
+## Performance Configuration
+
+### Caching
+
+Enable caching for faster repeated queries:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    cache_enabled=True,
+    cache_ttl=3600  # Cache TTL in seconds
+)
+```
+
+### Parallel Processing
+
+Enable parallel processing for batch operations:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    parallel_workers=4  # Number of parallel workers
+)
+```
+
+## Next Steps
+
+- [First Agent](first-agent.md) - Create your first configured agent
+- [Core Modules](../core/crcagent/overview.md) - Learn about core functionality
+- [Advanced Features](../features/causal-reasoning/overview.md) - Explore advanced features