bkn-osdk 0.2.1__tar.gz

bkn_osdk-0.2.1/.gitignore

@@ -0,0 +1,60 @@
+# Dependencies
+# No trailing slash: that form matches directories only, and a symlinked
+# node_modules — how a worktree usually borrows the parent's install — is not
+# a directory, so it slipped past and got committed.
+node_modules
+.pnp/
+.pnp.js
+
+# Build output
+dist/
+build/
+.tmp-example/
+*.tsbuildinfo
+
+# Python (python/ — the OSDK runtime + generator)
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+
+# Test / coverage
+coverage/
+.nyc_output/
+test-results/
+*.lcov
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+*.local
+
+# Local CLI state (BKN tokens/config — never commit)
+.bkn/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/*
+!.vscode/extensions.json
+*.swp
+
+# Package manager artifacts
+.npm/
+*.tgz
+
+.cursor/
+
+# Claude Code local worktrees
+.claude/

bkn_osdk-0.2.1/PKG-INFO

@@ -0,0 +1,600 @@
+Metadata-Version: 2.5
+Name: bkn-osdk
+Version: 0.2.1
+Summary: Generated, read-only ontology SDK for BKN knowledge networks
+Project-URL: Homepage, https://github.com/openbkn-ai/bkn-sdk
+Project-URL: Source, https://github.com/openbkn-ai/bkn-sdk/tree/main/python
+Project-URL: Issues, https://github.com/openbkn-ai/bkn-sdk/issues
+Author: OpenBKN
+License: Apache-2.0
+Keywords: bkn,knowledge-network,ontology,osdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bkn-osdk
+
+*[中文版](README.zh.md)*
+
+A Python SDK for BKN, in two layers.
+
+**The ontology layer** is typed, read-only, and specific to **one** knowledge
+network — generated from that network's schema, the way Palantir's OSDK is:
+
+```python
+from bkn.object_types import People
+
+People.where(People.age > 30).take(10)
+```
+
+**The platform layer** addresses the platform itself: any REST route by path,
+and any tool the deploy publishes by name.
+
+```python
+bkn_osdk.call("/api/agent-observability/v1/traces", query={"limit": 10})
+bkn_osdk.call_tool(ctx, kn_id, "describe_resource", {"resource_id": "…", ...})
+```
+
+The layers are named for what they address, not for how they were built — one
+happens to be generated and the other hand-written, which is an implementation
+fact rather than something a caller reasons about. Both go through the same
+credentials, the same transports, and the same managed turn, so dropping to the
+platform layer for one call and coming back up keeps the evidence on one chain.
+
+This is not a port of the TypeScript SDK. That one wraps eleven backend
+namespaces in HTTP calls, which buys a Python caller nothing that
+`bkn_osdk.call("/api/…")` does not. Generated classes over an ontology cannot be
+replaced by a raw call, which is why they are worth a second language.
+
+**Targets platform 0.1.5.** Payloads are taken as the platform sends them, and
+the 0.1.4 line does not send the same ones — it wraps `get_kn_detail`,
+`list_resources`, `list_skills`, `get_object_types` and `list_knowledge_networks`
+in a `result` key, and serves a `semantic-search` route that 0.1.5 withdrew.
+Reading against an older deploy is possible but is the caller's own adaptation,
+not this SDK's.
+
+## Install
+
+From PyPI. The version follows the SDK release that ships it, in PEP 440
+spelling (`v0.2.1-rc.2` is `0.2.1rc2`); pip skips prereleases unless pinned or
+asked with `--pre`:
+
+```bash
+pip install "bkn-osdk==0.2.1"
+```
+
+Its only dependency is `httpx`, so an image build is one line:
+
+```dockerfile
+RUN pip install --no-cache-dir "bkn-osdk==0.2.1"
+```
+
+A generated package declares the runtime minor line it was built for
+(`REQUIRES_RUNTIME`, `>=0.2,<0.3` by default) and refuses to import under any
+other. Packages generated by the earlier `0.1.0` runtime declare `>=0.1,<0.2`:
+regenerate them with this runtime when upgrading.
+
+To install an unreleased commit instead, the package lives in a subdirectory of
+this repository, which pip addresses directly:
+
+```bash
+pip install "bkn-osdk @ git+https://github.com/openbkn-ai/bkn-sdk@<sha>#subdirectory=python"
+```
+
+**Pin a commit, not a branch.** A direct URL carries no index, so nothing
+resolves a "latest" for you and moving versions means editing that line —
+which is the point. A branch name looks like it saves that edit and does not:
+pip's wheel cache is keyed by URL, so a rebuild against the same branch can
+reinstall the build it already has, reporting success while installing the old
+commit. `direct_url.json` in the installed distribution records which commit
+actually landed.
+
+Where git is not installed — the sandbox image is one such place — the archive
+URL takes the same fragment:
+
+```bash
+pip install "bkn-osdk @ https://github.com/openbkn-ai/bkn-sdk/archive/<sha>.zip#subdirectory=python"
+```
+
+## Generate
+
+```bash
+openbkn auth login https://your-platform      # the CLI owns the credential store
+bkn-osdk generate <kn-id> --out ./bkn
+```
+
+`--out` is the package: Python imports it by that directory's name. The command
+authenticates and fetches the whole schema **before** writing anything, and
+refuses a directory it did not produce, so a mistyped path cannot overwrite
+source. Regenerating an unchanged schema rewrites the same bytes, so a real
+regeneration shows up as a reviewable `git diff`.
+
+```text
+bkn/
+  __init__.py        # KN_ID, BRANCH, OBJECT_TYPES, RELATION_TYPES, METRICS,
+                     #   search(), search_instances()
+  object_types.py    # one class per object type
+  relation_types.py  # relation endpoints and their join columns
+  metrics.py         # one class per metric, with the dimensions it allows
+  _meta.py           # fingerprint, format version, runtime range
+```
+
+Commit the generated package, pin `bkn-osdk~=0.1`, and run `bkn-osdk check` in
+CI: it compares the live schema against the fingerprint and exits non-zero on
+drift, classifying it as *additive* (new object type or property — existing code
+keeps working) or *breaking* (removed, retyped, or rekeyed).
+
+Object-type catalogues may contain summaries. Generation fetches missing object
+properties from each public detail endpoint using the same caller and branch;
+a missing or mismatched detail stops generation instead of silently dropping
+properties. Metric UUIDs starting with digits receive a `Metric` class-name
+prefix; the original ID remains unchanged on requests. Multi-hop traversal keeps
+the starting row's bound connection and caller context unless the call supplies
+an explicit context.
+
+## Credentials
+
+Both commands take `--base-url`, `--token` or `--token-file`, `--user` and
+`--insecure`, which beat the environment and the store. That is what a CI job
+wants, and what lets one Makefile generate from two deploys without editing its
+own environment between the calls:
+
+```bash
+bkn-osdk generate <kn-id> --out ./bkn --base-url https://staging --token-file /run/secrets/bkn
+bkn-osdk check ./bkn --base-url https://staging --token-file -   # or read it from stdin
+```
+
+A token passed as `--token` is visible in `ps` and in shell history; outside a
+local shell, mount it and use `--token-file`.
+
+Nothing is compiled into the generated package: the same KN commonly exists on a
+dev and a prod platform, so it pins only `kn_id` and `branch`. Credentials
+resolve at call time, innermost first:
+
+1. the active `session(...)` scope,
+2. the process default from `bkn_osdk.configure(...)`,
+3. `BKN_TOKEN` / `BKN_BASE_URL`,
+4. `~/.bkn/…/token.json` — the store `openbkn auth login` writes.
+
+```python
+import bkn_osdk
+from bkn_osdk import session
+from bkn.object_types import People
+
+People.take(10)  # notebook: nothing to configure
+
+bkn_osdk.configure(base_url=PROD, token=TOKEN)  # one platform, whole process
+
+with session(token=user_token):  # a scope per request
+    People.take(10)
+```
+
+The scope lives in a `ContextVar`, so threads and asyncio tasks each carry their
+own — a multi-tenant server cannot leak one user's token into another's request.
+
+A stored session refreshes itself when its access token expires mid-process. If
+the platform rotates the refresh token, the replacement is written back to the
+store, because spending the CLI's credential and keeping the new one would force
+a re-login.
+
+## Sign users in to your app
+
+An app that acts as its own users needs an OAuth token per user and has to keep
+it alive. `bkn_osdk.oauth` does the sign-in (PKCE, the loopback callback, the
+code exchange) and the refresh grant, and `configure` / `session` refresh the
+tokens it returns the way they refresh a stored session:
+
+```python
+import bkn_osdk
+from bkn_osdk import oauth
+
+# Once: a public client for the app (or ask an operator for one).
+client = oauth.register_client(PLATFORM, "My app")
+
+# A CLI, desktop app, script or notebook: opens the browser, waits on
+# http://127.0.0.1:8765/callback, exchanges the code.
+tokens = oauth.login(PLATFORM, client_id=client.client_id)
+save(tokens.to_dict())  # keep it; see the caveats below
+
+bkn_osdk.configure(
+    base_url=PLATFORM,
+    tokens=tokens,
+    client_id=client.client_id,  # refresh must name the client the tokens were issued to
+    on_refresh=lambda fresh: save(fresh.to_dict()),
+)
+People.take(10)  # refreshed shortly before expiry and on a 401
+```
+
+A server with many users binds each request's tokens instead; the scope is a
+`ContextVar`, so one user's tokens never reach another's request:
+
+```python
+with bkn_osdk.session(tokens=tokens_for(user), client_id=CLIENT_ID, on_refresh=save_for(user)):
+    People.take(10)
+```
+
+A web app receives the callback in its own handler. Keep the `AuthorizationRequest`
+(it holds the `state` and PKCE verifier) in the user's server-side session:
+
+```python
+req = oauth.authorization_request(PLATFORM, CLIENT_ID, redirect_uri="https://app.example/cb")
+# redirect the browser to req.url; later, in the /cb handler:
+tokens = oauth.exchange_code(PLATFORM, req, code=params["code"], state=params["state"])
+```
+
+On a machine without a browser, `oauth.device_login(PLATFORM)` prints a code to
+approve elsewhere (pass `on_prompt` to show it yourself); it signs in as the
+CLI's `openbkn-sdk` client, which is also `configure`'s default `client_id`.
+`oauth.refresh(PLATFORM, tokens, client_id=…)` is the refresh grant on its own.
+A sign-in that did not happen raises `AuthError`, with `error` and `description`.
+
+Four things to know:
+
+1. **Save the refresh token from every callback.** Each refresh spends the old
+   one and the platform issues a new one; `on_refresh` receives the whole new
+   set. An app that kept only the first must sign the user in again on its next
+   start.
+2. **Never refresh one user's tokens from two processes.** The platform treats a
+   reused refresh token as theft and revokes the whole chain, signing the user
+   out everywhere. One process is safe (concurrent requests share a single
+   refresh); several instances need a shared store with a lock, or one place
+   that does the refreshing.
+3. **A failed refresh means sign in again.** The refresh token expired, was
+   revoked, or the user disconnected the app under connected clients. The
+   request then fails with its original 401 and a hint saying so.
+4. **`login` serves loopback callbacks only.** A web app uses
+   `authorization_request` + `exchange_code` from its own handler, and an
+   operator must allow a non-loopback callback origin for the client.
+   `register_client` raises `AuthError` where the platform has no
+   self-registration (0.2.0 has none; it can also be disabled): use
+   `device_login`, or ask an operator.
+
+## Query
+
+```python
+from decimal import Decimal
+from bkn.object_types import Order
+
+Order.get(10357)  # Order | None
+Order.count()  # respects the filter
+Order.where(Order.order_status == "pending_payment").count()
+Order.where((Order.total_amount > Decimal("10000")) & Order.paid_at.exists()).order_by(
+    Order.total_amount.desc()
+).select(Order.order_no, Order.total_amount).take(20)
+
+for order in Order.iterate(page_size=500):  # cursor paging, or limit/offset on older deploys
+    ...
+
+page = Order.objects().page(limit=100)
+next_page = Order.objects().page(limit=100, cursor=page.next_cursor)  # None on the last page
+```
+
+The current ontology-query contract pages by an opaque cursor: the response's
+`paging.next_cursor` is sent back as `cursor` with the same query, and is `null`
+on the last page. Deploys built before that change (0.1.5 releases in the field)
+return no `paging` block but honour `offset`, so `iterate()` follows the cursor
+where the first response carries one and otherwise falls back to `limit`/`offset`,
+stopping on a short page. `page(offset=...)` still sends `offset`; passing both
+`offset` and `cursor` raises.
+
+`~` negates a filter where the platform can express it: comparison operators
+invert into each other, `in`/`like`/`exist` have paired negatives, and `and`/`or`
+negate by De Morgan. `match` and `knn` have no opposite in the operator enum, so
+`~` on them raises rather than inventing one.
+
+`Order.total_amount` is a `PropertyRef` used to build filters; `order.total_amount`
+is a `Decimal`. One name, two jobs — and both typed, so `People.age > 30` checks
+and `People.name > 30` does not.
+
+Decoding follows the declared type: a `decimal` arrives as a JSON string and
+becomes an exact `Decimal`, a `datetime` keeps its offset. A property the query
+did not return raises rather than reading as `None`.
+
+Three things about the platform's filter grammar are worth knowing, all verified
+against a live deploy:
+
+- `like` semantics belong to the **backing resource**, and the two deploys probed
+  disagree: a Postgres-backed object type read the value as a plain substring
+  (`like("2026")` matched, `like("2026%")` did not), while a Vega-catalog-backed
+  one read it as a SQL pattern (`like("%FIFA%")` matched, `like("FIFA")` did
+  not). The value is sent verbatim; a wrong guess returns zero rows, not an
+  error, so try both against your own object type.
+- `match` is in the operator enum but a Postgres-backed object type answers 500.
+- `limit` is 1–10000, and `total_count` is omitted entirely when nothing matched.
+
+## Aggregate
+
+There is no `sum()` or `group_by()` over an object set, because there is no
+endpoint for one: an instance query takes a condition, a sort, a limit, a cursor (or
+offset) and a property selection, and `need_total` returns a row count. Pulling every row back
+to aggregate client-side would be a lie dressed as an API.
+
+The platform's aggregation surface is published, versioned **Object Metrics V1**.
+The generated class pins a published version and permits only runtime choices
+declared by that definition:
+
+```python
+from bkn.metrics import Gmv
+
+Gmv.query(
+    time={"start": 1751328000000, "end": 1753920000000},  # unix ms
+    group_by=["channel_id"],
+)
+```
+
+`Gmv.__version__` and `Gmv.__dimensions__` come from the published definition.
+An undeclared or ambiguous dimension is refused locally. `start`/`end` must be
+integer Unix milliseconds; old `instant` and `step` fields are not accepted.
+`analysis_dimensions` is retained as a compatibility keyword, but both forms
+send the canonical runtime field `group_by`.
+Without an interaction, the transport is the bare ontology-query request
+`POST …/object-metrics/{metric_id}/data?version=N`. Inside
+`session(traced=True)`, or when the context already carries conversation and
+interaction IDs, it uses Context Loader's managed `query_metric` tool instead.
+The same query fields and generated branch are forwarded, the managed response
+is normalized to the same V1 `model`, `entries`, `status`, and `warnings`
+envelope, and its receipt is accumulated on the interaction. Lifecycle
+`bkn_context` is never added to ontology-query's strict request body. Fixed
+business qualifiers and statistical grain cannot be overridden at query time.
+
+## Traverse
+
+One hop is a filter on the target object type, using the join columns the schema
+declares — no session, no second grammar:
+
+```python
+order = Order.get(10357)
+order.order_user.take(10)  # User.where(User.user_id == order.user_id)
+```
+
+Several hops have to be joined server-side, which rides the REST subgraph
+endpoint — still an ordinary read, no session:
+
+```python
+Order.order_user.then(User.user_address).of(order, step_limit=20)
+```
+
+That endpoint's seed-based form walks *every* relation up to the path length, so
+the requested chain is selected from the paths it reports back, and a `where()`
+on the far end is applied locally (it filters only its starting object type).
+Three hops is its ceiling.
+
+## Evidence
+
+Reads through `session(traced=True)` go over MCP inside one managed interaction —
+opened on the first read, reused, finished on exit — and come back with a
+receipt: its status, evidence durability, the evidence refs, and the business
+refs resolved down to property granularity. That is the slim receipt a
+completed call carries (foundry #1417); Core keeps the full record, read with
+`openbkn trace interactions operations <interaction-id>`. A receipt whose status
+is `failed` raises `ToolError("receipt_failed")`; a `pending` one comes back
+with no value.
+
+```python
+with bkn_osdk.session(traced=True):
+    page = Order.objects().page(limit=10)
+    page.receipt["receipt_status"]
+    page.rows[0].__receipt__  # the same receipt, on each row it accounts for
+```
+
+`order_by` travels to the tool as `sort`; opaque `cursor` continuation also
+stays on MCP and keeps receipts. The tool takes no `need_total` and none of
+the REST query flags (`options(...)`), so a query
+wanting one of those takes the REST path even inside a traced scope — carrying
+the scope's turn, so it is still recorded, but answering without an in-band
+receipt. Untraced reads take REST throughout, which is faster, and carry no
+receipt.
+
+Which calls need a turn is a matter of surface, not of tool. The capability
+surface — the MCP tools and their REST twins under `/kn/` — refuses a
+context-free call: every tool in the catalog bar the two lifecycle ones declares
+`bkn_context` required. So `search`, `search_instances` and any direct
+`call_tool` carry a turn on the first attempt, joining the scope's own where
+there is one and opening a short-lived turn where there is not. The instance
+and subgraph read routes under `ontology-query`, and an untraced metric read,
+serve a bare request and mint nothing. A metric read that already has a turn
+deliberately uses Context Loader's managed tool; it never retries a strict
+ontology-query body with `bkn_context` added.
+
+A caller that already has a turn passes it in without a traced scope, which is
+how the sandbox does it — `BKN_CONVERSATION_ID` and `BKN_INTERACTION_ID` in the
+environment, inherited with no argument passing, and never finished by this SDK
+because it does not own them.
+
+## Search
+
+Search is network-level — its request has no object-type dimension — so it lives
+on the package. It calls the `search_schema` MCP tool, the same one the
+TypeScript SDK calls, and answers with the object, relation, action and metric
+types a question touches:
+
+```python
+import bkn
+
+bkn.search("who owns supply chain")
+bkn.search("orders and their buyers", max_concepts=3, search_scope={"include_action_types": False})
+```
+
+`search_instances` asks the other question — not which types a question touches
+but which rows answer it — over the `search_instance` tool. Recall runs two
+channels, vector and full text, so only properties whose `condition_operations`
+include `match` or `knn` take part and a type with no index contributes nothing:
+
+```python
+bkn.search_instances("Lionel Messi")
+bkn.search_instances("欠款最多的客户", object_types=["customer"], rerank=True)
+```
+
+It is where to start when neither the type name nor the field name is known.
+Once both are, a typed query is cheaper and exact.
+
+## The platform layer
+
+Everything the generated classes do not cover — every other network, every
+capability, every route — is reached here:
+
+```python
+bkn_osdk.call("/api/agent-observability/v1/traces", query={"limit": 10})   # REST, by path
+bkn_osdk.call("/api/safe/v1/me/api-keys")                                 # anything else
+
+ctx = bkn_osdk.resolve_context()
+bkn_osdk.tool_catalog(ctx)                            # what this deploy publishes
+bkn_osdk.call_tool(ctx, kn_id, "run_sql", {"kn_id": kn_id, "sql": …, "bkn_context": …})
+```
+
+`call_tool` is the raw seam: it takes the arguments the catalog declares and
+returns what the tool answered, with no shape of its own — including the
+envelope, which differs by build. Passing a `bkn_context` is the caller's job
+there, and `ensure_interaction` is how to get one:
+
+```python
+from bkn_osdk.lifecycle import ensure_interaction
+
+with ensure_interaction(ctx, kn_id) as turn:
+    arguments = {"kn_id": kn_id, "bkn_context": turn.bkn_context}
+    bkn_osdk.call_tool(ctx, kn_id, "list_skills", arguments)
+```
+
+### Who is calling
+
+`me()` returns the record of the user the current credential belongs to, read
+live from bkn-safe:
+
+```python
+user = bkn_osdk.me()
+user.id, user.account, user.name, user.email, user.telephone
+user.departments, user.roles  # department ids; role names
+```
+
+Inside a Function the credential is the invoking caller's own, so `me()` names
+whoever ran it — for a Function behind an action, the person who triggered the
+action. It is a REST call through `BKN_BASE_URL`. If that is empty in the
+sandbox, it raises `InputError` ("No base URL"), like every other OSDK call;
+if it is set but the sandbox network does not allow the gateway, it fails with
+a connection error.
+
+### Named functions for the capability routes
+
+The context-loader surface — 25 routes under `/api/agent-retrieval/v1/kn/` — is
+also generated, from foundry's own OpenAPI:
+
+```python
+from bkn_osdk import kn
+
+kn.list_resources(KN_ID)
+kn.run_sql(KN_ID, "SELECT COUNT(*) AS n FROM {{d9hff…}}")
+kn.run_cypher(
+    KN_ID,
+    "MATCH (o:order)-[:rel_order_customer]->(c:customer) RETURN c.city AS city, count(*) AS n",
+)
+kn.query_object_instance(KN_ID, "order", limit=10, response_format="json")
+```
+
+Three things the wrapper knows and a raw call does not: **which arguments go in
+the query string** rather than the body (`query_object_instance` and both
+subgraph routes split them, and sending `kn_id` in the body answers
+`Public.NotFound` — "对象不存在" — which reads as a missing object type); which
+arguments are required; and that every route on this surface needs a turn, so
+`bkn_context` is attached rather than being a parameter. `kn_id` is the first
+argument everywhere, because the turn belongs to a network even where the route
+does not send one.
+
+The spec is frozen in `contracts/kn-rest.json` and regenerated by
+`scripts/capture_kn_contract.py`; `bkn_osdk/kn.py` is committed, and a test
+fails if regenerating would change it. `call_tool` remains for the tools with no
+REST twin, and for arguments a route accepts but does not publish.
+
+`search` and `search_instances` are the same thing wrapped by hand.
+[`examples/platform/`](examples/platform) runs the whole surface.
+
+## Examples
+
+Six runnable scripts under [`examples/`](examples): [`credentials.py`](examples/credentials.py)
+(which platform, as whom, and where that was decided), three under `ontology/`
+(explore, query, evidence) and two under `platform/` (the tool surface, the
+sandbox).
+
+Instance and subgraph query options use `ignore_local_index=True` to bypass a
+Table resource local index and read its original source. The default remains
+`False`; full-text and vector conditions require the index and return 400 when
+bypassed. `Page.query_source` reports `"local_index"`, `"source"`, or `None` if no
+resource was queried. It replaces `Page.search_from_index`; the old
+`ignoring_store_cache` option is removed. Upgrade with the matching Foundry #844
+server change and restart cursors created before the upgrade.
+
+The generated `kn.query_object_instance(...)` also replaces `search_after` with
+`cursor`: pass the previous response's opaque `cursor` string unchanged for the
+next page. On the first page, omit `cursor` or pass `cursor=None`. Remove any
+`search_after` argument, including `search_after=None`; that keyword is no longer
+accepted. `cursor` and `offset` are mutually exclusive.
+
+## Upgrades
+
+| What moves | You run | Guard |
+| --- | --- | --- |
+| runtime | `pip install -U bkn-osdk` | `REQUIRES_RUNTIME`, checked at import |
+| KN schema | `bkn-osdk generate` again | `SCHEMA_FINGERPRINT` + `bkn-osdk check` |
+| emitted code shape | regenerate | `FORMAT_VERSION` |
+
+A runtime upgrade never requires regeneration — that is why generated packages
+carry declarations and no logic. `configure(check_schema=True)` adds one
+fingerprint check on the first query, for callers who would rather fail loudly
+than read a stale attribute.
+
+## Not in this release
+
+Writes and action execution, aggregation over an object set (no endpoint exists —
+see above), typed wrappers for the catalog's MCP-only tools — the lifecycle
+pair and the sandbox tools, reachable today only through `call_tool` — an async
+client, and offline generation from a local
+`.bkn` directory. Each has a section in
+[the design](../docs/superpowers/specs/2026-08-11-python-osdk-design.md)
+describing the shape it takes when it lands.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+python -m pytest -q          # unit tests, all offline
+python -m mypy               # strict
+python -m ruff check . && python -m ruff format --check .
+```
+
+Wire behaviour is pinned by exchanges recorded from a live platform under
+`tests/fixtures/`; re-record with `scripts/capture_schema_fixtures.py` and
+`scripts/capture_query_fixtures.py` when a contract moves.
+
+Recorded fixtures cannot notice a route being withdrawn, so there is a live
+suite as well. It generates a package for a real network, type-checks it, reads
+through it and closes a real interaction — and it skips itself unless asked for:
+
+```bash
+BKN_E2E=1 BKN_E2E_KN=ecommerce_ops_bkn_public BKN_BASE_URL=https://your-platform \
+  python -m pytest tests/e2e -q
+```
+
+`BKN_E2E_OBJECT_TYPE` pins the class under test; without it the suite picks a
+populated type that has relations to walk. Credentials resolve as they do for
+any caller, so `openbkn auth login` is enough. Run it against more than one
+deploy: the two this SDK was built against have disagreed about route names,
+metrics, and which reads their data resources can serve.
+
+### Function Trace parent
+
+When the sandbox supplies `BKN_PARENT_OPERATION_ID` together with its conversation
+and interaction IDs, internal reads send it as `bkn_context.parent_operation_id`.
+Each read keeps its own operation and receipt. An explicit override to a different
+turn does not inherit the sandbox's parent. Business functions need no new argument.