lionherd-core 1.0.0a3__py3-none-any.whl

lionherd_core/libs/concurrency/_task.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Any, TypeVar
+
+import anyio
+import anyio.abc
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+__all__ = (
+    "TaskGroup",
+    "create_task_group",
+)
+
+
+class TaskGroup:
+    """Structured concurrency task group."""
+
+    __slots__ = ("_tg",)
+
+    def __init__(self, tg: anyio.abc.TaskGroup) -> None:
+        self._tg = tg
+
+    @property
+    def cancel_scope(self) -> anyio.CancelScope:
+        """Cancel scope for task group lifetime."""
+        return self._tg.cancel_scope
+
+    def start_soon(
+        self,
+        func: Callable[..., Awaitable[Any]],
+        *args: Any,
+        name: str | None = None,
+    ) -> None:
+        """Start task without waiting for initialization."""
+        self._tg.start_soon(func, *args, name=name)
+
+    async def start(
+        self,
+        func: Callable[..., Awaitable[R]],
+        *args: Any,
+        name: str | None = None,
+    ) -> R:
+        """Start task and wait for initialization."""
+        return await self._tg.start(func, *args, name=name)
+
+
+@asynccontextmanager
+async def create_task_group() -> AsyncIterator[TaskGroup]:
+    """Create task group for structured concurrency."""
+    async with anyio.create_task_group() as tg:
+        yield TaskGroup(tg)

lionherd_core/libs/concurrency/_utils.py

@@ -0,0 +1,61 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+from collections.abc import Callable
+from functools import cache, partial
+from typing import Any, ParamSpec, TypeVar
+
+import anyio
+import anyio.to_thread
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+__all__ = ("current_time", "is_coro_func", "run_sync", "sleep")
+
+
+@cache
+def _is_coro_func(func: Callable[..., Any]) -> bool:
+    """Cached check for coroutine function, handles partials."""
+    # Unwrap partials to get the underlying function
+    while isinstance(func, partial):
+        func = func.func
+
+    # Check if it's a coroutine function
+    return inspect.iscoroutinefunction(func)
+
+
+def is_coro_func(func: Callable[..., Any]) -> bool:
+    """Check if function is coroutine function."""
+    return _is_coro_func(func)
+
+
+def current_time() -> float:
+    """Get current time in seconds (monotonic clock)."""
+    return anyio.current_time()
+
+
+async def run_sync(func: Callable[P, R], *args: P.args, **kwargs: P.kwargs) -> R:
+    """Run synchronous function in thread pool.
+
+    Preserves the function signature using ParamSpec, improving type inference.
+
+    Args:
+        func: Synchronous function to run in thread pool
+        *args: Positional arguments for func
+        **kwargs: Keyword arguments for func
+
+    Returns:
+        Result of func
+    """
+    if kwargs:
+        # anyio.to_thread.run_sync doesn't accept **kwargs, use partial
+        func_with_kwargs = partial(func, **kwargs)
+        return await anyio.to_thread.run_sync(func_with_kwargs, *args)
+    return await anyio.to_thread.run_sync(func, *args)
+
+
+async def sleep(seconds: float) -> None:
+    """Sleep without blocking event loop."""
+    await anyio.sleep(seconds)

lionherd_core/libs/schema_handlers/__init__.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING
+
+from ._function_call_parser import (
+    map_positional_args,
+    nest_arguments_by_schema,
+    parse_function_call,
+)
+from ._minimal_yaml import minimal_yaml
+from ._typescript import typescript_schema
+
+if TYPE_CHECKING:
+    from ._schema_to_model import load_pydantic_model_from_schema
+
+
+__all__ = (
+    "load_pydantic_model_from_schema",
+    "map_positional_args",
+    "minimal_yaml",
+    "nest_arguments_by_schema",
+    "parse_function_call",
+    "typescript_schema",
+)
+
+
+def __getattr__(name: str):
+    """Lazy import for optional dependencies."""
+    if name == "load_pydantic_model_from_schema":
+        from ._schema_to_model import load_pydantic_model_from_schema
+
+        return load_pydantic_model_from_schema
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

lionherd_core/libs/schema_handlers/_function_call_parser.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+import ast
+from typing import Any, get_args, get_origin
+
+from pydantic import BaseModel
+
+
+def parse_function_call(call_str: str) -> dict[str, Any]:
+    """Parse Python function call syntax into JSON tool invocation format."""
+    try:
+        # Parse the call as a Python expression
+        tree = ast.parse(call_str, mode="eval")
+        call = tree.body
+
+        if not isinstance(call, ast.Call):
+            raise ValueError("Not a function call")
+
+        # Extract function name
+        if isinstance(call.func, ast.Name):
+            tool_name = call.func.id
+        elif isinstance(call.func, ast.Attribute):
+            # Handle chained calls like client.search()
+            tool_name = call.func.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.literal_eval(arg)
+
+        # Keyword arguments
+        for keyword in call.keywords:
+            if keyword.arg is None:
+                # **kwargs syntax
+                raise ValueError("**kwargs not supported")
+            arguments[keyword.arg] = ast.literal_eval(keyword.value)
+
+        return {"tool": tool_name, "arguments": arguments}
+
+    except (SyntaxError, ValueError) as e:
+        raise ValueError(f"Invalid function call syntax: {e}")
+
+
+def map_positional_args(arguments: dict[str, Any], param_names: list[str]) -> dict[str, Any]:
+    """Map positional arguments (_pos_0, _pos_1, ...) to actual parameter names."""
+    mapped = {}
+    pos_count = 0
+
+    for key, value in arguments.items():
+        if key.startswith("_pos_"):
+            if pos_count >= len(param_names):
+                raise ValueError(f"Too many positional arguments (expected {len(param_names)})")
+            mapped[param_names[pos_count]] = value
+            pos_count += 1
+        else:
+            # Keep keyword arguments as-is
+            mapped[key] = value
+
+    return mapped
+
+
+def nest_arguments_by_schema(arguments: dict[str, Any], schema_cls) -> dict[str, Any]:
+    """Restructure flat arguments into nested format based on schema structure."""
+    if not schema_cls or not hasattr(schema_cls, "model_fields"):
+        return arguments
+
+    # Get top-level field names
+    top_level_fields = set(schema_cls.model_fields.keys())
+
+    # Find fields that are nested objects (Pydantic models or unions)
+    nested_field_mappings = {}
+    for field_name, field_info in schema_cls.model_fields.items():
+        annotation = field_info.annotation
+
+        # Check if it's a union type
+        if get_origin(annotation) is type(int | str):  # UnionType check
+            union_members = get_args(annotation)
+            # Collect all fields from union members
+            union_fields = set()
+            for member in union_members:
+                if hasattr(member, "model_fields"):
+                    union_fields.update(member.model_fields.keys())
+            if union_fields:
+                nested_field_mappings[field_name] = union_fields
+        # Check if it's a Pydantic model
+        elif isinstance(annotation, type) and issubclass(annotation, BaseModel):
+            nested_field_mappings[field_name] = set(annotation.model_fields.keys())
+
+    # If no nested fields detected, return as-is
+    if not nested_field_mappings:
+        return arguments
+
+    # Separate top-level args from nested args
+    result = {}
+    nested_args = {}
+
+    for key, value in arguments.items():
+        if key in top_level_fields:
+            # This is a top-level field
+            result[key] = value
+        else:
+            # Check if this belongs to a nested field
+            for nested_field, nested_keys in nested_field_mappings.items():
+                if key in nested_keys:
+                    if nested_field not in nested_args:
+                        nested_args[nested_field] = {}
+                    nested_args[nested_field][key] = value
+                    break
+            else:
+                # Unknown field - keep at top level (will fail validation later)
+                result[key] = value
+
+    # Add nested structures to result
+    result.update(nested_args)
+
+    return result

lionherd_core/libs/schema_handlers/_minimal_yaml.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2025, 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",)
+
+
+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) -> Any:
+    """Recursively remove empty leaves and empty containers."""
+    if isinstance(x, dict):
+        pruned = {k: _prune(v) 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) 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) 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) 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,
+) -> str:
+    """Convert value to minimal YAML string."""
+    # 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
+    return yaml.dump(
+        data,
+        Dumper=MinimalDumper,
+        default_flow_style=False,
+        sort_keys=sort_keys,
+        allow_unicode=True,
+        indent=indent,
+        width=line_width,
+    )

lionherd_core/libs/schema_handlers/_schema_to_model.py

@@ -0,0 +1,251 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import importlib.util
+import string
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, TypeVar
+
+from pydantic import BaseModel, PydanticUserError
+
+from lionherd_core import ln
+
+B = TypeVar("B", bound=BaseModel)
+
+
+def _get_python_version_enum(python_version_module: Any) -> Any:
+    """Auto-detect Python version from environment."""
+    version_info = sys.version_info
+    version_map = {
+        (3, 11): "PY_311",
+        (3, 12): "PY_312",
+        (3, 13): "PY_313",
+        (3, 14): "PY_314",
+    }
+    version_key = (version_info.major, version_info.minor)
+    enum_name = version_map.get(version_key, "PY_312")
+    return getattr(python_version_module, enum_name, python_version_module.PY_312)
+
+
+def _sanitize_model_name(name: str) -> str:
+    """Extract valid Python identifier from string.
+
+    Raises:
+        ValueError: If name cannot be converted to valid Python identifier.
+    """
+    valid_chars = string.ascii_letters + string.digits + "_"
+    sanitized = "".join(c for c in name.replace(" ", "") if c in valid_chars)
+
+    if not sanitized or not sanitized[0].isalpha():
+        msg = f"Cannot extract valid Python identifier from: {name!r}"
+        raise ValueError(msg)
+
+    return sanitized
+
+
+def _extract_model_name_from_schema(schema_dict: dict[str, Any], default: str) -> str:
+    """Extract model name from schema title or use default."""
+    title = schema_dict.get("title")
+    if title and isinstance(title, str):
+        try:
+            return _sanitize_model_name(title)
+        except ValueError:
+            pass  # Fall back to default if title cannot be sanitized
+    return default
+
+
+def _prepare_schema_input(
+    schema: str | dict[str, Any],
+    model_name: str,
+) -> tuple[str, dict[str, Any], str]:
+    """Convert schema to JSON string and extract model name."""
+    if isinstance(schema, dict):
+        try:
+            schema_dict = schema
+            schema_json = ln.json_dumps(schema_dict)
+        except TypeError as e:
+            msg = "Invalid dictionary provided for schema"
+            raise ValueError(msg) from e
+    elif isinstance(schema, str):
+        try:
+            schema_dict = ln.to_dict(schema)
+        except Exception as e:
+            msg = "Invalid JSON schema string provided"
+            raise ValueError(msg) from e
+        schema_json = schema
+    else:
+        msg = "Schema must be a JSON string or a dictionary"
+        raise TypeError(msg)
+
+    resolved_name = _extract_model_name_from_schema(schema_dict, model_name)
+    return schema_json, schema_dict, resolved_name
+
+
+def _generate_model_code(
+    schema_json: str,
+    output_file: Path,
+    pydantic_version: Any,
+    python_version: Any,
+    generate_func: Any,
+    input_file_type_enum: Any,
+) -> None:
+    """Generate Pydantic model code from schema."""
+    try:
+        generate_func(
+            schema_json,
+            input_file_type=input_file_type_enum.JsonSchema,
+            input_filename="schema.json",
+            output=output_file,
+            output_model_type=pydantic_version,
+            target_python_version=python_version,
+            base_class="pydantic.BaseModel",
+        )
+    except Exception as e:
+        msg = "Failed to generate model code from schema"
+        raise RuntimeError(msg) from e
+
+
+def _load_generated_module(output_file: Path, module_name: str) -> Any:
+    """Dynamically import generated Python module."""
+    if not output_file.exists():
+        msg = f"Generated model file not created: {output_file}"
+        raise FileNotFoundError(msg)
+
+    spec = importlib.util.spec_from_file_location(module_name, str(output_file))
+    if spec is None or spec.loader is None:
+        msg = f"Could not create module spec for {output_file}"
+        raise ImportError(msg)
+
+    module = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(module)
+    except Exception as e:
+        msg = f"Failed to load generated module from {output_file}"
+        raise RuntimeError(msg) from e
+
+    return module
+
+
+def _extract_model_class(
+    module: Any,
+    model_name: str,
+    output_file: Path,
+) -> type[BaseModel]:
+    """Find BaseModel class in generated module."""
+
+    def _is_valid_model(obj: Any) -> bool:
+        return isinstance(obj, type) and issubclass(obj, BaseModel)
+
+    try:
+        model_class = getattr(module, model_name)
+        if not _is_valid_model(model_class):
+            msg = f"'{model_name}' is not a Pydantic BaseModel class"
+            raise TypeError(msg)
+        return model_class
+    except AttributeError:
+        pass
+
+    # Fallback to 'Model'
+    try:
+        model_class = module.Model
+        if not _is_valid_model(model_class):
+            msg = "Fallback 'Model' is not a Pydantic BaseModel class"
+            raise TypeError(msg)
+        return model_class
+    except AttributeError:
+        pass
+
+    # List available models for debugging
+    available = [
+        attr
+        for attr in dir(module)
+        if _is_valid_model(getattr(module, attr, None)) and getattr(module, attr) is not BaseModel
+    ]
+    msg = (
+        f"Could not find '{model_name}' or 'Model' in {output_file}. "
+        f"Available BaseModel classes: {available}"
+    )
+    raise AttributeError(msg)
+
+
+def _rebuild_model(model_class: type[BaseModel], module: Any, model_name: str) -> None:
+    """Rebuild model with proper type resolution."""
+    try:
+        model_class.model_rebuild(_types_namespace=module.__dict__, force=True)
+    except (PydanticUserError, NameError) as e:
+        msg = f"Type resolution failed during rebuild for {model_name}"
+        raise RuntimeError(msg) from e
+    except Exception as e:
+        msg = f"Unexpected error during model_rebuild for {model_name}"
+        raise RuntimeError(msg) from e
+
+
+def load_pydantic_model_from_schema(
+    schema: str | dict[str, Any],
+    model_name: str = "DynamicModel",
+    /,
+    pydantic_version: Any = None,
+    python_version: Any = None,
+) -> type[BaseModel]:
+    """Generate Pydantic model dynamically from JSON schema.
+
+    Creates model class via datamodel-code-generator, imports it,
+    and rebuilds with proper type resolution.
+
+    Args:
+        schema: JSON schema (string or dict)
+        model_name: Base name for model (schema title takes precedence)
+        pydantic_version: DataModelType enum (default: PydanticV2BaseModel)
+        python_version: PythonVersion enum (default: PY_312)
+
+    Returns:
+        Dynamically created BaseModel class
+
+    Raises:
+        ImportError: datamodel-code-generator not installed
+        ValueError: Invalid schema format
+        TypeError: Invalid schema type
+        RuntimeError: Generation or loading failed
+
+    Example:
+        >>> schema = {"title": "User", "type": "object", ...}
+        >>> UserModel = load_pydantic_model_from_schema(schema)
+        >>> user = UserModel(name="Alice", age=30)
+    """
+    try:
+        from datamodel_code_generator import (
+            DataModelType,
+            InputFileType,
+            PythonVersion,
+            generate,
+        )
+    except ImportError as e:
+        msg = (
+            "datamodel-code-generator not installed. "
+            "Install with: pip install 'lionherd-core[schema-gen]' "
+            "or: pip install datamodel-code-generator"
+        )
+        raise ImportError(msg) from e
+
+    pydantic_version = pydantic_version or DataModelType.PydanticV2BaseModel
+    python_version = python_version or _get_python_version_enum(PythonVersion)
+
+    schema_json, _, resolved_name = _prepare_schema_input(schema, model_name)
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir_path = Path(tmpdir)
+        output_file = tmpdir_path / f"{resolved_name.lower()}_model_{hash(schema_json)}.py"
+        module_name = output_file.stem
+
+        _generate_model_code(
+            schema_json, output_file, pydantic_version, python_version, generate, InputFileType
+        )
+        module = _load_generated_module(output_file, module_name)
+        model_class = _extract_model_class(module, resolved_name, output_file)
+        _rebuild_model(model_class, module, resolved_name)
+
+        return model_class