docs(langchain): add tutorial reference + Python LangChain module reference

[r-marques]

Summary

Three changes for the LangChain integration docs:

1. docs/integrate/add-to-your-agent/langchain.mdx — surfaces the new SDK helpers and the x402 discovery-first flow:
   • <Card> link to the new langchain-paid-agent-py tutorial at the top.
   • New "Discovery-first flow with create_paid_react_agent (Python)" subsection that walks the canonical x402 dance: invoke without a token → catch PaymentRequiredError → read accepts[0].scheme/network/plan_id → acquire token via DelegationConfig → retry.
   • New "Reading the settlement receipt" subsection using last_settlement() — explains the LangGraph copies-configurable-per-node quirk and how the SDK works around it.
   • <Note> callout in the Dynamic Credits section on fixed-vs-range plan credit semantics (per nvm-monorepo#1568).
2. docs.json — sidebar slot for the new docs/api-reference/python/langchain-module page (will be auto-populated by the SDK release pipeline, see below).
3. skills/nevermined-payments/references/langchain-integration.md (NEW) — closes the pre-existing skill-ref gap that aaitor flagged. Mirrors the strands / fastapi / express patterns: quick start, discovery flow, LangGraph helper, settlement read, decorator configuration, credits semantics, and the HTTP-middleware alternative.

What changed since the original PR (in response to aaitor's review)

The original PR included a hand-authored docs/api-reference/python/langchain-module.mdx and listed the skill reference as out of scope. On checking aaitor's "convention drift" note, I confirmed there IS a Python doc-publish pipeline (payments-py/.github/workflows/publish-mintlify-docs.yml) that does rm -f "$TARGET_DIR"/*.mdx before copying converted output on every release tag — so a hand-authored mdx in docs/api-reference/python/ would be silently wiped. The docs CLAUDE.md rule ("sourced from different repositories — don't modify directly") is correctly stated.

So this PR:

• Drops the hand-authored langchain-module.mdx — it now lives as a Markdown source in nevermined-io/payments-py#187 (which adds docs/api/12-langchain-integration.md + a FILE_MAPPING entry in scripts/convert_to_mintlify.py + bumps the workflow's expected-file count from 11 to 12). The MDX will be generated by the release pipeline and land here automatically.
• Adds the skill reference that was previously deferred.

Merge sequence (release-train coordination)

1. payments-py#187 merges to payments-py main.
2. payments-py tags a release (e.g. v1.6.1 or v1.7.0). The workflow runs, opens an auto-PR on this repo with the new converted langchain-module.mdx, auto-merges it.
3. This PR rebases on the updated main (which now contains langchain-module.mdx) and merges. The sidebar entry in docs.json lights up; cross-links from langchain.mdx and the skill reference resolve.

Test plan

• mintlify broken-links → success no broken links found.
• docs.json validates as JSON.
• Integration-page edits + skill ref are coherent on their own (don't depend on the new module page).
• Hold merge until payments-py#187 merges AND a release ships — the docs.json sidebar entry points at a file that doesn't exist in this repo yet.

Motivation

Sprint 0 of the LangChain integration epic (nevermined-io/nvm-monorepo#1703, sub-issue #1704). The new SDK helpers (last_settlement, create_paid_react_agent) are on payments-py main via #183 (merged) but await a release.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Nevermined	🟢 Ready	View Preview	May 22, 2026, 3:05 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[aaitor]

Tight docs PR that fully matches the payments-py #183 surface I just reviewed. The new langchain-module.mdx reference page documents all four exports (requires_payment, PaymentRequiredError, last_settlement, create_paid_react_agent) with signatures, the credits-semantics note pointing at nvm-monorepo#1568, and the same multi-tenant warning on last_settlement() that's in the SDK docstring. The integration-guide additions (Discovery-first flow + Reading the settlement receipt + Dynamic Credits clarification) thread cleanly with the new reference page. Cross-references all pass Mintlify link-rot. Approving with two LOW body observations and a merge-gate reminder.

Verification I ran

• gh pr diff 178 (427 lines, all signal — no lockfile-style noise).
• Cross-checked every code example in langchain-module.mdx against the actual SDK shapes I verified in payments-py #183:
  • X402TokenOptions(scheme=..., delegation_config=DelegationConfig(...)) wrapping — matches get_x402_access_token(plan_id, agent_id=None, token_options=None) signature.
  • from payments_py.x402.langchain import ... exports list — matches the __all__ I saw in the SDK PR.
  • last_settlement() multi-tenant <Warning> wording — verbatim mirror of the SDK docstring.
  • credits semantics note — accurate per the nvm-monorepo#1568 fixed-vs-range behaviour (matches the SDK's updated requires_payment docstring I read yesterday).
• Verified docs.json slot for langchain-module lands after x402-module in the Python API reference sidebar (line 272 of the diff).
• Verified the new module page's section anchors (#requires-payment, #paymentrequirederror, #last-settlement, #create-paid-react-agent, #credits-semantics) match the cross-link target IDs from langchain.mdx.
• Spot-checked the apparent docs/api-reference/ convention concern (the docs CLAUDE.md at L384 says "All the documentation included in the 'docs/api-reference' folder is sourced from different repositories. Don't modify it directly"): no sync workflow exists in .github/workflows/, no scripts/ directory, and the existing module pages (x402-module.mdx, installation.mdx, …) have no auto-gen markers — they're hand-authored. The rule appears aspirational rather than enforced today. See the body note for the suggested follow-up.
• CI: Mintlify Deployment ✓, link-rot ✓, vale-spellcheck skipping (correctly).
• Parallel agent panel: skipped — small docs PR, cross-referenced against the payments-py SDK PR I reviewed yesterday, no auth / DB / contract surface. The integration is fully covered by the manual verification above.

Merge-gate reminder

Author's test plan correctly flags "Hold merge until payments-py 1.6.1+ ships" as the open prerequisite. The helpers documented here (last_settlement, create_paid_react_agent) are on payments-py main (PR #183 merged) but await a release. The <Card> link at the top of langchain.mdx points at nevermined-io/tutorials/tree/main/langchain-paid-agent-py — also worth confirming that tutorial repo is ready (or close enough) on merge day, since a broken link from a freshly-deployed docs page would be visible to readers immediately.

Out-of-scope observations (not blocking)

• docs/api-reference/ convention drift: The docs CLAUDE.md rule ("sourced from different repositories — don't modify directly") doesn't match the current state of the repo. The pre-existing Python module pages have no auto-gen markers; no sync workflow exists. Either the rule needs to be relaxed ("sourced where applicable; new module pages can be hand-authored") or a real sync mechanism needs to be set up. Worth a small follow-up to clarify the CLAUDE.md text so future contributors don't second-guess legitimate additions like this one.
• skills/nevermined-payments/references/langchain-integration.md is missing: The author's PR description acknowledges this as a pre-existing gap (other frameworks like a2a, express, fastapi, mcp, strands all have *-integration.md files in skills/nevermined-payments/references/). The docs CLAUDE.md L23 explicitly asks contributors to keep these in sync with framework integration changes. Worth a small follow-up PR that mirrors the new module-reference content into a langchain-integration.md skill reference file.

[r-marques]

Thanks @aaitor — your two out-of-scope observations turned into real fixes:

On the convention-drift note (N1): double-checked and the rule docs/api-reference/ is sourced from other reposis **correctly stated** —payments-py/.github/workflows/publish-mintlify-docs.ymldoesrm -f "$TARGET_DIR"/*.mdxbefore copying converted output on every release tag. The reason it's not visible from inside this repo: the workflow lives in the SDK repo, not here. So a hand-authoredlangchain-module.mdx` would have been silently wiped on the next payments-py release. Force-pushed the PR to drop it; the source MD + converter entry now live in nevermined-io/payments-py#187 and the MDX will be produced by the pipeline on next release.

On the skill-reference note (N2): added skills/nevermined-payments/references/langchain-integration.md mirroring the existing strands/fastapi/express patterns.

PR body updated with the new merge sequence. Holding until payments-py#187 lands AND a release ships.