krons 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

krons/utils/_pythonic_function_call.py

@@ -0,0 +1,249 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Function call parser with khive-mcp extensions for unified tool paradigm.
+
+Core parsing with support for:
+- Service namespacing: cognition.remember_episodic(...)
+- Batch parsing: [call1(...), call2(...)]
+- Reserved keyword handling: from= -> from_= (Python keywords as args)
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import Any
+
+# Python reserved keywords that might be used as field names
+# These get mapped to underscore versions for parsing
+RESERVED_KEYWORDS = {
+    "from",
+    "import",
+    "class",
+    "def",
+    "return",
+    "yield",
+    "async",
+    "await",
+}
+
+# Regex to match keyword arguments with reserved names
+# Matches: from="value" or from='value' at word boundary
+_RESERVED_KWARG_PATTERN = re.compile(
+    r"\b(" + "|".join(RESERVED_KEYWORDS) + r")\s*=", re.MULTILINE
+)
+
+__all__ = (
+    "parse_function_call",
+    "parse_batch_function_calls",
+)
+
+
+def _escape_reserved_keywords(call_str: str) -> str:
+    """Escape Python reserved keywords used as argument names.
+
+    Converts `from=` to `from_=` so ast.parse can handle it.
+    The underscore version is what Pydantic expects for aliased fields.
+
+    Args:
+        call_str: Function call string that may contain reserved keywords
+
+    Returns:
+        String with reserved keywords escaped
+    """
+    return _RESERVED_KWARG_PATTERN.sub(r"\1_=", call_str)
+
+
+def _ast_to_value(node: ast.AST) -> Any:
+    """Convert AST node to Python value with recursive dict/list processing.
+
+    Handles nested dicts, lists, tuples, and JSON-style literals (true/false/null).
+    Normalizes JSON literals: true->True, false->False, null->None.
+
+    Args:
+        node: AST node to convert
+
+    Returns:
+        Python value
+
+    Raises:
+        ValueError: If node cannot be converted to a value
+    """
+    # Handle JSON-style boolean/null names: true, false, null
+    if isinstance(node, ast.Name):
+        if node.id in ("true", "false", "null"):
+            return {"true": True, "false": False, "null": None}[node.id]
+        raise ValueError(f"Name '{node.id}' is not a valid literal")
+
+    # Handle dict nodes: {key1: val1, key2: val2, ...}
+    if isinstance(node, ast.Dict):
+        return {
+            _ast_to_value(k): _ast_to_value(v) for k, v in zip(node.keys, node.values)
+        }
+
+    # Handle list nodes: [elem1, elem2, ...]
+    if isinstance(node, ast.List):
+        return [_ast_to_value(elem) for elem in node.elts]
+
+    # Handle tuple nodes: (elem1, elem2, ...)
+    if isinstance(node, ast.Tuple):
+        return tuple(_ast_to_value(elem) for elem in node.elts)
+
+    # Handle simple literals (str, int, float, bool, None) via ast.literal_eval
+    try:
+        return ast.literal_eval(node)
+    except (ValueError, TypeError) as e:
+        raise ValueError(f"Cannot convert AST node: {type(node).__name__}") from e
+
+
+def parse_function_call(call_str: str) -> dict[str, Any]:
+    """Parse Python function call syntax into unified tool format.
+
+    Supports service namespacing for unified tool paradigm:
+        - Simple: search("query") -> {operation: "search", arguments: {...}}
+        - Namespaced: cognition.remember("...") -> {service: "cognition", ...}
+        - Deep: recall.search("...") -> {service: "recall", operation: "search", ...}
+
+    Examples:
+        >>> parse_function_call('search("AI news")')
+        {'operation': 'search', 'arguments': {'query': 'AI news'}}
+
+        >>> parse_function_call('cognition.remember_episodic(content="...")')
+        {'service': 'cognition', 'operation': 'remember_episodic', 'arguments': {'content': '...'}}
+
+    Args:
+        call_str: Python function call as string
+
+    Returns:
+        Dict with 'operation', optional 'service', and 'arguments' keys
+        Legacy 'tool' key also included for backward compatibility
+
+    Raises:
+        ValueError: If the string is not a valid function call
+    """
+    try:
+        # Escape reserved keywords before parsing (e.g., from= -> from_=)
+        escaped_str = _escape_reserved_keywords(call_str)
+
+        # Parse the call as a Python expression
+        tree = ast.parse(escaped_str, mode="eval")
+        call = tree.body
+
+        if not isinstance(call, ast.Call):
+            raise ValueError("Not a function call")
+
+        # Extract function name and service namespace
+        service = None
+        operation = None
+
+        if isinstance(call.func, ast.Name):
+            # Simple call: search(...)
+            operation = call.func.id
+        elif isinstance(call.func, ast.Attribute):
+            # Namespaced call: cognition.remember(...) or recall.search(...)
+            operation = call.func.attr
+
+            # Walk up the attribute chain to get service name
+            node = call.func.value
+            if isinstance(node, ast.Name):
+                service = node.id
+            elif isinstance(node, ast.Attribute):
+                # Multi-level: could be module.service.operation
+                # For now, take the last attribute as service
+                service = node.attr
+        else:
+            raise ValueError(f"Unsupported function type: {type(call.func)}")
+
+        # Extract arguments
+        arguments = {}
+
+        # Positional arguments (will be mapped by parameter order in schema)
+        for i, arg in enumerate(call.args):
+            # For now, use position-based keys; will be mapped to param names later
+            arguments[f"_pos_{i}"] = _ast_to_value(arg)
+
+        # Keyword arguments
+        for keyword in call.keywords:
+            if keyword.arg is None:
+                # **kwargs syntax
+                raise ValueError("**kwargs not supported")
+            arguments[keyword.arg] = _ast_to_value(keyword.value)
+
+        # Build result with new unified format
+        result = {
+            "operation": operation,
+            "arguments": arguments,
+            "tool": operation,  # Backward compatibility
+        }
+
+        if service:
+            result["service"] = service
+
+        return result
+
+    except (SyntaxError, ValueError) as e:
+        raise ValueError(f"Invalid function call syntax: {e}") from e
+
+
+def parse_batch_function_calls(batch_str: str) -> list[dict[str, Any]]:
+    """Parse batch function calls (array of function calls).
+
+    Supports:
+        - Same service batch: [remember(...), recall(...)]
+        - Cross-service batch: [cognition.remember(...), waves.check_in()]
+
+    Examples:
+        >>> parse_batch_function_calls('[search("A"), search("B")]')
+        [
+            {'operation': 'search', 'arguments': {'query': 'A'}},
+            {'operation': 'search', 'arguments': {'query': 'B'}}
+        ]
+
+        >>> parse_batch_function_calls('[cognition.remember(...), waves.check_in()]')
+        [
+            {'service': 'cognition', 'operation': 'remember', 'arguments': {...}},
+            {'service': 'waves', 'operation': 'check_in', 'arguments': {}}
+        ]
+
+    Args:
+        batch_str: String containing array of function calls
+
+    Returns:
+        List of parsed function call dicts
+
+    Raises:
+        ValueError: If the string is not a valid array of function calls
+    """
+    try:
+        # Remove whitespace for easier parsing
+        batch_str = batch_str.strip()
+
+        # Must start with [ and end with ]
+        if not (batch_str.startswith("[") and batch_str.endswith("]")):
+            raise ValueError("Batch call must be enclosed in [ ]")
+
+        # Escape reserved keywords before parsing (e.g., from= -> from_=)
+        escaped_str = _escape_reserved_keywords(batch_str)
+
+        # Parse as Python list expression
+        tree = ast.parse(escaped_str, mode="eval")
+        if not isinstance(tree.body, ast.List):
+            raise ValueError("Not a list expression")
+
+        results = []
+        for element in tree.body.elts:
+            if not isinstance(element, ast.Call):
+                raise ValueError(
+                    f"List element is not a function call: {ast.dump(element)}"
+                )
+
+            # Convert the Call node back to source code and parse it
+            call_str = ast.unparse(element)
+            parsed = parse_function_call(call_str)
+            results.append(parsed)
+
+        return results
+
+    except (SyntaxError, ValueError) as e:
+        raise ValueError(f"Invalid batch function call syntax: {e}") from e

krons/utils/_to_list.py

@@ -29,7 +29,7 @@ def _do_init() -> None:
     from pydantic import BaseModel
     from pydantic_core import PydanticUndefinedType
 
-    from krons.types import UndefinedType, UnsetType
+    from krons.core.types import UndefinedType, UnsetType
 
     global _MODEL_LIKE, _MAP_LIKE, _SINGLETONE_TYPES, _SKIP_TYPE, _SKIP_TUPLE_SET
     _MODEL_LIKE = (BaseModel,)
@@ -117,7 +117,11 @@ def to_list(
         if isinstance(input_, _BYTE_LIKE):
             return list(input_) if use_values else [input_]
         if isinstance(input_, Mapping):
-            return list(input_.values()) if use_values and hasattr(input_, "values") else [input_]
+            return (
+                list(input_.values())
+                if use_values and hasattr(input_, "values")
+                else [input_]
+            )
         if isinstance(input_, _MODEL_LIKE):
             return [input_]
         if isinstance(input_, Iterable) and not isinstance(input_, _BYTE_LIKE):
@@ -129,7 +133,9 @@ def to_list(
 
     initial_list = _to_list_type(input_, use_values=use_values)
     skip_types: tuple[type, ...] = _SKIP_TYPE if flatten_tuple_set else _SKIP_TUPLE_SET
-    processed = _process_list(initial_list, flatten=flatten, dropna=dropna, skip_types=skip_types)
+    processed = _process_list(
+        initial_list, flatten=flatten, dropna=dropna, skip_types=skip_types
+    )
 
     if unique:
         seen = set()

krons/utils/_utils.py

@@ -163,10 +163,14 @@ def import_module(
         ImportError: If module or attribute not found.
     """
     try:
-        full_import_path = f"{package_name}.{module_name}" if module_name else package_name
+        full_import_path = (
+            f"{package_name}.{module_name}" if module_name else package_name
+        )
 
         if import_name:
-            import_name = [import_name] if not isinstance(import_name, list) else import_name
+            import_name = (
+                [import_name] if not isinstance(import_name, list) else import_name
+            )
             a = __import__(
                 full_import_path,
                 fromlist=import_name,

krons/utils/concurrency/_async_call.py

@@ -11,7 +11,7 @@ Primary exports:
 from collections.abc import AsyncGenerator, Callable
 from typing import Any, ParamSpec, TypeVar
 
-from krons.types._sentinel import Unset, not_sentinel
+from krons.core.types._sentinel import Unset, not_sentinel
 from krons.utils._lazy_init import LazyInit
 from krons.utils._to_list import to_list
 
@@ -66,7 +66,9 @@ def _validate_func(func: Any) -> Callable:
     try:
         func_list = list(func)
     except TypeError:
-        raise ValueError("func must be callable or an iterable containing one callable.")
+        raise ValueError(
+            "func must be callable or an iterable containing one callable."
+        )
 
     if len(func_list) != 1 or not callable(func_list[0]):
         raise ValueError("Only one callable function is allowed.")

krons/utils/concurrency/_errors.py

@@ -48,7 +48,9 @@ def is_cancelled(exc: BaseException) -> bool:
     return isinstance(exc, anyio.get_cancelled_exc_class())
 
 
-async def shield(func: Callable[P, Awaitable[T]], *args: P.args, **kwargs: P.kwargs) -> T:
+async def shield(
+    func: Callable[P, Awaitable[T]], *args: P.args, **kwargs: P.kwargs
+) -> T:
     """Execute async function protected from outer cancellation.
 
     Args:

krons/utils/concurrency/_patterns.py

@@ -39,7 +39,9 @@ __all__ = (
 )
 
 
-async def gather(*aws: Awaitable[T], return_exceptions: bool = False) -> list[T | BaseException]:
+async def gather(
+    *aws: Awaitable[T], return_exceptions: bool = False
+) -> list[T | BaseException]:
     """Run awaitables concurrently and collect results in input order.
 
     Args:

krons/utils/concurrency/_resource_tracker.py

@@ -64,7 +64,9 @@ class LeakTracker:
             name: Identifier (defaults to "obj-{id}").
             kind: Optional category label.
         """
-        info = LeakInfo(name=name or f"obj-{id(obj)}", kind=kind, created_at=time.time())
+        info = LeakInfo(
+            name=name or f"obj-{id(obj)}", kind=kind, created_at=time.time()
+        )
         key = id(obj)
 
         def _finalizer(_key: int = key) -> None:
@@ -94,7 +96,9 @@ class LeakTracker:
 _TRACKER = LeakTracker()
 
 
-def track_resource(obj: object, name: str | None = None, kind: str | None = None) -> None:
+def track_resource(
+    obj: object, name: str | None = None, kind: str | None = None
+) -> None:
     """Track an object using the global leak tracker.
 
     Args:

krons/utils/display.py

@@ -0,0 +1,257 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Display utilities for verbose operation tracking.
+
+Ported from lionagi's as_readable system. Provides Rich-based
+console output with YAML/JSON syntax highlighting, environment
+detection, and truncation support.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from typing import Any
+
+try:
+    from rich.align import Align
+    from rich.box import ROUNDED
+    from rich.console import Console
+    from rich.padding import Padding
+    from rich.panel import Panel
+    from rich.syntax import Syntax
+    from rich.theme import Theme
+
+    DARK_THEME = Theme(
+        {
+            "info": "bright_cyan",
+            "warning": "bright_yellow",
+            "error": "bold bright_red",
+            "success": "bold bright_green",
+            "panel.border": "bright_blue",
+            "panel.title": "bold bright_cyan",
+            "json.key": "bright_cyan",
+            "json.string": "bright_green",
+            "json.number": "bright_yellow",
+            "json.boolean": "bright_magenta",
+            "json.null": "bright_red",
+            "yaml.key": "bright_cyan",
+            "yaml.string": "bright_green",
+            "yaml.number": "bright_yellow",
+            "yaml.boolean": "bright_magenta",
+        }
+    )
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+    DARK_THEME = None
+
+_console: Console | None = None
+
+
+def _get_console() -> Console | None:
+    global _console
+    if not RICH_AVAILABLE:
+        return None
+    if _console is None:
+        _console = Console(theme=DARK_THEME)
+    return _console
+
+
+def in_notebook() -> bool:
+    """Check if running inside a Jupyter notebook."""
+    try:
+        from IPython import get_ipython
+
+        shell = get_ipython().__class__.__name__
+        return "ZMQInteractiveShell" in shell
+    except Exception:
+        return False
+
+
+def in_console() -> bool:
+    """Check if running in a terminal with TTY."""
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty() and not in_notebook()
+
+
+def format_dict(data: Any, indent: int = 0) -> str:
+    """Format data as YAML-like readable string."""
+    lines = []
+    prefix = "  " * indent
+
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if isinstance(value, dict):
+                lines.append(f"{prefix}{key}:")
+                lines.append(format_dict(value, indent + 1))
+            elif isinstance(value, list):
+                lines.append(f"{prefix}{key}:")
+                for item in value:
+                    item_str = format_dict(item, indent + 2).lstrip()
+                    lines.append(f"{prefix}  - {item_str}")
+            elif isinstance(value, str) and "\n" in value:
+                lines.append(f"{prefix}{key}: |")
+                subprefix = "  " * (indent + 1)
+                for line in value.splitlines():
+                    lines.append(f"{subprefix}{line}")
+            else:
+                item_str = format_dict(value, indent + 1).lstrip()
+                lines.append(f"{prefix}{key}: {item_str}")
+        return "\n".join(lines)
+
+    elif isinstance(data, list):
+        for item in data:
+            item_str = format_dict(item, indent + 1).lstrip()
+            lines.append(f"{prefix}- {item_str}")
+        return "\n".join(lines)
+
+    return prefix + str(data)
+
+
+def as_readable(
+    input_: Any,
+    /,
+    *,
+    md: bool = False,
+    format_curly: bool = True,
+    max_chars: int | None = None,
+) -> str:
+    """Convert data to human-readable string.
+
+    Args:
+        input_: Data to format (dict, model, list, etc.).
+        md: Wrap in code fences for markdown.
+        format_curly: YAML-like (True) or JSON (False).
+        max_chars: Truncate output.
+
+    Returns:
+        Formatted string.
+    """
+    from krons.utils.fuzzy import to_dict
+
+    # Convert to dict
+    def safe_dict(obj: Any) -> Any:
+        try:
+            return to_dict(
+                obj,
+                use_model_dump=True,
+                fuzzy_parse=True,
+                recursive=True,
+                recursive_python_only=False,
+                max_recursive_depth=5,
+            )
+        except Exception:
+            return str(obj)
+
+    if isinstance(input_, list):
+        items = [safe_dict(x) for x in input_]
+    else:
+        maybe = safe_dict(input_)
+        items = maybe if isinstance(maybe, list) else [maybe]
+
+    rendered = []
+    for item in items:
+        if format_curly:
+            rendered.append(
+                format_dict(item) if isinstance(item, (dict, list)) else str(item)
+            )
+        else:
+            try:
+                rendered.append(json.dumps(item, indent=2, ensure_ascii=False))
+            except Exception:
+                rendered.append(str(item))
+
+    text = "\n\n".join(rendered).strip()
+
+    if md:
+        lang = "yaml" if format_curly else "json"
+        text = f"```{lang}\n{text}\n```"
+
+    if max_chars and len(text) > max_chars:
+        text = text[:max_chars] + "...\n\n[Truncated]"
+
+    return text
+
+
+def display(text: str, *, title: str | None = None, lang: str = "yaml") -> None:
+    """Display text with Rich formatting if available.
+
+    Args:
+        text: Text to display.
+        title: Optional panel title.
+        lang: Syntax language for highlighting.
+    """
+    console = _get_console()
+
+    if console and in_console():
+        syntax = Syntax(
+            text,
+            lang,
+            theme="github-dark",
+            line_numbers=False,
+            word_wrap=True,
+            background_color="default",
+        )
+        content = syntax
+        if title:
+            content = Panel(
+                Align.left(syntax, pad=False),
+                title=title,
+                title_align="left",
+                border_style="panel.border",
+                box=ROUNDED,
+                width=min(console.width - 4, 140),
+                expand=False,
+            )
+            console.print(Padding(content, (0, 0, 0, 2)))
+        else:
+            console.print(Padding(content, (0, 0, 0, 2)))
+        return
+
+    # Fallback
+    if title:
+        print(f"\n--- {title} ---")
+    print(text)
+
+
+def status(msg: str, *, style: str = "info") -> None:
+    """Print a status message with optional Rich styling.
+
+    Args:
+        msg: Status message.
+        style: Rich style name (info, success, warning, error).
+    """
+    console = _get_console()
+    if console and in_console():
+        console.print(f"  [{style}]{msg}[/{style}]")
+    else:
+        print(f"  {msg}")
+
+
+def phase(title: str) -> None:
+    """Print a phase header."""
+    console = _get_console()
+    if console and in_console():
+        console.print(f"\n[bold bright_cyan]=== {title} ===[/bold bright_cyan]")
+    else:
+        print(f"\n=== {title} ===")
+
+
+class Timer:
+    """Simple context manager for timing operations."""
+
+    def __init__(self, label: str = ""):
+        self.label = label
+        self.start = 0.0
+        self.elapsed = 0.0
+
+    def __enter__(self):
+        self.start = time.monotonic()
+        return self
+
+    def __exit__(self, *args):
+        self.elapsed = time.monotonic() - self.start
+        if self.label:
+            status(f"{self.label}: {self.elapsed:.1f}s", style="success")

krons/utils/fuzzy/__init__.py

@@ -1,14 +1,19 @@
 from ._extract_json import extract_json
 from ._fuzzy_json import fuzzy_json
-from ._fuzzy_match import fuzzy_match_keys
+from ._fuzzy_match import HandleUnmatched, fuzzy_match_keys
 from ._string_similarity import SimilarityAlgo, string_similarity
 from ._to_dict import to_dict
 
+# Alias for backward compatibility
+fuzzy_validate_mapping = fuzzy_match_keys
+
 __all__ = (
     "extract_json",
     "fuzzy_json",
     "fuzzy_match_keys",
+    "fuzzy_validate_mapping",
     "string_similarity",
     "SimilarityAlgo",
     "to_dict",
+    "HandleUnmatched",
 )

krons/utils/fuzzy/_fuzzy_match.py

@@ -1,18 +1,16 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from krons.types import KeysLike
+    from krons.core.types import KeysLike
 
-from krons.types._sentinel import Unset
+from krons.core.types._sentinel import Unset
 
 from ._string_similarity import SimilarityAlgo, string_similarity
 
-__all__ = ("fuzzy_match_keys",)
-
-HandleUnmatched = Literal["ignore", "raise", "remove", "fill", "force"]
+__all__ = ("fuzzy_match_keys", "HandleUnmatched")
 
 
 class HandleUnmatched(Enum):
@@ -114,7 +112,13 @@ def fuzzy_match_keys(
             )
 
             if matches:
-                match = matches if isinstance(matches, str) else matches[0] if matches else None
+                match = (
+                    matches
+                    if isinstance(matches, str)
+                    else matches[0]
+                    if matches
+                    else None
+                )
                 if match:
                     corrected_out[match] = d_[key]
                     matched_expected.add(match)
@@ -136,7 +140,9 @@ def fuzzy_match_keys(
     elif handle_unmatched in (HandleUnmatched.FILL, HandleUnmatched.FORCE):
         for key in unmatched_expected:
             corrected_out[key] = (
-                fill_mapping[key] if fill_mapping and key in fill_mapping else fill_value
+                fill_mapping[key]
+                if fill_mapping and key in fill_mapping
+                else fill_value
             )
 
         if handle_unmatched == HandleUnmatched.FILL: