AILib — Plan9Basic Documentation

AILib — AI Client Library

Provides functions to communicate with large language model APIs from your applets. Supports multiple AI providers out of the box — Anthropic (Claude), OpenAI (GPT), Google (Gemini), local models, and many more. AILib handles HTTP transport, authentication, message formatting, streaming, and multi-turn conversations, so your programs only need to focus on what to say and how to use the response. 45 functions.

Category	Count	Description
Error Handling	4	ai_error, errormsg$, strerror$, clearerror
Client Lifecycle	2	ai_client#, ai_free
Configuration	11	model, system, temperature, maxtokens, topp, timeout, baseurl, stop sequences
Custom Headers	3	header#, headerremove#, headerclear#
Identity	4	apikey#, endpoint#, useragent#, provider$
Simple Chat	2	chat$, clearchat
Streaming	3	ontoken#, chatstream, streambuffer$
Single-Shot Completion	2	complete$, completesystem$
Conversation Management	9	conversation#, free, system, clear, maxhistory, ask$, count, last$, tokens
Response Metadata	5	status, body$, tokensin, tokensout, ok

Architecture

Your program talks to AILib, which handles all the plumbing:

Your Program

→

AILib
45 functions

→

HTTP / JSON

→

AI Provider API
Claude, GPT, Gemini…

AILib automatically formats messages for each provider’s API, handles authentication headers, parses JSON responses, extracts token usage, and supports streaming. You just choose a provider, set your key, and start chatting.

ⓘ Three ways to talk to AI: Simple Chat (ai_chat$) keeps history automatically. Single-Shot Completion (ai_complete$) is stateless. Conversation (ai_ask$ + ai_conversation#) gives full control over history and token management.

Supported Providers

Cloud Providers

Provider	Alias	Default Model
`"anthropic"`	`"claude"`	claude-sonnet-4-20250514
`"openai"`	`"gpt"`	gpt-4o
`"google"`	`"gemini"`	gemini-2.0-flash
`"mistral"`	—	mistral-large-latest
`"groq"`	—	llama-3.3-70b-versatile
`"deepseek"`	—	deepseek-chat
`"xai"`	`"grok"`	grok-3
`"perplexity"`	—	sonar-pro
`"together"`	—	meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo
`"fireworks"`	—	accounts/fireworks/models/llama-v3p1-70b-instruct
`"openrouter"`	—	anthropic/claude-sonnet-4-20250514

Local Providers (No API Key Needed)

Provider	Default Model	Default Port
`"ollama"`	llama3	11434
`"lmstudio"`	local-model	1234
`"jan"`	local-model	1337
`"custom"`	(none — set with `ai_baseurl#` and `ai_model#`)	—

╯ provider examples─◻✕
' Cloud providers — need API key
let ai# = ai_client#("anthropic", "sk-ant-xxxxx")
let ai# = ai_client#("openai", "sk-xxxxx")
let ai# = ai_client#("google", "AIzaSy-xxxxx")

' Local models — no key needed
let ai# = ai_client#("ollama", "")

' Custom endpoint
let ai# = ai_client#("custom", myKey$)
ai_baseurl#(ai#, "https://my-proxy.example.com/v1")
ai_model#(ai#, "my-model")

Error Handling

Function	Signature	Description
`ai_error()`	`ai_error@`	Last error code (0 = no error)
`ai_errormsg$()`	`ai_errormsg$@`	Last error message as string
`ai_strerror$(code)`	`ai_strerror$@n`	Convert error code to description
`ai_clearerror()`	`ai_clearerror@`	Clear the error state

Error Codes

Code	Name	Description	Retry?
0	None	No error	—
1	Invalid Client	Invalid client handle	No
2	Invalid Conversation	Invalid conversation handle	No
3	Invalid Provider	Unknown provider name	No
4	Invalid Key	Invalid API key format	No
5	Connection Error	Network or connection failure	Yes
6	Timeout	Request timed out	Yes
7	API Error	Server returned an error	Maybe
8	Parse Error	Could not parse JSON response	No
9	Rate Limited	Too many requests	Yes (wait)
10	Auth Failed	Authentication rejected	No (check key)
11	Invalid Model	Model name not recognized	No
12	Stream Error	Error during streaming	Yes
13	Invalid Argument	Bad function argument	No
14	Context Overflow	Exceeded context window	No (reduce history)

ⓘ Transient errors (codes 5, 6, 9, 12) can be retried after a brief wait. Permanent errors (codes 1-4, 8, 10-11, 13-14) require fixing the code or configuration.

Client Lifecycle

Function	Signature	Description
`ai_client#(provider$, apiKey$)`	`ai_client#@$$`	Create AI client for a provider
`ai_free(ai#)`	`ai_free@#`	Free AI client and release resources

ⓘ Garbage collected. AI clients are tracked by the runtime GC and cleaned up automatically when the program ends. You can also call ai_free explicitly to release resources sooner.

Configuration

All configuration setters return the AI client pointer, so they can be called as standalone statements without assigning the result:

Function	Signature	Description
`ai_model#(ai#, model$)`	`ai_model#@#$`	Set the model to use
`ai_model$(ai#)`	`ai_model$@#`	Get current model name
`ai_system#(ai#, prompt$)`	`ai_system#@#$`	Set system prompt (sent with every request)
`ai_temperature#(ai#, value)`	`ai_temperature#@#n`	Set temperature (0.0–2.0, lower = more deterministic)
`ai_maxtokens#(ai#, tokens)`	`ai_maxtokens#@#n`	Set maximum output tokens
`ai_topp#(ai#, value)`	`ai_topp#@#n`	Set top-p / nucleus sampling (0.0–1.0)
`ai_timeout#(ai#, seconds)`	`ai_timeout#@#n`	Set request timeout in seconds
`ai_baseurl#(ai#, url$)`	`ai_baseurl#@#$`	Set custom base URL (proxies, self-hosted)
`ai_baseurl$(ai#)`	`ai_baseurl$@#`	Get current base URL
`ai_stop#(ai#, sequence$)`	`ai_stop#@#$`	Add a stop sequence
`ai_clearstop#(ai#)`	`ai_clearstop#@#`	Clear all stop sequences

╯ typical configuration─◻✕
let ai# = ai_client#("anthropic", key$)
ai_model#(ai#, "claude-sonnet-4-20250514")
ai_maxtokens#(ai#, 4096)
ai_temperature#(ai#, 0.7)
ai_system#(ai#, "You are a helpful assistant.")
ai_timeout#(ai#, 30)

Custom Headers

Function	Signature	Description
`ai_header#(ai#, name$, value$)`	`ai_header#@#$$`	Add a custom HTTP header to all requests
`ai_headerremove#(ai#, name$)`	`ai_headerremove#@#$`	Remove a custom header by name
`ai_headerclear#(ai#)`	`ai_headerclear#@#`	Remove all custom headers

Identity

Function	Signature	Description
`ai_apikey#(ai#, key$)`	`ai_apikey#@#$`	Change API key after client creation
`ai_endpoint#(ai#, path$)`	`ai_endpoint#@#$`	Set custom endpoint path (appended to base URL)
`ai_useragent#(ai#, agent$)`	`ai_useragent#@#$`	Set custom User-Agent header
`ai_provider$(ai#)`	`ai_provider$@#`	Get provider name (e.g. “anthropic”, “openai”)

Simple Chat

The easiest way to talk to an AI. Maintains internal history automatically — the AI remembers previous messages in the session.

Function	Signature	Description
`ai_chat$(ai#, message$)`	`ai_chat$@#$`	Send message, get complete response (keeps history)
`ai_clearchat(ai#)`	`ai_clearchat@#`	Clear internal chat history — next call starts fresh

╯ simple-chat.bas─◻✕
let ai# = ai_client#("anthropic", key$)
ai_model#(ai#, "claude-sonnet-4-20250514")
ai_maxtokens#(ai#, 1024)

let reply$ = ai_chat$(ai#, "What causes the northern lights?")
println reply$

' Follow-up — the AI remembers the previous message
let reply$ = ai_chat$(ai#, "Where is the best place to see them?")
println reply$

ai_free(ai#)

Streaming

Receive tokens in real-time as the AI generates them, via a callback function.

Function	Signature	Description
`ai_ontoken#(ai#, callback$)`	`ai_ontoken#@#$`	Set the streaming callback function name
`ai_chatstream(ai#, message$)`	`ai_chatstream@#$`	Send message and stream response via callback
`ai_streambuffer$(ai#)`	`ai_streambuffer$@#`	Get the full accumulated text after streaming

Callback Signature

The callback receives two parameters: token$ (the text chunk just received) and done (0 while streaming, 1 on the final token).

╯ streaming.bas─◻✕
function on_token$(token$, done)
    print token$;
    if done = 1 then
        println ""
        println "--- Stream complete ---"
    end if
    return ""
endfunction

let ai# = ai_client#("anthropic", key$)
ai_model#(ai#, "claude-sonnet-4-20250514")
ai_maxtokens#(ai#, 512)
ai_ontoken#(ai#, "on_token")

ai_chatstream(ai#, "Write a short poem about the ocean")

' Get the complete response after streaming finishes
let full$ = ai_streambuffer$(ai#)
println "Total: " + str$(len(full$)) + " chars"

ai_free(ai#)

Single-Shot Completion

Stateless prompt-in/response-out with no chat history. Each call is independent. Ideal for classification, summarization, code generation, and one-off tasks.

Function	Signature	Description
`ai_complete$(ai#, prompt$)`	`ai_complete$@#$`	Single-shot completion
`ai_completesystem$(ai#, sys$, msg$)`	`ai_completesystem$@#$$`	Completion with system prompt for this call only

╯ completion.bas─◻✕
' Summarize text (stateless)
let summary$ = ai_complete$(ai#, "Summarize in one sentence: " + longText$)

' Generate code with a system prompt
let sys$ = "You are a concise assistant. Return only the answer, no explanation."
let answer$ = ai_completesystem$(ai#, sys$, "What is the capital of Australia?")
println answer$

Conversation Management

Full control over multi-turn chat history. Create multiple conversations, set system prompts per conversation, manage history size for token awareness.

Function	Signature	Description
`ai_conversation#()`	`ai_conversation#@`	Create a new empty conversation
`ai_conversation_free(conv#)`	`ai_conversation_free@#`	Free conversation and its history
`ai_conversation_system#(conv#, sys$)`	`ai_conversation_system#@#$`	Set system prompt for the conversation
`ai_conversation_clear(conv#)`	`ai_conversation_clear@#`	Clear messages (keeps system prompt)
`ai_conversation_maxhistory#(conv#, n)`	`ai_conversation_maxhistory#@#n`	Set max messages to keep (auto-trims old ones)
`ai_ask$(ai#, conv#, message$)`	`ai_ask$@##$`	Send message using a conversation, get response
`ai_conversation_count(conv#)`	`ai_conversation_count@#`	Number of messages in history
`ai_conversation_last$(conv#)`	`ai_conversation_last$@#`	Text of last message (usually AI’s response)
`ai_conversation_tokens(conv#)`	`ai_conversation_tokens@#`	Estimated total token count for history

╯ conversation.bas─◻✕
let ai# = ai_client#("anthropic", key$)
ai_model#(ai#, "claude-sonnet-4-20250514")
ai_maxtokens#(ai#, 1024)

let conv# = ai_conversation#()
ai_conversation_system#(conv#, "You are a patient math tutor.")
ai_conversation_maxhistory#(conv#, 10)

' First question
let r$ = ai_ask$(ai#, conv#, "What is a prime number?")
println "A: " + r$

' Follow-up — AI remembers context
let r$ = ai_ask$(ai#, conv#, "Is 17 prime? Why?")
println "A: " + r$

' Check state
println "Messages: " + str$(ai_conversation_count(conv#))
println "Tokens: " + str$(ai_conversation_tokens(conv#))

ai_conversation_free(conv#)
ai_free(ai#)

Response Metadata

Function	Signature	Description
`ai_status(ai#)`	`ai_status@#`	HTTP status code (200, 401, 429, etc.)
`ai_body$(ai#)`	`ai_body$@#`	Raw JSON response body (for debugging)
`ai_tokensin(ai#)`	`ai_tokensin@#`	Input tokens used in last request
`ai_tokensout(ai#)`	`ai_tokensout@#`	Output tokens generated in last request
`ai_ok(ai#)`	`ai_ok@#`	Returns 1 if last request succeeded (HTTP 200)

╯ checking results─◻✕
let reply$ = ai_chat$(ai#, "Hello!")

if ai_ok(ai#) = 1 then
    println "Response: " + reply$
    println "HTTP: " + str$(ai_status(ai#))
    println "Tokens: " + str$(ai_tokensin(ai#)) + " in, " + str$(ai_tokensout(ai#)) + " out"
else
    println "Error " + str$(ai_error()) + ": " + ai_errormsg$()
    println "HTTP: " + str$(ai_status(ai#))
end if

Complete Examples

Summarization with System Prompt

╯ summarize.bas─◻✕
println "=== Article Summarizer ==="

let ai# = ai_client#("anthropic", "sk-ant-xxxxx")
ai_model#(ai#, "claude-sonnet-4-20250514")
ai_maxtokens#(ai#, 256)

let sys$ = "You are a concise summarizer. "
sys$ = sys$ + "Return a summary of 2-3 sentences maximum. "
sys$ = sys$ + "Focus on the key point and avoid filler words."

let article$ = "Scientists have discovered a new deep-sea species..."
let summary$ = ai_completesystem$(ai#, sys$, article$)

if ai_ok(ai#) = 1 then
    println "Summary:"
    println "---"
    println summary$
    println "---"
else
    println "Error: " + ai_errormsg$()
end if

ai_free(ai#)

Multi-Provider Comparison

╯ multi-provider.bas─◻✕
println "=== Multi-Provider Comparison ==="

let question$ = "In one sentence, what is recursion?"

' Anthropic
let ai# = ai_client#("anthropic", "sk-ant-xxxxx")
ai_maxtokens#(ai#, 100)
println "Claude: " + ai_chat$(ai#, question$)
ai_free(ai#)

' OpenAI
let ai# = ai_client#("openai", "sk-xxxxx")
ai_maxtokens#(ai#, 100)
println "GPT: " + ai_chat$(ai#, question$)
ai_free(ai#)

' Local Ollama (free)
let ai# = ai_client#("ollama", "")
ai_model#(ai#, "llama3")
ai_maxtokens#(ai#, 100)
println "Llama: " + ai_chat$(ai#, question$)
ai_free(ai#)

Choosing a Chat Mode

Mode	Function	History	Best For
Simple Chat	`ai_chat$`	Automatic (internal)	Interactive chatbots, quick Q&A
Single-Shot	`ai_complete$` / `ai_completesystem$`	None (stateless)	Classification, summarization, code generation
Conversation	`ai_ask$` + `ai_conversation#`	Explicit (you control)	Complex multi-topic apps, token budgeting

ⓘ Rule of thumb: Start with ai_chat$. Move to ai_complete$ if you don’t need history. Move to ai_ask$ + ai_conversation# when you need multiple conversations or fine-grained token management.

Best Practices

Practice	Why
Always check `ai_ok(ai#)` after API calls	Network errors, timeouts, and rate limits can happen
Set `ai_maxtokens#` to limit output	Controls cost and prevents unexpectedly long responses
Set `ai_timeout#` for production code	Prevents indefinite hangs on network issues
Monitor tokens with `ai_tokensin` / `ai_tokensout`	AI API calls are billed per token
Use `ai_conversation_maxhistory#`	Prevents unbounded history growth and context overflow
Use `ai_complete$` for one-off tasks	Stateless — no risk of unintended context bleeding
Transient errors (5, 6, 9, 12) can be retried	Network issues and rate limits are usually temporary
Use local models (Ollama) for development	No API costs during testing — same AILib API
Store API keys outside your code	Never hard-code secrets in source files
Use `ai_system#` for behavior control	System prompts guide the AI’s tone, format, and constraints

Quick Reference — All 45 Functions

Function	Signature	Description
ERROR HANDLING (4)
`ai_error()`	`ai_error@`	Last error code
`ai_errormsg$()`	`ai_errormsg$@`	Last error message
`ai_strerror$(code)`	`ai_strerror$@n`	Error code → string
`ai_clearerror()`	`ai_clearerror@`	Clear error state
CLIENT LIFECYCLE (2)
`ai_client#(provider$, key$)`	`ai_client#@$$`	Create AI client
`ai_free(ai#)`	`ai_free@#`	Free client
CONFIGURATION (11)
`ai_model#(ai#, model$)`	`ai_model#@#$`	Set model
`ai_model$(ai#)`	`ai_model$@#`	Get model
`ai_system#(ai#, prompt$)`	`ai_system#@#$`	Set system prompt
`ai_temperature#(ai#, val)`	`ai_temperature#@#n`	Set temperature
`ai_maxtokens#(ai#, n)`	`ai_maxtokens#@#n`	Set max output tokens
`ai_topp#(ai#, val)`	`ai_topp#@#n`	Set top-p
`ai_timeout#(ai#, sec)`	`ai_timeout#@#n`	Set timeout
`ai_baseurl#(ai#, url$)`	`ai_baseurl#@#$`	Set base URL
`ai_baseurl$(ai#)`	`ai_baseurl$@#`	Get base URL
`ai_stop#(ai#, seq$)`	`ai_stop#@#$`	Add stop sequence
`ai_clearstop#(ai#)`	`ai_clearstop#@#`	Clear stop sequences
CUSTOM HEADERS (3)
`ai_header#(ai#, name$, val$)`	`ai_header#@#$$`	Add header
`ai_headerremove#(ai#, name$)`	`ai_headerremove#@#$`	Remove header
`ai_headerclear#(ai#)`	`ai_headerclear#@#`	Clear all headers
IDENTITY (4)
`ai_apikey#(ai#, key$)`	`ai_apikey#@#$`	Change API key
`ai_endpoint#(ai#, path$)`	`ai_endpoint#@#$`	Set endpoint path
`ai_useragent#(ai#, agent$)`	`ai_useragent#@#$`	Set User-Agent
`ai_provider$(ai#)`	`ai_provider$@#`	Get provider name
SIMPLE CHAT (2)
`ai_chat$(ai#, msg$)`	`ai_chat$@#$`	Chat (keeps history)
`ai_clearchat(ai#)`	`ai_clearchat@#`	Clear chat history
STREAMING (3)
`ai_ontoken#(ai#, cb$)`	`ai_ontoken#@#$`	Set stream callback
`ai_chatstream(ai#, msg$)`	`ai_chatstream@#$`	Stream a message
`ai_streambuffer$(ai#)`	`ai_streambuffer$@#`	Get streamed text
SINGLE-SHOT COMPLETION (2)
`ai_complete$(ai#, prompt$)`	`ai_complete$@#$`	One-shot completion
`ai_completesystem$(ai#, sys$, msg$)`	`ai_completesystem$@#$$`	Completion with system prompt
CONVERSATION MANAGEMENT (9)
`ai_conversation#()`	`ai_conversation#@`	Create conversation
`ai_conversation_free(conv#)`	`ai_conversation_free@#`	Free conversation
`ai_conversation_system#(conv#, sys$)`	`ai_conversation_system#@#$`	Set system prompt
`ai_conversation_clear(conv#)`	`ai_conversation_clear@#`	Clear messages
`ai_conversation_maxhistory#(conv#, n)`	`ai_conversation_maxhistory#@#n`	Set max history
`ai_ask$(ai#, conv#, msg$)`	`ai_ask$@##$`	Chat with conversation
`ai_conversation_count(conv#)`	`ai_conversation_count@#`	Message count
`ai_conversation_last$(conv#)`	`ai_conversation_last$@#`	Last message text
`ai_conversation_tokens(conv#)`	`ai_conversation_tokens@#`	Estimated token count
RESPONSE METADATA (5)
`ai_status(ai#)`	`ai_status@#`	HTTP status code
`ai_body$(ai#)`	`ai_body$@#`	Raw response JSON
`ai_tokensin(ai#)`	`ai_tokensin@#`	Input tokens used
`ai_tokensout(ai#)`	`ai_tokensout@#`	Output tokens used
`ai_ok(ai#)`	`ai_ok@#`	1 if last request succeeded

45 functions. Integrates with RAGLib for knowledge-grounded responses.