cloud-dog-cache 0.2.0__tar.gz

cloud_dog_cache-0.2.0/.docs-manifest.yml

@@ -0,0 +1,6 @@
+schema-version: 1.0
+project: platform-cache
+canon-set: PACKAGE
+canon-template-baseline: 1.0
+conditional-docs: []
+additional-docs: []

cloud_dog_cache-0.2.0/.gitignore

@@ -0,0 +1 @@
+tmp/

cloud_dog_cache-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,40 @@
+---
+template-id: T-PKG-ARC
+template-version: 1.0
+applies-to: ARCHITECTURE.md
+registry: package
+required: must-have
+when-applicable: ""
+template-last-updated: 2026-06-12
+template-owner: platform-standards
+
+project: platform-cache
+public: true
+doc-last-updated: 2026-06-12
+doc-git-commit: no-git
+doc-git-branch: main
+doc-source-shas: []
+doc-age-policy: indefinite
+doc-conformance-stamp: 2026-06-12T12:00:00Z
+---
+
+# platform-cache — ARCHITECTURE
+
+> **Template version:** T-PKG-ARC v1.0
+
+## 1. Purpose
+What problem the package solves.
+
+## 2. Modules
+| Module | Responsibility |
+|---|---|
+
+## 3. Relationships
+Dependencies on other Cloud-Dog packages, external libs.
+
+## 4. Extension points
+How consumers plug in.
+
+## 5. Cross-references
+- [REQUIREMENTS.md](REQUIREMENTS.md), [DATA-MODEL.md](DATA-MODEL.md)
+- Consumer services

cloud_dog_cache-0.2.0/BUILD.md

@@ -0,0 +1,64 @@
+# Build Instructions
+
+## Package
+`cloud_dog_cache` - caching helpers for platform services.
+
+## Prerequisites
+- Python 3.11+
+- pip
+
+## Development Setup
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip build twine pytest
+pip install -e .
+```
+
+To include the optional Redis extra:
+```bash
+pip install -e .[redis]
+```
+
+## Local Use
+```bash
+python -c "import cloud_dog_cache; print('package import ok')"
+```
+
+## Run Tests
+```bash
+python -m pytest tests/unit -v
+```
+
+## Build Distribution
+```bash
+python -m build
+```
+
+## Publish
+```bash
+twine upload --repository-url $PYPI_URL dist/*
+```
+
+## Docker Packaging
+```bash
+PYPI_URL=https://packages.example.com/simple/ \
+PYPI_USERNAME=build-user \
+PYPI_PASSWORD=build-password \
+docker build -t cloud_dog_cache:latest .
+```
+
+## Dependencies
+- optional Redis support is available through the `redis` extra
+- see `pyproject.toml` for the exact dependency set
+
+## Configuration
+This package does not require a dedicated env overlay for unit testing; configure cache backends with standard shell environment variables when embedding it in an application.
+
+## Vault Integration
+```bash
+export VAULT_ADDR=https://vault.example.com
+export VAULT_TOKEN=your-token
+export VAULT_MOUNT_POINT=your-mount
+export VAULT_CONFIG_PATH=your-path
+```

cloud_dog_cache-0.2.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.2.0 (2026-05-04)
+
+- **NEW: URL-addressable cache layer** (`cloud_dog_cache.access`)
+  - `URLAddressableCache` wraps a `CacheManager` to expose cache entries via
+    externally-fetchable URLs. Closes the architectural gap surfaced by W28A
+    #A16 (notification-agent's `ImageCacheManager` had no platform replacement
+    for its `access_url` semantic).
+  - `AccessUrlConfig` — `base_url`, `signing_secret`, `default_url_ttl_seconds`,
+    `access_path_prefix`.
+  - `AccessUrlEntry` — return shape for `set_with_url`, mirrors the historical
+    `ImageCacheManager.cache_image` response keys (cache_key, access_url, etc.).
+  - Two URL modes: **unsigned** (`{base}/cache/access/{key}` — assumes upstream
+    auth) and **signed** (HMAC-SHA256 over `key|expires_ts`, expiry verified
+    server-side at fetch time).
+  - URL TTL is independent of cache content TTL — long-lived cache entries can
+    mint short-lived signed URLs.
+  - `create_access_url_router(cache, *, media_type_resolver=None)` —
+    drop-in FastAPI router serving `GET {prefix}/{key}` with signature +
+    expiry validation.
+- Pure additive change. No existing API surface modified. Backward compatible
+  with all 0.1.x consumers.
+
+## 0.1.1
+
+- Patch release.
+
+## 0.1.0 (2026-03-27)
+
+- Initial release
+- In-memory LRU backend with TTL
+- Redis backend (optional)
+- @cached decorator for async functions
+- Event-based invalidation (context_rebuild, config_change, prompt_change)
+- Tag-based flush
+- CacheStats model

cloud_dog_cache-0.2.0/DATA-MODEL.md

@@ -0,0 +1,33 @@
+---
+template-id: T-PKG-DMT
+template-version: 1.0
+applies-to: DATA-MODEL.md
+registry: package
+required: must-have
+when-applicable: ""
+template-last-updated: 2026-06-12
+template-owner: platform-standards
+
+project: platform-cache
+public: true
+doc-last-updated: 2026-06-12
+doc-git-commit: no-git
+doc-git-branch: main
+doc-source-shas: []
+doc-age-policy: indefinite
+doc-conformance-stamp: 2026-06-12T12:00:00Z
+---
+
+# platform-cache — DATA-MODEL
+
+> **Template version:** T-PKG-DMT v1.0
+
+## 1. Exported types
+| Type | Shape | Purpose |
+|---|---|---|
+
+## 2. Persisted state
+If the package owns persisted state, describe schema.
+
+## 3. Cross-references
+- [ARCHITECTURE.md](ARCHITECTURE.md)

cloud_dog_cache-0.2.0/LICENCE

@@ -0,0 +1,13 @@
+Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

cloud_dog_cache-0.2.0/NOTICE

@@ -0,0 +1,24 @@
+---
+template-id: T-PKG-NOT
+template-version: 1.0
+applies-to: NOTICE
+registry: package
+required: must-have
+when-applicable: ""
+template-last-updated: 2026-06-12
+template-owner: platform-standards
+
+project: platform-cache
+public: true
+doc-last-updated: 2026-06-12
+doc-git-commit: no-git
+doc-git-branch: main
+doc-source-shas: []
+doc-age-policy: indefinite
+doc-conformance-stamp: 2026-06-12T12:00:00Z
+---
+
+platform-cache
+Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+
+Licensed under the Apache License, Version 2.0.

cloud_dog_cache-0.2.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: cloud_dog_cache
+Version: 0.2.0
+Summary: Platform caching package for LLM and tool call results
+Author: Cloud-Dog, Viewdeck Engineering Limited
+License-Expression: Apache-2.0
+License-File: LICENCE
+License-File: NOTICE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'

cloud_dog_cache-0.2.0/README.md

@@ -0,0 +1,28 @@
+# cloud_dog_cache
+
+Platform caching package for LLM and tool call results.
+
+## Quick Start
+
+```python
+from cloud_dog_cache import cached, init_cache, CacheConfig
+
+# Initialise
+init_cache(CacheConfig(enabled=True, backend="memory", ttl_seconds=3600))
+
+# Decorate async functions
+@cached(ttl=3600, invalidate_on=["context_rebuild"])
+async def generate_sql(query: str, context_hash: str) -> str:
+    ...
+```
+
+## Backends
+
+- `memory` (default) — In-memory LRU with configurable max entries
+- `redis` — Redis-backed with tag-based invalidation
+
+## Invalidation
+
+- TTL-based expiry
+- Event-based: `invalidate_event("context_rebuild")`
+- Manual: `await manager.flush()`

cloud_dog_cache-0.2.0/REQUIREMENTS.md

@@ -0,0 +1,37 @@
+---
+template-id: T-PKG-REQ
+template-version: 1.0
+applies-to: REQUIREMENTS.md
+registry: package
+required: must-have
+when-applicable: ""
+template-last-updated: 2026-06-12
+template-owner: platform-standards
+
+project: platform-cache
+public: true
+doc-last-updated: 2026-06-12
+doc-git-commit: no-git
+doc-git-branch: main
+doc-source-shas: []
+doc-age-policy: indefinite
+doc-conformance-stamp: 2026-06-12T12:00:00Z
+---
+
+# platform-cache — REQUIREMENTS
+
+> **Template version:** T-PKG-REQ v1.0
+
+## 1. Functional
+| ID | Requirement | Consumer | Tests |
+|---|---|---|---|
+
+## 2. Non-functional
+| ID | Requirement | Measure |
+|---|---|---|
+
+## 3. Compatibility
+Python/Node versions, OS, peer-deps.
+
+## 4. Cross-references
+- [ARCHITECTURE.md](ARCHITECTURE.md), [TESTS.md](TESTS.md)

cloud_dog_cache-0.2.0/TESTS.md

@@ -0,0 +1,37 @@
+---
+template-id: T-PKG-TST
+template-version: 1.0
+applies-to: TESTS.md
+registry: package
+required: must-have
+when-applicable: ""
+template-last-updated: 2026-06-12
+template-owner: platform-standards
+
+project: platform-cache
+public: true
+doc-last-updated: 2026-06-12
+doc-git-commit: no-git
+doc-git-branch: main
+doc-source-shas: []
+doc-age-policy: 90d
+doc-conformance-stamp: 2026-06-12T12:00:00Z
+---
+
+# platform-cache — TESTS
+
+> **Template version:** T-PKG-TST v1.0
+
+## 1. Coverage
+| Test ID | Module | Requirement | Tier |
+|---|---|---|---|
+
+## 2. Running
+```bash
+pytest                # backend
+npm test              # frontend
+```
+
+## 3. Cross-references
+- [REQUIREMENTS.md](REQUIREMENTS.md)
+- PS-95-testing.md

cloud_dog_cache-0.2.0/cloud_dog_cache/__init__.py

@@ -0,0 +1,84 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""cloud_dog_cache — Platform caching package for LLM and tool call results.
+
+Provides a transparent caching layer with configurable TTL, pluggable backends
+(in-memory LRU, Redis), and event-based invalidation for context rebuilds,
+config changes, and prompt template changes.
+
+Usage::
+
+    from cloud_dog_cache import cached, CacheManager, get_cache_manager
+
+    @cached(ttl=3600, invalidate_on=["context_rebuild"])
+    async def generate_sql(query: str, context_hash: str, model: str) -> str:
+        ...
+
+    # Manual access
+    manager = get_cache_manager()
+    await manager.flush()
+    stats = await manager.stats()
+"""
+
+__version__ = "0.3.0"
+
+from cloud_dog_cache.manager import CacheManager, get_cache_manager, init_cache
+from cloud_dog_cache.decorator import cached
+from cloud_dog_cache.keys import cache_key, hash_text, hash_config
+from cloud_dog_cache.stats import CacheStats
+from cloud_dog_cache.models import CacheConfig, CacheEntry
+from cloud_dog_cache.invalidation import invalidate_event
+from cloud_dog_cache.runtime import init_cache_from_config
+from cloud_dog_cache.api import create_cache_router
+from cloud_dog_cache.access import (
+    AccessUrlConfig,
+    AccessUrlEntry,
+    URLAddressableCache,
+    create_access_url_router,
+)
+from cloud_dog_cache.memory import (
+    MemoryScope,
+    MemoryNamespace,
+    MemoryEntry,
+    MemoryStore,
+    VectorSearchAdapter,
+    DEFAULT_SCOPE_TTL,
+)
+
+__all__ = [
+    "AccessUrlConfig",
+    "AccessUrlEntry",
+    "CacheConfig",
+    "CacheEntry",
+    "CacheManager",
+    "CacheStats",
+    "DEFAULT_SCOPE_TTL",
+    "MemoryEntry",
+    "MemoryNamespace",
+    "MemoryScope",
+    "MemoryStore",
+    "URLAddressableCache",
+    "VectorSearchAdapter",
+    "cached",
+    "cache_key",
+    "create_access_url_router",
+    "create_cache_router",
+    "get_cache_manager",
+    "hash_config",
+    "hash_text",
+    "init_cache",
+    "init_cache_from_config",
+    "invalidate_event",
+]