lionagi 0.10.2__tar.gz → 0.10.4__tar.gz

{lionagi-0.10.2 → lionagi-0.10.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.10.2
+Version: 0.10.4
 Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>
 License:            Apache License
@@ -221,11 +221,11 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: aiocache>=0.12.0
 Requires-Dist: aiohttp>=3.11.0
-Requires-Dist: jinja2>=3.1.0
+Requires-Dist: jinja2>=3.0.0
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: pydantic>=2.0.0
-Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: tiktoken>=0.8.0
 Requires-Dist: toml>=0.9.0
 Provides-Extra: llms

{lionagi-0.10.2 → lionagi-0.10.4}/lionagi/adapters/toml_adapter.py

@@ -141,7 +141,7 @@ class TomlFileAdapter(Adapter):
         dict | list[dict]
             The loaded data from file.
         """
-        with open(obj, "r", encoding="utf-8") as f:
+        with open(obj, encoding="utf-8") as f:
             result = toml.load(f, **kwargs)
 
         # Handle array of tables in TOML for "many" case

{lionagi-0.10.2 → lionagi-0.10.4}/lionagi/fields/__init__.py

@@ -1,7 +1,4 @@
-from .action import (
-    ActionRequestModel,
-    ActionResponseModel,
-)
+from .action import ActionRequestModel, ActionResponseModel
 from .base import (
     CodeSnippet,
     Outline,
@@ -10,11 +7,8 @@ from .base import (
     Source,
     TextSnippet,
 )
-from .file import CodeFile, Documentation, File
-from .instruct import (
-    Instruct,
-    InstructResponse,
-)
+from .file import Documentation, File, Module, ResearchSummary
+from .instruct import Instruct, InstructResponse
 from .reason import Reason
 
 __all__ = (
@@ -27,7 +21,8 @@ __all__ = (
     "OutlineItem",
     "Outline",
     "File",
-    "CodeFile",
+    "Module",
+    "ResearchSummary",
     "Documentation",
     "Instruct",
     "InstructResponse",

lionagi-0.10.4/lionagi/fields/code.py

@@ -0,0 +1,236 @@
+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-0.10.4/lionagi/fields/file.py

@@ -0,0 +1,231 @@
+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-0.10.2 → lionagi-0.10.4}/lionagi/fields/reason.py

@@ -2,15 +2,15 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import Field, field_validator
 
-from lionagi.models import FieldModel
+from lionagi.models import FieldModel, HashableModel
 from lionagi.utils import to_num
 
 __all__ = ("Reason",)
 
 
-class Reason(BaseModel):
+class Reason(HashableModel):
 
     title: str | None = None
     content: str | None = None
@@ -22,10 +22,9 @@ class Reason(BaseModel):
             "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 or refine\n"
-            "  • 0.0-0.5: Off track"
+            "  • 0.5-0.8: Re-check, refine or backtrack\n"
+            "  • 0.0-0.5: Off track, stop"
         ),
-        examples=[0.821, 0.257, 0.923, 0.439],
     )
 
     @field_validator("confidence_score", mode="before")

lionagi-0.10.4/lionagi/fields/research.py

@@ -0,0 +1,49 @@
+from pydantic import Field
+
+from lionagi.models import HashableModel
+
+from .base import CodeSnippet, TextSnippet
+
+__all__ = (
+    "ResearchFinding",
+    "PotentialRisk",
+    "ResearchSummary",
+)
+
+
+class ResearchFinding(HashableModel):
+    """
+    A single piece of information or insight from the research phase.
+    """
+
+    summary: str = Field(
+        ...,
+        description="Concise text describing the discovered fact, concept, or best practice.",
+    )
+    snippets: list[TextSnippet | CodeSnippet] = Field(
+        default_factory=list,
+        description="Ordered list of content snippets (text or code) that illustrate or support the finding.",
+    )
+    relevance: str | None = Field(
+        default=None,
+        description="Why this finding matters to the project. E.g., 'Helps solve concurrency issue.'",
+    )
+
+
+class PotentialRisk(HashableModel):
+    """
+    Identifies a risk or challenge discovered during research.
+    """
+
+    description: str = Field(
+        ...,
+        description="Short text describing the risk. E.g., 'Scalability concerns with chosen DB'.",
+    )
+    impact: str | None = Field(
+        default=None,
+        description="Possible consequences if not mitigated. E.g., 'System slowdown, possible downtime.'",
+    )
+    mitigation_ideas: str | None = Field(
+        default=None,
+        description="Preliminary ways to reduce or handle this risk.",
+    )

{lionagi-0.10.2 → lionagi-0.10.4}/lionagi/libs/token_transform/synthlang_/base.py

@@ -31,7 +31,7 @@ class SynthlangFramework(Resource):
         import json
 
         fp = here / FRAMEWORK_PATH / "framework_options.json"
-        with open(fp, "r", encoding="utf-8") as f:
+        with open(fp, encoding="utf-8") as f:
             return json.load(f)
 
     @classmethod

{lionagi-0.10.2 → lionagi-0.10.4}/lionagi/libs/token_transform/synthlang_/resources/frameworks/framework_options.json

@@ -49,4 +49,4 @@
             ]
         }
     }
-}
+}

{lionagi-0.10.2 → lionagi-0.10.4}/lionagi/libs/token_transform/synthlang_/resources/mapping/lion_emoji_mapping.toml

@@ -58,4 +58,4 @@ False = "⊭"
 "⧦⧦⧦" = "⧦"
 "  " = "◻︎"
 "◻︎◻︎" = "◼︎"
-"###" = "#"
+"###" = "#"

{lionagi-0.10.2 → lionagi-0.10.4}/lionagi/libs/token_transform/synthlang_/resources/mapping/python_math_mapping.toml

@@ -38,4 +38,4 @@ False = "⊭"
 "⧦⧦⧦" = "⧦"
 "  " = "◻︎"
 "◻︎◻︎" = "◼︎"
-"###" = "#"
+"###" = "#"

{lionagi-0.10.2 → lionagi-0.10.4}/lionagi/libs/token_transform/synthlang_/resources/mapping/rust_chinese_mapping.toml

@@ -57,4 +57,4 @@ self = "自"
 Clone = "隆"
 clone = "隆"
 derive = "衍"
-"println!" = "印"
+"println!" = "印"