LSL standard library: HTTP, servers and AI

http, requests, httpserver (and lsl server) and ai (aikit). The HTTP clients run the system /usr/bin/curl by direct execve with its configuration on stdin, so request bodies, Authorization headers and other secrets never appear in the process argv. Plain HTTP is allowed only for numeric loopback 127.0.0.1 / [::1]; everything else requires HTTPS (TLS 1.2+).

requests — Python-style HTTP client

load requests. Every request returns a Response.

Function Description
requests.get(url, headers=None, timeout=None) GET
requests.post/put/patch/delete(url, data=None, headers=None, timeout=None) request with a body; List/Dictionary data is encoded as JSON (Content-Type: application/json added unless given)
requests.head(url, headers=None, timeout=None) HEAD without a response body
requests.request(method, url, data=None, headers=None, timeout=None) any method (lowercase names accepted)
requests.post_stream(url, data, headers, timeout, on_chunk, method="POST") stream the body to on_chunk(text), return a Response with the accumulated body
Response(status, text) fields status (0 = transport failure), status_code (alias), text, ok (200–299); methods json(), raise_for_status()

headers is a Dictionary (max 256 entries, not modified). Redirects are not followed. timeout 1..3600 s, default 60. Errors: ConnectionError (status 0), HTTPStatusError (status outside 200–299 in raise_for_status), JsonError (json() on invalid body), HTTPError (invalid URL, header, method, timeout, body too large).

load requests

response = requests.get("https://api.example.com/data")
if response.ok:
    print response.json()["items"]
else:
    print "HTTP", response.status
end

created = requests.post("https://api.example.com/items", {"name": "LSL"})
call created.raise_for_status()

http — low-level client

load http. Returns a Dictionary {"status": Int, "text": String, "ok": Bool} (status 0 means transport failure, the message is in text).

Function Description
http.get(url, headers=None, timeout=None) GET
http.post(url, body, headers, timeout, method="POST") POST (or another method); List/Dictionary body is JSON-encoded
http.post_stream(url, body, headers, timeout, on_chunk, method="POST") streamed POST, on_chunk(text) per piece
http.get_with(curl_path, ...), post_with, post_stream_with same with an injected transport program (for tests)
http.validate_url(url), http.method_name(method) validation helpers

Limits: URL 1..8192 bytes, safe ASCII, no user-info or fragment; response max 16 MiB; request body max 4 MB encoded. Errors: HTTPError.

httpserver — bounded HTTP/1.1 server

load httpserver. Syscall-only transport for Linux x86-64. Static files are opened relative to one pinned directory handle with openat2(RESOLVE_BENEATH|NO_MAGICLINKS|NO_SYMLINKS), so path and symlink escapes fail in the kernel.

Function Description
httpserver.serve(handler, address, port, max_requests) call handler(request) for each request (0 = no limit)
httpserver.serve_static(root, address, port, max_requests) serve GET/HEAD files from the pinned root
httpserver.serve_static_tls(root, address, port, cert, key, max_requests) static HTTPS through the system nginx/OpenSSL; max_requests must be 0
httpserver.serve_workers(handler, address, port, workers, max_requests) worker pool of 1–64 threads (protect shared state with lock/atomics); returns the number of requests served
httpserver.serve_listener(...), serve_listener_workers(...) serve an existing listener
httpserver.set_body_limit(n) / body_limit() request body limit (default unlimited)
httpserver.stream_write(stream, data) send a String/ByteArray chunk; False when the client closed
httpserver.sse_event(stream, data, event=None) send one Server-Sent Event

The handler receives {"ok", "method", "target", "version", "headers" (lowercase names), "body" (ByteArray), "body_text"} and returns e.g. {"body": "text", "content_type": "text/plain; charset=utf-8"}, {"status": 404, "body": "not found"} or {"content_type": "text/event-stream", "stream": function(stream)}. An error in the handler becomes 500. Invalid methods/targets/header values get 400; repeated Content-Length, Transfer-Encoding and Host are rejected. The plain serve accept loop is single-threaded. Errors: ServerError (e.g. port in use).

load httpserver

function handler(request):
    return {"body": request["method"] + " " + request["target"] + chr(10)}
end

call httpserver.serve(handler, "127.0.0.1", 8080, 0)

lsl server

lsl server --dir ./public --bind 127.0.0.1 --port 8080
lsl server --dir ./public --tls-cert cert.pem --tls-key key.pem
lsl server --help          # defaults and all options (--once, --max-requests N)

ai — OpenAI-compatible chat with tools

load ai (bundled; in 0.10.2 at the level of aikit 1.2.0). The same API is available as the separately updatable registry package aikit: lsl install ai / lsl update ai install aikit, and since 0.9.1 load ai uses the per-user aikit.lsl when it is newer than the bundled module. On older LSL write load aikit as ai.

Call Result
ai.request(endpoint, token, model, messages, options) decoded provider JSON (Dictionary); raises on HTTP errors
ai.stream(endpoint, token, model, messages, options, on_event) calls on_event(text) for each content delta; returns {"events", "tool_calls", "reasoning", "reasoning_events"} (not the answer – assemble the text from the callbacks)
ai.stream_text(text, on_event, cancel=None) parse already loaded SSE text, no network
ai.content(response) choices[0].message.content (String or None)
ai.tool_calls(response) List of {id, name, arguments} (arguments is a JSON String)
ai.tool_message(id, name, result) message with role tool for the follow-up request
ai.reasoning(response) model reasoning text or None
ai.decode_response(response) decode an http result Dictionary
ai.help() / ai.version short help / library version

messages is a List (max 4096) of {"role", "content"}. Options (unknown keys are rejected): temperature (0–2), max_tokens, timeout (1–3600, default 60), retries (0–10, for transport errors and HTTP 408/429/5xx; in a stream only before the first text callback), cancel (function → AICancelled), transport_chunk, tools (1–128 OpenAI-style function definitions), tool_choice (auto, none, required or a specific function), on_tool_call, stream_reliability (live or transactional), reasoning, reasoning_effort, on_reasoning. Errors: AIProviderError, AICancelled.

load ai
load env

token = env.require("LUX_AI_API")
model = env.get("LUX_AI_MODEL", "flash")
messages = [{"role": "user", "content": "Introduce yourself in one sentence."}]
response = ai.request("https://api.lux-ai.cz/v1/chat/completions", token, model, messages,
                      {"max_tokens": 500, "temperature": 0.7, "timeout": 60})
printl "Answer: {ai.content(response)}"

Tool calling: pass {"tools": tools, "tool_choice": "required"}, read ai.tool_calls(response), append the assistant message and one ai.tool_message(call["id"], call["name"], result) per call, then repeat the request. Keep the API key in .env (read with load env); the library does not store it and it is not passed in argv. See the full streaming chatbot in examples.md.