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.
@@ -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)