diff --git a/CLAUDE.md b/CLAUDE.md index 1a677ea1..514859cd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,7 @@ tutorials/ ├── langchain-deep-agent-py/ # Same pattern on the Deep Agents harness; paid tool in a subagent ├── langchain-langsmith-deployment-py/ # Route-level ASGI PaymentMiddleware (Python) ├── langchain-chat-ui-nvm/ # Next.js browser chat UI with the x402 card-delegation popup -├── catalog/ # Video showcase demos (song-from-the-headlines, diligence-in-a-box) +├── catalog/ # Discovery, paid outcome tutorials, redacted samples, and showcase media └── mcp-examples/ # Model Context Protocol (MCP) examples ├── weather-mcp/ # TypeScript MCP server (has CLAUDE.md) └── weather-mcp-py/ # Python MCP server diff --git a/README.md b/README.md index ce407b48..a15afe74 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,10 @@ A collection of practical tutorials demonstrating how to integrate **Nevermined 💻 **Frontend repository**: [https://github.com/nevermined-io/demo-ui-monorepo/](https://github.com/nevermined-io/demo-ui-monorepo/) +## Catalog outcome tutorials + +The [tutorials Showcase](https://tutorials.nevermined.app/) presents the Catalog discovery and paid-run recaps. The source tutorials and redacted representative results are in [catalog/](catalog/README.md), including the [SEC earnings evidence pack](catalog/sec-earnings-evidence-pack/README.md) and [competitive product teardown](catalog/competitive-product-teardown/README.md). Run a paid tutorial locally with your own key and a capped delegation; raw Router envelopes and payment records stay in ignored `out/` folders. + ## What is Nevermined Payments? Nevermined Payments is a platform that enables developers to monetize AI agents and services through blockchain-based credit systems with Stripe checkout integration. It provides: @@ -206,4 +210,4 @@ 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. -``` \ No newline at end of file +``` diff --git a/catalog/competitive-product-teardown/BUILD_LOG.md b/catalog/competitive-product-teardown/BUILD_LOG.md index f2bdd197..6167e1f9 100644 --- a/catalog/competitive-product-teardown/BUILD_LOG.md +++ b/catalog/competitive-product-teardown/BUILD_LOG.md @@ -16,7 +16,7 @@ A fresh 25¢ / 10-minute delegation repeated all three steps with the shorter pr The runner generated [redacted Markdown](sample/teardown.md) and [JSON](sample/teardown.json) from the paid responses. Both name the public Firefox source, cite five Brave search results, include bounded excerpts and a review action, mark model text as a hypothesis, and distinguish the $0.069 charge from the 8¢ cap consumption. The builder stripped HTML tags/entities from Brave snippets before writing these representative files. The sample contains no buyer key, email address, payment ID, or raw HTML tags; all six cited HTTPS URLs returned unauthenticated HTTP 200 on 2026-09-15. A later read-only Router audit found all three buyer-fee statuses `Settled`; the sample retains the immediate `Submitted` state to show what the runner saw before reconciliation. Private raw Router responses remain ignored in `out/` and are never part of the sample. -The sample folder and code are prepared locally; their GitHub URLs must be checked after publication before the Catalog outcome links are released. Prices, ranking, page copy, model output, buyer fees, and timing can change on another run. +The redacted sample folder and code were published on the tutorials repository's `main` branch in PR #77; their public GitHub URLs returned unauthenticated HTTP 200 after merge. Prices, ranking, page copy, model output, buyer fees, and timing can change on another run. ## 2026-09-15 local follow-up and fee reconciliation diff --git a/catalog/competitive-product-teardown/FRICTION.md b/catalog/competitive-product-teardown/FRICTION.md index 1f94bcc5..45caffb3 100644 --- a/catalog/competitive-product-teardown/FRICTION.md +++ b/catalog/competitive-product-teardown/FRICTION.md @@ -1,6 +1,6 @@ # DevEx friction log -Preparation date: 2026-09-15. Separate capped paid **service smokes** confirmed the wrappers. The first three-call run stopped without an artifact after empty DeepSeek content; a fresh capped repeat produced a redacted sourced teardown. Publication and larger Catalog/Router changes remain pending. +Preparation date: 2026-09-15. Separate capped paid **service smokes** confirmed the wrappers. The first three-call run stopped without an artifact after empty DeepSeek content; a fresh capped repeat produced a redacted sourced teardown. The redacted sample is published; larger Catalog/Router changes remain pending. | Step | Expected | Observed / reproduction | Impact | Proposed fix and acceptance check | | --- | --- | --- | --- | --- | @@ -10,4 +10,4 @@ Preparation date: 2026-09-15. Separate capped paid **service smokes** confirmed | Reconcile delivery and receipts | A paid result has a body, settled merchant payment, and understandable buyer-fee status | Bounded `/router/route` smokes returned HTTP 201, `paid:true`, delivered bodies, and Settled merchant payments. Brave was $0.035, Serper $0.020; Serper had `feeCents=1` and immediate `feeStatus=Submitted`. The delegation's spent counter rounded the $0.065 combined charge to 7 cents. DeepSeek's tiny smoke was $0.004 merchant with zero fee cents and immediate Submitted fee status. | Treating Submitted as merchant failure incorrectly rejects useful paid output; treating it as terminal incorrectly claims buyer-fee settlement. | Show merchant and buyer-fee states separately, and expose rounded delegation spend. Acceptance: full teardown reports delivered body, merchant Settled, submitted/terminal buyer fee, exact recorded cents, and remaining cap after each call. | | Produce a model-supported teardown | DeepSeek chat returns final model text after a paid response so the builder can assemble the report | First full run under a 25-cent cap settled Brave $0.035, Serper $0.020 plus a 1-cent buyer fee, and DeepSeek $0.004. The prior runner sent a longer evidence prompt with `max_tokens=250`; DeepSeek returned no usable `choices[0].message.content`, and the runner exited without a real artifact. | Three purchases succeeded but no deliverable resulted. A blind retry would be a fourth paid call and could obscure the original failure. | Shorter/redacted prompt, `max_tokens=1024`, private envelope and first-result timestamp are in the runner. A fresh capped repeat settled all three calls and produced redacted Markdown/JSON for $0.069, with first result in 14.44s; resolved for this sample. | -The wrapper-schema, quote/max-price, and buyer-fee-state gaps remain larger cross-team work. Internal nvm-monorepo #3508 records proposed acceptance checks and Router follow-up #3326. The sample files are local until publication; no stable GitHub artifact URL is claimed yet. +The wrapper-schema, quote/max-price, and buyer-fee-state gaps remain larger cross-team work. Internal nvm-monorepo #3508 records proposed acceptance checks and Router follow-up #3326. The redacted sample is published on the tutorials repository's `main` branch; raw paid responses and receipts remain private in ignored `out/`. diff --git a/catalog/competitive-product-teardown/README.md b/catalog/competitive-product-teardown/README.md index 02fecf5d..038cf4da 100644 --- a/catalog/competitive-product-teardown/README.md +++ b/catalog/competitive-product-teardown/README.md @@ -2,7 +2,7 @@ This one-off sample helps a product-marketing or strategy builder compare a public product page with rival search evidence and write a reviewable positioning hypothesis. It accepts a safe public HTTPS company URL and a rival product query. It produces redacted, sourced Markdown and JSON. It does **not** monitor pages over time, score leads, or make investment claims. -**Status: a bounded three-service Live repeat completed on 2026-09-15; publication is pending.** Separate small paid probes confirmed all three payable wrappers. The first complete-chain attempt settled all three merchants but DeepSeek returned no final text at a 250-token limit, so no artifact was counted. A new 25¢ capped run with a shorter prompt and 1024-token limit delivered the [redacted Markdown teardown](sample/teardown.md) and [JSON teardown](sample/teardown.json). It recorded **$0.069** in merchant-plus-buyer-fee charges, consumed **8¢** of cap, and delivered its first result in **14.44 seconds**. The immediate buyer-fee states were `Submitted`; a later Router audit found all three `Settled`. [`wrapper-contract.json`](wrapper-contract.json), [BUILD_LOG.md](BUILD_LOG.md), and [FRICTION.md](FRICTION.md) record the path from probe to repeat. The sample files are local until this folder is published. +**Status: a bounded three-service Live repeat completed on 2026-09-15; the redacted sample is published.** Separate small paid probes confirmed all three payable wrappers. The first complete-chain attempt settled all three merchants but DeepSeek returned no final text at a 250-token limit, so no artifact was counted. A new 25¢ capped run with a shorter prompt and 1024-token limit delivered the [redacted Markdown teardown](sample/teardown.md) and [JSON teardown](sample/teardown.json). It recorded **$0.069** in merchant-plus-buyer-fee charges, consumed **8¢** of cap, and delivered its first result in **14.44 seconds**. The immediate buyer-fee states were `Submitted`; a later Router audit found all three `Settled`. [`wrapper-contract.json`](wrapper-contract.json), [BUILD_LOG.md](BUILD_LOG.md), and [FRICTION.md](FRICTION.md) record the path from probe to repeat. Raw receipts and Router envelopes remain private. A later local full run delivered its first result in **13.48 seconds** and again recorded **$0.069**. Its Brave buyer-fee status was `Submitted` at receipt time; a read-only ledger reconciliation found all three buyer-fee records **Settled**. The new generated teardown stays in ignored `out/`; the linked sample is from the earlier run. @@ -53,4 +53,4 @@ The runner saves each raw Router envelope and any HTTP error body in private `ou The `.app` production-live and `.dev` staging-live APIs are separate account backends. A key/wallet from one cannot be used on the other. The script accepts only those two exact API origins. -See [FRICTION.md](FRICTION.md) for the still-missing public payable schemas, dynamic AI price, quote handling, and the resolved empty model-content failure. The representative sample files have been scanned for the buyer key, emails, payment IDs, and raw HTML tags; all six source URLs returned 200 without authentication. The folder has not yet been published to stable public URLs. +See [FRICTION.md](FRICTION.md) for the still-missing public payable schemas, dynamic AI price, quote handling, and the resolved empty model-content failure. The representative sample files have been scanned for the buyer key, emails, payment IDs, and raw HTML tags; all six source URLs returned 200 without authentication. The redacted sample and runner are published on the repository's `main` branch. diff --git a/showcase/README.md b/showcase/README.md index c27a9478..1e40c45b 100644 --- a/showcase/README.md +++ b/showcase/README.md @@ -71,9 +71,10 @@ Each tutorial declares a **tier**: 200 + settlement` — with a real per-session credit balance that decrements per call and responses that react to what you type. It talks to a **local sandbox agent** (`lib/demo-agent.mjs`), so it spends no real money and needs no credentials or backend. -- **`recap`** — the two paid `catalog/` demos spend real crypto autonomously across chains, so they are - **watch-only**: embedded video, playable outputs, the on-chain receipt, and a "run it locally" - note. +- **`recap`** — paid `catalog/` demos are review-only in the browser. A recording and + playable outputs appear where public media exists; otherwise the page shows the + observed receipt and links to a redacted sample. Run the source tutorial locally + with your own capped buyer delegation to make fresh paid calls. - **`discover`** — the catalog *discovery* demo (`discover-the-catalog`) is read-only and free, so its `See it run` panel is **functional in the browser**: it queries the real, public catalog live (REST, the Catalog MCP, and the ARD registry) through the `/api/catalog` same-origin proxy — no credentials, diff --git a/showcase/app/t/[slug]/page.tsx b/showcase/app/t/[slug]/page.tsx index 8bf46730..720160f4 100644 --- a/showcase/app/t/[slug]/page.tsx +++ b/showcase/app/t/[slug]/page.tsx @@ -32,6 +32,14 @@ export default async function TutorialPage({ params }: { params: Promise<{ slug: if (!t) notFound(); const isRecap = t.tier === "recap"; + const evidenceOnly = t.run.kind === "recap" && !t.run.video; + const tierLabel = evidenceOnly + ? "recap · review the run" + : isRecap + ? "recap · watch it run" + : t.tier === "discover" + ? "discover · free & live" + : "live · you pay per call"; // discover tutorials keep the demo (§4) and the video in a separate §5 const discoverVideo = t.run.kind === "discover" ? t.run.video : undefined; @@ -55,11 +63,7 @@ export default async function TutorialPage({ params }: { params: Promise<{ slug: ))} - {t.tier === "recap" - ? "recap · watch it run" - : t.tier === "discover" - ? "discover · free & live" - : "live · you pay per call"} + {tierLabel}

{t.title}

@@ -183,7 +187,8 @@ export default async function TutorialPage({ params }: { params: Promise<{ slug: {/* 4 — Run */}
- 4 See it run + 4{" "} + {evidenceOnly ? "Review the run" : "See it run"}
{t.run.kind === "live" ? ( diff --git a/showcase/content/tutorials.ts b/showcase/content/tutorials.ts index 24afb94b..03e07393 100644 --- a/showcase/content/tutorials.ts +++ b/showcase/content/tutorials.ts @@ -1,4 +1,5 @@ import type { Tutorial, Protocol } from "@/lib/types"; +import { repoFileUrl } from "@/lib/repo"; // Every entry is sourced from the tutorial's own README in this repo. // Order here is the gallery order. @@ -741,12 +742,13 @@ weather.ensureCity # prompt — guide the LLM to request weather`, ["Brave", "today's headline", "$0.035"], ["2s.io", "the lyrics", "$0.0025"], ["Suno", "the song", "$0.105"], + ["Suno status checks", "3 × $0.005 polling", "$0.015"], ["fal.ai", "the album cover", "$0.003"], - ["Total", "4 vendors · 2 chains", "~$0.16"], + ["Total", "7 settled calls · 2 chains", "$0.1605"], ], - totalRow: 4, + totalRow: 5, }, - warn: "Real money — the run-it-yourself script spends ~$0.16 on live blockchains, capped at 50¢ and 10 minutes so it can't overspend. That's why this tutorial is watch-only in the browser.", + warn: "The September 15 Live follow-up made seven Settled payments totaling $0.1605, delivered its first headline in 8 seconds, and consumed 20¢ of a 50¢ delegation cap. Its new audio and cover stay private; the playable media here is the earlier public reference run. Running the script yourself spends real money.", interactive: [ { label: "Interactive showcase", href: "https://claude.ai/code/artifact/160b776a-65c5-4059-be76-e8972190df89" }, ], @@ -816,6 +818,141 @@ weather.ensureCity # prompt — guide the LLM to request weather`, }, }, + // ────────────────────── Catalog · bounded evidence packs ──────────────────── + { + slug: "sec-earnings-evidence-pack", + title: "SEC Earnings Evidence Pack", + tagline: + "Buy five filing and earnings responses through one capped Router delegation, then assemble a source-linked Apple evidence pack without turning the figures into an investment conclusion.", + protocol: "catalog", + language: "py", + tier: "recap", + repoPath: "catalog/sec-earnings-evidence-pack/", + learn: { + lead: "A paid data workflow is reviewable when every figure keeps its source, period, and receipt.", + bullets: [ + "Discover the payable EDGAR and Alpha Vantage services and verify their POST paths before spending", + "Cap the run at five calls and 10¢ for ten minutes", + "Keep filing dates, accession numbers, XBRL periods, and source fields beside the selected values", + "Stop on missing delivery, settlement, or budget evidence rather than guessing a result", + ], + }, + how: { + paragraphs: [ + "The script buys SEC submissions, SEC company facts, EDGAR keyword search, Alpha Vantage earnings, and an income statement. An offline builder selects evidence from the delivered bodies and marks unavailable fields instead of inventing them.", + "The September 15 Apple run delivered all five paid responses. Merchant charges totaled $0.040; each sub-cent call counted as one cent against the delegation cap, so 5¢ of the 10¢ cap was consumed.", + ], + table: { + head: ["Source", "Evidence", "Caution"], + rows: [ + ["SEC submissions", "latest 10-K/10-Q and accession", "check filing date"], + ["SEC company facts", "revenue and net-income XBRL", "check period and unit"], + ["EDGAR search", "keyword hit lower bound", "hits may be third-party mentions"], + ["Alpha Vantage", "quarterly EPS and income", "secondary data may lag SEC"], + ], + }, + }, + tech: { + stack: ["Nevermined Catalog", "Router", "bash runner", "Python builder", "SEC EDGAR", "Alpha Vantage", "10¢ cap"], + samples: [ + { + caption: "bounded Apple Live run — requires your own funded buyer key", + lang: "bash", + code: "CIK=320193 SYMBOL=AAPL COMPANY=Apple ./run-demo.sh", + }, + ], + files: [ + { path: "run-demo.sh", desc: "five-call bounded Live runner" }, + { path: "build-pack.py", desc: "offline evidence builder from saved paid responses" }, + { path: "sample/evidence.md", desc: "redacted representative Apple evidence pack" }, + ], + }, + run: { + kind: "recap", + receipt: { + head: ["Paid source", "Calls", "Observed merchant charge"], + rows: [ + ["SEC submissions", "1", "$0.008"], + ["SEC company facts", "1", "$0.008"], + ["EDGAR search", "1", "$0.008"], + ["Alpha Vantage earnings", "1", "$0.008"], + ["Alpha Vantage income", "1", "$0.008"], + ["Total", "5 Settled", "$0.040"], + ], + totalRow: 5, + }, + warn: "The September 15 Live run delivered its first result in 10 seconds and finished in 41 seconds. It spent real money; the public sample is redacted and is evidence, not investment advice. Raw Router envelopes and payment records remain private.", + interactive: [ + { label: "Read the redacted evidence pack", href: repoFileUrl("catalog/sec-earnings-evidence-pack/", "sample/evidence.md") }, + ], + }, + }, + { + slug: "competitive-product-teardown", + title: "Competitive Product Teardown", + tagline: + "Compare a public product page with rival search evidence, then write a sourced positioning hypothesis under a 25¢ paid-run cap.", + protocol: "catalog", + language: "py", + tier: "recap", + repoPath: "catalog/competitive-product-teardown/", + learn: { + lead: "A paid research chain can separate sourced observations from a model's unverified interpretation.", + bullets: [ + "Use Brave search and Serper scrape to collect bounded public evidence", + "Optionally pay DeepSeek for a short draft while keeping its claim labeled unverified", + "Check delivered bodies, settled merchants, buyer fees, and remaining budget after every purchase", + "Publish a redacted Markdown and JSON comparison while private receipts stay in ignored out/", + ], + }, + how: { + paragraphs: [ + "The runner checks each Catalog slug and payable path, buys rival search and company-page extraction, then optionally asks a model to draft two sentences from short excerpts. It records source URLs and asks a human to test whether the comparison is a real differentiator.", + "The Firefox versus Brave follow-up completed all three calls on September 15. A later read-only ledger check reconciled the initially Submitted Brave buyer fee to Settled; total merchant-plus-fee charge was $0.069.", + ], + table: { + head: ["Paid service", "Purpose", "Observed charge"], + rows: [ + ["Brave", "rival search", "$0.035"], + ["Serper", "company-page scrape", "$0.020 + $0.010 buyer fee"], + ["DeepSeek", "optional draft", "$0.004"], + ], + }, + }, + tech: { + stack: ["Nevermined Catalog", "Router", "Brave", "Serper", "DeepSeek", "25¢ cap"], + samples: [ + { + caption: "free synthetic preview — no buyer key or payment", + lang: "bash", + code: "python3 run.py && cat out/teardown.md", + }, + ], + files: [ + { path: "run.py", desc: "bounded Live runner and free synthetic fixture mode" }, + { path: "wrapper-contract.json", desc: "verified payable paths and response wrappers" }, + { path: "sample/teardown.md", desc: "redacted representative Firefox versus Brave comparison" }, + ], + }, + run: { + kind: "recap", + receipt: { + head: ["Service", "Result", "Observed charge"], + rows: [ + ["Brave", "Settled search", "$0.035"], + ["Serper", "Settled scrape + buyer fee", "$0.030"], + ["DeepSeek", "Settled model draft", "$0.004"], + ["Total", "3 delivered calls", "$0.069"], + ], + totalRow: 3, + }, + warn: "The later Live follow-up delivered its first result in 13.48 seconds. The earlier representative run consumed 8¢ of its 25¢ cap, and its redacted sample is linked here. The model draft is unverified; check the cited pages before using the comparison. Running the Live script spends real money.", + interactive: [ + { label: "Read the redacted teardown", href: repoFileUrl("catalog/competitive-product-teardown/", "sample/teardown.md") }, + ], + }, + }, + // ─────────────────────────────── MPP — pay-as-you-go forecast ─────────────── { slug: "mpp-weather-payg", diff --git a/showcase/lib/types.ts b/showcase/lib/types.ts index 18bfc795..4b77676b 100644 --- a/showcase/lib/types.ts +++ b/showcase/lib/types.ts @@ -81,7 +81,8 @@ export interface LiveRun { note: string; } -/** Section 4 (recap) — watch it run; no live backend (real money / autonomy). */ +/** Section 4 (recap) — review the paid run via public media when available, + * otherwise via the receipt and redacted sample; no live backend. */ export interface RecapRun { kind: "recap"; video?: {