lionagi 0.7.8__tar.gz → 0.8.0__tar.gz

{lionagi-0.7.8 → lionagi-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.7.8
+Version: 0.8.0
 Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>
 License:            Apache License

lionagi-0.8.0/docs/modules/form.rst

@@ -0,0 +1,329 @@
+======================================
+Form & Flow
+======================================
+
+The forms module provides a flexible system for handling structured data transformations
+through forms and multi-step flows. It consists of four core components:
+
+1. :class:`BaseForm` - Foundation for form handling
+2. :class:`Form` - Enhanced form with input/output field distinction
+3. :class:`FlowDefinition` - Multi-step transformation pipeline
+4. :class:`Report` - Aggregator for completed forms
+
+-----------
+Base Form
+-----------
+
+.. module:: lionagi.operatives.forms.base
+   :synopsis: Core form functionality.
+
+.. class:: BaseForm
+
+   **Inherits from**: :class:`lionagi.protocols.generic.element.Element`
+
+   A minimal form class that tracks output fields and validates completeness.
+   Uses Pydantic v2 with ``ConfigDict(extra="allow", arbitrary_types_allowed=True)``.
+
+   **Attributes**:
+
+   - **assignment** (*str | None*) -- A DSL string describing the transformation
+   - **output_fields** (*list[str]*) -- Fields considered mandatory outputs
+   - **none_as_valid** (*bool*) -- If True, None is accepted as valid
+   - **has_processed** (*bool*) -- Marks if form is completed
+
+   **Methods**:
+
+   .. method:: is_completed() -> bool
+
+      Check if all required output fields are set and valid.
+      A field is considered valid if:
+      
+      - It exists and has a value
+      - The value is not UNDEFINED
+      - If none_as_valid=False, the value is not None
+
+   .. method:: check_completeness(how: Literal["raise", "return_missing"]) -> list[str]
+
+      Return missing required fields or raise an exception.
+
+      Parameters:
+         - **how** -- If "raise", raises ValueError for missing fields.
+           If "return_missing", returns list of missing field names.
+
+   .. method:: get_results(valid_only: bool = False) -> dict[str, Any]
+
+      Return a dict of output fields, optionally filtering invalid values.
+
+      Parameters:
+         - **valid_only** -- If True, omit fields with None/UNDEFINED values
+           (depending on none_as_valid setting)
+
+   **Example**::
+
+      from lionagi.operatives.forms import BaseForm
+
+      form = BaseForm(
+          output_fields=["result"],
+          none_as_valid=False
+      )
+      form.result = "computation complete"
+      assert form.is_completed()
+      print(form.get_results())  # {"result": "computation complete"}
+
+      # With none_as_valid=True
+      form = BaseForm(
+          output_fields=["optional_result"],
+          none_as_valid=True
+      )
+      form.optional_result = None
+      assert form.is_completed()  # True, None is valid
+
+-----------
+Flow System
+-----------
+
+.. module:: lionagi.operatives.forms.flow
+   :synopsis: Multi-step flow handling.
+
+.. class:: FlowStep
+
+   **Inherits from**: :class:`pydantic.BaseModel`
+
+   A single transformation step in a multi-step flow.
+   Uses Pydantic v2 with ``ConfigDict(arbitrary_types_allowed=True)``.
+
+   **Attributes**:
+
+   - **name** (*str*) -- Step identifier (e.g., "step_1")
+   - **inputs** (*list[str]*) -- Required input fields for this step
+   - **outputs** (*list[str]*) -- Fields produced by this step
+   - **description** (*str | None*) -- Optional step documentation
+
+.. class:: FlowDefinition
+
+   **Inherits from**: :class:`pydantic.BaseModel`
+
+   Manages a sequence of transformation steps using a DSL.
+   Uses Pydantic v2 with ``ConfigDict(arbitrary_types_allowed=True)``.
+
+   **Attributes**:
+
+   - **steps** (*List[FlowStep]*) -- Ordered list of transformation steps
+
+   **Methods**:
+
+   .. method:: parse_flow_string(flow_str: str)
+
+      Parse a DSL string like "a,b->c; c->d" into FlowSteps.
+      Each step is named sequentially (step_1, step_2, etc.).
+      Empty segments and whitespace are handled gracefully.
+
+   .. method:: get_required_fields() -> set[str]
+
+      Return fields needed as inputs but not produced by prior steps.
+      For example, in "a->b; b,c->d", returns {"a", "c"} since:
+      
+      - "a" is needed by step 1 but not produced earlier
+      - "b" is needed by step 2 but produced by step 1
+      - "c" is needed by step 2 but not produced earlier
+
+   .. method:: get_produced_fields() -> set[str]
+
+      Return all fields produced by any step.
+      For example, in "a->b,c; c->d", returns {"b", "c", "d"}.
+
+   **Example**::
+
+      from lionagi.operatives.forms import FlowDefinition
+
+      flow = FlowDefinition()
+      
+      # Parse text processing pipeline
+      flow.parse_flow_string(
+          "text->tokens; tokens->embeddings; embeddings->clusters"
+      )
+      
+      print(flow.get_required_fields())  # {"text"}
+      print(flow.get_produced_fields())  # {"tokens", "embeddings", "clusters"}
+      
+      # Steps are named sequentially
+      for step in flow.steps:
+          print(f"{step.name}: {step.inputs} -> {step.outputs}")
+
+------
+Form
+------
+
+.. module:: lionagi.operatives.forms.form
+   :synopsis: Enhanced form with input/output distinction.
+
+.. class:: Form
+
+   **Inherits from**: :class:`BaseForm`
+
+   A form that distinguishes between input and request (output) fields.
+   Uses Pydantic v2 with ``ConfigDict(extra="allow", arbitrary_types_allowed=True)``.
+
+   **Attributes**:
+
+   - **flow_definition** (*Optional[FlowDefinition]*) -- For multi-step flows
+   - **guidance** (*str | None*) -- Optional processing guidance
+   - **task** (*str | None*) -- Task description
+
+   **Validators**:
+
+   - **parse_assignment_into_flow**: Creates FlowDefinition for multi-step assignments
+   - **compute_output_fields**: Sets output_fields based on assignment or flow
+
+   **Methods**:
+
+   .. method:: fill_fields(**kwargs)
+
+      Update form fields with provided values.
+      Useful for partial updates when you don't want to recreate the form.
+
+   .. method:: to_instructions() -> dict[str, Any]
+
+      Return a dictionary suitable for LLM consumption, containing:
+      
+      - assignment: The DSL string
+      - flow: FlowDefinition as dict (if multi-step)
+      - guidance: Optional processing guidance
+      - task: Optional task description
+      - required_outputs: List of required output fields
+
+   **Example**::
+
+      from lionagi.operatives.forms import Form
+
+      # Single-step form
+      form = Form(assignment="user_input->greeting")
+      form.fill_fields(user_input="Alice")
+      
+      # Multi-step form with all produced fields as outputs
+      form = Form(
+          assignment="name,age->profile; profile->recommendation",
+          guidance="Generate personalized recommendations",
+          task="User profiling"
+      )
+      
+      # The flow is automatically parsed
+      assert form.flow_definition is not None
+      assert len(form.flow_definition.steps) == 2
+      
+      # All produced fields are outputs
+      assert set(form.output_fields) == {"profile", "recommendation"}
+
+--------
+Report
+--------
+
+.. module:: lionagi.operatives.forms.report
+   :synopsis: Form aggregation and tracking.
+
+.. class:: Report
+
+   **Inherits from**: :class:`BaseForm`
+
+   Collects and manages multiple completed forms.
+   Uses Pydantic v2 with ``ConfigDict(extra="allow", arbitrary_types_allowed=True)``.
+
+   **Attributes**:
+
+   - **default_form_cls** (*type[Form]*) -- Form class to use (defaults to Form)
+   - **completed_forms** (*Pile[Form]*) -- Thread-safe collection of completed forms
+   - **form_assignments** (*dict[str, str]*) -- Maps form IDs to assignments
+
+   **Methods**:
+
+   .. method:: add_completed_form(form: Form, update_report_fields: bool = False)
+
+      Add a completed form to the report.
+
+      Parameters:
+         - **form** -- A completed Form instance
+         - **update_report_fields** -- If True, copy form's output values to report
+
+      Raises:
+         - ValueError if form is incomplete
+
+   **Example**::
+
+      from lionagi.operatives.forms import Report, Form
+
+      report = Report()
+      
+      # Create and complete forms for a multi-step process
+      form1 = Form(assignment="query->embeddings")
+      form1.fill_fields(
+          query="What's the weather?",
+          embeddings=[0.1, 0.2, 0.3]
+      )
+      
+      form2 = Form(assignment="embeddings->answer")
+      form2.fill_fields(
+          embeddings=form1.embeddings,
+          answer="Sunny with a high of 75°F"
+      )
+      
+      # Add both forms, updating report fields from the final form
+      report.add_completed_form(form1)
+      report.add_completed_form(form2, update_report_fields=True)
+      
+      print(report.answer)  # "Sunny with a high of 75°F"
+
+--------------------
+Additional Notes
+--------------------
+
+**DSL Format**
+
+The forms system uses a simple DSL (Domain Specific Language) for describing
+transformations:
+
+- Single step: ``input1, input2 -> output``
+- Multiple steps: ``a,b->c; c->d``
+- Spaces are allowed: ``input1, input2  ->  output``
+
+The DSL is parsed into either:
+
+1. Simple input/output field lists for :class:`Form`
+2. A full :class:`FlowDefinition` for multi-step processes
+
+**Multi-step Flow Behavior**
+
+When using multi-step flows:
+
+1. Each step's outputs become available to later steps as inputs
+2. The form's output_fields include all produced fields by default
+3. You can override output_fields to select specific outputs
+4. Required fields are those needed as inputs but not produced by prior steps
+
+**Best Practices**
+
+1. Use :class:`BaseForm` when you only need output validation
+2. Use :class:`Form` when distinguishing inputs from outputs
+3. Use :class:`FlowDefinition` for complex multi-step transformations
+4. Use :class:`Report` to track multiple related forms
+5. Set none_as_valid=True when fields may legitimately be None
+6. Provide guidance and task descriptions for better LLM interaction
+
+**Type Safety**
+
+All form classes use Pydantic v2 for validation. You can create typed forms by
+subclassing and adding type hints::
+
+   from pydantic import Field
+   from lionagi.utils import UNDEFINED
+
+   class UserForm(Form):
+       name: str = Field(default=UNDEFINED)
+       age: int = Field(default=UNDEFINED)
+       profile: str | None = Field(default=None)
+       
+       model_config = ConfigDict(
+           extra="allow",
+           arbitrary_types_allowed=True
+       )
+
+This ensures type safety and proper validation for form fields.

{lionagi-0.7.8 → lionagi-0.8.0}/lionagi/operations/manager.py

@@ -1,4 +1,4 @@
-from typing import Callable
+from collections.abc import Callable
 
 from lionagi.protocols._concepts import Manager
 

lionagi-0.8.0/lionagi/operatives/forms/base.py

@@ -0,0 +1,80 @@
+# forms/base_form.py
+
+from typing import Any, Literal
+
+from pydantic import ConfigDict, Field
+from pydantic_core import PydanticUndefined
+
+from lionagi.protocols.generic.element import Element
+from lionagi.utils import UNDEFINED
+
+
+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

lionagi-0.8.0/lionagi/operatives/forms/flow.py

@@ -0,0 +1,74 @@
+# forms/flow.py
+from typing import List
+
+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

lionagi-0.8.0/lionagi/operatives/forms/form.py

@@ -0,0 +1,82 @@
+# forms/form.py
+
+from typing import Any, Optional
+
+from pydantic import ConfigDict, Field, model_validator
+from typing_extensions import Self
+
+from .base import BaseForm
+from .flow import FlowDefinition
+
+
+class Form(BaseForm):
+    """
+    A domain form that can handle either a simple 'a,b->c' assignment
+    or a multi-step flow if the assignment string has semicolons, etc.
+    """
+
+    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+
+    flow_definition: FlowDefinition | None = None
+    # Possibly some extra fields, e.g. "guidance" or "task"
+    guidance: str | None = Field(default=None)
+    task: str | None = Field(default=None)
+
+    @model_validator(mode="before")
+    def parse_assignment_into_flow(cls, values):
+        """
+        If the 'assignment' has semicolons, assume multiple steps, parse into FlowDefinition.
+        If it's a single step or no semicolons, we remain in 'simple' mode.
+        """
+        assignment_str = values.get("assignment")
+        if assignment_str and ";" in assignment_str:
+            flow = FlowDefinition()
+            flow.parse_flow_string(assignment_str)
+            values["flow_definition"] = flow
+        return values
+
+    @model_validator(mode="after")
+    def compute_output_fields(self) -> Self:
+        """
+        If in simple mode, we parse something like 'a,b->c' and set output_fields=[c].
+        If in multi-step mode, we set output_fields to the final produced fields of the flow.
+        """
+        if self.flow_definition:
+            # multi-step
+            produced = self.flow_definition.get_produced_fields()
+            if not self.output_fields:
+                self.output_fields = list(produced)
+        else:
+            # single-step
+            if self.assignment and "->" in self.assignment:
+                # parse the single arrow
+                ins_outs = self.assignment.split("->", 1)
+                outs_str = ins_outs[1]
+                outs = [x.strip() for x in outs_str.split(",") if x.strip()]
+                if not self.output_fields:
+                    self.output_fields = outs
+        return self
+
+    def fill_fields(self, **kwargs) -> None:
+        """
+        A small helper: fill fields in this form by direct assignment.
+        Usually you'd do 'myform(field=val, field2=val2)', but sometimes you want partial updates.
+        """
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+    def to_instructions(self) -> dict[str, Any]:
+        """
+        Return a small dictionary that an LLM can read as an 'instruction context'.
+        """
+        return {
+            "assignment": self.assignment,
+            "flow": (
+                self.flow_definition.model_dump()
+                if self.flow_definition
+                else None
+            ),
+            "guidance": self.guidance,
+            "task": self.task,
+            "required_outputs": self.output_fields,
+        }

lionagi-0.8.0/lionagi/operatives/forms/report.py

@@ -0,0 +1,45 @@
+# forms/report.py
+
+from pydantic import Field
+
+from lionagi.protocols.generic.pile import Pile
+
+from .base import BaseForm
+from .form import Form
+
+
+class Report(BaseForm):
+    """
+    A minimal class that collects multiple completed forms as "sub-tasks."
+    If you have a single FlowDefinition that describes the entire multi-step pipeline,
+    you can track each step as a separate form in here.
+    """
+
+    default_form_cls: type[Form] = Form
+    completed_forms: Pile[Form] = Field(
+        default_factory=lambda: Pile(item_type={Form}),
+        description="A list of forms that have been completed for this report.",
+    )
+    form_assignments: dict[str, str] = Field(
+        default_factory=dict,
+        description="Mapping from form ID -> assignment string",
+    )
+
+    def add_completed_form(
+        self, form: Form, update_report_fields: bool = False
+    ):
+        """
+        Add a completed form. Optionally update the report’s fields from the form's output.
+        """
+        missing = form.check_completeness()
+        if missing:
+            raise ValueError(
+                f"Form {form.id} is incomplete: missing {missing}."
+            )
+        self.completed_forms.append(form)
+        self.form_assignments[form.id] = form.assignment or ""
+        # optionally update the report’s own fields
+        if update_report_fields:
+            for f_ in form.output_fields:
+                val = getattr(form, f_, None)
+                setattr(self, f_, val)

{lionagi-0.7.8 → lionagi-0.8.0}/lionagi/operatives/types.py

@@ -10,6 +10,7 @@ from .action.request_response_model import (
 )
 from .action.tool import FuncTool, FuncToolRef, Tool, ToolRef
 from .forms.base import BaseForm
+from .forms.flow import FlowDefinition, FlowStep
 from .forms.form import Form
 from .forms.report import Report
 from .instruct.base import (
@@ -66,4 +67,6 @@ __all__ = (
     "FuncTool",
     "FuncToolRef",
     "FunctionCalling",
+    "FlowDefinition",
+    "FlowStep",
 )

lionagi-0.8.0/lionagi/version.py

@@ -0,0 +1 @@
+__version__ = "0.8.0"

{lionagi-0.7.8 → lionagi-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lionagi"
-version = "0.7.8"
+version = "0.8.0"
 description = "An Intelligence Operating System."
 authors = [
     { name = "HaiyangLi", email = "quantocean.li@gmail.com" },