> ## Documentation Index
> Fetch the complete documentation index at: https://gligabao.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```go theme={null}
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](https://gligabao.mintlify.site/getting-started/configuration.md). `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](https://gligabao.mintlify.site/training/datasets.md#the-datasets-directory-and-manifests); 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](https://gligabao.mintlify.site/training/deploying.md#fetching-the-weights) (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](https://gligabao.mintlify.site/api-reference/timeseries.md#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](https://gligabao.mintlify.site/guides/geo.md#writing-a-resolver).

> **Hooks**
>
> Callbacks gligabao invokes, today the system-event hook (called after every `remember`, `query` and timeseries request, with counts and timings). See [Hooks](https://gligabao.mintlify.site/embedding/hooks.md).

> **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](https://gligabao.mintlify.site/training/deploying.md).

> **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](https://gligabao.mintlify.site/embedding/admin-extensions.md).

> **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).

## 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.

```go theme={null}
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](https://gligabao.mintlify.site/getting-started/configuration.md#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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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()`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.