tooluniverse.cache package

Cache utilities for ToolUniverse.

Submodules

tooluniverse.cache.memory_cache module

In-memory cache utilities for ToolUniverse.

Provides a lightweight, thread-safe LRU cache with optional singleflight deduplication for expensive misses.

class tooluniverse.cache.memory_cache.LRUCache

Bases: object

Thread-safe LRU cache with basic telemetry.

__init__(max_size=128)

get(key)

set(key, value)

delete(key)

clear()

stats()

items()

class tooluniverse.cache.memory_cache.SingleFlight

Bases: object

Per-key lock manager to collapse duplicate cache misses.

__init__()

acquire(key)

tooluniverse.cache.result_cache_manager module

Result cache manager that coordinates in-memory and persistent storage.

class tooluniverse.cache.result_cache_manager.CacheRecord

Bases: object

CacheRecord(value: ‘Any’, expires_at: ‘Optional[float]’, namespace: ‘str’, version: ‘str’)

value: Any

expires_at: float | None

namespace: str

version: str

__init__(value, expires_at, namespace, version)

class tooluniverse.cache.result_cache_manager.ResultCacheManager

Bases: object

Facade around memory + persistent cache layers.

__init__(*, memory_size=256, persistent_path=None, enabled=True, persistence_enabled=True, singleflight=True, default_ttl=None, async_persist=None, async_queue_size=10000)

static compose_key(namespace, version, cache_key)

get(*, namespace, version, cache_key)

set(*, namespace, version, cache_key, value, ttl=None)

delete(*, namespace, version, cache_key)

clear(namespace=None)

bulk_get(requests)

Fetch multiple cache entries at once.

Parameters:

requests (Sequence[Dict[str, str]]) – Iterable of dicts containing namespace, version and cache_key.

Returns

Mapping of composed cache keys to cached values.

stats()

dump(namespace=None)

singleflight_guard(composed_key)

close()

Close the cache manager and cleanup resources.

__del__()

Ensure cleanup happens even if close() is not called explicitly.

flush()

tooluniverse.cache.sqlite_backend module

SQLite-backed persistent cache for ToolUniverse.

The cache stores serialized tool results with TTL and version metadata. Designed to be a drop-in persistent layer behind the in-memory cache.

class tooluniverse.cache.sqlite_backend.CacheEntry

Bases: object

CacheEntry(key: ‘str’, value: ‘Any’, namespace: ‘str’, version: ‘str’, ttl: ‘Optional[int]’, created_at: ‘float’, last_accessed: ‘float’, hit_count: ‘int’, expires_at: ‘Optional[float]’ = None)

key: str

value: Any

namespace: str

version: str

ttl: int | None

created_at: float

last_accessed: float

hit_count: int

expires_at: float | None = None

__init__(key, value, namespace, version, ttl, created_at, last_accessed, hit_count, expires_at=None)

class tooluniverse.cache.sqlite_backend.PersistentCache

Bases: object

SQLite-backed cache layer with TTL support.

__init__(path, *, enable=True)

close()

cleanup_expired()

get(cache_key)

set(cache_key, value, *, namespace, version, ttl, created_at=None, expires_at=None)

delete(cache_key)

clear(namespace=None)

iter_entries(namespace=None)

stats()