embedded

Antfly Embedded Go Binding

go/pkg/embedded is the first language binding above the stable Zig APIs and the libantfly C ABI. It exposes local databases and database-free inference from the same ABI. Applications can embed .aflite or directory storage without talking to the network SDK.

The Go module includes the matching antfly.h header. Install pkg-config and extract the Apache antfly-embedded release archive for your platform. Keep its lib/ and include/ directories together; lib/pkgconfig/libantfly.pc is relocatable and supplies the library, header, and runtime search paths. No database server or CLI package is required.

export PKG_CONFIG_PATH="/path/to/antfly-embedded/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
go build ./...

The binding uses #cgo pkg-config: libantfly, so this works after go get without paths into the monorepo. If you install into a standard system prefix, your system pkg-config and loader configuration may already find it. The native library must remain installed when running the compiled application.

From a source checkout:

cd zig
zig build capi
export PKG_CONFIG_PATH="$PWD/zig-out/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
cd ../go/pkg/embedded
go test -tags libantfly ./...

Native release libraries are available for Linux and macOS targets in the release archive matrix. Python/npm prebuilt packages currently support Linux x86-64 and ARM64 (glibc 2.28+), and macOS ARM64. Go links native archives directly; it does not install a Python/npm platform package.

The archive relocates before compilation: pkg-config resolves its current installation directory when you build. The resulting runtime search path is absolute, so moving the archive afterward requires rebuilding the application or configuring the system loader. For distribution packages, install the library into the final system prefix and remove the -Wl,-rpath,${libdir} flag from libantfly.pc; use the distribution's loader policy instead.

go vet, gopls, and golangci-lint also run cgo and therefore need pkg-config and the same PKG_CONFIG_PATH configuration as go build. Set that environment in your editor's launch environment as well as your shell. Native builds and tests that link the binding require the actual library. Repository CI's declaration-only vet check generates temporary pkg-config metadata without a library; that setup cannot run or link an application.

Embedded inference

libantfly always links the inference runtime and executes it in-process (see zig/COMPILATION.md's "C API composition" section and zig/LITE.md's "Local Embedded Inference" section). Setting LocalRuntimeConfigured (below) yields local_embedded behavior -- an embedded model runtime that runs chunker, embedder, and extractor producers configured with "provider": "antfly" and no api_url locally instead of failing or requiring a remote URL -- with the standard library and no extra link flags. This makes libantfly a much larger shared library than before inference was embedded by default; there is no smaller inference-free variant to link against instead.

Normal go test ./... does not run the C ABI smoke test. The libantfly build tag means "a built libantfly is available to link"; it is not Lite-specific, because the C ABI itself is storage-neutral. Without it, test binaries would fail at link time, but cgo still requires pkg-config metadata during compilation. Tests that exercise native calls require the actual library.

The open helpers call ValidateABI before filling C option structures or creating handles. Applications can call ValidateABI at startup to fail fast when the loaded libantfly ABI version or antfly_open_options size does not match the header used to build the Go binding.

The binding exposes raw JSON methods such as StatusJSON and CapabilitiesJSON for parity with the C ABI. It also exposes typed Status and Capabilities helpers for stable Lite control fields, including storage identity, inference mode, caller-supplied artifact support, and distributed-only capability flags. Use constants such as InferenceModeCallerSuppliedArtifacts, InferenceModeManualMaintenance, and InferenceModeDisabledDeferred when branching on inference status or capabilities. Typed PendingWorkStats, RunUntilIdleStatus, Check, Compact, Vacuum, CopyStableSnapshot, and CopyStableSnapshotFile helpers cover the stable Lite maintenance reports while keeping the raw JSON methods available. ReplayGeneratedEnrichments recreates generated enrichment work from stored documents after a manual-maintenance or restore pause. Use CheckFile or CheckFileJSON to inspect an invalid, truncated, or corrupted .aflite file without opening a database handle.

Use Create for a new native .aflite writer database and Open for an existing native .aflite writer database. Open does not create missing files or upgrade pre-release Lite layouts; unknown or invalid files fail explicitly. Every Create* variant provisions the default full_text_index_v0 full-text index, matching the server's table-create behavior, so AddIndexJSON is only needed for indexes beyond that default. Use OpenReadonly for read-only query handles and OpenStatusOnly for inspection. Use CreateHosted for a new hosted/manual-maintenance database and OpenHosted for an existing hosted/manual-maintenance database when the application will call RunUntilIdle itself. Use RunUntilIdleStatus when the application also wants the typed post-drain pending-work readiness document. Use CreateWithOptions and OpenWithOptions for advanced settings such as map size, native-profile TTL cleanup, and explicit inference status reporting. Set RemoteProviderConfigured when the embedding producer is backed by a configured remote provider so Status().Inference reports remote_provider instead of the default caller-supplied/deferred mode. Set LocalRuntimeConfigured when the application requests a local inference runtime; Lite reports local_embedded whenever the loaded build advertises LocalInferenceRuntime, which is true by default for the standard libantfly (see "Embedded inference" above).

In-process execution. libantfly runs inference in-process on every backend, including Metal, CUDA, and ONNX -- there is no separate worker process, and ANTFLY_INFERENCE_WORKER is not used by libantfly. A call that has already reached a GPU driver cannot be interrupted: a call_timeout_ms deadline or a Close only takes effect once the call returns on its own, and a driver fault terminates the process (unlike the antfly server, which runs models in a separate, restartable worker process it can kill). Size InferenceOptions/OpenOptions resource budgets and keep concurrent calls bounded accordingly. See zig/LITE.md's "Local Embedded Inference" section for the full rationale.

Embedded inference without a database

Database failures retain an owned native diagnostic in NativeError. Use errors.Is(err, lite.InvalidArgument) (or another stable ErrorCode) to classify failures. The copied detail remains valid after later native calls; Go keeps each native call and diagnostic read on the same OS thread.

When Batch, BatchJSON, or an autocommit SQL write fails with OutcomeUnknown, the error may carry an outcome receipt (NativeError.OutcomeReceipt or SQLError.OutcomeReceipt; read either with lite.OutcomeReceiptOf(err)). Resolve it later on any handle for the same database with db.OutcomeReceiptStatus(receipt), which returns OutcomeReceiptApplied or OutcomeReceiptNotApplied, or Stalled while the uncertain commit is not reconciled yet (Lite: retry; directory database: close the issuing handle and reopen first). Call db.ForgetOutcomeReceipt(receipt) once resolved; afterwards the receipt can no longer be resolved.

OpenInference opens a standalone *Inference handle that runs models with no DB attached -- models load on first use and stay cached until Close. Each method sends and receives the JSON of the matching /ai/v1 route of the Antfly inference HTTP API (see specs/openapi/inference/api.yaml): Embed, Rerank, Chunk, Generate, GenerateBatch, Rewrite, Extract, Read (documents, images, or audio), and ListModels. Generate always returns a complete response; a request with "stream": true fails with InvalidArgument. Use GenerateStream to stream chunks instead.

inf, err := lite.OpenInference(&lite.InferenceOptions{ModelsDir: "/path/to/models"})
if err != nil {
    // Unsupported means this build does not link the inference runtime, or
    // it failed to start.
}
defer inf.Close()

body, err := inf.Chunk([]byte(`{"input":"Ants live in colonies."}`))

Like DB, an *Inference is safe for concurrent use by multiple goroutines, and Close waits for in-flight calls before releasing the handle; calls made after Close return InvalidArgument.

On failure, every JSON method still returns the runtime's JSON error body ({"error": ..., "message": ...}) wrapped in an *InferenceError, alongside the mapped stable ErrorCode (an HTTP 404, such as a model that is not installed, maps to NotFound; 4xx to InvalidArgument; 429/503/504 or an elapsed call timeout to Busy; 501/507, meaning the model does not fit the configured memory budgets, to Unsupported; a Pull or GenerateStream callback returning false, or its ctx becoming done, to Cancelled). Use errors.As for the API error code (e.g. "MODEL_NOT_FOUND") and message, or errors.Is(err, lite.NotFound) for the stable code:

_, err := inf.Embed(request)
var infErr *lite.InferenceError
if errors.As(err, &infErr) {
    log.Printf("inference call failed: %s: %s", infErr.API.Code, infErr.API.Message)
}

Models are not downloaded automatically. Use Pull to fetch a model from the Hugging Face Hub into the handle's models directory, like antfly inference pull. The optional progress callback runs synchronously on the calling goroutine as each file starts, every 16 MiB, and as each file completes:

_, err := inf.Pull(ctx, []byte(`{"model":"owner/name"}`), func(p lite.PullProgress) bool {
    log.Printf("%s: %s %d/%d bytes (cached=%v)", p.Model, p.File, p.BytesDownloaded, p.TotalBytes, p.Cached)
    return true // false stops the pull
})

Pull and GenerateStream both take a context.Context (nil is treated as context.Background()) alongside their own callback-return-value mechanism for stopping early -- the callback returning false, or ctx being done at the point a callback fires, both stop the call, and either way the call returns lite.Cancelled (the ANTFLY_CANCELLED C ABI code). Each progress report is a rendezvous: the call waits for the callback to return before continuing, so cancellation takes effect exactly at the report where the callback returns false (or ctx is observed done) -- for Pull, that can be each file start, every 16 MiB, or each file end (ctx itself is only checked when a report fires, not continuously); for GenerateStream, each streamed chunk. For Pull, files already fully downloaded before cancellation stay staged, so pulling the same model again resumes rather than restarts.

err := inf.GenerateStream(ctx, request, func(chunk []byte) bool {
    // chunk is a "chat.completion.chunk" JSON document; it is only valid
    // during this call, so copy it before returning if you need to keep it.
    return true // false stops generation
})

Concurrency

A *DB is safe for concurrent use by multiple goroutines, like *sql.DB; share one handle rather than opening one per goroutine. libantfly runs in serialized threading mode (ThreadingMode() == ThreadingSerialized). Lite calls queue on a connection and coordinate with other connections to the file. Streaming SQL cursors retain their original snapshots while other connections publish new commits. Schema or index changes wait for in-flight calls. Close waits for in-flight calls; calls after it return InvalidArgument. See zig/CAPI.md "Thread Safety" for the full contract.

Multiple writable Lite connections may remain open, including across processes. Native operations queue within a process and take a kernel writer lease across processes. OpenOptions.BusyTimeout retries admission while another process holds the writer lease or advances the allocator checkpoint. This admission retry never replays a mutation body. Connection lifetimes are independent.

Use BeginTransaction, WriteTransaction, ResolveTransaction, TransactionStatus, and CommitVersion when an embedded application needs the local transaction/OCC path exposed by the Antfly C ABI.

OpenOptions.Storage selects a .aflite file (StorageLite, the default) or a normal Antfly directory (StorageDirectory); every method works on either. CreateWithOptions only creates .aflite files; open a missing directory path to create one.

Use Backup or BackupToFile to write a portable .afb archive of the entire database. Use Restore or RestoreFile to create a new database from one without publishing a partial target on failure; RestoreOptions.Storage selects a .aflite file (the default) or a directory, and a backup of either kind restores into either kind. ImportBackup imports into an empty open database. Use CopyStableSnapshot or CopyStableSnapshotFile when you want a physical .aflite database snapshot rather than a portable .afb backup archive.

From the repository’s zig directory, zig build libantfly builds the Lite CLI and libantfly. Run zig build lite-test for the Lite checks, including the Go binding tests against the built library.

SQL and multiple tables

Importing this package registers the antfly driver with database/sql:

db, err := sql.Open("antfly", "file:/path/app.aflite")
if err != nil { return err }
defer db.Close()
_, err = db.Exec("CREATE TABLE people (id BIGINT PRIMARY KEY, name TEXT)")
_, err = db.Exec("INSERT INTO people (id,name) VALUES ($1,$2)", int64(1), "Ada")
rows, err := db.Query("SELECT id,name FROM people")

Pooled connections have independent SQL sessions. Compatible connections to the same canonical file path share a process storage owner, caches, and maintenance worker. Native operations coordinate writer ownership; busy_timeout_ms in the DSN defaults to 5000. BeginTx uses READ COMMITTED; stronger isolation returns an error. Rows use native streaming cursors, so queries continue beyond 128 rows. Signed 64-bit integers remain int64; SQL NULL becomes nil. JSON parameters can use json.RawMessage, JSON results use []byte, and byte parameters represent UTF-8 text. Errors expose SQLState() and an optional transaction receipt.

The document API uses the same catalog: CreateTableJSON, ListTablesJSON, OpenTable, and DropTable. A table handle supports the existing document, schema, search, index, and enrichment methods. Close table handles before dropping them. Closing the database invalidates its table handles.

Portable .afb archives back up the entire database: its table catalog, schemas, documents, indexes, enrichments, durable resolver merges, and constraint records. Call backup on the database handle. Restore publishes all tables together into either Lite or directory storage; import requires an empty database with no open table handles, SQL sessions, or cursors. Table handles cannot export or import backups.

See the native SQL contract for transaction, savepoint, result-size, and commit-outcome behavior.

Cypher and SQL graph composition

GraphCatalogJSON, CypherJSON, and GraphWriteStatusJSON expose durable named graphs, Cypher queries and mutations, and transaction receipts through libantfly. Catalog requests use action (put, get, list, drop), a graph name, and a definition for puts. Replacement and drop require the current decimal-string expected_revision.

Queries use the same request contract as the server: query, parameters or lossless typed_parameters, optional limits, and write_request_id. Results contain tagged graph values; integer values are decimal strings. Native writes return a commit receipt. Retain the request ID and resolve an unknown outcome through the status method instead of replaying the query. *GraphError preserves the diagnostic code, span, outcome, and transaction ID when available.

Local SQL supports GRAPH_TABLE over these catalogs, including ordinary-table joins and staged SQL rows in an explicit transaction. Graph definitions pin local table and graph-index identities across reopen. Raw embedded calls reject protected tables; authenticated principal queries use the server API.

See the Cypher contract for grammar, mapping, value, mutation, and deployment semantics.

The real local synonym/ANN regression is opt-in with ANTFLY_LITE_EMBEDDING_MODELS_DIR=/path/to/inference/models. It uses that explicit model root (containing Qwen/Qwen3-Embedding-0.6B-GGUF), rather than searching the user's home directory. The Zig CI gate separately downloads the pinned GLiNER base bundle and runs real extraction, promotion, and a public direction: "both" PageRank query. It also downloads the pinned Qwen bundle for a required public Python embedding/promotion/drain/ANN test; Unicode resolver tests run in the ordinary lib-test gate.