lionagi 0.18.0__py3-none-any.whl → 0.18.2__py3-none-any.whl

lionagi/fields/code.py

@@ -1,239 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from enum import Enum
-
-from pydantic import Field
-
-from lionagi.models import HashableModel
-
-__all__ = (
-    "ParameterKind",
-    "Parameter",
-    "Decorator",
-    "Import",
-    "Attribute",
-    "Function",
-    "Method",
-    "Class",
-    "Module",
-)
-
-
-class ParameterKind(str, Enum):
-    """
-    Distinguishes how a function/method parameter is used.
-    Primarily inspired by Python's param categories, but can be ignored by simpler languages.
-    Pay attention to the languege's own conventions for parameter handling.
-    """
-
-    POSITIONAL_ONLY = "positional_only"  # E.g. Python's '/'-based params
-    POSITIONAL_OR_KEYWORD = "positional_or_keyword"  # Default for many
-    VAR_POSITIONAL = "var_positional"  # *args-like
-    KEYWORD_ONLY = "keyword_only"  # Python's '*' marker
-    VAR_KEYWORD = "var_keyword"  # **kwargs-like
-
-
-class Parameter(HashableModel):
-    """
-    Represents one parameter in a function or method signature.
-    """
-
-    name: str = Field(
-        ...,
-        description="Exact identifier for the parameter (e.g., 'user_id', 'self', 'arg').",
-    )
-    type: str | None = Field(
-        default=None,
-        description=(
-            "Type annotation as a string (e.g., 'str', 'int', 'SomeClass'). None if untyped or not declared."
-        ),
-    )
-    default_value_repr: str | None = Field(
-        default=None,
-        description=(
-            "String representation of default value if present (e.g., 'None', '10', '\"hi\"'). "
-            "None if parameter is required with no default."
-        ),
-    )
-    kind: ParameterKind = Field(
-        default=ParameterKind.POSITIONAL_OR_KEYWORD,
-        description=(
-            "Parameter's calling convention category. 'positional_or_keyword' is typical if unspecified."
-        ),
-    )
-
-
-class Decorator(HashableModel):
-    """
-    A decorator or annotation attached to a function, class, or method.
-    Common in Python (@deco), Java (@Override), .NET ([Attribute]), etc.
-    """
-
-    name: str = Field(
-        ...,
-        description="Decorator/annotation name (e.g., '@staticmethod', '[ApiController]', '@Override').",
-    )
-    arguments_repr: list[str] | None = Field(
-        default=None,
-        description=(
-            "If this decorator/annotation is called with arguments, provide them as a list of string expressions "
-            "(e.g., `['\"/home\"', 'methods=[\"GET\"]']`). None if no arguments."
-        ),
-    )
-
-
-class Import(HashableModel):
-    """
-    Represents an import/using/include statement. Merges Python's 'import X' and 'from Y import Z' logic.
-    Other languages can interpret accordingly.
-    """
-
-    module: str | None = Field(
-        default=None,
-        description=(
-            "The module/package/namespace from which symbols are imported (e.g., 'os.path', 'java.util'). "
-            "None for a direct import statement like 'import X' if no sub-path is specified."
-        ),
-    )
-    name: str = Field(
-        ...,
-        description=(
-            "The symbol or module being imported (e.g., 'os', 'List', 'time', '*')."
-        ),
-    )
-    alias: str | None = Field(
-        default=None,
-        description="Alias name if used ('import X as Y'), else None.",
-    )
-    level: int = Field(
-        default=0,
-        description=(
-            "For Pythonic relative imports. Number of leading dots. 0 if absolute or not applicable."
-        ),
-    )
-
-
-class Attribute(HashableModel):
-    """
-    A variable/constant/field at class or module level. Possibly static/final, with an initial value.
-    """
-
-    name: str = Field(
-        ...,
-        description="Identifier for this attribute/field (e.g., 'MAX_CONNECTIONS', 'version').",
-    )
-    type: str | None = Field(
-        default=None,
-        description="String type annotation if declared. None if untyped.",
-    )
-    initial_value_repr: str | None = Field(
-        default=None,
-        description="String representation of any initial value (e.g., '100', 'true', 'None'). None if uninitialized.",
-    )
-    is_static: bool = Field(
-        default=False,
-        description="True if this is a static (class-level) attribute. Otherwise instance-level or module-level.",
-    )
-    is_final: bool = Field(
-        default=False,
-        description="True if this attribute/field is read-only/const/final after initialization.",
-    )
-    visibility: str | None = Field(
-        default=None,
-        description="Optional access modifier (e.g., 'public', 'private', 'protected'). None if default or not applicable.",
-    )
-
-
-class Function(HashableModel):
-    """
-    Represents a standalone function or procedure.
-    For methods (attached to classes), see 'Method' below.
-    """
-
-    name: str = Field(
-        ..., description="Function name identifier (e.g., 'process_data')."
-    )
-    parameters: list[Parameter] = Field(
-        default_factory=list,
-        description="Ordered list of Parameter objects for this function.",
-    )
-    return_type: str | None = Field(
-        default=None,
-        description="Return type string if declared. None if not declared or no explicit type.",
-    )
-    is_async: bool = Field(
-        default=False,
-        description="True if an 'async' function in languages that support it. Else False.",
-    )
-    docstring: str | None = Field(
-        default=None,
-        description="Documentation string or comment describing this function.",
-    )
-    decorators: list[Decorator] = Field(
-        default_factory=list,
-        description="List of decorators/annotations on this function (e.g., @staticmethod).",
-    )
-
-
-class Method(Function):
-    """
-    A function bound to a class, including potential method-specific flags (static, abstract, etc.).
-    Inherits fields from 'Function.'
-    """
-
-    is_static: bool = Field(
-        default=False,
-        description="True if method is static (no instance or 'self' needed).",
-    )
-    is_classmethod: bool = Field(
-        default=False,
-        description="True if method is recognized as a class method (receives class as first arg).",
-    )
-    is_abstract: bool = Field(
-        default=False,
-        description="True if the method is abstract (no concrete implementation).",
-    )
-    visibility: str | None = Field(
-        default=None,
-        description="Access level like 'public', 'private', etc., if relevant to the language.",
-    )
-
-
-class Class(HashableModel):
-    """
-    Represents a class, interface, or other composite type, with optional docstring, attributes, methods, etc.
-    """
-
-    name: str = Field(
-        ...,
-        description="Class/struct/interface name (e.g., 'UserRepository', 'MyDataClass').",
-    )
-    base_types: list[str] = Field(
-        default_factory=list,
-        description="List of parent classes or interfaces by name. Empty if none.",
-    )
-    is_abstract: bool = Field(
-        default=False,
-        description="True if this is an abstract class (cannot be instantiated directly).",
-    )
-    is_interface: bool = Field(
-        default=False,
-        description="True if this represents an interface definition rather than a concrete class.",
-    )
-    docstring: str | None = Field(
-        default=None,
-        description="Documentation for the class/interface, if any.",
-    )
-    decorators: list[Decorator] = Field(
-        default_factory=list,
-        description="Class-level decorators/annotations (e.g., @dataclass).",
-    )
-    attributes: list[Attribute] = Field(
-        default_factory=list,
-        description="Fields or properties declared at class level.",
-    )
-    methods: list[Method] = Field(
-        default_factory=list,
-        description="List of Method objects representing this class's methods.",
-    )

lionagi/fields/file.py

@@ -1,234 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from abc import abstractmethod
-from pathlib import Path
-
-from pydantic import Field, field_validator
-
-from .base import HashableModel, Source
-from .code import Class, Function, Import
-from .research import PotentialRisk, ResearchFinding
-
-__all__ = (
-    "File",
-    "Documentation",
-    "ResearchSummary",
-    "Module",
-)
-
-
-class File(HashableModel):
-    """
-    Represents a generic file with an optional name, content, and brief
-    description. Useful for capturing and validating metadata about any
-    kind of file within a project.
-    """
-
-    file_name: str | None = Field(
-        default=None,
-        description=(
-            "Provide the name of the file or its relative path in the "
-            "project. If an absolute path is given, it will be converted"
-            " to a string. "
-        ),
-        examples=[
-            "session.py",
-            "src/components/UserCard.tsx",
-            "/absolute/path/to/my_file.txt",
-        ],
-    )
-    description: str | None = Field(
-        default=None,
-        description=(
-            "Briefly explain the file's purpose or function within the "
-            "project. This can be a short summary describing why this "
-            "file is needed and/or what it does."
-        ),
-        examples=[
-            "Manages user session logic for the LionAGI framework.",
-            "Contains CSS styles for the navbar component.",
-        ],
-    )
-
-    @field_validator("file_name", mode="before")
-    def validate_file_name(cls, value):
-        if isinstance(value, Path):
-            return str(value)
-        return value
-
-    @abstractmethod
-    def render_content(
-        self,
-        header: str | None = None,
-        footer: str | None = None,
-    ) -> str:
-        pass
-
-    def persist(
-        self,
-        directory: Path | str,
-        overwrite: bool = True,
-        timestamp: bool = False,
-        random_hash_digits: int = None,
-        header: str | None = None,
-        footer: str | None = None,
-    ) -> Path:
-        from lionagi.utils import create_path
-
-        fp = create_path(
-            directory=directory,
-            filename=self.file_name,
-            file_exist_ok=overwrite,
-            timestamp=timestamp,
-            random_hash_digits=random_hash_digits,
-        )
-        fp.write_text(self.render_content(header=header, footer=footer))
-        return fp
-
-
-class Documentation(File):
-    """
-    Represents a documentation file, typically Markdown-based, that includes
-    a title and main content explaining or describing some aspect of the project.
-    """
-
-    title: str = Field(
-        default_factory=str,
-        description=(
-            "Specify the title of this documentation entry or page. "
-            "For instance, this might be the top-level heading in a Markdown file.\n"
-        ),
-        examples=["Getting Started", "API Reference: LionAGI Session Module"],
-    )
-    content: str = Field(
-        default_factory=str,
-        description=(
-            "Provide the primary Markdown (or similar) content for the documentation. "
-            "This can include headings, bullet points, tables, code snippets, etc.\n"
-        ),
-    )
-    sources: list[Source] | None = Field(
-        default=None,
-        description=(
-            "List of sources or references used to create this documentation. "
-            "Each source should include a title and URL to the original content."
-        ),
-    )
-
-    def render_content(
-        self,
-        header: str | None = None,
-        footer: str | None = None,
-        include_source: bool = True,
-    ) -> str:
-        """
-        Renders the documentation content, optionally including citations for sources.
-        """
-        footer = footer or ""
-        if include_source and self.sources:
-            footer = "\n\n## Sources\n"
-            for source in self.sources:
-                footer += f"- [{source.title}]({source.url})\n"
-                footer += f"  - {source.note}\n" if source.note else ""
-        return (header or "") + self.content + footer
-
-
-class ResearchSummary(Documentation):
-    """
-    Captures the final outcome of the deep research process.
-    """
-
-    scope: str | None = Field(
-        default=None,
-        description="Brief statement of what was investigated. E.g., 'Surveyed python-based ORMs.'",
-    )
-    main_takeaways: str = Field(
-        ...,
-        description="High-level summary of the most critical insights for the project.",
-    )
-    findings: list[ResearchFinding] = Field(
-        default_factory=list,
-        description="List of key facts or knowledge gained.",
-    )
-    risks: list[PotentialRisk] = Field(
-        default_factory=list,
-        description="Identified obstacles or concerns for the project.",
-    )
-
-    def render_content(
-        self,
-        header: str | None = None,
-        footer: str | None = None,
-    ) -> str:
-        """
-        Renders the documentation content, optionally including citations for sources.
-        """
-        content = self.model_dump(exclude_unset=True, exclude_none=True)
-
-        from lionagi.libs.schema.as_readable import as_readable
-
-        text = as_readable(content, md=True, format_curly=True)
-
-        footer = footer or ""
-        if self.sources:
-            footer = "\n\n## Sources\n"
-            for source in self.sources:
-                footer += f"- [{source.title}]({source.url})\n"
-                footer += f"  - {source.note}\n" if source.note else ""
-        return (header or "") + text + footer
-
-
-class Module(File):
-    """
-    Represents a single source file: docstring, imports, top-level functions, classes, etc.
-    """
-
-    name: str = Field(
-        ...,
-        description="Logical name for this file/module (e.g., 'utils', 'main', 'data_models').",
-    )
-    path: str | None = Field(
-        default=None,
-        description="Filesystem path if known (e.g., 'src/utils.py').",
-    )
-    docstring: str | None = Field(
-        default=None, description="File-level docstring or comments if any."
-    )
-    imports: list[Import] = Field(
-        default_factory=list,
-        description="All import statements / using directives / includes in this file.",
-    )
-    classes: list[Class] = Field(
-        default_factory=list,
-        description="All class or interface definitions in this file.",
-    )
-    functions: list[Function] = Field(
-        default_factory=list,
-        description="All top-level (non-class) functions in this file.",
-    )
-    variables: list = Field(
-        default_factory=list,
-        description="All top-level variables/constants in this file.",
-    )
-    language: str = Field(
-        default_factory=str,
-        description=(
-            "Indicate the programming language of this code file. e.g., 'python', 'typescript'. "
-            "LLMs or humans can use this info to apply specific formatting or syntax analysis."
-        ),
-    )
-
-    def render_content(
-        self,
-        header: str | None = None,
-        footer: str | None = None,
-    ) -> str:
-        """
-        Renders the documentation content, optionally including citations for sources.
-        """
-        text = self.model_dump_json(exclude_none=True, exclude_unset=True)
-        return header or "" + text + footer or ""
-
-
-# File: lionagi/fields/file.py

lionagi/fields/instruct.py

@@ -1,135 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Any, ClassVar, Literal
-
-from pydantic import Field, JsonValue, field_validator
-
-from lionagi.libs.validate.common_field_validators import (
-    validate_boolean_field,
-    validate_nullable_jsonvalue_field,
-)
-from lionagi.models import FieldModel, HashableModel
-
-__all__ = (
-    "Instruct",
-    "InstructResponse",
-)
-
-
-class Instruct(HashableModel):
-    """Model for defining instruction parameters and execution requirements.
-
-    Attributes:
-        instruction (JsonValue | None): The primary instruction.
-        guidance (JsonValue | None): Execution guidance.
-        context (JsonValue | None): Task context.
-    """
-
-    reserved_kwargs: ClassVar[list[str]] = [
-        "operative_model",
-        "field_models",
-        "operative",
-        "reason",
-        "actions",
-        "action_strategy",
-        "request_params",
-        "response_params",
-    ]
-    instruction: JsonValue | None = Field(
-        None,
-        title="Primary Instruction",
-        description=(
-            "A clear, actionable task definition. Specify:\n"
-            "1) The primary goal or objective\n"
-            "2) Key success criteria or constraints\n"
-            "\n"
-            "Guidelines:\n"
-            "- Start with a direct action verb (e.g., 'Analyze', 'Generate', 'Create')\n"
-            "- Include scope, boundaries, or constraints\n"
-            "- Provide success criteria if relevant\n"
-            "- For complex tasks, break them into logical steps"
-        ),
-    )
-    guidance: JsonValue | None = Field(
-        None,
-        title="Guidance",
-        description=(
-            "Strategic direction and constraints for executing the task. "
-            "Include:\n"
-            "1) Preferred methods or frameworks\n"
-            "2) Quality benchmarks (e.g., speed, clarity)\n"
-            "3) Resource or environmental constraints\n"
-            "4) Relevant compliance or standards\n"
-            "Use None if no special guidance."
-        ),
-    )
-    context: JsonValue | None = Field(
-        None,
-        description=(
-            "Background information and current-state data needed for the task. "
-            "Should be:\n"
-            "1) Directly relevant\n"
-            "2) Sufficient to perform the task\n"
-            "3) Free of extraneous detail\n"
-            "Include environment, prior outcomes, system states, or dependencies. "
-            "Use None if no additional context is needed."
-        ),
-    )
-    reason: bool | None = Field(
-        None,
-        description=(
-            "Include a thoughtful explanation of decisions, trade-offs, "
-            "and insights. Encourage deeper introspection on why certain "
-            "choices were made, potential alternatives, and how confidence "
-            "was shaped. If not needed, set to None."
-        ),
-    )
-    actions: bool | None = Field(
-        None,
-        description=(
-            "Controls execution mode. "
-            "True: Execute specified actions. "
-            "False: Analysis/recommendations only. "
-            "None: Contextual execution."
-        ),
-    )
-    action_strategy: Literal["sequential", "concurrent"] | None = Field(
-        None,
-        description="Action strategy to use for executing actions. Default "
-        "is 'concurrent'. Only provide for if actions are enabled.",
-    )
-
-    @field_validator("instruction", "guidance", "context", mode="before")
-    def _validate_instruction(cls, v):
-        return validate_nullable_jsonvalue_field(cls, v)
-
-    @field_validator("reason", "actions", mode="before")
-    def _validate_reason(cls, v):
-        return validate_boolean_field(cls, v)
-
-    @field_validator("action_strategy", mode="before")
-    def _validate_action_strategy(cls, v):
-        if v not in ["batch", "sequential", "concurrent"]:
-            return "concurrent"
-        return v
-
-
-class InstructResponse(HashableModel):
-    instruct: Instruct
-    response: Any | None = None
-
-
-INSTRUCT_FIELD = FieldModel(
-    name="instruct_model",
-    annotation=Instruct | None,
-    default=None,
-)
-
-LIST_INSTRUCT_FIELD_MODEL = FieldModel(
-    name="instruct_models",
-    annotation=list[Instruct] | None,
-    default=None,
-)
-
-# File: lionagi/fields/instruct.py

lionagi/fields/reason.py

@@ -1,55 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from pydantic import Field, field_validator
-
-from lionagi.libs.validate.to_num import to_num
-from lionagi.models import FieldModel, HashableModel
-
-__all__ = ("Reason",)
-
-
-class Reason(HashableModel):
-    title: str | None = None
-    content: str | None = None
-    confidence_score: float | None = Field(
-        None,
-        title="Confidence Score",
-        description=(
-            "Numeric confidence score (0.0 to 1.0, up to three decimals) indicating "
-            "how well you've met user expectations. Use this guide:\n"
-            "  • 1.0: Highly confident\n"
-            "  • 0.8-1.0: Reasonably sure\n"
-            "  • 0.5-0.8: Re-check, refine or backtrack\n"
-            "  • 0.0-0.5: Off track, stop"
-        ),
-    )
-
-    @field_validator("confidence_score", mode="before")
-    def _validate_confidence(cls, v):
-        return validate_confidence_score(cls, v)
-
-
-def validate_confidence_score(cls, v):
-    if v is None:
-        return None
-    try:
-        return to_num(
-            v,
-            upper_bound=1,
-            lower_bound=0,
-            num_type=float,
-            precision=3,
-        )
-    except Exception:
-        return -1
-
-
-REASON_FIELD = FieldModel(
-    name="reason",
-    annotation=Reason | None,
-    title="Reason",
-    description="**Provide a concise reason for the decision made.**",
-)
-
-# File: lionagi/fields/reason.py