feat(langchain-paid-agent-py): Sprint 1 — LangSmith observability bridge

[r-marques]

Summary

Wires the existing LangChain tutorial to the new LangSmith observability bridge shipping in payments-py 1.8.0 (Sprint 1 of the LangChain partnership epic).

Zero code changes in src/ — the bridge is fully zero-config opt-in via env vars on top of the Sprint 0 agent + buyer.

Files changed

File	Change
langchain-paid-agent-py/pyproject.toml	payments-py dep bumped to ^1.8.0 with both extras ([langchain, langsmith]); tutorial version 1.0.0 → 1.1.0.
langchain-paid-agent-py/.env.example	New Observability (optional) block with the LANGSMITH_* vars (TRACING, API_KEY, PROJECT) plus the regional LANGSMITH_ENDPOINT fallback table for GCP EU / APAC / AWS US accounts.
langchain-paid-agent-py/README.md	New ## Observability with LangSmith (optional) section (~48 lines) covering install, enable, re-run, what to look for in the trace tree, and the active payment_token redaction privacy note.

How it works

A reader who already followed the Sprint 0 quickstart just needs to:

1. poetry install (picks up the new [langsmith] extra)
2. Uncomment the LangSmith block in .env
3. Re-run poetry run buyer

The trace tree then shows two dedicated child spans under the tool:

LangGraph
└── tools
    └── get_market_insight
        ├── nvm:verify      ← around verify_permissions
        └── nvm:settlement  ← around settle_permissions

Each carries nvm.* metadata: nvm.plan_ids, nvm.scheme, nvm.payer, nvm.payment_token (abbreviated), nvm.credits_redeemed, nvm.tx_hash, nvm.balance.after, nvm.network, nvm.verify.duration_ms, nvm.settle.duration_ms.

The failed discovery probe (first invocation without a token) also produces an nvm:verify span — marked failed but carrying the static plan / scheme / network attrs, so it's filterable in the LangSmith UI rather than an opaque LangChain crash.

Status

Draft because the underlying payments-py 1.8.0 is not yet on PyPI — it's in nevermined-io/payments-py#198 (also draft). Once that PR is reviewed, merged, and tagged via the prepare-release.yml workflow, this can be marked ready for review.

Pairs with

• nevermined-io/payments-py#198 — SDK side (the payments_py.langsmith module + decorator hooks)
• nevermined-io/docs#185 — Mintlify docs (integration guide + skill reference)

Implements nevermined-io/nvm-monorepo#1705 (Sprint 1 tutorial deliverable).

Test plan

• Tutorial directory cleanly branches from origin/main — no stray files from other branches (web-search-paid-api-ts/ left untracked, not staged)
• Sprint 0 codepath untouched — src/agent.py, src/buyer.py, src/__init__.py not modified
• .env.example syntactically valid (commented lines only)
• After payments-py 1.8.0 ships: poetry install in a fresh clone resolves cleanly
• After payments-py 1.8.0 ships: poetry run buyer with LANGSMITH_TRACING=true produces the expected trace tree with nvm:verify + nvm:settlement spans
• Screenshot of the trace tree attached to the SDK PR / nvm-monorepo#1705 closeout

🤖 Generated with Claude Code