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

{kronos → 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")

{kronos → 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",
 )

{kronos → 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 kronos.types import KeysLike
+    from krons.core.types import KeysLike
 
-from kronos.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:

{kronos → krons}/utils/fuzzy/_string_similarity.py

@@ -165,7 +165,9 @@ def string_similarity(
             raise ValueError(f"Unsupported algorithm: {algorithm}")
 
     results = []
-    for idx, (orig_word, comp_word) in enumerate(zip(original_words, compare_words, strict=False)):
+    for idx, (orig_word, comp_word) in enumerate(
+        zip(original_words, compare_words, strict=False)
+    ):
         if algo_name == "hamming" and len(comp_word) != len(compare_word):
             continue  # Hamming requires equal length
         score = score_func(compare_word, comp_word)  # type: ignore[operator]

{kronos → krons}/utils/fuzzy/_to_dict.py

@@ -310,7 +310,9 @@ def _preprocess_recursive(
 
     if recursive_custom_types:
         with contextlib.suppress(Exception):
-            mapped = _object_to_mapping_like(obj, prioritize_model_dump=prioritize_model_dump)
+            mapped = _object_to_mapping_like(
+                obj, prioritize_model_dump=prioritize_model_dump
+            )
             return _preprocess_recursive(
                 mapped,
                 depth=depth + 1,

krons/utils/schemas/__init__.py

@@ -0,0 +1,26 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Schema utilities for YAML, TypeScript, and Pydantic processing."""
+
+from ._breakdown_pydantic_annotation import (
+    breakdown_pydantic_annotation,
+    is_pydantic_model,
+)
+from ._formatter import (
+    format_clean_multiline_strings,
+    format_model_schema,
+    format_schema_pretty,
+)
+from ._minimal_yaml import minimal_yaml
+from ._typescript import typescript_schema
+
+__all__ = (
+    "breakdown_pydantic_annotation",
+    "is_pydantic_model",
+    "minimal_yaml",
+    "typescript_schema",
+    "format_model_schema",
+    "format_schema_pretty",
+    "format_clean_multiline_strings",
+)

krons/utils/schemas/_breakdown_pydantic_annotation.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+from inspect import isclass
+from typing import Any, get_args, get_origin
+
+from pydantic import BaseModel
+
+# Pattern to match module-qualified names like __main__.Foo or lionagi.x.y.Bar
+_MODULE_PATTERN = re.compile(r"([a-zA-Z_][a-zA-Z0-9_]*\.)+([a-zA-Z_][a-zA-Z0-9_]*)")
+
+
+# Pattern to extract type name from <class 'typename'>
+_CLASS_PATTERN = re.compile(r"<class '([^']+)'>")
+
+
+def _clean_type_repr(t: Any) -> str:
+    """Convert a type annotation to a clean Python-like string.
+
+    Handles:
+    - <class 'str'> -> "str"
+    - <class 'int'> -> "int"
+    - Module-qualified names -> just class name
+    """
+    s = str(t) if not isinstance(t, str) else t
+
+    # Handle <class 'typename'> pattern
+    if match := _CLASS_PATTERN.match(s):
+        type_name = match.group(1)
+        # Strip module prefix if present (e.g., 'builtins.str' -> 'str')
+        return type_name.rsplit(".", 1)[-1]
+
+    # Replace module-qualified names with just the class name
+    s = _MODULE_PATTERN.sub(r"\2", s)
+
+    return s
+
+
+# Default maximum recursion depth for safety
+DEFAULT_MAX_DEPTH = 50
+
+
+def breakdown_pydantic_annotation(
+    model: type[BaseModel],
+    max_depth: int | None = DEFAULT_MAX_DEPTH,
+    clean_types: bool = True,
+) -> dict[str, Any]:
+    """Break down a Pydantic model's annotations into a nested dict structure.
+
+    Args:
+        model: The Pydantic model class to break down.
+        max_depth: Maximum recursion depth for nested models (default: 50).
+            Set to None for unlimited depth (not recommended).
+        clean_types: If True, convert type annotations to clean strings
+            without module prefixes (e.g., 'list[CodeModule]' instead of
+            'list[__main__.CodeModule]').
+
+    Returns:
+        Dict mapping field names to type representations:
+        - Strings for simple types
+        - Dicts for nested Pydantic models
+        - Lists containing the above for list fields
+
+    Raises:
+        TypeError: If model is not a Pydantic BaseModel subclass.
+        RecursionError: If max_depth is exceeded during traversal.
+    """
+    result = _breakdown_pydantic_annotation(
+        model=model,
+        max_depth=max_depth,
+        current_depth=0,
+    )
+    if clean_types:
+        return _clean_result(result)
+    return result
+
+
+def _clean_result(result: dict[str, Any]) -> dict[str, Any]:
+    """Recursively clean type representations in the result dict."""
+    out: dict[str, Any] = {}
+    for k, v in result.items():
+        if isinstance(v, dict):
+            out[k] = _clean_result(v)
+        elif isinstance(v, list) and v:
+            if isinstance(v[0], dict):
+                out[k] = [_clean_result(v[0])]
+            else:
+                out[k] = [_clean_type_repr(v[0])]
+        else:
+            out[k] = _clean_type_repr(v)
+    return out
+
+
+def _breakdown_pydantic_annotation(
+    model: type[BaseModel],
+    max_depth: int | None = None,
+    current_depth: int = 0,
+) -> dict[str, Any]:
+    if not is_pydantic_model(model):
+        raise TypeError("Input must be a Pydantic model")
+
+    if max_depth is not None and current_depth >= max_depth:
+        raise RecursionError("Maximum recursion depth reached")
+
+    out: dict[str, Any] = {}
+    for k, v in model.__annotations__.items():
+        origin = get_origin(v)
+        if is_pydantic_model(v):
+            out[k] = _breakdown_pydantic_annotation(v, max_depth, current_depth + 1)
+        elif origin is list:
+            args = get_args(v)
+            if args and is_pydantic_model(args[0]):
+                out[k] = [
+                    _breakdown_pydantic_annotation(
+                        args[0], max_depth, current_depth + 1
+                    )
+                ]
+            else:
+                out[k] = [args[0] if args else Any]
+        else:
+            out[k] = v
+
+    return out
+
+
+def is_pydantic_model(x: Any) -> bool:
+    try:
+        return isclass(x) and issubclass(x, BaseModel)
+    except TypeError:
+        return False

krons/utils/schemas/_formatter.py

@@ -0,0 +1,72 @@
+import textwrap
+
+from pydantic import BaseModel
+
+from ._typescript import typescript_schema
+
+__all__ = (
+    "format_model_schema",
+    "format_schema_pretty",
+    "format_clean_multiline_strings",
+)
+
+
+def format_model_schema(request_model: type[BaseModel]) -> str:
+    model_schema = request_model.model_json_schema()
+    schema_text = ""
+    if defs := model_schema.get("$defs"):
+        for def_name, def_schema in defs.items():
+            if def_ts := typescript_schema(def_schema):
+                schema_text += f"\n{def_name}:\n" + textwrap.indent(def_ts, "  ")
+    return schema_text
+
+
+def format_schema_pretty(schema: dict, indent: int = 0) -> str:
+    """Format schema dict with unquoted Python type values."""
+    lines = ["{"]
+    items = list(schema.items())
+    for i, (key, value) in enumerate(items):
+        comma = "," if i < len(items) - 1 else ""
+        if isinstance(value, dict):
+            nested = format_schema_pretty(value, indent + 4)
+            lines.append(f'{" " * (indent + 4)}"{key}": {nested}{comma}')
+        elif isinstance(value, list) and value:
+            if isinstance(value[0], dict):
+                nested = format_schema_pretty(value[0], indent + 4)
+                lines.append(f'{" " * (indent + 4)}"{key}": [{nested}]{comma}')
+            else:
+                lines.append(f'{" " * (indent + 4)}"{key}": [{value[0]}]{comma}')
+        else:
+            lines.append(f'{" " * (indent + 4)}"{key}": {value}{comma}')
+    lines.append(f"{' ' * indent}}}")
+    return "\n".join(lines)
+
+
+def format_clean_multiline_strings(data: dict) -> dict:
+    """Clean multiline strings for YAML block scalars (| not |-)."""
+    cleaned: dict[str, object] = {}
+    for k, v in data.items():
+        if isinstance(v, str) and "\n" in v:
+            # Strip trailing whitespace from each line, ensure ends with newline for "|"
+            lines = "\n".join(line.rstrip() for line in v.split("\n"))
+            cleaned[k] = lines if lines.endswith("\n") else lines + "\n"
+        elif isinstance(v, list):
+            cleaned[k] = [
+                (
+                    _clean_multiline(item)
+                    if isinstance(item, str) and "\n" in item
+                    else item
+                )
+                for item in v
+            ]
+        elif isinstance(v, dict):
+            cleaned[k] = format_clean_multiline_strings(v)
+        else:
+            cleaned[k] = v
+    return cleaned
+
+
+def _clean_multiline(s: str) -> str:
+    """Clean a multiline string: strip line trailing whitespace, ensure final newline."""
+    lines = "\n".join(line.rstrip() for line in s.split("\n"))
+    return lines if lines.endswith("\n") else lines + "\n"