lionagi 0.10.3__tar.gz → 0.10.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.10.3
+Version: 0.10.4
 Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>
 License:            Apache License

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

@@ -7,7 +7,7 @@ from .base import (
     Source,
     TextSnippet,
 )
-from .file import CodeFile, Documentation, File
+from .file import Documentation, File, Module, ResearchSummary
 from .instruct import Instruct, InstructResponse
 from .reason import Reason
 
@@ -21,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.3 → lionagi-0.10.4}/lionagi/fields/file.py

@@ -1,13 +1,17 @@
+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",
-    "CodeFile",
     "Documentation",
+    "ResearchSummary",
+    "Module",
 )
 
 
@@ -31,16 +35,6 @@ class File(HashableModel):
             "/absolute/path/to/my_file.txt",
         ],
     )
-    content: str | None = Field(
-        default=None,
-        description=(
-            "Paste or generate the full textual content of the file here. "
-            "For example, this might include plain text, Markdown, or any "
-            "other text format.\nExamples:\n"
-            "  - '# My Title\\nSome description...'\n"
-            "  - 'function greet() { return \"Hello\"; }'"
-        ),
-    )
     description: str | None = Field(
         default=None,
         description=(
@@ -60,16 +54,13 @@ class File(HashableModel):
             return str(value)
         return value
 
+    @abstractmethod
     def render_content(
         self,
         header: str | None = None,
         footer: str | None = None,
     ) -> str:
-        text = f"\n{header}\n\n" if header else ""
-        text += self.content if self.content else ""
-        if not footer:
-            return text
-        return text + f"\n\n{footer}\n"
+        pass
 
     def persist(
         self,
@@ -93,41 +84,6 @@ class File(HashableModel):
         return fp
 
 
-class CodeFile(File):
-    """
-    Represents a code file with an identifiable programming language. Inherits
-    from the generic File model but specializes for code-related content.
-    """
-
-    language: str | None = Field(
-        default=None,
-        description=(
-            "Indicate the programming language of this code file. "
-            "LLMs or humans can use this info to apply specific formatting or syntax analysis."
-        ),
-        examples=[
-            "python",
-            "json",
-            "typescript",
-            "html",
-            "css",
-            "java",
-            "cpp",
-        ],
-    )
-    content: str | None = Field(
-        default=None,
-        description=(
-            "Provide or generate the **full source code**. This should be the primary text content "
-            "of the code file, including all function/class definitions.\nNo md codeblock, only raw code"
-        ),
-        examples=[
-            'def my_function():\\n    print("Hello, world!")',
-            'export function greet(): string { return "Hello"; }',
-        ],
-    )
-
-
 class Documentation(File):
     """
     Represents a documentation file, typically Markdown-based, that includes
@@ -161,7 +117,7 @@ class Documentation(File):
         self,
         header: str | None = None,
         footer: str | None = None,
-        include_source: bool = False,
+        include_source: bool = True,
     ) -> str:
         """
         Renders the documentation content, optionally including citations for sources.
@@ -172,7 +128,104 @@ class Documentation(File):
             for source in self.sources:
                 footer += f"- [{source.title}]({source.url})\n"
                 footer += f"  - {source.note}\n" if source.note else ""
-        return super().render_content(header=header, footer=footer)
+        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.3 → 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

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.4/lionagi/version.py

@@ -0,0 +1 @@
+__version__ = "0.10.4"

{lionagi-0.10.3 → lionagi-0.10.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lionagi"
-version = "0.10.3"
+version = "0.10.4"
 description = "An Intelligence Operating System."
 authors = [
     { name = "HaiyangLi", email = "quantocean.li@gmail.com" },

{lionagi-0.10.3 → lionagi-0.10.4}/uv.lock

@@ -1165,7 +1165,7 @@ wheels = [
 
 [[package]]
 name = "lionagi"
-version = "0.10.3"
+version = "0.10.4"
 source = { editable = "." }
 dependencies = [
     { name = "aiocache" },

lionagi-0.10.3/lionagi/version.py

@@ -1 +0,0 @@
-__version__ = "0.10.3"