agent-discogs 0.1.0__tar.gz → 0.2.0__tar.gz

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-discogs
-Version: 0.1.0
+Version: 0.2.0
 Summary: Token-efficient Discogs CLI for AI agents
 Keywords: ai-agent,cli,discogs,discogs-api,music-database
 Author: Jean-Marc Fontaine
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
 Requires-Dist: click>=8.3.1
-Requires-Dist: discogs-sdk>=0.4.0
+Requires-Dist: discogs-sdk>=0.5.0
 Requires-Dist: pydantic>=2.12.5
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/jmfontaine/agent-discogs
@@ -173,7 +173,7 @@ Errors under `--json` are a JSON document on stdout with exit code 1:
 {"error":{"code":"not_found","message":"Master @m... not found.","hint":"Try: agent-discogs search \"<title>\"","status":404}}
 ```
 
-Codes: `not_found`, `seller_settings_required`, `auth_required`, `forbidden`, `rate_limited` (with `retry_after` seconds when provided), `api_error`, `connection_error`, `invalid_argument`, `unexpected`.
+Codes: `not_found`, `seller_settings_required`, `auth_required`, `forbidden`, `rate_limited` (with `retry_after` seconds when provided, and `limit`/`remaining` for the current minute when Discogs reports them), `cache_miss` (only under `--cached`), `api_error`, `connection_error`, `invalid_argument`, `unexpected`.
 
 ## Ref system
 
@@ -194,6 +194,55 @@ Smart resolution: `get versions @r352665` auto-resolves the release to its maste
 
 HTTP responses are cached automatically with a 1-hour TTL. The cache is stored at `~/.cache/agent-discogs/` (or `$XDG_CACHE_HOME/agent-discogs/`). Clear it with `agent-discogs cache clear`.
 
+Two global flags control it for one command. They precede the subcommand and are mutually exclusive (exit code 2 otherwise):
+
+```bash
+agent-discogs --cached price @r352665      # serve only from the cache; never touches the API
+agent-discogs --fresh get release @r352665 # bypass the cache; go to the API
+```
+
+`--cached` fails with a `cache_miss` error (exit code 1) on any request the cache cannot serve, before any network I/O. With several refs, hits print normally and each miss reports inline, exactly like other per-ref failures; under `--json` the miss item carries `error.code == "cache_miss"`. The check is exact: it uses the real cache key at the real moment, so a command that issues several requests fails at the first one that is not cached. There is no separate "is it cached?" query because the answer depends on the whole request sequence a command issues.
+
+`--fresh` fetches every request from the API and does **not** store the response, so a later run without `--fresh` can still be served the older cached entry until its 1-hour TTL expires.
+
+## Budget
+
+Discogs throttles by source IP: 60 requests per minute with a token, 25 without, as a moving 60-second window. After any command that talks to the API, stderr ends with one budget line:
+
+```
+api: 3 requests · 43/60 left this minute
+api: 0 requests · cached
+api: 4 requests · 6/60 left this minute ⚠ pause ~60s before uncached calls
+```
+
+The count is what this command spent; `43/60` is what Discogs reported after the last request. `⚠` appears when 10 or fewer requests remain: pause about a minute, or keep to refs that are already cached (`--cached` guarantees zero spend). Without a token the warning suggests setting `DISCOGS_TOKEN` instead. The line is on stderr and never inside `--json` output; commands that make no request (`status`, `skills`, `cache clear`) print nothing.
+
+What commands cost:
+
+| Command | Requests |
+|---|---|
+| `get <noun>`, `tracks`, `price` | 1 per ref (`price`: up to 3; `versions @r...`: 2) |
+| `search`, `get releases`, `get versions` (server-side pages) | 1 |
+| Client-side scans: `search --release-type official\|unofficial`, `get releases --role`, `get releases @l... --year` | up to 5 |
+| Anything repeated within 1 hour | 0 (cached) |
+
+The CLI reports; it never sleeps or throttles on your behalf. When Discogs answers 429, the error says how much of the minute is left (`Rate limited: 0/60 requests left this minute.`), and under `--json` the envelope carries `retry_after`, `limit`, and `remaining`.
+
+## Debugging
+
+`--debug` (or `AGENT_DISCOGS_DEBUG=1`) prints a trace panel to stderr after the budget line: one row per request with status and timing (`cache` for cache hits, `×N attempts` when the SDK retried), scan statistics for client-side filters, cache size, and output size with a rough token estimate. The SDK's own log lines (`[sdk] HTTP request ...`, `[sdk] Retrying ... waiting 30s`) stream to stderr in real time, which is the only way to see a rate-limit retry while it is happening. stdout is byte-identical with and without the flag.
+
+```
+api: 2 requests · 58/60 left this minute
+── debug ───────────────────────────────────────────────
+total     1310ms
+GET /artists/3857                               200   338ms
+GET /artists/3857/releases?page=1&per_page=15   200   947ms
+scan      1 API calls, 15 rows fetched, 5 kept, not capped
+cache     ~/.cache/agent-discogs  540.0 KB  ttl 1h
+output    494 chars, 9 lines, ≈123 tokens
+```
+
 ## Error handling
 
 The CLI maps API errors to recovery-oriented messages with suggested next steps:
@@ -201,7 +250,8 @@ The CLI maps API errors to recovery-oriented messages with suggested next steps:
 ```
 ✗ Release 999999999 not found. Try: agent-discogs search "<title>"
 ✗ Authentication failed. Check your DISCOGS_TOKEN.
-✗ Rate limit exceeded. Wait a moment and retry.
+✗ Rate limited: 0/60 requests left this minute. Retry in 30s.
+✗ Not cached: GET /marketplace/price_suggestions/352665 (only under --cached)
 ✗ Connection error. Check your network and retry.
 ```
 

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/README.md

@@ -148,7 +148,7 @@ Errors under `--json` are a JSON document on stdout with exit code 1:
 {"error":{"code":"not_found","message":"Master @m... not found.","hint":"Try: agent-discogs search \"<title>\"","status":404}}
 ```
 
-Codes: `not_found`, `seller_settings_required`, `auth_required`, `forbidden`, `rate_limited` (with `retry_after` seconds when provided), `api_error`, `connection_error`, `invalid_argument`, `unexpected`.
+Codes: `not_found`, `seller_settings_required`, `auth_required`, `forbidden`, `rate_limited` (with `retry_after` seconds when provided, and `limit`/`remaining` for the current minute when Discogs reports them), `cache_miss` (only under `--cached`), `api_error`, `connection_error`, `invalid_argument`, `unexpected`.
 
 ## Ref system
 
@@ -169,6 +169,55 @@ Smart resolution: `get versions @r352665` auto-resolves the release to its maste
 
 HTTP responses are cached automatically with a 1-hour TTL. The cache is stored at `~/.cache/agent-discogs/` (or `$XDG_CACHE_HOME/agent-discogs/`). Clear it with `agent-discogs cache clear`.
 
+Two global flags control it for one command. They precede the subcommand and are mutually exclusive (exit code 2 otherwise):
+
+```bash
+agent-discogs --cached price @r352665      # serve only from the cache; never touches the API
+agent-discogs --fresh get release @r352665 # bypass the cache; go to the API
+```
+
+`--cached` fails with a `cache_miss` error (exit code 1) on any request the cache cannot serve, before any network I/O. With several refs, hits print normally and each miss reports inline, exactly like other per-ref failures; under `--json` the miss item carries `error.code == "cache_miss"`. The check is exact: it uses the real cache key at the real moment, so a command that issues several requests fails at the first one that is not cached. There is no separate "is it cached?" query because the answer depends on the whole request sequence a command issues.
+
+`--fresh` fetches every request from the API and does **not** store the response, so a later run without `--fresh` can still be served the older cached entry until its 1-hour TTL expires.
+
+## Budget
+
+Discogs throttles by source IP: 60 requests per minute with a token, 25 without, as a moving 60-second window. After any command that talks to the API, stderr ends with one budget line:
+
+```
+api: 3 requests · 43/60 left this minute
+api: 0 requests · cached
+api: 4 requests · 6/60 left this minute ⚠ pause ~60s before uncached calls
+```
+
+The count is what this command spent; `43/60` is what Discogs reported after the last request. `⚠` appears when 10 or fewer requests remain: pause about a minute, or keep to refs that are already cached (`--cached` guarantees zero spend). Without a token the warning suggests setting `DISCOGS_TOKEN` instead. The line is on stderr and never inside `--json` output; commands that make no request (`status`, `skills`, `cache clear`) print nothing.
+
+What commands cost:
+
+| Command | Requests |
+|---|---|
+| `get <noun>`, `tracks`, `price` | 1 per ref (`price`: up to 3; `versions @r...`: 2) |
+| `search`, `get releases`, `get versions` (server-side pages) | 1 |
+| Client-side scans: `search --release-type official\|unofficial`, `get releases --role`, `get releases @l... --year` | up to 5 |
+| Anything repeated within 1 hour | 0 (cached) |
+
+The CLI reports; it never sleeps or throttles on your behalf. When Discogs answers 429, the error says how much of the minute is left (`Rate limited: 0/60 requests left this minute.`), and under `--json` the envelope carries `retry_after`, `limit`, and `remaining`.
+
+## Debugging
+
+`--debug` (or `AGENT_DISCOGS_DEBUG=1`) prints a trace panel to stderr after the budget line: one row per request with status and timing (`cache` for cache hits, `×N attempts` when the SDK retried), scan statistics for client-side filters, cache size, and output size with a rough token estimate. The SDK's own log lines (`[sdk] HTTP request ...`, `[sdk] Retrying ... waiting 30s`) stream to stderr in real time, which is the only way to see a rate-limit retry while it is happening. stdout is byte-identical with and without the flag.
+
+```
+api: 2 requests · 58/60 left this minute
+── debug ───────────────────────────────────────────────
+total     1310ms
+GET /artists/3857                               200   338ms
+GET /artists/3857/releases?page=1&per_page=15   200   947ms
+scan      1 API calls, 15 rows fetched, 5 kept, not capped
+cache     ~/.cache/agent-discogs  540.0 KB  ttl 1h
+output    494 chars, 9 lines, ≈123 tokens
+```
+
 ## Error handling
 
 The CLI maps API errors to recovery-oriented messages with suggested next steps:
@@ -176,7 +225,8 @@ The CLI maps API errors to recovery-oriented messages with suggested next steps:
 ```
 ✗ Release 999999999 not found. Try: agent-discogs search "<title>"
 ✗ Authentication failed. Check your DISCOGS_TOKEN.
-✗ Rate limit exceeded. Wait a moment and retry.
+✗ Rate limited: 0/60 requests left this minute. Retry in 30s.
+✗ Not cached: GET /marketplace/price_suggestions/352665 (only under --cached)
 ✗ Connection error. Check your network and retry.
 ```
 

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["uv-build>=0.12.13,<0.13"]
 
 [project]
 name = "agent-discogs"
-version = "0.1.0"
+version = "0.2.0"
 description = "Token-efficient Discogs CLI for AI agents"
 readme = "README.md"
 keywords = [
@@ -28,7 +28,7 @@ classifiers = [
 ]
 dependencies = [
     "click>=8.3.1",
-    "discogs-sdk>=0.4.0",
+    "discogs-sdk>=0.5.0",
     "pydantic>=2.12.5",
 ]
 
@@ -142,6 +142,7 @@ ignore-names = [
     "_patch_get",
     "_patch_search",
     "_reset_singleton",
+    "_scoped_client",
     "format_help",
     "get_skill",
     "skill_path",

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ requires = [ "uv-build>=0.12.13,<0.13" ]
 
 [project]
 name = "agent-discogs"
-version = "0.1.0"
+version = "0.2.0"
 description = "Token-efficient Discogs CLI for AI agents"
 readme = "README.md"
 keywords = [ "ai-agent", "cli", "discogs", "discogs-api", "music-database" ]
@@ -21,7 +21,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: 3.15",
 ]
-dependencies = [ "click>=8.3.1", "discogs-sdk>=0.4.0", "pydantic>=2.12.5" ]
+dependencies = [ "click>=8.3.1", "discogs-sdk>=0.5.0", "pydantic>=2.12.5" ]
 urls.Homepage = "https://github.com/jmfontaine/agent-discogs"
 urls.Issues = "https://github.com/jmfontaine/agent-discogs/issues"
 urls.Repository = "https://github.com/jmfontaine/agent-discogs"
@@ -125,6 +125,7 @@ ignore-names = [
   "_patch_get",
   "_patch_search",
   "_reset_singleton",
+  "_scoped_client",
   "format_help",
   "get_skill",        # click subcommands are registered by decorator, invisible to deadcode
   "skill_path",

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/src/agent_discogs/__init__.py

@@ -7,6 +7,7 @@ from typing import Any
 
 import click
 
+from agent_discogs import client, trace
 from agent_discogs.commands.cache import cache
 from agent_discogs.commands.get import get, price, tracks
 from agent_discogs.commands.search import search
@@ -44,6 +45,11 @@ Refs:
   @m3719 (master), @l647 (label). Use refs with get commands.
 
 Options:
+  --cached         Serve only from the cache; a miss fails (cache_miss), spends
+                   nothing. Precedes the command: agent-discogs --cached price @r...
+  --fresh          Bypass the cache for this command (response is not stored)
+  --debug          Request rows, timings, retries, scan stats, cache and output
+                   size on stderr, plus the SDK's own log lines
   --json           JSON output: a compact projection of the text view (search, get)
   --full           With --json: the raw SDK record instead of the projection
   --limit N        Results per page (search, get)
@@ -63,7 +69,14 @@ Options:
   --help           Show this message and exit
 
 Environment:
-  DISCOGS_TOKEN    Personal access token (higher rate limit, required for price data)
+  DISCOGS_TOKEN        Personal access token (60 req/min, required for price data)
+  AGENT_DISCOGS_DEBUG  Same as --debug
+
+Budget:
+  After any command that talks to the API, stderr ends with a budget line, e.g.
+  'api: 3 requests · 43/60 left this minute'. ⚠ means 10 or fewer requests
+  remain in the moving 60s window: pause ~60s or stick to cached refs. Cache
+  hits cost nothing ('api: 0 requests · cached'). Never inside --json output.
 
 Price data also needs seller settings filled out on the Discogs account the
 token belongs to (discogs.com/settings/seller). Without them the API answers
@@ -130,9 +143,25 @@ class AliasGroup(click.Group):
 
 @click.group(cls=AliasGroup, invoke_without_command=True)
 @click.version_option(package_name="agent-discogs", prog_name="agent-discogs")
+@click.option(
+    "--debug",
+    is_flag=True,
+    envvar="AGENT_DISCOGS_DEBUG",
+    help="Print request trace and timings to stderr.",
+)
+@click.option("--cached", is_flag=True, help="Serve only from cache; fail on a miss.")
+@click.option("--fresh", is_flag=True, help="Bypass the cache for this command.")
 @click.pass_context
-def cli(ctx: click.Context) -> None:
+def cli(ctx: click.Context, debug: bool, cached: bool, fresh: bool) -> None:
     """Token-efficient Discogs CLI for AI agents."""
+    if cached and fresh:
+        msg = "--cached and --fresh are mutually exclusive."
+        raise click.UsageError(msg)
+    trace.begin(ctx, debug=debug)
+    if cached:
+        ctx.with_resource(client.get_client().cache_only())
+    elif fresh:
+        ctx.with_resource(client.get_client().no_cache())
     if ctx.invoked_subcommand is None:
         click.echo(ctx.get_help())
 

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/src/agent_discogs/client.py

@@ -7,6 +7,8 @@ from pathlib import Path
 
 from discogs_sdk import Discogs
 
+from agent_discogs import trace
+
 _client: Discogs | None = None
 
 CACHE_DIR = (
@@ -21,7 +23,13 @@ def get_client() -> Discogs:
         return _client
 
     token = os.environ.get("DISCOGS_TOKEN")
-    _client = Discogs(token=token, cache=True, cache_dir=CACHE_DIR)
+    _client = Discogs(
+        token=token,
+        cache=True,
+        cache_dir=CACHE_DIR,
+        cache_ttl=trace.CACHE_TTL,
+        on_request=trace.record,
+    )
     return _client
 
 

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/src/agent_discogs/errors.py

@@ -6,6 +6,9 @@ import json
 import sys
 from dataclasses import asdict, dataclass
 from typing import Any, NoReturn
+from urllib.parse import urlsplit
+
+from agent_discogs import trace
 
 
 @dataclass(frozen=True)
@@ -18,6 +21,8 @@ class ErrorInfo:
     hint: str | None = None
     retry_after: int | None = None
     status: int | None = None
+    limit: int | None = None
+    remaining: int | None = None
 
 
 def _api_message(exc: Exception) -> str:
@@ -40,6 +45,7 @@ def classify(exc: Exception, context: str | None = None) -> ErrorInfo:
     failed, e.g. "Release @r847868", and is used in not-found messages."""
     from discogs_sdk import (
         AuthenticationError,
+        CacheMissError,
         DiscogsAPIError,
         DiscogsConnectionError,
         ForbiddenError,
@@ -91,12 +97,20 @@ def classify(exc: Exception, context: str | None = None) -> ErrorInfo:
         wait = (
             f"Retry in {retry_after}s." if retry_after else "Wait a moment and retry."
         )
+        rl = exc.ratelimit
+        message = (
+            "Rate limit exceeded."
+            if rl is None
+            else f"Rate limited: {rl.remaining}/{rl.limit} requests left this minute."
+        )
         return ErrorInfo(
             "rate_limited",
-            "Rate limit exceeded.",
+            message,
             f"{wait} 60 req/min with DISCOGS_TOKEN, 25 without.",
             retry_after=retry_after,
             status=429,
+            limit=None if rl is None else rl.limit,
+            remaining=None if rl is None else rl.remaining,
         )
 
     if isinstance(exc, DiscogsAPIError):
@@ -109,6 +123,18 @@ def classify(exc: Exception, context: str | None = None) -> ErrorInfo:
             "connection_error", "Connection error.", "Check your network and retry."
         )
 
+    if isinstance(exc, CacheMissError):
+        # The SDK emits no request event for a miss, so the footer learns
+        # about it here: every miss an agent sees passes through classify().
+        trace.note_cache_miss()
+        split = urlsplit(exc.url)
+        where = split.path + (f"?{split.query}" if split.query else "")
+        return ErrorInfo(
+            "cache_miss",
+            f"Not cached: {exc.method} {where}",
+            "Rerun without --cached to fetch it from the API.",
+        )
+
     if isinstance(exc, ValueError):
         return ErrorInfo("invalid_argument", str(exc))
 

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/src/agent_discogs/pagination.py

@@ -10,6 +10,8 @@ from typing import Any
 from discogs_sdk import Discogs
 from pydantic import BaseModel
 
+from agent_discogs import trace
+
 MAX_API_CALLS = 5
 DEFAULT_LIMIT = 5
 
@@ -152,11 +154,14 @@ def fetch_filtered_page(
     collected: list[Any] = []
     next_cursor: str | None = None
     capped = False
+    api_calls = rows = 0
     result = PageResult(items=[], page=page, total_items=0, total_pages=1)
 
     for _ in range(MAX_API_CALLS):
         fetch_params = {**params, "page": api_page, "per_page": api_per_page}
         result = fetch_page(client, path, fetch_params, model_cls, items_key)
+        api_calls += 1
+        rows += len(result.items)
 
         for idx in range(offset, len(result.items)):
             item = result.items[idx]
@@ -179,6 +184,7 @@ def fetch_filtered_page(
         capped = True
         next_cursor = f"{page + 1}:{api_page}.0"
 
+    trace.note_scan(trace.ScanNote(api_calls, rows, len(collected), capped))
     return PageResult(
         items=collected,
         page=page,

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/src/agent_discogs/skills/core/SKILL.md

@@ -94,7 +94,7 @@ agent-discogs get release @r847868 --json -v          # adds notes, credits, and
 agent-discogs get release @r847868 --json --full      # raw Discogs record (images, URLs, ~20x larger); only when the projection lacks a field you need
 ```
 
-With `--json`, errors are a JSON document on stdout and exit code 1: `{"error":{"code":"not_found","message":"Master @m... not found.","hint":"Try: agent-discogs search \"<title>\"","status":404}}`. Branch on `error.code`: `not_found`, `seller_settings_required`, `auth_required`, `forbidden`, `rate_limited` (with `retry_after` seconds when Discogs sends it), `api_error`, `connection_error`, `invalid_argument`, `unexpected`.
+With `--json`, errors are a JSON document on stdout and exit code 1: `{"error":{"code":"not_found","message":"Master @m... not found.","hint":"Try: agent-discogs search \"<title>\"","status":404}}`. Branch on `error.code`: `not_found`, `seller_settings_required`, `auth_required`, `forbidden`, `rate_limited` (with `retry_after` seconds when Discogs sends it, plus `limit`/`remaining` for the current minute), `cache_miss` (only under `--cached`), `api_error`, `connection_error`, `invalid_argument`, `unexpected`.
 
 ## Anti-Patterns
 
@@ -104,6 +104,7 @@ With `--json`, errors are a JSON document on stdout and exit code 1: `{"error":{
 - **Don't compute page numbers.** Paste the `Next page:` / `Continue scan:` command printed under a list. Filtered lists (the default search, `releases --role`, `releases @l... --year`) continue with an `--after` cursor; `--page` is rejected there and the error says what to use.
 - **Don't guess IDs.** Always search first to find the right entity.
 - **Don't use `get versions` on a release ID.** Release rows already show `→ @m...`; use that master ref (smart resolution costs an extra API call).
+- **Don't use `--fresh` by default.** Catalogue data an hour old is fine; reserve `--fresh` for `price` when you need current market numbers.
 
 ## Error Recovery
 
@@ -111,7 +112,8 @@ With `--json`, errors are a JSON document on stdout and exit code 1: `{"error":{
 - **Auth required** — price suggestions and search require `DISCOGS_TOKEN`. Run `agent-discogs status` to check.
 - **"Price data requires seller settings"** — not a bad ref. The release exists, but Discogs only serves price suggestions to accounts with seller settings filled out. Nothing to retry: use `get release @r...` for the `num_for_sale`/`lowest_price` summary instead.
 - **Invalid ref** — refs are Discogs IDs and never expire; there is no session. Check the prefix matches the noun (`@r` release, `@m` master, `@a` artist, `@l` label). A bare `@123` is invalid: either add the type letter or pass the raw number `123`.
-- **Rate limited** — wait briefly and retry. Authenticated requests get 60/min; unauthenticated get 25/min.
+- **Rate limited** — the error says what is left (`Rate limited: 0/60 requests left this minute.`, `remaining`/`limit` in JSON). Pause ~60s, or continue with `--cached` on refs you already fetched. Authenticated requests get 60/min; unauthenticated get 25/min.
+- **Unexpected cost or a stall?** Re-run once with `--debug` to see each request, retries and cache hits on stderr. Do not leave it on.
 - **"Continue scan:" instead of "Next page:"** — the filter was sparse and the scan stopped at 5 API calls before filling the page. The next window may also be short or empty; keep pasting the printed command until it disappears (no footer = nothing left to scan). Counts shown as `≤N` are the unfiltered upper bound.
 
 ## Refs
@@ -130,6 +132,35 @@ Refs encode entity type and Discogs ID: `@a3857` (artist), `@r847868` (release),
 
 Prefer the most specific command: `tracks @r...` over `get release @r...` when you only need the tracklist, and `price @r...` over `get release @r...` when you only need pricing. This reduces output tokens and avoids unnecessary data.
 
+## Budget
+
+Discogs allows 60 requests per minute with a token (25 without), as a moving 60s window shared by every process on this machine. After any command that talks to the API, stderr ends with one line:
+
+```
+api: 3 requests · 43/60 left this minute
+api: 0 requests · cached
+api: 4 requests · 6/60 left this minute ⚠ pause ~60s before uncached calls
+```
+
+The count is what this command spent; `43/60` is what Discogs reported after its last request. It is never part of `--json` output. Commands that make no request print nothing.
+
+| Command | Requests |
+|---|---|
+| `get <noun>`, `tracks` | 1 per ref |
+| `price` | 3 per ref; `get versions @r...` 2 (resolve, then list) |
+| `search`, `get releases`, `get versions` (server-side pages) | 1 |
+| Client-side scans: `search` with `--release-type official\|unofficial` (the default), `get releases --role`, `get releases @l... --year` | up to 5 |
+| Anything repeated within 1 hour | 0 (cached) |
+
+At `⚠` (10 or fewer left): pause ~60s before uncached calls, or spend nothing with `--cached`. Unauthenticated runs get 25/min; setting `DISCOGS_TOKEN` is the fix there.
+
+**Try everything with `--cached` first, then spend only on the misses.** `agent-discogs --cached get release @r847868 @r...` serves what the cache has and reports each miss inline as `✗ Not cached: GET ...` (`error.code == "cache_miss"` under `--json`) without touching the API. It matters when several agents share one machine (one cache, one IP budget), and after a `⚠`. The flags precede the command:
+
+```bash
+agent-discogs --cached price @r847868     # zero spend; misses fail with cache_miss
+agent-discogs --fresh price @r847868      # bypass the cache; the response is not stored
+```
+
 ## Reference Docs
 
 | Document | Content |

{agent_discogs-0.1.0 → agent_discogs-0.2.0}/src/agent_discogs/skills/core/references/commands.md

@@ -2,11 +2,18 @@
 
 ## Global Flags
 
+Global flags precede the command (`agent-discogs --cached price @r847868`).
+
 | Flag | Description |
 |------|-------------|
+| `--cached` | Serve only from the response cache. A request the cache cannot serve fails with error code `cache_miss` (exit 1, per ref when several are given) before any network I/O. Never spends a request. |
+| `--fresh` | Bypass the cache for this command. Every request goes to the API; the response is not stored, so a later run without `--fresh` may still see the older cached entry until its 1h TTL expires. Mutually exclusive with `--cached` (exit 2). |
+| `--debug` | Trace panel on stderr after the budget line: one row per request (path, status, timing or `cache`, `×N attempts` on retry), scan statistics, cache size, output size with a token estimate, plus the SDK's own log lines in real time. `AGENT_DISCOGS_DEBUG=1` does the same. stdout is unchanged. |
 | `--help` | Show help |
 | `--version` | Show version |
 
+After any command that talks to the API, stderr ends with a budget line such as `api: 3 requests · 43/60 left this minute` (`⚠` when 10 or fewer remain). See the Budget section of the core skill.
+
 
 ## search
 

agent_discogs-0.2.0/src/agent_discogs/trace.py

@@ -0,0 +1,223 @@
+"""Per-invocation request trace: the budget footer and the --debug panel.
+
+One process-wide collector, reset by `begin()` at the top of every invocation
+and drained by `finish()` when the click context closes. `record()` is the
+SDK's `on_request` hook; `note_scan()` is called by client-side scans.
+Everything printed here goes to stderr so stdout stays a pure data channel.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit
+
+if TYPE_CHECKING:
+    import click
+    from discogs_sdk import RequestEvent
+
+# Remaining requests at which the footer warns. One client-side scan costs up
+# to MAX_API_CALLS (5) requests; two back-to-back scans can spend 10.
+LOW_BUDGET = 10
+# Passed to Discogs(cache_ttl=...) and shown by --debug.
+CACHE_TTL = 3600.0
+
+_SDK_LOGGER = "discogs_sdk"
+
+
+@dataclass
+class ScanNote:
+    """What one `fetch_filtered_page` call spent and kept."""
+
+    api_calls: int
+    rows: int
+    kept: int
+    capped: bool
+
+
+class _CountingWriter:
+    """Proxy around a text stream that counts what was written to it."""
+
+    def __init__(self, target: Any) -> None:
+        self.target: Any = target
+        self.chars: int = 0
+        self.lines: int = 0
+
+    def write(self, s: str) -> int:
+        n = self.target.write(s)
+        self.chars += len(s)
+        self.lines += s.count("\n")
+        return n
+
+    def flush(self) -> None:
+        self.target.flush()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.target, name)
+
+
+@dataclass
+class Trace:
+    events: list[RequestEvent] = field(default_factory=list)
+    scans: list[ScanNote] = field(default_factory=list)
+    started: float = 0.0
+    debug: bool = False
+    cache_misses: int = 0
+    stdout: _CountingWriter | None = None
+    log_handler: logging.Handler | None = None
+    log_level: int = logging.NOTSET
+
+
+_trace = Trace()
+
+
+def begin(ctx: click.Context, *, debug: bool) -> None:
+    """Reset the trace for this invocation and arrange for `finish()` to run
+    when `ctx` closes, i.e. after the subcommand, success or failure."""
+    global _trace  # noqa: PLW0603  # one invocation per process; reset for tests
+    _trace = Trace(started=time.perf_counter(), debug=debug)
+    if debug:
+        _trace.stdout = _CountingWriter(sys.stdout)
+        sys.stdout = _trace.stdout  # type: ignore[assignment]
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setLevel(logging.DEBUG)
+        handler.setFormatter(logging.Formatter("[sdk] %(message)s"))
+        logger = logging.getLogger(_SDK_LOGGER)
+        _trace.log_level = logger.level
+        logger.setLevel(logging.DEBUG)
+        logger.addHandler(handler)
+        _trace.log_handler = handler
+    ctx.call_on_close(finish)
+
+
+def record(event: RequestEvent) -> None:
+    """SDK `on_request` hook: one event per request, cache hit or network."""
+    _trace.events.append(event)
+
+
+def note_scan(note: ScanNote) -> None:
+    """Record the cost of one client-side filtered scan."""
+    _trace.scans.append(note)
+
+
+def note_cache_miss() -> None:
+    """Record a `--cached` lookup the cache could not serve. The SDK emits no
+    event for it, so this is the only trace such a request leaves."""
+    _trace.cache_misses += 1
+
+
+def render_footer(
+    events: Sequence[RequestEvent], *, authenticated: bool, cache_misses: int = 0
+) -> str | None:
+    """The budget line, or None when nothing was requested.
+
+    Counts network requests only; the budget comes from the last network
+    response that reported rate-limit headers, so cache hits never move it.
+    A `--cached` miss counts as a request that cost nothing.
+    """
+    if not events and not cache_misses:
+        return None
+    network = [e for e in events if e.source == "network"]
+    n = len(network)
+    if n == 0:
+        return "api: 0 requests · cached"
+    line = f"api: {n} request" + ("" if n == 1 else "s")
+    rl = next((e.ratelimit for e in reversed(network) if e.ratelimit), None)
+    if rl is None:
+        return line
+    line += f" · {rl.remaining}/{rl.limit} left this minute"
+    if rl.remaining <= LOW_BUDGET:
+        line += (
+            " ⚠ pause ~60s before uncached calls"
+            if authenticated
+            else " ⚠ set DISCOGS_TOKEN for 60/min, or pause ~60s"
+        )
+    return line
+
+
+def _request_path(url: str) -> str:
+    split = urlsplit(url)
+    return split.path + (f"?{split.query}" if split.query else "")
+
+
+_KB = 1024
+
+
+def _cache_size(cache_dir: Path) -> str:
+    # SQLite may leave -wal/-shm beside the database file.
+    size = sum(p.stat().st_size for p in cache_dir.glob("cache.db*"))
+    if size < _KB:
+        return f"{size} B"
+    if size < _KB * _KB:
+        return f"{size / _KB:.1f} KB"
+    return f"{size / (_KB * _KB):.1f} MB"
+
+
+def _tilde(path: Path) -> str:
+    home = Path.home()
+    try:
+        return f"~/{path.relative_to(home)}"
+    except ValueError:
+        return str(path)
+
+
+def render_panel(trace: Trace, *, cache_dir: Path, elapsed_ms: float) -> str:
+    """The `--debug` panel: one row per request, then scan, cache and output
+    statistics. Takes plain values; never touches the client or the network."""
+    lines = ["── debug ".ljust(56, "─"), f"total     {elapsed_ms:.0f}ms"]
+    paths = [_request_path(e.url) for e in trace.events]
+    width = max((len(p) for p in paths), default=0)
+    for event, path in zip(trace.events, paths, strict=True):
+        if event.source == "cache":
+            cost = "cache"
+        else:
+            cost = f"{event.elapsed_ms:.0f}ms"
+            if event.attempts > 1:
+                cost += f"  \u00d7{event.attempts} attempts"  # multiplication sign
+        lines.append(f"{event.method} {path:<{width}}   {event.status_code}   {cost}")
+    for scan in trace.scans:
+        capped = (
+            f"capped at {scan.api_calls} API calls" if scan.capped else "not capped"
+        )
+        lines.append(
+            f"scan      {scan.api_calls} API calls, {scan.rows} rows fetched, "
+            f"{scan.kept} kept, {capped}"
+        )
+    lines.append(
+        f"cache     {_tilde(cache_dir)}  {_cache_size(cache_dir)}  "
+        f"ttl {CACHE_TTL / 3600:g}h"
+    )
+    if trace.stdout is not None:
+        out = trace.stdout
+        lines.append(
+            f"output    {out.chars} chars, {out.lines} lines, ≈{out.chars // 4} tokens"
+        )
+    return "\n".join(lines)
+
+
+def finish() -> None:
+    """Print the footer (and the panel under --debug) to stderr and undo
+    whatever `begin()` installed."""
+    from agent_discogs.client import CACHE_DIR, has_token
+
+    if _trace.stdout is not None:
+        sys.stdout = _trace.stdout.target
+    footer = render_footer(
+        _trace.events, authenticated=has_token(), cache_misses=_trace.cache_misses
+    )
+    if footer:
+        print(footer, file=sys.stderr)
+    if _trace.debug:
+        elapsed_ms = (time.perf_counter() - _trace.started) * 1000
+        panel = render_panel(_trace, cache_dir=CACHE_DIR, elapsed_ms=elapsed_ms)
+        print(panel, file=sys.stderr)
+    if _trace.log_handler is not None:
+        logger = logging.getLogger(_SDK_LOGGER)
+        logger.removeHandler(_trace.log_handler)
+        logger.setLevel(_trace.log_level)
+        _trace.log_handler = None