prompture 1.13.5.dev1__tar.gz → 1.13.5.dev2__tar.gz

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/.env.copy

@@ -252,6 +252,12 @@ PROMPTURE_SEARCH_PROVIDERS=
 PROMPTURE_FETCH_BACKENDS=
 # Allow tools to reach private/loopback addresses (off by default).
 PROMPTURE_WEB_ALLOW_PRIVATE=
+# Local cache for search / fetch / reader results: disk (default, shared
+# across processes), memory (this process only) or off. Lifetimes depend on
+# the content: minutes for weather/prices/news, days for papers/transcripts.
+PROMPTURE_WEB_CACHE=
+# Where the disk cache lives (default ~/.prompture/cache/web_cache.db).
+PROMPTURE_WEB_CACHE_PATH=
 
 # ─── Media understanding (transcripts / summaries) ───────────────────────────
 # Uses the first configured STT key: GROQ_API_KEY ▸ OPENAI_API_KEY ▸

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.13.5.dev1
+Version: 1.13.5.dev2
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT
@@ -162,6 +162,37 @@ print(person.name)  # Maria
 > | `ollama/llama3.1:8b`, … (local) | no extra needed | — (set `OLLAMA_HOST` if non-default) |
 > | everything in one go | `pip install "prompture[all]"` | provider-specific |
 
+## Agents That Can Search, Read, Watch and Listen
+
+Prompture also gives agents working capabilities, and **none of them need an
+API key to start**. Keys only raise limits and quality.
+
+```python
+from prompture import Agent
+
+agent = Agent(
+    "openai/gpt-4o-mini",
+    tools=["web:all", "pack:dev", "mcp:exa"],   # search, read any URL, transcribe, GitHub/HN/arXiv, MCP
+    system_prompt="Cite every fact with a URL you opened.",
+)
+print(agent.run("Summarize https://youtu.be/<id> and find related papers").output)
+```
+
+```bash
+prompture doctor                               # what works on this machine and how to fix the rest
+prompture research "What changed in Python 3.13?" --depth quick   # cited multi-source report
+prompture transcribe talk.mp3 --summary        # timestamped transcript + key points
+prompture mcp add --preset exa                 # mount MCP servers by name
+prompture skill install                        # teach your coding agent all of this
+```
+
+- **Web:** keyless search, fetch and readers for YouTube, GitHub, Hacker News, arXiv, Wikipedia, feeds and podcasts
+- **Fails over, never just fails:** every capability tries the next backend on auth, quota or rate-limit errors and tells you which one served the result
+- **Cached locally:** repeat searches and static pages come back instantly; weather, prices and news expire in minutes, papers and transcripts in days
+- **Safe by default:** public URLs only, size caps, secret scrubbing, and audio never goes to a second provider without your consent
+
+Full guide: [Capabilities](#capabilities).
+
 ## Prompture Desk: Usage in Your Tray
 
 **See what your LLM calls cost, live, from your tray.** [Prompture Desk](https://github.com/jhd3197/Prompture-Desk) tracks tokens and spend per provider and project, rate-limit headroom, balances, and your coding tools (Claude Code, Codex, …). Windows, macOS and Linux.
@@ -194,8 +225,7 @@ No setup: Desk runs `prompture companion` (Prompture 1.13+) on localhost for you
 **Agents, tools, RAG**
 - Stateful conversations with sync + async support
 - Function calling and streaming across providers, with prompt-based simulation for models without native tool use
-- Drop-in tools: sandboxed `python_execute` (Tukuy), keyless `web_search` / `web_fetch` / `read_url` (YouTube, GitHub, HN, arXiv, Wikipedia, feeds, podcasts) — see [Capabilities](#capabilities)
-- Mount tools by name: `tools=["web:all", "mcp:exa", "pack:finance", "cli:gh"]`; `ResearchAgent` for cited multi-source research
+- Drop-in tools: sandboxed `python_execute` (Tukuy) plus the [capability layer](#capabilities) below
 - `DeepAgent` with planning, virtual filesystem, sub-agents, and auto-summarization — no LangChain
 - Full RAG stack — loaders, chunkers, vector stores, hybrid dense+BM25 retrieval, end-to-end `RAGPipeline` — see [RAG](#rag)
 
@@ -204,8 +234,16 @@ No setup: Desk runs `prompture companion` (Prompture 1.13+) on localhost for you
 - `RefusalDetector` / `RefusalEvaluator` for cross-provider alignment scoring
 - `generate_qa_dataset()` — synthetic JSONL datasets ready for Unsloth, Axolotl, TRL
 
-**Ops**
+**Capabilities** — see [Capabilities](#capabilities)
+- Keyless `web_search`, `web_fetch` and `read_url` (YouTube, GitHub, HN, arXiv, Wikipedia, feeds, podcasts), with failover across keyed providers
+- Local web cache with content-aware lifetimes: minutes for weather, prices and news, days for papers and transcripts
+- `transcribe` / `summarize_media` for video, podcasts and audio, with timestamped key points
+- `ResearchAgent` / `prompture research` — cited multi-source reports within fetch, token, cost and time budgets
+- MCP hub, wrapped CLI tools (`gh`, `yt-dlp`) and domain packs (finance, news, dev, places), mounted by name: `tools=["mcp:exa", "pack:finance", "cli:gh"]`
 - `prompture doctor` — what works on this machine (providers, tools, media, MCP servers, binaries), which backend is active, and the exact fix for anything that isn't
+- `prompture setup` with an owner-only credential store and profiles; `prompture skill install` teaches coding agents to use all of it
+
+**Ops**
 - Resilient routing — `resilient()` retries transient errors, honors `Retry-After`, rotates API keys, trips circuit breakers and fails over across models; every response records who served it — see [Resilient Routing](#resilient-routing)
 - [Prompture Desk](#prompture-desk-usage-in-your-tray) — desktop tray app: usage per provider and project, rate limits and balances, live calls
 - [prompture-hub](#prompture-hub-gateway--dashboard) — optional companion app: web dashboard, scoped per-app keys, spend caps and per-call metering (`pip install prompture[hub]`)
@@ -2103,6 +2141,27 @@ agent = Agent("openai/gpt-4o", tools=["web:all"])
   refused, redirects are re-checked per hop, bodies are size-capped and
   challenge pages move to the next backend.
 
+**Local cache.** Results are cached in `~/.prompture/cache/web_cache.db`, so a
+repeated search or page comes back instantly, even from another process. Each
+entry lives as long as that kind of content stays true:
+
+| Content | Lifetime |
+|---|---|
+| Searches about weather, prices, scores, news, "today", or `recency_days <= 1` | 10 min |
+| Fast-moving pages (Hacker News, Reddit, X, status pages), GitHub issues/PRs | 10 min |
+| Feeds | 15 min |
+| Platform search (GitHub, HN, arXiv, YouTube) | 30 min |
+| Ordinary pages / searches within `recency_days <= 7` | 1 h |
+| Other searches | 6 h |
+| Wikipedia, podcast episodes | 1 day |
+| Papers, PDFs, DOIs, commit-pinned GitHub files, YouTube transcripts | 7 days |
+
+Cached results say so (`route["cached"]`, `cache_age_s`, and "cached 3 min
+ago" in the Markdown footer). Errors and empty results are never stored. Pass
+`use_cache=False` or `cache_ttl=<seconds>` per call, set
+`PROMPTURE_WEB_CACHE=memory|off` to change the store, and
+`clear_web_cache()` or `prompture reset` to empty it.
+
 ### Media understanding: transcripts and summaries
 
 ```python

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/README.md

@@ -45,6 +45,37 @@ print(person.name)  # Maria
 > | `ollama/llama3.1:8b`, … (local) | no extra needed | — (set `OLLAMA_HOST` if non-default) |
 > | everything in one go | `pip install "prompture[all]"` | provider-specific |
 
+## Agents That Can Search, Read, Watch and Listen
+
+Prompture also gives agents working capabilities, and **none of them need an
+API key to start**. Keys only raise limits and quality.
+
+```python
+from prompture import Agent
+
+agent = Agent(
+    "openai/gpt-4o-mini",
+    tools=["web:all", "pack:dev", "mcp:exa"],   # search, read any URL, transcribe, GitHub/HN/arXiv, MCP
+    system_prompt="Cite every fact with a URL you opened.",
+)
+print(agent.run("Summarize https://youtu.be/<id> and find related papers").output)
+```
+
+```bash
+prompture doctor                               # what works on this machine and how to fix the rest
+prompture research "What changed in Python 3.13?" --depth quick   # cited multi-source report
+prompture transcribe talk.mp3 --summary        # timestamped transcript + key points
+prompture mcp add --preset exa                 # mount MCP servers by name
+prompture skill install                        # teach your coding agent all of this
+```
+
+- **Web:** keyless search, fetch and readers for YouTube, GitHub, Hacker News, arXiv, Wikipedia, feeds and podcasts
+- **Fails over, never just fails:** every capability tries the next backend on auth, quota or rate-limit errors and tells you which one served the result
+- **Cached locally:** repeat searches and static pages come back instantly; weather, prices and news expire in minutes, papers and transcripts in days
+- **Safe by default:** public URLs only, size caps, secret scrubbing, and audio never goes to a second provider without your consent
+
+Full guide: [Capabilities](#capabilities).
+
 ## Prompture Desk: Usage in Your Tray
 
 **See what your LLM calls cost, live, from your tray.** [Prompture Desk](https://github.com/jhd3197/Prompture-Desk) tracks tokens and spend per provider and project, rate-limit headroom, balances, and your coding tools (Claude Code, Codex, …). Windows, macOS and Linux.
@@ -77,8 +108,7 @@ No setup: Desk runs `prompture companion` (Prompture 1.13+) on localhost for you
 **Agents, tools, RAG**
 - Stateful conversations with sync + async support
 - Function calling and streaming across providers, with prompt-based simulation for models without native tool use
-- Drop-in tools: sandboxed `python_execute` (Tukuy), keyless `web_search` / `web_fetch` / `read_url` (YouTube, GitHub, HN, arXiv, Wikipedia, feeds, podcasts) — see [Capabilities](#capabilities)
-- Mount tools by name: `tools=["web:all", "mcp:exa", "pack:finance", "cli:gh"]`; `ResearchAgent` for cited multi-source research
+- Drop-in tools: sandboxed `python_execute` (Tukuy) plus the [capability layer](#capabilities) below
 - `DeepAgent` with planning, virtual filesystem, sub-agents, and auto-summarization — no LangChain
 - Full RAG stack — loaders, chunkers, vector stores, hybrid dense+BM25 retrieval, end-to-end `RAGPipeline` — see [RAG](#rag)
 
@@ -87,8 +117,16 @@ No setup: Desk runs `prompture companion` (Prompture 1.13+) on localhost for you
 - `RefusalDetector` / `RefusalEvaluator` for cross-provider alignment scoring
 - `generate_qa_dataset()` — synthetic JSONL datasets ready for Unsloth, Axolotl, TRL
 
-**Ops**
+**Capabilities** — see [Capabilities](#capabilities)
+- Keyless `web_search`, `web_fetch` and `read_url` (YouTube, GitHub, HN, arXiv, Wikipedia, feeds, podcasts), with failover across keyed providers
+- Local web cache with content-aware lifetimes: minutes for weather, prices and news, days for papers and transcripts
+- `transcribe` / `summarize_media` for video, podcasts and audio, with timestamped key points
+- `ResearchAgent` / `prompture research` — cited multi-source reports within fetch, token, cost and time budgets
+- MCP hub, wrapped CLI tools (`gh`, `yt-dlp`) and domain packs (finance, news, dev, places), mounted by name: `tools=["mcp:exa", "pack:finance", "cli:gh"]`
 - `prompture doctor` — what works on this machine (providers, tools, media, MCP servers, binaries), which backend is active, and the exact fix for anything that isn't
+- `prompture setup` with an owner-only credential store and profiles; `prompture skill install` teaches coding agents to use all of it
+
+**Ops**
 - Resilient routing — `resilient()` retries transient errors, honors `Retry-After`, rotates API keys, trips circuit breakers and fails over across models; every response records who served it — see [Resilient Routing](#resilient-routing)
 - [Prompture Desk](#prompture-desk-usage-in-your-tray) — desktop tray app: usage per provider and project, rate limits and balances, live calls
 - [prompture-hub](#prompture-hub-gateway--dashboard) — optional companion app: web dashboard, scoped per-app keys, spend caps and per-call metering (`pip install prompture[hub]`)
@@ -1986,6 +2024,27 @@ agent = Agent("openai/gpt-4o", tools=["web:all"])
   refused, redirects are re-checked per hop, bodies are size-capped and
   challenge pages move to the next backend.
 
+**Local cache.** Results are cached in `~/.prompture/cache/web_cache.db`, so a
+repeated search or page comes back instantly, even from another process. Each
+entry lives as long as that kind of content stays true:
+
+| Content | Lifetime |
+|---|---|
+| Searches about weather, prices, scores, news, "today", or `recency_days <= 1` | 10 min |
+| Fast-moving pages (Hacker News, Reddit, X, status pages), GitHub issues/PRs | 10 min |
+| Feeds | 15 min |
+| Platform search (GitHub, HN, arXiv, YouTube) | 30 min |
+| Ordinary pages / searches within `recency_days <= 7` | 1 h |
+| Other searches | 6 h |
+| Wikipedia, podcast episodes | 1 day |
+| Papers, PDFs, DOIs, commit-pinned GitHub files, YouTube transcripts | 7 days |
+
+Cached results say so (`route["cached"]`, `cache_age_s`, and "cached 3 min
+ago" in the Markdown footer). Errors and empty results are never stored. Pass
+`use_cache=False` or `cache_ttl=<seconds>` per call, set
+`PROMPTURE_WEB_CACHE=memory|off` to change the store, and
+`clear_web_cache()` or `prompture reset` to empty it.
+
 ### Media understanding: transcripts and summaries
 
 ```python

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/llms.txt

@@ -39,7 +39,7 @@ Model strings are `provider/model` (e.g. `openai/gpt-4o-mini`, `claude/claude-ha
 - `prompture.drivers`: one driver per provider; `get_driver_for_model("provider/model")`
 - `prompture.resilience`: `resilient()`, `classify_error`, combos and virtual models
 - `prompture.capabilities`: `BackendChain`, `probe_command`, `HealthStatus`, `safe_get`, `normalize_public_http_url`
-- `prompture.tools.web`: `web_search`, `web_fetch`, `read_url`, `search_platform`, `WebToolkit`
+- `prompture.tools.web`: `web_search`, `web_fetch`, `read_url`, `search_platform`, `WebToolkit`, local cache (`clear_web_cache`, `cache_info`, `PROMPTURE_WEB_CACHE`)
 - `prompture.media.understand`: `transcribe`, `summarize_media`
 - `prompture.mcp`: MCP client/server and `hub` (`MCPHub`, `resolve_mcp_tools`)
 - `prompture.tools.cli`, `prompture.tools.packs`: `CLITool`, domain packs

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.13.5.dev1'
-__version_tuple__ = version_tuple = (1, 13, 5, 'dev1')
+__version__ = version = '1.13.5.dev2'
+__version_tuple__ = version_tuple = (1, 13, 5, 'dev2')
 
 __commit_id__ = commit_id = None

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/prompture/cli/setup_cmd.py

@@ -550,7 +550,7 @@ _STATE_DESCRIPTIONS = {
     "credentials.yaml": "stored credentials and settings",
     "mcp.json": "named MCP servers",
     "usage": "usage ledger databases",
-    "cache": "model-rate, response and plan-usage caches",
+    "cache": "model-rate, response, web and plan-usage caches",
     "update_check.json": "update-check state",
     "companion.json": "local companion address and token",
     "companion-prefs.json": "companion preferences",

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/prompture/skill/data/references/search.md

@@ -65,6 +65,14 @@ The report only cites pages it actually opened. Model defaults to
 `PROMPTURE_RESEARCH_MODEL`, then the first configured provider's cheap model.
 Other agents can call it as a tool: `tools=[research_tool(depth="quick")]`.
 
+## Cache
+
+Results are cached locally (`~/.prompture/cache/web_cache.db`). Volatile
+searches (weather, prices, scores, news, "today", `recency_days <= 1`) live 10
+minutes; others live hours. A cached result has `route["cached"] is True` and
+`route["cache_age_s"]` — say so when it matters ("from a search 5 min ago").
+For something that must be live right now, pass `use_cache=False`.
+
 ## When search fails
 
 1. `prompture doctor --only tools --json` → look at the `web_search` row.

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/prompture/skill/data/references/web.md

@@ -41,8 +41,18 @@ if page.truncated:
     more = web_fetch(page.url, start=page.next_start)   # paging
 ```
 
-Long pages end with `[truncated — call again with start=N]`. Results are
-cached for 10 minutes. `compress=True` trims boilerplate for agent loops.
+Long pages end with `[truncated — call again with start=N]`; paging reads
+from the cache, not the network. `compress=True` trims boilerplate for agent
+loops.
+
+## Cache
+
+`web_fetch`, `read_url` and `search_platform` share a local cache whose
+lifetime follows the content: 10 minutes for Hacker News, Reddit, X, status
+pages and GitHub issues/PRs, 1 hour for ordinary pages, 1 day for Wikipedia,
+7 days for papers, PDFs, DOIs and YouTube transcripts. Cached results carry
+`route["cached"]` and `route["cache_age_s"]`. Use `use_cache=False` when the
+user needs the page as it is right now; `PROMPTURE_WEB_CACHE=off` disables it.
 
 ## Safety (don't work around these)
 

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/prompture/tools/web/__init__.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 
 from ._mcp_http import MCPError, MCPHttpClient
 from ._types import SearchResponse, SearchResult
+from .cache import cache_info, clear_web_cache
 from .fetch import (
     FETCH_BACKENDS,
     FETCH_OVERRIDE_ENV,
@@ -99,7 +100,9 @@ __all__ = [
     "afetch",
     "aread_url",
     "asearch",
+    "cache_info",
     "clear_fetch_cache",
+    "clear_web_cache",
     "fetch_chain",
     "find_feed_links",
     "get_reader",

{prompture-1.13.5.dev1 → prompture-1.13.5.dev2}/prompture/tools/web/_types.py

@@ -30,9 +30,25 @@ def _route_footer(served_by: str, route: dict[str, Any], verb: str = "served by"
     failed = [a.get("backend") for a in route.get("attempts", []) if a.get("status") == "error"]
     if route.get("fallback") and failed:
         footer += f" (fallback after {', '.join(dict.fromkeys(str(f) for f in failed))} failed)"
+    if route.get("cached"):
+        footer += f", cached {_age_text(route.get('cache_age_s'))}"
     return footer + "_"
 
 
+def _age_text(age: Any) -> str:
+    try:
+        seconds = float(age)
+    except (TypeError, ValueError):
+        return "earlier"
+    if seconds < 60:
+        return "just now"
+    if seconds < 3600:
+        return f"{int(seconds // 60)} min ago"
+    if seconds < 86400:
+        return f"{int(seconds // 3600)} h ago"
+    return f"{int(seconds // 86400)} d ago"
+
+
 @dataclass
 class SearchResponse:
     """Search results plus the route that produced them.

prompture-1.13.5.dev2/prompture/tools/web/cache.py

@@ -0,0 +1,296 @@
+"""Local cache for web search, fetch, URL readers and platform search.
+
+Repeated questions shouldn't cost a network round trip, but a weather or
+price query must not be served from yesterday. Each entry gets a lifetime
+from :func:`ttl_for`, based on how fast that kind of content changes:
+
+=====================================================  ==========
+Content                                                Lifetime
+=====================================================  ==========
+Volatile searches (weather, prices, scores, news,      10 min
+"today", ``recency_days <= 1``)
+Recent-window searches (``recency_days <= 7``)         1 h
+Other searches                                         6 h
+Platform search (GitHub, HN, arXiv, YouTube)           30 min
+Fast-moving pages (HN, Reddit, X, status pages)        10 min
+Ordinary pages                                         1 h
+Wikipedia                                              1 day
+Papers, PDFs, DOIs, commit-pinned GitHub files,        7 days
+YouTube transcripts
+GitHub issues / pull requests, HN items                10 min
+Feeds                                                  15 min
+Podcast episodes                                       1 day
+=====================================================  ==========
+
+``PROMPTURE_WEB_CACHE`` picks the store: ``disk`` (default, SQLite at
+``~/.prompture/cache/web_cache.db`` — shared across processes and CLI runs),
+``memory`` (this process only) or ``off``. ``PROMPTURE_WEB_CACHE_PATH``
+moves the database. Every function also takes ``use_cache=False`` and
+``cache_ttl=<seconds>``. Errors and challenge pages are never cached, and a
+cached result says so: ``route["cached"] is True`` with ``cache_age_s``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import re
+import threading
+import time
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from ...infra.cache import CacheBackend, MemoryCacheBackend, SQLiteCacheBackend
+
+logger = logging.getLogger("prompture.tools.web.cache")
+
+CACHE_ENV = "PROMPTURE_WEB_CACHE"
+CACHE_PATH_ENV = "PROMPTURE_WEB_CACHE_PATH"
+DEFAULT_PATH = Path.home() / ".prompture" / "cache" / "web_cache.db"
+MAX_ENTRIES = 5000
+MEMORY_ENTRIES = 512
+# Pages above this size stay out of the disk cache (still served, just not stored).
+MAX_VALUE_BYTES = 2 * 1024 * 1024
+
+MINUTE = 60
+HOUR = 60 * MINUTE
+DAY = 24 * HOUR
+
+# Queries whose answers change by the hour.
+_VOLATILE_QUERY = re.compile(
+    r"\b(weather|forecast|temperature|rain|snow|today|tonight|tomorrow|yesterday|right now|currently|"
+    r"live|breaking|latest|news|headlines?|price|prices|stock|stocks|shares?|quote|exchange rate|crypto|"
+    r"bitcoin|score|scores|standings|results|traffic|outage|status|election|polls?|this (week|month))\b",
+    re.IGNORECASE,
+)
+_VOLATILE_HOSTS = (
+    "news.ycombinator.com",
+    "reddit.com",
+    "x.com",
+    "twitter.com",
+    "status.",
+    "weather.",
+    "finance.yahoo.com",
+)
+_STATIC_HOSTS = ("arxiv.org", "doi.org", "export.arxiv.org", "openreview.net", "aclanthology.org")
+_SHA_PATH = re.compile(r"/[0-9a-f]{40}(/|$)")
+
+_lock = threading.Lock()
+_store: tuple[tuple[str, str], CacheBackend | None] | None = None
+
+
+# ---------------------------------------------------------------------------
+# Lifetimes
+# ---------------------------------------------------------------------------
+
+
+def _host(url: str) -> str:
+    try:
+        return (urlsplit(url).hostname or "").lower()
+    except ValueError:
+        return ""
+
+
+def search_ttl(query: str, recency_days: int | None = None) -> int:
+    """Lifetime for a web search: short for volatile topics, hours otherwise."""
+    if recency_days is not None and recency_days <= 1:
+        return 10 * MINUTE
+    if _VOLATILE_QUERY.search(query or ""):
+        return 10 * MINUTE
+    if recency_days is not None and recency_days <= 7:
+        return HOUR
+    return 6 * HOUR
+
+
+def page_ttl(url: str) -> int:
+    """Lifetime for a fetched page, from how static its URL looks."""
+    host = _host(url)
+    path = urlsplit(url).path.lower() if url else ""
+    if any(host == h or host.endswith("." + h) or (h.endswith(".") and host.startswith(h)) for h in _VOLATILE_HOSTS):
+        return 10 * MINUTE
+    if any(host == h or host.endswith("." + h) for h in _STATIC_HOSTS) or path.endswith(".pdf"):
+        return 7 * DAY
+    if host in ("github.com", "raw.githubusercontent.com") and _SHA_PATH.search(path):
+        return 7 * DAY
+    if host.endswith("wikipedia.org"):
+        return DAY
+    return HOUR
+
+
+def read_ttl(url: str, reader: str, kind: str = "page") -> int:
+    """Lifetime for a :func:`read_url` result, per reader and content kind."""
+    reader = (reader or "").lower()
+    if reader == "youtube":
+        return 7 * DAY  # a published video's transcript doesn't change
+    if reader == "arxiv":
+        return 7 * DAY
+    if reader == "wikipedia":
+        return DAY
+    if reader == "podcasts":
+        return DAY
+    if reader == "feeds":
+        return 15 * MINUTE
+    if reader == "hackernews":
+        return 10 * MINUTE
+    if reader == "github":
+        if kind in ("issue", "pull_request", "pr", "discussion") or re.search(r"/(issues|pull|discussions)/", url):
+            return 10 * MINUTE
+        return page_ttl(url)
+    return page_ttl(url)
+
+
+PLATFORM_TTL = 30 * MINUTE
+
+
+def ttl_for(kind: str, **context: Any) -> int:
+    """Lifetime in seconds for an entry of *kind* (``search``, ``fetch``, ``read``, ``platform``)."""
+    if kind == "search":
+        return search_ttl(context.get("query", ""), context.get("recency_days"))
+    if kind == "fetch":
+        return page_ttl(context.get("url", ""))
+    if kind == "read":
+        return read_ttl(context.get("url", ""), context.get("reader", ""), context.get("result_kind", "page"))
+    if kind == "platform":
+        return PLATFORM_TTL
+    return HOUR
+
+
+# ---------------------------------------------------------------------------
+# Store
+# ---------------------------------------------------------------------------
+
+
+def _setting(name: str) -> str | None:
+    try:
+        from ...infra.credentials import get_config_value
+
+        value = get_config_value(name)
+    except Exception:
+        import os
+
+        value = os.environ.get(name)
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def cache_mode() -> str:
+    """``disk`` (default), ``memory`` or ``off``."""
+    mode = (_setting(CACHE_ENV) or "disk").lower()
+    if mode in ("0", "false", "no", "none", "disabled"):
+        return "off"
+    return mode if mode in ("disk", "memory", "off") else "disk"
+
+
+def cache_path() -> Path:
+    custom = _setting(CACHE_PATH_ENV)
+    return Path(custom).expanduser() if custom else DEFAULT_PATH
+
+
+def _backend() -> CacheBackend | None:
+    """The active store, rebuilt when the mode or path changes."""
+    global _store
+    signature = (cache_mode(), str(cache_path()))
+    with _lock:
+        if _store is not None and _store[0] == signature:
+            return _store[1]
+        mode, path = signature
+        backend: CacheBackend | None
+        if mode == "off":
+            backend = None
+        elif mode == "memory":
+            backend = MemoryCacheBackend(maxsize=MEMORY_ENTRIES)
+        else:
+            try:
+                backend = SQLiteCacheBackend(db_path=path, max_entries=MAX_ENTRIES)
+            except Exception as exc:  # read-only home, locked file, ...
+                logger.warning("web cache: disk store unavailable (%s); using memory", exc)
+                backend = MemoryCacheBackend(maxsize=MEMORY_ENTRIES)
+        _store = (signature, backend)
+        return backend
+
+
+def make_key(kind: str, *parts: Any) -> str:
+    """Stable key for *kind* and its arguments."""
+    raw = json.dumps([kind, *parts], sort_keys=True, default=str, ensure_ascii=False)
+    return f"web:{kind}:" + hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def get(key: str) -> tuple[Any, float] | None:
+    """Return ``(value, age_seconds)`` for a live entry, else ``None``."""
+    backend = _backend()
+    if backend is None:
+        return None
+    try:
+        entry = backend.get(key)
+    except Exception as exc:
+        logger.debug("web cache read failed: %s", exc)
+        return None
+    if not isinstance(entry, dict) or "value" not in entry:
+        return None
+    return entry["value"], max(0.0, time.time() - float(entry.get("stored_at", time.time())))
+
+
+def put(key: str, value: Any, ttl: float) -> None:
+    """Store a JSON-serializable *value* for *ttl* seconds (``<= 0`` skips)."""
+    backend = _backend()
+    if backend is None or ttl <= 0:
+        return
+    entry = {"stored_at": time.time(), "value": value}
+    if isinstance(backend, SQLiteCacheBackend):
+        try:
+            if len(json.dumps(entry, default=str)) > MAX_VALUE_BYTES:
+                return
+        except (TypeError, ValueError):
+            return
+    try:
+        backend.set(key, entry, ttl=int(ttl))
+    except Exception as exc:
+        logger.debug("web cache write failed: %s", exc)
+
+
+def mark_cached(route: dict[str, Any] | None, age: float) -> dict[str, Any]:
+    """Copy of *route* flagged as served from the cache."""
+    return {**(route or {}), "cached": True, "cache_age_s": round(age, 1)}
+
+
+def clear_web_cache() -> None:
+    """Drop every cached search, page, reader result and platform search."""
+    backend = _backend()
+    if backend is not None:
+        backend.clear()
+
+
+def cache_info() -> dict[str, Any]:
+    """Mode, location and entry count (for doctor / debugging).
+
+    Read-only: it never creates the cache database.
+    """
+    mode = cache_mode()
+    path = cache_path()
+    info: dict[str, Any] = {"mode": mode, "path": str(path) if mode == "disk" else None, "entries": None}
+    if mode == "disk":
+        if not path.exists():
+            info["entries"] = 0
+            return info
+        try:
+            import sqlite3
+
+            conn = sqlite3.connect(f"file:{path.as_posix()}?mode=ro", uri=True, timeout=2)
+            try:
+                info["entries"] = conn.execute("SELECT COUNT(*) FROM cache").fetchone()[0]
+            finally:
+                conn.close()
+        except Exception:
+            info["entries"] = None
+    elif mode == "memory":
+        with _lock:
+            backend = _store[1] if _store is not None and _store[0] == (mode, str(path)) else None
+        info["entries"] = len(backend._data) if isinstance(backend, MemoryCacheBackend) else 0
+    return info
+
+
+def _reset_for_tests() -> None:
+    global _store
+    with _lock:
+        _store = None