SPB Git

Repository Public

samples.js 35.5 KB 928 lines javascript

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
Files main
Menu

Theme