[adiman9]

What

The Python SDK (python/arete-sdk) honours the dev environment switch from docs/internal/dev-environment-switch.md. This is the Python half of the parity work; the Rust SDK and a4/MCP are in #482. The two PRs are independent.

• Switch (§2): environment= on Arete.connect, create_session and ProtocolClient ("production" or {"kind": "dev", "url"?, "env"?}; arete.dev_environment.dev(url=..., env=...) builds one). Without it, ARETE_ENVIRONMENT decides, and production is the default. Precedence, edge URL and environment reference grammar, and the nearest .arete/dev/session.json follow the contract. With the switch unset no dev input is read (the secret-key check is lazy too) and production requests are unchanged. environment is only added to session bodies when it is set.
• Edge (§3.1): chain, transactions, Program Read, stack socket + queries and the protocol API go to the edge with no Authorization and the X-Arete-Dev-Identity header (none for stacks). Answers without X-Arete-Dev-Edge: 1, or a failed connection, raise devenv-edge-unreachable. GET /.well-known/arete-dev-edge is checked before the socket opens. Unpublished protocols use package:<package>. A stack without a release raises devenv-stack-not-loaded.
• Direct (§3.2/§4/§5): at connect the client resolves gateway, stack and hosted program-read identities in one request; protocol clients resolve on first use. Answers are cached for the life of the client. Environment tokens carry environment. Program Read authenticates with the installed release and reads the served release. Protocol sessions name the environment's deployment.
• Refusals (§6): arete.DevEnvironmentError (an AreteError). code is the wire code, message is the message, and details holds fix and every other detail field (.fix reads it). It is read from the API problem envelope or the Program Read envelope, from services, the edge, resolve and the session endpoint. Malformed config raises AreteError with code INVALID_CONFIG. A refused surface raises before anything is sent; other surfaces keep working.
• client.environment, ProtocolClient.environment, Session.environment ("production" / "dev").

Vectors

tests/test_dev_environment_vectors.py runs every case of switch.json, targets.json and refusals.json and is picked up by the existing Python CI matrix. targets.json runs end to end: each surface is built the way a client builds it, and its requests (endpoint, token request, session endpoint, identity header, resolve request, absence of Authorization) are captured by a mock transport. Three client-level tests cover ARETE_ENVIRONMENT=dev + ARETE_DEV_URL on Arete.connect, an unknown switch value, and environment == "production".

Known gaps

• Transaction routes mint per-route scopes (transaction:inspect, or transaction:send for sends). That is existing production behaviour, so the test checks the minted scope is a subset of the vector's tokenRequest.scopes.
• The stack socket session body has never carried scopes. The stack query session body matches the vector.
• In dev mode a custom url/http_url is refused (INVALID_CONFIG), because the stack is resolved by identity.
• Protocol metadata wallet proofs in direct mode are still signed over the installed deployment id.

Testing

Run locally: python -m pytest in python/arete-sdk on Python 3.11: 1173 passed, 102 of them dev-environment tests. Python 3.9/3.10 and the solana extra run only in CI.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
arete-docs	Ready	Preview	Oct 29, 2026 5:30am UTC

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; the cancelled-request retry issue is fixed.

Summary

The Python SDK adds a dev environment switch for stack clients, sessions, and protocol clients.

• Python stack clients can route traffic to a selected development environment.
• Protocol clients can send requests to the selected development deployment.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Client environment switch] --> B{Selected mode}
    B -->|Production| C[Installed endpoints]
    B -->|Dev edge| D[Local edge with installed identity]
    B -->|Dev direct| E[Resolve installed identities]
    E --> F[Resolved endpoints and environment sessions]

Loading

_{Reviews (4) · Last reviewed commit: "fix(python-sdk): a failed resolve is for..." · Reviewed by Greptile}