ghostlink-client 2.5.0__py3-none-any.whl
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.
- ghostlink_client/__init__.py +24 -0
- ghostlink_client/_sse.py +54 -0
- ghostlink_client/client.py +360 -0
- ghostlink_client/exceptions.py +29 -0
- ghostlink_client/models.py +130 -0
- ghostlink_client/py.typed +0 -0
- ghostlink_client-2.5.0.dist-info/METADATA +133 -0
- ghostlink_client-2.5.0.dist-info/RECORD +11 -0
- ghostlink_client-2.5.0.dist-info/WHEEL +5 -0
- ghostlink_client-2.5.0.dist-info/licenses/LICENSE +21 -0
- ghostlink_client-2.5.0.dist-info/top_level.txt +1 -0
|
@@ -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"
|
ghostlink_client/_sse.py
ADDED
|
@@ -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,11 @@
|
|
|
1
|
+
ghostlink_client/__init__.py,sha256=F6hsO9_X6OXvmW1JxYNHvy7oVeuvSVQBnWut90H_9-4,521
|
|
2
|
+
ghostlink_client/_sse.py,sha256=ZtZJx1C73sCOtKW3FP-i2xTdNFupw_LP3mWnDSp4Hi0,1963
|
|
3
|
+
ghostlink_client/client.py,sha256=SuAHYK1hlht-BtvoycVJcO-j3LALtDh5W8XhtZGDIDk,12291
|
|
4
|
+
ghostlink_client/exceptions.py,sha256=XkU8wN1N-YVnn-lgicaDbB_s-jgPGESqbqxFndGrP1o,860
|
|
5
|
+
ghostlink_client/models.py,sha256=bbXO1Vg1DN-V3oBmRh_Sfrpd_PiY-wYTpFvK-hUoO5o,3618
|
|
6
|
+
ghostlink_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
7
|
+
ghostlink_client-2.5.0.dist-info/licenses/LICENSE,sha256=i76r2F5qQZRW3rBshlL9rnCiYzHzIWcJl6pQGG6cnsM,1079
|
|
8
|
+
ghostlink_client-2.5.0.dist-info/METADATA,sha256=mFasIc-UXYrB_iNtvdt86Qi4Dd2Gqf29NRfcpSvgxD0,4173
|
|
9
|
+
ghostlink_client-2.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
|
|
10
|
+
ghostlink_client-2.5.0.dist-info/top_level.txt,sha256=PDx8p7pKFPbrzstPYlKvbNlpKDIfHoWpN3buIzZ3bIA,17
|
|
11
|
+
ghostlink_client-2.5.0.dist-info/RECORD,,
|
|
@@ -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 @@
|
|
|
1
|
+
ghostlink_client
|