Metadata-Version: 2.5
Name: tungsten-runtime
Version: 0.1.3
Summary: Runtime for Python SDKs generated by tungsten: transport, retries, idempotency, diagnostic error envelopes, previews and pagination.
Project-URL: Homepage, https://github.com/pboachie/tungsten
Project-URL: Repository, https://github.com/pboachie/tungsten
Project-URL: Issues, https://github.com/pboachie/tungsten/issues
Author: Prince Boachie
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,mcp,openapi,sdk,tungsten
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: async-timeout<6,>=4.0.3; python_version < '3.11'
Requires-Dist: httpx<1,>=0.27
Requires-Dist: sniffio>=1.3
Requires-Dist: typing-extensions>=4.6
Description-Content-Type: text/markdown

# tungsten-runtime (Python)

Runtime support for SDKs generated by [Tungsten](https://github.com/pboachie/tungsten).

## Install from source

From the repository root, with an interpreter satisfying `requires-python` in
`runtimes/python/pyproject.toml`:

```sh
python -m pip install ./runtimes/python
```

For generated clients, set `targets.python.runtime_path` to this runtime
checkout when using uv, or install the runtime and generated SDK explicitly.
The package includes `py.typed`; generated models support Pydantic and
`models: dataclasses`. See the root README for interpreter compatibility
options. `ClientCore` is synchronous; `AsyncClientCore` uses asyncio.

## Shared contract

Generated clients use the runtime for request validation, authentication,
idempotency keys, confirmation previews, bounded retries, verification,
pagination, macros and server-sent events where the input API declares them.
Calls return a typed result or a diagnostic envelope describing recovery;
unknown outcomes never justify blindly repeating a mutation. The API remains
responsible for authorization and server-side idempotency.

## Limits

Stream `collect(max_bytes=..., max_ms=...)` accepts optional byte and time budgets. Setting
either defaults the other to 4 MiB or 60 seconds. The byte count uses UTF-8
JSON for the event values, excluding SSE framing. A limit closes the stream
and returns a nonretryable error with only the admitted events as `partial`.
Calling `collect()` with no arguments preserves unbounded collection.

Set `ClientOptions.max_response_bytes` to opt into an ordinary-response byte cap;
a call option with the same name overrides it. The value must be a positive
safe integer (at most 9007199254740991); unset keeps the existing unbounded
behavior. Content-Length is checked before reading, and actual bytes are
counted even without that header. Overflow closes the body and returns
`UNEXPECTED_RESPONSE` with code `RESPONSE_TOO_LARGE` and `retryable: never`.
A mutation may have taken effect: inspect API state before retrying. The cap
does not limit a successful SSE stream; use its event and collection limits.

Default idempotency and OAuth token state are in memory. A
`FileIdempotencyStore` is available for durable idempotency keys; it does not
store OAuth tokens. Applications own persistence, permissions and lifecycle.

No runtime ships a file-backed OAuth token store. Provide an application-owned
token-store implementation when tokens must survive process restarts; protect
stored credentials and avoid logging them. Registry publication and package
availability are separate from building this source checkout.

## License

Apache-2.0; see the packaged LICENSE. The compiler is licensed separately
under AGPL-3.0-only.
