quadkit-cache 0.0.42__tar.gz → 0.0.44__tar.gz

quadkit_cache-0.0.44/.gitignore

@@ -0,0 +1,24 @@
+# Generated public-repository ignore rules.
+# Private monorepo paths are intentionally not referenced here.
+
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+*.log
+.DS_Store
+.idea/
+.vscode/

{quadkit_cache-0.0.42 → quadkit_cache-0.0.44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit-cache
-Version: 0.0.42
+Version: 0.0.44
 Summary: Multi-backend caching system for Quadkit Framework - Redis, Memcached, and in-memory caching
 Project-URL: Homepage, https://dbtinoy-.github.io/quadkit
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit

{quadkit_cache-0.0.42 → quadkit_cache-0.0.44}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit-cache"
-version = "0.0.42"
+version = "0.0.44"
 description = "Multi-backend caching system for Quadkit Framework - Redis, Memcached, and in-memory caching"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -95,9 +95,6 @@ Documentation = "https://dbtinoy-.github.io/quadkit"
 Issues = "https://github.com/dbtinoy-/quadkit/issues"
 Changelog = "https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md"
 
-[project.entry-points."quadkit.admin.contributors"]
-cache = "quadkit.cache.admin.contributor:CacheAdminContributor"
-
 [project.entry-points."quadkit.cli.contributors"]
 cache = "quadkit.cache.cli.contributor:CacheCliContributor"
 
@@ -180,9 +177,6 @@ overrides = [
 [tool.uv.sources.quadkit]
 workspace = true
 
-[tool.uv.sources.quadkit-admin]
-workspace = true
-
 [tool.uv.sources.quadkit-testing]
 workspace = true
 

{quadkit_cache-0.0.42 → quadkit_cache-0.0.44}/src/quadkit/cache/admin/contributor.py

@@ -138,7 +138,7 @@ _ACTIONS: tuple[AdminActionDefinition, ...] = (
 class CacheAdminContributor(BaseAdminContributor):
     """Admin contributor for the quadkit-cache package.
 
-    Registered via ``quadkit.admin.contributors`` entry point.
+    Registered via ``the optional provider module`` entry point.
     Provides cache hit/miss ratio, eviction rate, and backend ping widgets.
     Dependencies are resolved from the container in ``on_admin_boot``.
     """

{quadkit_cache-0.0.42 → quadkit_cache-0.0.44}/src/quadkit/cache/backends/redis/circuit.py

@@ -1,7 +1,7 @@
 """Local circuit breaker backend types for quadkit-cache.
 
 This module provides local type definitions to avoid cross-package imports
-from quadkit-resilience.
+from the optional provider.
 """
 
 from __future__ import annotations

{quadkit_cache-0.0.42 → quadkit_cache-0.0.44}/src/quadkit/cache/backends/redis/resilience.py

@@ -6,7 +6,7 @@ breakers) that require distributed, cross-process state.
 Usage::
 
     from quadkit.cache.backends.redis.resilience import RedisCircuitBreakerBackend
-    from quadkit.resilience.circuit import CircuitBreakerRegistry
+    from the optional provider module import CircuitBreakerRegistry
 
     backend = RedisCircuitBreakerBackend(
         redis_url="redis://localhost:6379",
@@ -31,7 +31,7 @@ class RedisCircuitBreakerBackend:
 
     Suitable for multi-process deployments where circuit breaker state must
     be shared across containers or workers.  Implements
-    :class:`~quadkit.resilience.circuit.backend.CircuitBreakerBackend`.
+    :class:`~the optional provider module`.
 
     Args:
         redis_url: Redis connection URL.

quadkit_cache-0.0.42/.gitignore

@@ -1,214 +0,0 @@
-*
-!tests/
-!tests/**
-!README.md
-!AGENTS.md
-!DEVELOPMENT.md
-!QUICKGUIDE.md
-!MILESTONE*.md
-!TESTS*.md
-!CHANGELOG.md
-!AUDIT*.md
-!REF*.md
-!AUDIT*.json
-!LICENSE
-!LICENSE-MIT.txt
-!NOTICE
-!TRADEMARK.md
-!conftest.py
-!CONTRIBUTING.md
-!CODE_OF_CONDUCT.md
-!SECURITY.md
-!GOVERNANCE.md
-!pyproject.toml
-!uv.lock
-!docker-compose.yml
-!.env.example
-!.env.full.example
-!.importlinter
-!.superpowers/
-!.superpowers/**
-!.gitattributes
-!.editorconfig
-!Makefile
-!docker-compose.test.yml
-!quadkit.yaml.example
-!.github/
-!.github/workflows/
-!.github/workflows/**
-!.github/dependabot.yml
-!.devcontainer/
-!.devcontainer/**
-!tools/
-!tools/**
-!*example.yaml
-
-# Quadkit Packages
-!quadkit*/
-!quadkit*/pyproject.toml
-!quadkit*/CHANGELOG.md
-!quadkit*/README.md
-!quadkit*/alembic.ini
-!quadkit*/mypy.ini
-!quadkit*/*.yaml.example
-!quadkit*/src/
-!quadkit*/src/**
-!quadkit*/docs/
-!quadkit*/docs/**
-!quadkit*/tests/
-!quadkit*/tests/**
-
-# Keep quadkit docs
-!/docs/
-!docs/**
-
-# Session / cutover plans at the repo root
-!plans/
-!plans/**
-
-# Keep example files for README examples
-!/examples/
-!/examples/**
-
-# Re-ignore these AFTER negations (last match wins)
-*.tape
-examples/*/runs/
-__pycache__/
-*.pyc
-*.pyo
-*.egg-info/
-dist/
-build/
-.eggs/
-*.egg
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-htmlcov/
-.coverage
-coverage.xml
-test.db
-!quadkit*/tests/fixtures/test.db
-*.log
-*.tmp
-
-# Company-specific files (keep private, do not commit)
-.company/
-COMPANY_*.md
-company-config/
-internal-docs/
-# Editor swap files
-*.swp
-
-!core/
-!packages/
-!core/quadkit*/
-!packages/quadkit*/
-!core/quadkit*/pyproject.toml
-!packages/quadkit*/pyproject.toml
-!core/quadkit*/CHANGELOG.md
-!packages/quadkit*/CHANGELOG.md
-!core/quadkit*/README.md
-!packages/quadkit*/README.md
-!core/quadkit*/alembic.ini
-!packages/quadkit*/alembic.ini
-!core/quadkit*/mypy.ini
-!packages/quadkit*/mypy.ini
-!core/quadkit*/*.yaml.example
-!packages/quadkit*/*.yaml.example
-!core/quadkit*/src/
-!core/quadkit*/src/**
-!packages/quadkit*/src/
-!packages/quadkit*/src/**
-!core/quadkit*/tests/
-!core/quadkit*/tests/**
-!packages/quadkit*/tests/
-!packages/quadkit*/tests/**
-!core/quadkit*/docs/
-!core/quadkit*/docs/**
-!packages/quadkit*/docs/
-!packages/quadkit*/docs/**
-
-# dev/
-!dev/
-!dev/**
-
-# Admin dev playground (committed dev asset; local SQLite files stay ignored)
-!packages/quadkit-admin/playground/
-!packages/quadkit-admin/playground/serve.py
-
-# gatewai apps
-!apps/
-!apps/**
-!apps/gatewai/
-!apps/gatewai/**
-apps/**/node_modules/
-apps/**/dist/
-apps/**/__pycache__/
-apps/**/*.pyc
-apps/**/*.db
-apps/**/*.db-wal
-apps/**/*.db-shm
-apps/**/.env
-apps/**/.env.*
-!apps/**/.env.example
-!apps/**/.env.full.example
-
-# Piccolina — nested app tracked in this monorepo (standalone .git removed).
-# Keep marketing packages and deployment secrets out of the tree.
-apps/piccolina/piccolina-marketing/
-apps/piccolina/piccolina-marketing-plans/
-apps/piccolina/secrets/
-apps/piccolina/**/secrets/
-apps/piccolina/**/*.pem
-apps/piccolina/**/*.key
-apps/piccolina/**/.venv/
-apps/piccolina/**/node_modules/
-apps/piccolina/**/__pycache__/
-apps/piccolina/**/*.pyc
-apps/piccolina/**/*.pbf
-apps/piccolina/**/.open-next/
-apps/piccolina/**/storage/
-apps/piccolina/**/.deploy-host
-
-# Re-exclude private content under the tiered paths.
-# MUST come after the !...docs/** negations above — last match wins.
-core/quadkit*/docs/plans/
-packages/quadkit*/docs/plans/
-core/quadkit*/docs/**/
-packages/quadkit*/docs/**/
-
-# Re-exclude tooling artifacts under the tiered paths
-__pycache__/
-*.pyc
-*.pyo
-*.egg-info/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-htmlcov/
-.coverage
-coverage.xml
-test.db
-*.tmp
-*.log
-!core/quadkit*/tests/fixtures/test.db
-!packages/quadkit*/tests/fixtures/test.db
-
-# Allow the generated example gifs to be tracked (README hero images).
-!core/quadkit*/docs/gifs/
-!core/quadkit*/docs/gifs/**
-!packages/*/quadkit*/docs/gifs/
-!packages/*/quadkit*/docs/gifs/**
-examples/*/screenshot.png
-!banner*
-apps/quadkit-playground/**/node_modules/
-apps/quadkit-playground/**/dist/
-apps/quadkit-playground/**/__pycache__/
-apps/quadkit-playground/**/*.pyc
-apps/quadkit-playground/**/*.db
-apps/quadkit-playground/**/*.db-wal
-apps/quadkit-playground/**/*.db-shm
-apps/quadkit-playground/projects/
-apps/quadkit-playground/quadkit/
-docs/superpowers/

quadkit_cache-0.0.42/docs/ARCHITECTURE.md

@@ -1,275 +0,0 @@
-# Architecture
-
-Internal design of the `quadkit-cache` package.
-
----
-
-## Role in the System
-
-`quadkit-cache` is the **caching abstraction layer** in the Quadkit framework. It depends only on `quadkit` and `quadkit-contracts`. Other packages consume caching through `CacheBackendProtocol` resolved via the DI container — never through direct imports.
-
-```mermaid
-flowchart BT
-    App[Application Layer]
-    Ext[quadkit-* Extensions]
-    LC[quadkit-cache<br/>CacheService · Backends · Stampede Protection]
-    Core[quadkit<br/>DI · Config · Logging]
-    Contracts[quadkit-contracts<br/>CacheBackendProtocol · CacheKeyBuilderProtocol]
-
-    App --> Ext
-    Ext --> LC
-    LC --> Core
-    LC --> Contracts
-    Core --> Contracts
-```
-
-**Import direction:** Arrows point toward the dependency. Services depend on protocols from contracts; backends implement those protocols. The cache provider wires both sides through the container.
-
----
-
-## Backend Abstraction
-
-All cache backends implement `CacheBackendProtocol` from `quadkit-contracts`. Operations return `Result[T, CacheError]` — backend errors are signalled via `Err` rather than exceptions, letting callers decide how to handle failures.
-
-```mermaid
-flowchart LR
-    subgraph Contracts[quadkit-contracts]
-        CBP[CacheBackendProtocol<br/>get · set · delete · clear<br/>get_many · set_many · delete_many<br/>exists · delete_pattern · health_check]
-    end
-    subgraph Backends[quadkit-cache · backends]
-        MEM[MemoryCacheBackend<br/>in-process dict<br/>TTL · LRU eviction]
-        REDIS[RedisCacheBackend<br/>StateStoreProtocol<br/>pipeline · SCAN]
-        MEMCACHED[MemcachedCacheBackend<br/>pymemcache]
-    end
-    subgraph ThirdParty[Third Party]
-        EP[entry-point<br/>quadkit.cache.backends]
-    end
-
-    Backends --> CBP
-    EP --> CBP
-    CBP -->|DI binding| Provider[CacheProvider<br/>register · boot · shutdown]
-```
-
-### Backend Selection
-
-Backends are configured via `CacheConfig.backends`. Each backend specifies a `name`, `type` (memory / redis / memcached), and `default` flag. The provider registers an unnamed `CacheBackendProtocol` singleton for the default backend and named singletons for all enabled backends:
-
-```python
-container.singleton(CacheBackendProtocol, factory=lambda: self.get_backend(None))
-container.singleton(CacheBackendProtocol, factory=lambda n=name: self.get_backend(n), name=name)
-```
-
----
-
-## Cache Operations
-
-`CacheService` is the main high-level API. It composes three mixins:
-
-| Class | Source | Adds |
-|-------|--------|------|
-| `CacheService` | `core.py` | `get`, `set`, `delete`, `exists`, `clear`, `delete_pattern`, `get_typed`, health check |
-| `PipelineMixin` | `pipeline.py` | `get_many`, `set_many`, `delete_many` |
-| `InvalidationMixin` | `invalidation.py` | `set_with_tags`, `invalidate_by_tag` |
-| `PatternsMixin` | `patterns.py` | `get_or_set`, `get_or_compute`, `get_or_set_result`, `remember` |
-
-### Key Behaviours
-
-- **TTL jitter:** `set()` applies ±10% random jitter to spread expiry times and reduce thundering-herd risk.
-- **Fast path:** Primitive values (`str`, `int`, `float`, `bool`) are stored directly without serialization round-trip.
-- **Namespace scoping:** Keys can be request-scoped via `request_scoped=True`, which prepends `req:<request_id>:` to the key.
-- **Error handling:** Backend errors are caught (`RuntimeError`, `OSError`, `ConnectionError`, etc.) and logged; `get` returns `default`, `set`/`delete` return `False`.
-- **Metrics:** Every operation updates an in-memory counter (`hits`, `misses`, `errors`, `operations`). Exposed via `get_metrics()` and `reset_metrics()`.
-
-```python
-cache = container.resolve(CacheService)
-
-await cache.set("user:42", profile, ttl=300)
-profile = await cache.get("user:42", default=None)
-await cache.delete("user:42")
-
-batch = await cache.get_many(["a", "b", "c"])
-await cache.set_many({"x": 1, "y": 2}, ttl=60)
-
-# Tag-based invalidation
-await cache.set_with_tags("pet:1", pet, tags=["user:42"])
-await cache.invalidate_by_tag("user:42")
-
-# Type-safe access
-count = await cache.get_typed("counter", type_=int, default=0)
-```
-
----
-
-## Stampede Protection
-
-Two complementary mechanisms prevent cache stampedes (thundering-herd problems):
-
-### 1. TTL Jitter (Built Into CacheService)
-
-`_add_ttl_jitter()` applies ±10% random variation to every TTL, spreading out natural expiry times so multiple keys don't expire simultaneously.
-
-### 2. Single-Flight Pattern (StampedeProtectedCache)
-
-`StampedeProtectedCache` wraps a `CacheBackendProtocol` (injected via `@inject`) and implements single-flight coalescing:
-
-```mermaid
-flowchart TD
-    R1[Request A<br/>get_or_compute(key)]
-    R2[Request B<br/>get_or_compute(key)]
-    R3[Request C<br/>get_or_compute(key)]
-    STAMP[StampedeProtectedCache]
-    CACHE[Cache Backend]
-    COMPUTE[Compute Function]
-
-    R1 --> STAMP
-    R2 --> STAMP
-    R3 --> STAMP
-
-    STAMP -->|try cache| CACHE
-    CACHE -->|miss| STAMP
-    STAMP -->|acquire lock| STAMP
-    STAMP -->|double-check cache| CACHE
-    CACHE -->|still miss| STAMP
-    STAMP -->|single flight task| COMPUTE
-    COMPUTE -->|value| STAMP
-    STAMP -->|store + return| R1
-    STAMP -->|return same| R2
-    STAMP -->|return same| R3
-```
-
-Key implementation details:
-
-| Mechanism | How It Works |
-|-----------|--------------|
-| **In-process lock** | `asyncio.Lock` per key via `WeakValueDictionary` — concurrent requests for the same key serialize |
-| **Double-check** | After acquiring the lock, re-checks cache (another request may have filled it) |
-| **Single-flight task** | One `asyncio.Task` per key; subsequent requests `await` the same task |
-| **XFetch early refresh** | Probabilistic early refresh: the closer to expiry, the higher the probability a request refreshes before the key expires |
-
-```python
-from quadkit.cache.service.stampede import StampedeProtectedCache
-
-protected = StampedeProtectedCache(backend, lock_timeout=10)
-
-# Only one compute call per key, regardless of concurrent requests
-result = await protected.get_or_compute(
-    key="expensive:data",
-    compute=load_data_from_db,
-    ttl=300,
-    ttl_jitter=0.2,
-)
-```
-
-### XFetch Algorithm
-
-When `ttl_jitter > 0`, `StampedeProtectedCache` applies probabilistic early refresh (XFetch). A request that finds a cached but partially-stale entry will refresh it with probability proportional to how close it is to expiry:
-
-```
-staleness = 1.0 - (time_left / ttl)
-refresh if random() < staleness   # higher probability near expiry
-```
-
----
-
-## Provider Lifecycle
-
-```mermaid
-sequenceDiagram
-    actor User as Container
-    participant P as CacheProvider
-    participant REG as BackendRegistry
-    participant B as Backend Instance
-    participant PROT as StampedeProtectedCache
-    participant SVC as CacheService
-
-    User->>P: CacheProvider(config)
-    P->>P: configure(config)
-
-    User->>P: register(container)
-    P->>REG: BackendRegistry()
-    P->>REG: register entry-point backends
-    P->>P: bind factories (no I/O)
-    Note over P: CacheBackendProtocol → lazy factory<br/>CacheService → lazy factory<br/>BackendRegistry → singleton<br/>CacheStatusRegistry → singleton
-
-    User->>P: boot(container)
-    P->>B: create_backend(config)
-    Note over B: Redis connect<br/>or Memory init
-    B-->>P: backend instance
-    P->>PROT: StampedeProtectedCache(backend)
-    P->>SVC: CacheService(provider, protection)
-    Note over SVC: PipelineMixin + InvalidationMixin<br/>+ PatternsMixin composed
-
-    User->>SVC: get/set operations
-    SVC->>B: delegated backend call
-
-    User->>P: shutdown()
-    P->>SVC: close()
-    P->>B: close()
-    Note over P: services.clear()<br/>backends.clear()
-```
-
-### Provider Configuration
-
-```python
-class CacheProvider(Provider):
-    name = "cache"
-    priority = ProviderPriority.INFRASTRUCTURE  # 10
-    config_key = "cache"                         # QK_CACHE__* env vars
-```
-
-| Phase | Action | I/O? |
-|-------|--------|------|
-| `__init__` | Store config, initialize serializers | No |
-| `register()` | Bind lazy factories, discover entry-point backends, register admin components | No |
-| `boot()` | Create backends (open connections), wire stampede protection, create services, register admin hooks | Yes |
-| `shutdown()` | Close services → close backends → clear state | Yes |
-
----
-
-## Contracts Used
-
-| Contract | Source | Purpose |
-|----------|--------|---------|
-| `CacheBackendProtocol` | `quadkit.contracts.infra.cache` | Primary backend interface: `get`, `set`, `delete`, `clear`, `exists`, `get_many`, `set_many`, `delete_many`, `delete_pattern`, `health_check` |
-| `CacheKeyBuilderProtocol` | `quadkit.contracts.infra.cache` | Key construction and namespace management |
-| `CacheProtectionStrategyProtocol` | `quadkit.contracts.infra.cache` | Stampede protection contract |
-| `CacheProviderProtocol` | `quadkit.contracts.infra.cache` | Provider self-reference for DI resolution |
-| `CacheHealthCheckerProtocol` | `quadkit.contracts.infra.cache` | Backend health checks |
-| `StateStoreProtocol` | `quadkit.contracts.infra` | Low-level key-value store (Redis backends) |
-| `AsyncStringSerializerProtocol` | `quadkit.contracts.core.serialization` | Serialization interface (JSON, Pickle, Msgpack) |
-| `SemanticCacheProtocol` | `quadkit.contracts.ai.llm` | Semantic caching (optional, requires faiss) |
-| `EmbeddingClientProtocol` | `quadkit.contracts.ai.llm` | Embedding generation for semantic caching |
-| `HealthCheckResult` | `quadkit.contracts.core` | Structured health check type |
-| `HookRegistryProtocol` | `quadkit.contracts.core` | Lifecycle hook emission |
-
----
-
-## Extension Points
-
-| Point | Mechanism |
-|-------|-----------|
-| Custom backend | Implement `CacheBackendProtocol`, register via `quadkit.cache.backends` entry point |
-| Custom serializer | Implement `AsyncStringSerializerProtocol` |
-| Custom cache key builder | Implement `CacheKeyBuilderProtocol` |
-| Custom stampede strategy | Implement `CacheProtectionStrategyProtocol` |
-| Named multi-backend | Add entries to `CacheConfig.backends` with unique `name` |
-| Cache status handler | Implement `CacheStatusHandler`, register with `CacheStatusRegistry` |
-| Cache warmer | Subclass or configure `CacheWarmer` |
-| Semantic caching | Install `faiss`, provide `EmbeddingClientProtocol` |
-| Cacheable decorator | Use `@cacheable` from `decorators.py` |
-| Repository caching | Use `CacheRepository` from `repository/` with invalidation observer pattern |
-| Admin widgets | Registered via `CacheAdminContributor`; extend with custom handlers |
-| Operator CLI | Extend the `quadkit cache` CLI commands |
-| Hooks | Register `HookRegistryProtocol` action handlers (`cache.hit`, `cache.miss`, `cache.evicted`) |
-
-### Backend Registration via Entry Points
-
-Third-party backends self-register using the `quadkit.cache.backends` entry point group. During `register()` the provider scans this group and calls each provider's `register()` method:
-
-```python
-# pyproject.toml
-[project.entry-points."quadkit.cache.backends"]
-my_backend = "my_package:MyBackendProvider"
-```
-
-Each entry point must resolve to a `Provider` subclass. The provider handles container bindings for its backend; the CacheProvider's `boot()` never references third-party types directly.