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

lionagi/fields/base.py

@@ -1,153 +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, HttpUrl
-
-from lionagi.models import HashableModel
-
-__all__ = (
-    "Source",
-    "TextSnippet",
-    "CodeSnippet",
-    "Section",
-    "OutlineItem",
-    "Outline",
-)
-
-
-class Source(HashableModel):
-    """
-    Represents a citation or external source, such as:
-     - a website,
-     - documentation link,
-     - research paper,
-     - or any external resource.
-    """
-
-    title: str = Field(
-        ...,
-        description="Short label or title for the reference (e.g. 'Pydantic Docs', 'RFC 3986').",
-    )
-
-    url: str | HttpUrl | None = Field(
-        None,
-        description="Full URL or local path pointing to the resource. Must conform to standard URL format.",
-    )
-
-    note: str | None = Field(
-        default=None,
-        description=(
-            "Optional additional note explaining why this reference is relevant or what it contains."
-        ),
-    )
-
-
-class SnippetType(str, Enum):
-    TEXT = "text"
-    CODE = "code"
-
-
-class TextSnippet(HashableModel):
-    """
-    Specialized snippet for textual/prose content.
-    """
-
-    type: SnippetType = Field(
-        SnippetType.TEXT,
-        description=(
-            "Must be 'text' for textual snippets. Ensures explicit type distinction."
-        ),
-    )
-    content: str = Field(
-        ...,
-        description=(
-            "The actual text. Can be a paragraph, bullet list, or any narrative content."
-        ),
-    )
-
-
-class CodeSnippet(HashableModel):
-    """
-    Specialized snippet for source code or command-line examples.
-    """
-
-    type: SnippetType = Field(
-        SnippetType.CODE,
-        description=(
-            "Must be 'code' for code snippets. Allows separate handling or formatting."
-        ),
-    )
-    content: str = Field(
-        ...,
-        description=(
-            "The actual code or command sequence. Should be well-formatted so it can be rendered properly."
-        ),
-    )
-
-
-class Section(HashableModel):
-    """
-    A single section of a document or article. Each section has:
-     - A title
-     - A sequential list of content snippets (text or code),
-       which appear in the intended reading order.
-     - Optional sources specifically cited in this section.
-    """
-
-    title: str = Field(
-        ...,
-        description=(
-            "The section heading or label, e.g., 'Introduction', 'Implementation Steps'."
-        ),
-    )
-    snippets: list[TextSnippet | CodeSnippet] = Field(
-        default_factory=list,
-        description=(
-            "Ordered list of content snippets. Could be multiple text blocks, code examples, etc."
-        ),
-    )
-
-    sources: list[Source] = Field(
-        default_factory=list,
-        description=(
-            "References specifically cited in this section. "
-            "If sources are stored at the doc-level, this can be omitted."
-        ),
-    )
-
-
-class OutlineItem(HashableModel):
-    """
-    Represents a single outline item, which could become a full section later.
-    """
-
-    heading: str = Field(
-        ...,
-        description="Short name or label for this item, e.g., 'Chapter 1: Basics'.",
-    )
-    summary: str | None = Field(
-        default=None,
-        description=(
-            "A brief description of what this section will cover, if known."
-        ),
-    )
-
-
-class Outline(HashableModel):
-    """
-    A top-level outline for a document or article.
-    """
-
-    topic: str = Field(
-        ..., description="Working title or overarching topic of the document."
-    )
-    items: list[OutlineItem] = Field(
-        default_factory=list,
-        description="List of major outline points or sections planned.",
-    )
-    notes: str | None = Field(
-        default=None,
-        description="Any additional remarks, questions, or brainstorming notes for the outline.",
-    )

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