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

docs/api/branches/crca-sd.md

@@ -0,0 +1,37 @@
+# CRCA-SD API
+
+API reference for CRCA-SD socioeconomic dynamics.
+
+## Classes
+
+### StateVector
+
+Socioeconomic state vector.
+
+```python
+class StateVector:
+    P: float  # Population
+    L: float  # Labor
+    U: float  # Unemployment
+    # ... 15 variables total
+```
+
+### DynamicsModel
+
+System dynamics model.
+
+```python
+class DynamicsModel:
+    def step(self, x_t: StateVector, u_t: ControlVector) -> StateVector:
+        """Step forward one time period."""
+```
+
+## Mathematical Foundation
+
+Dynamics follow:
+
+$$\mathbf{x}_{t+1} = f(\mathbf{x}_t, \mathbf{u}_t, \mathbf{w}_t)$$
+
+## Next Steps
+
+- [CRCA-CG](crca-cg.md) - Corporate governance API

docs/api/branches/general-agent.md

@@ -0,0 +1,24 @@
+# General Agent API
+
+API reference for General Agent.
+
+## Classes
+
+### GeneralAgent
+
+General-purpose agent.
+
+```python
+class GeneralAgent(BaseSpecializedAgent):
+    def __init__(
+        self,
+        model_name: str,
+        enable_multimodal: bool = False,
+        personality: Optional[Personality] = None
+    ):
+        """Initialize general agent."""
+```
+
+## Next Steps
+
+- [Image Annotation API](../image-annotation/overview.md) - Image annotation API

docs/api/branches/overview.md

@@ -0,0 +1,19 @@
+# Branches API Reference
+
+API reference for specialized branches.
+
+## Overview
+
+Branches API provides documentation for CRCA-Q, CRCA-SD, CRCA-CG, and General Agent.
+
+## Branches
+
+- **[CRCA-Q](crca-q.md)**: Quantitative trading API
+- **[CRCA-SD](crca-sd.md)**: Socioeconomic dynamics API
+- **[CRCA-CG](crca-cg.md)**: Corporate governance API
+- **[General Agent](general-agent.md)**: General agent API
+
+## Next Steps
+
+- [CRCA-Q](crca-q.md) - Trading API
+- [CRCA-SD](crca-sd.md) - Socioeconomic dynamics API

docs/api/crca/agent-methods.md

@@ -0,0 +1,62 @@
+# CRCAAgent Class & Core Methods
+
+Main causal reasoning agent class and core methods.
+
+## Class Definition
+
+```python
+class CRCAAgent(Agent):
+    """Causal Reasoning with Counterfactual Analysis Agent."""
+```
+
+## Initialization
+
+```python
+CRCAAgent(
+    model_name: str = "gpt-4o-mini",
+    agent_name: str = "cr-ca-lite-agent",
+    max_loops: Optional[Union[int, str]] = 3,
+    variables: Optional[List[str]] = None,
+    causal_edges: Optional[List[Tuple[str, str]] = None,
+    **kwargs
+)
+```
+
+## Core Methods
+
+### run()
+
+Execute a causal reasoning task.
+
+```python
+def run(self, task: str) -> str:
+    """Execute causal reasoning task."""
+```
+
+### add_causal_relationship()
+
+Add a causal relationship to the graph.
+
+```python
+def add_causal_relationship(
+    self,
+    parent: str,
+    child: str,
+    strength: float = 0.0
+) -> None:
+    """Add causal relationship."""
+```
+
+## Mathematical Foundation
+
+The agent implements operations on SCMs:
+
+$$V_i = f_i(Pa(V_i), U_i)$$
+
+Methods implement:
+- **run**: $Result = f(Task, SCM)$
+- **add_causal_relationship**: $E \leftarrow E \cup \{(X, Y)\}$
+
+## Next Steps
+
+- [Operations](operations.md) - Advanced operations

docs/api/crca/operations.md

@@ -0,0 +1,79 @@
+# CRCAAgent Operations
+
+Advanced operations including extraction, simulation, and counterfactuals.
+
+## Variable Extraction
+
+Methods for automatic variable extraction from natural language.
+
+### Mathematical Foundation
+
+Extraction identifies:
+
+$$V = \{V_1, \ldots, V_n\} = Extract(T)$$
+
+Where $T$ is the natural language task.
+
+### Methods
+
+- `extract_variables()`: Extract variables from text
+- `extract_relationships()`: Extract causal relationships
+
+## Deterministic Simulation
+
+Methods for deterministic causal simulation.
+
+### Mathematical Foundation
+
+Simulation uses:
+
+$$V_i(t+\Delta t) = V_i(t) + f_i(Pa(V_i(t)), U_i) \cdot \Delta t$$
+
+For differential equation systems.
+
+### Methods
+
+- `simulate()`: Single-step simulation
+- `simulate_time_series()`: Multi-step simulation
+
+### Usage
+
+```python
+result = agent.simulate(
+    variables={"education": 16, "experience": 5},
+    target="income"
+)
+```
+
+## Counterfactual Generation
+
+Methods for generating counterfactual scenarios.
+
+### Mathematical Foundation
+
+Counterfactuals compute:
+
+$$P(Y_{x'} | X=x, Y=y)$$
+
+Using:
+1. **Abduction**: $U_Y = f^{-1}(X=x, Z=z, Y=y)$
+2. **Action**: Set $X = x'$
+3. **Prediction**: $Y_{x'} = f(X=x', Z=z, U_Y)$
+
+### Methods
+
+- `generate_counterfactuals()`: Generate counterfactual scenarios
+- `evaluate_counterfactual()`: Evaluate specific counterfactual
+
+### Usage
+
+```python
+counterfactuals = agent.generate_counterfactuals(
+    intervention={"education": "college"},
+    outcome="income"
+)
+```
+
+## Next Steps
+
+- [Utils API](../utils/overview.md) - Utils API

docs/api/crca/overview.md

@@ -0,0 +1,32 @@
+# CRCAAgent API Reference
+
+API reference for CRCAAgent and related classes.
+
+## Overview
+
+This section provides API documentation for CRCAAgent. Documentation is hybrid: auto-generated where docstrings exist, manually created where they are missing.
+
+## Core Classes
+
+- **[CRCAAgent](agent.md)**: Main agent class
+- **[Methods](methods.md)**: Core methods
+- **[Extraction](extraction.md)**: Variable extraction methods
+- **[Simulation](simulation.md)**: Simulation methods
+- **[Counterfactuals](counterfactuals.md)**: Counterfactual methods
+
+## Mathematical Foundation
+
+All methods implement operations on Structural Causal Models:
+
+$$(U, V, F)$$
+
+Where operations include:
+- Variable extraction: $V = Extract(T)$
+- Graph construction: $G = Build(V, E)$
+- Causal inference: $E[Y | do(X=x)]$
+- Counterfactuals: $P(Y_{x'} | X=x, Y=y)$
+
+## Next Steps
+
+- [CRCAAgent](agent.md) - Agent class
+- [Methods](methods.md) - Core methods

docs/api/image-annotation/engine.md

@@ -0,0 +1,52 @@
+# AnnotationEngine API
+
+API reference for AnnotationEngine class.
+
+## Class Definition
+
+```python
+class ImageAnnotationEngine:
+    """Image annotation engine."""
+```
+
+## Methods
+
+### annotate()
+
+Annotate image(s).
+
+```python
+def annotate(
+    self,
+    input: Union[str, np.ndarray, Image.Image, List, Path],
+    frame_id: Optional[int] = None,
+    output: Optional[str] = None
+) -> Union[AnnotationResult, np.ndarray, Dict[str, Any], str, List]:
+    """Annotate image(s)."""
+```
+
+### query()
+
+Query image with natural language.
+
+```python
+def query(
+    self,
+    input: Union[str, np.ndarray, Image.Image, Path],
+    query: str,
+    frame_id: Optional[int] = None
+) -> Dict[str, Any]:
+    """Query image."""
+```
+
+## Mathematical Foundation
+
+Annotation uses:
+
+$$P(L_i | E_i, I) = LLM(E_i, I)$$
+
+Where $L_i$ is label, $E_i$ is entity, and $I$ is image.
+
+## Next Steps
+
+- [Schemas](schemas.md) - Annotation schemas

docs/api/image-annotation/overview.md

@@ -0,0 +1,17 @@
+# Image Annotation API Reference
+
+API reference for image annotation system.
+
+## Overview
+
+Image annotation API provides documentation for AnnotationEngine and related classes.
+
+## Classes
+
+- **[Engine](engine.md)**: AnnotationEngine class
+- **[Schemas](schemas.md)**: Annotation data schemas
+
+## Next Steps
+
+- [Engine](engine.md) - AnnotationEngine API
+- [Schemas](schemas.md) - Annotation schemas

docs/api/schemas/annotation.md

@@ -0,0 +1,34 @@
+# Annotation Schemas
+
+Schemas for image annotation system.
+
+## Classes
+
+### AnnotationResult
+
+Complete annotation result.
+
+```python
+class AnnotationResult(BaseModel):
+    annotation_graph: AnnotationGraph
+    overlay_image: Optional[bytes]
+    formal_report: str
+    json_output: Dict[str, Any]
+    processing_time: float
+```
+
+### PrimitiveEntity
+
+Geometric primitive entity.
+
+```python
+class PrimitiveEntity(BaseModel):
+    entity_id: str
+    primitive_type: str
+    pixel_coords: List[Tuple[int, int]]
+    metadata: Dict[str, Any]
+```
+
+## Next Steps
+
+- [Conversation](conversation.md) - Conversation schemas

docs/api/schemas/core-schemas.md

@@ -0,0 +1,82 @@
+# Core Schemas API
+
+API for core data schemas grouped together.
+
+## Conversation Schemas
+
+Schemas for conversation management.
+
+### Classes
+
+- `ConversationState`: Current conversation state
+- `Message`: Individual message in conversation
+- `Context`: Conversation context
+
+### Usage
+
+```python
+from schemas.conversation import ConversationState, Message
+
+state = ConversationState(
+    messages=[Message(role="user", content="Hello")]
+)
+```
+
+## Hybrid Agent Schemas
+
+Schemas for hybrid agent architecture.
+
+### Classes
+
+- `HybridAgentState`: Hybrid agent state
+- `ReasoningStep`: Individual reasoning step
+- `ConsistencyCheck`: Consistency check result
+
+### Usage
+
+```python
+from schemas.hybrid import HybridAgentState
+
+state = HybridAgentState(
+    reasoning_steps=[],
+    consistency_checks=[]
+)
+```
+
+## Reasoning Schemas
+
+Schemas for causal reasoning operations and results.
+
+### Classes
+
+- `CausalInferenceResult`: Causal inference result
+- `CounterfactualScenario`: Counterfactual scenario
+- `CausalEffect`: Causal effect estimate
+
+### Mathematical Foundation
+
+Causal effect:
+
+$$\tau = E[Y | do(X=1)] - E[Y | do(X=0)]$$
+
+With confidence interval:
+
+$$CI_{1-\alpha} = [\tau - z_{\alpha/2} \cdot SE, \tau + z_{\alpha/2} \cdot SE]$$
+
+### Usage
+
+```python
+from schemas.reasoning import CausalInferenceResult
+
+result = CausalInferenceResult(
+    treatment="X",
+    outcome="Y",
+    effect=0.5,
+    confidence=0.9
+)
+```
+
+## Next Steps
+
+- [Annotation](annotation.md) - Image annotation schemas
+- [Policy](policy.md) - Policy engine schemas

docs/api/schemas/overview.md

@@ -0,0 +1,32 @@
+# Schemas API Reference
+
+API reference for data schemas.
+
+## Overview
+
+Schemas define Pydantic models for type safety and validation.
+
+## Modules
+
+- **[Annotation](annotation.md)**: Image annotation schemas
+- **[Conversation](conversation.md)**: Conversation schemas
+- **[Hybrid](hybrid.md)**: Hybrid agent schemas
+- **[Reasoning](reasoning.md)**: Reasoning schemas
+- **[Policy](policy.md)**: Policy engine schemas
+
+## Usage
+
+```python
+from schemas.annotation import AnnotationResult
+
+result = AnnotationResult(
+    entities=[],
+    labels=[],
+    relations=[]
+)
+```
+
+## Next Steps
+
+- [Annotation](annotation.md) - Annotation schemas
+- [Policy](policy.md) - Policy schemas

docs/api/schemas/policy.md

@@ -0,0 +1,30 @@
+# Policy Engine Schemas
+
+Schemas for policy engine system.
+
+## Classes
+
+### DoctrineV1
+
+Policy doctrine definition.
+
+```python
+class DoctrineV1(BaseModel):
+    version: str
+    objectives: List[str]
+    constraints: List[str]
+```
+
+## Mathematical Foundation
+
+Doctrine defines optimization problem:
+
+$$\min_{\mathbf{u}} \sum_{i} w_i J_i(\mathbf{u})$$
+
+Subject to:
+
+$$g_j(\mathbf{u}) \leq 0, \quad j = 1, \ldots, m$$
+
+## Next Steps
+
+- [Branches API](../branches/overview.md) - Branches API

docs/api/utils/conversation.md

@@ -0,0 +1,22 @@
+# Conversation API
+
+API for conversation management.
+
+## Classes
+
+### ConversationManager
+
+Manages conversation state and history.
+
+```python
+class ConversationManager:
+    def add_message(self, role: str, content: str) -> None:
+        """Add message to conversation."""
+    
+    def get_history(self) -> List[Message]:
+        """Get conversation history."""
+```
+
+## Next Steps
+
+- [Graph Reasoner](graph-reasoner.md) - Graph reasoner API

docs/api/utils/graph-reasoner.md

@@ -0,0 +1,32 @@
+# Graph Reasoner API
+
+API for graph reasoning utilities.
+
+## Classes
+
+### GraphReasoner
+
+Provides utilities for reasoning about causal graphs.
+
+```python
+class GraphReasoner:
+    def find_paths(self, source: str, target: str) -> List[List[str]]:
+        """Find all paths from source to target."""
+    
+    def identify_confounders(self, X: str, Y: str) -> List[str]:
+        """Identify confounders for X -> Y."""
+```
+
+## Mathematical Foundation
+
+Path finding uses graph algorithms:
+
+$$Paths(X, Y) = \{p : X \to^* Y\}$$
+
+Confounder identification:
+
+$$Z \in Confounders(X, Y) \iff Z \to X \text{ and } Z \to Y$$
+
+## Next Steps
+
+- [Batch Processor](batch-processor.md) - Batch processor API

docs/api/utils/overview.md

@@ -0,0 +1,21 @@
+# Utils API Reference
+
+API reference for utility modules.
+
+## Overview
+
+Utils API provides documentation for utility functions and classes. Most documentation is manual due to minimal docstrings in source code.
+
+## Modules
+
+- **[Formatter](formatter.md)**: Formatter utilities
+- **[Router](router.md)**: Router functionality
+- **[Conversation](conversation.md)**: Conversation management
+- **[Graph Reasoner](graph-reasoner.md)**: Graph reasoning
+- **[Batch Processor](batch-processor.md)**: Batch processing
+- **[Rate Limiter](rate-limiter.md)**: Rate limiting
+
+## Next Steps
+
+- [Formatter](formatter.md) - Formatter API
+- [Router](router.md) - Router API

docs/api/utils/router.md

@@ -0,0 +1,19 @@
+# Router API
+
+API for router functionality.
+
+## Classes
+
+### Router
+
+Routes requests to appropriate agents.
+
+```python
+class Router:
+    def select_agent(self, task: str) -> Agent:
+        """Select appropriate agent for task."""
+```
+
+## Next Steps
+
+- [Conversation](conversation.md) - Conversation API

docs/api/utils/utilities.md

@@ -0,0 +1,97 @@
+# Utility Functions API
+
+API for smaller utility modules grouped together.
+
+## Formatter
+
+Text formatting and output utilities.
+
+### 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 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.
+
+### 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.
+
+### Usage
+
+```python
+from utils.agent_discovery import AgentDiscovery
+
+discovery = AgentDiscovery()
+agents = discovery.discover_agents()
+```
+
+## Tool Discovery
+
+Tool discovery and registration.
+
+### 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:
+
+$$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) - Router API
+- [Conversation](conversation.md) - Conversation API