ghostlink-client 2.5.0__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,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ghostlink contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: ghostlink-client
3
+ Version: 2.5.0
4
+ Summary: Python client for the Ghostlink Studio API: OpenAI-compatible chat/completions/embeddings, plus native token-streaming chat, workers, metrics, and settings.
5
+ Author: Ghostlink contributors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/rwilliamspbg-ops/Ghostlink
8
+ Project-URL: Documentation, https://rwilliamspbg-ops.github.io/Ghostlink/
9
+ Project-URL: Repository, https://github.com/rwilliamspbg-ops/Ghostlink
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Typing :: Typed
16
+ Requires-Python: >=3.9
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: requests>=2.28
20
+ Provides-Extra: test
21
+ Requires-Dist: pytest>=7; extra == "test"
22
+ Requires-Dist: responses>=0.23; extra == "test"
23
+ Dynamic: license-file
24
+
25
+ # ghostlink-client
26
+
27
+ Python client for a [Ghostlink](https://github.com/rwilliamspbg-ops/Ghostlink) Studio API server — the OpenAI-compatible REST endpoints (`/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`, `/v1/models`) plus Ghostlink's native `/api/*` surface (workers, sessions, settings, metrics, and real token-by-token streaming chat).
28
+
29
+ ## Install
30
+
31
+ ```bash
32
+ pip install -e ./sdks/python
33
+ ```
34
+
35
+ (Not yet published to PyPI — install from a local checkout or a Git URL.)
36
+
37
+ ## Quick start
38
+
39
+ ```python
40
+ from ghostlink_client import GhostlinkClient
41
+
42
+ client = GhostlinkClient("http://127.0.0.1:8003", api_key="<your api key>")
43
+
44
+ resp = client.chat.completions.create(
45
+ model="llama3.2:3b",
46
+ messages=[{"role": "user", "content": "Say hello in one sentence."}],
47
+ )
48
+ print(resp.content)
49
+ ```
50
+
51
+ The API key is the one Ghostlink generates on first run (printed at startup, persisted to `api_key.txt` by default — see `GHOSTLINK_API_KEY_PATH`).
52
+
53
+ ## OpenAI-compatible endpoints
54
+
55
+ ```python
56
+ # Chat
57
+ resp = client.chat.completions.create(model="llama3.2:3b", messages=[...])
58
+
59
+ # Legacy text completion
60
+ resp = client.completions.create(model="llama3.2:3b", prompt="Once upon a time")
61
+ print(resp.text)
62
+
63
+ # Embeddings
64
+ resp = client.embeddings.create(model="nomic-embed-text", input="hello world")
65
+
66
+ # List models
67
+ for m in client.list_models():
68
+ print(m.id)
69
+ ```
70
+
71
+ ## Real streaming chat
72
+
73
+ `/v1/chat/completions` accepts a `stream` field but Ghostlink doesn't act on it yet — real token-by-token streaming is only available today through Ghostlink Studio's native chat endpoint:
74
+
75
+ ```python
76
+ for chunk in client.stream_chat("Tell me a short story"):
77
+ if chunk.error:
78
+ print(f"\n[error: {chunk.token}]")
79
+ elif not chunk.done:
80
+ print(chunk.token, end="", flush=True)
81
+ ```
82
+
83
+ ## Cluster, metrics, settings
84
+
85
+ ```python
86
+ client.workers.list()
87
+ client.workers.discover() # UDP broadcast + mDNS sweep
88
+ client.workers.connect("192.168.1.42", 8003)
89
+
90
+ client.metrics() # JSON snapshot
91
+ client.metrics_prometheus() # Prometheus exposition format
92
+
93
+ client.settings.get()
94
+ client.settings.update(inference_backend="ollama")
95
+ ```
96
+
97
+ ## Error handling
98
+
99
+ ```python
100
+ from ghostlink_client import GhostlinkAPIError, GhostlinkAuthError, GhostlinkConnectionError
101
+
102
+ try:
103
+ client.chat.completions.create(model="x", messages=[])
104
+ except GhostlinkAuthError as err:
105
+ print("bad or missing API key:", err)
106
+ except GhostlinkAPIError as err:
107
+ print(f"server rejected the request: HTTP {err.status_code}: {err.message}")
108
+ except GhostlinkConnectionError as err:
109
+ print("could not reach the server:", err)
110
+ ```
111
+
112
+ ## Context manager
113
+
114
+ ```python
115
+ with GhostlinkClient("http://127.0.0.1:8003", api_key=key) as client:
116
+ client.health()
117
+ ```
118
+
119
+ ## Custom inference backends
120
+
121
+ If the server has a custom backend plugin registered (see `backend_plugin.rs` / `GHOSTLINK_OPENAI_COMPAT_BASE_URL` in the main project), select it the same way as any built-in backend:
122
+
123
+ ```python
124
+ client.settings.update(inference_backend="my_custom_backend")
125
+ resp = client.chat.completions.create(model="anything", messages=[...])
126
+ ```
127
+
128
+ ## Development
129
+
130
+ ```bash
131
+ pip install -e ".[test]"
132
+ pytest
133
+ ```
@@ -0,0 +1,109 @@
1
+ # ghostlink-client
2
+
3
+ Python client for a [Ghostlink](https://github.com/rwilliamspbg-ops/Ghostlink) Studio API server — the OpenAI-compatible REST endpoints (`/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`, `/v1/models`) plus Ghostlink's native `/api/*` surface (workers, sessions, settings, metrics, and real token-by-token streaming chat).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pip install -e ./sdks/python
9
+ ```
10
+
11
+ (Not yet published to PyPI — install from a local checkout or a Git URL.)
12
+
13
+ ## Quick start
14
+
15
+ ```python
16
+ from ghostlink_client import GhostlinkClient
17
+
18
+ client = GhostlinkClient("http://127.0.0.1:8003", api_key="<your api key>")
19
+
20
+ resp = client.chat.completions.create(
21
+ model="llama3.2:3b",
22
+ messages=[{"role": "user", "content": "Say hello in one sentence."}],
23
+ )
24
+ print(resp.content)
25
+ ```
26
+
27
+ The API key is the one Ghostlink generates on first run (printed at startup, persisted to `api_key.txt` by default — see `GHOSTLINK_API_KEY_PATH`).
28
+
29
+ ## OpenAI-compatible endpoints
30
+
31
+ ```python
32
+ # Chat
33
+ resp = client.chat.completions.create(model="llama3.2:3b", messages=[...])
34
+
35
+ # Legacy text completion
36
+ resp = client.completions.create(model="llama3.2:3b", prompt="Once upon a time")
37
+ print(resp.text)
38
+
39
+ # Embeddings
40
+ resp = client.embeddings.create(model="nomic-embed-text", input="hello world")
41
+
42
+ # List models
43
+ for m in client.list_models():
44
+ print(m.id)
45
+ ```
46
+
47
+ ## Real streaming chat
48
+
49
+ `/v1/chat/completions` accepts a `stream` field but Ghostlink doesn't act on it yet — real token-by-token streaming is only available today through Ghostlink Studio's native chat endpoint:
50
+
51
+ ```python
52
+ for chunk in client.stream_chat("Tell me a short story"):
53
+ if chunk.error:
54
+ print(f"\n[error: {chunk.token}]")
55
+ elif not chunk.done:
56
+ print(chunk.token, end="", flush=True)
57
+ ```
58
+
59
+ ## Cluster, metrics, settings
60
+
61
+ ```python
62
+ client.workers.list()
63
+ client.workers.discover() # UDP broadcast + mDNS sweep
64
+ client.workers.connect("192.168.1.42", 8003)
65
+
66
+ client.metrics() # JSON snapshot
67
+ client.metrics_prometheus() # Prometheus exposition format
68
+
69
+ client.settings.get()
70
+ client.settings.update(inference_backend="ollama")
71
+ ```
72
+
73
+ ## Error handling
74
+
75
+ ```python
76
+ from ghostlink_client import GhostlinkAPIError, GhostlinkAuthError, GhostlinkConnectionError
77
+
78
+ try:
79
+ client.chat.completions.create(model="x", messages=[])
80
+ except GhostlinkAuthError as err:
81
+ print("bad or missing API key:", err)
82
+ except GhostlinkAPIError as err:
83
+ print(f"server rejected the request: HTTP {err.status_code}: {err.message}")
84
+ except GhostlinkConnectionError as err:
85
+ print("could not reach the server:", err)
86
+ ```
87
+
88
+ ## Context manager
89
+
90
+ ```python
91
+ with GhostlinkClient("http://127.0.0.1:8003", api_key=key) as client:
92
+ client.health()
93
+ ```
94
+
95
+ ## Custom inference backends
96
+
97
+ If the server has a custom backend plugin registered (see `backend_plugin.rs` / `GHOSTLINK_OPENAI_COMPAT_BASE_URL` in the main project), select it the same way as any built-in backend:
98
+
99
+ ```python
100
+ client.settings.update(inference_backend="my_custom_backend")
101
+ resp = client.chat.completions.create(model="anything", messages=[...])
102
+ ```
103
+
104
+ ## Development
105
+
106
+ ```bash
107
+ pip install -e ".[test]"
108
+ pytest
109
+ ```
@@ -0,0 +1,24 @@
1
+ """Python client SDK for the Ghostlink Studio API."""
2
+
3
+ from .client import GhostlinkClient
4
+ from .exceptions import (
5
+ GhostlinkAPIError,
6
+ GhostlinkAuthError,
7
+ GhostlinkConnectionError,
8
+ GhostlinkError,
9
+ )
10
+ from .models import ChatCompletion, Completion, Model, StreamChunk
11
+
12
+ __all__ = [
13
+ "GhostlinkClient",
14
+ "GhostlinkError",
15
+ "GhostlinkAPIError",
16
+ "GhostlinkAuthError",
17
+ "GhostlinkConnectionError",
18
+ "ChatCompletion",
19
+ "Completion",
20
+ "Model",
21
+ "StreamChunk",
22
+ ]
23
+
24
+ __version__ = "0.1.0"
@@ -0,0 +1,54 @@
1
+ """Minimal Server-Sent Events parser for `requests`' `iter_lines()` output.
2
+
3
+ Ghostlink's streaming endpoint (`/api/inference/chat` with `stream: true`)
4
+ sends unnamed SSE events — each a single `data: {json}` line followed by a
5
+ blank line — so this parser only needs to handle the `data:` field, but
6
+ follows the SSE spec generally (multiple `data:` lines per event are
7
+ joined with `\n`, comment lines starting with `:` are ignored) rather than
8
+ assuming that shape, so it keeps working if the server ever splits a
9
+ payload across lines.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ from typing import Any, Dict, Iterable, Iterator, Optional, Union
16
+
17
+
18
+ def iter_sse_json(lines: Iterable[Union[bytes, str]]) -> Iterator[Dict[str, Any]]:
19
+ """Decodes an SSE line stream into one dict per event's `data:` payload.
20
+
21
+ A payload that isn't valid JSON is silently skipped rather than raised —
22
+ a keep-alive comment or a non-JSON control line is valid SSE, not a
23
+ client-side bug.
24
+ """
25
+ data_lines = []
26
+
27
+ def flush() -> Optional[Dict[str, Any]]:
28
+ if not data_lines:
29
+ return None
30
+ payload = "\n".join(data_lines)
31
+ data_lines.clear()
32
+ try:
33
+ decoded = json.loads(payload)
34
+ except json.JSONDecodeError:
35
+ return None
36
+ return decoded if isinstance(decoded, dict) else None
37
+
38
+ for raw_line in lines:
39
+ line = raw_line.decode("utf-8") if isinstance(raw_line, bytes) else raw_line
40
+ if line == "":
41
+ decoded = flush()
42
+ if decoded is not None:
43
+ yield decoded
44
+ continue
45
+ if line.startswith(":"):
46
+ continue
47
+ if line.startswith("data:"):
48
+ data_lines.append(line[len("data:") :].lstrip(" "))
49
+ # event:/id:/retry: fields are ignored — the server only ever sends
50
+ # unnamed data-only events today.
51
+
52
+ decoded = flush()
53
+ if decoded is not None:
54
+ yield decoded
@@ -0,0 +1,360 @@
1
+ """Client for a Ghostlink Studio API server.
2
+
3
+ Wraps both the OpenAI-compatible REST surface (`/v1/chat/completions`,
4
+ `/v1/completions`, `/v1/embeddings`, `/v1/models`) and Ghostlink's native
5
+ `/api/*` surface (workers, sessions, settings, metrics, and real
6
+ token-by-token streaming chat via `/api/inference/chat`).
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence, Union
12
+
13
+ import requests
14
+
15
+ from ._sse import iter_sse_json
16
+ from .exceptions import (
17
+ GhostlinkAPIError,
18
+ GhostlinkAuthError,
19
+ GhostlinkConnectionError,
20
+ )
21
+ from .models import ChatCompletion, Completion, Model, StreamChunk
22
+
23
+ __all__ = ["GhostlinkClient"]
24
+
25
+ DEFAULT_TIMEOUT = 30.0
26
+
27
+
28
+ def _add_optional(payload: Dict[str, Any], **fields: Any) -> None:
29
+ for key, value in fields.items():
30
+ if value is not None:
31
+ payload[key] = value
32
+
33
+
34
+ def _extract_error_message(body: Any) -> Optional[str]:
35
+ if isinstance(body, dict):
36
+ error = body.get("error")
37
+ if isinstance(error, dict):
38
+ return error.get("message")
39
+ if isinstance(error, str):
40
+ return error
41
+ return None
42
+
43
+
44
+ class _ChatCompletions:
45
+ def __init__(self, client: "GhostlinkClient") -> None:
46
+ self._client = client
47
+
48
+ def create(
49
+ self,
50
+ *,
51
+ model: str,
52
+ messages: Sequence[Mapping[str, Any]],
53
+ temperature: Optional[float] = None,
54
+ top_p: Optional[float] = None,
55
+ top_k: Optional[int] = None,
56
+ penalty: Optional[float] = None,
57
+ max_tokens: Optional[int] = None,
58
+ ) -> ChatCompletion:
59
+ """`POST /v1/chat/completions` — OpenAI-compatible, non-streaming."""
60
+ payload: Dict[str, Any] = {"model": model, "messages": list(messages)}
61
+ _add_optional(
62
+ payload,
63
+ temperature=temperature,
64
+ top_p=top_p,
65
+ top_k=top_k,
66
+ penalty=penalty,
67
+ max_tokens=max_tokens,
68
+ )
69
+ data = self._client._request("POST", "/v1/chat/completions", json=payload)
70
+ return ChatCompletion.from_dict(data)
71
+
72
+
73
+ class _Chat:
74
+ def __init__(self, client: "GhostlinkClient") -> None:
75
+ self.completions = _ChatCompletions(client)
76
+
77
+
78
+ class _Completions:
79
+ def __init__(self, client: "GhostlinkClient") -> None:
80
+ self._client = client
81
+
82
+ def create(
83
+ self,
84
+ *,
85
+ model: str,
86
+ prompt: str,
87
+ temperature: Optional[float] = None,
88
+ top_p: Optional[float] = None,
89
+ top_k: Optional[int] = None,
90
+ penalty: Optional[float] = None,
91
+ max_tokens: Optional[int] = None,
92
+ ) -> Completion:
93
+ """`POST /v1/completions` — OpenAI's legacy completions endpoint."""
94
+ payload: Dict[str, Any] = {"model": model, "prompt": prompt}
95
+ _add_optional(
96
+ payload,
97
+ temperature=temperature,
98
+ top_p=top_p,
99
+ top_k=top_k,
100
+ penalty=penalty,
101
+ max_tokens=max_tokens,
102
+ )
103
+ data = self._client._request("POST", "/v1/completions", json=payload)
104
+ return Completion.from_dict(data)
105
+
106
+
107
+ class _Embeddings:
108
+ def __init__(self, client: "GhostlinkClient") -> None:
109
+ self._client = client
110
+
111
+ def create(self, *, model: str, input: Union[str, Sequence[str]]) -> Dict[str, Any]:
112
+ """`POST /v1/embeddings`."""
113
+ return self._client._request(
114
+ "POST", "/v1/embeddings", json={"model": model, "input": input}
115
+ )
116
+
117
+
118
+ class _Models:
119
+ def __init__(self, client: "GhostlinkClient") -> None:
120
+ self._client = client
121
+
122
+ def list(self) -> List[Model]:
123
+ """`GET /v1/models`."""
124
+ data = self._client._request("GET", "/v1/models")
125
+ return [Model.from_dict(m) for m in data.get("data", [])]
126
+
127
+
128
+ class _Workers:
129
+ def __init__(self, client: "GhostlinkClient") -> None:
130
+ self._client = client
131
+
132
+ def list(self) -> List[Dict[str, Any]]:
133
+ return self._client._request("GET", "/api/workers").get("workers", [])
134
+
135
+ def discover(self) -> Dict[str, Any]:
136
+ """Triggers a UDP-broadcast + mDNS discovery sweep and registers
137
+ any peers found. See `GET /api/workers/discover`."""
138
+ return self._client._request("GET", "/api/workers/discover")
139
+
140
+ def connect(self, host: str, port: int) -> Dict[str, Any]:
141
+ return self._client._request(
142
+ "POST", "/api/workers/connect", json={"host": host, "port": port}
143
+ )
144
+
145
+ def add(self, **fields: Any) -> Dict[str, Any]:
146
+ return self._client._request("POST", "/api/workers/add", json=fields)
147
+
148
+ def disconnect(self, worker_id: str) -> Dict[str, Any]:
149
+ return self._client._request("POST", f"/api/workers/{worker_id}/disconnect")
150
+
151
+
152
+ class _Sessions:
153
+ def __init__(self, client: "GhostlinkClient") -> None:
154
+ self._client = client
155
+
156
+ def list(self) -> List[Dict[str, Any]]:
157
+ return self._client._request("GET", "/api/sessions").get("sessions", [])
158
+
159
+
160
+ class _Settings:
161
+ def __init__(self, client: "GhostlinkClient") -> None:
162
+ self._client = client
163
+
164
+ def get(self) -> Dict[str, Any]:
165
+ return self._client._request("GET", "/api/settings")
166
+
167
+ def update(self, **fields: Any) -> Dict[str, Any]:
168
+ return self._client._request("POST", "/api/settings", json=fields)
169
+
170
+ def reset(self) -> Dict[str, Any]:
171
+ return self._client._request("POST", "/api/settings/reset")
172
+
173
+
174
+ class GhostlinkClient:
175
+ """Client for a Ghostlink Studio API server.
176
+
177
+ Example:
178
+ >>> client = GhostlinkClient("http://127.0.0.1:8003", api_key="...")
179
+ >>> resp = client.chat.completions.create(
180
+ ... model="llama3.2:3b",
181
+ ... messages=[{"role": "user", "content": "hello"}],
182
+ ... )
183
+ >>> print(resp.content)
184
+
185
+ Use as a context manager to close the underlying HTTP session:
186
+ >>> with GhostlinkClient(url, api_key=key) as client:
187
+ ... client.health()
188
+ """
189
+
190
+ def __init__(
191
+ self,
192
+ base_url: str,
193
+ api_key: Optional[str] = None,
194
+ timeout: float = DEFAULT_TIMEOUT,
195
+ session: Optional[requests.Session] = None,
196
+ ) -> None:
197
+ self.base_url = base_url.rstrip("/")
198
+ self.api_key = api_key
199
+ self.timeout = timeout
200
+ self._session = session or requests.Session()
201
+
202
+ self.chat = _Chat(self)
203
+ self.completions = _Completions(self)
204
+ self.embeddings = _Embeddings(self)
205
+ self.models = _Models(self)
206
+ self.workers = _Workers(self)
207
+ self.sessions = _Sessions(self)
208
+ self.settings = _Settings(self)
209
+
210
+ def __enter__(self) -> "GhostlinkClient":
211
+ return self
212
+
213
+ def __exit__(self, *exc_info: object) -> None:
214
+ self.close()
215
+
216
+ def close(self) -> None:
217
+ self._session.close()
218
+
219
+ def _headers(self) -> Dict[str, str]:
220
+ headers = {"Content-Type": "application/json"}
221
+ if self.api_key:
222
+ headers["Authorization"] = f"Bearer {self.api_key}"
223
+ return headers
224
+
225
+ def _raise_for_status(self, resp: requests.Response) -> None:
226
+ if resp.status_code < 400:
227
+ return
228
+ body: Any
229
+ try:
230
+ body = resp.json()
231
+ except ValueError:
232
+ body = resp.text
233
+ message = _extract_error_message(body) or resp.reason or "request failed"
234
+ if resp.status_code in (401, 403):
235
+ raise GhostlinkAuthError(resp.status_code, message, body)
236
+ raise GhostlinkAPIError(resp.status_code, message, body)
237
+
238
+ def _request(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
239
+ url = f"{self.base_url}{path}"
240
+ try:
241
+ resp = self._session.request(
242
+ method, url, headers=self._headers(), timeout=self.timeout, **kwargs
243
+ )
244
+ except requests.exceptions.RequestException as err:
245
+ raise GhostlinkConnectionError(f"failed to reach {url}: {err}") from err
246
+
247
+ self._raise_for_status(resp)
248
+
249
+ if not resp.content:
250
+ return {}
251
+ return resp.json()
252
+
253
+ def health(self) -> Dict[str, Any]:
254
+ """`GET /health` — unauthenticated liveness/version/backend info."""
255
+ return self._request("GET", "/health")
256
+
257
+ def metrics(self) -> Dict[str, Any]:
258
+ """`GET /api/metrics` — JSON metrics snapshot. See
259
+ `metrics_prometheus` for the Prometheus-exposition-format sibling."""
260
+ return self._request("GET", "/api/metrics")
261
+
262
+ def metrics_prometheus(self) -> str:
263
+ """`GET /metrics` — the same snapshot as `metrics()`, formatted for
264
+ a Prometheus scrape config instead of JSON."""
265
+ url = f"{self.base_url}/metrics"
266
+ try:
267
+ resp = self._session.get(url, headers=self._headers(), timeout=self.timeout)
268
+ except requests.exceptions.RequestException as err:
269
+ raise GhostlinkConnectionError(f"failed to reach {url}: {err}") from err
270
+ self._raise_for_status(resp)
271
+ return resp.text
272
+
273
+ def list_models(self) -> List[Model]:
274
+ """Convenience alias for ``self.models.list()``."""
275
+ return self.models.list()
276
+
277
+ def studio_chat(
278
+ self,
279
+ message: str,
280
+ *,
281
+ messages: Optional[Sequence[Mapping[str, str]]] = None,
282
+ model: Optional[str] = None,
283
+ temperature: Optional[float] = None,
284
+ top_p: Optional[float] = None,
285
+ top_k: Optional[int] = None,
286
+ penalty: Optional[float] = None,
287
+ max_tokens: Optional[int] = None,
288
+ ) -> Dict[str, Any]:
289
+ """Non-streaming call to Ghostlink Studio's native chat endpoint
290
+ (`POST /api/inference/chat`) — richer than the OpenAI-compatible
291
+ routes (session bookkeeping, MCP tool results, live metrics in the
292
+ response), but Ghostlink-specific rather than portable. Use
293
+ `stream_chat` for real token-by-token streaming.
294
+ """
295
+ payload: Dict[str, Any] = {"message": message}
296
+ if messages is not None:
297
+ payload["messages"] = list(messages)
298
+ _add_optional(
299
+ payload,
300
+ model=model,
301
+ temperature=temperature,
302
+ top_p=top_p,
303
+ top_k=top_k,
304
+ penalty=penalty,
305
+ max_tokens=max_tokens,
306
+ )
307
+ return self._request("POST", "/api/inference/chat", json=payload)
308
+
309
+ def stream_chat(
310
+ self,
311
+ message: str,
312
+ *,
313
+ messages: Optional[Sequence[Mapping[str, str]]] = None,
314
+ model: Optional[str] = None,
315
+ temperature: Optional[float] = None,
316
+ top_p: Optional[float] = None,
317
+ top_k: Optional[int] = None,
318
+ penalty: Optional[float] = None,
319
+ max_tokens: Optional[int] = None,
320
+ ) -> Iterator[StreamChunk]:
321
+ """Real token-by-token streaming via `POST /api/inference/chat`
322
+ (`stream: true`) over Server-Sent Events. Yields one `StreamChunk`
323
+ per token as the model produces it; the final chunk has
324
+ `done=True`. This is the only endpoint with genuine incremental
325
+ streaming today — the OpenAI-compatible `/v1/chat/completions`
326
+ accepts a `stream` field but does not yet act on it.
327
+
328
+ Example:
329
+ >>> for chunk in client.stream_chat("tell me a story"):
330
+ ... if not chunk.done:
331
+ ... print(chunk.token, end="", flush=True)
332
+ """
333
+ payload: Dict[str, Any] = {"message": message, "stream": True}
334
+ if messages is not None:
335
+ payload["messages"] = list(messages)
336
+ _add_optional(
337
+ payload,
338
+ model=model,
339
+ temperature=temperature,
340
+ top_p=top_p,
341
+ top_k=top_k,
342
+ penalty=penalty,
343
+ max_tokens=max_tokens,
344
+ )
345
+ url = f"{self.base_url}/api/inference/chat"
346
+ try:
347
+ resp = self._session.post(
348
+ url,
349
+ headers=self._headers(),
350
+ json=payload,
351
+ timeout=self.timeout,
352
+ stream=True,
353
+ )
354
+ except requests.exceptions.RequestException as err:
355
+ raise GhostlinkConnectionError(f"failed to reach {url}: {err}") from err
356
+
357
+ self._raise_for_status(resp)
358
+
359
+ for payload_dict in iter_sse_json(resp.iter_lines(decode_unicode=True)):
360
+ yield StreamChunk.from_dict(payload_dict)
@@ -0,0 +1,29 @@
1
+ """Exception hierarchy for the Ghostlink client."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+
8
+ class GhostlinkError(Exception):
9
+ """Base class for all errors raised by this client."""
10
+
11
+
12
+ class GhostlinkConnectionError(GhostlinkError):
13
+ """The client could not reach the Ghostlink server at all — DNS
14
+ failure, connection refused, or a timeout before any response arrived.
15
+ """
16
+
17
+
18
+ class GhostlinkAPIError(GhostlinkError):
19
+ """The server responded with a non-2xx status code."""
20
+
21
+ def __init__(self, status_code: int, message: str, body: Any = None) -> None:
22
+ super().__init__(f"HTTP {status_code}: {message}")
23
+ self.status_code = status_code
24
+ self.message = message
25
+ self.body = body
26
+
27
+
28
+ class GhostlinkAuthError(GhostlinkAPIError):
29
+ """401/403 — missing, invalid, or expired bearer token."""
@@ -0,0 +1,130 @@
1
+ """Typed response wrappers.
2
+
3
+ These are thin, permissive views over the JSON the server returns — every
4
+ field is read with a default rather than a required key, so a minor server
5
+ version skew (a new field added, one renamed) doesn't raise inside the
6
+ client. The original decoded JSON is always available on `.raw` for
7
+ anything not modeled explicitly here.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from dataclasses import dataclass, field
13
+ from typing import Any, Dict, List, Optional
14
+
15
+
16
+ @dataclass
17
+ class ChatChoice:
18
+ index: int
19
+ message: Dict[str, Any]
20
+ finish_reason: Optional[str] = None
21
+
22
+ @classmethod
23
+ def from_dict(cls, data: Dict[str, Any]) -> "ChatChoice":
24
+ return cls(
25
+ index=data.get("index", 0),
26
+ message=data.get("message", {}) or {},
27
+ finish_reason=data.get("finish_reason"),
28
+ )
29
+
30
+
31
+ @dataclass
32
+ class ChatCompletion:
33
+ id: str
34
+ object: str
35
+ created: int
36
+ model: str
37
+ choices: List[ChatChoice]
38
+ raw: Dict[str, Any] = field(repr=False, default_factory=dict)
39
+
40
+ @property
41
+ def content(self) -> str:
42
+ """The first choice's assistant text, or `""` if there are none."""
43
+ if not self.choices:
44
+ return ""
45
+ return self.choices[0].message.get("content", "")
46
+
47
+ @classmethod
48
+ def from_dict(cls, data: Dict[str, Any]) -> "ChatCompletion":
49
+ return cls(
50
+ id=data.get("id", ""),
51
+ object=data.get("object", ""),
52
+ created=data.get("created", 0),
53
+ model=data.get("model", ""),
54
+ choices=[ChatChoice.from_dict(c) for c in data.get("choices", [])],
55
+ raw=data,
56
+ )
57
+
58
+
59
+ @dataclass
60
+ class CompletionChoice:
61
+ text: str
62
+ index: int
63
+ finish_reason: Optional[str] = None
64
+
65
+
66
+ @dataclass
67
+ class Completion:
68
+ id: str
69
+ object: str
70
+ created: int
71
+ model: str
72
+ choices: List[CompletionChoice]
73
+ raw: Dict[str, Any] = field(repr=False, default_factory=dict)
74
+
75
+ @property
76
+ def text(self) -> str:
77
+ return self.choices[0].text if self.choices else ""
78
+
79
+ @classmethod
80
+ def from_dict(cls, data: Dict[str, Any]) -> "Completion":
81
+ return cls(
82
+ id=data.get("id", ""),
83
+ object=data.get("object", ""),
84
+ created=data.get("created", 0),
85
+ model=data.get("model", ""),
86
+ choices=[
87
+ CompletionChoice(
88
+ text=c.get("text", ""),
89
+ index=c.get("index", 0),
90
+ finish_reason=c.get("finish_reason"),
91
+ )
92
+ for c in data.get("choices", [])
93
+ ],
94
+ raw=data,
95
+ )
96
+
97
+
98
+ @dataclass
99
+ class Model:
100
+ id: str
101
+ raw: Dict[str, Any] = field(repr=False, default_factory=dict)
102
+
103
+ @classmethod
104
+ def from_dict(cls, data: Dict[str, Any]) -> "Model":
105
+ return cls(id=data.get("id", ""), raw=data)
106
+
107
+
108
+ @dataclass
109
+ class StreamChunk:
110
+ """One incremental piece of a `/api/inference/chat` streamed response."""
111
+
112
+ token: str = ""
113
+ request_id: str = ""
114
+ session_id: str = ""
115
+ error: bool = False
116
+ done: bool = False
117
+ truncated: bool = False
118
+ raw: Dict[str, Any] = field(repr=False, default_factory=dict)
119
+
120
+ @classmethod
121
+ def from_dict(cls, data: Dict[str, Any]) -> "StreamChunk":
122
+ return cls(
123
+ token=data.get("token", ""),
124
+ request_id=data.get("request_id", ""),
125
+ session_id=data.get("session_id", ""),
126
+ error=bool(data.get("error", False)),
127
+ done=bool(data.get("done", False)),
128
+ truncated=bool(data.get("truncated", False)),
129
+ raw=data,
130
+ )
File without changes
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: ghostlink-client
3
+ Version: 2.5.0
4
+ Summary: Python client for the Ghostlink Studio API: OpenAI-compatible chat/completions/embeddings, plus native token-streaming chat, workers, metrics, and settings.
5
+ Author: Ghostlink contributors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/rwilliamspbg-ops/Ghostlink
8
+ Project-URL: Documentation, https://rwilliamspbg-ops.github.io/Ghostlink/
9
+ Project-URL: Repository, https://github.com/rwilliamspbg-ops/Ghostlink
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Typing :: Typed
16
+ Requires-Python: >=3.9
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: requests>=2.28
20
+ Provides-Extra: test
21
+ Requires-Dist: pytest>=7; extra == "test"
22
+ Requires-Dist: responses>=0.23; extra == "test"
23
+ Dynamic: license-file
24
+
25
+ # ghostlink-client
26
+
27
+ Python client for a [Ghostlink](https://github.com/rwilliamspbg-ops/Ghostlink) Studio API server — the OpenAI-compatible REST endpoints (`/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`, `/v1/models`) plus Ghostlink's native `/api/*` surface (workers, sessions, settings, metrics, and real token-by-token streaming chat).
28
+
29
+ ## Install
30
+
31
+ ```bash
32
+ pip install -e ./sdks/python
33
+ ```
34
+
35
+ (Not yet published to PyPI — install from a local checkout or a Git URL.)
36
+
37
+ ## Quick start
38
+
39
+ ```python
40
+ from ghostlink_client import GhostlinkClient
41
+
42
+ client = GhostlinkClient("http://127.0.0.1:8003", api_key="<your api key>")
43
+
44
+ resp = client.chat.completions.create(
45
+ model="llama3.2:3b",
46
+ messages=[{"role": "user", "content": "Say hello in one sentence."}],
47
+ )
48
+ print(resp.content)
49
+ ```
50
+
51
+ The API key is the one Ghostlink generates on first run (printed at startup, persisted to `api_key.txt` by default — see `GHOSTLINK_API_KEY_PATH`).
52
+
53
+ ## OpenAI-compatible endpoints
54
+
55
+ ```python
56
+ # Chat
57
+ resp = client.chat.completions.create(model="llama3.2:3b", messages=[...])
58
+
59
+ # Legacy text completion
60
+ resp = client.completions.create(model="llama3.2:3b", prompt="Once upon a time")
61
+ print(resp.text)
62
+
63
+ # Embeddings
64
+ resp = client.embeddings.create(model="nomic-embed-text", input="hello world")
65
+
66
+ # List models
67
+ for m in client.list_models():
68
+ print(m.id)
69
+ ```
70
+
71
+ ## Real streaming chat
72
+
73
+ `/v1/chat/completions` accepts a `stream` field but Ghostlink doesn't act on it yet — real token-by-token streaming is only available today through Ghostlink Studio's native chat endpoint:
74
+
75
+ ```python
76
+ for chunk in client.stream_chat("Tell me a short story"):
77
+ if chunk.error:
78
+ print(f"\n[error: {chunk.token}]")
79
+ elif not chunk.done:
80
+ print(chunk.token, end="", flush=True)
81
+ ```
82
+
83
+ ## Cluster, metrics, settings
84
+
85
+ ```python
86
+ client.workers.list()
87
+ client.workers.discover() # UDP broadcast + mDNS sweep
88
+ client.workers.connect("192.168.1.42", 8003)
89
+
90
+ client.metrics() # JSON snapshot
91
+ client.metrics_prometheus() # Prometheus exposition format
92
+
93
+ client.settings.get()
94
+ client.settings.update(inference_backend="ollama")
95
+ ```
96
+
97
+ ## Error handling
98
+
99
+ ```python
100
+ from ghostlink_client import GhostlinkAPIError, GhostlinkAuthError, GhostlinkConnectionError
101
+
102
+ try:
103
+ client.chat.completions.create(model="x", messages=[])
104
+ except GhostlinkAuthError as err:
105
+ print("bad or missing API key:", err)
106
+ except GhostlinkAPIError as err:
107
+ print(f"server rejected the request: HTTP {err.status_code}: {err.message}")
108
+ except GhostlinkConnectionError as err:
109
+ print("could not reach the server:", err)
110
+ ```
111
+
112
+ ## Context manager
113
+
114
+ ```python
115
+ with GhostlinkClient("http://127.0.0.1:8003", api_key=key) as client:
116
+ client.health()
117
+ ```
118
+
119
+ ## Custom inference backends
120
+
121
+ If the server has a custom backend plugin registered (see `backend_plugin.rs` / `GHOSTLINK_OPENAI_COMPAT_BASE_URL` in the main project), select it the same way as any built-in backend:
122
+
123
+ ```python
124
+ client.settings.update(inference_backend="my_custom_backend")
125
+ resp = client.chat.completions.create(model="anything", messages=[...])
126
+ ```
127
+
128
+ ## Development
129
+
130
+ ```bash
131
+ pip install -e ".[test]"
132
+ pytest
133
+ ```
@@ -0,0 +1,16 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ ghostlink_client/__init__.py
5
+ ghostlink_client/_sse.py
6
+ ghostlink_client/client.py
7
+ ghostlink_client/exceptions.py
8
+ ghostlink_client/models.py
9
+ ghostlink_client/py.typed
10
+ ghostlink_client.egg-info/PKG-INFO
11
+ ghostlink_client.egg-info/SOURCES.txt
12
+ ghostlink_client.egg-info/dependency_links.txt
13
+ ghostlink_client.egg-info/requires.txt
14
+ ghostlink_client.egg-info/top_level.txt
15
+ tests/test_client.py
16
+ tests/test_sse.py
@@ -0,0 +1,5 @@
1
+ requests>=2.28
2
+
3
+ [test]
4
+ pytest>=7
5
+ responses>=0.23
@@ -0,0 +1 @@
1
+ ghostlink_client
@@ -0,0 +1,37 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "ghostlink-client"
7
+ version = "2.5.0"
8
+ description = "Python client for the Ghostlink Studio API: OpenAI-compatible chat/completions/embeddings, plus native token-streaming chat, workers, metrics, and settings."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ authors = [{ name = "Ghostlink contributors" }]
12
+ requires-python = ">=3.9"
13
+ dependencies = [
14
+ "requests>=2.28",
15
+ ]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Intended Audience :: Developers",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Operating System :: OS Independent",
22
+ "Typing :: Typed",
23
+ ]
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/rwilliamspbg-ops/Ghostlink"
27
+ Documentation = "https://rwilliamspbg-ops.github.io/Ghostlink/"
28
+ Repository = "https://github.com/rwilliamspbg-ops/Ghostlink"
29
+
30
+ [project.optional-dependencies]
31
+ test = ["pytest>=7", "responses>=0.23"]
32
+
33
+ [tool.setuptools.packages.find]
34
+ include = ["ghostlink_client*"]
35
+
36
+ [tool.setuptools.package-data]
37
+ ghostlink_client = ["py.typed"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,153 @@
1
+ import pytest
2
+ import responses
3
+
4
+ from ghostlink_client import (
5
+ GhostlinkAPIError,
6
+ GhostlinkAuthError,
7
+ GhostlinkClient,
8
+ GhostlinkConnectionError,
9
+ )
10
+
11
+ BASE_URL = "http://127.0.0.1:8003"
12
+
13
+
14
+ @pytest.fixture
15
+ def client():
16
+ with GhostlinkClient(BASE_URL, api_key="test-key") as c:
17
+ yield c
18
+
19
+
20
+ @responses.activate
21
+ def test_chat_completions_create(client):
22
+ responses.add(
23
+ responses.POST,
24
+ f"{BASE_URL}/v1/chat/completions",
25
+ json={
26
+ "id": "chatcmpl-1",
27
+ "object": "chat.completion",
28
+ "created": 123,
29
+ "model": "llama3.2:3b",
30
+ "choices": [
31
+ {
32
+ "index": 0,
33
+ "message": {"role": "assistant", "content": "hi there"},
34
+ "finish_reason": "stop",
35
+ }
36
+ ],
37
+ },
38
+ status=200,
39
+ )
40
+
41
+ resp = client.chat.completions.create(
42
+ model="llama3.2:3b", messages=[{"role": "user", "content": "hello"}]
43
+ )
44
+
45
+ assert resp.content == "hi there"
46
+ assert resp.model == "llama3.2:3b"
47
+ assert responses.calls[0].request.headers["Authorization"] == "Bearer test-key"
48
+
49
+
50
+ @responses.activate
51
+ def test_completions_create(client):
52
+ responses.add(
53
+ responses.POST,
54
+ f"{BASE_URL}/v1/completions",
55
+ json={
56
+ "id": "cmpl-1",
57
+ "object": "text_completion",
58
+ "created": 123,
59
+ "model": "llama3.2:3b",
60
+ "choices": [{"text": "once upon a time", "index": 0, "finish_reason": "stop"}],
61
+ },
62
+ status=200,
63
+ )
64
+
65
+ resp = client.completions.create(model="llama3.2:3b", prompt="Once")
66
+ assert resp.text == "once upon a time"
67
+
68
+
69
+ @responses.activate
70
+ def test_list_models(client):
71
+ responses.add(
72
+ responses.GET,
73
+ f"{BASE_URL}/v1/models",
74
+ json={"data": [{"id": "llama3.2:3b"}, {"id": "gemma2:2b"}]},
75
+ status=200,
76
+ )
77
+
78
+ models = client.list_models()
79
+ assert [m.id for m in models] == ["llama3.2:3b", "gemma2:2b"]
80
+
81
+
82
+ @responses.activate
83
+ def test_auth_error_raises_ghostlink_auth_error(client):
84
+ responses.add(
85
+ responses.POST,
86
+ f"{BASE_URL}/v1/chat/completions",
87
+ json={"error": {"message": "missing bearer token", "type": "invalid_request_error"}},
88
+ status=401,
89
+ )
90
+
91
+ with pytest.raises(GhostlinkAuthError) as exc_info:
92
+ client.chat.completions.create(model="x", messages=[{"role": "user", "content": "hi"}])
93
+
94
+ assert exc_info.value.status_code == 401
95
+ assert "missing bearer token" in str(exc_info.value)
96
+
97
+
98
+ @responses.activate
99
+ def test_bad_request_raises_ghostlink_api_error(client):
100
+ responses.add(
101
+ responses.POST,
102
+ f"{BASE_URL}/v1/chat/completions",
103
+ json={"error": {"message": "messages must not be empty", "type": "invalid_request_error"}},
104
+ status=400,
105
+ )
106
+
107
+ with pytest.raises(GhostlinkAPIError) as exc_info:
108
+ client.chat.completions.create(model="x", messages=[])
109
+
110
+ assert exc_info.value.status_code == 400
111
+ assert "messages must not be empty" in exc_info.value.message
112
+
113
+
114
+ def test_connection_error_raises_ghostlink_connection_error(client):
115
+ # No `responses.activate` — nothing is mocked, so the request against an
116
+ # address nothing is listening on raises requests' own connection error,
117
+ # which the client should wrap.
118
+ unreachable = GhostlinkClient("http://127.0.0.1:1", api_key="k", timeout=1)
119
+ with pytest.raises(GhostlinkConnectionError):
120
+ unreachable.health()
121
+
122
+
123
+ @responses.activate
124
+ def test_health(client):
125
+ responses.add(responses.GET, f"{BASE_URL}/health", json={"status": "healthy"}, status=200)
126
+ assert client.health() == {"status": "healthy"}
127
+
128
+
129
+ @responses.activate
130
+ def test_metrics_prometheus_returns_raw_text(client):
131
+ responses.add(
132
+ responses.GET,
133
+ f"{BASE_URL}/metrics",
134
+ body="# HELP ghostlink_uptime_seconds ...\nghostlink_uptime_seconds 12.5\n",
135
+ status=200,
136
+ content_type="text/plain; version=0.0.4; charset=utf-8",
137
+ )
138
+ text = client.metrics_prometheus()
139
+ assert "ghostlink_uptime_seconds 12.5" in text
140
+
141
+
142
+ @responses.activate
143
+ def test_settings_update(client):
144
+ responses.add(
145
+ responses.POST,
146
+ f"{BASE_URL}/api/settings",
147
+ json={"settings": {"inference_backend": "ollama"}, "status": "ok"},
148
+ status=200,
149
+ )
150
+ result = client.settings.update(inference_backend="ollama")
151
+ assert result["status"] == "ok"
152
+ sent_body = responses.calls[0].request.body
153
+ assert b"ollama" in sent_body
@@ -0,0 +1,66 @@
1
+ from ghostlink_client._sse import iter_sse_json
2
+ from ghostlink_client.models import StreamChunk
3
+
4
+
5
+ def sse_lines(*events):
6
+ """Builds an SSE line stream (as `requests.Response.iter_lines()` would
7
+ yield it) from a list of already-JSON-encoded data payload strings.
8
+ """
9
+ lines = []
10
+ for event in events:
11
+ lines.append(f"data: {event}")
12
+ lines.append("")
13
+ return lines
14
+
15
+
16
+ def test_parses_single_event():
17
+ lines = sse_lines('{"token": "hello", "request_id": "req-1", "session_id": "s1"}')
18
+ events = list(iter_sse_json(lines))
19
+ assert events == [{"token": "hello", "request_id": "req-1", "session_id": "s1"}]
20
+
21
+
22
+ def test_parses_multiple_events_in_order():
23
+ lines = sse_lines(
24
+ '{"token": "hel", "request_id": "req-1", "session_id": "s1"}',
25
+ '{"token": "lo", "request_id": "req-1", "session_id": "s1"}',
26
+ '{"done": true, "request_id": "req-1", "session_id": "s1", "truncated": false}',
27
+ )
28
+ events = list(iter_sse_json(lines))
29
+ assert [e.get("token") for e in events[:2]] == ["hel", "lo"]
30
+ assert events[2]["done"] is True
31
+
32
+
33
+ def test_ignores_comment_lines():
34
+ lines = [": ping", ""] + sse_lines('{"token": "x", "request_id": "r", "session_id": "s"}')
35
+ events = list(iter_sse_json(lines))
36
+ assert len(events) == 1
37
+ assert events[0]["token"] == "x"
38
+
39
+
40
+ def test_skips_invalid_json_payload():
41
+ lines = ["data: not json", ""] + sse_lines('{"token": "ok", "request_id": "r", "session_id": "s"}')
42
+ events = list(iter_sse_json(lines))
43
+ assert len(events) == 1
44
+ assert events[0]["token"] == "ok"
45
+
46
+
47
+ def test_handles_trailing_event_without_final_blank_line():
48
+ lines = ['data: {"token": "x", "request_id": "r", "session_id": "s"}']
49
+ events = list(iter_sse_json(lines))
50
+ assert len(events) == 1
51
+
52
+
53
+ def test_stream_chunk_from_dict_defaults():
54
+ chunk = StreamChunk.from_dict({"token": "hi", "request_id": "r1", "session_id": "s1"})
55
+ assert chunk.token == "hi"
56
+ assert chunk.done is False
57
+ assert chunk.error is False
58
+
59
+
60
+ def test_stream_chunk_from_dict_done_and_error_flags():
61
+ done_chunk = StreamChunk.from_dict({"done": True, "request_id": "r1", "session_id": "s1", "truncated": True})
62
+ assert done_chunk.done is True
63
+ assert done_chunk.truncated is True
64
+
65
+ error_chunk = StreamChunk.from_dict({"token": "[err]", "error": True, "request_id": "r1", "session_id": "s1"})
66
+ assert error_chunk.error is True