Build with Wisent.

Wisent frameworks

Desktop, Swift UI, and Swift ML foundations.

Desktop foundations

Shared desktop authentication and update contracts.

Wisent Desktop Auth

    ![LinkedIn](https://www.linkedin.com/comp

wisent-desktop-update

    ![LinkedIn](https://www.linkedin.com/c

Swift ML

Native model loading, templating, inference, audio, and speech foundations.

espeak-ng-spm

    ![LinkedIn](https://www.linkedin.com/company/wisent a

MLX Swift

MLX Swift Installation Documentation Examples MLX Swift is a Swift API for MLX. MLX is an array framework for machine learning on Apple silicon. MLX Swift expands MLX to the Swift language, making research and experimentation easier on Appl

Individual Contributors

Individual Contributors If you wish to be acknowledged for your contributions, please list your name with a short description of your contribution(s) below. For example: Jane Smith: Added the foo and bar ops. MLX Swift was developed with co

Contributor Covenant Code of Conduct

Contributor Covenant Code of Conduct Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment free experience for everyone, regardless of age, body size, visible or invisible disability,

Contributing to MLX Swift

Contributing to MLX Swift We want to make contributing to this project as easy and transparent as possible. Pull Requests 1. Fork and submit pull requests to the repo. 2. If you've added code that should be tested, add tests. 3. If you've c

Maintenance Tasks

Maintenance Tasks Updating Documentation 1. git checkout gh pages 2. git rebase main 3. update Source/MLX/Documentation.docc/Resources/mlx examples swift.zip as needed 4. ./tools/build documentation.sh 5. git add docs 6. git commit docs 7.

MLXArray Reference

MLXArray Reference MLXArray is the fundamental data type in MLX Swift, representing multi dimensional arrays on Apple Silicon. Creating Arrays From Swift Values Factory Methods Random Arrays Use MLXRandom namespace or free functions: Data T

Swift Concurrency Reference

Swift Concurrency Reference MLX Swift has specific concurrency characteristics for thread safety on Apple Silicon. Key Concurrency Facts MLXArray is NOT Sendable MLXArray is intentionally not Sendable . This is by design: Why? MLXArray cont

Custom Metal Kernels Reference

Custom Metal Kernels Reference MLXFast allows you to write custom Metal compute kernels for operations not covered by built in functions. Basic Metal Kernel Kernel Parameters metalKernel Function Kernel Execution Metal Shader Syntax Availab

Custom Layers Reference

Custom Layers Reference Guide to creating custom neural network layers in MLX Swift. Basic Custom Layer Using @ModuleInfo For layers containing sub modules, use @ModuleInfo to enable updates and quantization: Custom Parameter Keys Conformin

Deprecated APIs and Migration Guide

Deprecated APIs and Migration Guide This guide covers deprecated APIs in MLX Swift and their modern replacements. Module Consolidation The following standalone modules have been deprecated. Their functionality is now available in the main M

Neural Networks Reference

Neural Networks Reference The MLXNN module provides neural network layers built on top of MLX arrays. Module Base Class All layers inherit from Module : Key Module Methods Property Wrappers @ModuleInfo Use for sub modules to enable updates

Array Operations Reference

Array Operations Reference MLX provides NumPy like operations with automatic broadcasting and lazy evaluation. Arithmetic Operations Basic Math More Arithmetic Trigonometric Exponential and Logarithmic Comparison Operations Element wise Log

Optimizers Reference

Optimizers Reference MLXOptimizers provides gradient based optimization algorithms for training neural networks. Optimizer Protocol All optimizers conform to the Optimizer protocol: Basic Usage SGD Stochastic Gradient Descent with optional

Transforms Reference

Transforms Reference MLX provides powerful function transforms for automatic differentiation, vectorization, and JIT compilation. Automatic Differentiation grad Compute Gradients valueAndGrad Value and Gradient Together Model Gradients For

Wired Memory Management Reference

Wired Memory Management Reference MLX Swift includes a process wide wired memory coordinator for concurrent GPU workloads. Core Types WiredMemoryManager : coordinates wired limit updates and admission control. WiredMemoryTicket : a handle r

MLX Swift Framework

name: swift mlx description: MLX Swift High performance ML framework for Apple Silicon with lazy evaluation, automatic differentiation, and unified memory triggers: mlx mlx swift mlx array apple silicon ml neural network swift automatic dif

MLX Swift skill

MLX Swift skill This repo ships an MLX Swift skill definition under skills/mlx swift/ (the skill.md file plus references/ ). The install folder name can be mlx swift , as shown below. If your local copy lives at skills/mlx swift , just swap

Numpy Style Broadcasting

Numpy Style Broadcasting How different size arrays can be used together. MLX uses Numpy style broadcasting: Numpy Documentation Here is a brief excerpt on how numpy describes this: Numpy: The term broadcasting describes how NumPy treats arr

Compilation

Compilation MLX has a compile(inputs:outputs:shapeless: :) ([Updatable],[Updatable],Bool,([MLXArray]) [MLXArray]) function transformation which compiles computation graphs. Function compilation results in smaller graphs by merging common wo

Converting From Python

Converting From Python Common patterns from python and mapping mlx function names. Indexing MLXArray supports all the same indexing (see ) as the python mx.array , though in some cases they are written differently. In all cases both MLXArra

Lazy Evaluation

Lazy Evaluation Computation in MLX is lazy. Understand when the graph is evaluated. See also mlx python docs. Why Lazy Evaluation When you perform operations in MLX, no computation actually happens. Instead a compute graph is recorded. The

Running on iOS

Running on iOS Considerations for running on iOS and general memory tuning. Controlling Memory Use iOS devices have a feature called jetsam which will terminate processes if they use too much memory. Models may take several gigabytes for th

Unified Memory

Unified Memory MLX takes advantage of the shared memory between the CPU and GPU. Discussion See also mlx python docs. Apple silicon has a unified memory architecture. The CPU and GPU have direct access to the same memory pool. MLX is design

Using Streams

Using Streams Controlling where your computations are evaluated. Specifying the Stream All operations (including random number generation) take an optional argument stream . The stream specifies which Stream the operation should run on. If

Vectorization

Vectorization Automatic vectorization with vmap( :inAxes:outAxes:) . vmap transforms a function so that it operates independently over a batch axis. This is convenient for evaluating a function over many inputs without writing explicit loop

Wired Memory Management

Wired Memory Management Coordinate a process wide wired memory limit for GPU workloads. Overview Wired memory is a global process setting. MLX exposes a coordinator that lets multiple concurrent tasks agree on a single wired limit while sti

MLX Swift Examples

MLX Swift Examples Swift example code for MLX and MLXNN. @Metadata { @CallToAction( purpose: download, url: "https://github.com/ml explore/mlx swift examples/archive/refs/heads/main.zip") @PageKind(sampleCode) } Overview Examples using MLX

Free Functions

Free Functions Free functions in MLX. MLX has a wide variety of free functions, categorized below. MLXArray has some identical operations as methods for convenience. Topics Element wise Arithmetic Free Functions abs( :stream:) acos( :stream

Installation

Installation How to install and use. MLX is meant to be built and run from Xcode or SwiftPM. Xcode In Xcode you can add https://github.com/ml explore/mlx swift as a package dependency and link MLX , MLXNN and MLXRandom as needed. SwiftPM To

``MLX``

MLX MLX Swift is a Swift API for MLX. MLX is an array framework for machine learning on Apple silicon. MLX Swift expands MLX to the Swift language, making research and experimentation easier on Apple silicon. The Swift API closely follows t

``MLX/MLXArray``

MLX/MLXArray An N dimensional array. The main type in mlx . Introduction MLXArray is an N dimension array that can contain a variety of data types ( DType ). MLXArray supports a wide range of functions and operations to manipulate it and is

Arithmetic

Arithmetic MLX supports a wide range of binary arithmetic operators. Many of the operations are avilable as infix operators (e.g. '+') or as functions, either on MLXArray itself or as free functions. There are also a wide variety of element

Conversion

Conversion Conversion functions. Topics Conversion Functions MLX has several functions to support converting between DType : MLXArray/asType( :stream:) (HasDType.Type,StreamOrDevice) MLXArray/asType( :stream:) (DType,StreamOrDevice) MLXArra

Convolution

Convolution Convolution operations. Topics Convolution Functions MLX has several functions to support convolutions: conv1d( : :stride:padding:dilation:groups:stream:) conv2d( : :stride:padding:dilation:groups:stream:) conv3d( : :stride:padd

Cumulative Operations

Cumulative Operations Operations that produce a cumulative result. There are a number of functions that can produce a cumulative result. For example: These are available as both methods on MLXArray and free functions. They each have options

Indexes

Indexes Functions to produce and consume array indexes. MLX has a number of functions (typically named argX() ) that can produce array indices and a few functions that can consume them. Topics Index Producing Functions MLXArray/argMax(keepD

Indexing

Indexing Array subscripts. MLXArray supports all the same indexing (see ) as the python mx.array , though in some cases they are written differently. In all cases both MLXArray and mx.array indexing strive to match numpy indexing. The full

Initialization

Initialization Creating MLXArrays. Scalar Arrays A scalar MLXArray is created from a scalar and has zero dimensions: If an MLXArray of a different type is needed there is an initializer: Sometimes scalars can be used in place of arrays (no

Logical Operators

Logical Operators Evaluating logical operations on MLXArray. MLXArray has a number of logical operators, instance methods and free functions. Single or multiple arrayscan be combined using these operators: These can be used for control flow

Reduction Functions

Reduction Functions Reduction or aggregation functions. MLX has a number of functions to reduce or aggregate data in MLXArray . These functions typically work over one or more axes, though there are overloads where the axis can be omitted a

Shapes

Shapes Shape is a term to describe the number and size of the dimensions of an N dimension (ND) array. MLXArray is an N dimensional array. The number of dimensions is described by MLXArray/ndim and the size of each dimension can be examined

Sorting

Sorting Sorting and partitioning values and indices. MLX has a number of methods that produce an array of indexes, including for sorting and partitioning: There are other methods that produce a new sorted or partitioned array: See related i

Troubleshooting

Troubleshooting Help with problems you might run into. Installation See for more information. If you use Xcode or SwiftPM to reference the package on github.com there should be no manual steps. If you clone the mlx swift repository yourself

Activation Functions and Layers

Activation Functions and Layers Built in activation functions and layers. MLXNN provides a number of activation functions and modules. The modules simply wrap the functions, though some like GELU provide some settings that select between di

Creating Modules

Creating Modules Creating custom modules using MLXNN . Neural Networks Writing arbitrarily complex neural networks in MLX can be done using only MLXArray and valueAndGrad() . However, this requires the user to write again and again the same

Layers

Layers Built in layers. MLXNN provides a number of built in layers that can be used to build models. See also for Activation Layers and for examples of their use Topics Unary Layers Layers that provide an interface that takes a single MLXAr

Loss Functions

Loss Functions Built in loss functions Topics Loss Functions binaryCrossEntropy(logits:targets:weights:withLogits:reduction:) cosineSimilarityLoss(x1:x2:axis:eps:reduction:) crossEntropy(logits:targets:weights:axis:labelSmoothing:reduction:

``MLXNN``

MLXNN Neural Networks support for MLX Overview Writing arbitrarily complex neural networks in MLX can be done using only MLXArray and valueAndGrad() . However, this requires the user to write again and again the same simple neural network o

``Module``

Module Topics Parameters Module/apply(filter:map:) Module/filterMap(filter:map:isLeaf:) Module/mapParameters(map:isLeaf:) Module/parameters() Module/trainableParameters() Module/update(parameters:) Module/update(parameters:verify:) Layers (

Module Filter and Map Functions

Module Filter and Map Functions Pre built filter and map functions in Module . Module provides a number of pre build filter and map functions for use in: Module/filterMap(filter:map:isLeaf:) Module/apply(filter:map:) Module/mapParameters(ma

Normalization

Normalization Built in normalization layers Topics Normalization Layers InstanceNorm LayerNorm RMSNorm GroupNorm BatchNorm

Positional Encoding

Positional Encoding Built in layers for positional encoding. Topics Positional Encoding Layers RoPE SinusoidalPositionalEncoding ALiBi

Training a Model

Training a Model A model training loop. The model training loop in MLX consists of: defining a model defining a loss function that measures the distance between predicted and expected values using the valueAndGrad(model: :) 12a2c function t

Transformer

Transformer Built in transformer layers Topics Transformer Layers MultiHeadAttention Transformer

``MLXOptimizers``

MLXOptimizers Built in optimizers. MLX has a number of built in optimizers that are useful for training models. Here is a simple training loop: Other MLX Packages MLX MLXNN Python mlx Topics Optimizers AdaDelta Adafactor AdaGrad AdamW Adam

NeuCodec MLX Swift

    ![LinkedIn](https://www.linkedin.com/compan

Jinja

Jinja A Swift implementation of the Jinja2 template engine. Jinja templates are widely used for generating HTML, configuration files, code generation, and text processing. This implementation is focused primarily on the features needed to g

README

    ![LinkedIn](https://www.linkedin.com/compan

Swift UI

Reusable Swift UI foundations.

EasySkeleton

EasySkeleton   Fast and lightweight skeleton framework for S

Wisent AI system map

Wisent AI system map This is the cross repo index. Detailed implementation docs stay in the owning repos. CI/CD and deployment pipeline ownership is indexed separately in CI/CD and deployment pipeline map. Branch protection coverage is inde

wisent-ground-truth-api

    ![LinkedIn](https://www.linkedin.

Brand assets: logos, favicons, icons, fonts

Brand assets: logos, favicons, icons, fonts Generated from a visible wisent ai GitHub tree scan on 2026 07 01. Current state There is no central ground truth resolver for logos, favicons, app icons, fonts, OpenGraph images, or brand assets

Wisent Quality Control

    ![LinkedIn](https://www.linkedin.com/company/wise

Service readiness

Service readiness A cross repo rule. Every Wisent service exposes a health route, and every deployment script in this organization treats one as a verdict. Rule 1 — liveness and readiness are different questions GET /health answers whether

Transcript Label Trainer

    ![LinkedIn](https://www.linkedi

Wisent models and runtimes

Canonical model architecture, evaluation, optimization, and Swift ML runtime guides.

Image-to-video generation

Wan 2.2 Image to Video Pipeline A complete pipeline for generating videos from images using Wan 2.2 14B I2V with physics optimized LoRAs. Components Pipeline Files File Description i2v pipeline.py Main Python pipeline script i2v config.json

Contrastive Activation Addition

Steering Llama 2 with Contrastive Activation Addition Setup Then create a .env file with the Hugging Face credential shown in .env.example . Datasets All raw and processed data can be seen in /datasets . Original sources are listed below. T

Rej-1B

Rej 1B A reference implementation of Rej 1B , a Representation Native Language Model (RNM) with an explicit concept stream. Key idea: concepts are not a post hoc decomposition of hidden states; they are a separate computational state that r

wisent-continual

    ![LinkedIn](https://www.linkedin.com/company/wi

Documentation

     ![

Individual Contributors

Individual Contributors If you wish to be acknowledged for your contributions, please list your name with a short description of your contribution(s) below. For example: Jane Smith: Added the foo and bar ops. MLX Swift was developed with co

LLMEval

LLMEval An example that: downloads a huggingface model (phi 2) and tokenizer evaluates a prompt displays the output as it generates text You will need to set the Team on the LLMEval target in order to build and run on iOS. Some notes about

LoRATrainingExample

LoRATrainingExample Example application that: downloads the mlx community/Mistral 7B v0.1 hf 4bit mlx model from huggingface loads the train/valid/test data from $SRCROOT/Data/lora (this is copied into the build but you can imagine how it m

MLX Chat Example

MLX Chat Example A lightweight chat application demonstrating MLX integration for iOS and macOS. Built with SwiftUI, this example project shows how to implement both Large Language Models (LLMs) and Vision Language Models (VLMs) using MLX.

MNISTTrainer

MNISTTrainer This is an example of model training that works on both macOS and iOS. The example will download the MNIST training data, create a LeNet, and train it. It will show the epoch time and test accuracy as it trains. You will need t

StableDiffusionExample

StableDiffusionExample An example application that runs the StableDiffusion example code. See also image tool for a command line example. This example application accepts a prompt and used the StableDiffusion example library to render an im

VLMEval

VLMEval An example that: downloads a vision language model (Qwen VL 2B) processes an image with a prompt You will need to set the Team on the VLMEval target in order to build and run on macOS. Some notes about the setup: This downloads mode

Contributor Covenant Code of Conduct

Contributor Covenant Code of Conduct Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment free experience for everyone, regardless of age, body size, visible or invisible disability,

Contributing to MLX Swift Examples

Contributing to MLX Swift Examples We want to make contributing to this project as easy and transparent as possible. Pull Requests 1. Fork and submit pull requests to the repo. 2. If you've added code that should be tested, add tests. 3. Ev

MLXEmbedders

MLXEmbedders This directory contains ports of popular Encoders / Embedding Models. Usage Example Ported to swift from taylorai/mlx embedding models

Adding a Model

Adding a Model If the model follows the typical LLM pattern you can add a new model in a few steps. config.json , tokenizer.json , and tokenizer config.json .safetensors You can follow the pattern of the models in the Models directory and c

Evaluation

Evaluation The simplified LLM/VLM API allows you to load a model and evaluate prompts with only a few lines of code. For example, this loads a model and asks a question and a follow on question: The second question actually refers to inform

MLXLLM

MLXLLM Documentation Porting and implementing models MLXLLMCommon common API for LLM and VLM MLXLLM large language model example implementations MLXVLM vision language model example implementations Contents This is a port of several models

``MLXLLM``

MLXLLM Example implementations of various Large Language Models (LLMs). Other MLX Libraries Packages MLXEmbedders MLXLLM MLXLMCommon MLXMNIST MLXVLM StableDiffusion Quick Start See . Using LLMs and VLMs is as easy as this: More advanced API

Using a Model

Using a Model Using a model is easy: load the weights, tokenize and evaluate. There is a high level API described in and this documentation describes the lower level API if you need more control. Loading a Model A model is typically loaded

MLXLMCommon

MLXLMCommon Documentation Porting and implementing models MLXLLMCommon common API for LLM and VLM MLXLLM large language model example implementations MLXVLM vision language model example implementations Quick Start Using LLMs and VLMs from

Porting Models

Porting Models There are a number of ways to implement new models in MLX in Swift: Build from scratch Port from other ML frameworks MLX Documentation Port from existing MLX models in Python This document talks primarily about the latter. Po

``MLXLMCommon``

MLXLMCommon Common language model code. Other MLX Libraries Packages MLXEmbedders MLXLLM MLXLMCommon MLXMNIST MLXVLM StableDiffusion

MNIST

MNIST This is a port of the MNIST training code from the Python MLX example. This example uses a LeNet instead of an MLP. It provides code to: Download the MNIST test/train data Build the LeNet Some functions to shuffle and batch the data S

MLXVLM

MLXVLM Documentation Porting and implementing models MLXLLMCommon common API for LLM and VLM MLXLLM large language model example implementations MLXVLM vision language model example implementations Quick Start Using LLMs and VLMs from MLXLM

Stable Diffusion

Stable Diffusion Stable Diffusion in MLX. The implementation was ported from Hugging Face's diffusers and mlx examples/stable diffusion. Model weights are downloaded directly from the Hugging Face hub. The implementation currently supports

README

ExampleLLM

ExampleLLM An example that uses the simplified APIs to load and evaluate an LLM in only a few lines of code: See various READMEs: MLXLMCommon common LM code MLXLLM large language models MLXVLM vision language models Building Build the Examp

LinearModelTraining

LinearModelTraining A command line tool that creates a Model that represents: f(x) = mx + b and trains it against an unknown linear function. Very simple but illustrates: a very simple model with parameters a loss function the gradient use

llm-tool

llm tool See various READMEs: MLXLMCommon common LM code MLXLLM large language models MLXVLM vision language models Building Build the llm tool scheme in Xcode. Running: Xcode To run this in Xcode simply press cmd opt r to set the scheme ar

mnist-tool

mnist tool See the MNIST README.md. Building mnist tool has no dependencies outside of the package dependencies represented in xcode. When you run the tool it will download the test/train datasets and store them in a specified directory (se

wisent-model

    ![LinkedIn](https://www.linkedin.com/company/wisent ai/

Model Testing Suite

Model Testing Suite This directory contains comprehensive tests for evaluating and comparing baseline and RL trained conversation models. Test Files test phrases.json Contains test phrases organized by content type: sexual content : Sexuall

wisent-nurt

    

wisent-optimizer

wisent optimizer Hyperparameter optimization for wisent steering methods, using Optuna and hyperopt. Split out of wisent open source. Provides wisent.core.control.steering optimizer . Install Versioning The public contract of this package i

wisent-przelom

    ![LinkedIn](https://www.linkedin.com/company/wisent

wisent-szlak

    ![LinkedIn](https://www.linkedin.com/company/wisent ai/

wisent-titan

    ![LinkedIn](https://www.linkedin.com/company/wisent ai/

wisent-uncensored-model

    ![LinkedIn](https://www.linkedin.

wisent-wicher

    ![LinkedIn](https://www.linkedin.com/company/wisent a

Wisent Components

    ![LinkedIn](https://www.linkedin.com/company/

The Wisent application shell

The Wisent application shell WisentAppShell.swift ships the layer above the tokens: the shell every Wisent desktop application shares, and the ten rules that make ten applications look like one product without making them say the same thing

The Wisent documentation system

The Wisent documentation system One record of what Wisent product documentation is, how every site is structured, and how the system evolved. The layout convention lives in this repository as DocumentationLayout ; the content lives with eac

Changelog

Changelog Unreleased Every registered Figma component now has a generated literal runtime tree. WisentFigmaComponent renders source bounds, nesting, copy, paints, typography, effects, and referenced image fills; node level overrides keep pr

Wisent AI Product Guidelines

    ![LinkedIn](https://www.linkedin.com/company

Core Functionality Guidelines

Core Functionality Guidelines Core functionality implements the product promise established by the README and the first successful journey established by onboarding. It comes after the release and onboarding contracts so implementation has

Documentation Guidelines

Documentation Guidelines Product documentation is the reader facing site at https:// .wisent.com/docs . It is not the README (the product contract), not onboarding (first success in the repository), and not marketing (the landing page above

Examples Guidelines

Examples Guidelines Examples are a required product surface. They translate the contracts in the README, onboarding, core, and integrations into complete tasks a user can execute and understand. A feature, command, API operation, integratio

Hierarchy of Product Creation

Hierarchy of Product Creation Product work must follow a fixed sequence. Each stage defines the contract for the stages that follow it. A later stage must not begin until the preceding stage is complete and internally consistent. If an earl

Adaptive README Template

Adaptive README Template This is a decision oriented guide for public product READMEs, not a mandatory table of contents. It combines recurring reader expectations from the open source reference catalog with Wisent's stricter requirements f

Integration Guidelines

Integration Guidelines Integrations are built only after core functionality is complete and stable. They connect the product to external tools, providers, services, protocols, or ecosystems without redefining the product's core behavior. An

Onboarding Guidelines

Onboarding Guidelines Onboarding is designed after the product promise and release model, but before core functionality. It defines how a person or system moves from zero knowledge and zero configuration to the first successful product outc

Onboarding Product Inventory

Onboarding Product Inventory This inventory classifies every repository in the Wisent name register. It controls which onboarding contract applies; it does not claim that the required journey already exists. Contract classifications: human

README Best Practices from the Reference Catalog

README Best Practices from the Reference Catalog This document turns the curated open source README examples into practical guidance for Wisent repositories. It complements the normative README Guidelines: the catalog shows effective public

README Guidelines

README Guidelines The README is the first product artifact. It defines what the product is before release mechanics, onboarding, implementation, integrations, examples, or verification artifacts are created. A README is not a retrospective

Release and Versioning Guidelines

Release and Versioning Guidelines Release and versioning rules are defined immediately after the README. A product must be identifiable, reproducible, upgradeable, and recoverable before onboarding or core functionality is treated as stable

Testing Guidelines

Testing Guidelines Tests are created after the README, release model, onboarding, core functionality, integrations, and canonical examples have defined the product's observable contracts. Tests defend those contracts; they do not invent the

Wisent Errors

Stable, cross-runtime error envelopes and integration contracts.

The boundary

The boundary What wisent errors owns, and what it deliberately does not. The package decides the content of a failure report — the vocabulary, the shape, the derived fields, the trim rule — and almost nothing else. Everything on the far sid

The catalogue

The catalogue catalogue/codes.json (version 1) is the single source of truth for the fleet's failure vocabulary. codegen/generate.mjs is what turns it into code, and the generated modules are the only copies the runtimes carry. The tables o

Code

Code A code is the classification of a failure: one of exactly seven lowercase strings, declared in catalogue/codes.json and carried by every envelope as error code . Everything mechanical about a failure — severity, retryability, the outag

Envelope

Envelope The envelope is the one shape every Wisent component reports failures in. schema/failure.schema.json (draft 2020 12, $id https://wisent.ai/schema/failure.v1.json ) states it, checkable from any language. The fields answer, in order

Failure point

Failure point failure point is where it broke: a dotted lowercase path, one segment or more, chosen by the call site. It is the first field of every envelope and the first thing a reader greps for. The package owns only the shape of a failu

HTTP status and exit code

HTTP status and exit code Two derivations turn a code into numbers the outside world reads: the HTTP status a service answers with at its edge, and the exit code a command leaves the process with. Both live in the catalogue ( http status pe

Outage flag

Outage flag outage is a boolean on every envelope: is our side broken, as opposed to the request being wrong? It is derived from the code, never chosen at a call site. It answers the first question an operator asks of any failure line — our

Report

Report A report is a failure leaving the process that classified it. The package ships three report surfaces: render (one line for a human and machines at once), chain (the cause chain flattened for a reader in a hurry), and — for Swift des

Retryability

Retryability retryable is a boolean on every envelope: is it worth running the same thing again, unchanged? It is derived from the code, never chosen at a call site, and it is the one derived field that changes behaviour rather than present

Severity

Severity Severity is how loud a failure is: warning , error , or critical — exactly three values, declared once in the catalogue's severities array and derived from the code, never chosen at a call site. The schema's own description of the

Configuration

Configuration The package reads almost nothing from its environment, on purpose: a vocabulary that behaves differently per machine is not a vocabulary. The complete list — two environment variables and one file, all read by the Swift Wisent

Conformance

Conformance Four runtimes are one behaviour only because a harness proves it, byte for byte, on every change. This page is the proof machinery: the golden cases, the vocabulary probes, the harness that compares runtimes against each other,

Integrating the JavaScript runtime

Integrating the JavaScript runtime The npm package is @wisent/errors , defined by the package.json at the repository root — deliberately at the root, because npm has no way to install from a subdirectory of a git repository. Two entry point

Integrating the Python runtime

Integrating the Python runtime The package is wisent errors (import name wisent errors ), living under python/ — hence the subdirectory in the pip spec. It requires Python ≥ 3.9 and carries zero dependencies. Two modules: wisent errors (bui

Integrating the Rust runtime

Integrating the Rust runtime The crate is wisent errors , in rust/ , reachable as a git dependency because the repository root is a Cargo workspace naming it — without that, wisent errors = { git = "..." } would fail to find a crate that si

Integrating the Swift runtime

Integrating the Swift runtime The SwiftPM package is wisent errors , its Package.swift at the repository root so a dependency resolves; the product is the WisentErrors library (target under swift/Sources/WisentErrors ). Platforms: macOS 13,

Integrating a product

Integrating a product How does a product adopt the envelope? Pin the package at an exact commit, delete the local vocabulary and derived tables, route what the product already decides through arguments, and run the guard that keeps the enve

Quick start

Quick start How do you emit your first envelope? Pin the package at an exact commit, import your runtime, and build one failure. Every runtime is dependency free on purpose — no serde, no validator, no npm tree — so adoption costs one depen

JavaScript API reference

JavaScript API reference Package @wisent/errors ( js/index.mjs , types in js/index.d.ts ); subpath @wisent/errors/codes ( js/codes.mjs , types in js/codes.d.ts ) exports the generated catalogue module alone. The main module re exports every

Python API reference

Python API reference Package wisent errors , import name wisent errors , under python/ ( pyproject.toml there; hence #subdirectory=python in the pip spec). Python ≥ 3.9, zero dependencies. Two modules: wisent errors (builders, render, chain

Rust API reference

Rust API reference Crate wisent errors , in rust/ , named by the root Cargo workspace so a git dependency resolves. Edition 2021, zero dependencies — no serde; serialization is hand rolled in the schema's key order. All refusal sentences be

Swift API reference

Swift API reference SwiftPM package wisent errors (manifest at the repository root), library product WisentErrors , target under swift/Sources/WisentErrors . Platforms macOS 13 / iOS 13, zero dependencies. All refusal sentences below are th

Tools reference

Tools reference Five node scripts, no dependencies. Two run in this repository ( generate , check ); one is the harness they both lean on ( conformance ); two run against other trees ( no handrolled envelope , find implementations ). Every

Runbook

Runbook What red looks like, captured for real. Every failure below was produced by breaking a scratch copy of this repository and running the gate — nothing here is imagined output. Make such a copy the same way when you need to reproduce

The four runtimes

The four runtimes One catalogue, four languages. Each runtime is a generated codes module — written by codegen/generate.mjs , committed, never edited by hand — plus a hand written envelope module around it. All four carry zero dependencies

Walkthrough: adopting the envelope on a service

Walkthrough: adopting the envelope on a service One toy service, shelf , taken from a hand rolled failure object to the fleet envelope, end to end: guard before, migrate, guard after, then real requests against its edge with the captured an

Walkthrough: proving a checkout

Walkthrough: proving a checkout What "the four runtimes are one behaviour" looks like when you actually run it. Every output block below is a verbatim capture from this repository on a machine with node , python3 , cargo , and swift install

What is wisent-errors

What is wisent errors One failure envelope for the whole Wisent fleet: one vocabulary of seven codes, one shape, one place to look a code up. Four runtimes — Rust, Python, JavaScript, Swift — are generated from one catalogue and proven byte

Wisent SDKs

Client examples, environment APIs, and cross-runtime error contracts.

KantBench OpenEnv API

KantBench: 93 Game Theory Environments for LLM Training A comprehensive game theory environment for training and evaluating LLM strategic reasoning via OpenEnv. Supports GRPO/DPO training with the environment as a reward oracle. Games (93)

Wisent Examples

Wisent Examples This directory contains examples and tutorials for using the Wisent library. Command Line Examples Extract Activations Extract activations from a model and optionally upload them to the Wisent backend: Control Vector Inferen