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

krons/{specs → core/specs}/spec.py

@@ -11,15 +11,15 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Annotated, Any, Self
 
-from krons.protocols import Hashable, implements
-from krons.types._sentinel import (
+from krons.core.types._sentinel import (
     MaybeUndefined,
     Undefined,
     is_sentinel,
     is_undefined,
     not_sentinel,
 )
-from krons.types.base import Enum, Meta
+from krons.core.types.base import Enum, Meta
+from krons.protocols import Hashable, implements
 from krons.utils.concurrency import is_coro_func
 
 # Global cache for annotated types with bounded size
@@ -64,13 +64,17 @@ class CommonMeta(Enum):
         errors: list[Exception] = []
 
         if kw.get("default") and kw.get("default_factory"):
-            errors.append(ValueError("Cannot provide both 'default' and 'default_factory'"))
+            errors.append(
+                ValueError("Cannot provide both 'default' and 'default_factory'")
+            )
         if (_df := kw.get("default_factory")) and not callable(_df):
             errors.append(ValueError("'default_factory' must be callable"))
         if _val := kw.get("validator"):
             _val = [_val] if not isinstance(_val, list) else _val
             if not all(callable(v) for v in _val):
-                errors.append(ValueError("Validators must be a list of functions or a function"))
+                errors.append(
+                    ValueError("Validators must be a list of functions or a function")
+                )
 
         if errors:
             raise ExceptionGroup("Metadata validation failed", errors)
@@ -192,7 +196,9 @@ class Spec:
                 or isinstance(base_type, types.UnionType)
             )
             if not is_valid_type:
-                raise ValueError(f"base_type must be a type or type annotation, got {base_type}")
+                raise ValueError(
+                    f"base_type must be a type or type annotation, got {base_type}"
+                )
 
         if kw.get("default_factory") and is_coro_func(kw["default_factory"]):
             import warnings
@@ -389,7 +395,9 @@ class Spec:
 
         return spec
 
-    def with_validator(self, validator: Callable[..., Any] | list[Callable[..., Any]]) -> Self:
+    def with_validator(
+        self, validator: Callable[..., Any] | list[Callable[..., Any]]
+    ) -> Self:
         """Return new Spec with validator function(s) attached."""
         return self.with_updates(validator=validator)
 
@@ -407,7 +415,7 @@ class Spec:
         if not is_undefined(fk):
             from uuid import UUID
 
-            from krons.types.db_types import FKMeta
+            from krons.core.types.db_types import FKMeta
 
             t_ = Annotated[UUID, FKMeta(fk)]  # type: ignore[valid-type]
         if self.is_listable:
@@ -431,7 +439,9 @@ class Spec:
                 _annotated_cache.move_to_end(cache_key)
                 return _annotated_cache[cache_key]
 
-            actual_type = Any if is_sentinel(self.base_type, {"none"}) else self.base_type
+            actual_type = (
+                Any if is_sentinel(self.base_type, {"none"}) else self.base_type
+            )
             current_metadata = self.metadata
 
             # Resolve FK target (explicit or Observable base_type)
@@ -440,7 +450,7 @@ class Spec:
             if not is_undefined(resolved_fk):
                 from uuid import UUID
 
-                from krons.types.db_types import FKMeta
+                from krons.core.types.db_types import FKMeta
 
                 actual_type = UUID  # FK fields are UUID references
                 extra_annotations.append(FKMeta(resolved_fk))
@@ -475,7 +485,9 @@ class Spec:
             exclude = set()
         if exclude_common:
             exclude = exclude | set(CommonMeta.allowed())
-        return {meta.key: meta.value for meta in self.metadata if meta.key not in exclude}
+        return {
+            meta.key: meta.value for meta in self.metadata if meta.key not in exclude
+        }
 
 
 def _is_observable(cls: type) -> bool:

krons/{types → core/types}/base.py

@@ -111,7 +111,9 @@ class _SentinelMixin:
         """Return set of valid field names (excludes private/ClassVar)."""
         if cls._allowed_keys:
             return cls._allowed_keys
-        cls._allowed_keys = set(f.name for f in fields(cls) if not f.name.startswith("_"))
+        cls._allowed_keys = set(
+            f.name for f in fields(cls) if not f.name.startswith("_")
+        )
         return cls._allowed_keys
 
     @classmethod
@@ -353,7 +355,7 @@ class HashableModel(_PydanticBaseModel):
     as DataClass but for Pydantic models.
 
     Usage:
-        class ServiceConfig(HashableModel):
+        class ResourceConfig(HashableModel):
             provider: str
             name: str
     """

krons/{types → core/types}/db_types.py

@@ -18,7 +18,7 @@ import types
 from typing import Annotated, Any, Literal, Union, get_args, get_origin
 from uuid import UUID
 
-from krons.types._sentinel import Unset, UnsetType, not_sentinel
+from krons.core.types._sentinel import Unset, UnsetType, not_sentinel
 
 
 def _is_field_info(obj: Any) -> bool:
@@ -237,7 +237,7 @@ def extract_kron_db_meta(
 
     else:
         # Try Spec (lazy import to avoid circular)
-        from krons.specs.spec import Spec
+        from krons.core.specs.spec import Spec
 
         if isinstance(from_, Spec):
             if metas in ("FK", "BOTH"):

krons/errors.py

@@ -3,7 +3,7 @@
 
 """Kron exception hierarchy with structured details and retryability.
 
-All exceptions inherit from KronError and include:
+All exceptions inherit from KronsError and include:
     - message: Human-readable description
     - details: Structured context dict
     - retryable: Whether retry might succeed
@@ -23,7 +23,7 @@ __all__ = (
     "ExecutionError",
     "ExistsError",
     "KronConnectionError",
-    "KronError",
+    "KronsError",
     "KronTimeoutError",
     "NotFoundError",
     "OperationError",
@@ -33,7 +33,7 @@ __all__ = (
 
 
 @implements(Serializable)
-class KronError(Exception):
+class KronsError(Exception):
     """Base exception for kron. Serializable with structured details.
 
     Subclasses set default_message and default_retryable.
@@ -76,70 +76,70 @@ class KronError(Exception):
         }
 
 
-class ValidationError(KronError):
+class ValidationError(KronsError):
     """Data validation failure. Raise when input fails schema/constraint checks."""
 
     default_message = "Validation failed"
     default_retryable = False
 
 
-class AccessError(KronError):
+class AccessError(KronsError):
     """Permission denied. Raise when capability/resource access is blocked."""
 
     default_message = "Access denied"
     default_retryable = False
 
 
-class ConfigurationError(KronError):
+class ConfigurationError(KronsError):
     """Invalid configuration. Raise when setup/config is incorrect."""
 
     default_message = "Configuration error"
     default_retryable = False
 
 
-class ExecutionError(KronError):
+class ExecutionError(KronsError):
     """Execution failure. Raise when Event/Calling invoke fails (often transient)."""
 
     default_message = "Execution failed"
     default_retryable = True
 
 
-class KronConnectionError(KronError):
+class KronConnectionError(KronsError):
     """Network/connection failure. Named to avoid shadowing builtins."""
 
     default_message = "Connection error"
     default_retryable = True
 
 
-class KronTimeoutError(KronError):
+class KronTimeoutError(KronsError):
     """Operation timeout. Named to avoid shadowing builtins."""
 
     default_message = "Operation timed out"
     default_retryable = True
 
 
-class NotFoundError(KronError):
+class NotFoundError(KronsError):
     """Resource/item not found. Raise when lookup fails."""
 
     default_message = "Item not found"
     default_retryable = False
 
 
-class ExistsError(KronError):
+class ExistsError(KronsError):
     """Duplicate item. Raise when creating item that already exists."""
 
     default_message = "Item already exists"
     default_retryable = False
 
 
-class QueueFullError(KronError):
+class QueueFullError(KronsError):
     """Capacity exceeded. Raise when queue/buffer is full."""
 
     default_message = "Queue is full"
     default_retryable = True
 
 
-class OperationError(KronError):
+class OperationError(KronsError):
     """Generic operation failure. Use for unclassified operation errors."""
 
     default_message = "Operation failed"

krons/protocols.py

@@ -179,7 +179,9 @@ def _check_signature_compatibility(
     # If protocol accepts **kwargs, implementation must also accept them
     # Otherwise callers passing kwargs (allowed by protocol) will fail
     if proto_has_var_keyword and not impl_has_var_keyword:
-        errors.append("  - 'kwargs': protocol accepts **kwargs but implementation doesn't")
+        errors.append(
+            "  - 'kwargs': protocol accepts **kwargs but implementation doesn't"
+        )
 
     # If protocol accepts *args, implementation must also accept them
     if proto_has_var_positional and not impl_has_var_positional:
@@ -277,10 +279,12 @@ def _check_signature_compatibility(
             if param_name not in protocol_params:
                 # Check if protocol has *args or **kwargs that could provide it
                 proto_has_var_positional = any(
-                    p.kind == inspect.Parameter.VAR_POSITIONAL for p in protocol_params.values()
+                    p.kind == inspect.Parameter.VAR_POSITIONAL
+                    for p in protocol_params.values()
                 )
                 proto_has_var_keyword = any(
-                    p.kind == inspect.Parameter.VAR_KEYWORD for p in protocol_params.values()
+                    p.kind == inspect.Parameter.VAR_KEYWORD
+                    for p in protocol_params.values()
                 )
 
                 can_satisfy = False
@@ -396,7 +400,8 @@ def implements(
                         if errors:
                             error_msg = (
                                 f"{cls.__name__}.{member_name} signature incompatible "
-                                f"with {protocol.__name__}.{member_name}:\n" + "\n".join(errors)
+                                f"with {protocol.__name__}.{member_name}:\n"
+                                + "\n".join(errors)
                             )
                             all_signature_errors.append(error_msg)
 

krons/resource/__init__.py

@@ -0,0 +1,89 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Resources module: iModel, ResourceBackend, hooks, and registry.
+
+Core exports:
+- iModel: Unified resource interface with rate limiting and hooks
+- ResourceBackend/Endpoint: Backend abstractions for API calls
+- HookRegistry/HookEvent/HookPhase: Lifecycle hook system
+- ResourceRegistry: O(1) name-based resource lookup
+
+Uses lazy loading for fast import.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Lazy import mapping
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "Calling": ("krons.resource.backend", "Calling"),
+    "NormalizedResponse": ("krons.resource.backend", "NormalizedResponse"),
+    "NormalizedResponseModel": ("krons.resource.backend", "NormalizedResponseModel"),
+    "ResourceBackend": ("krons.resource.backend", "ResourceBackend"),
+    "ResourceConfig": ("krons.resource.backend", "ResourceConfig"),
+    "ResourceRegistry": ("krons.resource.registry", "ResourceRegistry"),
+    "iModel": ("krons.resource.imodel", "iModel"),
+    "Endpoint": ("krons.resource.endpoint", "Endpoint"),
+    "EndpointConfig": ("krons.resource.endpoint", "EndpointConfig"),
+    "APICalling": ("krons.resource.endpoint", "APICalling"),
+    "HookRegistry": ("krons.resource.hook", "HookRegistry"),
+    "HookEvent": ("krons.resource.hook", "HookEvent"),
+    "HookPhase": ("krons.resource.hook", "HookPhase"),
+}
+
+_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.resource' 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 .backend import (
+        Calling,
+        NormalizedResponse,
+        NormalizedResponseModel,
+        ResourceBackend,
+        ResourceConfig,
+    )
+    from .endpoint import APICalling, Endpoint, EndpointConfig
+    from .hook import HookEvent, HookPhase, HookRegistry
+    from .imodel import iModel
+    from .registry import ResourceRegistry
+
+__all__ = (
+    "APICalling",
+    "Calling",
+    "Endpoint",
+    "EndpointConfig",
+    "HookEvent",
+    "HookPhase",
+    "HookRegistry",
+    "NormalizedResponse",
+    "NormalizedResponseModel",
+    "ResourceBackend",
+    "ResourceConfig",
+    "ResourceRegistry",
+    "iModel",
+)

krons/{services → resource}/backend.py

@@ -5,12 +5,13 @@ from __future__ import annotations
 
 import logging
 from abc import abstractmethod
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 from pydantic import BaseModel, Field, PrivateAttr, field_validator, model_validator
 
 from krons.core import Element, Event, EventStatus
-from krons.types import HashableModel, Unset, UnsetType, is_sentinel
+from krons.core.types import HashableModel, Unset, UnsetType, is_sentinel, is_unset
+from krons.errors import ValidationError
 
 from .hook import HookBroadcaster, HookEvent, HookPhase, HookRegistry
 
@@ -32,7 +33,7 @@ def _get_schema_field_keys(cls: type[BaseModel]) -> set[str]:
     return _SCHEMA_FIELD_KEYS_CACHE[cls]
 
 
-class ServiceConfig(HashableModel):
+class ResourceConfig(HashableModel):
     provider: str = Field(..., min_length=4, max_length=50)
     name: str = Field(..., min_length=4, max_length=100)
     request_options: type[BaseModel] | None = Field(default=None, exclude=True)
@@ -73,18 +74,33 @@ class ServiceConfig(HashableModel):
             raise ValueError("Invalid payload") from e
 
 
-class NormalizedResponse(HashableModel):
-    """Generic normalized response for all service backends.
+@runtime_checkable
+class NormalizedResponse(Protocol):
+    status: str
+    data: Any
+    error: str | None
+    raw_response: dict[str, Any]
+    metadata: dict[str, Any] | None
+
+
+class NormalizedResponseModel(HashableModel):
+    """Generic normalized response for all resource backends.
 
     Works for any backend type: HTTP endpoints, tools, LLM APIs, etc.
-    Provides consistent interface regardless of underlying service.
+    Provides consistent interface regardless of underlying resource.
     """
 
     status: str = Field(..., description="Response status: 'success' or 'error'")
     data: Any = None
-    error: str | None = Field(default=None, description="Error message if status='error'")
-    raw_response: dict[str, Any] = Field(..., description="Original unmodified response")
-    metadata: dict[str, Any] | None = Field(default=None, description="Provider-specific metadata")
+    error: str | None = Field(
+        default=None, description="Error message if status='error'"
+    )
+    raw_response: dict[str, Any] = Field(
+        ..., description="Original unmodified response"
+    )
+    metadata: dict[str, Any] | None = Field(
+        default=None, description="Provider-specific metadata"
+    )
 
     def _to_dict(self, **kwargs: Any) -> dict[str, Any]:
         """Convert to dict, excluding None values."""
@@ -95,14 +111,16 @@ class Calling(Event):
     """Base calling event with hook support.
 
     Extends kron.Event with pre/post invocation hooks.
-    Always delegates to backend.call() for actual service invocation.
+    Always delegates to backend.call() for actual resource invocation.
 
     Attributes:
-        backend: ServiceBackend instance (Tool, Endpoint, etc.)
+        backend: ResourceBackend instance (Tool, Endpoint, etc.)
         payload: Request payload/arguments for backend call
     """
 
-    backend: ServiceBackend = Field(..., exclude=True, description="Service backend instance")
+    backend: ResourceBackend = Field(
+        ..., exclude=True, description="Resource backend instance"
+    )
     payload: dict[str, Any] = Field(..., description="Request payload/arguments")
     _pre_invoke_hook_event: HookEvent | None = PrivateAttr(None)
     _post_invoke_hook_event: HookEvent | None = PrivateAttr(None)
@@ -158,7 +176,7 @@ class Calling(Event):
                 )
             await HookBroadcaster.broadcast(h_ev)
 
-        # Actual service call via backend (post-hook runs in finally)
+        # Actual resource call via backend (post-hook runs in finally)
         try:
             response = await self.backend.call(**self.call_args)
             return response
@@ -217,15 +235,23 @@ class Calling(Event):
         )
         self._post_invoke_hook_event = h_ev
 
+    def assert_is_normalized(self) -> None:
+        """Assert that response is normalized."""
+        self.assert_completed()
+        if is_unset(self.execution.response):
+            raise ValidationError("Calling response is not set")
+        if not isinstance(self.execution.response, NormalizedResponse):
+            raise ValidationError("Calling response is not normalized")
+
 
-class ServiceBackend(Element):
-    """Base class for all service backends (Tool, Endpoint, etc.).
+class ResourceBackend(Element):
+    """Base class for all resource backends (Tool, Endpoint, etc.).
 
     Inherits from krons.Element for UUID-based identity.
     Subclasses must implement event_type and call() methods.
     """
 
-    config: ServiceConfig = Field(..., description="Service configuration")
+    config: ResourceConfig = Field(..., description="Resource configuration")
 
     @property
     def provider(self) -> str:
@@ -234,17 +260,17 @@ class ServiceBackend(Element):
 
     @property
     def name(self) -> str:
-        """Service name from config."""
+        """Resource name from config."""
         return self.config.name
 
     @property
     def version(self) -> str | None:
-        """Service version from config."""
+        """Resource version from config."""
         return self.config.version
 
     @property
     def tags(self) -> set[str]:
-        """Service tags from config."""
+        """Resource tags from config."""
         return set(self.config.tags) if self.config.tags else set()
 
     @property
@@ -265,12 +291,12 @@ class ServiceBackend(Element):
         to extract specific fields or add metadata.
 
         Args:
-            raw_response: Raw response from service call
+            raw_response: Raw response from resource call
 
         Returns:
             NormalizedResponse with status, data, raw_response
         """
-        return NormalizedResponse(
+        return NormalizedResponseModel(
             status="success",
             data=raw_response,
             raw_response=raw_response,
@@ -278,7 +304,7 @@ class ServiceBackend(Element):
 
     @abstractmethod
     async def call(self, *args, **kw) -> NormalizedResponse:
-        """Execute service call and return normalized response."""
+        """Execute resource call and return normalized response."""
         ...
 
     async def stream(self, *args, **kw):

krons/{services → resource}/endpoint.py

@@ -44,7 +44,7 @@ from pydantic import (
     model_validator,
 )
 
-from .backend import Calling, NormalizedResponse, ServiceBackend, ServiceConfig
+from .backend import Calling, NormalizedResponse, ResourceBackend, ResourceConfig
 from .utilities.header_factory import AUTH_TYPES, HeaderFactory
 from .utilities.resilience import CircuitBreaker, RetryConfig, retry_with_backoff
 
@@ -81,10 +81,10 @@ SYSTEM_ENV_VARS = frozenset(
 B = TypeVar("B", bound=type[BaseModel])
 
 
-class EndpointConfig(ServiceConfig):
+class EndpointConfig(ResourceConfig):
     """HTTP endpoint configuration with secure credential handling.
 
-    Extends ServiceConfig with HTTP-specific settings: URL construction,
+    Extends ResourceConfig with HTTP-specific settings: URL construction,
     authentication, headers, and request validation.
 
     Credential Security:
@@ -175,7 +175,9 @@ class EndpointConfig(ServiceConfig):
                     object.__setattr__(self, "_api_key", SecretStr(resolved.strip()))
                 else:
                     object.__setattr__(self, "api_key_is_env", False)
-                    object.__setattr__(self, "_api_key", SecretStr(self.api_key.strip()))
+                    object.__setattr__(
+                        self, "_api_key", SecretStr(self.api_key.strip())
+                    )
                     object.__setattr__(self, "api_key", None)
             else:
                 object.__setattr__(self, "api_key_is_env", False)
@@ -204,7 +206,7 @@ class EndpointConfig(ServiceConfig):
         return f"{self.base_url}/{self.endpoint.format(**self.params)}"
 
 
-class Endpoint(ServiceBackend):
+class Endpoint(ResourceBackend):
     """HTTP API backend with resilience patterns.
 
     Wraps httpx.AsyncClient with circuit breaker and retry support.
@@ -252,7 +254,9 @@ class Endpoint(ServiceBackend):
         secret_api_key = None
         if isinstance(config, dict):
             config_dict = {**config, **kwargs}
-            if "api_key" in config_dict and isinstance(config_dict["api_key"], SecretStr):
+            if "api_key" in config_dict and isinstance(
+                config_dict["api_key"], SecretStr
+            ):
                 secret_api_key = config_dict.pop("api_key")
             _config = EndpointConfig(**config_dict)
         elif isinstance(config, EndpointConfig):
@@ -321,7 +325,11 @@ class Endpoint(ServiceBackend):
         Raises:
             ValueError: If request_options not defined or validation fails.
         """
-        request = request if isinstance(request, dict) else request.model_dump(exclude_none=True)
+        request = (
+            request
+            if isinstance(request, dict)
+            else request.model_dump(exclude_none=True)
+        )
 
         payload = self.config.kwargs.copy()
         payload.update(request)
@@ -397,7 +405,9 @@ class Endpoint(ServiceBackend):
 
         if self.circuit_breaker:
 
-            async def cb_wrapped_call(p: dict[Any, Any], h: dict[Any, Any], **kw: Any) -> Any:
+            async def cb_wrapped_call(
+                p: dict[Any, Any], h: dict[Any, Any], **kw: Any
+            ) -> Any:
                 return await self.circuit_breaker.execute(base_call, p, h, **kw)  # type: ignore[union-attr]
 
             inner_call = cb_wrapped_call
@@ -435,9 +445,7 @@ class Endpoint(ServiceBackend):
             elif response.status_code != 200:
                 try:
                     error_body = response.json()
-                    error_message = (
-                        f"Request failed with status {response.status_code}: {error_body}"
-                    )
+                    error_message = f"Request failed with status {response.status_code}: {error_body}"
                 except Exception:
                     error_message = f"Request failed with status {response.status_code}"
 
@@ -467,7 +475,9 @@ class Endpoint(ServiceBackend):
         """
         payload, headers = self.create_payload(request, extra_headers, **kwargs)
 
-        async for chunk in self._stream_http(payload=payload, headers=headers, **kwargs):
+        async for chunk in self._stream_http(
+            payload=payload, headers=headers, **kwargs
+        ):
             yield chunk
 
     async def _stream_http(self, payload: dict, headers: dict, **kwargs):
@@ -507,7 +517,9 @@ class Endpoint(ServiceBackend):
         return circuit_breaker.to_dict()
 
     @field_serializer("retry_config")
-    def _serialize_retry_config(self, retry_config: RetryConfig | None) -> dict[str, Any] | None:
+    def _serialize_retry_config(
+        self, retry_config: RetryConfig | None
+    ) -> dict[str, Any] | None:
         """Serialize RetryConfig to dict for transport."""
         if retry_config is None:
             return None
@@ -522,7 +534,9 @@ class Endpoint(ServiceBackend):
         if isinstance(v, CircuitBreaker):
             return v
         if not isinstance(v, dict):
-            raise ValueError("circuit_breaker must be a dict or CircuitBreaker instance")
+            raise ValueError(
+                "circuit_breaker must be a dict or CircuitBreaker instance"
+            )
         return CircuitBreaker(**v)
 
     @field_validator("retry_config", mode="before")