Metadata-Version: 2.4
Name: bnbagent-studio-core
Version: 0.0.2
Summary: Agent-runtime library for bnbagent-studio: wallet, ERC-8004, ERC-8183, x402 over bnbagent-sdk.
Project-URL: Homepage, https://github.com/bnb-chain/bnbagent-studio
Project-URL: Repository, https://github.com/bnb-chain/bnbagent-studio
Author: BNB Chain Studio
License-Expression: Apache-2.0
Keywords: agent,blockchain,bnb,erc-8004,erc-8183,x402
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: bnbagent>=0.3.5
Requires-Dist: eth-account
Requires-Dist: httpx
Requires-Dist: python-dotenv>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: tomlkit>=0.13
Requires-Dist: web3
Provides-Extra: serve
Requires-Dist: fastapi>=0.110; extra == 'serve'
Requires-Dist: uvicorn>=0.30; extra == 'serve'
Description-Content-Type: text/markdown

# bnbagent-studio-core

The **agent-runtime library** for
[bnbagent-studio](https://github.com/bnb-chain/bnbagent-studio) — the code a
deployed BNB Chain seller agent imports and runs. It wraps the `bnbagent`
protocol SDK with studio's configuration, workflow, and safety layer so an
agent can sign quotes, run ERC-8183 jobs, pay over x402, and read chain state
without re-implementing any of it.

## Highlights

- **Wraps the `bnbagent` SDK** (wallet / ERC-8004 / ERC-8183 / x402) with
  studio's opinions — `studio.toml` config, multi-step workflows, signing
  policy, and an audit log — while leaving the SDK protocol layer untouched.
- **Lean runtime deps** — `bnbagent`, `web3`, `eth-account`, `httpx`,
  `tomlkit`, `python-dotenv`. No agent framework, no web server in the base
  install.
- **Framework- and runtime-agnostic** — does NOT import ADK, LangChain, or
  bedrock-agentcore. Those couplings live in the CLI's emitted recipes, not
  here, so you can drop this into any runtime.
- **FastAPI is opt-in.** The ERC-8183 seller-hosting helpers are the only code
  that touches FastAPI, and they `import` it lazily — install the `[serve]`
  extra only when you host an 8183 endpoint yourself.
- **What a deployed agent imports.** This is the library a scaffolded agent
  declares as its runtime dependency; signing, settlement, and chain reads all
  flow through it.

> ⚠️ **This project is under active development** and may introduce breaking
> changes between releases. It manages wallet keys and on-chain funds: start on
> **testnet**, and use it at your own risk.

> ⚠️ **Deploying provisions AWS resources in your own account**, under IAM
> policies you review and apply yourself. The published policy documents
> ([least-privilege guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/least-privilege-iam.md),
> [policy JSON](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/iam-policies.md))
> are **reference configurations provided AS IS** — you remain responsible for
> scoping, costs, and security. Full terms:
> [DISCLAIMER.md](https://github.com/bnb-chain/bnbagent-studio/blob/main/DISCLAIMER.md)
> (also shipped in this package as `bnbagent_studio_core/DISCLAIMER.md`).

## Distribution & import names

- **Distribution:** `bnbagent-studio-core`
- **Import package:** `bnbagent_studio_core`

```python
from bnbagent_studio_core import get_wallet, get_policy
from bnbagent_studio_core.erc8183 import submit_workflow, settle_workflow
```

## Where it sits

You normally **don't install this directly**. It's the library half of a
two-distribution split:

- **`bnbagent-studio-core`** (this package, import `bnbagent_studio_core`) — the
  runtime library.
- **`bnbagent-studio`** (import `bag`) — the CLI: scaffolding, recipes, and a
  read-only MCP server. It depends on this package.

Its three consumers:

1. **A deployed Agent (Layer A, on AWS Bedrock AgentCore)** imports it at
   runtime to sign quotes, submit/settle ERC-8183 jobs, auto-renew LLM credit,
   and read chain state. Emitted agent code does
   `from bnbagent_studio_core import ...`.
2. **The `bag` CLI and its read-only MCP server** — shipped as the separate
   `bnbagent-studio` distribution — also import it.
3. **Rarely standalone** — only when building or vendoring an agent runtime by
   hand.

The keyless Layer-B Service depends on **neither** package — it inlines its own
~10-LOC config loader.

## Install

```bash
# Usual path: install the CLI, which pulls this in automatically
pip install bnbagent-studio
```

Install it standalone only when building or vendoring an agent runtime by hand:

```bash
pip install bnbagent-studio-core
```

### The `[serve]` extra

FastAPI/uvicorn are an optional `[serve]` extra. Only the seller-hosting path
(`bnbagent_studio_core.erc8183.seller`, reached via `serve_8183` /
`build_erc8183_app`) imports them, and it does so lazily — the agent runtime
never touches FastAPI. Install the extra only to host an ERC-8183 endpoint
yourself:

```bash
pip install "bnbagent-studio-core[serve]"
```

## What's inside

Modules live under `bnbagent_studio_core/`. The convenience surface that
agent code imports is re-exported from the package root
(`get_wallet`, `get_policy`, `Policy`, `load_studio_toml`,
`find_project_root`, `emit`); lower-level surfaces stay reachable via their
submodules.

- **wallet** — keystore-backed signing. `get_wallet()` returns a
  `bnbagent` `WalletProvider` (an `EVMWalletProvider` that enforces a
  `SigningPolicy` on every sign); `ensure_keystore_materialized()` writes the
  injected keystore to disk when the code mount is read-only. Local Keystore V3
  today (KMS / remote signing deferred to v2).
- **config** — `studio.toml` loading and project discovery:
  `load_studio_toml()`, `find_project_root()`, `find_workspace_root()`,
  `load_env()`.
- **networks** — BSC testnet/mainnet registry and the **U** stablecoin (United
  Stables, 18 decimals) token info; `get_network()`, plus `to_raw` / `from_raw`
  amount converters.
- **policy** — `get_policy()` / `Policy` (budget caps: per-call and daily
  spend limits read from `studio.toml`).
- **erc8004** — identity: `register`, `resolve`, `resolve_service`,
  `update_endpoint`, `update_service_endpoint`, `show` (with `AgentRecord` /
  `ResolvedService` result types).
- **erc8183** — commerce: a pre-configured client (`get_8183_client`),
  multi-step workflows (`buy_workflow` / `submit_workflow` / `fetch_workflow` /
  `settle_workflow`, plus `get_job_summary`), quote verification
  (`verify_signed_job` / `recover_quote_signer` → `Verdict`), off-chain
  negotiation, and seller-hosting starters (`serve_8183` /
  `build_erc8183_app`). Typed errors (`JobNotFoundError`, `JobStateError`,
  `BudgetCapExceededError`, …) are exported alongside.
- **x402** — x402 micropayment buyer kernel over the SDK's hardened
  `X402Signer` (`fetch_with_payment`, `quote_url`, `pay_challenge`,
  `FetchResult`) gated by an `X402BuyerPolicy` / `BudgetTracker`.
- **pieverse** — Pieverse LLM credit layer: `PieverseCreditEnsurer`
  (budget-gated auto-renew), `BudgetPolicy` / `PieversePolicy`, key management
  (`create_key`, `inspect_key`, `allocate`, `get_account_usage`), SIWE login
  (`siwe_login`), and x402 top-up (`topup_x402`).
- **tools.chain_readonly** — 15 read-only on-chain query functions
  (`wallet_info`, `balance_native`, `balance_u`, `agent_info`, `job_status`,
  `job_list`, `tx_status`, `block_info`, `network_info`, …). Also surfaced as
  the CLI's MCP tools; framework-neutral.
- **audit** — `.studio/audit-log.jsonl` emission protocol for on-chain money
  ops: redaction (`validate_no_secrets`), schema (`Event`, `SCHEMA_VERSION`),
  and a writer (`record`, `record_chain_op`, `audited_op`, `tail`).
- **storage** — deliverable storage selection (local file / IPFS) via
  `storage_provider_from_config()`.
- **llm** — framework-neutral LLM-config resolution
  (`_resolve_provider_config()` → `ProviderConfig`) used by emitted provider
  shells. Studio constructs no model object itself.

## Usage

The smallest meaningful snippets — read config and a wallet, verify a signed
quote. See the
[reference doc](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/reference.md)
for the full API.

```python
from bnbagent_studio_core import get_wallet, get_policy, load_studio_toml

cfg = load_studio_toml()           # parsed studio.toml (project root auto-discovered)
wallet = get_wallet()              # keystore-backed WalletProvider (policy enforced)
policy = get_policy()              # budget caps from [policy] in studio.toml
```

```python
# Verify a counterparty's signed ERC-8183 quote before acting on it.
from bnbagent_studio_core.erc8183 import verify_signed_job

verdict = verify_signed_job(signed_job)
if verdict.ok:
    ...  # safe to submit / settle
```

```python
# Read-only chain query (no signing, no key needed).
from bnbagent_studio_core.tools.chain_readonly import balance_u

print(balance_u(network="bsc-testnet"))
```

## Dependencies & boundaries

Runtime dependencies (lean by design):

- `bnbagent`, `web3`, `eth-account`, `httpx`, `tomlkit`, `python-dotenv`
  (and `tomli` on Python < 3.11).

Boundaries:

- **FastAPI/uvicorn are `[serve]`-only.** The agent runtime never imports them;
  the seller-hosting helpers import FastAPI lazily.
- **Framework- and runtime-agnostic.** This library does NOT import ADK,
  LangChain, or bedrock-agentcore — those couplings live in the CLI's emitted
  recipes, not here.
- **The SDK protocol layer stays pure.** Studio's opinions wrap `bnbagent`;
  they never pollute it.

Python ≥ 3.10.

## Further reading

- [Main repository](https://github.com/bnb-chain/bnbagent-studio) — overview,
  guides, and the `bag` CLI.
- [Architecture](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/design/architecture.md)
  — the layered design and two-layer deploy model.
- [Reference](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/reference.md)
  — CLI / recipe / MCP-tool / library reference.
- [User Guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/user-guide.md)
  — the install → skills → Claude Code → `bag dev` path (for CLI end-users).

## License

Apache-2.0.
