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

{kronos/services → krons/resource}/imodel.py

@@ -7,11 +7,11 @@ from typing import TYPE_CHECKING, Any
 
 from pydantic import Field, field_serializer, field_validator
 
-from kronos.core import Element, Executor
-from kronos.protocols import Invocable, implements
-from kronos.utils.concurrency import sleep
+from krons.core import Element, Executor
+from krons.protocols import Invocable, implements
+from krons.utils.concurrency import sleep
 
-from .backend import ServiceBackend
+from .backend import ResourceBackend
 from .endpoint import Endpoint
 from .hook import HookRegistry
 from .utilities.rate_limited_executor import RateLimitedExecutor
@@ -26,14 +26,14 @@ __all__ = ("iModel",)
 
 @implements(Invocable)
 class iModel(Element):  # noqa: N801
-    """Unified service interface wrapping ServiceBackend with rate limiting and hooks.
+    """Unified resource interface wrapping ResourceBackend with rate limiting and hooks.
 
-    Combines ServiceBackend (API abstraction) with optional:
+    Combines ResourceBackend (API abstraction) with optional:
     - Rate limiting: TokenBucket (simple) or Executor (event-driven)
     - Hook registry: Lifecycle callbacks at PreEventCreate/PreInvocation/PostInvocation
 
     Attributes:
-        backend: ServiceBackend instance (e.g., Endpoint for HTTP APIs).
+        backend: ResourceBackend instance (e.g., Endpoint for HTTP APIs).
         rate_limiter: Optional TokenBucket for simple blocking rate limits.
         executor: Optional Executor for event-driven processing with rate limiting.
         hook_registry: Optional HookRegistry for invocation lifecycle callbacks.
@@ -43,9 +43,9 @@ class iModel(Element):  # noqa: N801
     _EXECUTOR_POLL_TIMEOUT_ITERATIONS = 100
     _EXECUTOR_POLL_SLEEP_INTERVAL = 0.1
 
-    backend: ServiceBackend | None = Field(
+    backend: ResourceBackend | None = Field(
         None,
-        description="ServiceBackend instance (e.g., Endpoint)",
+        description="ResourceBackend instance (e.g., Endpoint)",
     )
 
     rate_limiter: TokenBucket | None = Field(
@@ -70,7 +70,7 @@ class iModel(Element):  # noqa: N801
 
     def __init__(
         self,
-        backend: ServiceBackend,
+        backend: ResourceBackend,
         rate_limiter: TokenBucket | None = None,
         executor: Executor | None = None,
         hook_registry: HookRegistry | None = None,
@@ -78,10 +78,10 @@ class iModel(Element):  # noqa: N801
         capacity_refresh_time: float = 60,
         limit_requests: int | None = None,
     ):
-        """Initialize iModel with ServiceBackend.
+        """Initialize iModel with ResourceBackend.
 
         Args:
-            backend: ServiceBackend instance (required).
+            backend: ResourceBackend instance (required).
             rate_limiter: TokenBucket for simple blocking rate limits.
             executor: Executor for event-driven processing.
             hook_registry: HookRegistry for lifecycle callbacks.
@@ -114,21 +114,21 @@ class iModel(Element):  # noqa: N801
 
     @property
     def name(self) -> str:
-        """Service name from backend."""
+        """Resource name from backend."""
         if self.backend is None:
             raise RuntimeError("Backend not configured")
         return self.backend.name
 
     @property
     def version(self) -> str:
-        """Service version from backend."""
+        """Resource version from backend."""
         if self.backend is None:
             raise RuntimeError("Backend not configured")
         return self.backend.version or ""
 
     @property
     def tags(self) -> set[str]:
-        """Service tags from backend."""
+        """Resource tags from backend."""
         if self.backend is None:
             raise RuntimeError("Backend not configured")
         return self.backend.tags
@@ -181,7 +181,11 @@ class iModel(Element):  # noqa: N801
                 hook_phase=HookPhase.PreEventCreate,
                 event_like=calling_type,
                 registry=self.hook_registry,
-                exit=(create_event_exit_hook if create_event_exit_hook is not None else False),
+                exit=(
+                    create_event_exit_hook
+                    if create_event_exit_hook is not None
+                    else False
+                ),
                 timeout=create_event_hook_timeout,
                 streaming=False,
                 params=create_event_hook_params or {},
@@ -194,11 +198,12 @@ class iModel(Element):  # noqa: N801
                 )
 
         payload = self.backend.create_payload(request=arguments)
+        # Handle backends that return (payload, headers) tuple
+        if isinstance(payload, tuple):
+            payload, _ = payload
         calling: Calling = calling_type(
             backend=self.backend,
             payload=payload,
-            timeout=timeout,
-            streaming=streaming,
         )
 
         if self.hook_registry is not None and self.hook_registry._can_handle(
@@ -206,7 +211,9 @@ class iModel(Element):  # noqa: N801
         ):
             calling.create_pre_invoke_hook(
                 hook_registry=self.hook_registry,
-                exit_hook=(pre_invoke_exit_hook if pre_invoke_exit_hook is not None else False),
+                exit_hook=(
+                    pre_invoke_exit_hook if pre_invoke_exit_hook is not None else False
+                ),
                 hook_timeout=pre_invoke_hook_timeout,
                 hook_params=pre_invoke_hook_params or {},
             )
@@ -216,7 +223,11 @@ class iModel(Element):  # noqa: N801
         ):
             calling.create_post_invoke_hook(
                 hook_registry=self.hook_registry,
-                exit_hook=(post_invoke_exit_hook if post_invoke_exit_hook is not None else False),
+                exit_hook=(
+                    post_invoke_exit_hook
+                    if post_invoke_exit_hook is not None
+                    else False
+                ),
                 hook_timeout=post_invoke_hook_timeout,
                 hook_params=post_invoke_hook_params or {},
             )
@@ -281,7 +292,8 @@ class iModel(Element):  # noqa: N801
             # Poll for completion (fast backends see ~100-200% overhead, slow backends <10%)
             interval = poll_interval or self._EXECUTOR_POLL_SLEEP_INTERVAL
             timeout_seconds = poll_timeout or (
-                self._EXECUTOR_POLL_TIMEOUT_ITERATIONS * self._EXECUTOR_POLL_SLEEP_INTERVAL
+                self._EXECUTOR_POLL_TIMEOUT_ITERATIONS
+                * self._EXECUTOR_POLL_SLEEP_INTERVAL
             )
             max_iterations = int(timeout_seconds / interval)
             ctr = 0
@@ -300,7 +312,9 @@ class iModel(Element):  # noqa: N801
                     f"Event aborted after 3 permission denials (rate limited): {calling.id}"
                 )
             elif calling.execution.status.value == "failed":
-                raise calling.execution.error or RuntimeError(f"Event failed: {calling.id}")
+                raise calling.execution.error or RuntimeError(
+                    f"Event failed: {calling.id}"
+                )
 
             self._store_claude_code_session_id(calling)
             return calling
@@ -317,7 +331,7 @@ class iModel(Element):  # noqa: N801
 
     def _store_claude_code_session_id(self, calling: Calling) -> None:
         """Extract and store Claude Code session_id for context continuation."""
-        from kronos.types import is_sentinel
+        from krons.core.types import is_sentinel
 
         from .backend import NormalizedResponse
 
@@ -334,7 +348,7 @@ class iModel(Element):  # noqa: N801
                     self.provider_metadata["session_id"] = session_id
 
     @field_serializer("backend")
-    def _serialize_backend(self, backend: ServiceBackend) -> dict[str, Any] | None:
+    def _serialize_backend(self, backend: ResourceBackend) -> dict[str, Any] | None:
         """Serialize backend to dict with kron_class for polymorphic restoration."""
         if backend is None:
             return None
@@ -384,24 +398,24 @@ class iModel(Element):  # noqa: N801
 
     @field_validator("backend", mode="before")
     @classmethod
-    def _deserialize_backend(cls, v: Any) -> ServiceBackend:
+    def _deserialize_backend(cls, v: Any) -> ResourceBackend:
         """Reconstruct backend via Element polymorphic deserialization."""
         if v is None:
             raise ValueError("backend is required")
 
-        if isinstance(v, ServiceBackend):
+        if isinstance(v, ResourceBackend):
             return v
 
         if not isinstance(v, dict):
-            raise ValueError("backend must be a dict or ServiceBackend instance")
+            raise ValueError("backend must be a dict or ResourceBackend instance")
 
-        from kronos.core import Element
+        from krons.core import Element
 
         backend = Element.from_dict(v)
 
-        if not isinstance(backend, ServiceBackend):
+        if not isinstance(backend, ResourceBackend):
             raise ValueError(
-                f"Deserialized backend must be ServiceBackend subclass, got: {type(backend).__name__}"
+                f"Deserialized backend must be ResourceBackend subclass, got: {type(backend).__name__}"
             )
         return backend
 
@@ -420,9 +434,13 @@ class iModel(Element):  # noqa: N801
 
         config = {**v}
         if "request_bucket" in config and isinstance(config["request_bucket"], dict):
-            config["request_bucket"] = TokenBucket(RateLimitConfig(**config["request_bucket"]))
+            config["request_bucket"] = TokenBucket(
+                RateLimitConfig(**config["request_bucket"])
+            )
         if "token_bucket" in config and isinstance(config["token_bucket"], dict):
-            config["token_bucket"] = TokenBucket(RateLimitConfig(**config["token_bucket"]))
+            config["token_bucket"] = TokenBucket(
+                RateLimitConfig(**config["token_bucket"])
+            )
 
         return RateLimitedExecutor(processor_config=config)
 

{kronos/services → krons/resource}/registry.py

@@ -6,24 +6,24 @@ from __future__ import annotations
 from typing import Any
 from uuid import UUID
 
-from kronos.core import Pile
-from kronos.types import Undefined, UndefinedType, is_sentinel
+from krons.core import Pile
+from krons.core.types import Undefined, UndefinedType, is_sentinel
 
 from .imodel import iModel
 
-__all__ = ("ServiceRegistry",)
+__all__ = ("ResourceRegistry",)
 
 
-class ServiceRegistry:
-    """Service registry managing iModel instances with O(1) name-based lookup.
+class ResourceRegistry:
+    """Resource registry managing iModel instances with O(1) name-based lookup.
 
     Provides type-safe storage via Pile[iModel] with name-based indexing.
-    Services must have unique names; duplicates raise ValueError unless update=True.
+    Resources must have unique names; duplicates raise ValueError unless update=True.
 
     Example:
-        >>> registry = ServiceRegistry()
+        >>> registry = ResourceRegistry()
         >>> registry.register(iModel(backend=my_endpoint))
-        >>> model = registry.get("my_service")
+        >>> model = registry.get("my_resource")
         >>> tagged = registry.list_by_tag("api")
     """
 
@@ -39,17 +39,17 @@ class ServiceRegistry:
 
         Args:
             model: iModel instance to register.
-            update: If True, replaces existing service with same name.
+            update: If True, replaces existing resource with same name.
 
         Returns:
-            UUID of registered service.
+            UUID of registered resource.
 
         Raises:
-            ValueError: If service name exists and update=False.
+            ValueError: If resource name exists and update=False.
         """
         if model.name in self._name_index:
             if not update:
-                raise ValueError(f"Service '{model.name}' already registered")
+                raise ValueError(f"Resource '{model.name}' already registered")
             # Update: remove old, add new
             old_uid = self._name_index[model.name]
             self._pile.remove(old_uid)
@@ -60,15 +60,17 @@ class ServiceRegistry:
         return model.id
 
     def unregister(self, name: str) -> iModel:
-        """Remove and return service by name. Raises KeyError if not found."""
+        """Remove and return resource by name. Raises KeyError if not found."""
         if name not in self._name_index:
-            raise KeyError(f"Service '{name}' not found")
+            raise KeyError(f"Resource '{name}' not found")
 
         uid = self._name_index.pop(name)
         return self._pile.remove(uid)
 
-    def get(self, name: str | UUID | iModel, default: Any | UndefinedType = Undefined) -> iModel:
-        """Get service by name, UUID, or return iModel passthrough. Raises KeyError if not found."""
+    def get(
+        self, name: str | UUID | iModel, default: Any | UndefinedType = Undefined
+    ) -> iModel:
+        """Get resource by name, UUID, or return iModel passthrough. Raises KeyError if not found."""
         if isinstance(name, UUID):
             return self._pile[name]
         if isinstance(name, iModel):
@@ -76,40 +78,40 @@ class ServiceRegistry:
         if name not in self._name_index:
             if not is_sentinel(default):
                 return default
-            raise KeyError(f"Service '{name}' not found")
+            raise KeyError(f"Resource '{name}' not found")
 
         uid = self._name_index[name]
         return self._pile[uid]
 
     def has(self, name: str) -> bool:
-        """Check if service exists."""
+        """Check if resource exists."""
         return name in self._name_index
 
     def list_names(self) -> list[str]:
-        """List all registered service names."""
+        """List all registered resource names."""
         return list(self._name_index.keys())
 
     def list_by_tag(self, tag: str) -> Pile[iModel]:
-        """Filter services by tag, returns Pile of matching iModels."""
+        """Filter resources by tag, returns Pile of matching iModels."""
         return self._pile[lambda m: tag in m.tags]
 
     def count(self) -> int:
-        """Count registered services."""
+        """Count registered resources."""
         return len(self._pile)
 
     def clear(self) -> None:
-        """Remove all registered services."""
+        """Remove all registered resources."""
         self._pile.clear()
         self._name_index.clear()
 
     def __len__(self) -> int:
-        """Return number of registered services."""
+        """Return number of registered resources."""
         return len(self._pile)
 
     def __contains__(self, name: str) -> bool:
-        """Check if service exists (supports `name in registry`)."""
+        """Check if resource exists (supports `name in registry`)."""
         return name in self._name_index
 
     def __repr__(self) -> str:
         """String representation."""
-        return f"ServiceRegistry(count={len(self)})"
+        return f"ResourceRegistry(count={len(self)})"

{kronos/services → krons/resource}/utilities/rate_limited_executor.py

@@ -14,16 +14,16 @@ from typing import TYPE_CHECKING, Any, Self
 
 from typing_extensions import override
 
-from kronos.core import Event, Executor, Processor
-from kronos.services.endpoint import APICalling
-from kronos.utils.concurrency import get_cancelled_exc_class, sleep
+from krons.core import Event, Executor, Processor
+from krons.resource.endpoint import APICalling
+from krons.utils.concurrency import get_cancelled_exc_class, sleep
 
 from .rate_limiter import TokenBucket
 
 if TYPE_CHECKING:
     import asyncio
 
-    from kronos.core import Pile
+    from krons.core import Pile
 
 __all__ = ("RateLimitedExecutor", "RateLimitedProcessor")
 
@@ -213,8 +213,12 @@ class RateLimitedProcessor(Processor):
             "concurrency_limit": self.concurrency_limit,
             "max_queue_size": self.max_queue_size,
             "max_denial_tracking": self.max_denial_tracking,
-            "request_bucket": (self.request_bucket.to_dict() if self.request_bucket else None),
-            "token_bucket": (self.token_bucket.to_dict() if self.token_bucket else None),
+            "request_bucket": (
+                self.request_bucket.to_dict() if self.request_bucket else None
+            ),
+            "token_bucket": (
+                self.token_bucket.to_dict() if self.token_bucket else None
+            ),
         }
 
 

{kronos/services → krons/resource}/utilities/rate_limiter.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 import logging
 from dataclasses import dataclass
 
-from kronos.utils.concurrency import Lock, current_time, sleep
+from krons.utils.concurrency import Lock, current_time, sleep
 
 __all__ = ("RateLimitConfig", "TokenBucket")
 
@@ -105,7 +105,9 @@ class TokenBucket:
 
                 if self.tokens >= tokens:
                     self.tokens -= tokens
-                    logger.debug(f"Acquired {tokens} tokens, {self.tokens:.2f} remaining")
+                    logger.debug(
+                        f"Acquired {tokens} tokens, {self.tokens:.2f} remaining"
+                    )
                     return True
 
                 deficit = tokens - self.tokens

{kronos/services → krons/resource}/utilities/resilience.py

@@ -16,8 +16,8 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, TypedDict, TypeVar
 
-from kronos.errors import KronConnectionError
-from kronos.utils.concurrency import Lock, current_time, sleep
+from krons.errors import KronConnectionError
+from krons.utils.concurrency import Lock, current_time, sleep
 
 
 class _MetricsDict(TypedDict):
@@ -199,7 +199,9 @@ class CircuitBreaker:
                 if now - self.last_failure_time >= self.recovery_time:
                     await self._change_state(CircuitState.HALF_OPEN)
                 else:
-                    recovery_remaining = self.recovery_time - (now - self.last_failure_time)
+                    recovery_remaining = self.recovery_time - (
+                        now - self.last_failure_time
+                    )
                     self._metrics["rejected_count"] += 1
 
                     logger.warning(
@@ -223,7 +225,9 @@ class CircuitBreaker:
 
             return True, 0.0
 
-    async def execute(self, func: Callable[..., Awaitable[T]], *args: Any, **kwargs: Any) -> T:
+    async def execute(
+        self, func: Callable[..., Awaitable[T]], *args: Any, **kwargs: Any
+    ) -> T:
         """Execute async function with circuit breaker protection.
 
         Args:
@@ -259,7 +263,9 @@ class CircuitBreaker:
             return result
 
         except Exception as e:
-            is_excluded = any(isinstance(e, exc_type) for exc_type in self.excluded_exceptions)
+            is_excluded = any(
+                isinstance(e, exc_type) for exc_type in self.excluded_exceptions
+            )
 
             if not is_excluded:
                 async with self._lock:
@@ -322,7 +328,9 @@ class RetryConfig:
         Returns:
             Delay in seconds before next retry
         """
-        delay = min(self.initial_delay * (self.exponential_base**attempt), self.max_delay)
+        delay = min(
+            self.initial_delay * (self.exponential_base**attempt), self.max_delay
+        )
         if self.jitter:
             delay = delay * (0.5 + random.random() * 0.5)
         return delay
@@ -394,7 +402,9 @@ async def retry_with_backoff(
             last_exception = e
 
             if attempt >= max_retries:
-                logger.error(f"All {max_retries} retry attempts exhausted for {func.__name__}: {e}")
+                logger.error(
+                    f"All {max_retries} retry attempts exhausted for {func.__name__}: {e}"
+                )
                 raise
 
             delay = min(initial_delay * (exponential_base**attempt), max_delay)

krons/resource/utilities/token_calculator.py

@@ -0,0 +1,185 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+from collections.abc import Callable
+from typing import cast
+
+import tiktoken
+
+from krons.errors import KronsError
+
+logger = logging.getLogger(__name__)
+
+
+class TokenCalculationError(KronsError):
+    """Raised when token calculation fails due to encoding/model errors."""
+
+    default_message = "Token calculation failed"
+    default_retryable = False
+
+
+def get_encoding_name(value: str | None) -> str:
+    """Get encoding name for model, with fallback chain.
+
+    Returns:
+        Encoding name (defaults to o200k_base if model/encoding not found or None)
+    """
+    if value is None:
+        return "o200k_base"
+
+    try:
+        enc = tiktoken.encoding_for_model(value)
+        return enc.name
+    except KeyError:
+        # Not a known model name, try as encoding name
+        try:
+            tiktoken.get_encoding(value)
+            return value
+        except Exception as e:
+            logger.warning(
+                f"Unknown model/encoding '{value}', falling back to o200k_base: {e}"
+            )
+            return "o200k_base"
+
+
+class TokenCalculator:
+    @staticmethod
+    def calculate_message_tokens(messages: list[dict], /, **kwargs) -> int:
+        model = kwargs.get("model", "gpt-4o")
+        image_token_cost = kwargs.get("image_token_cost", 500)
+        tokenizer = tiktoken.get_encoding(get_encoding_name(model)).encode
+
+        num_tokens = 0
+        for msg in messages:
+            num_tokens += 4
+            _c = msg.get("content")
+            num_tokens += TokenCalculator._calculate_chatitem(
+                _c,
+                tokenizer=tokenizer,
+                model_name=model,
+                image_token_cost=image_token_cost,
+            )
+        return num_tokens  # buffer for chat
+
+    @staticmethod
+    def calculate_embed_token(inputs: list[str], /, **kwargs) -> int:
+        if not inputs:
+            raise ValueError("inputs must be a non-empty list of strings")
+
+        try:
+            tokenizer = tiktoken.get_encoding(
+                get_encoding_name(kwargs.get("model", "text-embedding-3-small"))
+            ).encode
+
+            return sum(
+                TokenCalculator._calculate_embed_item(i, tokenizer=tokenizer)
+                for i in inputs
+            )
+        except TokenCalculationError:
+            # Re-raise from nested calls
+            raise
+        except Exception as e:
+            logger.error(f"Failed to calculate embed tokens: {e}", exc_info=True)
+            raise TokenCalculationError(f"Embed token calculation failed: {e}") from e
+
+    @staticmethod
+    def tokenize(
+        s_: str | None = None,
+        /,
+        encoding_name: str | None = None,
+        tokenizer: Callable | None = None,
+        decoder: Callable | None = None,
+        return_tokens: bool = False,
+        return_decoded: bool = False,
+    ) -> int | list[int] | tuple[int, str]:
+        if not s_:
+            return 0
+
+        if not callable(tokenizer):
+            encoding_name = get_encoding_name(encoding_name)
+            tokenizer = tiktoken.get_encoding(encoding_name).encode
+        if not callable(decoder):
+            # Use encoding_name if available, otherwise fallback to default
+            decoder_encoding = encoding_name if encoding_name else "o200k_base"
+            decoder = tiktoken.get_encoding(decoder_encoding).decode
+
+        try:
+            if return_tokens:
+                if return_decoded:
+                    a = tokenizer(s_)
+                    return len(a), decoder(a)
+                return tokenizer(s_)
+            return len(tokenizer(s_))
+        except Exception as e:
+            # Actual encoding failure during tokenization - this is an error
+            logger.error(
+                f"Tokenization failed for input (len={len(s_) if s_ else 0}): {e}",
+                exc_info=True,
+            )
+            raise TokenCalculationError(f"Tokenization failed: {e}") from e
+
+    @staticmethod
+    def _calculate_chatitem(
+        i_, tokenizer: Callable, model_name: str, image_token_cost: int = 500
+    ) -> int:
+        try:
+            if isinstance(i_, str):
+                # tokenize returns int when return_tokens=False (default)
+                return cast(int, TokenCalculator.tokenize(i_, tokenizer=tokenizer))
+
+            if isinstance(i_, dict):
+                if "text" in i_:
+                    return TokenCalculator._calculate_chatitem(
+                        str(i_["text"]), tokenizer, model_name, image_token_cost
+                    )
+                elif "image_url" in i_:
+                    return image_token_cost
+
+            if isinstance(i_, list):
+                return sum(
+                    TokenCalculator._calculate_chatitem(
+                        x, tokenizer, model_name, image_token_cost
+                    )
+                    for x in i_
+                )
+
+            # Unknown type - return 0 is valid (no text content)
+            return 0
+        except TokenCalculationError:
+            # Re-raise tokenization errors from nested calls
+            raise
+        except Exception as e:
+            logger.error(
+                f"Failed to calculate chat item tokens (type={type(i_).__name__}): {e}",
+                exc_info=True,
+            )
+            raise TokenCalculationError(
+                f"Chat item token calculation failed: {e}"
+            ) from e
+
+    @staticmethod
+    def _calculate_embed_item(s_, tokenizer: Callable) -> int:
+        try:
+            if isinstance(s_, str):
+                # tokenize returns int when return_tokens=False (default)
+                return cast(int, TokenCalculator.tokenize(s_, tokenizer=tokenizer))
+
+            if isinstance(s_, list):
+                return sum(
+                    TokenCalculator._calculate_embed_item(x, tokenizer) for x in s_
+                )
+
+            # Unknown type - return 0 is valid (no text content)
+            return 0
+        except TokenCalculationError:
+            # Re-raise tokenization errors from nested calls
+            raise
+        except Exception as e:
+            logger.error(
+                f"Failed to calculate embed item tokens (type={type(s_).__name__}): {e}",
+                exc_info=True,
+            )
+            raise TokenCalculationError(
+                f"Embed item token calculation failed: {e}"
+            ) from e