Embedding in Go programs

Use gligabao as a Go library through the root package.

gligabao is also a Go library. All server code is under internal/ (not importable); the public API is the root package github.com/deepblue-phoenix/gligabao, which the CLI (cmd/gligabao, internal/cli) itself uses, so embedded and standalone behave the same.

import "github.com/deepblue-phoenix/gligabao"

cfg, err := gligabao.LoadConfig("gligabao.toml") // or gligabao.DefaultConfig()
if err != nil { /* ... */ }
err = gligabao.Serve(ctx, cfg, gligabao.ServeOptions{DBPath: "data/gligabao.db"})

API

Config / Price

The configuration described in Configuration. DefaultConfig() takes API keys from the environment, and fields can be set in code instead of a TOML file.

ServeOptions

DBPath (default build/gligabao.db), VectorDir (the chromem directory; default <name>.vectors next to DBPath), ImageDir (image files; default <name>.images next to DBPath) and TrainingDatasetDir (the training datasets directory: one subdirectory per dataset with a dataset.toml manifest, see Training datasets; datasets uploaded through the server or the admin UI are saved there too; default a datasets_training directory next to DBPath), the equivalents of serve --db / --vector-dir / --image-dir / --training-dataset-dir; TrainedModelDeployDir is the directory trained models’ files are fetched to for an deploy (one subdirectory per job, never deleted by gligabao; default a trained_models directory next to DBPath, i.e. build/trained_models), serve --trained-model-deploy-dir.

TimeseriesProviders

The timeseries providers remember can fetch from. Each is a gligabao.TimeseriesProvider{Name, Description, QueryFormat, Fetch}: Description says in natural language when the provider applies (an LLM reads it), Fetch is your callback that returns the series.

GeoResolver

Finds the coordinates of the places remember extracts as entities: any gligabao.GeoResolver (Name, and Resolve that returns the best GeoPlace for a GeoQuery, or gligabao.GeoNotFound). Setting it turns the geo stage of remember on, whatever Config.Geo says; with Config.Geo and no GeoResolver, the public Nominatim geocoder of OpenStreetMap is used. See Geo.

Hooks

Callbacks gligabao invokes, today the system-event hook (called after every remember, query and timeseries request, with counts and timings). See Hooks.

TrainedModelDeployers

The hooks that deploy a trained model: each is a gligabao.TrainedModelDeployer{Name, Deploy}. gligabao fetches the model’s files to a local directory and calls Deploy with it (POST /v1/gb/training/models/{id}/deployments). See Model deploying.

AdminExtensions

Extensions of the admin UI: each is a gligabao.AdminExtension{Name, Assets, Handler}, browser files (an index.js ES module that adds views and buttons/blocks to the admin page) and an optional HTTP handler of its own. Served only with the admin UI on. See Admin UI extensions.

Serve(ctx, cfg, opts)

Blocks until ctx is cancelled or SIGINT/SIGTERM arrives, then shuts down gracefully. A nil cfg means DefaultConfig().

Mount(ctx, cfg, opts, mount)

Registers gligabao’s handlers on your own *http.ServeMux instead of starting a server on its own port. A nil cfg means DefaultConfig(). See Mounting on your own HTTP server.

Mounting on your own HTTP server

Serve starts gligabao’s own HTTP server on the config’s port. A program that already runs an HTTP server (a gloflow gf_solo, say) can instead have gligabao register its handlers on the program’s *http.ServeMux and serve them on its own port, with no second server and no second port.

mux := http.NewServeMux() // the host's mux, with the host's own routes
release, err := gligabao.Mount(ctx, cfg, gligabao.ServeOptions{DBPath: "data/gligabao.db"}, gligabao.MountOptions{
    Mux: mux,
    Wrap: func(next http.Handler) http.Handler { return requireAuth(next) }, // optional
})
if err != nil { /* ... */ }
defer release()
// ... http.ListenAndServe(":8080", mux), and call release after the host's server has shut down

• It takes the same Config and ServeOptions as Serve (providers, deployers, hooks, admin extensions, directories, …). Mount does the whole setup itself (databases, sidecar check, remember manager, …) and returns once the handlers are registered, so call it before the host starts serving. It does not block and does not handle SIGINT/SIGTERM: the host owns the process.
• All routes are registered as one subtree, gligabao.MountPrefix (/v1/gb/): the API and, when the config enables them, the admin UI (/v1/gb/admin/) and the eval and training endpoints. They are registered per method (GET /v1/gb/, POST /v1/gb/, …), so they do not conflict with a host’s GET /. The host must not have routes of its own under /v1/gb/: Mount returns an error, not a panic, if it has.
• gligabao’s own /, /health and /version are not registered, they belong to the host, and an unknown path under /v1/gb/ is a plain 404. The config’s port is not used.
• release stops the remember manager and closes the databases. It is idempotent, and is also called when ctx is cancelled. Call it after the host’s server has shut down; after it the mounted routes answer 503. The Hooks and App of ServeOptions are installed until then.
• MountOptions.Wrap wraps the whole handler before it is registered. It covers the MCP endpoint (/v1/gb/mcp, when mcp is on) as well.

gligabao has no access control of its own (standalone it is meant to run on a private port). Mounted on a public server, its API and admin UI are as public as that server: use Wrap to put the host’s authentication in front of them.

Serve, the gligabao CLI and the standalone gligabao_int are unchanged and keep running on their own port. gligabao_int/gligabao_int_embed has EmbedMount, the counterpart of its Embed that mounts instead of listening.

gligabao needs no CGO, so the embedding program can be built with CGO_ENABLED=0. A working example with a cobra serve command is in the sibling gligabao_int project, which uses replace github.com/deepblue-phoenix/gligabao => ../gligabao during local development. Programs can pass their own version in ServeOptions.App, and get gligabao.Version().