oxibonsai for 4D

Overview / Integration guide

Run the OxiBonsai local HTTP server from 4D 20+.
This repository is the MIT-licensed 4D component and its build/packaging integration,
not the upstream inference engine. The upstream Rust engine is Apache-2.0 licensed.

The documentation site adopts the shared local inference site design v1.0.0,
with oxibonsai's own branding and capabilities. Guideline updates are reviewed
centrally
and adopted explicitly here; there is no shared runtime stylesheet or dependency.
The sidebar and stack use assets/icon.png, copied unchanged from
oxibonsai/Resources/icon.png; the favicon and touch icon are resized versions
of that resource, not replacement artwork. Preview the site with
bundle exec jekyll serve --destination .build/site and open
http://127.0.0.1:4000/oxibonsai/. Check the overview and guide in light and dark
mode at 1440, 1024, 768, 390 and 320 CSS-pixel widths when changing the layout
or styles. Check keyboard navigation, clipboard feedback, table scrolling,
local links, and the stack layout (beside the hero above 1000px, below otherwise).

Installation and targets

Download a component from Releases,
install the .4dbase in your application's Components folder, and restart 4D.
Source projects declare the miyako/tcp, miyako/workers, and miyako/event
dependencies in oxibonsai/Project/Sources/dependencies.json; resolve these with
4D's dependency manager when using the source project.
Model weights are not included and require separate disk space and RAM.

No Linux component or CUDA-enabled executable is packaged here. Upstream's optional
CUDA, RAG, and other CLI capabilities are not promises of this component's builds.
The wrapper chooses a bundled executable for the current platform, or falls back to
oxibonsai on PATH when that file is absent.

Use from 4D

The example downloads the Bonsai GGUF if needed, then starts the server on
http://127.0.0.1:8080. Use a tokenizer matching your model; the bundled
Resources/models/tokenizer.json is the fallback, not a universal tokenizer.

var $oxibonsai : cs.oxibonsai
var $homeFolder; $modelFolder : 4D.Folder
var $huggingface : cs.event.huggingface
var $huggingfaces : cs.event.huggingfaces
var $event : cs.event.event
var $options : Object

$homeFolder:=Folder(fk home folder).folder(".GGUF")
$modelFolder:=$homeFolder.folder("Bonsai")

$event:=cs.event.event.new()
$event.onError:=Formula(ALERT($2.message))
$event.onSuccess:=Formula(ALERT($2.models.extract("name").join(",")+" started"))
$event.onData:=Formula(MESSAGE(This.file.fullName+":"+String((This.range.end/This.range.length)*100; "###.00%")))
$event.onResponse:=Formula(MESSAGE(This.file.fullName+":download complete"))
$event.onTerminate:=Formula(LOG EVENT(Into 4D debug message; "oxibonsai process terminated"))

$options:={host: "127.0.0.1"; max_seq_len: 8192; pool_size: 1; \
max_concurrent_requests: 4; request_timeout_ms: 60000}

$huggingface:=cs.event.huggingface.new($modelFolder; "prism-ml/Bonsai-8B-gguf"; ["Bonsai-8B.gguf"])
$huggingfaces:=cs.event.huggingfaces.new([$huggingface])
$oxibonsai:=cs.oxibonsai.new(8080; $huggingfaces; $homeFolder; $options; $event)

onSuccess currently means the worker was started, not that model loading
or an HTTP readiness check succeeded. Check GET /health before sending requests;
loading a large model can take time. Call $oxibonsai.terminate() to stop the worker.

If there is nothing to download (no huggingfaces, or none of them resolves to a
file), the server is started with options.model when it is an existing local
4D.File. Otherwise event.onError receives an error with code 2 and the server
is not started. The server is launched at most once per wrapper attempt. event
may be Null (no callbacks are delivered) when nothing needs to be downloaded;
an actual download still requires an event, because the downloader in the
separate event component does not accept Null.

Options and API

Options use underscores; the wrapper converts them to CLI hyphens. The model
downloader supplies model as a 4D.File. Optional tokenizer must also be a
4D.File; omitting it selects the bundled tokenizer.

Keep the loopback binding unless you deliberately configure network access.
bearer_token is forwarded to the server; clients must send
Authorization: Bearer <token>. Upstream also accepts OXIBONSAI_BEARER_TOKEN
from the environment, avoiding a token in process arguments. /health and
/metrics are exempt from bearer authentication; admin endpoints are not.
The CLI loads .env from its working directory or parents; explicit flags take
precedence over the supported environment defaults. In this upstream revision,
serve does not apply the TOML server settings; use the explicit flags above.
Do not put secrets in this repository.

For 4D AI Kit's OpenAI-compatible provider, use base URL
http://127.0.0.1:8080/v1, the model ID returned by GET /v1/models, and
the same bearer token if configured.

Upstream's separate image CLI and oxibonsai-serve binary are not used by this wrapper.
The embeddings endpoint accepts but ignores the requested model name; do not
treat its lexical vectors as learned semantic embeddings from the loaded GGUF.

Reproducible source builds

As checked on 2026-11-02, upstream's latest release is v0.2.3
(published 2026-07-22); its master HEAD and the dereferenced tag both resolve to
1d10c48e14754ff6999158f8fa13c7c92b40b0dc, committed
2026-07-22 09:54:07 UTC. The existing bundled executables already report
0.2.3, but have no recorded build provenance; this update establishes a
source-built packaging path rather than claiming a newer upstream version.

upstream.json pins the commit, package oxibonsai-cli,
binary oxibonsai, target features, and Rust 1.99.0. Upstream declares
Rust >=1.86, but its source repository does not track Cargo.lock; this repository
supplies a resolved lockfile and uses --locked with a pinned newer compiler.
No upstream prebuilt executables are downloaded. Reproducibility here means pinned
source/dependencies/toolchain/features, not a guarantee of byte-identical binaries
across different SDK or linker versions.

Install Python 3.12+, Git, rustup, CMake, and a native C/C++ toolchain (Xcode
command-line tools on macOS; Visual Studio C++ Build Tools and Windows SDK on
Windows). The resolved TLS dependency includes aws-lc-sys, so this build is not
C-toolchain-free even though the inference engine is Rust. On a matching
native host, for example Apple Silicon:

rustup toolchain install 1.99.0 --profile minimal --target aarch64-apple-darwin
python3 scripts/build-server.py --target aarch64-apple-darwin
python3 -m unittest discover -s scripts/tests -v

Use the corresponding target triple from upstream.json on each other host.
The script fetches the exact commit, checks the source is clean, copies the
lockfile, builds release mode with explicit features, checks --version and
serve --help, and writes the executable plus SHA-256 provenance to
.build/server/artifacts/<target>/. It refuses inherited RUSTFLAGS and
CARGO_ENCODED_RUSTFLAGS. Windows builds explicitly set the recorded
-C target-feature=+crt-static so the VC runtime is not an unbundled prerequisite.
For an update, change the pin intentionally, regenerate Cargo.lock using the
pinned Rust toolchain against that source, and rerun all four native builds.
Use a fresh --work-dir when changing the source pin.

The source-build workflow runs on native
macOS ARM/Intel and Windows x64/ARM64 runners. It combines the Mac slices with
lipo, verifies both architectures, checks each artifact's source/lockfile/hash,
audits Mach-O imports and normal/delayed PE imports against system runtimes,
and uploads server-resource-bin with the complete 4D resource layout and
source.json. The upstream license is included in both native artifacts and
the final Resources/bin/UPSTREAM-LICENSE.txt, with its checksum recorded.
Manifest resource paths always use forward slashes, including on Windows.
The lockfile and checked-in license use LF bytes on every platform; the build
exports the upstream license from the pinned Git object rather than a potentially
CRLF-converted working copy. Checksums remain exact byte hashes.
CI uses Python 3.13.17, which has native distributions for all four runners.
For manual staging on macOS, collect the four target artifact
directories and run:

python3 scripts/package-server.py --artifacts .build/native --output .build/bin

Each native binary is smoke-tested on its own runner before universal packaging.
Assembly requires all four targets, exact provenance, system-only runtime closure,
an empty output directory and files strictly smaller than GitHub's 100 MiB limit
(104,857,600 bytes), including the combined universal Mac executable.
Unexpected resources, missing targets and external runtime DLLs fail before
replacement. No Git LFS conversion or partial matrix update is attempted.

Native refresh, then quick component publication

1. Intentionally update upstream.json, Cargo.lock and the upstream license
   together when adopting new source. Run Build server from source for
   read-only validation; PR/push/build-only runs only upload artifacts.
2. After reviewing the source change on main, explicitly run
   Update committed native resources
   from main with update_git=true. This rebuilds the pinned source on all
   four native runners, then verifies and commits/pushes precisely these paths:
   oxibonsai/Resources/bin/macOS/oxibonsai,
   oxibonsai/Resources/bin/Windows/oxibonsai.exe,
   oxibonsai/Resources/bin/WindowsARM/oxibonsai.exe,
   oxibonsai/Resources/bin/UPSTREAM-LICENSE.txt and
   oxibonsai/Resources/bin/source.json. It does not modify models/tokenizers,
   wrapper filenames, other platforms or component version metadata.
3. Review the resulting resource commit, then separately dispatch
   Publish
   on main with the desired component version increment. A GITHUB_TOKEN
   push does not trigger other push workflows. The native updater deliberately
   has no publication dispatch and no actions: write permission.

Configure required reviewers and main branch restrictions for the native-update
and component-publish GitHub environments. Only the gated updater job receives
contents: write; PR/native compilation jobs are read-only and do not receive
deployment secrets. Branch protection must permit the authorized bot's normal
fast-forward push; the updater never bypasses protection, force-pushes, rebases,
or retries against a changed main. Main freshness is checked before replacement
and commit, and a race at push is rejected by Git. Native updates and production
Publish share a non-cancelling concurrency group.

Bootstrap requirement: the old tracked executables have no source.json;
they are preserved, not assigned fabricated build provenance. The first complete
authorized native update must land before the new committed-resource Publish
and component PR compilation gates can pass. The old successful CI artifacts
also require an unbundled vcruntime140.dll on both Windows architectures and
are therefore not suitable for installing under the new contract. Run the new
static-CRT Windows builds rather than copying those artifacts into Git.
For a staged rollout, land the reviewed workflow/scripts/docs first without a
4D source/resource change: these paths do not trigger production Publish.
The native updater does not depend on Publish, the component compile job,
or an existing resource manifest, so it can perform the first refresh on main.
The initial component PR resource check is intentionally red until that verified
resource commit exists; it must not be interpreted as a native build failure or
waived with a legacy-success fallback. Then validate an ordinary 4D-only change
against the committed resources before authorizing a separate Publish dispatch.

Publish has no native build job or native artifact download. Normal 4D-only
changes use the committed resources, validate their checksums/runtime closure
before the version bump, compile 4D, and verify the packaged resources again
before signing. Both hosted and self-hosted modes use the same path; Python
3.12+ and native inspection tools must be available on the packaging host.
PRs compile/validate read-only and can never publish or use the self-hosted runner.
The component version (package.json) is independent of upstream 0.2.3.

The compiler helper is pinned, and component-dependencies.json pins
checksum-verified tcp/workers/event release archives. A structured Compile project
report must contain success: true and an empty diagnostics array; archive
existence alone is not success. Packaging also requires a .4DZ (case-insensitive),
generated Libraries and the unchanged tokenizer. Signing includes every Mach-O
code object, including generated Libraries, not just the CLI. Developer ID team,
timestamp, hardened runtime, notarization Accepted, DMG signing/stapling and
assessment are fail-closed gates. Only afterward are the local version commit and
tag pushed atomically without force and release assets uploaded.

Resources/bin/source.json describes pre-component-signing hashes.
Signing changes executable bytes; Resources/signed-code.json records final
signed code hashes, and the release SHA256SUMS records the final ZIP/DMG bytes.

Building/help checks need no model. Real inference and readiness testing require
a compatible GGUF/tokenizer and sufficient RAM; neither a successful compilation
nor the wrapper's start callback proves inference quality.

Earlier source-build validation (2026-11-02)

Both macOS release targets were built from the pinned source. A universal binary
passed version/help checks on ARM64 and Intel via Rosetta, and both slices
accepted the wrapper's server flags and reported a missing GGUF explicitly.
Eight build/packaging tests, fourteen upstream HTTP/CLI regression tests
(using synthetic tiny models), workflow linting, and the Jekyll site build passed.
This does not validate production-model inference quality or Metal performance.

Windows x64/ARM64 builds require the native Windows CI jobs and were not run on
this Mac; Intel execution here used Rosetta, not physical Intel hardware.
Full 4D compilation/runtime integration and signing/notarization were not
exercised locally (tool4d and deployment credentials were not used).
No production GGUF was downloaded. The Metal dependency block 0.1.6 emits a
Rust future-incompatibility warning; the pinned compiler still builds it.
No release workflow was triggered.

For the build-back-to-Git audit, actual artifacts from successful native run
41401312312 measured 28,355,168 bytes (universal Mac),
13,504,000 bytes (Windows x64) and 11,643,392 bytes (Windows ARM64).
These are measured CI outputs, not the older Git copies and not measurements of
the new static-CRT Windows builds. They demonstrate size headroom only; the
Windows runtime audit above prevents their installation. Each future update
measures its own final files before committing. Local contract tests are not
evidence that unrun Windows builds, 4D compilation or credentialed signing passed.

The new local macOS builds passed version/help and system-library closure checks;
their combined universal executable is 28,354,688 bytes, with both architectures
executed on Apple Silicon (Intel via Rosetta). New static-CRT Windows outputs
remain unrun and unmeasured.

The local 4D check used the same tool4d 20.7 build 20.101905, compiler revision
b73a89a9eac2636f59bcbd020ccf0aad954cab64 and invocation flags as established CI.
With pinned dependencies, it emitted {"success":true,"errors":[]} and generated
a .4DZ, generic compiled code, an ARM64 Library and matching tokenizer.
However, tool4d exited 139 during shutdown on macOS 26.7, including with the
unchanged compiler entry point and with a no-compilation/no-dependency control
method. This local runtime/environment failure is not specific to the new compile
invocation; its precise native crash cause is unresolved. The command's nonzero
exit is not suppressed, so this is not a successful packaging run or evidence
of credentialed signing/notarization. Hosted macOS 15 validation is still required.

Credits and licensing

Engine: cool-japan/oxibonsai, Apache-2.0
(bundled license).
4D integration: miyako/oxibonsai, MIT.
Native workflow conventions follow
llama-cpp,
CTranslate2, and
onnx-genai, adapted to this Rust CLI.