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

docs/features/causal-reasoning/advanced-topics.md

@@ -0,0 +1,101 @@
+# Advanced Causal Reasoning Topics
+
+Advanced topics in causal reasoning including discovery, interventions, and confounders.
+
+## Causal Discovery
+
+Causal discovery learns causal structure from observational data.
+
+### Mathematical Foundation
+
+Causal discovery uses various methods:
+
+**Constraint-Based Methods**: Test conditional independencies:
+
+$$X \perp Y | Z \implies \text{No direct edge } X \to Y$$
+
+**Score-Based Methods**: Search for graph $G$ that maximizes:
+
+$$Score(G, D) = \sum_{i=1}^n \log P(V_i | Pa(V_i), \theta_i) - \text{Complexity}(G)$$
+
+**Functional Causal Models**: Assume functional relationships:
+
+$$Y = f(X, U_Y)$$
+
+Where $U_Y$ is independent of $X$.
+
+### Usage
+
+Causal discovery is integrated into automatic extraction:
+
+```python
+agent = CRCAAgent(enable_automatic_extraction=True)
+result = agent.run("Analyze relationships in data")
+```
+
+## Causal Interventions
+
+Interventions represent actions that change the value of a variable.
+
+### Mathematical Foundation
+
+**Intervention vs. Observation**:
+
+**Observation**: $P(Y | X=x)$ - Conditional probability
+
+**Intervention**: $P(Y | do(X=x))$ - Causal effect
+
+The key difference:
+
+$$P(Y | X=x) = \sum_z P(Y | X=x, Z=z) P(Z=z | X=x)$$
+$$P(Y | do(X=x)) = \sum_z P(Y | X=x, Z=z) P(Z=z)$$
+
+**Average Causal Effect (ACE)**:
+
+$$ACE = E[Y | do(X=1)] - E[Y | do(X=0)]$$
+
+### Usage
+
+```python
+effect = agent.compute_causal_effect(
+    treatment="X",
+    outcome="Y",
+    value_treated=1,
+    value_control=0
+)
+```
+
+## Confounder Identification
+
+Confounders are variables that cause both treatment and outcome.
+
+### Mathematical Foundation
+
+**Confounder Definition**: $Z$ is a confounder for $X \to Y$ if:
+
+$$Z \to X \text{ and } Z \to Y$$
+
+This creates a backdoor path: $X \leftarrow Z \to Y$.
+
+**Backdoor Criterion**: To identify $E[Y | do(X=x)]$, we need to block all backdoor paths. A set $Z$ satisfies the backdoor criterion if:
+
+1. $Z$ blocks all backdoor paths from $X$ to $Y$
+2. $Z$ contains no descendants of $X$
+
+Then:
+
+$$E[Y | do(X=x)] = \sum_z E[Y | X=x, Z=z] P(Z=z)$$
+
+### Usage
+
+```python
+from utils.graph_reasoner import GraphReasoner
+
+reasoner = GraphReasoner(graph)
+confounders = reasoner.identify_confounders("X", "Y")
+adjustment_set = reasoner.find_adjustment_set("X", "Y")
+```
+
+## Next Steps
+
+- [Overview](overview.md) - Return to overview

docs/features/causal-reasoning/counterfactuals.md

@@ -0,0 +1,43 @@
+# Counterfactual Reasoning
+
+Counterfactual reasoning answers "what-if" questions about alternative scenarios.
+
+## Overview
+
+Counterfactuals enable reasoning about what would have happened under different conditions, given what actually occurred.
+
+## Mathematical Foundation
+
+### Counterfactual Query
+
+A counterfactual query is:
+
+$$P(Y_{x'} | X=x, Y=y)$$
+
+Where:
+- $Y_{x'}$: Potential outcome under intervention $do(X=x')$
+- $X=x, Y=y$: Observed values
+
+### Three-Step Process
+
+1. **Abduction**: Infer exogenous variables from observations
+   $$U_Y = f^{-1}(X=x, Z=z, Y=y)$$
+
+2. **Action**: Set $X = x'$
+
+3. **Prediction**: Compute $Y$ using structural equations
+   $$Y_{x'} = f(X=x', Z=z, U_Y)$$
+
+## Usage
+
+```python
+counterfactuals = agent.generate_counterfactuals(
+    intervention={"education": "college"},
+    outcome="income",
+    observed={"education": "high_school", "income": 30000}
+)
+```
+
+## Next Steps
+
+- [Causal Discovery](causal-discovery.md) - Learning causal structure

docs/features/causal-reasoning/do-calculus.md

@@ -0,0 +1,50 @@
+# Do-Calculus
+
+Do-calculus provides rules for identifying causal effects from observational data.
+
+## Overview
+
+Do-calculus, developed by Judea Pearl, provides three rules for manipulating probability expressions involving the do-operator.
+
+## Mathematical Foundation
+
+### Do-Operator
+
+The do-operator $do(X=x)$ represents intervention, setting $X$ to value $x$:
+
+$$P(Y | do(X=x)) \neq P(Y | X=x)$$
+
+The key difference: observation vs. intervention.
+
+### Do-Calculus Rules
+
+**Rule 1** (Insertion/deletion of observations):
+$$P(Y | do(X), Z, W) = P(Y | do(X), W)$$
+
+If $Z$ is irrelevant to $Y$ given $X$ and $W$ in the graph.
+
+**Rule 2** (Action/observation exchange):
+$$P(Y | do(X), do(Z), W) = P(Y | do(X), Z, W)$$
+
+If $Z$ is irrelevant to $Y$ given $X$ and $W$ in the modified graph.
+
+**Rule 3** (Insertion/deletion of actions):
+$$P(Y | do(X), do(Z), W) = P(Y | do(X), W)$$
+
+If $Z$ is irrelevant to $Y$ given $X$ and $W$ in the modified graph.
+
+## Causal Effect Identification
+
+Using do-calculus, we can identify:
+
+$$E[Y | do(X=x)] = \sum_{z} E[Y | X=x, Z=z] P(Z=z)$$
+
+Where $Z$ is a valid adjustment set.
+
+## Usage
+
+CR-CA automatically applies do-calculus rules when computing causal effects.
+
+## Next Steps
+
+- [Counterfactuals](counterfactuals.md) - Counterfactual reasoning

docs/features/causal-reasoning/overview.md

@@ -0,0 +1,47 @@
+# Causal Reasoning Overview
+
+Causal reasoning framework based on Judea Pearl's Structural Causal Models.
+
+## Overview
+
+Causal reasoning enables understanding of cause-and-effect relationships, going beyond correlation to identify true causal mechanisms.
+
+## Key Concepts
+
+- **Structural Causal Models (SCMs)**: Mathematical framework for causality
+- **Do-Calculus**: Rules for causal inference
+- **Counterfactuals**: "What-if" reasoning
+- **Causal Discovery**: Learning causal structure from data
+- **Interventions**: Reasoning about actions
+
+## Mathematical Foundation
+
+### Structural Causal Models
+
+An SCM is a triple $(U, V, F)$ where:
+- $U$: Exogenous variables
+- $V$: Endogenous variables
+- $F$: Structural equations
+
+Each variable has:
+
+$$V_i = f_i(Pa(V_i), U_i)$$
+
+Where $Pa(V_i)$ are parents of $V_i$.
+
+### Do-Calculus
+
+The do-operator represents intervention:
+
+$$P(Y | do(X=x)) = \sum_{z} P(Y | X=x, Z=z) P(Z=z)$$
+
+## Documentation
+
+- **[Structural Models](structural-models.md)**: SCMs
+- **[Do-Calculus](do-calculus.md)**: Do-calculus implementation
+- **[Counterfactuals](counterfactuals.md)**: Counterfactual reasoning
+
+## Next Steps
+
+- [Structural Models](structural-models.md) - SCMs
+- [Do-Calculus](do-calculus.md) - Do-calculus

docs/features/causal-reasoning/structural-models.md

@@ -0,0 +1,52 @@
+# Structural Causal Models (SCMs)
+
+Structural Causal Models provide the mathematical foundation for causal reasoning.
+
+## Overview
+
+SCMs represent causal relationships through structural equations that define how variables depend on their causes.
+
+## Mathematical Foundation
+
+### Definition
+
+An SCM is a triple:
+
+$$(U, V, F)$$
+
+Where:
+- $U = \{U_1, \ldots, U_n\}$: Exogenous (unobserved) variables
+- $V = \{V_1, \ldots, V_m\}$: Endogenous (observed) variables
+- $F = \{f_1, \ldots, f_m\}$: Structural equations
+
+### Structural Equations
+
+Each endogenous variable has a structural equation:
+
+$$V_i = f_i(Pa(V_i), U_i)$$
+
+Where $Pa(V_i)$ are the parents of $V_i$ in the causal graph.
+
+### Example
+
+For education and income:
+
+$$Education = f_E(U_E)$$
+$$Experience = f_{Exp}(Education, U_{Exp})$$
+$$Income = f_I(Education, Experience, U_I)$$
+
+## Usage
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(model_name="gpt-4o-mini")
+
+# Build SCM
+agent.add_causal_relationship("education", "income", strength=0.6)
+agent.add_causal_relationship("experience", "income", strength=0.4)
+```
+
+## Next Steps
+
+- [Do-Calculus](do-calculus.md) - Do-calculus implementation

docs/features/hybrid-agent/advanced-components.md

@@ -0,0 +1,55 @@
+# Hybrid Agent Advanced Components
+
+Advanced components of the hybrid agent architecture.
+
+## Explanation Generator
+
+Generates human-readable explanations for reasoning steps.
+
+The explanation generator translates reasoning steps into natural language explanations.
+
+## Few-Shot Learner
+
+Enables learning from few examples.
+
+### Mathematical Foundation
+
+Few-shot learning uses:
+
+$$P(y | x, D_{few}) = \int P(y | x, \theta) P(\theta | D_{few}) d\theta$$
+
+Where $D_{few}$ is the few-shot dataset.
+
+## Graph Compressor
+
+Reduces causal graph complexity while preserving essential relationships.
+
+### Mathematical Foundation
+
+Graph compression preserves:
+
+$$\text{Preserve}(G, G') = \frac{|Paths(G) \cap Paths(G')|}{|Paths(G)|}$$
+
+Where $G'$ is the compressed graph.
+
+## Language Compiler
+
+Translates natural language into structured representations.
+
+The language compiler converts natural language tasks into structured formats suitable for causal reasoning.
+
+## Reasoning Tracker
+
+Monitors and logs reasoning steps.
+
+The reasoning tracker maintains a log of all reasoning steps for analysis and debugging.
+
+## Text Corrector
+
+Fixes errors in generated text.
+
+The text corrector identifies and corrects errors in agent-generated text.
+
+## Next Steps
+
+- [Overview](overview.md) - Return to overview

docs/features/hybrid-agent/core-components.md

@@ -0,0 +1,64 @@
+# Hybrid Agent Core Components
+
+Core components of the hybrid agent architecture.
+
+## Consistency Engine
+
+Ensures logical consistency across reasoning steps.
+
+### 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.
+
+## Conversation Manager
+
+Manages multi-turn dialogue and context management.
+
+### Mathematical Foundation
+
+Conversation state is maintained as:
+
+$$C_t = \{m_1, m_2, \ldots, m_t\}$$
+
+Where $m_i$ are messages. Context is extracted as:
+
+$$Context_t = f(C_t)$$
+
+## Task Decomposer
+
+Decomposes complex tasks into manageable subtasks.
+
+### Mathematical Foundation
+
+Task decomposition:
+
+$$T = \{T_1, T_2, \ldots, T_n\}$$
+
+Where:
+- $T$: Original task
+- $T_i$: Subtasks
+- Dependencies: $T_i \prec T_j$
+
+## Self Verifier
+
+Verifies reasoning steps for correctness.
+
+### Mathematical Foundation
+
+Verification checks:
+
+$$\text{Valid}(S) = \begin{cases}
+1 & \text{if } S \text{ is logically consistent} \\
+0 & \text{otherwise}
+\end{cases}$$
+
+## Next Steps
+
+- [Advanced Components](advanced-components.md) - Advanced components

docs/features/hybrid-agent/overview.md

@@ -0,0 +1,34 @@
+# Hybrid Agent Overview
+
+The hybrid agent architecture combines multiple reasoning components for robust causal analysis.
+
+## Overview
+
+Hybrid agent integrates consistency engine, conversation manager, explanation generator, and other components for enhanced reasoning.
+
+## Key Components
+
+- **Consistency Engine**: Ensures logical consistency
+- **Conversation Manager**: Manages dialogue
+- **Explanation Generator**: Generates explanations
+- **Task Decomposer**: Decomposes complex tasks
+- **Self Verifier**: Verifies reasoning steps
+
+## Mathematical Foundation
+
+Hybrid agent combines 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.
+
+## Documentation
+
+- **[Consistency Engine](consistency-engine.md)**: Consistency mechanisms
+- **[Conversation Manager](conversation-manager.md)**: Dialogue management
+- **[Task Decomposer](task-decomposer.md)**: Task decomposition
+
+## Next Steps
+
+- [Consistency Engine](consistency-engine.md) - Consistency mechanisms
+- [Conversation Manager](conversation-manager.md) - Dialogue management

docs/features/image-annotation/engine.md

@@ -0,0 +1,82 @@
+# AnnotationEngine
+
+The AnnotationEngine class provides the core image annotation functionality.
+
+## Overview
+
+AnnotationEngine processes images to extract geometric primitives, generate semantic labels, and enable natural language queries.
+
+## Initialization
+
+```python
+from image_annotation import ImageAnnotationEngine
+from image_annotation.annotation_engine import AnnotationConfig
+
+# Basic initialization
+engine = ImageAnnotationEngine()
+
+# With custom configuration
+config = AnnotationConfig(
+    gpt_model="gpt-4o-mini",
+    enable_temporal_tracking=True,
+    auto_detect_type=True,
+    output_format="all"
+)
+engine = ImageAnnotationEngine(config=config)
+```
+
+## Main Methods
+
+### annotate()
+
+Annotate image(s) with full automation:
+
+```python
+result = engine.annotate(
+    input="image.png",
+    frame_id=None,
+    output="all"
+)
+```
+
+Returns `AnnotationResult` object with:
+- `annotation_graph`: Graph of entities, labels, and relations
+- `overlay_image`: Annotated image overlay
+- `formal_report`: Textual report
+- `json_output`: JSON representation
+
+### query()
+
+Query an image with natural language:
+
+```python
+result = engine.query(
+    input="image.png",
+    query="find all circles",
+    frame_id=None
+)
+```
+
+Returns dictionary with:
+- `answer`: Natural language answer
+- `entities`: List of relevant entities
+- `measurements`: Dict of measurements
+- `graph`: AnnotationGraph if needed
+
+## Mathematical Foundation
+
+The annotation process involves:
+
+1. **Geometric Detection**: Extract primitives using computer vision
+2. **Semantic Classification**: Assign labels using LLM
+
+For entity $E_i$ in image $I$:
+
+$$P(L_i | E_i, I) = \text{LLM}(E_i, I)$$
+
+Where $L_i$ is the semantic label.
+
+## Next Steps
+
+- [Geometric Primitives](geometric-primitives.md) - Primitive extraction
+- [Semantic Labeling](semantic-labeling.md) - Labeling system

docs/features/image-annotation/features.md

@@ -0,0 +1,113 @@
+# Image Annotation Features
+
+Comprehensive guide to image annotation features.
+
+## Geometric Primitive Extraction
+
+Extracts geometric primitives from images using computer vision algorithms.
+
+### Mathematical Foundation
+
+**Circle Detection**: Circles are detected using Hough circle transform:
+
+$$(x - x_c)^2 + (y - y_c)^2 = r^2$$
+
+Where $(x_c, y_c)$ is the center and $r$ is the radius.
+
+**Line Detection**: Lines are detected using Hough line transform:
+
+$$\rho = x \cos \theta + y \sin \theta$$
+
+Where $\rho$ is the distance from origin and $\theta$ is the angle.
+
+**Contour Detection**: Contours are extracted using:
+
+$$C = \text{findContours}(\nabla I)$$
+
+Where $\nabla I$ is the image gradient.
+
+### Usage
+
+```python
+result = engine.annotate("image.png", output="all")
+entities = result.annotation_graph.entities
+circles = [e for e in entities if e.primitive_type == "circle"]
+```
+
+## Semantic Labeling
+
+Assigns meaningful labels to detected geometric primitives.
+
+### Mathematical Foundation
+
+For entity $E_i$ with geometric properties $G_i$, the semantic label $L_i$ is:
+
+$$L_i = \arg\max_{l} P(l | E_i, G_i, I)$$
+
+Where $I$ is the image context, and the probability is estimated using LLM:
+
+$$P(l | E_i, G_i, I) \approx \text{LLM}(E_i, G_i, I)$$
+
+### Usage
+
+```python
+labels = result.annotation_graph.labels
+for label in labels:
+    print(f"Entity {label.entity_id}: {label.label}")
+```
+
+## Query Capabilities
+
+Natural language queries about images.
+
+### Query Types
+
+- **Object Detection**: "find all circles", "identify military bases"
+- **Measurement**: "measure distance", "calculate area"
+- **Counting**: "how many objects", "count lines"
+- **Spatial**: "what is near X", "find objects between A and B"
+
+### Mathematical Foundation
+
+Queries are processed by:
+
+1. Parsing the natural language query $Q$
+2. Identifying relevant entities $E_Q \subseteq E$
+3. Computing requested measurements $M_Q$
+4. Generating answer $A = f(Q, E_Q, M_Q)$
+
+### Usage
+
+```python
+result = engine.query("image.png", "find all circles")
+print(result["answer"])
+```
+
+## Temporal Tracking
+
+Tracks entities across video frames using Kalman filters.
+
+### Mathematical Foundation
+
+Temporal tracking uses Kalman filters for state estimation:
+
+**State Model**:
+$$\mathbf{x}_t = \mathbf{F} \mathbf{x}_{t-1} + \mathbf{B} \mathbf{u}_t + \mathbf{w}_t$$
+
+**Observation Model**:
+$$\mathbf{z}_t = \mathbf{H} \mathbf{x}_t + \mathbf{v}_t$$
+
+**Kalman Update**:
+$$\hat{\mathbf{x}}_{t|t} = \hat{\mathbf{x}}_{t|t-1} + \mathbf{K}_t (\mathbf{z}_t - \mathbf{H} \hat{\mathbf{x}}_{t|t-1})$$
+
+### Usage
+
+```python
+engine = ImageAnnotationEngine(enable_temporal_tracking=True)
+for frame_id, image_path in enumerate(frame_paths):
+    result = engine.annotate(image_path, frame_id=frame_id)
+```
+
+## Next Steps
+
+- [Integration](integration.md) - Integration with agents