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

lionagi/protocols/operatives/prompts.py

@@ -0,0 +1,232 @@
+from pydantic import JsonValue
+
+function_field_description = (
+    "Specify the name of the function to execute. **Choose "
+    "from the provided `tool_schemas`; do not invent function names.**"
+    "Only provide function names if tool_schemas are provided. Otherwise, "
+    "must leave blank or set to None."
+)
+
+arguments_field_description = (
+    "Provide the arguments to pass to the function as a "
+    "dictionary. **Use argument names and types as specified in the "
+    "`tool_schemas`; do not invent argument names.**"
+)
+
+action_required_field_description = (
+    "Specify whether the step requires actions to be "
+    "performed. If **True**, the actions in `action_requests` "
+    "must be performed. If **False**, the actions in "
+    "`action_requests` are optional. If no tool_schemas"
+    " are provided, this field is ignored."
+)
+
+action_requests_field_description = (
+    "List of actions to be performed if `action_required` "
+    "is **True**. Leave empty if no action is required. "
+    "**When providing actions, you must choose from the "
+    "provided `tool_schemas`. Do not invent function or "
+    "argument names.**"
+)
+
+confidence_description = (
+    "Provide an objective numeric confidence score between 0 and 1 (with 3 "
+    "decimal places) indicating how likely you successfully achieved the task"
+    " according to user expectation. Interpret the score as:\n"
+    "- **1**: Very confident in a good job.\n"
+    "- **0**: Not confident at all.\n"
+    "- **[0.8, 1]**: You can continue the path of reasoning if needed.\n"
+    "- **[0.5, 0.8)**: Recheck your reasoning and consider reverting to a "
+    "previous, more confident reasoning path.\n"
+    "- **[0, 0.5)**: Stop because the reasoning is starting to be off track."
+)
+
+instruction_field_description = (
+    "Define the core task or instruction to be executed. Your instruction should:\n\n"
+    "1. Be specific and actionable\n"
+    "2. Clearly state the expected outcome\n"
+    "3. Include any critical constraints or requirements\n\n"
+    "**Guidelines for writing effective instructions:**\n"
+    "- Start with a clear action verb (e.g., analyze, create, evaluate)\n"
+    "- Specify the scope and boundaries of the task\n"
+    "- Include success criteria when applicable\n"
+    "- Break complex tasks into distinct steps\n\n"
+    "**Examples:**\n"
+    "- 'Analyze the provided sales data and identify top 3 performing products'\n"
+    "- 'Generate a Python function that validates email addresses'\n"
+    "- 'Create a data visualization showing monthly revenue trends'"
+)
+
+guidance_field_description = (
+    "Provide strategic direction and constraints for task execution.\n\n"
+    "**Key components to include:**\n"
+    "1. Methodological preferences\n"
+    "2. Quality standards and requirements\n"
+    "3. Specific limitations or boundaries\n"
+    "4. Performance expectations\n\n"
+    "**Best practices:**\n"
+    "- Be explicit about any assumptions that should be made\n"
+    "- Specify preferred approaches or techniques\n"
+    "- Detail any constraints on resources or methods\n"
+    "- Include relevant standards or compliance requirements\n\n"
+    "Leave as None if no specific guidance is needed beyond the instruction."
+)
+
+context_field_description = (
+    "Supply essential background information and current state data required for "
+    "task execution.\n\n"
+    "**Include relevant details about:**\n"
+    "1. Environmental conditions\n"
+    "2. Historical context\n"
+    "3. Related systems or processes\n"
+    "4. Previous outcomes or decisions\n\n"
+    "**Context should:**\n"
+    "- Be directly relevant to the task\n"
+    "- Provide necessary background without excess detail\n"
+    "- Include any dependencies or prerequisites\n"
+    "- Specify the current state of the system\n\n"
+    "Set to None if no additional context is required."
+)
+
+reason_field_description = (
+    "Control whether detailed reasoning should be included in the response.\n\n"
+    "**When set to True:**\n"
+    "- Must include a ReasonModel explaining decision rationale\n"
+    "- Should detail key decision points\n"
+    "- Must provide confidence scores for decisions\n"
+    "- Should explain trade-offs considered\n\n"
+    "**When set to False:**\n"
+    "- Skip detailed reasoning\n"
+    "- Focus on direct results\n"
+    "- Omit confidence scoring\n\n"
+    "Set to None to make reasoning optional based on context."
+)
+
+actions_field_description = (
+    "Specify whether concrete actions should be taken as part of task execution.\n\n"
+    "**When set to True:**\n"
+    "- Must include appropriate ActionRequestModels\n"
+    "- Actions should directly relate to task goals\n"
+    "- Each action must be properly structured and validated\n"
+    "- Actions must use available tool schemas\n\n"
+    "**When set to False:**\n"
+    "- No actions should be included\n"
+    "- Focus on analysis and recommendations\n\n"
+    "Set to None to make actions optional based on requirements."
+)
+
+# Example structures for each field to demonstrate proper formatting
+instruction_examples: list[JsonValue] = [
+    "Analyze the dataset 'sales_2023.csv' and identify revenue trends",
+    "Create a Python function to process customer feedback data",
+    {
+        "task": "data_analysis",
+        "target": "sales_performance",
+        "scope": ["revenue", "growth", "seasonality"],
+    },
+]
+
+guidance_examples: list[JsonValue] = [
+    "Use statistical methods for trend analysis",
+    "Optimize for readability and maintainability",
+    {
+        "methods": ["regression", "time_series"],
+        "constraints": {"memory": "2GB", "time": "5min"},
+    },
+]
+
+context_examples: list[JsonValue] = [
+    "Previous analysis showed seasonal patterns",
+    {
+        "prior_results": {"accuracy": 0.95},
+        "system_state": "production",
+        "dependencies": ["numpy", "pandas"],
+    },
+]
+
+"""Field description for InstructModel."""
+
+instruct_model_description = (
+    "Generate structured instructions for task execution.\n\n"
+    "**Key Components:**\n"
+    "1. Task Definition: Clear description of what needs to be accomplished\n"
+    "2. Execution Parameters: How the task should be performed\n"
+    "3. Success Criteria: What constitutes successful completion\n"
+    "4. Scope and Boundaries: Limits and constraints of the task\n\n"
+    "**Structure Guidelines:**\n"
+    "- `instruction`: Core task or objective to accomplish\n"
+    "- `guidance`: Parameters, preferences, and constraints\n"
+    "- `context`: Relevant background and environmental information\n"
+    "- `reason`: Whether to include reasoning in output\n"
+    "- `actions`: Whether specific actions are required\n\n"
+    "**Best Practices:**\n"
+    "- Keep instructions clear and specific\n"
+    "- Provide necessary but not excessive detail\n"
+    "- Define measurable outcomes\n"
+    "- Include relevant dependencies\n"
+    "- Specify critical constraints\n\n"
+    "**Common Issues to Avoid:**\n"
+    "- Vague or ambiguous directives\n"
+    "- Missing essential context\n"
+    "- Undefined success criteria\n"
+    "- Incomplete requirements\n"
+    "- Conflicting parameters\n\n"
+    "Structure instructions to enable successful task execution while maintaining "
+    "appropriate flexibility for implementation details."
+)
+
+instruct_model_examples = [
+    {
+        "instruction": "Process the input data according to specified requirements",
+        "guidance": {
+            "requirements": ["validation", "transformation", "aggregation"],
+            "output_format": "structured_report",
+            "quality_metrics": ["accuracy", "completeness"],
+        },
+        "context": {
+            "input_source": "data_stream",
+            "domain": "general",
+            "priority": "standard",
+        },
+        "reason": True,
+        "actions": True,
+    },
+    {
+        "instruction": "Evaluate system performance against baseline metrics",
+        "guidance": {
+            "evaluation_criteria": [
+                "response_time",
+                "resource_usage",
+                "error_rate",
+            ],
+            "methodology": "standard",
+            "reporting": "detailed",
+        },
+        "context": {
+            "environment": "test",
+            "criticality": "medium",
+            "constraints": {"time": "bounded"},
+        },
+        "reason": True,
+        "actions": False,
+    },
+]
+
+
+__all__ = [
+    "function_field_description",
+    "arguments_field_description",
+    "action_required_field_description",
+    "action_requests_field_description",
+    "confidence_description",
+    "instruction_field_description",
+    "guidance_field_description",
+    "context_field_description",
+    "reason_field_description",
+    "actions_field_description",
+    "instruction_examples",
+    "guidance_examples",
+    "context_examples",
+    "instruct_model_description",
+    "instruct_model_examples",
+]

lionagi/protocols/operatives/reason.py

@@ -0,0 +1,56 @@
+from pydantic import BaseModel, field_validator
+
+from lionagi.core.models import FieldModel
+from lionagi.libs.parse import to_num
+
+from .prompts import confidence_description
+
+
+def validate_confidence_score(cls, value) -> float:
+    try:
+        return to_num(
+            value,
+            upper_bound=1,
+            lower_bound=0,
+            num_type=float,
+            precision=3,
+        )
+    except Exception:
+        return -1
+
+
+CONFIDENCE_SCORE_FIELD = FieldModel(
+    name="confidence_score",
+    annotation=float | None,
+    default=None,
+    title="Confidence Score",
+    description=confidence_description,
+    examples=[0.821, 0.257, 0.923, 0.439],
+    validator=validate_confidence_score,
+    validator_kwargs={"mode": "before"},
+)
+
+
+class ReasonModel(BaseModel):
+
+    title: str | None = None
+    content: str | None = None
+    confidence_score: float | None = CONFIDENCE_SCORE_FIELD.field_info
+
+    @field_validator(
+        "confidence_score", **CONFIDENCE_SCORE_FIELD.validator_kwargs
+    )
+    def _validate_confidence(cls, v):
+        return CONFIDENCE_SCORE_FIELD.validator(cls, v)
+
+
+REASON_FIELD = FieldModel(
+    name="reason",
+    annotation=ReasonModel | None,
+    default=None,
+    title="Reason",
+    description="**Provide a concise reason for the decision made.**",
+)
+
+
+__all__ = ["ReasonModel"]

lionagi/protocols/operatives/step.py

@@ -0,0 +1,217 @@
+"""
+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 pydantic import BaseModel
+from pydantic.fields import FieldInfo
+
+from lionagi.core.typing import FieldModel, NewModelParams
+from lionagi.protocols.operatives.operative import Operative
+
+from .action import (
+    ACTION_REQUESTS_FIELD,
+    ACTION_REQUIRED_FIELD,
+    ACTION_RESPONSES_FIELD,
+    ActionRequestModel,
+    ActionResponseModel,
+)
+from .reason import REASON_FIELD, ReasonModel
+
+
+class StepModel(BaseModel):
+    """Model representing a single operational step with optional reasoning and actions."""
+
+    title: str
+    description: str
+    reason: ReasonModel | None = REASON_FIELD.field_info
+    action_requests: list[ActionRequestModel] = (
+        ACTION_REQUESTS_FIELD.field_info
+    )
+    action_required: bool = ACTION_REQUIRED_FIELD.field_info
+    action_responses: list[ActionResponseModel] = (
+        ACTION_RESPONSES_FIELD.field_info
+    )
+
+
+class Step:
+    """Utility class providing methods to create and manage Operative instances for steps."""
+
+    @staticmethod
+    def request_operative(
+        *,
+        operative_name: str | None = None,
+        reason: bool = False,
+        actions: bool = False,
+        request_params: NewModelParams | None = None,
+        parameter_fields: dict[str, FieldInfo] | None = None,
+        base_type: type[BaseModel] | None = None,
+        field_models: list[FieldModel] | None = None,
+        exclude_fields: list[str] | None = None,
+        new_model_name: str | None = None,
+        field_descriptions: dict[str, str] | None = None,
+        inherit_base: bool = True,
+        config_dict: dict | None = None,
+        doc: str | None = None,
+        frozen: bool = False,
+    ) -> Operative:
+        """Creates an Operative instance configured for request handling.
+
+        Args:
+            operative_name (str, optional): Name of the operative.
+            reason (bool, optional): Whether to include reason field.
+            actions (bool, optional): Whether to include action fields.
+            request_params (NewModelParams, optional): Parameters for the new model.
+            parameter_fields (dict[str, FieldInfo], optional): Parameter fields for the model.
+            base_type (type[BaseModel], optional): Base type for the model.
+            field_models (list[FieldModel], optional): List of field models.
+            exclude_fields (list[str], optional): List of fields to exclude.
+            new_model_name (str | None, optional): Name of the new model.
+            field_descriptions (dict[str, str], optional): Descriptions for the fields.
+            inherit_base (bool, optional): Whether to inherit base.
+            config_dict (dict | None, optional): Configuration dictionary.
+            doc (str | None, optional): Documentation string.
+            frozen (bool, optional): Whether the model is frozen.
+
+        Returns:
+            Operative: The configured operative instance.
+        """
+
+        field_models = field_models or []
+        exclude_fields = exclude_fields or []
+        field_descriptions = field_descriptions or {}
+        if reason:
+            field_models.append(REASON_FIELD)
+        if actions:
+            field_models.extend(
+                [
+                    ACTION_REQUESTS_FIELD,
+                    ACTION_REQUIRED_FIELD,
+                ]
+            )
+        request_params = request_params or NewModelParams(
+            parameter_fields=parameter_fields,
+            base_type=base_type,
+            field_models=field_models,
+            exclude_fields=exclude_fields,
+            name=new_model_name,
+            field_descriptions=field_descriptions,
+            inherit_base=inherit_base,
+            config_dict=config_dict,
+            doc=doc,
+            frozen=frozen,
+        )
+        return Operative(name=operative_name, request_params=request_params)
+
+    @staticmethod
+    def respond_operative(
+        *,
+        operative: Operative,
+        additional_data: dict | None = None,
+        response_params: NewModelParams | None = None,
+        field_models: list[FieldModel] | None = None,
+        frozen_response: bool = False,
+        response_config_dict: dict | None = None,
+        response_doc: str | None = None,
+        exclude_fields: list[str] | None = None,
+    ) -> Operative:
+        """Updates the operative with response parameters and data.
+
+        Args:
+            operative (Operative): The operative instance to update.
+            additional_data (dict | None, optional): Additional data to include in the response.
+            response_params (NewModelParams | None, optional): Parameters for the response model.
+            field_models (list[FieldModel] | None, optional): List of field models.
+            frozen_response (bool, optional): Whether the response model is frozen.
+            response_config_dict (dict | None, optional): Configuration dictionary for the response.
+            response_doc (str | None, optional): Documentation string for the response.
+            exclude_fields (list[str] | None, optional): List of fields to exclude.
+
+        Returns:
+            Operative: The updated operative instance.
+        """
+
+        additional_data = additional_data or {}
+        field_models = field_models or []
+        operative = Step._create_response_type(
+            operative=operative,
+            response_params=response_params,
+            field_models=field_models,
+            frozen_response=frozen_response,
+            response_config_dict=response_config_dict,
+            response_doc=response_doc,
+            exclude_fields=exclude_fields,
+        )
+
+        data = operative.response_model.model_dump()
+        data.update(additional_data or {})
+        operative.response_model = operative.response_type.model_validate(data)
+        return operative
+
+    @staticmethod
+    def _create_response_type(
+        operative: Operative,
+        response_params: NewModelParams | None = None,
+        response_validators: dict | None = None,
+        frozen_response: bool = False,
+        response_config_dict: dict | None = None,
+        response_doc: str | None = None,
+        field_models: list[FieldModel] | None = None,
+        exclude_fields: list[str] | None = None,
+    ) -> Operative:
+        """Internal method to create a response type for the operative.
+
+        Args:
+            operative (Operative): The operative instance.
+            response_params (NewModelParams | None, optional): Parameters for the response model.
+            response_validators (dict | None, optional): Validators for the response model.
+            frozen_response (bool, optional): Whether the response model is frozen.
+            response_config_dict (dict | None, optional): Configuration dictionary for the response.
+            response_doc (str | None, optional): Documentation string for the response.
+            field_models (list[FieldModel] | None, optional): List of field models.
+            exclude_fields (list[str] | None, optional): List of fields to exclude.
+
+        Returns:
+            Operative: The operative instance with updated response type.
+        """
+
+        field_models = field_models or []
+
+        if (
+            hasattr(operative.request_type, "action_required")
+            and operative.response_model.action_required
+        ):
+            field_models.extend(
+                [
+                    ACTION_RESPONSES_FIELD,
+                    ACTION_REQUIRED_FIELD,
+                    ACTION_REQUESTS_FIELD,
+                ]
+            )
+        if hasattr(operative.request_type, "reason"):
+            field_models.extend([REASON_FIELD])
+
+        exclude_fields = exclude_fields or []
+        exclude_fields.extend(operative.request_params.exclude_fields)
+
+        operative.create_response_type(
+            response_params=response_params,
+            field_models=field_models,
+            exclude_fields=exclude_fields,
+            doc=response_doc,
+            config_dict=response_config_dict,
+            frozen=frozen_response,
+            validators=response_validators,
+        )
+        return operative

lionagi/protocols/registries/_component_registry.py

@@ -0,0 +1,19 @@
+from lionagi.protocols.adapters.adapter import AdapterRegistry
+from lionagi.protocols.adapters.json_adapter import (
+    JsonAdapter,
+    JsonFileAdapter,
+)
+from lionagi.protocols.adapters.pandas_adapter import PandasSeriesAdapter
+
+ADAPTERS = [
+    JsonAdapter,
+    JsonFileAdapter,
+    PandasSeriesAdapter,
+]
+
+
+class ComponentAdapterRegistry(AdapterRegistry):
+    _adapters = {k.obj_key: k() for k in ADAPTERS}
+
+
+__all__ = ["ComponentAdapterRegistry"]

lionagi/protocols/registries/_pile_registry.py

@@ -0,0 +1,26 @@
+from lionagi.protocols.adapters.adapter import AdapterRegistry
+from lionagi.protocols.adapters.json_adapter import (
+    JsonAdapter,
+    JsonFileAdapter,
+)
+from lionagi.protocols.adapters.pandas_adapter import (
+    CSVFileAdapter,
+    ExcelFileAdapter,
+    PandasDataFrameAdapter,
+)
+
+ADAPTERS = [
+    JsonAdapter,
+    JsonFileAdapter,
+    PandasDataFrameAdapter,
+    CSVFileAdapter,
+    ExcelFileAdapter,
+]
+
+
+class PileAdapterRegistry(AdapterRegistry):
+
+    _adapters = {k.obj_key: k() for k in ADAPTERS}
+
+
+__all__ = ["PileAdapterRegistry"]

lionagi/service/__init__.py

@@ -0,0 +1,13 @@
+from .imodel import iModel
+from .rate_limiter import RateLimiter, RateLimitError
+from .service import Service, register_service
+from .service_util import invoke_retry
+
+__all__ = [
+    "Service",
+    "register_service",
+    "RateLimiter",
+    "RateLimitError",
+    "invoke_retry",
+    "iModel",
+]

lionagi/service/complete_request_info.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel, Field
+
+
+class CompleteRequestInfo(BaseModel):
+    timestamp: float = Field(description="HTTP response generated time")
+
+
+class CompleteRequestTokenInfo(CompleteRequestInfo):
+    token_usage: int = Field(
+        description="Number of tokens used in the request"
+    )

lionagi/service/imodel.py

@@ -0,0 +1,110 @@
+import warnings
+
+from lionagi.service.service import Service
+from lionagi.service.service_match_util import (
+    match_parameters,
+    match_service,
+    match_task_method,
+)
+
+
+class iModel:
+    def __init__(
+        self,
+        provider: str | Service,
+        task: str = "chat",
+        model: str = None,
+        api_key: str = None,
+        api_key_schema: str = None,
+        interval_tokens: int = None,
+        interval_requests: int = None,
+        **kwargs,
+    ):
+
+        if api_key is not None:
+            api_key = api_key
+        elif api_key_schema is not None:
+            api_key = api_key_schema
+
+        if api_key is None:
+            if isinstance(provider, str):
+                match provider:
+                    case "openai":
+                        api_key = "OPENAI_API_KEY"
+                    case "anthropic":
+                        api_key = "ANTHROPIC_API_KEY"
+                    case "grok":
+                        api_key = "GROK_API_KEY"
+                    case "perplexity":
+                        api_key = "PERPLEXITY_API_KEY"
+
+        if isinstance(provider, str):
+            self.service = match_service(provider, api_key=api_key, **kwargs)
+        elif isinstance(provider, Service):
+            self.service = provider
+            if api_key:
+                warnings.warn(
+                    "A Service instance was provided along with api key info."
+                    "The the separately provided api_key or api_key_schema will be ignored."
+                )
+        else:
+            raise ValueError(
+                "Invalid provider. Please provide a valid provider name or valid service object."
+            )
+
+        task_method_list = match_task_method(task, self.service)
+        if len(task_method_list) == 0:
+            raise ValueError(
+                "No matching task found. "
+                "Please refer to the service provider's API to provide a valid task."
+            )
+        if len(task_method_list) > 1:
+            raise ValueError(
+                f"Multiple possible tasks found. Please specify: {task_method_list}"
+            )
+        self.task = task_method_list[0]
+        task_method = getattr(self.service, task_method_list[0])
+        task_params = match_parameters(
+            task_method, model, interval_tokens, interval_requests
+        )
+        try:
+            self.request_model = task_method(**task_params)
+        except Exception as e:
+            raise ValueError(
+                f"{self.task} requires the following to be provided as input: {e}."
+            )
+
+        self.model = model
+        self.configs = kwargs
+
+        self.data_model = self.service.match_data_model(self.task)
+
+    def parse_to_data_model(self, **kwargs):
+        if kwargs.get("model") and self.model:
+            if kwargs.get("model") != self.model:
+                raise ValueError(
+                    f"Models are inconsistent. This iModel is for {self.model}"
+                )
+
+        output = {}
+        for invoke_param, data_model in self.data_model.items():
+            data_model_dict = {}
+            if "model" in data_model.model_fields:
+                data_model_dict["model"] = self.model
+            for key in self.configs:
+                if key in data_model.model_fields:
+                    data_model_dict[key] = self.configs[key]
+            for key in kwargs:
+                if key in data_model.model_fields:
+                    data_model_dict[key] = kwargs[key]
+            output[invoke_param] = data_model(**data_model_dict)
+        return output
+
+    async def invoke(self, **kwargs):
+        return await self.request_model.invoke(**kwargs)
+
+    def list_tasks(self):
+        return self.service.list_tasks()
+
+
+__all__ = ["iModel"]