oxap-sdk 0.1.0a34__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- oxap_sdk-0.1.0a34/.gitignore +65 -0
- oxap_sdk-0.1.0a34/PKG-INFO +123 -0
- oxap_sdk-0.1.0a34/README.md +101 -0
- oxap_sdk-0.1.0a34/pyproject.toml +48 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/__init__.py +195 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/_ids.py +62 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/_oap.py +703 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/auth.py +310 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/binary.py +196 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/client.py +219 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/errors.py +140 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/py.typed +0 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/sync.py +335 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/transport.py +656 -0
- oxap_sdk-0.1.0a34/src/oxap_sdk/types.py +471 -0
- oxap_sdk-0.1.0a34/tests/conftest.py +142 -0
- oxap_sdk-0.1.0a34/tests/fixtures/fake_server.py +167 -0
- oxap_sdk-0.1.0a34/tests/fixtures/usage.py +70 -0
- oxap_sdk-0.1.0a34/tests/test_binary_resolver.py +410 -0
- oxap_sdk-0.1.0a34/tests/test_catalog_absence.py +182 -0
- oxap_sdk-0.1.0a34/tests/test_distribution.py +16 -0
- oxap_sdk-0.1.0a34/tests/test_exports.py +19 -0
- oxap_sdk-0.1.0a34/tests/test_idle_timeout.py +113 -0
- oxap_sdk-0.1.0a34/tests/test_ids.py +47 -0
- oxap_sdk-0.1.0a34/tests/test_oap_wire.py +299 -0
- oxap_sdk-0.1.0a34/tests/test_real_binary.py +247 -0
- oxap_sdk-0.1.0a34/tests/test_sync.py +205 -0
- oxap_sdk-0.1.0a34/tests/test_transport.py +393 -0
- oxap_sdk-0.1.0a34/tests/test_usage.py +101 -0
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# OS files
|
|
2
|
+
.DS_Store
|
|
3
|
+
Thumbs.db
|
|
4
|
+
|
|
5
|
+
# Editor / IDE
|
|
6
|
+
*.swp
|
|
7
|
+
*.swo
|
|
8
|
+
*~
|
|
9
|
+
.vscode/
|
|
10
|
+
.idea/
|
|
11
|
+
*.sublime-project
|
|
12
|
+
*.sublime-workspace
|
|
13
|
+
|
|
14
|
+
# Node.js (package.json present)
|
|
15
|
+
node_modules/
|
|
16
|
+
dist/
|
|
17
|
+
typescript/dist/
|
|
18
|
+
npm-debug.log*
|
|
19
|
+
yarn-debug.log*
|
|
20
|
+
yarn-error.log*
|
|
21
|
+
|
|
22
|
+
# Zig build artifacts
|
|
23
|
+
zig-cache/
|
|
24
|
+
zig-out/
|
|
25
|
+
.zig-cache/
|
|
26
|
+
zig/zig-pkg/
|
|
27
|
+
*.o
|
|
28
|
+
*.a
|
|
29
|
+
*.so
|
|
30
|
+
*.dylib
|
|
31
|
+
*.dll
|
|
32
|
+
*.exe
|
|
33
|
+
|
|
34
|
+
# Rust build artifacts
|
|
35
|
+
rust/target/
|
|
36
|
+
|
|
37
|
+
# Temporary files
|
|
38
|
+
tmp/
|
|
39
|
+
|
|
40
|
+
# Environment / secrets
|
|
41
|
+
.env
|
|
42
|
+
.env.*
|
|
43
|
+
.oapx/
|
|
44
|
+
.oxap/
|
|
45
|
+
.makai/
|
|
46
|
+
|
|
47
|
+
# TUI PTY harness output (scripts/tui-pty-driver.py)
|
|
48
|
+
tui-pty-out/
|
|
49
|
+
|
|
50
|
+
# Python bytecode and test/type caches
|
|
51
|
+
scripts/__pycache__/
|
|
52
|
+
__pycache__/
|
|
53
|
+
*.py[cod]
|
|
54
|
+
.pytest_cache/
|
|
55
|
+
.mypy_cache/
|
|
56
|
+
.ruff_cache/
|
|
57
|
+
|
|
58
|
+
# Python SDK (python/)
|
|
59
|
+
.venv/
|
|
60
|
+
venv/
|
|
61
|
+
*.egg-info/
|
|
62
|
+
python/build/
|
|
63
|
+
python/dist/
|
|
64
|
+
|
|
65
|
+
/go/nocomment
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: oxap-sdk
|
|
3
|
+
Version: 0.1.0a34
|
|
4
|
+
Summary: Python SDK for the Open Agent Protocol project's runtime, over its stdio protocol
|
|
5
|
+
Project-URL: Homepage, https://github.com/lsm/oxap
|
|
6
|
+
Project-URL: Source, https://github.com/lsm/oxap/tree/main/sdk/python
|
|
7
|
+
Author: Open Agent Protocol contributors
|
|
8
|
+
License: ISC
|
|
9
|
+
Keywords: llm,oxap_sdk,sdk,stdio,streaming
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: Typing :: Typed
|
|
16
|
+
Requires-Python: >=3.11
|
|
17
|
+
Provides-Extra: dev
|
|
18
|
+
Requires-Dist: mypy>=1.11; extra == 'dev'
|
|
19
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
|
|
20
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# OAP Python SDK
|
|
24
|
+
|
|
25
|
+
`oxap-sdk` (imported as `oxap_sdk`) uses one combined OAP 0.1 stdio endpoint by default:
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
oapx serve agent,provider --stdio
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
It multiplexes `agent-control-core` and `model-provider-core` profiles over that connection. The public `MakaiClient` name remains for source compatibility.
|
|
32
|
+
|
|
33
|
+
The package requires Python 3.11+. Install from a checkout with `pip install ./sdk/python` (it is not yet published to PyPI). It was called `oap-sdk` / `oap_sdk` before; no `oap_sdk` module is kept, so change the import. The `oap-sdk` project on PyPI is unrelated.
|
|
34
|
+
|
|
35
|
+
## Connect and call a provider
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
import asyncio
|
|
39
|
+
import oxap_sdk
|
|
40
|
+
|
|
41
|
+
async def main() -> None:
|
|
42
|
+
async with oxap_sdk.connect() as client:
|
|
43
|
+
model = await client.models.resolve(
|
|
44
|
+
provider_id="anthropic", model_id="claude-sonnet-4-5"
|
|
45
|
+
)
|
|
46
|
+
response = await client.provider.complete(
|
|
47
|
+
model_ref=model.model_ref,
|
|
48
|
+
messages=[{"role": "user", "content": "Write a haiku about streams."}],
|
|
49
|
+
options=oxap_sdk.RunOptions(max_tokens=128),
|
|
50
|
+
)
|
|
51
|
+
print(response.text)
|
|
52
|
+
|
|
53
|
+
asyncio.run(main())
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`client.models` reads the direct provider profile's catalog. Treat returned `model_ref` values as opaque. `client.provider.stream(...)` yields `MessageStart`, content deltas, tool-call events, and `MessageEnd` or `StreamError`. If leaving a stream early, close its async generator so the SDK sends a best-effort cancellation. Direct provider tool definitions map to OAP `input_schema`; tool calls are returned to the caller, not executed in the SDK.
|
|
57
|
+
|
|
58
|
+
## Breaking changes
|
|
59
|
+
|
|
60
|
+
`Usage.input` and `Usage.output` are now `Optional[int]`, defaulting to `None`,
|
|
61
|
+
like the other four counters. Under Decision 0063, `None` means unmeasured;
|
|
62
|
+
an explicit `0` is a measurement. Check `is not None` before arithmetic, and
|
|
63
|
+
choose explicitly whether unknown counts are acceptable for your calculation.
|
|
64
|
+
|
|
65
|
+
Provider and agent unary responses and terminal stream events preserve partial
|
|
66
|
+
usage and any supplied `total`, including the full uint64 maximum
|
|
67
|
+
(`18446744073709551615`). The SDK does not infer a missing total from partial
|
|
68
|
+
counts. An absent usage object remains `None`; `{}` becomes `Usage()` with all
|
|
69
|
+
counters unknown. Present null usage or counters, negative, non-integer and
|
|
70
|
+
out-of-range counts raise `MakaiProtocolError` with code `malformed_response`.
|
|
71
|
+
|
|
72
|
+
Usage counters follow Decision 0065: absence is unknown, `0` is measured zero,
|
|
73
|
+
and accepted counts are exact integers through `18446744073709551615`.
|
|
74
|
+
A raw `-0` count is refused with `MakaiProtocolError(code="malformed_response")`
|
|
75
|
+
on provider and agent unary and streaming APIs. The transport retains that
|
|
76
|
+
noncanonical integer token for the strict usage decoder instead of accepting
|
|
77
|
+
JSON's integer-zero normalization. Usage is checked before content/failure
|
|
78
|
+
frames can be ignored or converted to ordinary provider errors; valid counts
|
|
79
|
+
retain those frames' behavior. Numbers in tool results and other application
|
|
80
|
+
objects retain their ordinary JSON decoding.
|
|
81
|
+
|
|
82
|
+
## Agent sessions
|
|
83
|
+
|
|
84
|
+
`client.agent` uses the agent-control profile. A session has a default model, which can be changed between runs. A per-call `model_ref` overrides that default for one submit. `available_models` reads the session's effective catalog, distinct from direct provider discovery.
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
async with oxap_sdk.connect() as client:
|
|
88
|
+
session = await client.agent.open_session("my-session")
|
|
89
|
+
session_id = session["session_id"]
|
|
90
|
+
catalog = await client.agent.available_models(session_id)
|
|
91
|
+
await client.agent.switch_model(session_id, catalog["models"][0]["id"])
|
|
92
|
+
response = await client.agent.run(
|
|
93
|
+
messages=[{"role": "user", "content": "Hello"}],
|
|
94
|
+
options=oxap_sdk.RunOptions(session_id=session_id),
|
|
95
|
+
)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The optional `client.agent.attach_provider(session_id, {"id": ..., "provider_id": ..., "service_id": ...})` operation attaches an operator-configured OAP provider service to one session. A host without the extension returns typed `unsupported_feature`; there is no implicit attachment. Remote provider services are follow-up work. `switch_model` affects future runs, not an active run.
|
|
99
|
+
|
|
100
|
+
`tools=` on `client.agent.run` or `.stream` are provided to the session at open (`action.tools.provide`), owned by the SDK's participant `sdk`. When the model calls one, the SDK runs its `execute` callback and answers with `action.call.resolve.request`: the returned text as the result, or the exception's message as an error. A tool without `execute` is answered with an error. Against an endpoint that does not advertise `action.tools.provide`, a run with tools raises `unsupported_feature` before the open rather than having its tools ignored, and once a tool has run, an `auto_once` auth failure is raised rather than retried, so the tool is not run twice. `.stream` yields `tool_execution_start` and `tool_execution_end` for every call, the endpoint's own tools included. Agent `RunOptions.reasoning_effort` becomes the session's reasoning level and `.max_tokens` (an integer from 1 to 4294967295, else `invalid_request`) the oapx output limit, both at open, the output limit only on the `oapx.agent` endpoint that reads it (elsewhere `unsupported_feature`); `.temperature` and `reasoning_effort="minimal"` raise `unsupported_feature`, since the agent loop takes no temperature and runs minimal as low. The open also turns off the loop's `request_user_input` tool, which the SDK cannot answer. `.metadata` maps to submit metadata.
|
|
101
|
+
|
|
102
|
+
## Authentication
|
|
103
|
+
|
|
104
|
+
`client.auth.list_providers()` and `.login()` use agent-profile `+auth` on the local stdio connection. The runtime owns credentials; no login code or prompt answer travels in an OAP envelope. A manual-code flow without host-owned input fails with `auth_input_unavailable`. `openai-codex` offers two ways at once: its URL is the ChatGPT sign-in, which returns to a `localhost:1455` callback the runtime listens on, and its instructions also give `https://auth.openai.com/codex/device` and a one-time code for signing in from any other device, which needs device code login turned on in ChatGPT's security settings (or by a workspace admin). Whichever finishes first completes the login. `anthropic` signs in through a browser on the same computer: its URL returns to a `localhost` callback the runtime listens on (macOS and Linux). Where no browser can reach that computer, give the runtime a Claude subscription token, such as one from `claude setup-token`, as `ANTHROPIC_AUTH_TOKEN` in its environment.
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
handlers = oxap_sdk.AuthFlowHandlers(
|
|
108
|
+
on_event=lambda event: print(event.url) if isinstance(event, oxap_sdk.AuthUrlEvent) else None,
|
|
109
|
+
)
|
|
110
|
+
await client.auth.login("anthropic", handlers)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`AuthOptions(auth_retry_policy="auto_once", handlers=handlers)` enables one login and retry after a typed `auth_required` or `credential_*` failure; arbitrary provider-error text never triggers login. For a stream that already emitted user-visible output, the SDK does not replay the call.
|
|
114
|
+
|
|
115
|
+
## Configuration and errors
|
|
116
|
+
|
|
117
|
+
`connect()` accepts `command`, `args`, `cwd`, `env`, a `BinaryResolverOptions`, `auth`, and timeouts in seconds. `response_timeout` bounds each request's reply, the acceptance of a run or inference included, and never a running run; `idle_timeout`, off by default, cancels a run or inference that sends no event for that long. The default args are `("serve", "agent,provider", "--stdio")`. Binary resolution honors `OXAP_SDK_BINARY_PATH` and then the legacy `OAP_SDK_BINARY_PATH`, an explicit path or checksum-verified URL, local `zig-out/bin/oxap` and `zig/zig-out/bin/oxap` before the `oapx` names, then `oxap` and then `oapx` on `PATH`. An `OXAP_SDK_BINARY_URL` likewise outranks `OAP_SDK_BINARY_URL`, and each environment URL takes the checksum written beside it, so a checksum is never borrowed across the two pairs; `checksum_sha256` from the options is the fallback for any URL. The legacy names stay read-compatible.
|
|
118
|
+
|
|
119
|
+
`oxap_sdk.connect_sync()` supplies the same API through a blocking wrapper for scripts; do not call it inside a running event loop. The async and sync clients own their child process and should be closed.
|
|
120
|
+
|
|
121
|
+
Failures are typed as `MakaiStreamError`, `MakaiAuthRequiredError`, `MakaiProtocolError`, or `MakaiAuthError`. Unsupported operations carry code `unsupported_feature`. The `Makai` class names remain for compatibility.
|
|
122
|
+
|
|
123
|
+
Run `uv run --with pytest --with pytest-asyncio pytest -q` from `sdk/python` to run the suite. OAP fake-host tests require no credentials.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# OAP Python SDK
|
|
2
|
+
|
|
3
|
+
`oxap-sdk` (imported as `oxap_sdk`) uses one combined OAP 0.1 stdio endpoint by default:
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
oapx serve agent,provider --stdio
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
It multiplexes `agent-control-core` and `model-provider-core` profiles over that connection. The public `MakaiClient` name remains for source compatibility.
|
|
10
|
+
|
|
11
|
+
The package requires Python 3.11+. Install from a checkout with `pip install ./sdk/python` (it is not yet published to PyPI). It was called `oap-sdk` / `oap_sdk` before; no `oap_sdk` module is kept, so change the import. The `oap-sdk` project on PyPI is unrelated.
|
|
12
|
+
|
|
13
|
+
## Connect and call a provider
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
import asyncio
|
|
17
|
+
import oxap_sdk
|
|
18
|
+
|
|
19
|
+
async def main() -> None:
|
|
20
|
+
async with oxap_sdk.connect() as client:
|
|
21
|
+
model = await client.models.resolve(
|
|
22
|
+
provider_id="anthropic", model_id="claude-sonnet-4-5"
|
|
23
|
+
)
|
|
24
|
+
response = await client.provider.complete(
|
|
25
|
+
model_ref=model.model_ref,
|
|
26
|
+
messages=[{"role": "user", "content": "Write a haiku about streams."}],
|
|
27
|
+
options=oxap_sdk.RunOptions(max_tokens=128),
|
|
28
|
+
)
|
|
29
|
+
print(response.text)
|
|
30
|
+
|
|
31
|
+
asyncio.run(main())
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`client.models` reads the direct provider profile's catalog. Treat returned `model_ref` values as opaque. `client.provider.stream(...)` yields `MessageStart`, content deltas, tool-call events, and `MessageEnd` or `StreamError`. If leaving a stream early, close its async generator so the SDK sends a best-effort cancellation. Direct provider tool definitions map to OAP `input_schema`; tool calls are returned to the caller, not executed in the SDK.
|
|
35
|
+
|
|
36
|
+
## Breaking changes
|
|
37
|
+
|
|
38
|
+
`Usage.input` and `Usage.output` are now `Optional[int]`, defaulting to `None`,
|
|
39
|
+
like the other four counters. Under Decision 0063, `None` means unmeasured;
|
|
40
|
+
an explicit `0` is a measurement. Check `is not None` before arithmetic, and
|
|
41
|
+
choose explicitly whether unknown counts are acceptable for your calculation.
|
|
42
|
+
|
|
43
|
+
Provider and agent unary responses and terminal stream events preserve partial
|
|
44
|
+
usage and any supplied `total`, including the full uint64 maximum
|
|
45
|
+
(`18446744073709551615`). The SDK does not infer a missing total from partial
|
|
46
|
+
counts. An absent usage object remains `None`; `{}` becomes `Usage()` with all
|
|
47
|
+
counters unknown. Present null usage or counters, negative, non-integer and
|
|
48
|
+
out-of-range counts raise `MakaiProtocolError` with code `malformed_response`.
|
|
49
|
+
|
|
50
|
+
Usage counters follow Decision 0065: absence is unknown, `0` is measured zero,
|
|
51
|
+
and accepted counts are exact integers through `18446744073709551615`.
|
|
52
|
+
A raw `-0` count is refused with `MakaiProtocolError(code="malformed_response")`
|
|
53
|
+
on provider and agent unary and streaming APIs. The transport retains that
|
|
54
|
+
noncanonical integer token for the strict usage decoder instead of accepting
|
|
55
|
+
JSON's integer-zero normalization. Usage is checked before content/failure
|
|
56
|
+
frames can be ignored or converted to ordinary provider errors; valid counts
|
|
57
|
+
retain those frames' behavior. Numbers in tool results and other application
|
|
58
|
+
objects retain their ordinary JSON decoding.
|
|
59
|
+
|
|
60
|
+
## Agent sessions
|
|
61
|
+
|
|
62
|
+
`client.agent` uses the agent-control profile. A session has a default model, which can be changed between runs. A per-call `model_ref` overrides that default for one submit. `available_models` reads the session's effective catalog, distinct from direct provider discovery.
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
async with oxap_sdk.connect() as client:
|
|
66
|
+
session = await client.agent.open_session("my-session")
|
|
67
|
+
session_id = session["session_id"]
|
|
68
|
+
catalog = await client.agent.available_models(session_id)
|
|
69
|
+
await client.agent.switch_model(session_id, catalog["models"][0]["id"])
|
|
70
|
+
response = await client.agent.run(
|
|
71
|
+
messages=[{"role": "user", "content": "Hello"}],
|
|
72
|
+
options=oxap_sdk.RunOptions(session_id=session_id),
|
|
73
|
+
)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The optional `client.agent.attach_provider(session_id, {"id": ..., "provider_id": ..., "service_id": ...})` operation attaches an operator-configured OAP provider service to one session. A host without the extension returns typed `unsupported_feature`; there is no implicit attachment. Remote provider services are follow-up work. `switch_model` affects future runs, not an active run.
|
|
77
|
+
|
|
78
|
+
`tools=` on `client.agent.run` or `.stream` are provided to the session at open (`action.tools.provide`), owned by the SDK's participant `sdk`. When the model calls one, the SDK runs its `execute` callback and answers with `action.call.resolve.request`: the returned text as the result, or the exception's message as an error. A tool without `execute` is answered with an error. Against an endpoint that does not advertise `action.tools.provide`, a run with tools raises `unsupported_feature` before the open rather than having its tools ignored, and once a tool has run, an `auto_once` auth failure is raised rather than retried, so the tool is not run twice. `.stream` yields `tool_execution_start` and `tool_execution_end` for every call, the endpoint's own tools included. Agent `RunOptions.reasoning_effort` becomes the session's reasoning level and `.max_tokens` (an integer from 1 to 4294967295, else `invalid_request`) the oapx output limit, both at open, the output limit only on the `oapx.agent` endpoint that reads it (elsewhere `unsupported_feature`); `.temperature` and `reasoning_effort="minimal"` raise `unsupported_feature`, since the agent loop takes no temperature and runs minimal as low. The open also turns off the loop's `request_user_input` tool, which the SDK cannot answer. `.metadata` maps to submit metadata.
|
|
79
|
+
|
|
80
|
+
## Authentication
|
|
81
|
+
|
|
82
|
+
`client.auth.list_providers()` and `.login()` use agent-profile `+auth` on the local stdio connection. The runtime owns credentials; no login code or prompt answer travels in an OAP envelope. A manual-code flow without host-owned input fails with `auth_input_unavailable`. `openai-codex` offers two ways at once: its URL is the ChatGPT sign-in, which returns to a `localhost:1455` callback the runtime listens on, and its instructions also give `https://auth.openai.com/codex/device` and a one-time code for signing in from any other device, which needs device code login turned on in ChatGPT's security settings (or by a workspace admin). Whichever finishes first completes the login. `anthropic` signs in through a browser on the same computer: its URL returns to a `localhost` callback the runtime listens on (macOS and Linux). Where no browser can reach that computer, give the runtime a Claude subscription token, such as one from `claude setup-token`, as `ANTHROPIC_AUTH_TOKEN` in its environment.
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
handlers = oxap_sdk.AuthFlowHandlers(
|
|
86
|
+
on_event=lambda event: print(event.url) if isinstance(event, oxap_sdk.AuthUrlEvent) else None,
|
|
87
|
+
)
|
|
88
|
+
await client.auth.login("anthropic", handlers)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`AuthOptions(auth_retry_policy="auto_once", handlers=handlers)` enables one login and retry after a typed `auth_required` or `credential_*` failure; arbitrary provider-error text never triggers login. For a stream that already emitted user-visible output, the SDK does not replay the call.
|
|
92
|
+
|
|
93
|
+
## Configuration and errors
|
|
94
|
+
|
|
95
|
+
`connect()` accepts `command`, `args`, `cwd`, `env`, a `BinaryResolverOptions`, `auth`, and timeouts in seconds. `response_timeout` bounds each request's reply, the acceptance of a run or inference included, and never a running run; `idle_timeout`, off by default, cancels a run or inference that sends no event for that long. The default args are `("serve", "agent,provider", "--stdio")`. Binary resolution honors `OXAP_SDK_BINARY_PATH` and then the legacy `OAP_SDK_BINARY_PATH`, an explicit path or checksum-verified URL, local `zig-out/bin/oxap` and `zig/zig-out/bin/oxap` before the `oapx` names, then `oxap` and then `oapx` on `PATH`. An `OXAP_SDK_BINARY_URL` likewise outranks `OAP_SDK_BINARY_URL`, and each environment URL takes the checksum written beside it, so a checksum is never borrowed across the two pairs; `checksum_sha256` from the options is the fallback for any URL. The legacy names stay read-compatible.
|
|
96
|
+
|
|
97
|
+
`oxap_sdk.connect_sync()` supplies the same API through a blocking wrapper for scripts; do not call it inside a running event loop. The async and sync clients own their child process and should be closed.
|
|
98
|
+
|
|
99
|
+
Failures are typed as `MakaiStreamError`, `MakaiAuthRequiredError`, `MakaiProtocolError`, or `MakaiAuthError`. Unsupported operations carry code `unsupported_feature`. The `Makai` class names remain for compatibility.
|
|
100
|
+
|
|
101
|
+
Run `uv run --with pytest --with pytest-asyncio pytest -q` from `sdk/python` to run the suite. OAP fake-host tests require no credentials.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "oxap-sdk"
|
|
7
|
+
version = "0.1.0a34"
|
|
8
|
+
description = "Python SDK for the Open Agent Protocol project's runtime, over its stdio protocol"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = { text = "ISC" }
|
|
12
|
+
authors = [{ name = "Open Agent Protocol contributors" }]
|
|
13
|
+
keywords = ["oxap_sdk", "sdk", "streaming", "llm", "stdio"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Programming Language :: Python :: 3.11",
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Programming Language :: Python :: 3.13",
|
|
20
|
+
"Typing :: Typed",
|
|
21
|
+
]
|
|
22
|
+
dependencies = []
|
|
23
|
+
|
|
24
|
+
[project.optional-dependencies]
|
|
25
|
+
dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.11"]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
Homepage = "https://github.com/lsm/oxap"
|
|
29
|
+
Source = "https://github.com/lsm/oxap/tree/main/sdk/python"
|
|
30
|
+
|
|
31
|
+
[tool.hatch.build.targets.wheel]
|
|
32
|
+
packages = ["src/oxap_sdk"]
|
|
33
|
+
|
|
34
|
+
[tool.hatch.build.targets.sdist]
|
|
35
|
+
include = ["src/oxap_sdk", "tests", "README.md", "pyproject.toml"]
|
|
36
|
+
|
|
37
|
+
[tool.pytest.ini_options]
|
|
38
|
+
testpaths = ["tests"]
|
|
39
|
+
asyncio_mode = "auto"
|
|
40
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
41
|
+
markers = [
|
|
42
|
+
"real_binary: needs OAP_SDK_BINARY_PATH pointing at a built oapx runtime",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[tool.mypy]
|
|
46
|
+
python_version = "3.11"
|
|
47
|
+
strict = true
|
|
48
|
+
files = ["src/oxap_sdk", "tests"]
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
"""OAP Python SDK with source-compatible Makai class names.
|
|
2
|
+
|
|
3
|
+
Starts ``oapx serve agent,provider --stdio`` by default and exposes four
|
|
4
|
+
namespaces over profiled OAP 0.1 newline-delimited JSON:
|
|
5
|
+
|
|
6
|
+
``client.auth``
|
|
7
|
+
List auth providers and run interactive logins. Token material stays in
|
|
8
|
+
the runtime and is never returned to callers.
|
|
9
|
+
``client.models``
|
|
10
|
+
Discover models. ``model_ref`` values are opaque handles -- pass them
|
|
11
|
+
through unchanged.
|
|
12
|
+
``client.provider``
|
|
13
|
+
Direct provider completions (``complete``) and streaming (``stream``).
|
|
14
|
+
``client.agent``
|
|
15
|
+
Agent sessions and runs. Client-executed tools are rejected explicitly
|
|
16
|
+
until the OAP endpoint offers ``+control-tools``.
|
|
17
|
+
|
|
18
|
+
Quick start::
|
|
19
|
+
|
|
20
|
+
import asyncio
|
|
21
|
+
import oxap_sdk
|
|
22
|
+
|
|
23
|
+
async def main() -> None:
|
|
24
|
+
async with oxap_sdk.connect() as client:
|
|
25
|
+
model = await client.models.resolve(
|
|
26
|
+
provider_id="anthropic",
|
|
27
|
+
api="anthropic-messages",
|
|
28
|
+
model_id="claude-sonnet-4-5",
|
|
29
|
+
)
|
|
30
|
+
response = await client.provider.complete(
|
|
31
|
+
model_ref=model.model_ref,
|
|
32
|
+
messages=[{"role": "user", "content": "Write a haiku about streams."}],
|
|
33
|
+
options=oxap_sdk.RunOptions(max_tokens=128),
|
|
34
|
+
)
|
|
35
|
+
print(response.text)
|
|
36
|
+
|
|
37
|
+
asyncio.run(main())
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
from __future__ import annotations
|
|
41
|
+
|
|
42
|
+
from .auth import AuthApi
|
|
43
|
+
from .binary import BinaryResolverOptions, resolve_makai_binary
|
|
44
|
+
from .client import AuthOptions, MakaiClient, connect
|
|
45
|
+
from .errors import (
|
|
46
|
+
MakaiAuthError,
|
|
47
|
+
MakaiAuthErrorKind,
|
|
48
|
+
MakaiAuthRequiredError,
|
|
49
|
+
MakaiError,
|
|
50
|
+
MakaiProtocolError,
|
|
51
|
+
MakaiStreamError,
|
|
52
|
+
MakaiStreamErrorKind,
|
|
53
|
+
)
|
|
54
|
+
from ._oap import AgentApi, ModelsApi, ProviderApi
|
|
55
|
+
from .sync import SyncMakaiClient, connect_sync
|
|
56
|
+
from .transport import Frame, FrameRoute, StdioTransport
|
|
57
|
+
from .types import (
|
|
58
|
+
AgentEnd,
|
|
59
|
+
AgentStart,
|
|
60
|
+
AgentStreamEvent,
|
|
61
|
+
AssistantMessage,
|
|
62
|
+
AuthErrorEvent,
|
|
63
|
+
AuthEvent,
|
|
64
|
+
AuthKind,
|
|
65
|
+
AuthEventHandler,
|
|
66
|
+
AuthFlowHandlers,
|
|
67
|
+
AuthProgressEvent,
|
|
68
|
+
AuthPromptEvent,
|
|
69
|
+
AuthRetryPolicy,
|
|
70
|
+
AuthStatus,
|
|
71
|
+
AuthSuccessEvent,
|
|
72
|
+
AuthUrlEvent,
|
|
73
|
+
ChatMessage,
|
|
74
|
+
CompletionResponse,
|
|
75
|
+
Content,
|
|
76
|
+
ContentPart,
|
|
77
|
+
ImageContentPart,
|
|
78
|
+
UrlImageContentPart,
|
|
79
|
+
ListModelsResponse,
|
|
80
|
+
MessageEnd,
|
|
81
|
+
MessageStart,
|
|
82
|
+
ModelCapability,
|
|
83
|
+
ModelDescriptor,
|
|
84
|
+
ModelLifecycle,
|
|
85
|
+
ModelSource,
|
|
86
|
+
ProviderAuthInfo,
|
|
87
|
+
ProviderStreamEvent,
|
|
88
|
+
ReasoningEffort,
|
|
89
|
+
Role,
|
|
90
|
+
RunOptions,
|
|
91
|
+
StreamError,
|
|
92
|
+
TextContentPart,
|
|
93
|
+
TextDelta,
|
|
94
|
+
ThinkingContentPart,
|
|
95
|
+
ThinkingDelta,
|
|
96
|
+
ToolCall,
|
|
97
|
+
ToolCallContentPart,
|
|
98
|
+
ToolContext,
|
|
99
|
+
ToolDefinition,
|
|
100
|
+
ToolExecutionEnd,
|
|
101
|
+
ToolExecutionStart,
|
|
102
|
+
ToolExecutor,
|
|
103
|
+
ToolResult,
|
|
104
|
+
ToolResultContentPart,
|
|
105
|
+
TurnEnd,
|
|
106
|
+
TurnStart,
|
|
107
|
+
Usage,
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
__version__ = "0.1.0a34"
|
|
111
|
+
|
|
112
|
+
__all__ = [
|
|
113
|
+
"__version__",
|
|
114
|
+
# Entry points
|
|
115
|
+
"connect",
|
|
116
|
+
"connect_sync",
|
|
117
|
+
"MakaiClient",
|
|
118
|
+
"SyncMakaiClient",
|
|
119
|
+
"AuthOptions",
|
|
120
|
+
# Namespaces
|
|
121
|
+
"AuthApi",
|
|
122
|
+
"ModelsApi",
|
|
123
|
+
"ProviderApi",
|
|
124
|
+
"AgentApi",
|
|
125
|
+
# Transport
|
|
126
|
+
"StdioTransport",
|
|
127
|
+
"FrameRoute",
|
|
128
|
+
"Frame",
|
|
129
|
+
"BinaryResolverOptions",
|
|
130
|
+
"resolve_makai_binary",
|
|
131
|
+
# Errors
|
|
132
|
+
"MakaiError",
|
|
133
|
+
"MakaiStreamError",
|
|
134
|
+
"MakaiStreamErrorKind",
|
|
135
|
+
"MakaiAuthRequiredError",
|
|
136
|
+
"MakaiProtocolError",
|
|
137
|
+
"MakaiAuthError",
|
|
138
|
+
"MakaiAuthErrorKind",
|
|
139
|
+
# Requests
|
|
140
|
+
"ChatMessage",
|
|
141
|
+
"Role",
|
|
142
|
+
"Content",
|
|
143
|
+
"ContentPart",
|
|
144
|
+
"TextContentPart",
|
|
145
|
+
"ThinkingContentPart",
|
|
146
|
+
"ImageContentPart",
|
|
147
|
+
"UrlImageContentPart",
|
|
148
|
+
"ToolCallContentPart",
|
|
149
|
+
"ToolResultContentPart",
|
|
150
|
+
"ToolDefinition",
|
|
151
|
+
"ToolExecutor",
|
|
152
|
+
"ToolContext",
|
|
153
|
+
"ToolResult",
|
|
154
|
+
"RunOptions",
|
|
155
|
+
"AuthRetryPolicy",
|
|
156
|
+
"ReasoningEffort",
|
|
157
|
+
# Responses
|
|
158
|
+
"CompletionResponse",
|
|
159
|
+
"AssistantMessage",
|
|
160
|
+
"Usage",
|
|
161
|
+
# Provider events
|
|
162
|
+
"ProviderStreamEvent",
|
|
163
|
+
"MessageStart",
|
|
164
|
+
"TextDelta",
|
|
165
|
+
"ThinkingDelta",
|
|
166
|
+
"ToolCall",
|
|
167
|
+
"MessageEnd",
|
|
168
|
+
"StreamError",
|
|
169
|
+
# Agent events
|
|
170
|
+
"AgentStreamEvent",
|
|
171
|
+
"AgentStart",
|
|
172
|
+
"AgentEnd",
|
|
173
|
+
"TurnStart",
|
|
174
|
+
"TurnEnd",
|
|
175
|
+
"ToolExecutionStart",
|
|
176
|
+
"ToolExecutionEnd",
|
|
177
|
+
# Models
|
|
178
|
+
"ModelDescriptor",
|
|
179
|
+
"ListModelsResponse",
|
|
180
|
+
"ModelCapability",
|
|
181
|
+
"ModelLifecycle",
|
|
182
|
+
"ModelSource",
|
|
183
|
+
"AuthKind",
|
|
184
|
+
"AuthStatus",
|
|
185
|
+
# Auth
|
|
186
|
+
"ProviderAuthInfo",
|
|
187
|
+
"AuthFlowHandlers",
|
|
188
|
+
"AuthEventHandler",
|
|
189
|
+
"AuthEvent",
|
|
190
|
+
"AuthUrlEvent",
|
|
191
|
+
"AuthPromptEvent",
|
|
192
|
+
"AuthProgressEvent",
|
|
193
|
+
"AuthSuccessEvent",
|
|
194
|
+
"AuthErrorEvent",
|
|
195
|
+
]
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Protocol identifier generation.
|
|
2
|
+
|
|
3
|
+
The Makai protocols use two wire formats for identifiers (spec §3.1):
|
|
4
|
+
|
|
5
|
+
* ``session_id`` -- a 21-character alphanumeric NanoID.
|
|
6
|
+
* ``message_id`` / ``stream_id`` / ``flow_id`` -- a 26-character uppercase
|
|
7
|
+
Crockford Base32 ULID.
|
|
8
|
+
|
|
9
|
+
Both are generated here so the SDK has no third-party runtime dependencies.
|
|
10
|
+
Identifiers are opaque to callers; nothing outside this module parses them.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import os
|
|
16
|
+
import secrets
|
|
17
|
+
import time
|
|
18
|
+
|
|
19
|
+
__all__ = ["new_nano_id", "new_ulid", "is_nano_id", "is_ulid"]
|
|
20
|
+
|
|
21
|
+
_NANO_ID_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
|
|
22
|
+
_NANO_ID_LENGTH = 21
|
|
23
|
+
|
|
24
|
+
_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
|
|
25
|
+
_ULID_LENGTH = 26
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def new_nano_id() -> str:
|
|
29
|
+
"""Return a fresh 21-character alphanumeric NanoID."""
|
|
30
|
+
return "".join(secrets.choice(_NANO_ID_ALPHABET) for _ in range(_NANO_ID_LENGTH))
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def new_ulid() -> str:
|
|
34
|
+
"""Return a fresh 26-character uppercase Crockford Base32 ULID.
|
|
35
|
+
|
|
36
|
+
The leading 48 bits encode milliseconds since the Unix epoch, so ULIDs
|
|
37
|
+
minted in the same process sort roughly by creation time. The trailing 80
|
|
38
|
+
bits come from the OS CSPRNG.
|
|
39
|
+
"""
|
|
40
|
+
timestamp_ms = int(time.time() * 1000) & ((1 << 48) - 1)
|
|
41
|
+
randomness = int.from_bytes(os.urandom(10), "big")
|
|
42
|
+
value = (timestamp_ms << 80) | randomness
|
|
43
|
+
|
|
44
|
+
out = [""] * _ULID_LENGTH
|
|
45
|
+
for index in range(_ULID_LENGTH - 1, -1, -1):
|
|
46
|
+
out[index] = _CROCKFORD[value & 0x1F]
|
|
47
|
+
value >>= 5
|
|
48
|
+
return "".join(out)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def is_nano_id(value: str) -> bool:
|
|
52
|
+
"""Return ``True`` when ``value`` has the ``session_id`` wire shape."""
|
|
53
|
+
if len(value) != _NANO_ID_LENGTH:
|
|
54
|
+
return False
|
|
55
|
+
return all(char.isascii() and char.isalnum() for char in value)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def is_ulid(value: str) -> bool:
|
|
59
|
+
"""Return ``True`` when ``value`` has the ULID wire shape."""
|
|
60
|
+
if len(value) != _ULID_LENGTH:
|
|
61
|
+
return False
|
|
62
|
+
return all(char in _CROCKFORD for char in value)
|