lionagi 0.17.11__py3-none-any.whl → 0.18.1__py3-none-any.whl

lionagi/operations/plan/plan.py

@@ -1,386 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Any, Literal
-
-from pydantic import BaseModel
-
-from lionagi.fields.instruct import (
-    LIST_INSTRUCT_FIELD_MODEL,
-    Instruct,
-    InstructResponse,
-)
-from lionagi.ln import alcall
-from lionagi.protocols.types import ID
-from lionagi.session.branch import Branch
-from lionagi.session.session import Session
-
-from ..utils import prepare_instruct, prepare_session
-from .prompt import EXPANSION_PROMPT, PLAN_PROMPT
-
-# ---------------------------------------------------------------------
-# Data Model
-# ---------------------------------------------------------------------
-
-
-class PlanOperation(BaseModel):
-    """
-    Stores all relevant outcomes for a multi-step Plan:
-        * initial: The result of the initial plan prompt
-        * plan: A list of plan steps (Instruct objects) generated from the initial planning
-        * execute: Any responses from executing those plan steps
-    """
-
-    initial: Any
-    plan: list[Instruct] | None = None
-    execute: list[InstructResponse] | None = None
-
-
-# ---------------------------------------------------------------------
-# Utilities
-# ---------------------------------------------------------------------
-
-
-def chunked(iterable, n):
-    """
-    Yield successive n-sized chunks from an iterable.
-    Example:
-        >>> list(chunked([1,2,3,4,5], 2))
-        [[1,2],[3,4],[5]]
-    """
-    for i in range(0, len(iterable), n):
-        yield iterable[i : i + n]
-
-
-# ---------------------------------------------------------------------
-# Single-Step Runner
-# ---------------------------------------------------------------------
-
-
-async def run_step(
-    ins: Instruct,
-    session: Session,
-    branch: Branch,
-    verbose: bool = True,
-    **kwargs: Any,
-) -> Any:
-    """
-    Execute a single step of the plan with an 'expansion' or guidance prompt.
-
-    Args:
-        ins: The instruction model for the step.
-        session: The current session context.
-        branch: The branch to operate on for this step.
-        verbose: Whether to enable verbose output.
-        **kwargs: Additional keyword arguments passed to the branch operation.
-
-    Returns:
-        The result of the branch operation (which may contain more instructions).
-    """
-    if verbose:
-        snippet = (
-            ins.instruction[:100] + "..."
-            if len(ins.instruction) > 100
-            else ins.instruction
-        )
-        print(f"Further planning: {snippet}")
-
-    # Incorporate the EXPANSION_PROMPT into guidance
-    config = {**ins.model_dump(), **kwargs}
-    guidance_text = config.pop("guidance", "")
-    config["guidance"] = f"{EXPANSION_PROMPT}\n{guidance_text}"
-
-    # Run the step
-    result = await branch.operate(**config)
-    branch.dump_logs()  # Dump logs if needed
-    return result
-
-
-# ---------------------------------------------------------------------
-# Main Plan Function (with Multiple Execution Strategies)
-# ---------------------------------------------------------------------
-
-
-async def plan(
-    instruct: Instruct | dict[str, Any],
-    num_steps: int = 2,
-    session: Session | None = None,
-    branch: Branch | ID.Ref | None = None,
-    auto_run: bool = True,
-    auto_execute: bool = False,
-    execution_strategy: Literal[
-        "sequential",
-        "concurrent",
-        "sequential_concurrent_chunk",
-        "concurrent_sequential_chunk",
-    ] = "sequential",
-    execution_kwargs: dict[str, Any] | None = None,
-    branch_kwargs: dict[str, Any] | None = None,
-    return_session: bool = False,
-    verbose: bool = True,
-    **kwargs: Any,
-) -> PlanOperation | tuple[PlanOperation, Session]:
-    """
-    Create and optionally execute a multi-step plan with up to `num_steps`.
-
-    Steps:
-      1. Generate an initial plan with up to `num_steps`.
-      2. Optionally (auto_run=True) expand on each planned step
-         to refine or further clarify them.
-      3. Optionally (auto_execute=True) execute those refined steps
-         according to `execution_strategy`.
-
-    Args:
-        instruct: Initial instruction or a dict describing it.
-        num_steps: Maximum number of plan steps (must be <= 5).
-        session: An existing Session, or None to create a new one.
-        branch: An existing Branch, or None to create a new one.
-        auto_run: If True, automatically run the intermediate plan steps.
-        auto_execute: If True, automatically execute the fully refined steps.
-        execution_strategy:
-            - "sequential" (default) runs steps one by one
-            - "concurrent" runs all steps in parallel
-            - "sequential_concurrent_chunk" processes chunks sequentially, each chunk in parallel
-            - "concurrent_sequential_chunk" processes all chunks in parallel, each chunk sequentially
-        execution_kwargs: Extra kwargs used during execution calls.
-        branch_kwargs: Extra kwargs for branch/session creation.
-        return_session: Whether to return (PlanOperation, Session) instead of just PlanOperation.
-        verbose: If True, prints verbose logs.
-        **kwargs: Additional arguments for the initial plan operation.
-
-    Returns:
-        A PlanOperation object containing:
-            - initial plan
-            - (optional) plan expansions
-            - (optional) execution responses
-        Optionally returns the session as well, if `return_session=True`.
-    """
-
-    # -----------------------------------------------------------------
-    # 0. Basic Validation & Setup
-    # -----------------------------------------------------------------
-    if num_steps > 5:
-        raise ValueError("Number of steps must be 5 or less")
-
-    if verbose:
-        print(f"Planning execution with {num_steps} steps...")
-
-    # Ensure the correct field model
-    field_models: list = kwargs.get("field_models", [])
-    if LIST_INSTRUCT_FIELD_MODEL not in field_models:
-        field_models.append(LIST_INSTRUCT_FIELD_MODEL)
-    kwargs["field_models"] = field_models
-
-    # Prepare session/branch
-    session, branch = prepare_session(session, branch, branch_kwargs)
-    execute_branch: Branch = session.split(
-        branch
-    )  # a separate branch for execution
-
-    # -----------------------------------------------------------------
-    # 1. Run the Initial Plan Prompt
-    # -----------------------------------------------------------------
-    plan_prompt = PLAN_PROMPT.format(num_steps=num_steps)
-    instruct = prepare_instruct(instruct, plan_prompt)
-    initial_res = await branch.operate(**instruct, **kwargs)
-
-    # Wrap initial result in the PlanOperation
-    out = PlanOperation(initial=initial_res)
-
-    if verbose:
-        print("Initial planning complete. Starting step planning...")
-
-    # If we aren't auto-running the steps, just return the initial plan
-    if not auto_run:
-        return (out, session) if return_session else out
-
-    # -----------------------------------------------------------------
-    # 2. Expand Each Step (auto_run=True)
-    # -----------------------------------------------------------------
-    results = []
-    if hasattr(initial_res, "instruct_models"):
-        instructs: list[Instruct] = initial_res.instruct_models
-        for i, step_ins in enumerate(instructs, start=1):
-            if verbose:
-                print(f"\n----- Planning step {i}/{len(instructs)} -----")
-            expanded_res = await run_step(
-                step_ins, session, branch, verbose=verbose, **kwargs
-            )
-            results.append(expanded_res)
-
-        if verbose:
-            print("\nAll planning steps expanded/refined successfully!")
-
-    # Gather all newly created plan instructions
-    refined_plans = []
-    for step_result in results:
-        if hasattr(step_result, "instruct_models"):
-            for model in step_result.instruct_models:
-                if model and model not in refined_plans:
-                    refined_plans.append(model)
-
-    out.plan = refined_plans
-
-    # -----------------------------------------------------------------
-    # 3. Execute the Plan Steps (auto_execute=True)
-    # -----------------------------------------------------------------
-    if auto_execute:
-        if verbose:
-            print("\nStarting execution of all plan steps...")
-
-        # We now handle multiple strategies:
-        match execution_strategy:
-            # ---------------------------------------------------------
-            # Strategy A: SEQUENTIAL
-            # ---------------------------------------------------------
-            case "sequential":
-                seq_results = []
-                for i, plan_step in enumerate(refined_plans, start=1):
-                    if verbose:
-                        snippet = (
-                            plan_step.instruction[:100] + "..."
-                            if len(plan_step.instruction) > 100
-                            else plan_step.instruction
-                        )
-                        print(
-                            f"\n------ Executing step {i}/{len(refined_plans)} ------"
-                        )
-                        print(f"Instruction: {snippet}")
-
-                    step_response = await execute_branch.instruct(
-                        plan_step, **(execution_kwargs or {})
-                    )
-                    seq_results.append(
-                        InstructResponse(
-                            instruct=plan_step, response=step_response
-                        )
-                    )
-
-                out.execute = seq_results
-                if verbose:
-                    print("\nAll steps executed successfully (sequential)!")
-
-            # ---------------------------------------------------------
-            # Strategy B: CONCURRENT
-            # ---------------------------------------------------------
-            case "concurrent":
-
-                async def execute_step_concurrently(plan_step: Instruct):
-                    if verbose:
-                        snippet = (
-                            plan_step.instruction[:100] + "..."
-                            if len(plan_step.instruction) > 100
-                            else plan_step.instruction
-                        )
-                        print(f"\n------ Executing step (concurrently) ------")
-                        print(f"Instruction: {snippet}")
-                    local_branch = session.split(execute_branch)
-                    resp = await local_branch.instruct(
-                        plan_step, **(execution_kwargs or {})
-                    )
-                    return InstructResponse(instruct=plan_step, response=resp)
-
-                # Launch all steps in parallel
-                concurrent_res = await alcall(
-                    refined_plans, execute_step_concurrently
-                )
-                out.execute = concurrent_res
-                if verbose:
-                    print("\nAll steps executed successfully (concurrent)!")
-
-            # ---------------------------------------------------------
-            # Strategy C: SEQUENTIAL_CONCURRENT_CHUNK
-            #   - process plan steps in chunks (one chunk after another),
-            #   - each chunk's steps run in parallel.
-            # ---------------------------------------------------------
-            case "sequential_concurrent_chunk":
-                chunk_size = (execution_kwargs or {}).get("chunk_size", 5)
-                all_exec_responses = []
-
-                async def execute_chunk_concurrently(
-                    sub_steps: list[Instruct],
-                ):
-                    if verbose:
-                        print(
-                            f"\n--- Executing a chunk of size {len(sub_steps)} concurrently ---"
-                        )
-
-                    async def _execute(plan_step: Instruct):
-                        local_branch = session.split(execute_branch)
-                        resp = await local_branch.instruct(
-                            plan_step, **(execution_kwargs or {})
-                        )
-                        return InstructResponse(
-                            instruct=plan_step, response=resp
-                        )
-
-                    # run each chunk in parallel
-                    return await alcall(sub_steps, _execute)
-
-                # process each chunk sequentially
-                for chunk in chunked(refined_plans, chunk_size):
-                    chunk_responses = await execute_chunk_concurrently(chunk)
-                    all_exec_responses.extend(chunk_responses)
-
-                out.execute = all_exec_responses
-                if verbose:
-                    print(
-                        "\nAll steps executed successfully (sequential concurrent chunk)!"
-                    )
-
-            # ---------------------------------------------------------
-            # Strategy D: CONCURRENT_SEQUENTIAL_CHUNK
-            #   - split plan steps into chunks,
-            #   - run all chunks in parallel,
-            #   - but each chunk's steps run sequentially.
-            # ---------------------------------------------------------
-            case "concurrent_sequential_chunk":
-                chunk_size = (execution_kwargs or {}).get("chunk_size", 5)
-                all_chunks = list(chunked(refined_plans, chunk_size))
-
-                async def execute_chunk_sequentially(
-                    sub_steps: list[Instruct],
-                ):
-                    chunk_result = []
-                    local_branch = session.split(execute_branch)
-                    for plan_step in sub_steps:
-                        if verbose:
-                            snippet = (
-                                plan_step.instruction[:100] + "..."
-                                if len(plan_step.instruction) > 100
-                                else plan_step.instruction
-                            )
-                            print(
-                                f"\n--- Executing step (sequential in chunk) ---\nInstruction: {snippet}"
-                            )
-                        resp = await local_branch.instruct(
-                            plan_step, **(execution_kwargs or {})
-                        )
-                        chunk_result.append(
-                            InstructResponse(instruct=plan_step, response=resp)
-                        )
-                    return chunk_result
-
-                # run all chunks in parallel, each chunk sequentially
-                parallel_chunk_results = await alcall(
-                    all_chunks,
-                    execute_chunk_sequentially,
-                    output_flatten=True,
-                    output_dropna=True,
-                )
-
-                out.execute = parallel_chunk_results
-                if verbose:
-                    print(
-                        "\nAll steps executed successfully (concurrent sequential chunk)!"
-                    )
-
-            case _:
-                raise ValueError(
-                    f"Invalid execution strategy: {execution_strategy}"
-                )
-
-    # -----------------------------------------------------------------
-    # 4. Final Return
-    # -----------------------------------------------------------------
-    return (out, session) if return_session else out

lionagi/operations/plan/prompt.py

@@ -1,25 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-PLAN_PROMPT = """
-Develop a high-level plan containing {num_steps} distinct steps. Each step must:
-1. Represent a clear milestone or phase.
-2. Follow a logical sequence, respecting inter-step dependencies.
-3. Differ clearly from other steps.
-4. Have measurable completion criteria.
-5. Be open to further breakdown if needed.
-
-Keep each step concise yet actionable, ensuring the overall plan remains coherent.
-"""
-
-EXPANSION_PROMPT = """
-Transform each high-level plan step into detailed, executable actions. For every step:
-
-1. Keep actions atomic, verifiable, and clearly scoped.
-2. Include essential context and preconditions.
-3. Define expected outcomes, success criteria, and validations.
-4. Respect sequential dependencies and error handling.
-5. Provide all necessary parameters and specify outputs.
-
-Ensure each action is self-contained yet fits within the larger plan.
-"""

lionagi/operations/utils.py

@@ -1,45 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import TYPE_CHECKING
-
-from lionagi.fields.instruct import Instruct
-
-if TYPE_CHECKING:
-    from lionagi.session.session import Branch, Session
-
-
-def prepare_session(
-    session: "Session" = None,
-    branch: "Branch" = None,
-    branch_kwargs=None,
-) -> tuple["Session", "Branch"]:
-    from lionagi.session.session import Branch, Session
-
-    if session is not None:
-        if branch is not None:
-            branch: "Branch" = session.branches[branch]
-        else:
-            branch = session.new_branch(**(branch_kwargs or {}))
-    else:
-        session = Session()
-        if isinstance(branch, Branch):
-            session.branches.include(branch)
-            session.default_branch = branch
-        if branch is None:
-            branch = session.new_branch(**(branch_kwargs or {}))
-
-    return session, branch
-
-
-def prepare_instruct(instruct: Instruct | dict, prompt: str):
-    if isinstance(instruct, Instruct):
-        instruct = instruct.to_dict()
-    if not isinstance(instruct, dict):
-        raise ValueError(
-            "instruct needs to be an InstructModel object or a dictionary of valid parameters"
-        )
-
-    guidance = instruct.get("guidance", "")
-    instruct["guidance"] = f"\n{prompt}\n{guidance}"
-    return instruct

lionagi/protocols/forms/__init__.py

@@ -1,2 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0

lionagi/protocols/forms/base.py

@@ -1,85 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Any, Literal
-
-from pydantic import ConfigDict, Field
-from pydantic_core import PydanticUndefined
-
-from lionagi.utils import UNDEFINED
-
-from ..generic.element import Element
-
-
-class BaseForm(Element):
-    """
-    A minimal base form class to store fields and define output logic.
-    Typically, you'll inherit from this for domain-specific forms.
-    """
-
-    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
-
-    # A short "assignment" describing input->output
-    assignment: str | None = Field(
-        default=None,
-        description="A small DSL describing transformation, e.g. 'a,b -> c'.",
-    )
-    # Which fields are produced as 'final' or 'required' outputs.
-    output_fields: list[str] = Field(
-        default_factory=list,
-        description="Which fields are considered mandatory outputs.",
-    )
-    # Whether None counts as valid or incomplete
-    none_as_valid: bool = Field(
-        default=False,
-        description="If True, None is accepted as a valid value for completion checks.",
-    )
-    has_processed: bool = Field(
-        default=False,
-        description="Marks if the form is considered completed or 'processed'.",
-    )
-
-    def is_completed(self) -> bool:
-        """Check if all required output fields are set (and not UNDEFINED/None if not allowed)."""
-        missing = self.check_completeness()
-        return not missing
-
-    def check_completeness(
-        self, how: Literal["raise", "return_missing"] = "return_missing"
-    ) -> list[str]:
-        """
-        Return a list of any 'required' output fields that are missing or invalid.
-        If how='raise', raise an exception if missing any.
-        """
-        invalid_vals = [UNDEFINED, PydanticUndefined]
-        if not self.none_as_valid:
-            invalid_vals.append(None)
-
-        missing = []
-        for f in self.output_fields:
-            val = getattr(self, f, UNDEFINED)
-            if val in invalid_vals:
-                missing.append(f)
-
-        if missing and how == "raise":
-            raise ValueError(f"Form missing required fields: {missing}")
-        return missing
-
-    def get_results(self, valid_only: bool = False) -> dict[str, Any]:
-        """
-        Return a dict of all `output_fields`, optionally skipping invalid/None if `valid_only`.
-        """
-        results = {}
-        invalid_vals = [UNDEFINED, PydanticUndefined]
-        if not self.none_as_valid:
-            invalid_vals.append(None)
-
-        for f in self.output_fields:
-            val = getattr(self, f, UNDEFINED)
-            if valid_only and val in invalid_vals:
-                continue
-            results[f] = val
-        return results
-
-
-# File: lionagi/protocols/forms/base.py

lionagi/protocols/forms/flow.py

@@ -1,79 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from pydantic import BaseModel, ConfigDict, Field
-
-
-class FlowStep(BaseModel):
-    """
-    A minimal 'step' describing one transformation from some input fields to some output fields.
-    """
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    name: str = Field(..., description="Identifier for the step.")
-    inputs: list[str] = Field(
-        ..., description="Which fields are needed for this step."
-    )
-    outputs: list[str] = Field(
-        ..., description="Which fields are produced by this step."
-    )
-    description: str | None = None  # optional text doc
-
-
-class FlowDefinition(BaseModel):
-    """
-    A minimal DSL-based multi-step flow, e.g. 'a,b->c; c->d' to yield two steps.
-    """
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    steps: list[FlowStep] = Field(default_factory=list)
-
-    def parse_flow_string(self, flow_str: str):
-        """
-        Parse a string like 'a,b->c; c->d' into multiple FlowSteps.
-        We'll store them in self.steps in order.
-        """
-        if not flow_str:
-            return
-        segments = [seg.strip() for seg in flow_str.split(";") if seg.strip()]
-        for i, seg in enumerate(segments):
-            # seg might be like 'a,b->c' or 'a->b, c' etc
-            if "->" not in seg:
-                raise ValueError(f"Invalid DSL segment (no '->'): '{seg}'")
-            ins_str, outs_str = seg.split("->", 1)
-            inputs = [x.strip() for x in ins_str.split(",") if x.strip()]
-            outputs = [y.strip() for y in outs_str.split(",") if y.strip()]
-            step = FlowStep(
-                name=f"step_{i + 1}", inputs=inputs, outputs=outputs
-            )
-            self.steps.append(step)
-
-    def get_required_fields(self) -> set[str]:
-        """
-        Return all fields that are used as inputs in the earliest steps but not produced by prior steps.
-        This is a minimal approach; or we can do more advanced logic if needed.
-        """
-        produced = set()
-        required = set()
-        for step in self.steps:
-            # anything not yet produced is needed
-            for i in step.inputs:
-                if i not in produced:
-                    required.add(i)
-            for o in step.outputs:
-                produced.add(o)
-        return required
-
-    def get_produced_fields(self) -> set[str]:
-        """
-        Return all fields that eventually get produced by any step.
-        """
-        result = set()
-        for st in self.steps:
-            result.update(st.outputs)
-        return result
-
-
-# File: lionagi/protocols/forms/flow.py