docs(bnbagent-sdk): fix non-existent server module, install extras, and 404 example links - #882
Conversation
…le paths The SDK docs referenced a `bnbagent.erc8183.server` module and a `server` install extra that do not exist in the published package. Following the quickstart produced a ModuleNotFoundError. Verified against bnbagent-sdk @ v0.5.1: - No `server` extra. `pyproject.toml` defines only `ipfs`, `dev`, and `examples`; `examples` is the group that carries FastAPI/Uvicorn/dotenv. Replaced `bnbagent[server,ipfs]` with `bnbagent[ipfs,examples]`. - No `bnbagent/erc8183/server/` package. `create_erc8183_app()` lives in python/examples/agent-server/src/erc8183_server.py, which that example's own README states is "example code, not SDK API". Reframed the quickstart and architecture sections accordingly and corrected the imports. - `bnbagent/erc8183/module.py` / `ERC8183Module` do not exist; replaced that architecture table row with the real `job_ops.py` entry. - Example links were missing the `python/` path prefix and 404'd. Also clarifies `bag budget enable` in the Studio security page: it enables wallet-funded renewal (off by default) and is separate from the managed-model auto-renew hook, which is included at no cost.
Pull Request ReviewThis documentation-only PR corrects the Python/web3 BNB Agent SDK installation and server guidance by replacing the nonexistent Sensitive ContentNo sensitive content detected. Security IssuesNo serious security issues detected. Generated by Hashdit Bot. This tool can absolutely NOT replace manual audits. |
The five claims in bnb-chain#882 were all symptoms of one upstream commit (0523197, "drop the built-in REST server", shipped in bnbagent-v0.4.0). That commit deleted more than the server package, and the docs only caught up on the instances that had been clicked. This sweeps the rest. architecture.md - Tier 1 import block raised ImportError: BNBAgent and BNBAgentConfig are not in upstream __all__ (main.py deleted; BNBAgentConfig renamed to AgentConfig in core/). Same failure mode bnb-chain#882 was opened to fix, 14 lines above the import it already corrected. - Removed the deleted plugin/module system: main.py, core/module.py, core/registry.py and erc8004/module.py table rows; the "Module System" section, which told readers to register plugins under a [project.entry-points."bnbagent.modules"] group absent from pyproject.toml; the ModuleInfo.dependencies invariant; the "Custom Module" extension point; the facade box in the diagram. - Config-flow diagram: BNBAgentConfig -> ERC8183Config, which inherits wallet_provider from AgentConfig. - Dependencies table advertised a "Server (optional)" extra, contradicting the no-server-extra note this PR adds to index.md. Rewritten to the three real extras with contents from PyPI 0.4.3. - Redrew the architecture diagram; the connectors no longer met the boxes. bnbagent-sdk/security.md - Two more 404 example links; it was eight, not six. Both were renamed as well as moved, so the python/ prefix alone would not have fixed them: python/examples/security/e2e.py, python/examples/x402/buyer_demo.py. quickstart.md - Dropped the await on erc8183_app.state.startup(). state.startup is a sync lambda returning the infinite poll loop's Task, so awaiting it meant the lifespan never reached yield and uvicorn never served. Pre-existing, mirrored upstream at service_mount.py:156. index.md, bnbchain-studio/architecture.md - Stale "module system" prose. Names no symbol, so an identifier grep misses it; found by sweeping the vocabulary instead. bnbchain-studio/security.md - "included at no cost" is unsupported by any shipped artifact. The managed-model hook never spends from the wallet but does draw down the prepaid Pieverse Account Balance; it is $0 only on the default auto/free model. Verified against npm @bnbagent/studio-cli 0.0.12, the package index.md:27 tells users to install (the GitHub repo 404s, the CLI is published). - Noted that an interactive bag init prompts [Y/n] and treats bare Enter as yes, so the most common first run opts in. - Fallback is automatic allocate-only mode, not "manual bag llm allocate". Outstanding, tracked separately: 15 dead links to bnb-chain/bnbagent-studio across the studio doc set, and docs/llms.txt:217, which is generated and needs a sync re-run rather than a hand-edit.
Pull Request ReviewThis documentation-only PR aligns the BNB Agent SDK guides with the current Python package by removing references to the deleted plugin/server APIs, documenting the example-based FastAPI integration, and correcting installation extras and imports. It also repairs moved/renamed example links, fixes the mounted-app startup guidance, and clarifies BNB Agent Studio wallet-funded auto-top-up behavior. Sensitive ContentNo sensitive content detected. Security IssuesNo serious security issues detected. Generated by Hashdit Bot. This tool can absolutely NOT replace manual audits. |
… entry llms.txt:217 still described the SDK architecture page as "Module system and data flows". The module/plugin system was removed upstream in 0523197 and this PR strips the last of it from the page itself, so the index line pointed at a section that no longer exists. Retargeted to the page's actual headings (Code Map, Public API, Invariants, Data Flows). Single-line correction, not a full index re-sync.
Pull Request ReviewThis documentation-only PR aligns the BNB Agent SDK guides with the current Python package by removing references to the deleted plugin/server APIs, replacing the nonexistent Sensitive ContentNo sensitive content detected. Security IssuesNo serious security issues detected. Generated by Hashdit Bot. This tool can absolutely NOT replace manual audits. |
…-server-references # Conflicts: # docs/developer-kit/bnbagent-sdk/architecture.md # docs/developer-kit/bnbagent-sdk/index.md # docs/developer-kit/bnbchain-studio/architecture.md # docs/llms.txt
Pull Request ReviewThis documentation-only PR aligns the BNB Agent SDK guides with the current published Python package by removing references to the deleted plugin/server modules, replacing the nonexistent Sensitive ContentNo sensitive content detected. Security IssuesNo serious security issues detected. Generated by Hashdit Bot. This tool can absolutely NOT replace manual audits. |
2 participants
Summary
The BNB Agent SDK docs reference a
bnbagent.erc8183.servermodule and aserverinstall extra that do not exist in the published package. A developer following the quickstart hitsModuleNotFoundErroron the first server example.Verification is source-level against
bnb-chain/bnbagent-sdkmain@1f5476band the publishedbnbagent0.4.3 wheel on PyPI. (Note: the repo'sv0.5.1tag is the TypeScript package@bnbagent/sdk; the Python tag for the same tree isbnbagent-v0.4.3.)Root cause
Two upstream commits, not five unrelated errors:
0523197— "drop the built-in REST server (Remove 404 link #44)", 2026-07-01, first shipped inbnbagent-v0.4.0. Deleted the REST server package and the entire plugin/module system, and renamed two example scripts.010703a— monorepo restructure, 2026-08-06. Movedexamples/→python/examples/.Confirmed on PyPI: the
serverextra is present in 0.3.0 and absent from 0.4.0 onward.What was wrong
pip install "bnbagent[server,ipfs]"andbnbagent[server]serverextra.python/pyproject.tomldefines onlyipfs,dev,examples. pip emitsWARNING: bnbagent 0.4.3 does not provide the extra 'server'and continues, so FastAPI/Uvicorn never get installed.from bnbagent.erc8183.server import create_erc8183_appcreate_erc8183_app()lives inpython/examples/agent-server/src/erc8183_server.py:254. That example's own README states it is "example code, not SDK API".architecture.mddocuments abnbagent/erc8183/server/package withroutes.pyjob_ops.pyis real, but sits atbnbagent/erc8183/job_ops.py.architecture.mdlistsmodule.py/ERC8183Moduletree/main/examples/...tree/main/python/examples/....Beyond the five: the rest of the class
The five claims above are symptoms of
0523197. Sweeping the docs for everything that commit deleted or moved turned up more of the same defect:ImportError—BNBAgentandBNBAgentConfigare not in upstream__all__;main.pywas deleted by0523197andBNBAgentConfigwas renamed toAgentConfigincore/. This is the PR's own headline failure mode, 14 lines above the import it originally fixed.architecture.mdmain.py/core/module.py/core/registry.py/erc8004/module.pytable rows, the "Module System" section (which instructed readers to register plugins under a[project.entry-points."bnbagent.modules"]group absent frompyproject.toml), theModuleInfo.dependenciesinvariant, the "Custom Module" extension point, and the facade box in the architecture diagram.architecture.mdblob/main/examples/rather thantree/main/examples/, and the files were renamed as well as moved, so apython/prefix alone does not fix them:python/examples/security/e2e.pyandpython/examples/x402/buyer_demo.py(both 200).bnbagent-sdk/security.mdstate.startupis assigned aterc8183_server.py:470aslambda: _spawn(_funded_poll_loop())— a sync lambda returning the infinite poll loop'sTask. Awaiting it means the lifespan never reachesyieldand uvicorn never serves. Reproduced under Python 3.11. Pre-existing, and mirrored upstream atservice_mount.py:156.quickstart.mdarchitecture.md,index.md,bnbchain-studio/architecture.mdServer (optional)extra, contradicting the "noserverextra" note added by this PR.architecture.mdChanges
index.md— replaced the phantomserverextra with the realexamplesextra (which carries FastAPI/Uvicorn/python-dotenv/ddgs/aiosqlite); added a note that noserverextra exists; retitled the doc-table rows that referred to a module system.quickstart.md— added an admonition explainingcreate_erc8183_appis reference example code to copy; corrected both imports tofrom erc8183_server import ...; dropped theawaitonerc8183_app.state.startup()with a comment on why.architecture.md— removed the deleted plugin/module system in full (table rows, "Module System" section, invariant, extension point, diagram facade, prose); fixed the Tier 1 import block; corrected the config-flow diagram toERC8183Config; rewrote the dependencies table to the three real extras with their actual contents.bnbagent-sdk/security.md— repointed the two remaining 404 links to their renamed paths.bnbchain-studio/architecture.md— "protocol module system" → "protocol subpackage layout".bnbchain-studio/security.md—bag budget enableopts into wallet-funded renewal and is off by default; corrected "included at no cost", which no shipped artifact supports (the managed-model hook never spends from the wallet, but it draws down the prepaid Pieverse Account Balance; it is $0 only on the defaultauto/freemodel); noted that an interactivebag initprompts[Y/n]and treats bare Enter as yes; corrected the fallback from "manualbag llm allocate" to allocate-only mode. Verified against npm@bnbagent/studio-cli0.0.12 — the packagebnbchain-studio/index.md:27tells users to install. The GitHub repo 404s, but the CLI is published.Verification
The original check here grepped
docs/for the three strings this PR removes, so it could only ever return clean. Replaced with checks derived from the root-cause commits:All three return no matches on this branch. Every
bnbagent-sdkexample link in the doc set was status-checked; all resolve.Known issue, tracked separately
docs/developer-kit/bnbchain-studio/*.mdcontains 15 links togithub.com/bnb-chain/bnbagent-studio, which returns 404 — including one inbnbchain-studio/security.md, a file this PR edits. Counted at this head:demo.md6,architecture.md2,deployment.md2,troubleshooting.md2,index.md1,cli-reference.md1,security.md1. Out of scope here; follow-up PR to come. Note thebagCLI itself is public on npm, so if that repo is staying private those links may want to point at the package rather than be removed.docs/llms.txt:217also still reads "Module system and data flows". That file is generated (chore(llms): sync llms index), so it needs a sync re-run rather than a hand-edit — folding into the same follow-up.Limits
Verification is source-level and against published package metadata. The
ModuleNotFoundErrorand theawaitdeadlock were reproduced from the code and a stdlib repro, not by installingbnbagentand running the quickstart end to end.Note on the SDK's own README
python/README.mdin the SDK repo already sayspip install "bnbagent[ipfs]"correctly — the drift was only in these docs.