lionagi 0.15.8__py3-none-any.whl → 0.15.11__py3-none-any.whl

lionagi/ln/_extract_json.py

@@ -0,0 +1,60 @@
+import re
+from typing import Any
+
+import orjson
+
+from ._fuzzy_json import fuzzy_json
+
+# Precompile the regex for extracting JSON code blocks
+_JSON_BLOCK_PATTERN = re.compile(r"```json\s*(.*?)\s*```", re.DOTALL)
+
+
+def extract_json(
+    input_data: str | list[str],
+    /,
+    *,
+    fuzzy_parse: bool = False,
+    return_one_if_single: bool = True,
+) -> dict[str, Any] | list[dict[str, Any]]:
+    """Extract and parse JSON content from a string or markdown code blocks.
+    Attempts direct JSON parsing first. If that fails, looks for JSON content
+    within markdown code blocks denoted by ```json.
+
+    Args:
+        input_data (str | list[str]): The input string or list of strings to parse.
+        fuzzy_parse (bool): If True, attempts fuzzy JSON parsing on failed attempts.
+        return_one_if_single (bool): If True and only one JSON object is found,
+            returns a dict instead of a list with one dict.
+    """
+
+    # If input_data is a list, join into a single string
+    if isinstance(input_data, list):
+        input_str = "\n".join(input_data)
+    else:
+        input_str = input_data
+
+    # 1. Try direct parsing
+    try:
+        if fuzzy_parse:
+            return fuzzy_json(input_str)
+        return orjson.loads(input_str)
+    except Exception:
+        pass
+
+    # 2. Attempt extracting JSON blocks from markdown
+    matches = _JSON_BLOCK_PATTERN.findall(input_str)
+    if not matches:
+        return []
+
+    # If only one match, return single dict; if multiple, return list of dicts
+    if return_one_if_single and len(matches) == 1:
+        data_str = matches[0]
+        if fuzzy_parse:
+            return fuzzy_json(data_str)
+        return orjson.loads(data_str)
+
+    # Multiple matches
+    if fuzzy_parse:
+        return [fuzzy_json(m) for m in matches]
+    else:
+        return [orjson.loads(m) for m in matches]

lionagi/ln/_fuzzy_json.py

@@ -0,0 +1,116 @@
+import contextlib
+import re
+from typing import Any
+
+import orjson
+
+
+def fuzzy_json(str_to_parse: str, /) -> dict[str, Any] | list[dict[str, Any]]:
+    """
+    Attempt to parse a JSON string, trying a few minimal "fuzzy" fixes if needed.
+
+    Steps:
+    1. Parse directly with json.loads.
+    2. Replace single quotes with double quotes, normalize spacing, and try again.
+    3. Attempt to fix unmatched brackets using fix_json_string.
+    4. If all fail, raise ValueError.
+
+    Args:
+        str_to_parse: The JSON string to parse
+
+    Returns:
+        Parsed JSON (dict or list of dicts)
+
+    Raises:
+        ValueError: If the string cannot be parsed as valid JSON
+        TypeError: If the input is not a string
+    """
+    _check_valid_str(str_to_parse)
+
+    # 1. Direct attempt
+    with contextlib.suppress(Exception):
+        return orjson.loads(str_to_parse)
+
+    # 2. Try cleaning: replace single quotes with double and normalize
+    cleaned = _clean_json_string(str_to_parse.replace("'", '"'))
+    with contextlib.suppress(Exception):
+        return orjson.loads(cleaned)
+
+    # 3. Try fixing brackets
+    fixed = fix_json_string(cleaned)
+    with contextlib.suppress(Exception):
+        return orjson.loads(fixed)
+
+    # If all attempts fail
+    raise ValueError("Invalid JSON string")
+
+
+def _check_valid_str(str_to_parse: str, /):
+    if not isinstance(str_to_parse, str):
+        raise TypeError("Input must be a string")
+    if not str_to_parse.strip():
+        raise ValueError("Input string is empty")
+
+
+def _clean_json_string(s: str) -> str:
+    """Basic normalization: replace unescaped single quotes, trim spaces, ensure keys are quoted."""
+    # Replace unescaped single quotes with double quotes
+    # '(?<!\\)'" means a single quote not preceded by a backslash
+    s = re.sub(r"(?<!\\)'", '"', s)
+    # Collapse multiple whitespaces
+    s = re.sub(r"\s+", " ", s)
+    # Ensure keys are quoted
+    # This attempts to find patterns like { key: value } and turn them into {"key": value}
+    s = re.sub(r'([{,])\s*([^"\s]+)\s*:', r'\1"\2":', s)
+    return s.strip()
+
+
+def fix_json_string(str_to_parse: str, /) -> str:
+    """Try to fix JSON string by ensuring brackets are matched properly."""
+    if not str_to_parse:
+        raise ValueError("Input string is empty")
+
+    brackets = {"{": "}", "[": "]"}
+    open_brackets = []
+    pos = 0
+    length = len(str_to_parse)
+
+    while pos < length:
+        char = str_to_parse[pos]
+
+        if char == "\\":
+            pos += 2  # Skip escaped chars
+            continue
+
+        if char == '"':
+            pos += 1
+            # skip string content
+            while pos < length:
+                if str_to_parse[pos] == "\\":
+                    pos += 2
+                    continue
+                if str_to_parse[pos] == '"':
+                    pos += 1
+                    break
+                pos += 1
+            continue
+
+        if char in brackets:
+            open_brackets.append(brackets[char])
+        elif char in brackets.values():
+            if not open_brackets:
+                # Extra closing bracket
+                # Better to raise error than guess
+                raise ValueError("Extra closing bracket found.")
+            if open_brackets[-1] != char:
+                # Mismatched bracket
+                raise ValueError("Mismatched brackets.")
+            open_brackets.pop()
+
+        pos += 1
+
+    # Add missing closing brackets if any
+    if open_brackets:
+        str_to_parse += "".join(reversed(open_brackets))
+
+    return str_to_parse

lionagi/ln/_json_dump.py

@@ -0,0 +1,75 @@
+import datetime as dt
+import decimal
+from collections.abc import Callable
+from pathlib import Path
+from uuid import UUID
+
+import orjson
+
+
+def _get_default_serializers():
+    return {
+        dt.datetime: lambda o: o.isoformat(),
+        Path: lambda o: str(o),
+        UUID: lambda o: str(o),
+        decimal.Decimal: lambda o: str(o),
+        set: lambda o: list(o),
+        frozenset: lambda o: list(o),
+    }
+
+
+def _get_default_serializer_order():
+    return [dt.datetime, Path, UUID, decimal.Decimal, set, frozenset]
+
+
+def get_orjson_default(
+    order: list[type] = None,
+    additional: dict[type, Callable] = None,
+    extend_default: bool = True,
+) -> Callable:
+    """get the default function for orjson.dumps
+    Args:
+        order: order of types to check. Defaults to None.
+        additional: additional serializers
+        extend_default: when order is provided, whether to extend the default order or replace it.
+    """
+    dict_ = _get_default_serializers()
+    dict_.update(additional or {})
+    order_ = _get_default_serializer_order()
+
+    if order:
+        if len(additional or {}) > 0 and extend_default:
+            order_.extend([k for k in order if k not in order_])
+        else:
+            order_ = list(order)
+    else:
+        if len(additional or {}) > 0:
+            order_.extend([k for k in additional.keys() if k not in order_])
+
+    def default(obj):
+        for t in order_:
+            if isinstance(obj, t) and t in dict_:
+                return dict_[t](obj)
+        raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+
+    return default
+
+
+DEFAULT_SERIALIZER = get_orjson_default()
+DEFAULT_SERIALIZER_OPTION = (
+    orjson.OPT_INDENT_2
+    | orjson.OPT_SORT_KEYS
+    | orjson.OPT_APPEND_NEWLINE
+    | orjson.OPT_SERIALIZE_DATACLASS
+)
+
+
+def json_dumps(d_, decode=True, /) -> str:
+    by_ = orjson.dumps(
+        d_,
+        default=DEFAULT_SERIALIZER,
+        option=DEFAULT_SERIALIZER_OPTION,
+    )
+    if decode:
+        return by_.decode("utf-8")
+    return by_

lionagi/ln/_models.py

@@ -70,7 +70,6 @@ class Params:
             _validate_strict(k)
 
     def default_kw(self) -> Any:
-
         # create a partial function with the current parameters
         dict_ = self.to_dict()
 

lionagi/models/field_model.py

@@ -16,7 +16,6 @@ from typing import Annotated, Any
 from typing_extensions import Self, override
 
 from .._errors import ValidationError
-from ..utils import UNDEFINED
 
 # Cache of valid Pydantic Field parameters
 _PYDANTIC_FIELD_PARAMS: set[str] | None = None
@@ -660,13 +659,16 @@ def to_dict(self) -> dict[str, Any]:
 
     # Convert metadata to dictionary
     for meta in self.metadata:
-        if meta.key not in ("nullable", "listable", "validator"):
+        if meta.key not in (
+            "nullable",
+            "listable",
+            "validator",
+            "name",
+            "validator_kwargs",
+            "annotation",
+        ):
             result[meta.key] = meta.value
 
-    # Add annotation if available
-    if hasattr(self, "annotation"):
-        result["annotation"] = self.base_type
-
     return result
 
 

lionagi/operations/__init__.py

@@ -8,6 +8,8 @@ from .flow import flow
 from .node import BranchOperations, Operation
 from .plan.plan import PlanOperation, plan
 
+Builder = OperationGraphBuilder
+
 __all__ = (
     "ExpansionStrategy",
     "OperationGraphBuilder",
@@ -19,4 +21,5 @@ __all__ = (
     "PlanOperation",
     "brainstorm",
     "BrainstormOperation",
+    "Builder",
 )

lionagi/operations/builder.py

@@ -453,6 +453,16 @@ def visualize_graph(
     figsize=(14, 10),
 ):
     """Visualization with improved layout for complex graphs."""
+    from lionagi.protocols.graph.graph import (
+        _MATPLIB_AVAILABLE,
+        _NETWORKX_AVAILABLE,
+    )
+
+    if _MATPLIB_AVAILABLE is not True:
+        raise _MATPLIB_AVAILABLE
+    if _NETWORKX_AVAILABLE is not True:
+        raise _NETWORKX_AVAILABLE
+
     import matplotlib.pyplot as plt
     import networkx as nx
     import numpy as np

lionagi/protocols/generic/element.py

@@ -4,11 +4,12 @@
 
 from __future__ import annotations
 
+import datetime as dt
 from collections.abc import Mapping, Sequence
-from datetime import datetime
-from typing import Any, Generic, TypeAlias, TypeVar
+from typing import Any, Generic, Literal, TypeAlias, TypeVar
 from uuid import UUID, uuid4
 
+import orjson
 from pydantic import (
     BaseModel,
     ConfigDict,
@@ -17,10 +18,11 @@ from pydantic import (
     field_validator,
 )
 
+from lionagi import ln
 from lionagi._class_registry import get_class
 from lionagi._errors import IDError
 from lionagi.settings import Settings
-from lionagi.utils import UNDEFINED, time, to_dict
+from lionagi.utils import import_module, time, to_dict
 
 from .._concepts import Collective, Observable, Ordering
 
@@ -29,6 +31,7 @@ __all__ = (
     "Element",
     "ID",
     "validate_order",
+    "DEFAULT_ELEMENT_SERIALIZER",
 )
 
 
@@ -173,15 +176,6 @@ class Element(BaseModel, Observable):
         If a `lion_class` field is present in `metadata`, it must match the
         fully qualified name of this class. Converts `metadata` to a dict
         if needed.
-
-        Args:
-            val (dict): The initial metadata value.
-
-        Returns:
-            dict: A valid dictionary of metadata.
-
-        Raises:
-            ValueError: If the metadata is invalid or has a class mismatch.
         """
         if not val:
             return {}
@@ -196,7 +190,7 @@ class Element(BaseModel, Observable):
         return val
 
     @field_validator("created_at", mode="before")
-    def _coerce_created_at(cls, val: float | datetime | None) -> float:
+    def _coerce_created_at(cls, val: float | dt.datetime | None) -> float:
         """Coerces `created_at` to a float-based timestamp.
 
         Args:
@@ -212,7 +206,7 @@ class Element(BaseModel, Observable):
             return time(tz=Settings.Config.TIMEZONE, type_="timestamp")
         if isinstance(val, float):
             return val
-        if isinstance(val, datetime):
+        if isinstance(val, dt.datetime):
             return val.timestamp()
         try:
             return float(val)  # type: ignore
@@ -245,33 +239,24 @@ class Element(BaseModel, Observable):
         return str(val)
 
     @property
-    def created_datetime(self) -> datetime:
+    def created_datetime(self) -> dt.datetime:
         """Returns the creation time as a datetime object.
 
         Returns:
             datetime: The creation time in UTC.
         """
-        return datetime.fromtimestamp(self.created_at)
+        return dt.datetime.fromtimestamp(self.created_at)
 
     def __eq__(self, other: Any) -> bool:
-        """Compares two Element instances by their ID.
-
-        Args:
-            other (Any): Another object for comparison.
-
-        Returns:
-            bool: True if both share the same ID, False otherwise.
-        """
+        """Compares two Element instances by their ID."""
         if not isinstance(other, Element):
-            return NotImplemented
+            raise NotImplementedError(
+                f"Cannot compare Element with {type(other)}"
+            )
         return self.id == other.id
 
     def __hash__(self) -> int:
-        """Returns a hash of this element's ID.
-
-        Returns:
-            int: The hash of the ID, making elements usable as dictionary keys.
-        """
+        """Returns a hash of this element's ID."""
         return hash(self.id)
 
     def __bool__(self) -> bool:
@@ -282,42 +267,37 @@ class Element(BaseModel, Observable):
     def class_name(cls, full: bool = False) -> str:
         """Returns this class's name.
 
-        Args:
-            full (bool):
-                If True, returns the fully qualified class name; otherwise,
-                returns only the class name.
-
-        Returns:
-            str: The class name or fully qualified name.
+        full (bool): If True, returns the fully qualified class name; otherwise,
+            returns only the class name.
         """
         if full:
             return str(cls).split("'")[1]
         return cls.__name__
 
-    def to_dict(self) -> dict:
-        """Converts this Element to a dictionary.
-
-        All fields are included except those set to `UNDEFINED`.
-
-        Returns:
-            dict: The dictionary representation of this Element.
-        """
+    def _to_dict(self) -> dict:
         dict_ = self.model_dump()
         dict_["metadata"].update({"lion_class": self.class_name(full=True)})
-        return {k: v for k, v in dict_.items() if v is not UNDEFINED}
+        return {k: v for k, v in dict_.items() if ln.not_sentinel(v)}
+
+    def to_dict(self, mode: Literal["python", "json"] = "python") -> dict:
+        """Converts this Element to a dictionary."""
+        if mode == "python":
+            return self._to_dict()
+        return orjson.loads(self.to_json(decode=False))
+
+    def as_jsonable(self) -> dict:
+        """Converts this Element to a JSON-serializable dictionary."""
+        return self.to_dict(mode="json")
 
     @classmethod
     def from_dict(cls, data: dict, /) -> Element:
         """Deserializes a dictionary into an Element or subclass of Element.
 
         If `lion_class` in `metadata` refers to a subclass, this method
-        attempts to create an instance of that subclass.
+        is polymorphic, it will attempt to create an instance of that subclass.
 
         Args:
             data (dict): A dictionary of field data.
-
-        Returns:
-            Element: An Element or a subclass instance loaded from `data`.
         """
         metadata = data.pop("metadata", {})
         if "lion_class" in metadata:
@@ -337,9 +317,6 @@ class Element(BaseModel, Observable):
                         return subcls_type.from_dict(data)
 
                 except Exception:
-                    # Fallback attempt: direct import if not in registry
-                    from lionagi.libs.package.imports import import_module
-
                     mod, imp = subcls.rsplit(".", 1)
                     subcls_type = import_module(mod, import_name=imp)
                     data["metadata"] = metadata
@@ -350,6 +327,32 @@ class Element(BaseModel, Observable):
         data["metadata"] = metadata
         return cls.model_validate(data)
 
+    def to_json(self, decode: bool = True) -> str:
+        """Converts this Element to a JSON string."""
+        dict_ = self._to_dict()
+        if decode:
+            return orjson.dumps(
+                dict_,
+                default=DEFAULT_ELEMENT_SERIALIZER,
+                option=ln.DEFAULT_SERIALIZER_OPTION,
+            ).decode()
+        return orjson.dumps(dict_, default=DEFAULT_ELEMENT_SERIALIZER)
+
+    def from_json(cls, json_str: str) -> Element:
+        """Deserializes a JSON string into an Element or subclass of Element."""
+        data = orjson.loads(json_str)
+        return cls.from_dict(data)
+
+
+DEFAULT_ELEMENT_SERIALIZER = ln.get_orjson_default(
+    order=[IDType, Element, BaseModel],
+    additional={
+        IDType: lambda o: str(o),
+        Element: lambda o: o.to_dict(),
+        BaseModel: lambda o: o.model_dump(mode="json"),
+    },
+)
+
 
 def validate_order(order: Any) -> list[IDType]:
     """Validates and flattens an ordering into a list of IDType objects.