onetool-mcp 1.0.0b1__py3-none-any.whl → 1.0.0rc2__py3-none-any.whl

ot/utils/cache.py

@@ -1,120 +1,120 @@
-"""In-memory caching with TTL for tools.
-
-Provides both a decorator for function memoization and manual cache operations.
-Cache persists for the lifetime of the process.
-"""
-
-from __future__ import annotations
-
-import functools
-import time
-from collections.abc import Callable
-from typing import Any, TypeVar
-
-__all__ = ["CacheNamespace", "cache"]
-
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-class CacheEntry:
-    """A cached value with expiration time."""
-
-    def __init__(self, value: Any, ttl: float) -> None:
-        self.value = value
-        self.expires_at = time.time() + ttl
-
-
-class CacheNamespace:
-    """Cache namespace with get/set/clear operations and decorator."""
-
-    def __init__(self) -> None:
-        self._store: dict[str, CacheEntry] = {}
-        self._memoize_stores: dict[str, dict[str, CacheEntry]] = {}
-
-    def get(self, key: str) -> Any | None:
-        """Get a cached value by key.
-
-        Args:
-            key: Cache key
-
-        Returns:
-            Cached value, or None if not found or expired
-        """
-        entry = self._store.get(key)
-        if entry is None:
-            return None
-        if time.time() > entry.expires_at:
-            del self._store[key]
-            return None
-        return entry.value
-
-    def set(self, key: str, value: Any, ttl: float = 300.0) -> None:
-        """Set a cached value with TTL.
-
-        Args:
-            key: Cache key
-            value: Value to cache
-            ttl: Time-to-live in seconds (default: 5 minutes)
-        """
-        self._store[key] = CacheEntry(value, ttl)
-
-    def clear(self, key: str | None = None) -> None:
-        """Clear cached values.
-
-        Args:
-            key: Specific key to clear, or None to clear all
-        """
-        if key is None:
-            self._store.clear()
-            self._memoize_stores.clear()
-        else:
-            self._store.pop(key, None)
-
-    def __call__(self, ttl: float = 300.0) -> Callable[[F], F]:
-        """Decorator for memoizing function results with TTL.
-
-        Args:
-            ttl: Time-to-live in seconds (default: 5 minutes)
-
-        Returns:
-            Decorator function
-
-        Example:
-            @cache(ttl=60)
-            def expensive_operation(query: str) -> str:
-                ...
-        """
-
-        def decorator(func: F) -> F:
-            # Create a separate store for this function
-            func_id = f"{func.__module__}.{func.__qualname__}"
-            self._memoize_stores[func_id] = {}
-
-            @functools.wraps(func)
-            def wrapper(*args: Any, **kwargs: Any) -> Any:
-                # Build cache key from args and kwargs
-                key_parts = [repr(arg) for arg in args]
-                key_parts.extend(f"{k}={v!r}" for k, v in sorted(kwargs.items()))
-                cache_key = ":".join(key_parts)
-
-                # Get or create store (may have been cleared by cache.clear())
-                store = self._memoize_stores.get(func_id)
-                if store is None:
-                    store = {}
-                    self._memoize_stores[func_id] = store
-                entry = store.get(cache_key)
-
-                if entry is not None and time.time() <= entry.expires_at:
-                    return entry.value
-
-                result = func(*args, **kwargs)
-                store[cache_key] = CacheEntry(result, ttl)
-                return result
-
-            return wrapper  # type: ignore[return-value]
-
-        return decorator
-
-
-# Singleton instance
-cache = CacheNamespace()
+"""In-memory caching with TTL for tools.
+
+Provides both a decorator for function memoization and manual cache operations.
+Cache persists for the lifetime of the process.
+"""
+
+from __future__ import annotations
+
+import functools
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+__all__ = ["CacheNamespace", "cache"]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class CacheEntry:
+    """A cached value with expiration time."""
+
+    def __init__(self, value: Any, ttl: float) -> None:
+        self.value = value
+        self.expires_at = time.time() + ttl
+
+
+class CacheNamespace:
+    """Cache namespace with get/set/clear operations and decorator."""
+
+    def __init__(self) -> None:
+        self._store: dict[str, CacheEntry] = {}
+        self._memoize_stores: dict[str, dict[str, CacheEntry]] = {}
+
+    def get(self, key: str) -> Any | None:
+        """Get a cached value by key.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value, or None if not found or expired
+        """
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        if time.time() > entry.expires_at:
+            del self._store[key]
+            return None
+        return entry.value
+
+    def set(self, key: str, value: Any, ttl: float = 300.0) -> None:
+        """Set a cached value with TTL.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Time-to-live in seconds (default: 5 minutes)
+        """
+        self._store[key] = CacheEntry(value, ttl)
+
+    def clear(self, key: str | None = None) -> None:
+        """Clear cached values.
+
+        Args:
+            key: Specific key to clear, or None to clear all
+        """
+        if key is None:
+            self._store.clear()
+            self._memoize_stores.clear()
+        else:
+            self._store.pop(key, None)
+
+    def __call__(self, ttl: float = 300.0) -> Callable[[F], F]:
+        """Decorator for memoizing function results with TTL.
+
+        Args:
+            ttl: Time-to-live in seconds (default: 5 minutes)
+
+        Returns:
+            Decorator function
+
+        Example:
+            @cache(ttl=60)
+            def expensive_operation(query: str) -> str:
+                ...
+        """
+
+        def decorator(func: F) -> F:
+            # Create a separate store for this function
+            func_id = f"{func.__module__}.{func.__qualname__}"
+            self._memoize_stores[func_id] = {}
+
+            @functools.wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                # Build cache key from args and kwargs
+                key_parts = [repr(arg) for arg in args]
+                key_parts.extend(f"{k}={v!r}" for k, v in sorted(kwargs.items()))
+                cache_key = ":".join(key_parts)
+
+                # Get or create store (may have been cleared by cache.clear())
+                store = self._memoize_stores.get(func_id)
+                if store is None:
+                    store = {}
+                    self._memoize_stores[func_id] = store
+                entry = store.get(cache_key)
+
+                if entry is not None and time.time() <= entry.expires_at:
+                    return entry.value
+
+                result = func(*args, **kwargs)
+                store[cache_key] = CacheEntry(result, ttl)
+                return result
+
+            return wrapper  # type: ignore[return-value]
+
+        return decorator
+
+
+# Singleton instance
+cache = CacheNamespace()

ot/utils/exceptions.py

@@ -1,23 +1,23 @@
-"""Exception handling utilities."""
-
-from __future__ import annotations
-
-
-def flatten_exception_group(
-    eg: BaseExceptionGroup[BaseException],
-) -> list[BaseException]:
-    """Recursively flatten nested ExceptionGroups to get leaf exceptions.
-
-    Args:
-        eg: The exception group to flatten.
-
-    Returns:
-        List of leaf exceptions (non-group exceptions).
-    """
-    result: list[BaseException] = []
-    for exc in eg.exceptions:
-        if isinstance(exc, BaseExceptionGroup):
-            result.extend(flatten_exception_group(exc))
-        else:
-            result.append(exc)
-    return result
+"""Exception handling utilities."""
+
+from __future__ import annotations
+
+
+def flatten_exception_group(
+    eg: BaseExceptionGroup[BaseException],
+) -> list[BaseException]:
+    """Recursively flatten nested ExceptionGroups to get leaf exceptions.
+
+    Args:
+        eg: The exception group to flatten.
+
+    Returns:
+        List of leaf exceptions (non-group exceptions).
+    """
+    result: list[BaseException] = []
+    for exc in eg.exceptions:
+        if isinstance(exc, BaseExceptionGroup):
+            result.extend(flatten_exception_group(exc))
+        else:
+            result.append(exc)
+    return result

ot/utils/factory.py

@@ -1,179 +1,178 @@
-"""Factory utilities for OneTool.
-
-Provides thread-safe lazy initialization patterns for API clients.
-
-Example:
-    from ot.utils import lazy_client
-
-    # Define a client factory
-    def create_my_client():
-        from mylib import Client
-        api_key = get_secret("MY_API_KEY")
-        return Client(api_key=api_key)
-
-    # Create a lazy-initialized getter
-    get_client = lazy_client(create_my_client)
-
-    # Use it anywhere - initialized once, thread-safe
-    client = get_client()
-"""
-
-from __future__ import annotations
-
-import threading
-from typing import TYPE_CHECKING, TypeVar
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-__all__ = ["LazyClient", "lazy_client"]
-
-T = TypeVar("T")
-
-
-def lazy_client(
-    factory: Callable[[], T | None],
-    *,
-    allow_none: bool = False,
-) -> Callable[[], T | None]:
-    """Create a thread-safe lazy-initialized client getter.
-
-    Wraps a factory function with double-checked locking to ensure
-    the client is created exactly once, even under concurrent access.
-
-    The factory function should:
-    - Return the client instance on success
-    - Return None if required credentials are missing
-    - Raise exceptions for other errors
-
-    Args:
-        factory: Callable that creates and returns the client instance
-        allow_none: If True, cache None results. If False (default), retry
-                   factory on each call when it returns None.
-
-    Returns:
-        A callable that returns the lazily-initialized client
-
-    Example:
-        from ot.utils import lazy_client
-        from ot.config import get_secret, get_tool_config
-
-        def create_firecrawl():
-            from firecrawl import FirecrawlApp
-            api_key = get_secret("FIRECRAWL_API_KEY")
-            if not api_key:
-                return None
-            api_url = get_tool_config("firecrawl", Config).api_url
-            return FirecrawlApp(api_key=api_key, api_url=api_url or None)
-
-        get_firecrawl = lazy_client(create_firecrawl)
-
-        # Later, in tool functions:
-        def scrape(url: str) -> str:
-            client = get_firecrawl()
-            if client is None:
-                return "Error: FIRECRAWL_API_KEY not configured"
-            return client.scrape_url(url)
-    """
-    client: T | None = None
-    initialized = False
-    lock = threading.Lock()
-
-    def get_client() -> T | None:
-        nonlocal client, initialized
-
-        # Fast path: already initialized
-        if initialized:
-            return client
-
-        # Slow path: acquire lock and initialize
-        with lock:
-            # Double-check after acquiring lock
-            if initialized:
-                return client
-
-            result = factory()
-
-            # Cache result if successful or allow_none is True
-            if result is not None or allow_none:
-                client = result
-                initialized = True
-
-            return result
-
-    return get_client
-
-
-class LazyClient:
-    """Class-based lazy client for more complex initialization patterns.
-
-    Useful when you need to pass the factory as a method or need
-    additional client management features.
-
-    Example:
-        class MyPack:
-            def __init__(self):
-                self._client = LazyClient(self._create_client)
-
-            def _create_client(self):
-                return SomeClient(api_key=get_secret("API_KEY"))
-
-            def search(self, query: str) -> str:
-                client = self._client.get()
-                if client is None:
-                    return "Error: API_KEY not configured"
-                return client.search(query)
-    """
-
-    def __init__(
-        self,
-        factory: Callable[[], T | None],
-        *,
-        allow_none: bool = False,
-    ) -> None:
-        """Initialize the lazy client wrapper.
-
-        Args:
-            factory: Callable that creates the client
-            allow_none: If True, cache None results
-        """
-        self._factory = factory
-        self._allow_none = allow_none
-        self._client: T | None = None
-        self._initialized = False
-        self._lock = threading.Lock()
-
-    def get(self) -> T | None:
-        """Get the client, initializing if necessary.
-
-        Returns:
-            The client instance, or None if not available
-        """
-        if self._initialized:
-            return self._client  # type: ignore[return-value]
-
-        with self._lock:
-            if self._initialized:
-                return self._client
-
-            result = self._factory()
-
-            if result is not None or self._allow_none:
-                self._client = result
-                self._initialized = True
-
-            return result  # type: ignore[return-value]
-
-    def reset(self) -> None:
-        """Reset the client, forcing re-initialization on next access.
-
-        Useful for testing or when configuration changes.
-        """
-        with self._lock:
-            self._client = None
-            self._initialized = False
-
-    @property
-    def is_initialized(self) -> bool:
-        """Check if the client has been initialized."""
-        return self._initialized
+"""Factory utilities for OneTool.
+
+Provides thread-safe lazy initialization patterns for API clients.
+
+Example:
+    from ot.utils import lazy_client
+
+    # Define a client factory
+    def create_my_client():
+        from mylib import Client
+        api_key = get_secret("MY_API_KEY")
+        return Client(api_key=api_key)
+
+    # Create a lazy-initialized getter
+    get_client = lazy_client(create_my_client)
+
+    # Use it anywhere - initialized once, thread-safe
+    client = get_client()
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ["LazyClient", "lazy_client"]
+
+T = TypeVar("T")
+
+
+def lazy_client(
+    factory: Callable[[], T | None],
+    *,
+    allow_none: bool = False,
+) -> Callable[[], T | None]:
+    """Create a thread-safe lazy-initialized client getter.
+
+    Wraps a factory function with double-checked locking to ensure
+    the client is created exactly once, even under concurrent access.
+
+    The factory function should:
+    - Return the client instance on success
+    - Return None if required credentials are missing
+    - Raise exceptions for other errors
+
+    Args:
+        factory: Callable that creates and returns the client instance
+        allow_none: If True, cache None results. If False (default), retry
+                   factory on each call when it returns None.
+
+    Returns:
+        A callable that returns the lazily-initialized client
+
+    Example:
+        from ot.utils import lazy_client
+        from ot.config import get_secret
+
+        def create_brave():
+            from brave import Brave
+            api_key = get_secret("BRAVE_API_KEY")
+            if not api_key:
+                return None
+            return Brave(api_key=api_key)
+
+        get_brave = lazy_client(create_brave)
+
+        # Later, in tool functions:
+        def search(query: str) -> str:
+            client = get_brave()
+            if client is None:
+                return "Error: BRAVE_API_KEY not configured"
+            return client.search(query)
+    """
+    client: T | None = None
+    initialized = False
+    lock = threading.Lock()
+
+    def get_client() -> T | None:
+        nonlocal client, initialized
+
+        # Fast path: already initialized
+        if initialized:
+            return client
+
+        # Slow path: acquire lock and initialize
+        with lock:
+            # Double-check after acquiring lock
+            if initialized:
+                return client
+
+            result = factory()
+
+            # Cache result if successful or allow_none is True
+            if result is not None or allow_none:
+                client = result
+                initialized = True
+
+            return result
+
+    return get_client
+
+
+class LazyClient:
+    """Class-based lazy client for more complex initialization patterns.
+
+    Useful when you need to pass the factory as a method or need
+    additional client management features.
+
+    Example:
+        class MyPack:
+            def __init__(self):
+                self._client = LazyClient(self._create_client)
+
+            def _create_client(self):
+                return SomeClient(api_key=get_secret("API_KEY"))
+
+            def search(self, query: str) -> str:
+                client = self._client.get()
+                if client is None:
+                    return "Error: API_KEY not configured"
+                return client.search(query)
+    """
+
+    def __init__(
+        self,
+        factory: Callable[[], T | None],
+        *,
+        allow_none: bool = False,
+    ) -> None:
+        """Initialize the lazy client wrapper.
+
+        Args:
+            factory: Callable that creates the client
+            allow_none: If True, cache None results
+        """
+        self._factory = factory
+        self._allow_none = allow_none
+        self._client: T | None = None
+        self._initialized = False
+        self._lock = threading.Lock()
+
+    def get(self) -> T | None:
+        """Get the client, initializing if necessary.
+
+        Returns:
+            The client instance, or None if not available
+        """
+        if self._initialized:
+            return self._client  # type: ignore[return-value]
+
+        with self._lock:
+            if self._initialized:
+                return self._client
+
+            result = self._factory()
+
+            if result is not None or self._allow_none:
+                self._client = result
+                self._initialized = True
+
+            return result  # type: ignore[return-value]
+
+    def reset(self) -> None:
+        """Reset the client, forcing re-initialization on next access.
+
+        Useful for testing or when configuration changes.
+        """
+        with self._lock:
+            self._client = None
+            self._initialized = False
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if the client has been initialized."""
+        return self._initialized