mmar-carl 0.0.3__py3-none-any.whl

mmar_carl/__init__.py

@@ -0,0 +1,25 @@
+"""
+MAESTRO CARL (Collaborative Agent Reasoning Library)
+
+A library for building chain-of-thought reasoning systems with DAG-based parallel execution.
+"""
+
+from .chain import ChainBuilder, ReasoningChain
+from .executor import DAGExecutor
+from .llm import LLMClient, LLMClientBase
+from .models import Language, PromptTemplate, ReasoningContext, ReasoningResult, StepDescription, StepExecutionResult
+
+__version__ = "0.0.3"
+__all__ = [
+    "Language",
+    "StepDescription",
+    "ReasoningContext",
+    "StepExecutionResult",
+    "ReasoningResult",
+    "PromptTemplate",
+    "ReasoningChain",
+    "ChainBuilder",
+    "DAGExecutor",
+    "LLMClientBase",
+    "LLMClient",
+]

mmar_carl/chain.py

@@ -0,0 +1,344 @@
+"""
+Main chain definition and execution API for CARL.
+
+Provides the primary interface for defining and executing reasoning chains.
+"""
+
+import asyncio
+from typing import Any
+
+from .executor import DAGExecutor
+from .models import PromptTemplate, ReasoningContext, ReasoningResult, StepDescription
+
+
+class ReasoningChain:
+    """
+    Main interface for defining and executing reasoning chains.
+
+    Provides a high-level API that combines chain definition with DAG execution.
+    """
+
+    def __init__(
+        self,
+        steps: list[StepDescription],
+        max_workers: int = 3,
+        prompt_template: PromptTemplate | None = None,
+        enable_progress: bool = False,
+        metadata: dict[str, Any] | None = None,
+    ):
+        self.steps = steps
+        self.max_workers = max_workers
+        self.prompt_template = prompt_template or PromptTemplate()
+        self.enable_progress = enable_progress
+        self.metadata = metadata or {}
+        self._validate_steps()
+        self.executor = DAGExecutor(
+            max_workers=max_workers, prompt_template=self.prompt_template, enable_progress=enable_progress
+        )
+
+    def _validate_steps(self) -> None:
+        if not self.steps:
+            raise ValueError("Reasoning chain must have at least one step")
+        step_numbers = [step.number for step in self.steps]
+
+        # Check for duplicate step numbers
+        if len(step_numbers) != len(set(step_numbers)):
+            duplicates = [num for num in step_numbers if step_numbers.count(num) > 1]
+            raise ValueError(f"Duplicate step numbers found: {duplicates}")
+
+        # Check for missing dependencies
+        for step in self.steps:
+            for dep in step.dependencies:
+                if dep not in step_numbers:
+                    raise ValueError(f"Step {step.number} depends on non-existent step {dep}")
+
+        # Check for cycles (basic validation)
+        self._check_for_cycles()
+
+    def _check_for_cycles(self) -> None:
+        """
+        Basic cycle detection using dependency graph.
+
+        Raises:
+            ValueError: If cycles are detected
+        """
+        visited = set()
+        rec_stack = set()
+
+        def visit(step_num: int) -> bool:
+            if step_num in rec_stack:
+                return True  # Cycle detected
+            if step_num in visited:
+                return False
+
+            visited.add(step_num)
+            rec_stack.add(step_num)
+
+            # Visit dependencies
+            step = next(s for s in self.steps if s.number == step_num)
+            for dep in step.dependencies:
+                if visit(dep):
+                    return True
+
+            rec_stack.remove(step_num)
+            return False
+
+        for step in self.steps:
+            if step.number not in visited:
+                if visit(step.number):
+                    raise ValueError(f"Cycle detected involving step {step.number}")
+
+    async def execute_async(self, context: ReasoningContext) -> ReasoningResult:
+        """
+        Execute the reasoning chain asynchronously.
+
+        Args:
+            context: Reasoning context with input data and LLM client
+
+        Returns:
+            Complete reasoning result
+        """
+        # Add chain metadata to context
+        context.metadata.update({"chain_steps": len(self.steps), "chain_metadata": self.metadata})
+
+        return await self.executor.execute(self.steps, context)
+
+    def execute(self, context: ReasoningContext) -> ReasoningResult:
+        """
+        Execute the reasoning chain synchronously.
+
+        Args:
+            context: Reasoning context with input data and LLM client
+
+        Returns:
+            Complete reasoning result
+        """
+        try:
+            # Check if we're already in an event loop
+            _ = asyncio.get_running_loop()
+        except RuntimeError:
+            # No event loop running, safe to use asyncio.run
+            return asyncio.run(self.execute_async(context))
+        else:
+            # We're in an event loop, create a task and run it
+            import concurrent.futures
+
+            with concurrent.futures.ThreadPoolExecutor() as executor:
+                future = executor.submit(asyncio.run, self.execute_async(context))
+                return future.result()
+
+    def get_execution_plan(self) -> dict[str, Any]:
+        """
+        Get the execution plan showing parallelization opportunities.
+
+        Returns:
+            Dictionary describing the execution plan
+        """
+        # Build dependency levels
+        levels = []
+        remaining_steps = self.steps.copy()
+
+        while remaining_steps:
+            current_level = []
+            for step in remaining_steps[:]:
+                if all(dep not in [s.number for s in remaining_steps] for dep in step.dependencies):
+                    current_level.append(step)
+                    remaining_steps.remove(step)
+
+            if current_level:
+                levels.append(
+                    {
+                        "level": len(levels) + 1,
+                        "steps": [step.number for step in current_level],
+                        "parallelizable": len(current_level) > 1,
+                        "step_titles": [step.title for step in current_level],
+                    }
+                )
+
+        return {
+            "total_steps": len(self.steps),
+            "max_workers": self.max_workers,
+            "execution_levels": levels,
+            "estimated_parallel_batches": len(levels),
+            "parallelization_ratio": len([s for level in levels for s in level["steps"] if level["parallelizable"]])
+            / len(self.steps)
+            if self.steps
+            else 0,
+        }
+
+    def get_step_dependencies(self) -> dict[int, list[int]]:
+        """
+        Get a mapping of step dependencies.
+
+        Returns:
+            Dictionary mapping step numbers to their dependencies
+        """
+        return {step.number: step.dependencies.copy() for step in self.steps}
+
+    def get_steps_summary(self) -> list[dict[str, Any]]:
+        """
+        Get a summary of all steps in the chain.
+
+        Returns:
+            List of step summaries
+        """
+        return [
+            {
+                "number": step.number,
+                "title": step.title,
+                "aim": step.aim,
+                "dependencies": step.dependencies,
+                "entities": step.entities,
+                "has_dependencies": step.has_dependencies(),
+            }
+            for step in self.steps
+        ]
+
+
+class ChainBuilder:
+    """
+    Builder pattern for constructing reasoning chains.
+
+    Provides a fluent interface for building complex reasoning chains.
+    """
+
+    def __init__(self):
+        """Initialize the chain builder."""
+        self.steps: list[StepDescription] = []
+        self.max_workers: int = 3
+        self.prompt_template: PromptTemplate | None = None
+        self.enable_progress: bool = False
+        self.metadata: dict[str, Any] = {}
+
+    def add_step(
+        self,
+        number: int,
+        title: str,
+        aim: str,
+        reasoning_questions: str,
+        stage_action: str,
+        example_reasoning: str,
+        dependencies: list[int] | None = None,
+        entities: list[str] | None = None,
+    ) -> "ChainBuilder":
+        """
+        Add a step to the chain.
+
+        Args:
+            number: Step number
+            title: Step title
+            aim: Step objective
+            reasoning_questions: Key questions to answer
+            stage_action: Action to perform
+            example_reasoning: Example of expert reasoning
+            dependencies: List of step numbers this depends on
+            entities: Entities/concepts this works with
+
+        Returns:
+            Self for method chaining
+        """
+        step = StepDescription(
+            number=number,
+            title=title,
+            aim=aim,
+            reasoning_questions=reasoning_questions,
+            stage_action=stage_action,
+            example_reasoning=example_reasoning,
+            dependencies=dependencies or [],
+            entities=entities or [],
+        )
+        self.steps.append(step)
+        return self
+
+    def with_max_workers(self, max_workers: int) -> "ChainBuilder":
+        """
+        Set maximum number of parallel workers.
+
+        Args:
+            max_workers: Maximum workers
+
+        Returns:
+            Self for method chaining
+        """
+        self.max_workers = max_workers
+        return self
+
+    def with_prompt_template(self, template: PromptTemplate) -> "ChainBuilder":
+        """
+        Set custom prompt template.
+
+        Args:
+            template: Prompt template to use
+
+        Returns:
+            Self for method chaining
+        """
+        self.prompt_template = template
+        return self
+
+    def with_progress(self, enable: bool = True) -> "ChainBuilder":
+        """
+        Enable or disable progress tracking.
+
+        Args:
+            enable: Whether to enable progress
+
+        Returns:
+            Self for method chaining
+        """
+        self.enable_progress = enable
+        return self
+
+    def with_metadata(self, **metadata) -> "ChainBuilder":
+        """
+        Add metadata to the chain.
+
+        Args:
+            **metadata: Metadata key-value pairs
+
+        Returns:
+            Self for method chaining
+        """
+        self.metadata.update(metadata)
+        return self
+
+    def build(self) -> ReasoningChain:
+        """
+        Build the reasoning chain.
+
+        Returns:
+            Constructed reasoning chain
+
+        Raises:
+            ValueError: If chain configuration is invalid
+        """
+        return ReasoningChain(
+            steps=self.steps,
+            max_workers=self.max_workers,
+            prompt_template=self.prompt_template,
+            enable_progress=self.enable_progress,
+            metadata=self.metadata,
+        )
+
+
+def create_chain_from_config(config: dict[str, Any]) -> ReasoningChain:
+    """
+    Create a reasoning chain from a configuration dictionary.
+
+    Args:
+        config: Configuration dictionary
+
+    Returns:
+        Constructed reasoning chain
+    """
+    steps = []
+    for step_config in config.get("steps", []):
+        step = StepDescription(**step_config)
+        steps.append(step)
+
+    return ReasoningChain(
+        steps=steps,
+        max_workers=config.get("max_workers", 3),
+        enable_progress=config.get("enable_progress", False),
+        metadata=config.get("metadata", {}),
+    )

mmar_carl/executor.py

@@ -0,0 +1,343 @@
+"""
+DAG execution engine for CARL reasoning chains.
+
+Handles parallel execution of reasoning steps based on their dependencies.
+"""
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from .models import Language, PromptTemplate, ReasoningContext, ReasoningResult, StepDescription, StepExecutionResult
+
+
+@dataclass
+class ExecutionNode:
+    """
+    Represents a node in the execution DAG.
+    """
+
+    step: StepDescription
+    dependencies: list["ExecutionNode"]
+    dependents: list["ExecutionNode"]
+    executed: bool = False
+    executing: bool = False
+    result: StepExecutionResult | None = None
+
+    def __post_init__(self):
+        if self.dependencies is None:
+            self.dependencies = []
+        if self.dependents is None:
+            self.dependents = []
+
+    def can_execute(self) -> bool:
+        """Check if this node can be executed (all dependencies completed)."""
+        return all(dep.executed for dep in self.dependencies)
+
+    def is_ready(self) -> bool:
+        """Check if this node is ready for execution (not executing or executed)."""
+        return not self.executing and not self.executed and self.can_execute()
+
+
+class DAGExecutor:
+    """
+    Executes reasoning chains as a Directed Acyclic Graph (DAG).
+
+    Automatically parallelizes execution where dependencies allow.
+    """
+
+    def __init__(
+        self,
+        max_workers: int = 3,
+        prompt_template: PromptTemplate | None = None,
+        enable_progress: bool = False,
+    ):
+        """
+        Initialize the DAG executor.
+
+        Args:
+            max_workers: Maximum number of parallel executions
+            prompt_template: Template for generating prompts
+            enable_progress: Whether to enable progress tracking
+        """
+        self.max_workers = max_workers
+        self.prompt_template = prompt_template or PromptTemplate()
+        self.enable_progress = enable_progress
+        self._execution_stats = {
+            "total_steps": 0,
+            "executed_steps": 0,
+            "failed_steps": 0,
+            "parallel_batches": 0,
+            "total_time": 0.0,
+        }
+
+    def build_execution_graph(self, steps: list[StepDescription]) -> list[ExecutionNode]:
+        """
+        Build an execution graph from step descriptions.
+
+        Args:
+            steps: list of step descriptions
+
+        Returns:
+            list of execution nodes forming the DAG
+        """
+        if not steps:
+            return []
+
+        # Create nodes
+        step_map: dict[int, ExecutionNode] = {}
+        for step in steps:
+            node = ExecutionNode(step=step, dependencies=[], dependents=[])
+            step_map[step.number] = node
+
+        # Build dependencies
+        for step in steps:
+            node = step_map[step.number]
+            for dep_number in step.dependencies:
+                if dep_number in step_map:
+                    dependency_node = step_map[dep_number]
+                    node.dependencies.append(dependency_node)
+                    dependency_node.dependents.append(node)
+                else:
+                    raise ValueError(f"Step {step.number} depends on non-existent step {dep_number}")
+
+        # Validate no cycles
+        self._validate_no_cycles(step_map)
+
+        return list(step_map.values())
+
+    def _validate_no_cycles(self, nodes: dict[int, ExecutionNode]) -> None:
+        """
+        Validate that the execution graph has no cycles.
+
+        Args:
+            nodes: Dictionary of execution nodes
+
+        Raises:
+            ValueError: If cycles are detected
+        """
+        visited = set()
+        rec_stack = set()
+
+        def has_cycle(node_num: int) -> bool:
+            visited.add(node_num)
+            rec_stack.add(node_num)
+
+            node = nodes[node_num]
+            for dep in node.dependencies:
+                if dep.step.number not in visited:
+                    if has_cycle(dep.step.number):
+                        return True
+                elif dep.step.number in rec_stack:
+                    return True
+
+            rec_stack.remove(node_num)
+            return False
+
+        for node_num in nodes:
+            if node_num not in visited:
+                if has_cycle(node_num):
+                    raise ValueError(f"Cycle detected in execution graph involving step {node_num}")
+
+    async def execute_step(self, node: ExecutionNode, context: ReasoningContext) -> StepExecutionResult:
+        """
+        Execute a single reasoning step.
+
+        Args:
+            node: Execution node to execute
+            context: Reasoning context
+
+        Returns:
+            Step execution result
+        """
+        start_time = time.time()
+        step = node.step
+
+        try:
+            # Generate prompt for this step
+            step_prompt = self.prompt_template.format_step_prompt(step, context.language)
+            full_prompt = self.prompt_template.format_chain_prompt(
+                outer_context=context.outer_context,
+                current_task=step_prompt,
+                history=context.get_current_history(),
+                language=context.language,
+            )
+
+            # Execute LLM call with retries
+            result = await context.llm_client.get_response_with_retries(prompt=full_prompt, retries=context.retry_max)
+
+            # Update context history
+            if context.language == Language.ENGLISH:
+                step_result = f"Step {step.number}. {step.title}\nResult: {result}\n"
+            else:  # Russian
+                step_result = f"Шаг {step.number}. {step.title}\nРезультат: {result}\n"
+            updated_history = context.history.copy()
+            updated_history.append(step_result)
+
+            execution_time = time.time() - start_time
+
+            return StepExecutionResult(
+                step_number=step.number,
+                step_title=step.title,
+                result=result,
+                success=True,
+                execution_time=execution_time,
+                updated_history=updated_history,
+            )
+
+        except Exception as e:
+            execution_time = time.time() - start_time
+
+            return StepExecutionResult(
+                step_number=step.number,
+                step_title=step.title,
+                result="",
+                success=False,
+                error_message=str(e),
+                execution_time=execution_time,
+                updated_history=context.history.copy(),
+            )
+
+    async def execute_batch(
+        self, ready_nodes: list[ExecutionNode], context: ReasoningContext
+    ) -> list[StepExecutionResult]:
+        """
+        Execute a batch of ready nodes in parallel.
+
+        Args:
+            ready_nodes: list of nodes ready for execution
+            context: Reasoning context
+
+        Returns:
+            list of step execution results
+        """
+        if not ready_nodes:
+            return []
+
+        # Create independent contexts for parallel execution
+        context_snapshots = []
+        for _ in ready_nodes:
+            snapshot = ReasoningContext(
+                outer_context=context.outer_context,
+                llm_client=context.llm_client,
+                retry_max=context.retry_max,
+                history=context.history.copy(),
+                metadata=context.metadata.copy(),
+                language=context.language,
+            )
+            context_snapshots.append(snapshot)
+
+        # Execute in parallel
+        tasks = [self.execute_step(node, ctx) for node, ctx in zip(ready_nodes, context_snapshots)]
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Process results and handle exceptions
+        processed_results = []
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                processed_results.append(
+                    StepExecutionResult(
+                        step_number=ready_nodes[i].step.number,
+                        step_title=ready_nodes[i].step.title,
+                        result="",
+                        success=False,
+                        error_message=str(result),
+                    )
+                )
+            else:
+                processed_results.append(result)
+
+        return processed_results
+
+    async def execute(self, steps: list[StepDescription], context: ReasoningContext) -> ReasoningResult:
+        """
+        Execute a complete reasoning chain.
+
+        Args:
+            steps: list of step descriptions
+            context: Initial reasoning context
+
+        Returns:
+            Complete reasoning result
+        """
+        start_time = time.time()
+        self._execution_stats["total_steps"] = len(steps)
+
+        # Build execution graph
+        nodes = self.build_execution_graph(steps)
+        if not nodes:
+            return ReasoningResult(
+                success=True, history=[], step_results=[], total_execution_time=time.time() - start_time
+            )
+
+        # Execute DAG
+        executed_nodes: set[int] = set()
+        all_results: list[StepExecutionResult] = []
+        current_history = context.history.copy()
+        batch_count = 0
+
+        while len(executed_nodes) < len(nodes):
+            # Find ready nodes
+            ready_nodes = [node for node in nodes if node.step.number not in executed_nodes and node.can_execute()]
+
+            if not ready_nodes:
+                # This should not happen in a valid DAG
+                remaining = [n.step.number for n in nodes if n.step.number not in executed_nodes]
+                raise ValueError(f"Deadlock detected: unable to execute steps {remaining}")
+
+            batch_count += 1
+            if self.enable_progress:
+                print(f"Executing batch {batch_count} with {len(ready_nodes)} steps")
+
+            # Execute batch
+            batch_results = await self.execute_batch(ready_nodes, context)
+            all_results.extend(batch_results)
+
+            # Update history from successful results
+            # Sort by step number to maintain deterministic order
+            batch_results.sort(key=lambda r: r.step_number)
+            seen_steps = set()
+
+            for result in batch_results:
+                if result.success and result.step_number not in seen_steps:
+                    # Add the latest history entry from this step
+                    if result.updated_history:
+                        new_entry = result.updated_history[-1]
+                        current_history.append(new_entry)
+                        seen_steps.add(result.step_number)
+
+            # Mark nodes as executed
+            for node in ready_nodes:
+                node.executed = True
+                executed_nodes.add(node.step.number)
+
+            # Update context with current history
+            context.history = current_history.copy()
+
+        # Calculate final stats
+        total_time = time.time() - start_time
+        successful_steps = [r for r in all_results if r.success]
+        failed_steps = [r for r in all_results if not r.success]
+
+        self._execution_stats.update(
+            {
+                "executed_steps": len(successful_steps),
+                "failed_steps": len(failed_steps),
+                "parallel_batches": batch_count,
+                "total_time": total_time,
+            }
+        )
+
+        return ReasoningResult(
+            success=len(failed_steps) == 0,
+            history=current_history,
+            step_results=all_results,
+            total_execution_time=total_time,
+            metadata={"execution_stats": self._execution_stats.copy(), "parallel_batches": batch_count},
+        )
+
+    def get_execution_stats(self) -> dict[str, Any]:
+        """Get execution statistics from the last run."""
+        return self._execution_stats.copy()

mmar_carl/llm.py

@@ -0,0 +1,51 @@
+"""
+LLM client implementations for CARL using mmar-llm library.
+
+Provides integration with mmar-llm library for production use.
+"""
+
+from mmar_llm import EntrypointsAccessor
+
+from .models import LLMClientBase
+
+
+class LLMClient(LLMClientBase):
+    """
+    LLM client implementation using mmar-llm library.
+
+    Integrates with the mmar-llm EntrypointsAccessor for LLM calls.
+    """
+
+    def __init__(self, entrypoints: EntrypointsAccessor, entrypoint_key: str):
+        if not entrypoint_key:
+            raise ValueError("entrypoint_key is required and cannot be empty")
+
+        self.entrypoints = entrypoints
+        self.entrypoint_key = entrypoint_key
+
+    async def get_response(self, prompt: str) -> str:
+        # Get the specific entrypoint
+        ep = self.entrypoints[self.entrypoint_key]
+
+        # Check if the method is async or sync
+        result = ep.get_response_with_retries(prompt, retries=1)
+
+        # If the result is a coroutine (async), await it
+        if hasattr(result, "__await__") or hasattr(result, "__aiter__"):
+            return await result
+        else:
+            # If it's already a string, return it directly
+            return result
+
+    async def get_response_with_retries(self, prompt: str, retries: int = 3) -> str:
+        ep = self.entrypoints[self.entrypoint_key]
+
+        # Use mmar-llm's built-in retry functionality
+        result = ep.get_response_with_retries(prompt, retries=retries)
+
+        # If the result is a coroutine (async), await it
+        if hasattr(result, "__await__") or hasattr(result, "__aiter__"):
+            return await result
+        else:
+            # If it's already a string, return it directly
+            return result

mmar_carl/models.py

@@ -0,0 +1,219 @@
+"""
+Core data models for CARL reasoning system.
+"""
+
+from abc import ABC, abstractmethod
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Language(StrEnum):
+    """Supported languages."""
+
+    RUSSIAN = "ru"
+    ENGLISH = "en"
+
+
+class StepDescription(BaseModel):
+    """
+    Defines a single reasoning step in a chain.
+
+    This model encapsulates all the metadata needed for a reasoning step,
+    including its dependencies, objectives, and execution guidance.
+    """
+
+    number: int = Field(..., description="Step number in the sequence")
+    title: str = Field(..., description="Human-readable title of the step")
+    aim: str = Field(..., description="Primary objective of this step")
+    reasoning_questions: str = Field(..., description="Key questions to answer")
+    dependencies: list[int] = Field(default_factory=list, description="List of step numbers this step depends on")
+    entities: list[str] = Field(default_factory=list, description="Entities/concepts this step works with")
+    stage_action: str = Field(..., description="Specific action to perform")
+    example_reasoning: str = Field(..., description="Example of expert reasoning")
+
+    def depends_on(self, step_number: int) -> bool:
+        """Check if this step depends on a given step number."""
+        return step_number in self.dependencies
+
+    def has_dependencies(self) -> bool:
+        """Check if this step has any dependencies."""
+        return len(self.dependencies) > 0
+
+
+class ReasoningContext(BaseModel):
+    """
+    Context object that maintains state during reasoning execution.
+
+    Contains the input data, LLM client, execution history, and configuration.
+    """
+
+    outer_context: str = Field(..., description="Input data as string (it can be CSV or other text information)")
+    llm_client: Any = Field(..., description="LLM client for execution")
+    retry_max: int = Field(default=3, description="Maximum retry attempts")
+    history: list[str] = Field(default_factory=list, description="Accumulated reasoning history")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata and state")
+    language: Language = Field(default=Language.RUSSIAN, description="Language for reasoning prompts")
+
+    def add_to_history(self, entry: str) -> None:
+        """Add a new entry to the reasoning history."""
+        self.history.append(entry)
+
+    def get_current_history(self) -> str:
+        """Get the current reasoning history as a single string."""
+        return "\n".join(self.history)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class StepExecutionResult(BaseModel):
+    """
+    Result of executing a single reasoning step.
+    """
+
+    step_number: int = Field(..., description="Number of the executed step")
+    step_title: str = Field(..., description="Title of the executed step")
+    result: str = Field(..., description="Result content from LLM")
+    success: bool = Field(..., description="Whether execution succeeded")
+    error_message: str | None = Field(default=None, description="Error message if execution failed")
+    execution_time: float | None = Field(default=None, description="Time taken for execution in seconds")
+    updated_history: list[str] = Field(default_factory=list, description="History after this step's execution")
+
+
+class ReasoningResult(BaseModel):
+    """
+    Final result of executing a complete reasoning chain.
+    """
+
+    success: bool = Field(..., description="Whether overall execution succeeded")
+    history: list[str] = Field(..., description="Complete reasoning history")
+    step_results: list[StepExecutionResult] = Field(..., description="Results from each step")
+    total_execution_time: float | None = Field(default=None, description="Total execution time in seconds")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional result metadata")
+
+    def get_final_output(self) -> str:
+        """Get the final reasoning output as a single string."""
+        return "\n".join(self.history)
+
+    def get_successful_steps(self) -> list[StepExecutionResult]:
+        """Get all successfully executed steps."""
+        return [step for step in self.step_results if step.success]
+
+    def get_failed_steps(self) -> list[StepExecutionResult]:
+        """Get all failed steps."""
+        return [step for step in self.step_results if not step.success]
+
+
+class LLMClientBase(ABC):
+    """
+    Abstract base class for LLM clients.
+
+    This interface allows CARL to work with different LLM providers
+    while maintaining a consistent API.
+    """
+
+    @abstractmethod
+    async def get_response(self, prompt: str) -> str:
+        """
+        Get a response from the LLM.
+
+        Args:
+            prompt: The prompt to send to the LLM
+
+        Returns:
+            The LLM's response as a string
+
+        Raises:
+            Exception: If the LLM call fails
+        """
+        pass
+
+    @abstractmethod
+    async def get_response_with_retries(self, prompt: str, retries: int = 3) -> str:
+        """
+        Get a response from the LLM with retry logic.
+
+        Args:
+            prompt: The prompt to send to the LLM
+            retries: Maximum number of retry attempts
+
+        Returns:
+            The LLM's response as a string
+
+        Raises:
+            Exception: If all retry attempts fail
+        """
+        pass
+
+
+class PromptTemplate(BaseModel):
+    """
+    Template for generating prompts from reasoning steps.
+    """
+
+    system_prompt: str | None = Field(default=None, description="System-level instructions")
+
+    # Russian templates
+    ru_step_template: str = Field(
+        default="Шаг {step_number}. {step_title}\nЦель: {aim}\nЗадача: {stage_action}\nВопросы: {reasoning_questions}\nПример рассуждений: {example_reasoning}",
+        description="Template for individual step prompts in Russian",
+    )
+    ru_chain_template: str = Field(
+        default="Данные для анализа:\n{outer_context}\n{step_prompt}\nОтвечай кратко, подумай какие можно сделать выводы о результатах. Ответ должен состоять из одного параграфа. Не задавай дополнительных вопросов и не передавай инструкций. Пиши только текстом, без математических формул.",
+        description="Template for complete chain prompts in Russian",
+    )
+    ru_history_template: str = Field(
+        default="История предыдущих шагов:\n{history}\nОсновываясь на результатах предыдущих шагов, выполни следующую задачу:\n{current_task}",
+        description="Template for including history in prompts in Russian",
+    )
+
+    # English templates
+    en_step_template: str = Field(
+        default="Step {step_number}. {step_title}\nObjective: {aim}\nTask: {stage_action}\nQuestions: {reasoning_questions}\nExample reasoning: {example_reasoning}",
+        description="Template for individual step prompts in English",
+    )
+    en_chain_template: str = Field(
+        default="Data for analysis:\n{outer_context}\n{step_prompt}\nRespond concisely, consider what conclusions can be drawn from the results. Response should be one paragraph. Do not ask additional questions or provide instructions. Write in text only, without mathematical formulas.",
+        description="Template for complete chain prompts in English",
+    )
+    en_history_template: str = Field(
+        default="History of previous steps:\n{history}\nBased on the results of previous steps, perform the following task:\n{current_task}",
+        description="Template for including history in prompts in English",
+    )
+
+    def format_step_prompt(self, step: StepDescription, language: Language = Language.RUSSIAN) -> str:
+        """Format a single step prompt."""
+        if language == Language.ENGLISH:
+            return self.en_step_template.format(
+                step_number=step.number,
+                step_title=step.title,
+                aim=step.aim,
+                stage_action=step.stage_action,
+                reasoning_questions=step.reasoning_questions,
+                example_reasoning=step.example_reasoning,
+            )
+        else:  # Russian
+            return self.ru_step_template.format(
+                step_number=step.number,
+                step_title=step.title,
+                aim=step.aim,
+                stage_action=step.stage_action,
+                reasoning_questions=step.reasoning_questions,
+                example_reasoning=step.example_reasoning,
+            )
+
+    def format_chain_prompt(
+        self, outer_context: str, current_task: str, history: str = "", language: Language = Language.RUSSIAN
+    ) -> str:
+        """Format a complete chain prompt."""
+        if language == Language.ENGLISH:
+            if history:
+                current_task = self.en_history_template.format(history=history, current_task=current_task)
+
+            return self.en_chain_template.format(outer_context=outer_context, step_prompt=current_task)
+        else:  # Russian
+            if history:
+                current_task = self.ru_history_template.format(history=history, current_task=current_task)
+
+            return self.ru_chain_template.format(outer_context=outer_context, step_prompt=current_task)

mmar_carl-0.0.3.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: mmar-carl
+Version: 0.0.3
+Summary: Collaborative Agent Reasoning Library
+Keywords: 
+Author: glazkov, shaposhnikov, tagin
+Author-email: glazkov <glazkov@airi.net>, shaposhnikov <shaposhnikov@airi.net>, tagin <tagin@airi.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: mmar-llm>=1.0.6
+Requires-Dist: pydantic>=2.12.4
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# mmar-carl
+
+...

mmar_carl-0.0.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+mmar_carl/__init__.py,sha256=b6ucT35TUvjPgocZ4LE-OZyQ1NrZnRAxA9t7EbKYd1U,669
+mmar_carl/chain.py,sha256=KVsfRVIWcf8djV7OabNpIx48jDq_LrIh8hzvKDmvVzc,10483
+mmar_carl/executor.py,sha256=Mqm7nxT5kvV2vPd1obgG6kG6QC2bUt1Bmusn-nBDj34,11777
+mmar_carl/llm.py,sha256=82W8diXo1XL9RCUBYO5PeX5yzvfP3Zv4YHzJxfE3saA,1701
+mmar_carl/models.py,sha256=qV_V2z9DZ5lg3AINdzrujiBwcTH5kOU8Tqw_dBZWEXY,9476
+mmar_carl-0.0.3.dist-info/licenses/LICENSE,sha256=2A90w8WjhOgQXnFuUijKJYazaqZ4_NTokYb9Po4y-9k,1061
+mmar_carl-0.0.3.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+mmar_carl-0.0.3.dist-info/METADATA,sha256=WsieZRYaUbbS54ezVXKzFhxQDsa6N6dVF77HJZnagQo,964
+mmar_carl-0.0.3.dist-info/RECORD,,

mmar_carl-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

mmar_carl-0.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AIRI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.