mmar-carl 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

mmar_carl/__init__.py

@@ -6,10 +6,9 @@ A library for building chain-of-thought reasoning systems with DAG-based paralle
 
 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"
+__version__ = "0.0.5"
 __all__ = [
     "Language",
     "StepDescription",
@@ -20,6 +19,4 @@ __all__ = [
     "ReasoningChain",
     "ChainBuilder",
     "DAGExecutor",
-    "LLMClientBase",
-    "LLMClient",
 ]

mmar_carl/executor.py

@@ -164,8 +164,13 @@ class DAGExecutor:
                 language=context.language,
             )
 
-            # Execute LLM call with retries
-            result = await context.llm_client.get_response_with_retries(prompt=full_prompt, retries=context.retry_max)
+            # Execute LLM call with retries using EntrypointsAccessor
+            ep = context.entrypoints[context.entrypoint_key]
+            result = ep.get_response_with_retries(full_prompt, retries=context.retry_max)
+
+            # If the result is a coroutine (async), await it
+            if hasattr(result, "__await__") or hasattr(result, "__aiter__"):
+                result = await result
 
             # Update context history
             if context.language == Language.ENGLISH:
@@ -220,7 +225,8 @@ class DAGExecutor:
         for _ in ready_nodes:
             snapshot = ReasoningContext(
                 outer_context=context.outer_context,
-                llm_client=context.llm_client,
+                entrypoints=context.entrypoints,
+                entrypoint_key=context.entrypoint_key,
                 retry_max=context.retry_max,
                 history=context.history.copy(),
                 metadata=context.metadata.copy(),

mmar_carl/models.py

@@ -2,7 +2,6 @@
 Core data models for CARL reasoning system.
 """
 
-from abc import ABC, abstractmethod
 from enum import StrEnum
 from typing import Any
 
@@ -46,11 +45,12 @@ class ReasoningContext(BaseModel):
     """
     Context object that maintains state during reasoning execution.
 
-    Contains the input data, LLM client, execution history, and configuration.
+    Contains the input data, entrypoints accessor, 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")
+    entrypoints: Any = Field(..., description="EntrypointsAccessor for LLM execution")
+    entrypoint_key: str = Field(default="default", description="Key for the specific entrypoint to use")
     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")
@@ -105,46 +105,6 @@ class ReasoningResult(BaseModel):
         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):

mmar_carl-0.0.5.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: mmar-carl
+Version: 0.0.5
+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 - Collaborative Agent Reasoning Library
+
+A Python library for building chain-of-thought reasoning systems with DAG-based parallel execution and mmar-llm integration.
+
+## Overview
+
+CARL provides a structured framework for creating complex reasoning chains that can execute steps in parallel where dependencies allow. It's designed to work seamlessly with the `mmar-llm` library for production LLM integration and supports multi-language reasoning (Russian/English).
+
+## Key Features
+
+- **DAG-based Execution**: Automatically parallelizes reasoning steps based on dependencies
+- **Direct mmar-llm Integration**: Uses EntrypointsAccessor directly without unnecessary abstractions
+- **Multi-language Support**: Built-in support for Russian and English languages
+- **Clean Architecture**: Simple and straightforward usage pattern
+- **Production Ready**: Async/sync compatibility, error handling, and retry logic
+- **Parallel Processing**: Optimized execution with configurable worker pools
+- **Financial Focus**: Designed for financial analysis with specialized prompts
+
+## Quick Start
+
+```python
+import asyncio
+from mmar_carl import (
+    ReasoningChain, StepDescription, ReasoningContext,
+    Language
+)
+from mmar_llm import EntrypointsAccessor, EntrypointsConfig
+
+# Define a reasoning chain
+EBITDA_ANALYSIS = [
+    StepDescription(
+        number=1,
+        title="Рост EBITDA и стабильность",
+        aim="Выяснить, стабильно ли растет EBITDA и насколько выросла",
+        reasoning_questions="Насколько изменилась (выросла/уменьшилась) EBITDA за рассматриваемый период?",
+        dependencies=[],
+        entities=["EBITDA"],
+        stage_action="Рассчитать темп прироста EBITDA за 12 последних месяцев год к году",
+        example_reasoning="1) если темп > 0%, то положительный сигнал; если темп < 0%, то отрицательный сигнал"
+    ),
+    StepDescription(
+        number=2,
+        title="Маржинальность EBITDA",
+        aim="Выяснить, сколько процентов выручки забирают операционные расходы",
+        reasoning_questions="Какая маржинальность по EBITDA за рассматриваемый период?",
+        dependencies=[1],  # Depends on step 1
+        entities=["EBITDA_MARGIN", "EBITDA", "SALES_REVENUE"],
+        stage_action="EBITDA маржа = EBITDA / SALES_REVENUE",
+        example_reasoning="1) если маржа > 0%, то положительный сигнал: компания зарабатывает больше своих операционных расходов"
+    )
+]
+
+# Create entrypoints accessor from configuration file
+def create_entrypoints(entrypoints_path: str):
+    """Create EntrypointsAccessor from configuration file."""
+    import json
+    with open(entrypoints_path, encoding="utf-8") as f:
+        config_data = json.load(f)
+
+    entrypoints_config = EntrypointsConfig.model_validate(config_data)
+    return EntrypointsAccessor(entrypoints_config)
+
+# Create and execute the reasoning chain
+entrypoints = create_entrypoints("entrypoints.json")
+chain = ReasoningChain(
+    steps=EBITDA_ANALYSIS,
+    max_workers=2,
+    enable_progress=True
+)
+
+context = ReasoningContext(
+    outer_context="Период,EBITDA,SALES_REVENUE\n2023-Q1,1000000,5000000\n2023-Q2,1200000,5500000",
+    entrypoints=entrypoints,
+    entrypoint_key="my_entrypoint",
+    language=Language.RUSSIAN,
+    retry_max=3
+)
+
+result = chain.execute(context)
+print(result.get_final_output())
+```
+
+## Installation
+
+```bash
+# For production use
+pip install mmar-carl
+
+# For development with mmar-llm integration
+pip install mmar-carl mmar-llm>=1.0.3
+
+# Development version with all dependencies
+pip install mmar-carl[dev]
+```
+
+## Requirements
+
+- Python 3.12+
+- mmar-llm>=1.0.3 (for LLM integration)
+- Pydantic for data models
+- asyncio for parallel execution
+
+## Documentation
+
+- **Quick Start**: [docs/quickstart.md](docs/quickstart.md) - Get up and running quickly
+- **Examples**: [docs/examples.md](docs/examples.md) - Real-world usage examples
+- **Advanced Usage**: [docs/advanced.md](docs/advanced.md) - Advanced features and optimization
+- **Methodology**: [docs/methodology.md](docs/methodology.md) - Development methodology (in Russian)
+
+## Architecture
+
+CARL is built around several key components:
+
+- **StepDescription**: Defines individual reasoning steps with metadata and dependencies
+- **ReasoningChain**: Orchestrates the execution of reasoning steps with DAG optimization
+- **DAGExecutor**: Handles parallel execution based on dependencies with configurable workers
+- **ReasoningContext**: Manages execution state, history, and multi-language support
+- **EntrypointsAccessor**: Direct integration with mmar-llm EntrypointsAccessor
+- **Language**: Built-in support for Russian and English languages
+- **PromptTemplate**: Multi-language prompt templates for different analysis types
+
+## Key Concepts
+
+### DAG-Based Parallel Execution
+
+CARL automatically analyzes step dependencies and creates execution batches for maximum parallelization:
+
+```python
+# Steps 1 and 2 execute in parallel
+StepDescription(number=1, title="Revenue Analysis", dependencies=[])
+StepDescription(number=2, title="Cost Analysis", dependencies=[])
+# Step 3 waits for both to complete
+StepDescription(number=3, title="Profitability Analysis", dependencies=[1, 2])
+```
+
+### Multi-language Support
+
+Built-in support for Russian and English with appropriate prompt templates:
+
+```python
+# Russian language reasoning
+context = ReasoningContext(
+    outer_context=data,
+    entrypoints=entrypoints,
+    entrypoint_key="my_entrypoint",
+    language=Language.RUSSIAN
+)
+
+# English language reasoning
+context = ReasoningContext(
+    outer_context=data,
+    entrypoints=entrypoints,
+    entrypoint_key="my_entrypoint",
+    language=Language.ENGLISH
+)
+```
+
+### Direct mmar-llm Integration
+
+Simple and straightforward usage without unnecessary abstractions:
+
+```python
+from mmar_llm import EntrypointsAccessor
+
+# Direct usage pattern
+context = ReasoningContext(
+    outer_context=data,
+    entrypoints=entrypoints,
+    entrypoint_key="my_entrypoint"
+)
+```
+
+## Example Usage
+
+See the [example.py](example.py) file for a complete end-to-end demonstration with:
+
+- Direct mmar-llm EntrypointsAccessor integration
+- Multi-language support (Russian/English)
+- Parallel execution demonstration
+- Error handling and retry logic
+- Performance metrics
+
+Run it with:
+
+```bash
+# Set entrypoints configuration
+export ENTRYPOINTS_PATH=/path/to/your/entrypoints.json
+
+# Run the demonstration
+python example.py entrypoints.json my_entrypoint_key
+
+# Or run with environment variable
+ENTRYPOINTS_PATH=entrypoints.json python example.py
+```
+
+## License
+
+MIT License - see LICENSE file for details.

mmar_carl-0.0.5.dist-info/RECORD

@@ -0,0 +1,9 @@
+mmar_carl/__init__.py,sha256=UhK3QNaAIGO4WCfCBjgzANnmWgPI-eYdiwR_QvrxWo0,589
+mmar_carl/chain.py,sha256=KVsfRVIWcf8djV7OabNpIx48jDq_LrIh8hzvKDmvVzc,10483
+mmar_carl/executor.py,sha256=RzxGXAgv56Wwskqmrma8shItTEWkpY6CvuT-AWUx67Q,12069
+mmar_carl/llm.py,sha256=82W8diXo1XL9RCUBYO5PeX5yzvfP3Zv4YHzJxfE3saA,1701
+mmar_carl/models.py,sha256=cOtnWGnRk1ymPJGhfoDJbV8dJTISII6TrYZ0xul95fM,8596
+mmar_carl-0.0.5.dist-info/licenses/LICENSE,sha256=2A90w8WjhOgQXnFuUijKJYazaqZ4_NTokYb9Po4y-9k,1061
+mmar_carl-0.0.5.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+mmar_carl-0.0.5.dist-info/METADATA,sha256=Y3VdutXTMvfs8l6pRNDY2i93upXf9GbvWzz1GXOUez4,7942
+mmar_carl-0.0.5.dist-info/RECORD,,

mmar_carl-0.0.3.dist-info/METADATA

@@ -1,29 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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,,