lionagi 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

lionagi/strategies/base.py

@@ -0,0 +1,53 @@
+from typing import ClassVar
+
+from pydantic import model_validator
+
+from lionagi.fields.instruct import Instruct, InstructResponse
+
+from ..protocols.types import BaseLionModel
+from ..session.types import Branch, Session
+from .params import StrategyParams
+
+
+class StrategyExecutor(BaseLionModel):
+    """Base class for different execution strategies.
+
+    Each concrete executor should implement `execute()` to run instructions
+    according to a specific strategy (e.g., sequential, concurrent, chunked).
+    """
+
+    session: Session = None
+    branch: Branch = None
+    execute_branch: Branch = None
+    params: StrategyParams = None
+    params_cls: ClassVar[type[StrategyParams]] = StrategyParams
+
+    @model_validator(mode="before")
+    def validate_execution_config(cls, values: dict) -> dict:
+        params_cls = values.get("params_cls", cls.params_cls)
+        params = values.get("params", None)
+
+        if isinstance(params, dict):
+            params = params_cls(**params)
+        if not isinstance(params, StrategyParams):
+            params = params_cls(**values)
+
+        session: Session = values.get("session", params.session)
+        branch = values.get("branch", params.branch)
+        execute_branch = values.get("execute_branch", None) or session.split(
+            branch
+        )
+
+        return {
+            "params": params,
+            "session": session,
+            "branch": branch,
+            "execute_branch": execute_branch,
+            "params_cls": params_cls,
+        }
+
+    async def execute(
+        self, res
+    ) -> tuple[list[Instruct], list[InstructResponse]]:
+        """Run the instructions based on the strategy implemented by subclasses."""
+        raise NotImplementedError

lionagi/strategies/concurrent.py

@@ -0,0 +1,71 @@
+from lionagi.fields.instruct import Instruct, InstructResponse
+from lionagi.session.types import Branch
+from lionagi.utils import alcall, to_list
+
+from .base import StrategyExecutor
+
+
+class ConcurrentExecutor(StrategyExecutor):
+    """Executor for concurrent instruction processing.
+
+    Runs each instruction in parallel without chunking.
+    """
+
+    async def execute_instruct(
+        self, ins: Instruct, branch: Branch, auto_run: bool, **kwargs
+    ):
+        async def run(ins_):
+            if self.params.verbose:
+                print(f"\n-----Running sub-instruction-----\n{ins_.msg}")
+            b_ = self.session.split(branch)
+            return await self.execute_instruct(ins_, b_, False, **kwargs)
+
+        config = {**ins.model_dump(), **kwargs}
+        res = await branch.instruct(**config)
+        branch.msgs.logger.dump()
+        instructs = (
+            res.instruct_models if hasattr(res, "instruct_models") else []
+        )
+
+        if auto_run and instructs:
+            ress = await alcall(instructs, run)
+            response_ = []
+            for r in ress:
+                if isinstance(r, list):
+                    response_.extend(r)
+                else:
+                    response_.append(r)
+            response_.insert(0, res)
+            return response_
+        return res
+
+    async def instruct_concurrent_single(
+        self, ins_: Instruct, execute_branch: Branch
+    ) -> InstructResponse:
+        if self.params.verbose:
+            print(f"\n-----Running instruction-----\n{ins_.msg}")
+        b_ = self.session.split(execute_branch)
+        response = await self.execute_instruct(
+            ins_, b_, self.params.auto_run, **self.params.execute_kwargs
+        )
+        return InstructResponse(instruct=ins_, response=response)
+
+    async def execute(
+        self, res
+    ) -> tuple[list[Instruct], list[InstructResponse]]:
+        async with self.session.branches:
+            response_ = []
+            instructs = []
+            if hasattr(res, "instruct_models"):
+                instructs: list[Instruct] = res.instruct_models
+                ress = await alcall(
+                    instructs,
+                    self.instruct_concurrent_single,
+                    execute_branch=self.execute_branch,
+                )
+                ress = to_list(ress, dropna=True, flatten=True)
+                response_ = [r for r in ress if not isinstance(r, (str, dict))]
+                response_ = to_list(
+                    response_, unique=True, dropna=True, flatten=True
+                )
+            return instructs, response_

lionagi/strategies/concurrent_chunk.py

@@ -0,0 +1,43 @@
+from typing import ClassVar
+
+from lionagi.fields.instruct import Instruct, InstructResponse
+from lionagi.utils import to_list
+
+from ..libs.async_utils import bcall
+from .concurrent import ConcurrentExecutor
+from .params import ChunkStrategyParams
+
+
+class ConcurrentChunkExecutor(ConcurrentExecutor):
+    """Executor for concurrent chunked instruction processing.
+
+    Breaks instructions into chunks and executes each chunk concurrently.
+    """
+
+    params: ChunkStrategyParams | None = None
+    params_cls: ClassVar[type[ChunkStrategyParams]] = ChunkStrategyParams
+
+    async def execute(
+        self, res
+    ) -> tuple[list[Instruct], list[InstructResponse]]:
+        async with self.session.branches:
+            instructs = []
+            response_ = []
+            if hasattr(res, "instruct_models"):
+                instructs: list[Instruct] = res.instruct_models
+                ress = []
+                async for chunk_result in await bcall(
+                    instructs,
+                    self.instruct_concurrent_single,
+                    execute_branch=self.execute_branch,
+                    batch_size=self.params.chunk_size,
+                    **self.params.rcall_params.to_dict(),
+                ):
+                    ress.extend(chunk_result)
+
+                ress = to_list(ress, dropna=True, flatten=True)
+                response_ = [r for r in ress if not isinstance(r, (str, dict))]
+                response_ = to_list(
+                    response_, unique=True, dropna=True, flatten=True
+                )
+            return instructs, response_

lionagi/strategies/concurrent_sequential_chunk.py

@@ -0,0 +1,104 @@
+from pydantic import model_validator
+
+from lionagi.fields.instruct import Instruct, InstructResponse
+from lionagi.session.types import Branch, Session
+from lionagi.utils import alcall
+
+from .base import StrategyExecutor
+from .params import HybridStrategyParams
+
+
+class ConcurrentSequentialChunkExecutor(StrategyExecutor):
+    """Concurrent-sequential chunked executor:
+    1. Splits instructions into chunks
+    2. Processes chunks concurrently
+    3. Processes each instruction within a chunk sequentially.
+    """
+
+    params: HybridStrategyParams
+    session: Session
+    branch: Branch
+
+    @model_validator(mode="before")
+    def validate_execution_config(cls, values: dict) -> dict:
+        params = values.get("params", None)
+        if params is None:
+            params = HybridStrategyParams(**values)
+
+        if (
+            params.outer_mode != "concurrent"
+            or params.inner_mode != "sequential"
+        ):
+            raise ValueError(
+                "Requires outer_mode='concurrent' and inner_mode='sequential'"
+            )
+
+        session = values.get("session", params.session)
+        if not session:
+            raise ValueError("Session is required")
+        branch = values.get("branch", params.branch)
+        if isinstance(branch, Branch):
+            if branch not in session.branches:
+                session.branches.include(branch)
+        elif not branch:
+            branch = session.new_branch()
+        elif isinstance(branch, str):
+            branch = session.split(branch)
+        else:
+            raise ValueError("Invalid branch type")
+
+        return {"params": params, "session": session, "branch": branch}
+
+    async def _execute_single(
+        self, ins_: Instruct, idx: int, ttl: int
+    ) -> InstructResponse:
+        if self.params.verbose:
+            msg_ = (
+                (ins_.instruction[:100] + "...")
+                if len(ins_.instruction) > 100
+                else ins_.instruction
+            )
+            print(
+                f"\n-----Executing Instruct {idx}/{ttl}-----\n{msg_}"
+                if ttl
+                else f"\n-----Executing Instruct {idx}-----\n{msg_}"
+            )
+
+        res = await self.branch.instruct(ins_, **self.params.execute_kwargs)
+        return InstructResponse(instruct=ins_, response=res)
+
+    async def _execute_chunk(
+        self, chunk: list[tuple[Instruct, int, int]]
+    ) -> list[InstructResponse]:
+        # Each chunk sequential
+        branch = self.session.split(self.branch)
+        responses = []
+        for ins_, idx, ttl in chunk:
+            r = await self._execute_single(ins_, idx, ttl)
+            responses.append(r)
+        return responses
+
+    async def execute(self) -> list[InstructResponse]:
+        instructions = self.params.instruct
+        chunk_size = self.params.chunk_size
+        total = len(instructions)
+
+        if total <= chunk_size:
+            chunk = [(ins, i + 1, total) for i, ins in enumerate(instructions)]
+            return await self._execute_chunk(chunk)
+
+        chunks = []
+        for start in range(0, total, chunk_size):
+            end = min(start + chunk_size, total)
+            chunk = [
+                (instructions[i], i + 1, total) for i in range(start, end)
+            ]
+            chunks.append(chunk)
+
+        chunk_responses = await alcall(
+            chunks, self._execute_chunk, max_workers=self.params.max_workers
+        )
+        responses = []
+        for c in chunk_responses:
+            responses.extend(c)
+        return responses

lionagi/strategies/params.py

@@ -0,0 +1,128 @@
+from typing import Any, Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from lionagi.fields.instruct import INSTRUCT_FIELD_MODEL, Instruct
+from lionagi.libs.async_utils import RCallParams
+from lionagi.protocols.types import FieldModel, SchemaModel
+from lionagi.session.types import Branch, Session
+
+
+class StrategyParams(SchemaModel):
+    """Base parameters for execution strategies."""
+
+    instruct: list[Instruct] | Instruct = Field(
+        ..., description="Instructions to execute"
+    )
+    session: Session | None = Field(
+        default=None, description="Session for managing branches"
+    )
+    branch: Branch | str | None = Field(
+        default=None, description="Branch or branch reference for execution"
+    )
+    verbose: bool = Field(
+        default=True, description="Whether to print execution progress"
+    )
+    execute_kwargs: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional keyword arguments for execution",
+    )
+    branch_kwargs: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Keyword arguments for creating new branches",
+    )
+    auto_run: bool = False
+    auto_execute: bool = False
+    instruct_model_field: type[FieldModel] = INSTRUCT_FIELD_MODEL
+
+    @field_validator("branch_kwargs", mode="before")
+    def _validate_branch_kwargs(cls, v: Any) -> dict:
+        if v is None:
+            return {}
+        if hasattr(v, "to_dict"):
+            return v.to_dict()
+        if isinstance(v, dict):
+            return v
+        raise ValueError("branch_kwargs must be a dictionary or SchemaModel")
+
+    @field_validator("instruct", mode="before")
+    def validate_instructions(cls, v: Any) -> list[Instruct]:
+        """Validate and convert instructions to list format."""
+        if isinstance(v, Instruct):
+            return [v]
+        if isinstance(v, (list, tuple)):
+            if not all(isinstance(i, Instruct) for i in v):
+                raise ValueError("All instructions must be Instruct instances")
+            return list(v)
+        raise ValueError("Instructions must be Instruct or list of Instruct")
+
+    @field_validator("branch", mode="before")
+    def validate_branch(cls, v: Any) -> Branch | str | None:
+        """Validate branch reference."""
+        if v is None or isinstance(v, (Branch, str)):
+            return v
+        raise ValueError("Branch must be a Branch instance or branch ID")
+
+    @field_validator("session", mode="before")
+    def validate_session(cls, v: Any) -> Session | None:
+        """Validate session reference."""
+        if v is None or isinstance(v, Session):
+            return v
+        raise ValueError("Session must be a Session instance")
+
+    @model_validator(mode="after")
+    def _validate_session_branch(self):
+        if self.session is None:
+            self.session = Session()
+        if self.branch is None:
+            self.branch = self.session.new_branch(**self.branch_kwargs)
+        elif isinstance(self.branch, Branch):
+            if self.branch not in self.session.branches:
+                self.session.branches.include(self.branch)
+        elif isinstance(self.branch, str):
+            if self.branch not in self.session.branches:
+                raise ValueError("Branch ID not found in session")
+            self.branch = self.session.branches[self.branch]
+        return self
+
+
+class ChunkStrategyParams(StrategyParams):
+    """Parameters for chunked execution strategies."""
+
+    chunk_size: int = Field(
+        default=5,
+        description="Number of instructions to process in each chunk",
+        gt=0,
+    )
+    rcall_params: RCallParams = Field(default_factory=RCallParams)
+
+    @field_validator("rcall_params", mode="before")
+    def validate_rcall_params(cls, v: dict) -> RCallParams:
+        return RCallParams(**v)
+
+
+class HybridStrategyParams(ChunkStrategyParams):
+    """Parameters for hybrid execution strategies."""
+
+    outer_mode: Literal["concurrent", "sequential"] = Field(
+        ..., description="Execution mode for outer loop"
+    )
+    inner_mode: Literal["concurrent", "sequential"] = Field(
+        ..., description="Execution mode for inner loop"
+    )
+    inner_chunk_size: int | None = Field(
+        default=None, description="Chunk size for inner loop execution", gt=0
+    )
+    inner_rcall_params: RCallParams = Field(default_factory=RCallParams)
+
+    @field_validator("inner_chunk_size", mode="before")
+    def validate_inner_chunk_size(cls, v: Any) -> int | None:
+        if v is None:
+            return None
+        if not isinstance(v, int) or v <= 0:
+            raise ValueError("inner_chunk_size must be a positive integer")
+        return v
+
+    @field_validator("inner_rcall_params", mode="before")
+    def validate_inner_rcall_params(cls, v: dict):
+        return RCallParams(**v)

lionagi/strategies/sequential.py

@@ -0,0 +1,23 @@
+from lionagi.fields.instruct import Instruct, InstructResponse
+
+from .base import StrategyExecutor
+
+
+class SequentialExecutor(StrategyExecutor):
+    """Executor that runs instructions sequentially, one after another."""
+
+    async def execute(
+        self, res
+    ) -> tuple[list[Instruct], list[InstructResponse]]:
+        ress = []
+        instructs = (
+            res.instruct_models if hasattr(res, "instruct_models") else []
+        )
+        for idx, item in enumerate(instructs, start=1):
+            if self.params.verbose:
+                print(f"\nExecuting step {idx}/{len(instructs)}")
+            out = await self.execute_branch.instruct(
+                item, **self.params.execute_kwargs
+            )
+            ress.append(InstructResponse(instruct=item, response=out))
+        return instructs, ress

lionagi/strategies/sequential_chunk.py

@@ -0,0 +1,89 @@
+from pydantic import model_validator
+
+from lionagi.fields.instruct import Instruct, InstructResponse
+from lionagi.session.types import Branch, Session
+
+from .base import StrategyExecutor
+from .params import ChunkStrategyParams
+
+
+class SequentialChunkExecutor(StrategyExecutor):
+    """Executor for sequential chunked instruction processing.
+
+    Splits instructions into chunks and processes each chunk one by one.
+    """
+
+    params: ChunkStrategyParams
+    session: Session
+    branch: Branch
+
+    @model_validator(mode="before")
+    def validate_execution_config(cls, values: dict) -> dict:
+        params = values.get("params", None)
+        if params is None:
+            params = ChunkStrategyParams(**values)
+
+        session = values.get("session", params.session)
+        if not session:
+            raise ValueError(
+                "Session is required for sequential chunk execution"
+            )
+
+        branch = values.get("branch", params.branch)
+        if isinstance(branch, Branch):
+            if branch not in session.branches:
+                session.branches.include(branch)
+        elif not branch:
+            branch = session.new_branch()
+        elif isinstance(branch, str):
+            branch = session.split(branch)
+        else:
+            raise ValueError("Invalid branch type")
+
+        return {"params": params, "session": session, "branch": branch}
+
+    async def _execute_single(
+        self, ins_: Instruct, idx: int, ttl: int
+    ) -> InstructResponse:
+        if self.params.verbose:
+            msg_ = (
+                (ins_.instruction[:100] + "...")
+                if len(ins_.instruction) > 100
+                else ins_.instruction
+            )
+            if idx and ttl:
+                print(f"\n-----Executing Instruct {idx}/{ttl}-----\n{msg_}")
+            else:
+                print(f"\n-----Executing Instruct-----\n{msg_}")
+
+        res = await self.branch.instruct(ins_, **self.params.execute_kwargs)
+        return InstructResponse(instruct=ins_, response=res)
+
+    async def _execute_chunk(
+        self, chunk: list[tuple[Instruct, int, int]]
+    ) -> list[InstructResponse]:
+        responses = []
+        for ins_, idx, ttl in chunk:
+            res = await self._execute_single(ins_, idx, ttl)
+            responses.append(res)
+        return responses
+
+    async def execute(self) -> list[InstructResponse]:
+        instructions = self.params.instruct
+        chunk_size = self.params.chunk_size
+        total = len(instructions)
+
+        if total <= chunk_size:
+            chunk = [(ins, i + 1, total) for i, ins in enumerate(instructions)]
+            return await self._execute_chunk(chunk)
+
+        responses = []
+        for start in range(0, total, chunk_size):
+            end = min(start + chunk_size, total)
+            chunk = [
+                (instructions[i], i + 1, total) for i in range(start, end)
+            ]
+            chunk_responses = await self._execute_chunk(chunk)
+            responses.extend(chunk_responses)
+
+        return responses

lionagi/strategies/sequential_concurrent_chunk.py

@@ -0,0 +1,100 @@
+from pydantic import model_validator
+
+from lionagi.fields.instruct import Instruct, InstructResponse
+from lionagi.session.types import Branch, Session
+
+from ..libs.async_utils import alcall
+from .base import StrategyExecutor
+from .params import HybridStrategyParams
+
+
+class SequentialConcurrentChunkExecutor(StrategyExecutor):
+    """Sequential-concurrent chunked executor:
+    1. Splits instructions into chunks
+    2. Processes chunks sequentially
+    3. Within each chunk, processes instructions concurrently
+    """
+
+    params: HybridStrategyParams
+    session: Session
+    branch: Branch
+
+    @model_validator(mode="before")
+    def validate_execution_config(cls, values: dict) -> dict:
+        params = values.get("params", None)
+        if params is None:
+            params = HybridStrategyParams(**values)
+
+        if (
+            params.outer_mode != "sequential"
+            or params.inner_mode != "concurrent"
+        ):
+            raise ValueError(
+                "Requires outer_mode='sequential' and inner_mode='concurrent'"
+            )
+
+        session = values.get("session", params.session)
+        if not session:
+            raise ValueError("Session is required")
+
+        branch = values.get("branch", params.branch)
+        if isinstance(branch, Branch):
+            if branch not in session.branches:
+                session.branches.include(branch)
+        elif not branch:
+            branch = session.new_branch()
+        elif isinstance(branch, str):
+            branch = session.split(branch)
+        else:
+            raise ValueError("Invalid branch type")
+
+        return {"params": params, "session": session, "branch": branch}
+
+    async def _execute_single(
+        self, ins_: Instruct, idx: int, ttl: int
+    ) -> InstructResponse:
+        if self.params.verbose:
+            msg_ = (
+                (ins_.instruction[:100] + "...")
+                if len(ins_.instruction) > 100
+                else ins_.instruction
+            )
+            print(
+                f"\n-----Executing Instruct {idx}/{ttl}-----\n{msg_}"
+                if ttl
+                else f"\n-----Executing Instruct {idx}-----\n{msg_}"
+            )
+
+        branch = self.session.split(self.branch)
+        res = await branch.instruct(ins_, **self.params.execute_kwargs)
+        return InstructResponse(instruct=ins_, response=res)
+
+    async def _execute_chunk(
+        self, chunk: list[tuple[Instruct, int, int]]
+    ) -> list[InstructResponse]:
+        # Each chunk concurrently
+        return await alcall(
+            chunk,
+            self._execute_single,
+            max_workers=self.params.inner_max_workers,
+        )
+
+    async def execute(self) -> list[InstructResponse]:
+        instructions = self.params.instruct
+        chunk_size = self.params.chunk_size
+        total = len(instructions)
+
+        if total <= chunk_size:
+            chunk = [(ins, i + 1, total) for i, ins in enumerate(instructions)]
+            return await self._execute_chunk(chunk)
+
+        responses = []
+        for start in range(0, total, chunk_size):
+            end = min(start + chunk_size, total)
+            chunk = [
+                (instructions[i], i + 1, total) for i in range(start, end)
+            ]
+            chunk_responses = await self._execute_chunk(chunk)
+            responses.extend(chunk_responses)
+
+        return responses

lionagi/strategies/types.py

@@ -0,0 +1,21 @@
+from .base import StrategyExecutor
+from .concurrent import ConcurrentExecutor
+from .concurrent_chunk import ConcurrentChunkExecutor
+from .concurrent_sequential_chunk import ConcurrentSequentialChunkExecutor
+from .params import ChunkStrategyParams, HybridStrategyParams, StrategyParams
+from .sequential import SequentialExecutor
+from .sequential_chunk import SequentialChunkExecutor
+from .sequential_concurrent_chunk import SequentialConcurrentChunkExecutor
+
+__all__ = (
+    "StrategyExecutor",
+    "ConcurrentExecutor",
+    "ConcurrentSequentialChunkExecutor",
+    "ConcurrentChunkExecutor",
+    "SequentialConcurrentChunkExecutor",
+    "SequentialExecutor",
+    "SequentialChunkExecutor",
+    "StrategyParams",
+    "ChunkStrategyParams",
+    "HybridStrategyParams",
+)

lionagi/strategies/utils.py

@@ -0,0 +1,49 @@
+from typing import Any
+
+from lionagi.fields.instruct import Instruct
+from lionagi.utils import alcall
+
+from ..session.types import Branch, Session
+
+
+async def run_instruct(
+    ins: Instruct,
+    session: Session,
+    branch: Branch,
+    auto_run: bool,
+    verbose: bool = True,
+    **kwargs: Any,
+) -> Any:
+    async def run(ins_):
+        if verbose:
+            msg_ = (
+                ins_.instruction[:100] + "..."
+                if len(ins_.instruction) > 100
+                else ins_.instruction
+            )
+            print(f"\n-----Running instruction-----\n{msg_}")
+        b_ = session.split(branch)
+        return await run_instruct(
+            ins_, session, b_, False, verbose=verbose, **kwargs
+        )
+
+    config = {**ins.model_dump(), **kwargs}
+    res = await branch.operate(**config)
+    branch.msgs.logger.dump()
+    instructs = []
+
+    if hasattr(res, "instruct_models"):
+        instructs = res.instruct_models
+
+    if auto_run is True and instructs:
+        ress = await alcall(instructs, run)
+        response_ = []
+        for res in ress:
+            if isinstance(res, list):
+                response_.extend(res)
+            else:
+                response_.append(res)
+        response_.insert(0, res)
+        return response_
+
+    return res

lionagi/version.py

@@ -1 +1 @@
-__version__ = "0.4.0"
+__version__ = "0.5.1"