lionagi 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

lionagi/core/unit/template/score.py

@@ -0,0 +1,124 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from lionagi.libs.ln_convert import to_str
+from lionagi.core.collections.abc import Field
+from lionagi.core.unit import UnitForm
+
+
+class ScoreTemplate(UnitForm):
+    """
+    A template for performing a scoring task based on given instructions and context.
+
+    Inherits from `UnitForm` and adds fields and methods specific to scoring tasks.
+
+    Attributes:
+        confidence_score (float | None): A numeric score between 0 to 1 formatted to 2 decimal places, indicating confidence in the score.
+        reason (str | None): A brief reason for the given output.
+        template_name (str): The name of the template.
+        score (float | None): A score for the given context and task.
+        assignment (str): A string representing the task assignment for the score.
+    """
+
+    confidence_score: float | None = Field(
+        None,
+        description="a numeric score between 0 to 1 formatted in num:0.2f, 1 being very confident and 0 being not confident at all",
+        validation_kwargs={
+            "upper_bound": 1,
+            "lower_bound": 0,
+            "num_type": float,
+            "precision": 2,
+        },
+    )
+
+    reason: str | None = Field(
+        None,
+        description="brief reason for the given output, format: This is my best response because ...",
+    )
+
+    template_name: str = "score_template"
+
+    score: float | None = Field(
+        None,
+        description="a score for the given context and task, numeric",
+    )
+
+    assignment: str = "task -> score"
+
+    @property
+    def answer(self):
+        """
+        Gets the score attribute.
+
+        Returns:
+            float | None: The score for the given context and task.
+        """
+        return getattr(self, "score", None)
+
+    def __init__(
+        self,
+        *,
+        instruction=None,
+        context=None,
+        score_range=(0, 10),
+        include_endpoints=True,
+        num_digit=0,
+        confidence_score=False,
+        reason=False,
+        **kwargs,
+    ):
+        """
+        Initializes a new instance of the ScoreTemplate class.
+
+        Args:
+            instruction (str, optional): Additional instructions for the scoring task.
+            context (str, optional): Additional context for the scoring task.
+            score_range (tuple, optional): The range of the score. Defaults to (0, 10).
+            include_endpoints (bool, optional): Whether to include the endpoints in the score range. Defaults to True.
+            num_digit (int, optional): The number of digits allowed after the decimal point. Defaults to 0.
+            confidence_score (bool, optional): Whether to include a confidence score. Defaults to False.
+            reason (bool, optional): Whether to include a reasoning field. Defaults to False.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(**kwargs)
+
+        return_precision = ""
+
+        if num_digit == 0:
+            return_precision = "integer"
+        else:
+            return_precision = f"num:{to_str(num_digit)}f"
+
+        self.task = f"""
+perform scoring task according to the following constraints:
+1. additional objective: {to_str(instruction or "N/A")}.
+2. score range: {to_str(score_range)}.
+3. include_endpoints: {"yes" if include_endpoints else "no"}.
+4. precision, (max number of digits allowed after "."): {return_precision}.
+5. additional information: {to_str(context or "N/A")}.
+"""
+        if reason:
+            self.append_to_request("reason")
+
+        if confidence_score:
+            self.append_to_request("confidence_score")
+
+        self.validation_kwargs["score"] = {
+            "upper_bound": score_range[1],
+            "lower_bound": score_range[0],
+            "num_type": int if num_digit == 0 else float,
+            "precision": num_digit if num_digit != 0 else None,
+        }

lionagi/core/unit/template/select.py

@@ -0,0 +1,104 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from enum import Enum
+from .base import BaseUnitForm, Field
+
+
+class SelectTemplate(BaseUnitForm):
+    """
+    A template for performing a selection task based on given instructions and context.
+
+    Inherits from `BaseUnitForm` and adds fields and methods specific to selection tasks.
+
+    Attributes:
+        confidence_score (float | None): A numeric score between 0 to 1 formatted to 2 decimal places, indicating confidence in the selection.
+        reason (str | None): A brief reason for the given output.
+        template_name (str): The name of the template.
+        selection (Enum | str | list | None): The selection from given choices.
+        choices (list): The given choices to select from.
+        assignment (str): A string representing the task assignment for the selection.
+    """
+
+    confidence_score: float | None = Field(
+        None,
+        description="a numeric score between 0 to 1 formatted in num:0.2f, 1 being very confident and 0 being not confident at all, just guessing",
+        validation_kwargs={
+            "upper_bound": 1,
+            "lower_bound": 0,
+            "num_type": float,
+            "precision": 2,
+        },
+    )
+
+    reason: str | None = Field(
+        default_factory=str,
+        description="brief reason for the given output, format: This is my best response because ...",
+    )
+
+    template_name: str = "default_select"
+
+    selection: Enum | str | list | None = Field(
+        None, description="selection from given choices"
+    )
+    choices: list = Field(default_factory=list, description="the given choices")
+
+    assignment: str = "task -> selection"
+
+    @property
+    def answer(self):
+        """
+        Gets the selection attribute.
+
+        Returns:
+            Enum | str | list | None: The selection from given choices.
+        """
+        return getattr(self, "selection", None)
+
+    def __init__(
+        self,
+        *,
+        instruction=None,
+        context=None,
+        choices=None,
+        reason=False,
+        confidence_score=False,
+        **kwargs,
+    ):
+        """
+        Initializes a new instance of the SelectTemplate class.
+
+        Args:
+            instruction (str, optional): Additional instructions for the selection task.
+            context (str, optional): Additional context for the selection task.
+            choices (list, optional): The choices to select from.
+            reason (bool, optional): Whether to include a reasoning field. Defaults to False.
+            confidence_score (bool, optional): Whether to include a confidence score. Defaults to False.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(**kwargs)
+
+        self.choices = choices
+        self.task = f"""
+select 1 item from the provided choices {choices}.        
+1. additional objective: {instruction or "N/A"}.
+2. additional information: {context or "N/A"}.     
+"""
+        if reason:
+            self.append_to_request("reason")
+
+        if confidence_score:
+            self.append_to_request("confidence_score")

lionagi/core/unit/unit.py

@@ -0,0 +1,362 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from lionagi.libs.ln_convert import strip_lower
+from lionagi.libs.ln_func_call import rcall
+from lionagi.core.collections.abc import Directive
+from lionagi.core.validator.validator import Validator
+from lionagi.core.collections import iModel
+from .unit_form import UnitForm
+from .unit_mixin import DirectiveMixin
+from .util import retry_kwargs
+
+
+class Unit(Directive, DirectiveMixin):
+    """
+    Unit is a class that extends Directive and DirectiveMixin to provide
+    advanced operations like chat, direct actions, and predictions using a
+    specific branch and model.
+
+    Attributes:
+        branch (Branch): The branch instance associated with the Unit.
+        imodel (iModel): The model instance used for the Unit.
+        form_template (Type[Form]): The form template to use for operations.
+        validator (Validator): The validator instance for response validation.
+    """
+
+    default_template = UnitForm
+
+    def __init__(
+        self, branch, imodel: iModel = None, template=None, rulebook=None, verbose=False
+    ) -> None:
+        self.branch = branch
+        if imodel and isinstance(imodel, iModel):
+            branch.imodel = imodel
+            self.imodel = imodel
+        else:
+            self.imodel = branch.imodel
+        self.form_template = template or self.default_template
+        self.validator = Validator(rulebook=rulebook) if rulebook else Validator()
+        self.verbose = verbose
+
+    async def chat(
+        self,
+        instruction=None,
+        context=None,
+        system=None,
+        sender=None,
+        recipient=None,
+        branch=None,
+        requested_fields=None,
+        form=None,
+        tools=False,
+        invoke_tool=True,
+        return_form=True,
+        strict=False,
+        rulebook=None,
+        imodel=None,
+        clear_messages=False,
+        use_annotation=True,
+        return_branch=False,
+        **kwargs,
+    ):
+        """
+        Asynchronously performs a chat operation.
+
+        Args:
+            instruction (str, optional): Instruction message.
+            context (str, optional): Context message.
+            system (str, optional): System message.
+            sender (str, optional): Sender identifier.
+            recipient (str, optional): Recipient identifier.
+            branch (Branch, optional): Branch instance.
+            requested_fields (list, optional): Fields requested in the response.
+            form (Form, optional): Form data.
+            tools (bool, optional): Flag indicating if tools should be used.
+            invoke_tool (bool, optional): Flag indicating if tools should be invoked.
+            return_form (bool, optional): Flag indicating if form should be returned.
+            strict (bool, optional): Flag indicating if strict validation should be applied.
+            rulebook (Rulebook, optional): Rulebook instance for validation.
+            imodel (iModel, optional): Model instance.
+            clear_messages (bool, optional): Flag indicating if messages should be cleared.
+            use_annotation (bool, optional): Flag indicating if annotations should be used.
+            return_branch (bool, optional): Flag indicating if branch should be returned.
+            kwargs: Additional keyword arguments.
+
+        Returns:
+            Any: The processed response.
+        """
+        kwargs = {**retry_kwargs, **kwargs}
+        return await rcall(
+            self._chat,
+            instruction=instruction,
+            context=context,
+            system=system,
+            sender=sender,
+            recipient=recipient,
+            branch=branch,
+            requested_fields=requested_fields,
+            form=form,
+            tools=tools,
+            invoke_tool=invoke_tool,
+            return_form=return_form,
+            strict=strict,
+            rulebook=rulebook,
+            imodel=imodel,
+            clear_messages=clear_messages,
+            use_annotation=use_annotation,
+            return_branch=return_branch,
+            **kwargs,
+        )
+
+    async def direct(
+        self,
+        instruction=None,
+        *,
+        context=None,
+        form=None,
+        branch=None,
+        tools=None,
+        return_branch=False,
+        reason: bool = False,
+        predict: bool = False,
+        score=None,
+        select=None,
+        plan=None,
+        allow_action: bool = False,
+        allow_extension: bool = False,
+        max_extension: int = None,
+        confidence=None,
+        score_num_digits=None,
+        score_range=None,
+        select_choices=None,
+        plan_num_step=None,
+        predict_num_sentences=None,
+        directive: str = None,
+        verbose=None,
+        **kwargs,
+    ):
+        """
+        Asynchronously directs the operation based on the provided parameters.
+
+        Args:
+            instruction (str, optional): Instruction message.
+            context (str, optional): Context message.
+            form (Form, optional): Form data.
+            branch (Branch, optional): Branch instance.
+            tools (Any, optional): Tools to be used.
+            return_branch (bool, optional): Flag indicating if branch should be returned.
+            reason (bool, optional): Flag indicating if reason should be included.
+            predict (bool, optional): Flag indicating if prediction should be included.
+            score (Any, optional): Score parameters.
+            select (Any, optional): Select parameters.
+            plan (Any, optional): Plan parameters.
+            allow_action (bool, optional): Flag indicating if action should be allowed.
+            allow_extension (bool, optional): Flag indicating if extension should be allowed.
+            max_extension (int, optional): Maximum extension value.
+            confidence (Any, optional): Confidence parameters.
+            score_num_digits (int, optional): Number of digits for score.
+            score_range (tuple, optional): Range for score.
+            select_choices (list, optional): Choices for selection.
+            plan_num_step (int, optional): Number of steps for plan.
+            predict_num_sentences (int, optional): Number of sentences for prediction.
+            directive (str, optional): Directive for the operation.
+            kwargs: Additional keyword arguments.
+
+        Returns:
+            Any: The processed response.
+        """
+        kwargs = {**retry_kwargs, **kwargs}
+        verbose = verbose if verbose is not None else self.verbose
+
+        if not directive:
+
+            out = await rcall(
+                self._direct,
+                instruction=instruction,
+                context=context,
+                form=form,
+                branch=branch,
+                tools=tools,
+                return_branch=return_branch,
+                reason=reason,
+                predict=predict,
+                score=score,
+                select=select,
+                plan=plan,
+                allow_action=allow_action,
+                allow_extension=allow_extension,
+                max_extension=max_extension,
+                confidence=confidence,
+                score_num_digits=score_num_digits,
+                score_range=score_range,
+                select_choices=select_choices,
+                plan_num_step=plan_num_step,
+                predict_num_sentences=predict_num_sentences,
+                verbose=verbose,
+                **kwargs,
+            )
+
+            if verbose:
+                print(
+                    "\n--------------------------------------------------------------"
+                )
+                print(f"Directive successfully completed!")
+
+            return out
+
+        out = await rcall(
+            self._mono_direct,
+            directive=directive,
+            instruction=instruction,
+            context=context,
+            branch=branch,
+            tools=tools,
+            verbose=verbose,
+            **kwargs,
+        )
+
+        if verbose:
+            print("--------------------------------------------------------------")
+            print(f"Directive successfully completed!")
+
+        return out
+
+    async def select(self, *args, **kwargs):
+        """
+        Asynchronously performs a select operation using the _select method with
+        retry logic.
+
+        Args:
+            *args: Positional arguments to pass to the _select method.
+            **kwargs: Keyword arguments to pass to the _select method, including
+                retry configurations.
+
+        Returns:
+            Any: The result of the select operation.
+        """
+        from .template.select import SelectTemplate
+
+        kwargs = {**retry_kwargs, **kwargs}
+        kwargs["template"] = kwargs.get("template", SelectTemplate)
+        return await rcall(self._select, *args, **kwargs)
+
+    async def predict(self, *args, **kwargs):
+        """
+        Asynchronously performs a predict operation using the _predict method with
+        retry logic.
+
+        Args:
+            *args: Positional arguments to pass to the _predict method.
+            **kwargs: Keyword arguments to pass to the _predict method, including
+                retry configurations.
+
+        Returns:
+            Any: The result of the predict operation.
+        """
+        from .template.predict import PredictTemplate
+
+        kwargs = {**retry_kwargs, **kwargs}
+        kwargs["template"] = kwargs.get("template", PredictTemplate)
+        return await rcall(self._predict, *args, **kwargs)
+
+    async def score(self, *args, **kwargs):
+        """
+        Asynchronously performs a score operation using the _score method with retry logic.
+
+        Args:
+            *args: Positional arguments to pass to the _score method.
+            **kwargs: Keyword arguments to pass to the _score method, including retry configurations.
+
+        Returns:
+            Any: The result of the score operation.
+        """
+        from .template.score import ScoreTemplate
+
+        kwargs = {**retry_kwargs, **kwargs}
+        kwargs["template"] = kwargs.get("template", ScoreTemplate)
+        return await rcall(self._score, *args, **kwargs)
+
+    async def plan(self, *args, **kwargs):
+        """
+        Asynchronously performs a plan operation using the _plan method with retry logic.
+
+        Args:
+            *args: Positional arguments to pass to the _plan method.
+            **kwargs: Keyword arguments to pass to the _plan method, including retry configurations.
+
+        Returns:
+            Any: The result of the plan operation.
+        """
+        from .template.plan import PlanTemplate
+
+        kwargs = {**retry_kwargs, **kwargs}
+        kwargs["template"] = kwargs.get("template", PlanTemplate)
+        return await rcall(self._plan, *args, **kwargs)
+
+    async def _mono_direct(
+        self,
+        directive: str,  # examples, "chat", "predict", "act"
+        instruction=None,  # additional instruction
+        context=None,  # context to perform the instruction on
+        system=None,  # optionally swap system message
+        branch=None,
+        tools=None,
+        template=None,
+        verbose=None,
+        **kwargs,
+    ):
+        """
+        Asynchronously performs a single direct operation.
+
+        Args:
+            directive (str): The directive for the operation.
+            instruction (str, optional): Additional instruction.
+            context (str, optional): Context for the operation.
+            system (str, optional): System message.
+            branch (Branch, optional): Branch instance.
+            tools (Any, optional): Tools to be used.
+            template (Any, optional): Template for the operation.
+            kwargs: Additional keyword arguments.
+
+        Returns:
+            Any: The result of the direct operation.
+        """
+
+        if template:
+            kwargs["template"] = template
+
+        kwargs = {**retry_kwargs, **kwargs}
+        branch = branch or self.branch
+
+        if system:
+            branch.add_message(system=system)
+
+        if hasattr(self, strip_lower(directive)):
+            directive = getattr(self, strip_lower(directive))
+
+            verbose = verbose if verbose is not None else self.verbose
+            if verbose:
+                print(f"Performing directive: {directive}...")
+
+            return await directive(
+                context=context,
+                instruction=instruction,
+                tools=tools,
+                **kwargs,
+            )
+
+        raise ValueError(f"invalid directive: {directive}")