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

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)

{kronos → krons}/utils/sql/_sql_validation.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import re
 
-from kronos.errors import ValidationError
+from krons.errors import ValidationError
 
 __all__ = (
     "validate_identifier",

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}")

krons/work/__init__.py

@@ -0,0 +1,126 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Work system - Declarative workflow orchestration.
+
+Two complementary patterns at different abstraction levels:
+
+**Report** (artifact state):
+    Declarative workflow definition via form_assignments DSL.
+    Tracks one specific job's progress through the workflow.
+    Dependencies implicit from field names.
+
+    class HiringBriefReport(Report):
+        role_classification: RoleClassification | None = None
+        strategic_context: StrategicContext | None = None
+
+        assignment: str = "job_input -> executive_summary"
+
+        form_assignments: list[str] = [
+            "classifier: job_input -> role_classification | api:fast",
+            "strategist: job_input, role_classification -> strategic_context | api:synthesis",
+        ]
+
+**Worker** (execution capability):
+    Functional station that can execute forms.
+    Has internal DAG for retries/error handling.
+    Matches to forms via resource hints.
+
+    class ClassifierWorker(Worker):
+        @work(assignment="job_input -> role_classification")
+        async def classify(self, job_input, **kwargs):
+            return await self.llm.chat(**kwargs)
+
+Core concepts:
+- Phrase: Typed operation signature (inputs -> outputs)
+- Form: Data binding + scheduling (stateful artifact)
+- Report: Multi-step workflow declaration (stateful artifact)
+- Worker: Execution capability (stateless station)
+- WorkerEngine: Execution driver
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Lazy import mapping
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # engine
+    "WorkerEngine": ("krons.work.engine", "WorkerEngine"),
+    "WorkerTask": ("krons.work.engine", "WorkerTask"),
+    # form
+    "Form": ("krons.work.form", "Form"),
+    "ParsedAssignment": ("krons.work.form", "ParsedAssignment"),
+    "parse_assignment": ("krons.work.form", "parse_assignment"),
+    "parse_full_assignment": ("krons.work.form", "parse_full_assignment"),
+    # phrase
+    "CrudOperation": ("krons.work.phrase", "CrudOperation"),
+    "CrudPattern": ("krons.work.phrase", "CrudPattern"),
+    "Phrase": ("krons.work.phrase", "Phrase"),
+    "phrase": ("krons.work.phrase", "phrase"),
+    # report
+    "Report": ("krons.work.report", "Report"),
+    # worker
+    "Worker": ("krons.work.worker", "Worker"),
+    "WorkConfig": ("krons.work.worker", "WorkConfig"),
+    "WorkLink": ("krons.work.worker", "WorkLink"),
+    "work": ("krons.work.worker", "work"),
+    "worklink": ("krons.work.worker", "worklink"),
+}
+
+_LOADED: dict[str, object] = {}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import attributes on first access."""
+    if name in _LOADED:
+        return _LOADED[name]
+
+    if name in _LAZY_IMPORTS:
+        from importlib import import_module
+
+        module_name, attr_name = _LAZY_IMPORTS[name]
+        module = import_module(module_name)
+        value = getattr(module, attr_name)
+        _LOADED[name] = value
+        return value
+
+    raise AttributeError(f"module 'krons.work' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return all available attributes for autocomplete."""
+    return list(__all__)
+
+
+# TYPE_CHECKING block for static analysis
+if TYPE_CHECKING:
+    from krons.work.engine import WorkerEngine, WorkerTask
+    from krons.work.form import (
+        Form,
+        ParsedAssignment,
+        parse_assignment,
+        parse_full_assignment,
+    )
+    from krons.work.phrase import CrudOperation, CrudPattern, Phrase, phrase
+    from krons.work.report import Report
+    from krons.work.worker import WorkConfig, Worker, WorkLink, work, worklink
+
+__all__ = (
+    "CrudOperation",
+    "CrudPattern",
+    "Form",
+    "ParsedAssignment",
+    "Phrase",
+    "Report",
+    "WorkConfig",
+    "WorkLink",
+    "Worker",
+    "WorkerEngine",
+    "WorkerTask",
+    "parse_assignment",
+    "parse_full_assignment",
+    "phrase",
+    "work",
+    "worklink",
+)