Repository Public
1// Code samples shown on the landing page and in the documentation.2// Base URL, model id and key placeholder are fixed by the public contract.34const r = String.raw;56export const BASE_URL = "https://llm.spboucher.ai/v1";7export const MODEL = "maclustr-qwen3";8export const KEY = "YOUR_MACLUSTR_API_KEY";910const PY_CLIENT = r`from openai import OpenAI1112client = OpenAI(13 base_url="https://llm.spboucher.ai/v1",14 api_key="YOUR_MACLUSTR_API_KEY", # read it from the environment in real code15)`;1617const TS_CLIENT = r`import OpenAI from "openai";1819const client = new OpenAI({20 baseURL: "https://llm.spboucher.ai/v1",21 apiKey: "YOUR_MACLUSTR_API_KEY", // read it from process.env in real code22});`;2324const SWIFT_REQUEST = r`func makeRequest(_ body: [String: Any]) throws -> URLRequest {25 var request = URLRequest(url: URL(string: "https://llm.spboucher.ai/v1/chat/completions")!)26 request.httpMethod = "POST"27 request.setValue("Bearer YOUR_MACLUSTR_API_KEY", forHTTPHeaderField: "Authorization")28 request.setValue("application/json", forHTTPHeaderField: "Content-Type")29 request.httpBody = try JSONSerialization.data(withJSONObject: body)30 return request31}`;3233export const SAMPLES = {34 // ------------------------------------------------------------------ basic chat completion35 chat: {36 curl: r`curl https://llm.spboucher.ai/v1/chat/completions \37 -H "Authorization: Bearer YOUR_MACLUSTR_API_KEY" \38 -H "Content-Type: application/json" \39 -d '{40 "model": "maclustr-qwen3",41 "messages": [42 {"role": "system", "content": "You are a concise assistant."},43 {"role": "user", "content": "Explain unified memory in one sentence."}44 ],45 "max_tokens": 25646 }'`,47 python: `${PY_CLIENT}4849response = client.chat.completions.create(50 model="maclustr-qwen3",51 messages=[52 {"role": "system", "content": "You are a concise assistant."},53 {"role": "user", "content": "Explain unified memory in one sentence."},54 ],55 max_tokens=256,56)5758print(response.choices[0].message.content)59print(response.usage.prompt_tokens, response.usage.completion_tokens)`,60 typescript: `${TS_CLIENT}6162const response = await client.chat.completions.create({63 model: "maclustr-qwen3",64 messages: [65 { role: "system", content: "You are a concise assistant." },66 { role: "user", content: "Explain unified memory in one sentence." },67 ],68 max_tokens: 256,69});7071console.log(response.choices[0].message.content);72console.log(response.usage);`,73 swift: r`import Foundation7475struct ChatResponse: Decodable {76 struct Choice: Decodable {77 struct Message: Decodable { let role: String; let content: String? }78 let message: Message79 let finish_reason: String80 }81 struct Usage: Decodable { let prompt_tokens: Int; let completion_tokens: Int }82 let choices: [Choice]83 let usage: Usage84}8586var request = URLRequest(url: URL(string: "https://llm.spboucher.ai/v1/chat/completions")!)87request.httpMethod = "POST"88request.setValue("Bearer YOUR_MACLUSTR_API_KEY", forHTTPHeaderField: "Authorization")89request.setValue("application/json", forHTTPHeaderField: "Content-Type")90request.httpBody = try JSONSerialization.data(withJSONObject: [91 "model": "maclustr-qwen3",92 "messages": [93 ["role": "system", "content": "You are a concise assistant."],94 ["role": "user", "content": "Explain unified memory in one sentence."],95 ],96 "max_tokens": 256,97])9899let (data, response) = try await URLSession.shared.data(for: request)100guard (response as? HTTPURLResponse)?.statusCode == 200 else {101 throw URLError(.badServerResponse) // decode the error envelope here, see "Error Handling"102}103let completion = try JSONDecoder().decode(ChatResponse.self, from: data)104print(completion.choices[0].message.content ?? "")`,105 },106107 // ------------------------------------------------------------------ streaming108 stream: {109 curl: r`curl --no-buffer https://llm.spboucher.ai/v1/chat/completions \110 -H "Authorization: Bearer YOUR_MACLUSTR_API_KEY" \111 -H "Content-Type: application/json" \112 -d '{113 "model": "maclustr-qwen3",114 "messages": [{"role": "user", "content": "Write a haiku about silicon."}],115 "stream": true,116 "stream_options": {"include_usage": true}117 }'`,118 python: `${PY_CLIENT}119120stream = client.chat.completions.create(121 model="maclustr-qwen3",122 messages=[{"role": "user", "content": "Write a haiku about silicon."}],123 stream=True,124 stream_options={"include_usage": True},125)126127for chunk in stream:128 if chunk.usage: # final chunk: choices is empty129 print(f"\\n[{chunk.usage.completion_tokens} completion tokens]")130 for choice in chunk.choices:131 if choice.delta.content:132 print(choice.delta.content, end="", flush=True)`,133 typescript: `${TS_CLIENT}134135const stream = await client.chat.completions.create({136 model: "maclustr-qwen3",137 messages: [{ role: "user", content: "Write a haiku about silicon." }],138 stream: true,139 stream_options: { include_usage: true },140});141142for await (const chunk of stream) {143 const delta = chunk.choices[0]?.delta;144 if (delta?.content) process.stdout.write(delta.content);145 if (chunk.usage) console.log("\\n", chunk.usage); // final chunk: choices is empty146}`,147 swift: r`import Foundation148149struct ChatChunk: Decodable {150 struct Choice: Decodable {151 struct Delta: Decodable { let content: String?; let reasoning_content: String? }152 let delta: Delta153 let finish_reason: String?154 }155 struct Usage: Decodable { let prompt_tokens: Int; let completion_tokens: Int }156 struct StreamError: Decodable, Error { let message: String; let code: String? }157 let choices: [Choice]?158 let usage: Usage?159 let error: StreamError?160}161162var request = URLRequest(url: URL(string: "https://llm.spboucher.ai/v1/chat/completions")!)163request.httpMethod = "POST"164request.setValue("Bearer YOUR_MACLUSTR_API_KEY", forHTTPHeaderField: "Authorization")165request.setValue("application/json", forHTTPHeaderField: "Content-Type")166request.httpBody = try JSONSerialization.data(withJSONObject: [167 "model": "maclustr-qwen3",168 "messages": [["role": "user", "content": "Write a haiku about silicon."]],169 "stream": true,170 "stream_options": ["include_usage": true],171])172173let (bytes, response) = try await URLSession.shared.bytes(for: request)174guard (response as? HTTPURLResponse)?.statusCode == 200 else { throw URLError(.badServerResponse) }175176for try await line in bytes.lines {177 guard line.hasPrefix("data: ") else { continue } // skips ": keepalive" comments178 let payload = String(line.dropFirst(6))179 if payload == "[DONE]" { break }180 let chunk = try JSONDecoder().decode(ChatChunk.self, from: Data(payload.utf8))181 if let error = chunk.error { throw error } // in-stream error event182 if let text = chunk.choices?.first?.delta.content { print(text, terminator: "") }183 if let usage = chunk.usage { print("\n[\(usage.completion_tokens) completion tokens]") }184}`,185 },186187 // ------------------------------------------------------------------ tool calling round trip188 tools: {189 curl: r`# 1. Send the tool definitions. The model answers with tool_calls.190curl https://llm.spboucher.ai/v1/chat/completions \191 -H "Authorization: Bearer YOUR_MACLUSTR_API_KEY" \192 -H "Content-Type: application/json" \193 -d '{194 "model": "maclustr-qwen3",195 "messages": [{"role": "user", "content": "What is the weather in Montreal?"}],196 "tools": [{197 "type": "function",198 "function": {199 "name": "get_weather",200 "description": "Current weather for a city.",201 "parameters": {202 "type": "object",203 "properties": {"city": {"type": "string"}},204 "required": ["city"]205 }206 }207 }],208 "tool_choice": "auto"209 }'210211# 2. Run the tool yourself, then send its result back with the same tool_call_id.212curl https://llm.spboucher.ai/v1/chat/completions \213 -H "Authorization: Bearer YOUR_MACLUSTR_API_KEY" \214 -H "Content-Type: application/json" \215 -d '{216 "model": "maclustr-qwen3",217 "messages": [218 {"role": "user", "content": "What is the weather in Montreal?"},219 {"role": "assistant", "content": null, "tool_calls": [{220 "id": "call_870d56bbcb2e4ce4be7d3431", "type": "function",221 "function": {"name": "get_weather", "arguments": "{\"city\": \"Montreal\"}"}222 }]},223 {"role": "tool", "tool_call_id": "call_870d56bbcb2e4ce4be7d3431",224 "content": "{\"temperature_c\": -4, \"conditions\": \"light snow\"}"}225 ],226 "tools": [{"type": "function", "function": {"name": "get_weather",227 "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]228 }'`,229 python: `import json230${PY_CLIENT}231232tools = [{233 "type": "function",234 "function": {235 "name": "get_weather",236 "description": "Current weather for a city.",237 "parameters": {238 "type": "object",239 "properties": {"city": {"type": "string"}},240 "required": ["city"],241 },242 },243}]244245def get_weather(city: str) -> dict:246 return {"temperature_c": -4, "conditions": "light snow"} # your real implementation247248messages = [{"role": "user", "content": "What is the weather in Montreal?"}]249250while True:251 response = client.chat.completions.create(252 model="maclustr-qwen3", messages=messages, tools=tools, tool_choice="auto",253 )254 message = response.choices[0].message255 if not message.tool_calls:256 print(message.content)257 break258259 messages.append(message) # the assistant turn that carries tool_calls260 for call in message.tool_calls:261 args = json.loads(call.function.arguments)262 result = get_weather(**args)263 messages.append({264 "role": "tool",265 "tool_call_id": call.id,266 "content": json.dumps(result),267 })`,268 typescript: `${TS_CLIENT}269270const tools: OpenAI.ChatCompletionTool[] = [{271 type: "function",272 function: {273 name: "get_weather",274 description: "Current weather for a city.",275 parameters: {276 type: "object",277 properties: { city: { type: "string" } },278 required: ["city"],279 },280 },281}];282283async function getWeather(city: string) {284 return { temperature_c: -4, conditions: "light snow" }; // your real implementation285}286287const messages: OpenAI.ChatCompletionMessageParam[] = [288 { role: "user", content: "What is the weather in Montreal?" },289];290291while (true) {292 const response = await client.chat.completions.create({293 model: "maclustr-qwen3", messages, tools, tool_choice: "auto",294 });295 const message = response.choices[0].message;296 if (!message.tool_calls?.length) {297 console.log(message.content);298 break;299 }300301 messages.push(message); // the assistant turn that carries tool_calls302 for (const call of message.tool_calls) {303 const args = JSON.parse(call.function.arguments);304 const result = await getWeather(args.city);305 messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });306 }307}`,308 swift: `import Foundation309310${SWIFT_REQUEST}311` + r`312let tools: [[String: Any]] = [[313 "type": "function",314 "function": [315 "name": "get_weather",316 "description": "Current weather for a city.",317 "parameters": [318 "type": "object",319 "properties": ["city": ["type": "string"]],320 "required": ["city"],321 ],322 ],323]]324325var messages: [[String: Any]] = [["role": "user", "content": "What is the weather in Montreal?"]]326327while true {328 let request = try makeRequest(["model": "maclustr-qwen3", "messages": messages, "tools": tools, "tool_choice": "auto"])329 let (data, _) = try await URLSession.shared.data(for: request)330 let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]331 let message = (json["choices"] as! [[String: Any]])[0]["message"] as! [String: Any]332333 guard let calls = message["tool_calls"] as? [[String: Any]], !calls.isEmpty else {334 print(message["content"] as? String ?? "")335 break336 }337338 messages.append(message) // the assistant turn that carries tool_calls339 for call in calls {340 let function = call["function"] as! [String: Any]341 let arguments = function["arguments"] as! String // a JSON-encoded string342 print("calling", function["name"] as! String, arguments)343 let result = #"{"temperature_c": -4, "conditions": "light snow"}"# // your real implementation344 messages.append(["role": "tool", "tool_call_id": call["id"] as! String, "content": result])345 }346}`,347 },348349 // ------------------------------------------------------------------ structured outputs350 json: {351 curl: r`curl https://llm.spboucher.ai/v1/chat/completions \352 -H "Authorization: Bearer YOUR_MACLUSTR_API_KEY" \353 -H "Content-Type: application/json" \354 -d '{355 "model": "maclustr-qwen3",356 "messages": [{"role": "user", "content": "Extract: Ada Lovelace, born 1815 in London."}],357 "response_format": {358 "type": "json_schema",359 "json_schema": {360 "name": "person",361 "schema": {362 "type": "object",363 "properties": {364 "name": {"type": "string"},365 "birth_year": {"type": "integer"},366 "city": {"type": "string"}367 },368 "required": ["name", "birth_year", "city"],369 "additionalProperties": false370 }371 }372 }373 }'`,374 python: `import json375import openai376${PY_CLIENT}377378schema = {379 "type": "object",380 "properties": {381 "name": {"type": "string"},382 "birth_year": {"type": "integer"},383 "city": {"type": "string"},384 },385 "required": ["name", "birth_year", "city"],386 "additionalProperties": False,387}388389try:390 response = client.chat.completions.create( # non-streaming: the output is validated391 model="maclustr-qwen3",392 messages=[{"role": "user", "content": "Extract: Ada Lovelace, born 1815 in London."}],393 response_format={"type": "json_schema", "json_schema": {"name": "person", "schema": schema}},394 )395 person = json.loads(response.choices[0].message.content)396 print(person["name"], person["birth_year"])397except openai.UnprocessableEntityError as err: # 422 json_validation_failed398 print("The model could not produce valid JSON:", err)`,399 typescript: `${TS_CLIENT}400401const schema = {402 type: "object",403 properties: {404 name: { type: "string" },405 birth_year: { type: "integer" },406 city: { type: "string" },407 },408 required: ["name", "birth_year", "city"],409 additionalProperties: false,410};411412try {413 const response = await client.chat.completions.create({ // non-streaming: the output is validated414 model: "maclustr-qwen3",415 messages: [{ role: "user", content: "Extract: Ada Lovelace, born 1815 in London." }],416 response_format: { type: "json_schema", json_schema: { name: "person", schema } },417 });418 const person = JSON.parse(response.choices[0].message.content ?? "{}");419 console.log(person.name, person.birth_year);420} catch (err) {421 if (err instanceof OpenAI.UnprocessableEntityError) { // 422 json_validation_failed422 console.error("The model could not produce valid JSON:", err.message);423 } else throw err;424}`,425 swift: `import Foundation426427${SWIFT_REQUEST}428` + r`429struct Person: Decodable { let name: String; let birth_year: Int; let city: String }430431let schema: [String: Any] = [432 "type": "object",433 "properties": [434 "name": ["type": "string"],435 "birth_year": ["type": "integer"],436 "city": ["type": "string"],437 ],438 "required": ["name", "birth_year", "city"],439 "additionalProperties": false,440]441442let request = try makeRequest([443 "model": "maclustr-qwen3",444 "messages": [["role": "user", "content": "Extract: Ada Lovelace, born 1815 in London."]],445 "response_format": ["type": "json_schema", "json_schema": ["name": "person", "schema": schema]],446])447448let (data, response) = try await URLSession.shared.data(for: request)449let status = (response as! HTTPURLResponse).statusCode450guard status == 200 else {451 // 422 with code "json_validation_failed": the model could not produce valid JSON452 throw URLError(.cannotParseResponse)453}454let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]455let message = (json["choices"] as! [[String: Any]])[0]["message"] as! [String: Any]456let person = try JSONDecoder().decode(Person.self, from: Data((message["content"] as! String).utf8))457print(person.name, person.birth_year)`,458 },459460 // ------------------------------------------------------------------ list models461 models: {462 curl: r`curl https://llm.spboucher.ai/v1/models \463 -H "Authorization: Bearer YOUR_MACLUSTR_API_KEY"`,464 python: `${PY_CLIENT}465466for model in client.models.list():467 print(model.id)`,468 typescript: `${TS_CLIENT}469470for await (const model of client.models.list()) {471 console.log(model.id);472}`,473 swift: r`import Foundation474475var request = URLRequest(url: URL(string: "https://llm.spboucher.ai/v1/models")!)476request.setValue("Bearer YOUR_MACLUSTR_API_KEY", forHTTPHeaderField: "Authorization")477478let (data, _) = try await URLSession.shared.data(for: request)479let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]480for model in json["data"] as! [[String: Any]] {481 print(model["id"] as! String, model["context_window"] as! Int)482}`,483 },484485 // ------------------------------------------------------------------ errors and retries486 errors: {487 curl: r`# -i prints the status line and headers (x-request-id, Retry-After, x-ratelimit-*)488curl -i https://llm.spboucher.ai/v1/chat/completions \489 -H "Authorization: Bearer YOUR_MACLUSTR_API_KEY" \490 -H "Content-Type: application/json" \491 -d '{"model": "maclustr-qwen3", "messages": [{"role": "user", "content": "Hello"}]}'492493# Let curl retry transient failures; it honours Retry-After on 429 and 503494curl --retry 4 --retry-max-time 60 https://llm.spboucher.ai/v1/chat/completions \495 -H "Authorization: Bearer YOUR_MACLUSTR_API_KEY" \496 -H "Content-Type: application/json" \497 -d '{"model": "maclustr-qwen3", "messages": [{"role": "user", "content": "Hello"}]}'`,498 python: r`import random499import time500501import openai502from openai import OpenAI503504client = OpenAI(505 base_url="https://llm.spboucher.ai/v1",506 api_key="YOUR_MACLUSTR_API_KEY",507 max_retries=0, # the SDK can also retry for you (default: 2 retries, honours Retry-After)508)509510RETRYABLE = {429, 500, 502, 503, 504}511512def complete(messages, attempts=5):513 for attempt in range(attempts):514 try:515 return client.chat.completions.create(model="maclustr-qwen3", messages=messages)516 except openai.APIStatusError as err:517 print(err.status_code, err.code, err.response.headers.get("x-request-id"))518 if err.status_code not in RETRYABLE or err.code == "insufficient_quota":519 raise # fix the request, the key, or wait for the quota to reset520 if attempt == attempts - 1:521 raise522 retry_after = err.response.headers.get("retry-after")523 delay = float(retry_after) if retry_after else min(30, 2 ** attempt) * random.uniform(0.5, 1)524 time.sleep(delay)525 except openai.APIConnectionError:526 if attempt == attempts - 1:527 raise528 time.sleep(min(30, 2 ** attempt) * random.uniform(0.5, 1))`,529 typescript: r`import OpenAI from "openai";530531const client = new OpenAI({532 baseURL: "https://llm.spboucher.ai/v1",533 apiKey: "YOUR_MACLUSTR_API_KEY",534 maxRetries: 0, // the SDK can also retry for you (default: 2 retries, honours Retry-After)535});536537const RETRYABLE = new Set([429, 500, 502, 503, 504]);538const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));539540async function complete(messages: OpenAI.ChatCompletionMessageParam[], attempts = 5) {541 for (let attempt = 0; ; attempt++) {542 try {543 return await client.chat.completions.create({ model: "maclustr-qwen3", messages });544 } catch (err) {545 if (!(err instanceof OpenAI.APIError) || err.status === undefined) throw err;546 console.error(err.status, err.code, err.requestID);547 const last = attempt === attempts - 1;548 if (!RETRYABLE.has(err.status) || err.code === "insufficient_quota" || last) throw err;549 const retryAfter = Number(err.headers?.get("retry-after")); // openai v5+ (Headers object)550 const backoff = Math.min(30, 2 ** attempt) * (0.5 + Math.random() / 2);551 await sleep(1000 * (retryAfter > 0 ? retryAfter : backoff));552 }553 }554}`,555 swift: r`import Foundation556557struct APIError: Error, Decodable {558 let message: String559 let type: String560 let code: String?561 let param: String?562 let request_id: String?563}564struct ErrorEnvelope: Decodable { let error: APIError }565566struct RequestFailure: Error {567 let status: Int568 let error: APIError?569 let retryAfter: TimeInterval?570}571572func send(_ request: URLRequest, attempts: Int = 5) async throws -> Data {573 let retryable: Set<Int> = [429, 500, 502, 503, 504]574 var attempt = 0575 while true {576 try Task.checkCancellation()577 let (data, response) = try await URLSession.shared.data(for: request)578 let http = response as! HTTPURLResponse579 if http.statusCode == 200 { return data }580581 let failure = RequestFailure(582 status: http.statusCode,583 error: (try? JSONDecoder().decode(ErrorEnvelope.self, from: data))?.error,584 retryAfter: http.value(forHTTPHeaderField: "Retry-After").flatMap(TimeInterval.init)585 )586 attempt += 1587 let quota = failure.error?.code == "insufficient_quota"588 guard retryable.contains(http.statusCode), !quota, attempt < attempts else { throw failure }589590 let backoff = min(30, pow(2, Double(attempt - 1))) * Double.random(in: 0.5...1)591 try await Task.sleep(nanoseconds: UInt64((failure.retryAfter ?? backoff) * 1_000_000_000))592 }593}`,594 },595};596597// ------------------------------------------------------------------ complete clients (SDK Examples)598export const SDK = {599 python: r`# pip install openai600import os601602import openai603from openai import OpenAI604605client = OpenAI(606 base_url="https://llm.spboucher.ai/v1",607 api_key=os.environ["MACLUSTR_API_KEY"], # YOUR_MACLUSTR_API_KEY608 timeout=120,609 max_retries=2, # retries 429 / 5xx with backoff and honours Retry-After610)611612def ask(prompt: str) -> str:613 """Non-streaming completion."""614 response = client.chat.completions.create(615 model="maclustr-qwen3",616 messages=[{"role": "user", "content": prompt}],617 temperature=0.7,618 max_tokens=512,619 )620 return response.choices[0].message.content or ""621622def stream(prompt: str) -> None:623 """Streaming completion with reasoning, usage and error handling."""624 try:625 events = client.chat.completions.create(626 model="maclustr-qwen3",627 messages=[{"role": "user", "content": prompt}],628 stream=True,629 stream_options={"include_usage": True},630 )631 for chunk in events:632 for choice in chunk.choices:633 reasoning = getattr(choice.delta, "reasoning_content", None) # MacLustr extension634 if reasoning:635 print(f"[thinking] {reasoning}", end="", flush=True)636 if choice.delta.content:637 print(choice.delta.content, end="", flush=True)638 if chunk.usage:639 cached = chunk.usage.prompt_tokens_details.cached_tokens640 print(f"\n{chunk.usage.total_tokens} tokens ({cached} from the prefix cache)")641 except openai.AuthenticationError:642 print("Invalid or missing API key")643 except openai.RateLimitError as err:644 print("Rate limited, retry after", err.response.headers.get("retry-after"), "s")645 except openai.APIStatusError as err:646 print("API error", err.status_code, err.body)647 except openai.APIError as err:648 print("Stream failed:", err) # includes in-stream error events649650if __name__ == "__main__":651 print(ask("Say hello in French."))652 stream("Write a haiku about silicon.")`,653654 async_python: r`import asyncio655import os656657from openai import AsyncOpenAI658659client = AsyncOpenAI(base_url="https://llm.spboucher.ai/v1", api_key=os.environ["MACLUSTR_API_KEY"])660661async def main() -> None:662 stream = await client.chat.completions.create(663 model="maclustr-qwen3",664 messages=[{"role": "user", "content": "Write a haiku about silicon."}],665 stream=True,666 )667 async for chunk in stream:668 if chunk.choices and chunk.choices[0].delta.content:669 print(chunk.choices[0].delta.content, end="", flush=True)670671asyncio.run(main())`,672673 typescript: r`// npm install openai (server-side only: never ship your key to a browser)674import OpenAI from "openai";675676const client = new OpenAI({677 baseURL: "https://llm.spboucher.ai/v1",678 apiKey: process.env.MACLUSTR_API_KEY, // YOUR_MACLUSTR_API_KEY679 timeout: 120_000,680 maxRetries: 2, // retries 429 / 5xx with backoff and honours Retry-After681});682683/** Non-streaming completion. */684export async function ask(prompt: string): Promise<string> {685 const response = await client.chat.completions.create({686 model: "maclustr-qwen3",687 messages: [{ role: "user", content: prompt }],688 temperature: 0.7,689 max_tokens: 512,690 });691 return response.choices[0].message.content ?? "";692}693694/** Streaming completion with reasoning, usage, cancellation and error handling. */695export async function stream(prompt: string, signal?: AbortSignal): Promise<void> {696 try {697 const events = await client.chat.completions.create(698 {699 model: "maclustr-qwen3",700 messages: [{ role: "user", content: prompt }],701 stream: true,702 stream_options: { include_usage: true },703 },704 { signal }, // aborting closes the connection; the server stops generating705 );706 for await (const chunk of events) {707 const delta = chunk.choices[0]?.delta as708 | (OpenAI.ChatCompletionChunk.Choice.Delta & { reasoning_content?: string }) // MacLustr extension709 | undefined;710 if (delta?.reasoning_content) process.stdout.write("[thinking] " + delta.reasoning_content);711 if (delta?.content) process.stdout.write(delta.content);712 if (chunk.usage) {713 const cached = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;714 console.log("\n" + chunk.usage.total_tokens + " tokens (" + cached + " from the prefix cache)");715 }716 }717 } catch (err) {718 if (err instanceof OpenAI.APIUserAbortError) return; // cancelled by the caller719 if (err instanceof OpenAI.AuthenticationError) console.error("Invalid or missing API key");720 else if (err instanceof OpenAI.RateLimitError) console.error("Rate limited, retry after", err.headers?.get("retry-after"), "s");721 else if (err instanceof OpenAI.APIError) console.error("API error", err.status, err.code, err.message);722 else throw err;723 }724}725726const controller = new AbortController();727setTimeout(() => controller.abort(), 30_000); // example: give up after 30 s728console.log(await ask("Say hello in French."));729await stream("Write a haiku about silicon.", controller.signal);`,730731 swift: r`import Foundation732733/// Minimal native client for the MacLustr LLM API. No third-party dependency.734/// Requires iOS 15 / macOS 12 or later (URLSession.bytes).735struct MacLustrClient {736737 // The error envelope returned by the API: {"error": {message, type, param, code, request_id}}738 struct APIError: Error, Decodable {739 let message: String740 let type: String741 let code: String?742 let param: String?743 let request_id: String?744 var status = 0 // HTTP status (200 for in-stream errors)745 var retryAfter: TimeInterval? // from the Retry-After header on 429 / 503746747 private enum CodingKeys: String, CodingKey { case message, type, code, param, request_id }748 }749 private struct Envelope: Decodable { let error: APIError }750751 enum Event {752 case text(String)753 case reasoning(String)754 case toolCall(id: String, name: String, arguments: String)755 case usage(prompt: Int, completion: Int, cached: Int)756 case finished(reason: String)757 }758759 private struct Chunk: Decodable {760 struct Choice: Decodable {761 struct Delta: Decodable {762 struct ToolCall: Decodable {763 struct Function: Decodable { let name: String; let arguments: String }764 let id: String765 let function: Function766 }767 let content: String?768 let reasoning_content: String?769 let tool_calls: [ToolCall]?770 }771 let delta: Delta772 let finish_reason: String?773 }774 struct Usage: Decodable {775 struct Details: Decodable { let cached_tokens: Int }776 let prompt_tokens: Int777 let completion_tokens: Int778 let prompt_tokens_details: Details?779 }780 let choices: [Choice]?781 let usage: Usage?782 let error: APIError?783 }784785 let apiKey: String // from the Keychain or your backend, never hard-coded786 var baseURL = URL(string: "https://llm.spboucher.ai/v1")!787 var model = "maclustr-qwen3"788 var session = URLSession.shared789790 // MARK: Requests791792 private func request(_ path: String, body: [String: Any]) throws -> URLRequest {793 var request = URLRequest(url: baseURL.appendingPathComponent(path))794 request.httpMethod = "POST"795 request.timeoutInterval = 120796 request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")797 request.setValue("application/json", forHTTPHeaderField: "Content-Type")798 request.httpBody = try JSONSerialization.data(withJSONObject: body)799 return request800 }801802 private func failure(_ data: Data, _ http: HTTPURLResponse) -> APIError {803 var error = (try? JSONDecoder().decode(Envelope.self, from: data))?.error804 ?? APIError(message: "HTTP \(http.statusCode)", type: "api_error", code: nil, param: nil, request_id: nil)805 error.status = http.statusCode806 error.retryAfter = http.value(forHTTPHeaderField: "Retry-After").flatMap(TimeInterval.init)807 return error808 }809810 // MARK: Non-streaming811812 func complete(_ messages: [[String: Any]], maxTokens: Int = 512) async throws -> String {813 let request = try request("chat/completions", body: [814 "model": model, "messages": messages, "max_tokens": maxTokens,815 ])816 let (data, response) = try await session.data(for: request)817 let http = response as! HTTPURLResponse818 guard http.statusCode == 200 else { throw failure(data, http) }819 let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]820 let message = (json?["choices"] as? [[String: Any]])?.first?["message"] as? [String: Any]821 return message?["content"] as? String ?? ""822 }823824 // MARK: Streaming (server-sent events)825826 func stream(_ messages: [[String: Any]]) -> AsyncThrowingStream<Event, Error> {827 AsyncThrowingStream { continuation in828 let task = Task {829 do {830 let request = try request("chat/completions", body: [831 "model": model, "messages": messages,832 "stream": true, "stream_options": ["include_usage": true],833 ])834 let (bytes, response) = try await session.bytes(for: request)835 let http = response as! HTTPURLResponse836 guard http.statusCode == 200 else {837 var data = Data()838 for try await byte in bytes { data.append(byte) }839 throw failure(data, http)840 }841842 for try await line in bytes.lines {843 guard line.hasPrefix("data: ") else { continue } // ": keepalive" comments844 let payload = String(line.dropFirst(6))845 if payload == "[DONE]" { break }846847 let chunk = try JSONDecoder().decode(Chunk.self, from: Data(payload.utf8))848 if let error = chunk.error { throw error } // in-stream error event849 if let usage = chunk.usage {850 continuation.yield(.usage(prompt: usage.prompt_tokens,851 completion: usage.completion_tokens,852 cached: usage.prompt_tokens_details?.cached_tokens ?? 0))853 }854 guard let choice = chunk.choices?.first else { continue }855 if let text = choice.delta.reasoning_content { continuation.yield(.reasoning(text)) }856 if let text = choice.delta.content, !text.isEmpty { continuation.yield(.text(text)) }857 for call in choice.delta.tool_calls ?? [] { // each call arrives whole858 continuation.yield(.toolCall(id: call.id, name: call.function.name,859 arguments: call.function.arguments))860 }861 if let reason = choice.finish_reason { continuation.yield(.finished(reason: reason)) }862 }863 continuation.finish()864 } catch {865 continuation.finish(throwing: error)866 }867 }868 // Cancelling the consumer cancels the URLSession task, which closes the connection:869 // the server notices the disconnect and stops generating.870 continuation.onTermination = { _ in task.cancel() }871 }872 }873}874875// MARK: Usage876877let client = MacLustrClient(apiKey: "YOUR_MACLUSTR_API_KEY")878879let generation = Task {880 do {881 for try await event in client.stream([["role": "user", "content": "Write a haiku about silicon."]]) {882 switch event {883 case .text(let text): print(text, terminator: "")884 case .reasoning(let text): print("[thinking] \(text)", terminator: "")885 case .toolCall(_, let name, let arguments): print("tool call:", name, arguments)886 case .usage(let prompt, let completion, let cached): print("\n\(prompt)+\(completion) tokens, \(cached) cached")887 case .finished(let reason): print("\nfinish_reason:", reason)888 }889 }890 } catch let error as MacLustrClient.APIError {891 print("API error \(error.status) \(error.code ?? error.type): \(error.message)")892 if let delay = error.retryAfter { print("Retry after \(delay) s") }893 } catch is CancellationError {894 print("Cancelled")895 } catch {896 print("Network error:", error.localizedDescription) // e.g. URLError.networkConnectionLost897 }898}899900// Cancellation: call this from a Stop button, or let SwiftUI's .task modifier do it when the view disappears.901// generation.cancel()`,902903 curl: r`export MACLUSTR_API_KEY="YOUR_MACLUSTR_API_KEY"904905# List the models your key can use906curl https://llm.spboucher.ai/v1/models \907 -H "Authorization: Bearer $MACLUSTR_API_KEY"908909# Non-streaming completion910curl https://llm.spboucher.ai/v1/chat/completions \911 -H "Authorization: Bearer $MACLUSTR_API_KEY" \912 -H "Content-Type: application/json" \913 -d '{"model": "maclustr-qwen3", "messages": [{"role": "user", "content": "Say hello in French."}]}'914915# Streaming completion (server-sent events); --no-buffer prints tokens as they arrive916curl --no-buffer https://llm.spboucher.ai/v1/chat/completions \917 -H "Authorization: Bearer $MACLUSTR_API_KEY" \918 -H "Content-Type: application/json" \919 -d '{"model": "maclustr-qwen3", "stream": true, "stream_options": {"include_usage": true},920 "messages": [{"role": "user", "content": "Write a haiku about silicon."}]}'921922# Inspect status, request id and rate-limit headers; fail on HTTP errors in scripts923curl -i --fail-with-body https://llm.spboucher.ai/v1/chat/completions \924 -H "Authorization: Bearer $MACLUSTR_API_KEY" \925 -H "Content-Type: application/json" \926 -d '{"model": "maclustr-qwen3", "messages": [{"role": "user", "content": "Hello"}]}'`,927};928