Skip to content

docs(cookbook): revamp semantic-caching against playbook#663

Open
SuhaniNagpal7 wants to merge 1 commit into
devfrom
docs/semantic-caching-revamp
Open

docs(cookbook): revamp semantic-caching against playbook#663
SuhaniNagpal7 wants to merge 1 commit into
devfrom
docs/semantic-caching-revamp

Conversation

@SuhaniNagpal7
Copy link
Copy Markdown
Contributor

What changed

Area Before After
Frontmatter title + description only Full kebab-case schema: slug, date, author, products, frameworks, difficulty, time-to-complete, tags, og-image, canonical, last-tested-date, structured last-tested-with, code-repo-url, page-type
What you'll build Missing 5-bullet artifact list before Prerequisites
Why this matters Generic abstract framing Reader-facing diagnosis: "your support bot's bill grows with rephrasings, not new questions"; reader can verify the symptom in their own logs. Names the standard tools that miss it (HTTP, Redis, prompt-hash), the FAGI fix (L1 exact + L2 semantic at gateway), and the proof metric (x-agentcc-cache header values)
Install cell pip install openai agentcc (unused) pip install openai only
Em dashes 12 occurrences 0
Troubleshooting 3-column table 4 columns with Verify
Next steps 3 reference cards 4-item technical ladder (force-refresh CI hook, per-env namespaces, threshold tuning, fallback routing) + 1 reference link
Step 4 closer No screenshot Real Gateway -> Providers -> Cache panel showing 80% hit rate, 30 requests, 24 hits, $0.0089 saved (real UI, mock numbers matching the cookbook's example math)

Why this is shaped the way it is

  • The reader-facing "your bill grows with rephrasings" lead is meant to make them check their own request logs before committing to the recipe. Standard caches don't catch paraphrases; this is the failure mode the cookbook fixes.
  • The 4-item Next steps ladder is engineering moves, not commercial CTAs: force-refresh in CI, namespaces for per-env isolation, threshold tuning against real logs, routing policy on top of the cache.
  • The Step 4 screenshot is the real Cache panel (localhost:8000 dashboard layout), not a from-scratch mockup. Numbers are overlaid so they match the cookbook's worked example (6 unique * 5 = 30 calls; 6 misses + 24 hits = 80% hit rate; $0.0111 baseline - $0.00222 actual = ~$0.0089 saved).

Depends on

  • #660 for the <Mermaid> component is not required here. This cookbook has no <Mermaid> usage. Can merge independently.

Test plan

  • pnpm dev and visit /docs/cookbook/command-center/semantic-caching -- confirm the new Step 4 screenshot loads from S3 and all 5 step blocks render.
  • Em-dash check: grep -nE "(-|-)" src/pages/docs/cookbook/command-center/semantic-caching.mdx returns no hits.
  • pnpm astro build passes.

Out of scope

  • The notebook companion (cookbooks/command-center/semantic-caching.ipynb) has an equivalent revamp pending in the future-agi/cookbooks repo. Tracked separately; not part of this PR.

What changed

- Frontmatter: full kebab-case schema (slug, author, products,
  frameworks, difficulty, tags, og-image, canonical, last-tested-date,
  structured last-tested-with, code-repo-url, page-type).
- Added "What you'll build" section with 5 concrete artifact bullets
  so the reader sees the deliverables before they invest 10 minutes.
- Rewrote "Why this matters" as a reader-facing diagnosis: "your
  support bot's bill grows with rephrasings, not new questions,"
  with a "pull a day of your own request logs" prompt that lets the
  reader confirm the symptom in their own setup. Covers the four
  playbook elements (incident, why standard caches miss, FAGI fix,
  proof metric on the x-agentcc-cache header).
- Removed the unused `pip install agentcc` (was never imported).
- Strip em dashes (12 occurrences) per docs style.
- Troubleshooting table gained the "Verify" column.
- Replaced "Explore further" reference cards with a 4-item technical
  next-steps ladder (force-refresh in CI, namespaces, threshold
  tuning, routing policy) plus one reference link.
- Step 4 closes with a real screenshot of the Gateway -> Providers ->
  Cache panel showing 80% hit rate, 30 requests, 24 hits, $0.0089
  saved. Real product UI with mock numbers matching the cookbook's
  example math (6 unique x 5 = 30; 6 misses + 24 hits = 80%).

Out of scope

- No notebook changes in this PR. cookbooks/command-center/
  semantic-caching.ipynb has equivalent revamp ready but lives in a
  different repo; will follow up there.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant