# gizlang:hub the files of Hugging Face Hub repositories in a local folder, at REPO/FILE as the hub serves them. A file that the folder does not have is downloaded once from HUB/REPO/resolve/REVISION/FILE (HUB: $HF_ENDPOINT, else https://huggingface.co; with $HF_TOKEN when it is set) and written to its place at once. The pin of a repository (.pins/REPO.pin in the folder) keeps the commit that its first download resolved and the SHA-256 of each file downloaded: later downloads use that commit, and each read checks the file against its SHA-256. A snapshot downloads the data files of a repository folder (a model's weights stay on disk: Hub.path). And the client of a chat model behind an OpenAI-compatible API (modelApi), for the stack's builder and the database's pgml.transform. ```gizlang import * as Hub from "gizlang:hub"; ``` ## Types ### `Hub` ```gizlang type Hub = { sys: System; path: string; download: bool; allow: Vec; limit: i64; endpoint: string; } ``` A models folder: `path`, the System that reads it, whether a missing file is downloaded, and the hub it comes from (`endpoint`: $HF_ENDPOINT, a mirror or a local server, else https://huggingface.co). `allow`: the repositories that may be downloaded ("owner/name", or "owner/" for all of an owner; empty: all). `limit`: the most bytes of one downloaded file (0: no limit). - `sys`: `gizlang_system.System` - `path`: `string` - `download`: `bool` - `allow`: `Vec` - `limit`: `i64` - `endpoint`: `string` ### `Held` ```gizlang type Held = { repo: string; kind: string; } ``` A repository in the folder and what its files make: "encoder" (a sentence-transformers model: modules.json), "cross-encoder" (a sequence classification model) or "model" (another config.json). - `repo`: `string` - `kind`: `string` ### `ModelApi` ```gizlang type ModelApi = { endpoint: Http.Url; key: string; model: string; pool: Http.Pool; } ``` The API's base URL, its key, the model to use when a caller names none (AI_MODEL; "": none) and the connections kept open to it. Every copy shares the one pool, so the rounds of all callers reuse connections. - `endpoint`: `gizlang_http.Url` - `key`: `string` - `model`: `string` - `pool`: `gizlang_http.Pool` ### `Sampling` ```gizlang type Sampling = { maxTokens: i64; temperature: f64; topP: f64; seed: i64; stop: Vec; } ``` The sampling options of a request, as the OpenAI API names them: max_tokens (0: the model's default), temperature and top_p (a negative value: the default), seed (-1: none) and the stop strings. - `maxTokens`: `i64` - `temperature`: `f64` - `topP`: `f64` - `seed`: `i64` - `stop`: `Vec` ### `Call` ```gizlang type Call = { id: string; name: string; arguments: string; } ``` A tool call the model made: its id, the tool, and its arguments (a JSON object's text). - `id`: `string` - `name`: `string` - `arguments`: `string` ### `Fragment` ```gizlang type Fragment = { index: i64; id: string; name: string; arguments: string; } ``` A piece of a tool call as a stream sends it: the call's index, and its id and name (first piece) or more of its arguments. - `index`: `i64` - `id`: `string` - `name`: `string` - `arguments`: `string` ### `Chunk` ```gizlang type Chunk = { text: string; reasoning: string; details: Vec; calls: Vec; finish: string; tokens: i64; error: string; input: i64; cached: i64; cost: i64; } ``` What one event added: text, reasoning (and its provider details, which a tool round sends back), tool call pieces, why the turn ended, and in the last event the usage: the tokens it wrote, the prompt tokens it read and of those the ones read from the provider's cache, and the cost in millionths of a dollar (OpenRouter's `cost`); or an error. - `text`: `string` - `reasoning`: `string` - `details`: `Vec` - `calls`: `Vec` - `finish`: `string` - `tokens`: `i64` - `error`: `string` - `input`: `i64` - `cached`: `i64` - `cost`: `i64` ### `Refusal` ```gizlang type Refusal = { status: i64; message: string; } ``` Why a model API did not answer: its HTTP status (0: no connection) and its message. - `status`: `i64` - `message`: `string` ### `Picture` ```gizlang type Picture = { data: bytes; media: string; } ``` A picture a model drew: its bytes and media type (image/png, image/jpeg, image/webp). - `data`: `bytes` - `media`: `string` ## Functions ### `hub` ```gizlang function hub(sys: System, path: string, download: bool): Hub ``` The hub of the models folder `path`; `download` false reads only the files already there. Effects: fail, io. ### `folder` ```gizlang function folder(sys: System): string ``` The shared models folder: $GIZLANG_CACHE/huggingface, else ~/.cache/gizlang/huggingface; "" when neither is set. Effects: fail, io. ### `validRepo` ```gizlang function validRepo(repo: string): bool ``` Whether `repo` names a repository ("owner/name" or "name") and not a path out of the folder or into .pins. Effects: fail. ### `dataFile` ```gizlang function dataFile(name: string): bool ``` Whether a model reads a file of this name: JSON, safetensors, tokenizer and template files. Never code: no model runs code of its own. Effects: fail. ### `modelApi` ```gizlang function modelApi(sys: System): Option ``` The model API of AI_URL (https://openrouter.ai/api/v1 when unset), AI_API_KEY and AI_MODEL. None when the URL is not http(s), or with no key for the default URL; a URL set by AI_URL (a local server) may have no key. Effects: fail, write, io. ### `sampling` ```gizlang function sampling(): Sampling ``` The model's defaults for every option. Effects: fail. ### `stream` ```gizlang function stream(c: ModelApi, model: string, effort: string, messages: Vec, tools: bytes, answer: bool, options: Sampling): Http.Incoming throws string ``` Starts a streamed completion of `messages` (JSON objects, as `message` writes them) by `model` with `options`, offering `tools` (a JSON array, b"" for none); `effort` ("", "low", "medium", "high") sets how hard it reasons; `answer` keeps the tools described (earlier turns call them) but has the model write instead of calling one. An answer other than 200 is its error message. Effects: fail, read, write, console, io. ### `opened` ```gizlang function opened(c: ModelApi, model: string, effort: string, messages: Vec, tools: bytes, answer: bool, options: Sampling): Result ``` `stream`, with the status of a refusal (a gateway tries the next route on 0, 408, 429 and 5xx). Effects: fail, read, write, console, io. ### `requestBody` ```gizlang function requestBody(model: string, effort: string, messages: Vec, tools: bytes, answer: bool, options: Sampling): bytes ``` The body of `stream`'s request. Effects: fail. ### `posted` ```gizlang function posted(c: ModelApi, body: bytes, extra: Vec = []): Result ``` Posts `body`, a chat completion request, to `c` with the `extra` headers (a gateway route's own, which replace these of the same name); an answer other than 200 is its refusal. Effects: fail, read, write, console, io. ### `chunk` ```gizlang function chunk(data: string): Chunk ``` One event's data read; `"[DONE]"` and an unreadable event read as nothing. Effects: fail. ### `gather` ```gizlang function gather(calls: mut Vec, f: Fragment): void ``` Adds a call's piece to the calls made so far. Effects: fail. ### `system` ```gizlang function system(fixed: string, varying: string): bytes ``` The system message: `fixed` (the same for every request of a task) marked as a cache breakpoint, so a provider that caches by prefix (Anthropic and Gemini through OpenRouter; OpenAI caches without the mark) reads the tools and it from cache on every later round; then `varying`, what changes between tasks. Effects: fail. ### `breakpoint` ```gizlang function breakpoint(message: bytes): bytes ``` `message` (as `message`, `calling` or `result` write it) with its text content marked as a cache breakpoint: put on the last message of a request, a provider that caches by prefix reads the whole conversation before it from cache on the next request, which appends to it. A message without text content is returned as it is. Effects: fail. ### `message` ```gizlang function message(role: string, content: string): bytes ``` A message: {"role": role, "content": content}. Effects: fail. ### `calling` ```gizlang function calling(content: string, calls: Vec, details: Vec): bytes ``` The model's own turn that called tools, with the reasoning details the provider needs to continue it. Effects: fail. ### `result` ```gizlang function result(id: string, content: string): bytes ``` A tool's result for the call `id`. Effects: fail. ### `pieces` ```gizlang function pieces(c: ModelApi, model: string, messages: Vec, options: Sampling): Vec throws string ``` The pieces of text of a completion with no tools, in the order the stream sent them. Effects: fail, read, write, console, io. ### `texts` ```gizlang function texts(opened: Http.Incoming): Vec throws string ``` The text pieces of an opened stream, which it closes. Effects: fail, read, write, console, io. ### `complete` ```gizlang function complete(c: ModelApi, model: string, messages: Vec, options: Sampling): string throws string ``` The whole text of a completion with no tools, as for a title or a SQL transform. Effects: fail, read, write, console, io. ### `picture` ```gizlang function picture(c: ModelApi, model: string, prompt: string): Picture throws string ``` Has `model` (one that answers with images, as OpenRouter's image models do) draw `prompt`, and answers the first picture: its data URL decoded. Effects: fail, read, write, console, io. ## Methods ### `Hub.allows` ```gizlang function Hub.allows(self: Hub, repo: string): bool ``` Whether the hub may download `repo`. Effects: fail. ### `Hub.file` ```gizlang function Hub.file(self: Hub, repo: string, file: string): Option throws string ``` FILE of REPO: from the folder, downloaded first when it is missing, downloads are on and `allow` names REPO; none when neither has it. A file with a SHA-256 in the pin of REPO must have it. Effects: fail, read, write, console, io. ### `Hub.repositories` ```gizlang function Hub.repositories(self: Hub): Vec throws string ``` The repositories that the folder holds ("owner/name" or "name", with a config.json), in name order. Effects: fail, io. ### `Hub.path` ```gizlang function Hub.path(self: Hub, repo: string, file: string): Option throws string ``` The path of FILE of REPO in the folder, downloaded first as Hub.file downloads it; none when neither has it. It reads nothing: a weight file stays on disk, and its SHA-256 is checked once, when it is downloaded. Effects: fail, read, write, console, io. ### `Hub.snapshot` ```gizlang function Hub.snapshot(self: Hub, repo: string, folder: string): string throws string ``` The local path of folder `folder` of REPO ("" for its top) with all its data files (dataFile; of the safetensors files, only those that an index there names, when there is one), downloaded first when they are missing. The pin keeps the folder listed, so a later snapshot needs no network. Downloads off, the folder holds what it holds. Effects: fail, read, write, console, io.