lionagi 0.10.3__py3-none-any.whl → 0.10.5__py3-none-any.whl

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/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/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/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/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/libs/token_transform/symbolic_compress_context.py

@@ -111,7 +111,7 @@ async def symbolic_compress_context(
 
     elif text:
         chunks = chunk_content(
-            text=text,
+            text,
             chunk_by=chunk_by,
             chunk_size=chunk_size,
             overlap=overlap,

lionagi/version.py

@@ -1 +1 @@
-__version__ = "0.10.3"
+__version__ = "0.10.5"

{lionagi-0.10.3.dist-info → lionagi-0.10.5.dist-info}/METADATA

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

{lionagi-0.10.3.dist-info → lionagi-0.10.5.dist-info}/RECORD

@@ -4,7 +4,7 @@ lionagi/_errors.py,sha256=JlBTFJnRWtVYcRxKb7fWFiJHLbykl1E19mSJ8sXYVxg,455
 lionagi/_types.py,sha256=iDdYewsP9rDrM7QY19_NDTcWUk7swp8vnGCrloHMtUM,53
 lionagi/settings.py,sha256=W52mM34E6jXF3GyqCFzVREKZrmnUqtZm_BVDsUiDI_s,1627
 lionagi/utils.py,sha256=uLTJKl7aTnFXV6ehA6zwiwEB7G2nQYKsO2pZ6mqFzUk,78908
-lionagi/version.py,sha256=0C8KcY1dzs3hdkAre06v0NCQ0Uxcqv6g9a93bRcVLW0,23
+lionagi/version.py,sha256=c61d5YjslqtpItkzB2NGlURm177H2racruHXV9G6u6s,23
 lionagi/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lionagi/adapters/adapter.py,sha256=aW7s1OKAdxHd8HBv2UcThn-r2Q08EyArssNyFobMLuA,3357
 lionagi/adapters/json_adapter.py,sha256=EJj0Jev46ZhU3ZMnlYwyzN2rLxjLCVrMDpHkEuggBvk,4561
@@ -15,12 +15,14 @@ lionagi/adapters/pandas_/csv_adapter.py,sha256=HWie6Jlt8nR-EVJC_zmCFilaWszLNuk7E
 lionagi/adapters/pandas_/excel_adapter.py,sha256=ZqRT2xF93NLKNyMp16ePNzwUN3ntNkUy1dO3nbsrfak,2287
 lionagi/adapters/pandas_/pd_dataframe_adapter.py,sha256=ULGZVhK5aaOuTrmFq4x5SiuDScYetyYYUHeL8Hh13Eg,2279
 lionagi/adapters/pandas_/pd_series_adapter.py,sha256=TX3cqFtgEip8JqVqkjdJYOu4PQGpW1yYU6POhvz8Jeg,1388
-lionagi/fields/__init__.py,sha256=BrFzn3wOb9oCF_7iXH0b28-XwfZQNmee8sMDQD0HQBk,567
+lionagi/fields/__init__.py,sha256=8oU7Vfk-fKiULFKqhM6VpJMqdZcVXPTM7twVfNDN_SQ,603
 lionagi/fields/action.py,sha256=iWSApCM77jS0Oc28lb7G601Etkp-yjx5U1hfI_FQgfA,5792
 lionagi/fields/base.py,sha256=5CJc7j8kTTWzXwpYzkSAFzx4BglABfx3AElIATKB7bg,3857
-lionagi/fields/file.py,sha256=GkOxOtCTWjb4S0vwxLei6sNyONcbV8QRIMTyXkWwV1A,5601
+lionagi/fields/code.py,sha256=TFym51obzaSfCmeRoHZJyBtjfDI4tvl9F-1sjFc9rMw,7713
+lionagi/fields/file.py,sha256=DhQ_HE0RvTNzkvBGQHRgbMYSokDkzE8GEu814i6jw5Q,7297
 lionagi/fields/instruct.py,sha256=sMbCxEv0HQLa31JkJDmdrWWEzIfeKbcmN2hYOehz3Q0,4773
-lionagi/fields/reason.py,sha256=iNjgcIC2yWa0m0hkEZTCwKwknTkjVbhGLS2TWp6CE8s,1430
+lionagi/fields/reason.py,sha256=3Ksz9_40dI-oQ9VtmpnYAmJdeDDIO-TwLDrf1ijbXGM,1438
+lionagi/fields/research.py,sha256=2x6SFDwMSwzl4uHHUBbhT8mgwa49MsEy1NaUIb84MHU,1405
 lionagi/libs/__init__.py,sha256=5y5joOZzfFWERl75auAcNcKC3lImVJ5ZZGvvHZUFCJM,112
 lionagi/libs/parse.py,sha256=JRS3bql0InHJqATnAatl-hQv4N--XXw4P77JHhTFnrc,1011
 lionagi/libs/file/__init__.py,sha256=5y5joOZzfFWERl75auAcNcKC3lImVJ5ZZGvvHZUFCJM,112
@@ -55,7 +57,7 @@ lionagi/libs/token_transform/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NM
 lionagi/libs/token_transform/base.py,sha256=LBnaDgi4HNgaJJGwIzWcQjVMdu49i_93rRvOvMU22Rw,1545
 lionagi/libs/token_transform/llmlingua.py,sha256=DkeLUlrb7rGx3nZ04aADU9HXXu5mZTf_DBwT0xhzIv4,7
 lionagi/libs/token_transform/perplexity.py,sha256=tcVRjPBX3nuVqsoTkowCf6RBXuybO--owH1lf2Ywj1s,14470
-lionagi/libs/token_transform/symbolic_compress_context.py,sha256=Nr4vSJSN6sUQgaA1QxHhidWH3pUG_5RnoYeLHjMsoLA,4603
+lionagi/libs/token_transform/symbolic_compress_context.py,sha256=J8UleoCRDBvbFvmss2JjOvJfuBT7LXUW7AsRB-oQq7c,4598
 lionagi/libs/token_transform/synthlang.py,sha256=W6e-_265UXqVosM9X0TLKW53rNHvWCKhsWbVAop49Ac,259
 lionagi/libs/token_transform/types.py,sha256=4HgAfNDlJ_Hu18kLt59GHr_76eF3xLpNCTbOXlAYVlA,491
 lionagi/libs/token_transform/synthlang_/base.py,sha256=GDle72c8EjFz_3hg_k-y0YmksBsn5TSRVTw5_cwfWTo,4109
@@ -220,7 +222,7 @@ lionagi/tools/file/writer.py,sha256=5y5joOZzfFWERl75auAcNcKC3lImVJ5ZZGvvHZUFCJM,
 lionagi/tools/file/providers/__init__.py,sha256=5y5joOZzfFWERl75auAcNcKC3lImVJ5ZZGvvHZUFCJM,112
 lionagi/tools/file/providers/docling_.py,sha256=5y5joOZzfFWERl75auAcNcKC3lImVJ5ZZGvvHZUFCJM,112
 lionagi/tools/query/__init__.py,sha256=5y5joOZzfFWERl75auAcNcKC3lImVJ5ZZGvvHZUFCJM,112
-lionagi-0.10.3.dist-info/METADATA,sha256=NX6-ma5E2CK-UUTpfp6aZXUXuWHI2OukvBSRSUHjBzc,18464
-lionagi-0.10.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-lionagi-0.10.3.dist-info/licenses/LICENSE,sha256=VXFWsdoN5AAknBCgFqQNgPWYx7OPp-PFEP961zGdOjc,11288
-lionagi-0.10.3.dist-info/RECORD,,
+lionagi-0.10.5.dist-info/METADATA,sha256=X0dUpL8Dx7FOz_OdT_cGo3UZABgc7GE2SmywtibqEZs,18464
+lionagi-0.10.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lionagi-0.10.5.dist-info/licenses/LICENSE,sha256=VXFWsdoN5AAknBCgFqQNgPWYx7OPp-PFEP961zGdOjc,11288
+lionagi-0.10.5.dist-info/RECORD,,