ellements 0.2.0__py3-none-any.whl

ellements/core/caching/disk.py

@@ -0,0 +1,128 @@
+"""JSON-file disk cache backend.
+
+Each cache entry lives at ``<root>/<key>.json``. The file body is
+a single JSON object::
+
+    {"value": <whatever>, "created_at": 1700000000.0, "expires_at": null}
+
+This backend is fully durable across process restarts. It is **not**
+designed for high write throughput — it does one open/write per
+:meth:`set`. For high-volume workloads, prefer
+:class:`InMemoryCache` or build a Redis/SQLite backend on top of the
+:class:`Cache` Protocol.
+
+Values must be JSON-serializable (Pydantic ``BaseModel`` instances
+are accepted because they expose ``.model_dump()``). Round-tripping
+preserves only JSON-native types: dicts, lists, strings, numbers,
+``True``/``False``/``None``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from .cache import CacheEntry
+
+
+class JsonDiskCache:
+    """Durable JSON-on-disk cache satisfying :class:`Cache`.
+
+    Args:
+        root: Directory where entries are stored. Created on
+            construction if missing.
+        default_ttl: Optional default time-to-live (seconds). When a
+            caller omits ``ttl=`` on :meth:`set`, this value is used.
+            ``None`` (the default) means entries don't expire on
+            their own.
+    """
+
+    def __init__(
+        self,
+        root: Path | str,
+        *,
+        default_ttl: float | None = None,
+    ) -> None:
+        self._root = Path(root)
+        self._root.mkdir(parents=True, exist_ok=True)
+        self._default_ttl = default_ttl
+        self._lock = asyncio.Lock()
+
+    async def get(self, key: str) -> CacheEntry | None:
+        """Return the cached entry for *key*, or ``None`` if missing,
+        unreadable, or expired (in which case the file is removed)."""
+        path = self._path_for(key)
+        if not path.exists():
+            return None
+        async with self._lock:
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                return None
+            expires_at = data.get("expires_at")
+            if expires_at is not None and expires_at <= time.time():
+                path.unlink(missing_ok=True)
+                return None
+            return CacheEntry(
+                value=data.get("value"),
+                created_at=float(data.get("created_at", time.time())),
+            )
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl: float | None = None,
+    ) -> None:
+        """Store *value* as a JSON file under ``<root>/<key>.json``.
+
+        Uses ``ttl`` when provided; falls back to ``default_ttl``.
+        Pydantic ``BaseModel`` values are converted via
+        ``.model_dump()`` before serialisation.
+        """
+        effective_ttl = ttl if ttl is not None else self._default_ttl
+        now = time.time()
+        expires_at = now + effective_ttl if effective_ttl is not None else None
+        payload = {
+            "value": _to_json_native(value),
+            "created_at": now,
+            "expires_at": expires_at,
+        }
+        async with self._lock:
+            path = self._path_for(key)
+            path.write_text(json.dumps(payload), encoding="utf-8")
+
+    async def delete(self, key: str) -> None:
+        """Remove the file for *key* if present; no-op otherwise."""
+        async with self._lock:
+            self._path_for(key).unlink(missing_ok=True)
+
+    async def clear(self) -> None:
+        """Remove every ``*.json`` file under ``root``."""
+        async with self._lock:
+            for path in self._root.glob("*.json"):
+                path.unlink(missing_ok=True)
+
+    def _path_for(self, key: str) -> Path:
+        return self._root / f"{key}.json"
+
+
+def _to_json_native(value: Any) -> Any:
+    """Convert *value* into a JSON-native shape.
+
+    Pydantic models are converted via ``.model_dump()``; dataclasses
+    that expose ``.__dict__`` are converted to dicts. Everything else
+    is passed through and will raise ``TypeError`` at write time if
+    it is not JSON-serializable — a deliberate fail-loud choice so
+    misuses surface immediately rather than corrupting the cache.
+    """
+    if hasattr(value, "model_dump"):
+        return value.model_dump()
+    return value
+
+
+__all__ = ["JsonDiskCache"]

ellements/core/caching/keys.py

@@ -0,0 +1,97 @@
+"""Stable cache-key generation for LLM requests.
+
+The single public helper :func:`build_cache_key` produces a short
+hex digest that uniquely identifies a request payload modulo
+non-semantic noise:
+
+* Mappings are JSON-encoded with ``sort_keys=True``, so dict ordering
+  cannot perturb the digest.
+* Falsy "no override" fields (``model=None``, ``response_model=None``,
+  empty extras) are normalized to a fixed sentinel so different
+  call-sites that ultimately produce identical requests collide on
+  the same key.
+* Pydantic ``BaseModel`` types are represented by their fully
+  qualified name, since two distinct classes with identical fields
+  should not share cached entries.
+
+Callers should treat the returned key as **opaque**.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from typing import Any
+
+
+def build_cache_key(
+    *,
+    method: str,
+    model: str,
+    messages: Any,
+    temperature: float,
+    max_tokens: int | None,
+    extra: Mapping[str, Any] | None = None,
+    response_model: type | None = None,
+) -> str:
+    """Return a stable hex digest for an LLM request.
+
+    Args:
+        method: The :class:`ellements.core.LLMClient` method name
+            being cached (e.g. ``"complete"``,
+            ``"complete_structured"``).
+        model: Final resolved model identifier (after any
+            per-call override).
+        messages: The normalized messages list / Conversation /
+            string. Serialized with :func:`_normalize` so unhashable
+            container types still hash consistently.
+        temperature: Sampling temperature.
+        max_tokens: Optional max tokens cap; ``None`` is preserved.
+        extra: Extra kwargs (e.g. ``top_p``, ``stop``) the caller
+            passed through. Order-independent.
+        response_model: Optional Pydantic model class (for
+            ``complete_structured``); represented by its fully
+            qualified name.
+
+    Returns:
+        Hex digest (SHA-256, 64 chars) of the canonicalized payload.
+    """
+    payload = {
+        "method": method,
+        "model": model,
+        "messages": _normalize(messages),
+        "temperature": temperature,
+        "max_tokens": max_tokens,
+        "extra": _normalize(dict(extra or {})),
+        "response_model": (
+            f"{response_model.__module__}.{response_model.__qualname__}"
+            if response_model is not None
+            else None
+        ),
+    }
+    encoded = json.dumps(payload, sort_keys=True, default=_json_default)
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+def _normalize(value: Any) -> Any:
+    """Render *value* into a JSON-friendly, order-insensitive shape."""
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, Mapping):
+        return {str(k): _normalize(v) for k, v in sorted(value.items())}
+    if isinstance(value, (list, tuple)):
+        return [_normalize(item) for item in value]
+    if hasattr(value, "model_dump"):
+        return _normalize(value.model_dump())
+    return repr(value)
+
+
+def _json_default(value: Any) -> Any:
+    """Fallback for ``json.dumps`` when ``_normalize`` returned something exotic."""
+    if hasattr(value, "model_dump"):
+        return value.model_dump()
+    return repr(value)
+
+
+__all__ = ["build_cache_key"]

ellements/core/caching/memory.py

@@ -0,0 +1,104 @@
+"""Process-local in-memory cache backend.
+
+Backed by a plain ``dict`` plus a single :class:`asyncio.Lock` for
+mutation safety. Supports optional TTL with lazy expiry on read.
+
+Suitable for tests, demos, and short-lived processes; if you need
+durability across runs, use :class:`ellements.core.caching.JsonDiskCache`
+or build your own backend on top of the :class:`Cache` Protocol.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from .cache import CacheEntry
+
+
+@dataclass(slots=True)
+class _Record:
+    entry: CacheEntry
+    expires_at: float | None
+
+
+class InMemoryCache:
+    """Thread/task-safe in-memory cache satisfying :class:`Cache`.
+
+    Args:
+        default_ttl: Default time-to-live (seconds) applied when
+            callers omit ``ttl=`` on :meth:`set`. ``None`` (the
+            default) means entries never expire on their own.
+        max_entries: Optional cap on the number of entries. When the
+            cap is exceeded, the **oldest** entry (by ``created_at``)
+            is evicted on each new write. ``None`` disables eviction.
+    """
+
+    def __init__(
+        self,
+        *,
+        default_ttl: float | None = None,
+        max_entries: int | None = None,
+    ) -> None:
+        self._default_ttl = default_ttl
+        self._max_entries = max_entries
+        self._store: dict[str, _Record] = {}
+        self._lock = asyncio.Lock()
+
+    async def get(self, key: str) -> CacheEntry | None:
+        """Return the cached entry for *key*, or ``None`` if it's missing
+        or has expired (in which case the entry is also evicted)."""
+        async with self._lock:
+            record = self._store.get(key)
+            if record is None:
+                return None
+            if record.expires_at is not None and record.expires_at <= time.time():
+                del self._store[key]
+                return None
+            return record.entry
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl: float | None = None,
+    ) -> None:
+        """Store *value* under *key*.
+
+        Uses ``ttl`` when provided; falls back to ``default_ttl`` from
+        construction. Triggers eviction of the oldest entry when
+        ``max_entries`` is set and the cap is exceeded.
+        """
+        effective_ttl = ttl if ttl is not None else self._default_ttl
+        now = time.time()
+        expires_at = now + effective_ttl if effective_ttl is not None else None
+        entry = CacheEntry(value=value, created_at=now)
+        async with self._lock:
+            self._store[key] = _Record(entry=entry, expires_at=expires_at)
+            self._enforce_capacity()
+
+    async def delete(self, key: str) -> None:
+        """Remove *key* if present; no-op otherwise."""
+        async with self._lock:
+            self._store.pop(key, None)
+
+    async def clear(self) -> None:
+        """Drop every entry from the cache."""
+        async with self._lock:
+            self._store.clear()
+
+    def _enforce_capacity(self) -> None:
+        if self._max_entries is None:
+            return
+        overflow = len(self._store) - self._max_entries
+        if overflow <= 0:
+            return
+        ordered = sorted(self._store.items(), key=lambda kv: kv[1].entry.created_at)
+        for key, _ in ordered[:overflow]:
+            del self._store[key]
+
+
+__all__ = ["InMemoryCache"]

ellements/core/chunking.py

@@ -0,0 +1,262 @@
+"""Token-aware text **chunking** primitives.
+
+Everything here is LLM-dependency-free and operates on plain strings:
+
+- :func:`count_tokens` — token accounting via tiktoken (cached
+  encoder lookup so callers can call it freely on hot paths).
+- :func:`simple_truncate` — direct character/token truncation with an
+  optional suffix.
+- :func:`map_reduce` — chunked fan-out (one mapper call per chunk)
+  followed by a single reducer.
+- :func:`sequential_refine` — rolling synthesis where each chunk
+  refines an accumulating draft.
+- :class:`TextProcessor` — strategy-based orchestration of the above
+  with a single ``process()`` entry point.
+
+These primitives accept arbitrary mapper/reducer/refiner callables so
+callers plug in their own LLM-backed (or non-LLM-backed) processing
+without this module having an opinion.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable, Sequence
+from typing import Literal
+
+import tiktoken
+
+TruncationStrategy = Literal["simple", "map_reduce", "sequential"]
+
+_DEFAULT_MODEL = "gpt-5-mini"
+_Mapper = Callable[[str], str]
+_Reducer = Callable[[list[str]], str]
+_Refiner = Callable[[str, str], str]
+_InitialProcessor = Callable[[str], str]
+
+__all__ = [
+    "TextProcessor",
+    "TruncationStrategy",
+    "count_tokens",
+    "map_reduce",
+    "sequential_refine",
+    "simple_truncate",
+]
+
+
+@functools.lru_cache(maxsize=32)
+def _get_encoding(model: str = _DEFAULT_MODEL) -> tiktoken.Encoding:
+    """Return the tiktoken encoding for *model*, falling back to ``cl100k_base``."""
+    try:
+        return tiktoken.encoding_for_model(model)
+    except KeyError:
+        return tiktoken.get_encoding("cl100k_base")
+
+
+def _validate_positive(name: str, value: int) -> None:
+    if value <= 0:
+        raise ValueError(f"{name} must be greater than 0")
+
+
+def _resolve_chunk_size(max_tokens: int, chunk_size: int | None) -> int:
+    _validate_positive("max_tokens", max_tokens)
+    if chunk_size is None:
+        return max_tokens
+    _validate_positive("chunk_size", chunk_size)
+    return chunk_size
+
+
+def _chunk_tokens(
+    tokens: Sequence[int],
+    chunk_size: int,
+    chunk_overlap: int = 0,
+) -> list[list[int]]:
+    """Split a token sequence into chunks with optional overlap."""
+    _validate_positive("chunk_size", chunk_size)
+    if chunk_overlap < 0:
+        raise ValueError("chunk_overlap must be greater than or equal to 0")
+    if chunk_overlap >= chunk_size:
+        raise ValueError("chunk_overlap must be less than chunk_size")
+
+    if not tokens:
+        return []
+
+    stride = chunk_size - chunk_overlap
+    chunks: list[list[int]] = []
+    for start in range(0, len(tokens), stride):
+        chunk = list(tokens[start : start + chunk_size])
+        chunks.append(chunk)
+        if start + chunk_size >= len(tokens):
+            break
+    return chunks
+
+
+def count_tokens(text: str, model: str = _DEFAULT_MODEL) -> int:
+    """Return the number of tokens in *text* under the given model's tokenizer."""
+    encoding = _get_encoding(model)
+    return len(encoding.encode(text))
+
+
+def simple_truncate(
+    text: str,
+    max_tokens: int,
+    model: str = _DEFAULT_MODEL,
+    suffix: str = "\n\n[... truncated ...]",
+) -> str:
+    """Truncate *text* to at most *max_tokens* tokens, appending *suffix*."""
+    _validate_positive("max_tokens", max_tokens)
+    encoding = _get_encoding(model)
+    tokens = encoding.encode(text)
+
+    if len(tokens) <= max_tokens:
+        return text
+
+    suffix_tokens = len(encoding.encode(suffix))
+    keep_tokens = max_tokens - suffix_tokens
+    truncated_tokens = tokens[:max_tokens] if keep_tokens <= 0 else tokens[:keep_tokens]
+    truncated_text: str = encoding.decode(truncated_tokens)
+    return truncated_text + suffix if keep_tokens > 0 else truncated_text
+
+
+def map_reduce(
+    text: str,
+    max_tokens: int,
+    mapper: _Mapper,
+    reducer: _Reducer | None = None,
+    chunk_size: int | None = None,
+    chunk_overlap: int = 0,
+    model: str = _DEFAULT_MODEL,
+) -> str:
+    """Process *text* via a map-reduce pipeline until it fits the token budget."""
+    resolved_chunk_size = _resolve_chunk_size(max_tokens, chunk_size)
+    reduce_results = reducer or (lambda results: "\n\n".join(results))
+    encoding = _get_encoding(model)
+    current = text
+
+    while True:
+        current_tokens = encoding.encode(current)
+        if len(current_tokens) <= max_tokens:
+            return current
+
+        token_chunks = _chunk_tokens(current_tokens, resolved_chunk_size, chunk_overlap)
+        mapped_results = [mapper(encoding.decode(chunk)) for chunk in token_chunks]
+        current = reduce_results(mapped_results)
+        current_token_count = len(encoding.encode(current))
+
+        if current_token_count <= max_tokens:
+            return current
+        if current_token_count >= len(current_tokens):
+            raise ValueError(
+                "map_reduce requires the mapper/reducer combination to reduce "
+                "the text when the input exceeds max_tokens"
+            )
+
+
+def sequential_refine(
+    text: str,
+    max_tokens: int,
+    refiner: _Refiner,
+    chunk_size: int | None = None,
+    chunk_overlap: int = 0,
+    initial_processor: _InitialProcessor | None = None,
+    model: str = _DEFAULT_MODEL,
+) -> str:
+    """Process *text* chunk-by-chunk while refining an accumulated result."""
+    resolved_chunk_size = _resolve_chunk_size(max_tokens, chunk_size)
+    encoding = _get_encoding(model)
+    tokens = encoding.encode(text)
+
+    if len(tokens) <= max_tokens:
+        return initial_processor(text) if initial_processor is not None else text
+
+    token_chunks = _chunk_tokens(tokens, resolved_chunk_size, chunk_overlap)
+    chunks = [encoding.decode(chunk) for chunk in token_chunks]
+
+    accumulated = (
+        initial_processor(chunks[0]) if initial_processor is not None else chunks[0]
+    )
+    for chunk in chunks[1:]:
+        accumulated = refiner(accumulated, chunk)
+
+    if len(encoding.encode(accumulated)) > max_tokens:
+        return simple_truncate(accumulated, max_tokens, model)
+    return accumulated
+
+
+class TextProcessor:
+    """Configurable orchestrator over the chunking primitives."""
+
+    def __init__(
+        self,
+        max_tokens: int = 4000,
+        strategy: TruncationStrategy = "simple",
+        model: str = _DEFAULT_MODEL,
+        chunk_size: int | None = None,
+        chunk_overlap: int = 0,
+    ) -> None:
+        self.max_tokens = max_tokens
+        self.strategy = strategy
+        self.model = model
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self._mapper: _Mapper | None = None
+        self._reducer: _Reducer | None = None
+        self._refiner: _Refiner | None = None
+        self._initial_processor: _InitialProcessor | None = None
+
+    def set_mapper(self, mapper: _Mapper) -> None:
+        """Bind the mapper used by the ``map_reduce`` strategy."""
+        self._mapper = mapper
+
+    def set_reducer(self, reducer: _Reducer) -> None:
+        """Bind the reducer used by the ``map_reduce`` strategy."""
+        self._reducer = reducer
+
+    def set_refiner(self, refiner: _Refiner) -> None:
+        """Bind the refiner used by the ``sequential`` strategy."""
+        self._refiner = refiner
+
+    def set_initial_processor(self, processor: _InitialProcessor) -> None:
+        """Bind the initial processor used for the first chunk in sequential mode."""
+        self._initial_processor = processor
+
+    def process(self, text: str) -> str:
+        """Process *text* according to the configured strategy."""
+        if self.strategy == "simple":
+            return simple_truncate(text, self.max_tokens, self.model)
+
+        if self.strategy == "map_reduce":
+            if self._mapper is None:
+                raise ValueError(
+                    "map_reduce strategy requires a mapper. Call set_mapper() first."
+                )
+            return map_reduce(
+                text=text,
+                max_tokens=self.max_tokens,
+                mapper=self._mapper,
+                reducer=self._reducer,
+                chunk_size=self.chunk_size,
+                chunk_overlap=self.chunk_overlap,
+                model=self.model,
+            )
+
+        if self.strategy == "sequential":
+            if self._refiner is None:
+                raise ValueError(
+                    "sequential strategy requires a refiner. Call set_refiner() first."
+                )
+            return sequential_refine(
+                text=text,
+                max_tokens=self.max_tokens,
+                refiner=self._refiner,
+                chunk_size=self.chunk_size,
+                chunk_overlap=self.chunk_overlap,
+                initial_processor=self._initial_processor,
+                model=self.model,
+            )
+
+        raise ValueError(f"Unknown strategy: {self.strategy}")
+
+    def count_tokens(self, text: str) -> int:
+        """Count tokens in *text* using the processor's configured model."""
+        return count_tokens(text, self.model)