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

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]

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"

krons/utils/schemas/_minimal_yaml.py

@@ -0,0 +1,151 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+import orjson
+import yaml  # type: ignore[import-untyped]
+
+__all__ = ("minimal_yaml",)
+
+# Maximum recursion depth for pruning to prevent stack overflow
+MAX_PRUNE_DEPTH = 100
+
+
+class MinimalDumper(yaml.SafeDumper):
+    """YAML dumper with minimal, readable settings."""
+
+    def ignore_aliases(self, data: Any) -> bool:  # type: ignore[override]
+        """Disable anchors/aliases (&id001, *id001) for repeated objects."""
+        return True
+
+
+def _represent_str(dumper: yaml.SafeDumper, data: str):
+    """Use block scalars for multiline text; plain style otherwise."""
+    if "\n" in data:
+        return dumper.represent_scalar("tag:yaml.org,2002:str", data, style="|")
+    return dumper.represent_scalar("tag:yaml.org,2002:str", data)
+
+
+MinimalDumper.add_representer(str, _represent_str)
+
+
+def _is_empty(x: Any) -> bool:
+    """Define 'empty' for pruning. Keeps 0 and False."""
+    if x is None:
+        return True
+    if isinstance(x, str):
+        return x.strip() == ""
+    if isinstance(x, dict):
+        return len(x) == 0
+    if isinstance(x, list | tuple | set):
+        return len(x) == 0
+    return False
+
+
+def _prune(x: Any, *, _depth: int = 0, _max_depth: int = MAX_PRUNE_DEPTH) -> Any:
+    """Recursively remove empty leaves and empty containers.
+
+    Args:
+        x: Value to prune
+        _depth: Current recursion depth (internal use)
+        _max_depth: Maximum recursion depth (default: 100)
+
+    Returns:
+        Pruned value with empty containers removed
+
+    Raises:
+        RecursionError: If depth exceeds _max_depth
+    """
+    if _depth > _max_depth:
+        msg = f"Pruning depth exceeds maximum ({_max_depth})"
+        raise RecursionError(msg)
+
+    if isinstance(x, dict):
+        pruned = {
+            k: _prune(v, _depth=_depth + 1, _max_depth=_max_depth)
+            for k, v in x.items()
+            if not _is_empty(v)
+        }
+        return {k: v for k, v in pruned.items() if not _is_empty(v)}
+    if isinstance(x, list):
+        pruned_list = [
+            _prune(v, _depth=_depth + 1, _max_depth=_max_depth)
+            for v in x
+            if not _is_empty(v)
+        ]
+        return [v for v in pruned_list if not _is_empty(v)]
+    if isinstance(x, tuple):
+        pruned_list = [
+            _prune(v, _depth=_depth + 1, _max_depth=_max_depth)
+            for v in x
+            if not _is_empty(v)
+        ]
+        return tuple(v for v in pruned_list if not _is_empty(v))
+    if isinstance(x, set):
+        pruned_set = {
+            _prune(v, _depth=_depth + 1, _max_depth=_max_depth)
+            for v in x
+            if not _is_empty(v)
+        }
+        return {v for v in pruned_set if not _is_empty(v)}
+    return x
+
+
+def minimal_yaml(
+    value: Any,
+    *,
+    drop_empties: bool = True,
+    indent: int = 2,
+    line_width: int = 2**31 - 1,
+    sort_keys: bool = False,
+    unescape_html: bool = False,
+) -> str:
+    """Convert value to minimal YAML string.
+
+    Args:
+        value: Value to convert (dict, list, or JSON string)
+        drop_empties: Remove empty/None values recursively (default: True)
+        indent: YAML indentation level (default: 2)
+        line_width: Maximum line width (default: unlimited)
+        sort_keys: Sort dictionary keys alphabetically (default: False)
+        unescape_html: Unescape HTML entities in output (default: False)
+
+    Returns:
+        YAML-formatted string
+
+    Raises:
+        RecursionError: If value nesting exceeds maximum depth (100)
+
+    Security Note:
+        This function only DUMPS (outputs) YAML using SafeDumper - it does
+        not load/parse YAML, so it is not vulnerable to YAML deserialization
+        attacks. However, if unescape_html=True is used and the output is
+        later rendered in HTML without proper escaping, XSS vulnerabilities
+        may occur. Use caution with unescape_html in web contexts.
+    """
+    # Auto-parse JSON strings for convenience (fails gracefully on invalid JSON)
+    if isinstance(value, str):
+        try:
+            value = orjson.loads(value)
+        except orjson.JSONDecodeError:
+            # Not valid JSON - treat as plain string
+            pass
+
+    data = _prune(value) if drop_empties else value
+    str_ = yaml.dump(
+        data,
+        Dumper=MinimalDumper,
+        default_flow_style=False,
+        sort_keys=sort_keys,
+        allow_unicode=True,
+        indent=indent,
+        width=line_width,
+    )
+    if unescape_html:
+        import html
+
+        return html.unescape(str_)
+    return str_

krons/utils/schemas/_typescript.py

@@ -0,0 +1,153 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+
+def _type_map(json_type: str) -> str:
+    """Map JSON Schema types to TypeScript-like types."""
+    mapping = {
+        "string": "string",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+        "array": "array",  # Will be handled specially
+        "object": "object",
+        "null": "null",
+    }
+    return mapping.get(json_type, json_type)
+
+
+def _format_enum_union(enum_values: list) -> str:
+    """Format enum values as TypeScript union of literals."""
+    formatted = []
+    for val in enum_values:
+        if isinstance(val, str):
+            formatted.append(f'"{val}"')
+        elif val is None:
+            formatted.append("null")
+        else:
+            formatted.append(str(val))
+    return " | ".join(formatted)
+
+
+def _extract_type_signature(field_spec: dict, required: bool) -> tuple[str, bool]:
+    """Extract TypeScript-style type signature from JSON Schema field."""
+    # Handle enums first (most specific)
+    if "enum" in field_spec:
+        type_sig = _format_enum_union(field_spec["enum"])
+        # Check if enum includes null
+        has_null = None in field_spec["enum"]
+        is_optional = not required or has_null
+        return type_sig, is_optional
+
+    # Handle anyOf (unions)
+    if "anyOf" in field_spec:
+        options = field_spec["anyOf"]
+        type_parts = []
+        has_null = False
+
+        for opt in options:
+            if opt.get("type") == "null":
+                has_null = True
+                continue
+
+            if "type" in opt:
+                if opt["type"] == "array" and "items" in opt:
+                    item_type = _type_map(opt["items"].get("type", "any"))
+                    if "$ref" in opt["items"]:
+                        item_type = opt["items"]["$ref"].split("/")[-1]
+                    type_parts.append(f"{item_type}[]")
+                else:
+                    type_parts.append(_type_map(opt["type"]))
+            elif "$ref" in opt:
+                ref_name = opt["$ref"].split("/")[-1]
+                type_parts.append(ref_name)
+            elif "enum" in opt:
+                type_parts.append(_format_enum_union(opt["enum"]))
+
+        if has_null:
+            type_parts.append("null")
+
+        type_sig = " | ".join(type_parts) if type_parts else "any"
+        is_optional = not required or has_null
+        return type_sig, is_optional
+
+    # Handle arrays
+    if "type" in field_spec and field_spec["type"] == "array":
+        if "items" in field_spec:
+            items_spec = field_spec["items"]
+            if "type" in items_spec:
+                item_type = _type_map(items_spec["type"])
+            elif "$ref" in items_spec:
+                item_type = items_spec["$ref"].split("/")[-1]
+            elif "enum" in items_spec:
+                item_type = f"({_format_enum_union(items_spec['enum'])})"
+            else:
+                item_type = "any"
+        else:
+            item_type = "any"
+        type_sig = f"{item_type}[]"
+        is_optional = not required
+        return type_sig, is_optional
+
+    # Handle $ref
+    if "$ref" in field_spec:
+        ref_name = field_spec["$ref"].split("/")[-1]
+        is_optional = not required
+        return ref_name, is_optional
+
+    # Handle simple types
+    if "type" in field_spec:
+        base_type = field_spec["type"]
+        # Handle nullable simple types (type? suffix from simplification)
+        if isinstance(base_type, str) and base_type.endswith("?"):
+            type_sig = _type_map(base_type[:-1])
+            is_optional = True
+        else:
+            type_sig = _type_map(base_type)
+            is_optional = not required
+        return type_sig, is_optional
+
+    # Fallback
+    return "any", not required
+
+
+def typescript_schema(schema: dict, indent: int = 0) -> str:
+    """Convert JSON Schema to TypeScript-style notation for optimal LLM comprehension."""
+    lines = []
+    prefix = "  " * indent
+
+    if "properties" not in schema:
+        return ""
+
+    required_fields = set(schema.get("required", []))
+
+    for field_name, field_spec in schema["properties"].items():
+        is_required = field_name in required_fields
+
+        # Extract type signature
+        type_sig, is_optional = _extract_type_signature(field_spec, is_required)
+
+        # Add default value if present
+        default_str = ""
+        if "default" in field_spec:
+            default_val = field_spec["default"]
+            if isinstance(default_val, str):
+                default_str = f' = "{default_val}"'
+            elif default_val is None:
+                default_str = " = null"
+            elif isinstance(default_val, bool):
+                default_str = f" = {'true' if default_val else 'false'}"
+            else:
+                default_str = f" = {default_val}"
+
+        # Build field definition
+        optional_marker = "?" if is_optional else ""
+        field_def = f"{prefix}{field_name}{optional_marker}: {type_sig}{default_str}"
+
+        # Add description if present
+        if field_spec.get("description"):
+            field_def += f" - {field_spec['description']}"
+
+        lines.append(field_def)
+
+    return "\n".join(lines)

krons/utils/validators/__init__.py

@@ -0,0 +1,3 @@
+from ._validate_image_url import validate_image_url
+
+__all__ = ("validate_image_url",)

krons/utils/validators/_validate_image_url.py

@@ -0,0 +1,56 @@
+from urllib.parse import urlparse
+
+__all__ = ("validate_image_url",)
+
+
+def validate_image_url(url: str) -> None:
+    """Validate image URL to prevent security vulnerabilities.
+
+    Security checks:
+        - Reject null bytes (path truncation attacks)
+        - Reject file:// URLs (local file access)
+        - Reject javascript: URLs (XSS attacks)
+        - Reject data:// URLs (DoS via large embedded images)
+        - Only allow http:// and https:// schemes
+        - Validate URL format
+
+    Args:
+        url: URL to validate
+
+    Raises:
+        ValueError: If URL is invalid or uses disallowed scheme
+    """
+
+    if not url or not isinstance(url, str):
+        raise ValueError(
+            f"Image URL must be non-empty string, got: {type(url).__name__}"
+        )
+
+    # Reject null bytes (path truncation attacks)
+    # Check both literal null bytes and percent-encoded %00
+    if "\x00" in url:
+        raise ValueError(
+            "Image URL contains null byte - potential path truncation attack"
+        )
+    if "%00" in url.lower():
+        raise ValueError(
+            "Image URL contains percent-encoded null byte (%00) - potential path truncation attack"
+        )
+
+    try:
+        parsed = urlparse(url)
+    except Exception as e:
+        raise ValueError(f"Malformed image URL '{url}': {e}") from e
+
+    # Only allow http and https schemes
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(
+            f"Image URL must use http:// or https:// scheme, got: {parsed.scheme}://"
+            f"\nRejected URL: {url}"
+            f"\nReason: Disallowed schemes (file://, javascript://, data://) pose "
+            f"security risks (local file access, XSS, DoS)"
+        )
+
+    # Ensure netloc (domain) is present for http/https
+    if not parsed.netloc:
+        raise ValueError(f"Image URL missing domain: {url}")