feat(addons): list and install backends from a library (#12816)

* feat(addons): add the add-on runtime, navigation and first-party add-ons

Add the add-on runtime to LocalAI: manifests, the host operation broker,
admin gating by account role, the add-on UI bundle builder and the SDK
for add-on pages. Move the navigation to Chat, Models, Add-ons and
Settings, with pinned add-ons in the sidebar and an Add-ons drawer.

Ship the first-party add-ons (voice, face, fine-tuning, quantization) as
packages for linux/amd64, linux/arm64 and darwin/arm64. Intel macOS
(darwin/amd64) is enabled in the platform files.

Squashed from the review branch. The tree is unchanged; the pre-squash
history is kept on a local backup branch.

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(gosec): tighten file modes and annotate false positives

Write job state, configs and imported models with mode 0600, clean
the paths that are read from disk, and mark the route tables, the
header name and the retry jitter as reviewed false positives.

Assisted-by: Claude Code:claude-sonnet-5-5 gosec
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): keep API keys off recovery mutations and same-site cookies

POST /api/addons/dispatch forwarded the recovery and update
mutations to the owner for any administrator key, which skipped the
browser-session rule of their own routes. Refuse those actions
there. Also apply the same-origin rule to the legacy token cookie,
not only the session cookie, because the global CSRF check lets
same-site requests through.

Do not fail the start of LocalAI when an add-on library cannot be
refreshed; log it and keep the installed add-ons up.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): refuse a reinstall that would migrate retained data unbacked

An upgrade takes a verified backup before the new package migrates
the data. A reinstall over retained data has no running generation
to stop, so the new package would migrate it without one. Refuse a
reinstall whose data format differs from the retained one.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): release the manager lock while a release is fetched

Submit held the state lock across the catalog lookup and the package
download, so the apps list and status reads stalled for the whole
install. Serialize Submit and Reconcile with their own lock and drop
the state lock around the fetch only.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): kill an add-on only after three missed health probes

One slow 100 ms probe killed a busy add-on and dropped the work it
was serving. Require three misses in a row.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): move settings under the operate hub

The Operate hub already has Settings as a tab, so the sidebar no longer shows a separate Settings entry. The /app/settings route stays, and the hub tab still reaches it. The navigation test now expects Chat, Models and Add-ons as the primary items.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): accept same-host browser requests that carry no fetch metadata

Browsers do not send Sec-Fetch-* headers over plain HTTP on an address
that is not localhost, so every add-on request from a LAN address was
refused as cross-site. Keep refusing a Sec-Fetch-Site value other than
same-origin. When the header is absent, accept the request only if its
Origin, or failing that its Referer, names the same host and port as
the request.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(ui): show the server's reason when an add-on request is refused

A 403 or 400 answer showed a generic message and hid the reason in the
response body, so a refusal by the browser guard could not be told from
a missing permission. Show error.message from the body as the server
sent it, and keep the generic text when the body has none.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): run the add-on owner in the normal binary

The owner was only enabled when an embedding host set the add-on config,
so a normal run answered every add-on request as unavailable.

Add --addons-enabled (default true) and --addons-ownership-mode
(default named-user, or local-owner; anything else stops startup).
The node is its own owner: state lives under the data path, and the
carrier uses loopback keys made at each start and kept in memory.
--addons-enabled=false turns the owner off completely.

Named-user mode needs the account database. With authentication off
the owner stays off and a warning says how to use local-owner.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): keep the loopback owner address stable across restarts

The single-node loopback transport took a new ephemeral port at each
start. The owner stores its address in its identity file and refuses to
start when the address differs, so every start after the first failed
with "invalid addon owner configuration".

Choose the port once, keep it in the add-on state root (loopback-port,
mode 0600) and reuse it. If the port is taken at a later start, stop
with an error that names the port and --addons-enabled=false, because
another port would break the identity check. The keys and certificate
stay in memory.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): let add-on pages keep the host modules they were written against

A page written for the web UI imports React, the router, i18next and a
few shared components. The add-on builder refuses a bundle that holds a
host file, so moving such a page into an add-on meant rewriting it.

Add a compat mode to the shared builder. It answers those imports from a
directory of stand-ins that read the SDK, bundles the dynamic import of
the page code into the one output file, and collects the style sheets the
page imports. A relative import that is not in the add-on's own source
resolves to the file at the same path under the compat directory.

Widen the SDK for these pages, without a version change: more host
components (spinner, modal, lightbox, model picker) and hooks (models,
resources, voice profiles, operations, MCP client), a style on icons,
the icon names the pages draw, sdk.navigation.openApp to open a page of
the app (only addresses under /app, and the way back as the only state)
and sdk.portal. The shell passes the query string to the page.

The stand-ins cover the router (the tab in the path, the model in the
query), the translator over the host locale files, the core API calls
through sdk.core.fetch, and byte copies of the pure helpers, with tests
that keep the copies equal to the originals.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): ship Studio and Talk as add-ons instead of built-in pages

Studio and Talk were compiled into the web bundle and always listed in
the Add-ons drawer. They are add-ons now, like Voice, Face, fine-tuning
and quantization: a person installs and removes them, the drawer lists
them only while they are installed, and they are packaged the same way.

Move the pages, their components, hooks and helpers into addons/studio
and addons/talk. Each has a manifest, a UI bundle, a release platform
matrix and a catalog template, and is built by the compat mode of the
shared builder. The core API stays where it is: the pages call it with
the signed-in person's session. The history keeps its browser storage
keys. The unit tests of the moved helpers move with them.

In the core, drop the two pages, the Create group of the sidebar (Chat
joins Home and Models in the old layout), the built-in catalog entries
(the catalog is empty) and the talk locale namespace. The old addresses
(/app/studio, /app/talk and the generator links) redirect to the add-on
pages, with the model as ?model=. The Home /studio command is offered
only while the Studio add-on is installed and opens it.

The release workflow and its tests now list seven add-ons.

Assisted-by: Claude Code:claude-sonnet-5-5 go node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): run the Studio and Talk specs against the add-on bundles

The pages are add-ons now, so a spec that draws one installs the real
built bundle first: the apps list names it and its module and style
sheet are served from the build output, the way the add-on owner serves
them. studio-addon.js holds that helper, and the Studio and Talk
fixtures call it.

Update the specs for the new addresses (/app/addons/studio/studio, the
model as ?model=), the session permission the add-on route needs, the
legacy redirects, the Home /studio command that appears only while the
add-on is installed, and the sidebar without a Create group.

Add specs for the add-ons themselves: every tab draws with no script
error, the shell titles the page once, the old addresses say so when the
add-on is not installed, a button of the page reaches a core page with
the way back, and the drawer lists both only after they are installed.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(ui): centre the icon of a built-in tile in its icon box

The drawer drew the icon of a built-in tile (Studio's palette was one)
in a bare 40px box. Only the placeholder box was laid out as a centred
grid with the 20px size, so the real icon sat in the top-left corner at
the size of the page text.

Give the built-in tile the same classes as the placeholder box, and
check in a browser that the icon is centred.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* docs(addons): describe Studio and Talk as add-ons

Replace the built-in list (now empty) with the Studio and Talk add-on
sections, the new targets of the old links, the Home command, and the
seven packaged add-ons. Describe the SDK additions the pages use:
components, hooks, icons, openApp and portal. Say on the Studio page
that it is installed from the drawer.

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): click the shell title in the Studio slash-key spec

The add-on shell titles the page, and the Studio overview no longer draws
a second title, but the generator tabs keep theirs, so a bare h1 locator
matched two elements. Click the first, which is the shell's.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): read the loopback port file through os.Root

The persisted port file was read with a path built from the add-on
root, which gosec reports as a file inclusion through a variable. Open
it through os.Root so the name cannot leave the root, even by a
symbolic link, and require a regular file with no group or other
access. A looser file now fails closed instead of being trusted.

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): expect Settings under the Operate hub, not the sidebar

Settings moved out of the sidebar into the Operate hub. The navigation
spec still expected a sidebar link. Assert that the sidebar has no
Settings entry, and that the Operate hub opens Settings as a tab.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): drop Settings from the 404 places

Settings is a tab of the Operate hub and not a destination of its own,
so the 404 page does not list it. Assert that it is absent.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): drive the media history and TTS specs through the Studio add-on

The image, video, sound and speech generators are pages of the Studio
add-on now, and the old addresses redirect to it. Install the add-on
with the Studio fixtures, open its pages and use its compose card, so
the specs run against the page that exists.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): count the first-run steps, not every list item

The recommended models are a list inside the second step, so counting
all list items read 3 only while the models were still loading. Count
the step elements, which does not depend on the load order.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): fail the node refresh by state, not by call count

The spec served the list to the first request and failed the rest. The
first request is not always the one from the page, so the page could
get the failure first and show no list. Serve the list until the page
shows it, then fail the refreshes.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): default to local-owner when auth is off

A server without authentication has no accounts, so named-user left
the add-on owner off. Resolve the unset mode in one place: local-owner
when authentication is off, named-user when it is on. A flag or
environment value still wins, and an unknown value is still refused.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): register an official add-on library by default

Add gallery/addons/index.yaml, a YAML index of the four first-party
add-ons (fine-tuning, quantization, voice, face) in the library format.
The entries come from addonpkg catalog over locally built linux/amd64
packages, so the digests pin those images.

On the first start, when the owner has no sources.json, register the
raw GitHub URL of that index on master as the "official" library and
write the file. The file is then the record: a library the admin
removes stays removed, and an existing file is never changed.
--addons-official-library=false skips the default.

Assisted-by: Claude Code:claude-sonnet-5-5 go node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* docs(addons): document the ownership default and the official library

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): list Studio and Talk in the first-party index

Add the Studio and Talk entries to gallery/addons/index.yaml next to
the four existing ones. They come from addonpkg catalog over locally
built linux/amd64 packages, so the digests pin those images.

Assisted-by: Claude Code:claude-sonnet-5-5 go node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): expect Studio and Talk in the official index

The official index now lists six add-ons. Update the test that
decodes it so it accepts Studio and Talk.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): add a real icon to each first-party add-on

Each icon is a 256 by 256 PNG: a rounded square in one colour of the
UI kit palette with a white outline glyph from the kit sprite. Fine-tuning
uses sliders, quantization layers, voice waveform, face user, studio
palette, talk phone and tables database. They were rendered with headless
Chrome from the sprite paths.

Assisted-by: Claude Code:claude-sonnet-5-5 chrome
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): ship a committed icon.png instead of the generated square

The shared UI builder and the Tables builder copy ui/icon.png from the
add-on source tree to the package unchanged when the file exists. They
write the generated placeholder only when it does not. Add a fixture with
an icon and a test for both cases.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): list the tables add-on in the first-party index

Add the Tables entry to gallery/addons/index.yaml next to the six
existing ones. It comes from addonpkg catalog over a locally built
linux/amd64 package, so the digest pins that image. The official index
test now expects seven add-ons.

Assisted-by: Claude Code:claude-sonnet-5-5 go node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): make the Voice add-on one page with tabs

The Voice add-on had four pages: recognition, library, create and
speech, and the drawer listed two of them. It now has one page, "voice",
and one drawer entry. Recognition, Library, Text to speech and From a
recording are tabs of that page, drawn with the same tab strip the
recognition page already used. The tab is the first path segment
(voice/library), as in the Studio add-on, and the form that adds a voice
is a view of the Library tab (voice/library/new).

The old page names stay declared in the manifest. Each one redirects to
its tab and keeps the query string, so saved links still open.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): send the old voice routes to the Voice tabs

/app/voice, /app/voice-library and /app/voice-library/new now open the
matching tab of the Voice add-on page while the add-on is installed and
running, and the core pages otherwise. The moved-page helper compares
the first segment of the target with the declared pages, so a target
can name a tab. The docs and the navigation spec list the new addresses.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): cover the Voice tabs and the old page redirects

The add-on unit tests render the tabs instead of the four pages. The
Playwright spec checks the tab strip, the address of each tab, the
missing Library tab for a member, and that the old page addresses of the
add-on redirect to their tab with the query string kept. The migration
table test follows the new targets.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(studio): keep the model menu inside a narrow screen

The Home model picker sizes its menu from the viewport, and assumes the
picker sits at the page gutter. In the Studio composer card the field is
further in, so on a 390px screen the menu of the Sound expansion picker
ended 7px past the right edge. Size the menu from the field it opens
under instead.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): build the add-on bundles once for the whole run

Each worker built the Studio and Talk bundles into the same dist
directory, and the build empties that directory first. A worker that
started, or restarted after a failure, removed the files another worker
was serving, so a Studio spec saw "the style sheet of the add-on could
not be loaded". Build once in a global setup before the workers start.
A run without the setup still builds per worker.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): register the worker when the add-node spec says so

The mocked roster added the worker on the third read of /api/nodes. The
shell and the page both read it, and which one asks first depends on
load, so the page could take the new worker as part of the roster it
opened with and never show it as found. The worker now joins after the
page shows it is listening.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): hold the gallery answer until the skeleton is seen

The spec delayed the answer by a fixed 800 ms and then looked for the
skeleton. The assertion polls at growing intervals, so on a slow machine
it could step over that window. The answer now waits until the skeleton
has been seen, and the spec then checks that the skeleton goes away.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): give the PDF tag the time the other PDF specs have

pdf.js and its worker load on first use. The other specs in this file
wait up to ten seconds for the result of that load. The first one waited
five, and missed the tag on a busy machine.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): build the Face and Fine-tuning bundles in the global setup

The navigation spec serves the built Fine-tuning bundle, but nothing
built it, so two specs failed on a fresh checkout when the dist folder
was missing. The spec also built the Face bundle in a hook that every
worker runs, and a build rewrites the folder the other workers serve.

The global setup now builds Studio, Talk, Face and Fine-tuning once,
before the workers start. The spec builds the two bundles itself only
when it runs without the global setup.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): fix the Home answers in the stale pin spec

The spec asserts that the page shows no alert. The Home page raises its
own alert when the model list fails or a staging operation has failed,
and both answers come from the shared test server. A slow reply or a
failed install left there counted as an alert about the pin.

The spec now fixes both answers, so the alert count tells only about the
pin. The assertions are unchanged.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): read the server address in the add-node spec from the page

The spec expected the register address to carry port 8089, so it failed
on any other port. It now expects the origin the page was opened from.

Assisted-by: Claude Code:claude-sonnet-5-5 node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): give the navigation routes spec its own catalog

No page is built in today, so the catalog is empty and the three specs
that expect the studio and talk entries failed on the list and on the
pin seed. They passed only while Studio and Talk were built in.

The spec now sets a catalog of two ungated entries for each example and
restores the old one afterwards. The assertions are unchanged.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(cli): report a failed write of the MLX hostfile

The tunnel callback ignored the error of os.WriteFile and set the
hostfile variable even when the file was not written. It now logs the
error and leaves the variable alone.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): discard the close error of the held listener

errcheck flags the deferred Close of the listener that keeps the port
busy. The test has no use for that error, so the defer drops it
explicitly.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): move the add-on tool tests to Ginkgo

The fine-tuning, quantization and add-on host library tests used
t.Errorf, t.Fatal and t.Run, which the forbidigo rule rejects. They now
use Describe, It and Gomega, with a suite bootstrap in each package. The
cases and the assertions are the same.

The tables in the host client and the tool schema tests keep one entry
per case.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): move the host operation tests to Ginkgo

The hostops tests used the testing package calls that forbidigo rejects.
They now run as Ginkgo specs under one suite bootstrap. Every check and
every per-operation case is kept.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): move the pin store tests to Ginkgo

The pin service, file store, sweep and shared store contract tests used
the testing package calls that forbidigo rejects. The store contract is
now a function that registers its specs for each store, so the file
store, the memory-only store and the database store run the same cases.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): move the remaining add-on tests to Ginkgo

The built-in catalog, tool arguments, loopback carrier, host operation
contract, packaging, application, config, CLI and endpoint tests used
the testing package calls that forbidigo rejects. They now run as Ginkgo
specs. The endpoint tests also drop the unchecked Close errors that
errcheck reports when the auth tag is on.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): wait for the targeted Reinstall button before the install click

The "generic deletion blocks targeted install at confirmation" spec
dispatches a popstate to set the target node, then clicks Reinstall with
a script click. The click can run before the targeted page has rendered
or while the button is still disabled, so no install request is sent and
the poll on the install count times out. It failed 1 run in 10 with two
workers and on every retry in CI.

The spec now waits for the button to be enabled first. The assertions
are unchanged.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* chore(addons): refresh the voice package digest in the first-party index

The Voice add-on became one page with tabs and got a new icon, so the
digest in gallery/addons/index.yaml no longer matched the build. Render
the entry again with addonpkg catalog over a locally built linux/amd64
package; the main page is now voice. The other entries are unchanged.

Assisted-by: Claude Code:claude-sonnet-5-5 go node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): wait for the target node's Reinstall button after the popstate

The "generic deletion blocks targeted install at confirmation" spec
dispatches a popstate to set the target node, then waits for a button
named Reinstall and clicks it. Until React renders the targeted page,
the page still draws the generic Reinstall button. It is enabled and has
the same name, so the wait passed on it, the click started a global
install, and no node install request was sent. The poll on the install
count timed out with the confirm dialog still open.

With the CPU throttled to 8x, the spec failed on 20 of 20 runs, and the
button it clicked had the title "Reinstall". The spec now waits for the
button titled "Reinstall on <node>". With the throttle it passes 30 of
30 runs. The assertions are unchanged.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): give the Studio hand-off spec a budget for the cold bundle load

The "a result made through a hand-off records which result it came from"
spec opens the Studio add-on straight from an address, twice. Each is a
cold load: the page shows "Loading" until the add-on module has run, and
the next assertion had the default five seconds. The load takes about
two seconds on an idle run and seven to ten under CPU load, so the spec
failed on a loaded machine with the hand-off note not yet drawn.

With the CPU throttled to 6x and eight busy loops running, it failed on
21 of 30 runs. The first assertion after each load now waits up to 20
seconds, and the spec then passed 30 of 30 under the same load. The
assertions are unchanged.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): carry the identity page styles in the Face add-on

The Face page is drawn with the shared identity views, but its style sheet
held only the clip and error rules. The page, card, model list, known-faces
table, enrol sheet and distance scale classes had no rules. They looked
right only when the host had already loaded the style sheet of its own
Faces page, which a visit through the add-on drawer does not do. Opened
that way, the cards had no gap, the model list showed bullets, and the
install buttons ran into the names.

The Face sheet now holds the same identity rules as the core sheet, so the
page looks the same whichever way it is opened.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): scope the narrow-screen identity rules of the Voice add-on

The rules for narrow screens (single-column pairs, smaller tool padding,
compact rank rows) were copied into the Voice style sheet without their
media query, so they applied at every width. They now sit in a
max-width 720px query, and the reduced-motion rule in its own query, as in
the core sheet.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): drop the repeated title from the Voice and Face pages

The add-on shell already titles the page, so the recognition pages showed the name twice: "Voice" above "Voices", "Face" above "Faces". Keep the supporting line and the model picker, as the Studio page does, and remove the unused title strings.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): replace the Pinned sidebar section with an Apps entry

The sidebar no longer lists pinned add-ons. It shows one Apps entry that
opens the add-ons drawer, with a Show all link below it that opens the
same drawer. Pins are used from the drawer, where a pinned tile keeps
its pin and move buttons. The server pins API is unchanged.

Remove the PinnedNav component and its locale title, rename the
items.addons label to Apps, and update the e2e specs and the add-ons
documentation to match.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): assert the single shell title on the Voice and Face pages

The add-on shell now shows the one title, "Voice" or "Face", and the page no longer repeats it. The tests still looked for the h1 "Voices" and "Faces". Assert that the add-on page has exactly one h1 and that it is the shell title. The core pages keep their own "Voices" and "Faces" titles.

Assisted-by: Claude Code:claude-sonnet-5-5 playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): drop the repeated title from the Voice Library and Text to speech pages

The add-on shell already titles the page "Voice", so these two tabs showed a second heading below it ("Speech voices", "Speak text"). Keep the supporting line, as the Studio and recognition pages do, and remove the unused title strings. The e2e spec now checks that each tab has exactly one h1, the shell title.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): list pinned apps under Apps in the sidebar

A pinned app now shows as an indented child of the Apps entry, with its icon and title, in pin order. Show all stays the last child. The pins come from GET /api/addons/pins through the navigation context, and the apps from the add-on registry, which the drawer feeds on every list read, so the links follow the drawer. A pin without an installed app is not drawn, nothing extra shows when no app is pinned, and the children are hidden when the sidebar is collapsed to the rail.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* docs(addons): say that pinned apps are listed under Apps in the sidebar

The sidebar lists the pinned apps between Apps and Show all, in pin order. The pins section and the navigation section said that pins do not appear in the sidebar.

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(ui): remove the Show all link under Apps in the sidebar

The link repeated the Apps entry, which opens the same drawer, and looked redundant when no app was pinned. Apps is now the only add-on entry; pinned apps still list under it in pin order. The link, its locale key and the style comment are gone, and the e2e spec and the add-ons docs now say that Apps is the only entry.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): show a first-run card on Apps when nothing is installed

An administrator who opens Apps with no add-on installed now sees a
short card with three steps: choose a library, browse and install,
start the add-on. Its button opens the Browse tab. The card is hidden
once an add-on is installed and for anyone who cannot install.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(ui): hide the pinned apps in the icon rail

When the window is narrower than 1024 px the sidebar shrinks to the icon rail by CSS alone, without the collapsed class. The pinned app links were still drawn there, with the indent meant for the full sidebar, so their icons sat to the right of the rail and were cut off. Hide the pinned app links in both rail states. The Apps entry keeps its centred icon. The e2e spec checks that the rail shows no pinned app and that every icon is centred at 1280 px collapsed and at 1000 px.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(ui): stop the backend redirect test racing the installed list

The test reads the redirected URL right after the path changes. The
Backends page then loads the installed list and drops a selected backend
that is not installed, so the backend parameter was sometimes already gone
when the test read it. The mock server has no llama-cpp, and about 15 of
40 repeated runs failed on the backend assertion. The redirect itself was
correct, including show_all.

Serve the selected backend in the installed list, so the page keeps the
selection and the assertions stay as strict as before.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): accept a same-host Referer or Origin for human confirmation

Browsers send no Sec-Fetch-* headers over plain HTTP on an address that
is not localhost, so creating a resource from a LAN address failed with
"Creating a resource requires your own browser session".

When Sec-Fetch-Site is present it must still be same-origin with an
empty destination, as before. When it is absent, Origin or, failing
that, Referer must name the request host and port. A destination or
mode that is present must still be the expected one. This matches the
rule in BrowserProtection. The credential, token cookie, API key and
tool-context checks are unchanged.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(ui): keep hub entries off the Apps route in the sidebar

The Build hub still owned /app/addons through its legacy Add-ons tab,
so the sidebar lit both Apps and Build on the Apps page. A tab whose
gate is closed now owns no route when the sidebar asks, so only the
Apps entry is active there. The hubs keep their own routes, and the
legacy navigation still gives /app/addons to the Build hub.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): label the pin control on app tiles and in the detail view

The pin was a small icon-only button and hard to find. Each app tile now
shows a button reading Pin, or Pinned with a filled pin, and the detail
view has the same control in its header. Both toggle the same stored pin.

The Apps grid lists pinned apps first, in pin order, then the others.
The sidebar list and the server pins API are unchanged.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(addons): check the Voice From a recording tab has one title

The Library and Text to speech tabs already assert that the add-on shell
title is the only h1. Do the same for the From a recording tab, so a
heading added there later fails the navigation spec.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(ui): stop the add-on shell drawing a title over add-on pages

The app decides what its page shows. The shell drew the add-on name as a
header above every add-on page, so an add-on could not choose its own
title. The shell now draws no header on a live, loading or frozen
add-on page; each add-on titles its own pages. The unavailable and
missing-page states keep the name, because no add-on page is drawn there.

The runtime and shell specs now check that the shell adds no page title.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(addons): let each add-on draw its own page title

The shell no longer titles add-on pages, so each add-on draws one h1 per
page. Voice titles its tabs "Voices" (Recognition and From a recording),
"Speech voices" (Library) and "Speak text" (Text to speech); "Add a speech
voice" already had its own. Face draws "Faces", Studio "Studio" and Talk
"Talk". Tables promotes the database list and database name from h2 to h1.
Fine-tuning and Quantization already drew a title.

The add-on unit tests and the navigation and Studio specs now assert
exactly one h1 per page, with the page's own title.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): add a kind to library entries and read unknown kinds tolerantly

A library entry now has an optional kind: addon (the default when it is
absent), backend or model. Every index written before kinds existed stays
valid and its entries are add-ons.

A reader keeps the entries of the kinds it knows and skips the others
without reading their fields, so a newer kind never makes an older host
refuse the whole index. The refresh result and the library state report
how many entries were skipped and of which kinds, and the refresh logs a
warning. A kind that is not a plain kind name still makes the index
malformed. Search lists add-ons unless the caller asks for a kind, and
Resolve returns add-ons only, so an add-on install cannot be pointed at
a backend image.

A library policy may name the signer with an anchored identityRegex
instead of an exact identity, so builds from master and from tags both
verify. An add-on install refuses a policy that carries one.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(backends): install a backend from a library entry

A library can now list backends. An entry of kind backend names the
image of the backend gallery by digest, and POST /backends/library/install
installs it on the local node. The gallery stays the source of truth and
its install path is the one used: the library resolves the entry, takes
the signature policy from the library, pins the image by digest and calls
the same install as the gallery. Installing a name that came from a
gallery, another library or by hand is refused and changes nothing.

The signature policy of a backend library names the signer with an
anchored identityRegex, so images signed by the merge workflow on master
and on tags both verify. A pattern that is not anchored is refused.

An install is bounded by a size limit per kind: add-ons keep 512 MiB and
a backend image defaults to 8 GiB, set with --addons-backend-max-bytes.
The limit reads the manifest after the signature check and before any
layer is fetched. The metadata of an installed backend records the
library it came from.

scripts/backends/cmd/backendcatalog renders entries from
backend/index.yaml and pins them against the registry. The pilot is the
CPU build of local-store, in gallery/backends/index.yaml. The library is
registered on the first start only with --addons-backend-library, which
is off by default.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): show the kind of library entries and install backends from them

The Browse tab lists the entries of every kind this host reads and marks
each one as an add-on or a backend. A backend installs through the
backend route and not through the add-on lifecycle: the confirmation
says that the backend gallery is not changed and that a backend runs
native code, and a refusal of the host, such as a name installed from
another origin, is shown with its own reason. The details give the kind,
the alias and the signer pattern.

The library editor can name the signer with a pattern. Without this a
save would drop the pattern of a backend library. The Libraries tab
reports the entries a refresh skipped because their kind is not read.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* docs(addons): describe backends in the library

Document the entry kinds, how a reader skips a kind it does not know,
the backend entry format, the signer identity pattern, the install
route, the size limit of each kind, the pilot library and the command
that renders it. The backend page links to it.

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(mcp): install a backend from a library entry

The backend library route installs a backend from an add-on library
entry, and the admin REST surface and the MCP catalog must stay in step.
Add the install_library_backend tool with an in-process and an HTTP
client, the route map entry, the safety-rule listing and a skill recipe.

Listing library entries stays on the add-on routes, which the assistant
does not expose, so no list tool is added.

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(ui): carry the add-on library keys in every locale

The add-on library and backend library strings existed only in English,
so the other locales had no value for them. Add the missing keys of the
addons namespace to de, es, id, it, ko, pt-BR and zh-CN. The values are
the English text until a translation is contributed.

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(backends): report the steps of a library install as a job

A backend install from a library ran inside the request and showed
nothing until it ended. It is now a job of the gallery service, the
kind the backend gallery installs use. The request answers with the job
ID and GET /backends/jobs/{id} reports the step as the phase of the job:
resolving, verifying, size, fetching and writing, with the byte progress
of the fetch. A job that fails keeps the phase of the step that failed
and gives the reason. A second install of the same name is refused while
one runs.

The downloader and the gallery install report their stages through an
optional hook, so the steps are the real ones and not a guess. The
Browse tab lists the steps of the entry being installed, marks the one
that failed, and omits the signature step for a library that does not
require one.

The library installer also gets Updates and a route that lists the
installed library backends with a newer build in their library, for the
next change.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): mark library backends and offer their updates on the Backends page

A backend installed from a library now shows the library ID next to its
name and, in the detail, the library and the digest that metadata.json
pinned. Gallery backends look and behave as before, and the gallery
reinstall is not offered for a library backend, because the gallery does
not list it.

When the cached index of the library lists another build in the channel
of the installed version, the row says "Update available" and offers an
Update button. The button starts the same install as the Browse tab, and
the detail shows its steps. Nothing is upgraded on its own. The check
says nothing when the library no longer lists the installed version and
has several channels, instead of guessing one.

Assisted-by: Claude Code:claude-sonnet-5-5 node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(mcp): match the library installer to the progress type

The MCP install of a library backend was written against the earlier
Install signature. The job-based install now takes a Progress value,
so the application did not build. The MCP interface drops its unused
status callback and the application adapts the installer to it.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(gallery): add the model library entry shape and its reader

A model library entry is the shared library envelope (kind, id, name,
version, description, license, urls, tags, icon, channel, policy,
schemaVersion) plus a model body: url, backend, size, files,
configFile, overrides, variants and promptTemplates. The envelope lives
in the catalog package so the other kinds can move to it.

A gallery entry converts to a library entry and back to the same
gallery entry. Floats are written so they read back as floats, and an
empty variants list stays distinct from an absent one, because both
occur in the real index.

The reader is strict: unknown fields, duplicate ids, a second document
and a flow-style list are refused. An entry of another kind is skipped
and reported, as in the add-on reader. The gallery index stays the
default and is not changed.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(gallery): render the model library from the model gallery

scripts/models/cmd/modelcatalog reads gallery/index.yaml with the same
structs the host reads it with, converts every entry to a library entry
and back, and fails if any entry does not come back equal. It writes
gallery/models/index.yaml and the golden files for the tests. The
output is deterministic, and the gallery is only read.

The golden files are a digest pair for every entry (the gallery entry
and the library entry made from it) and a readable gallery and library
pair for each kind of entry: plain, with variants, with an empty
variants list, with a config file, with a size, with a backend, with
floats in the overrides, without a url, without files and with a
multiline description.

All 2212 entries of the index round trip. The gallery struct does not
read a few keys (last_checked, parameters and four stray capitalised
keys); the host drops them when it loads the index, so the library does
not carry them, and the command reports them.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(gallery): add --model-index-source to read the model library

--model-index-source selects the file the host reads the models of the
official gallery from: gallery (the default) or library. With library
the gallery named localai reads the model library, from
--model-library-url or the file in the repository, and keeps its
configured name and URL on every entry. A gallery the owner added keeps
its own index, and add-on and backend galleries never take this path. A
library that cannot be fetched or read is an error and not a fall back
to the gallery, so the setting is never silent.

The tests round trip every entry of the real gallery index, compare it
with the golden files, check the rendered library file reads and agrees
with itself, and cover the strict reader, the kinds it skips, prompt
templates, number types, empty lists and the setting.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(backends): upgrade library backends with the auto-upgrade switch

The upgrade checker now installs the newer build of a library backend
when auto_upgrade_backends is on, on the same check that upgrades the
gallery backends. With the switch off nothing is installed and the
Update button stays manual. The switch is read on every check, so a
change in the runtime settings applies at the next one. There is no
second toggle.

The tests cover both states and a host without a library.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(cli): add local-ai library to manage library sources

local-ai library has list, add, remove, enable and disable. It works on
the source store the server reads (addons/sources.json under the data
path), so it also works with the server stopped. A source has a kind
(addon, backend or model); the store records whether it is a shipped
default, and removing a default leaves a tombstone so it does not come
back at the next start.

The shipped model and backend gallery indexes are default sources next
to the official add-on library. Defaults are added at every start when
they have no record yet, and an existing file that holds no default is
left alone as before.

The --model-index-source and --model-library-url flags are removed: a
model library is added as a model source, and the gallery entry says it
is a library.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(addons): let a source of your own win an entry over a default

When two enabled sources list the same entry (same kind and id), the
source the user added wins over a shipped default, and the default is
ignored for that entry. When two sources the user added list it, search
and resolve are refused with an error that names the entry and both
sources, and nothing is picked silently. Among shipped defaults nothing
changes.

The tests cover a user source over a default, a tie between two user
sources, a default ignored once a user source wins, and the case where
disabling a source ends the conflict.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(cli): map the gallery flags to library sources at startup

--galleries and --backend-galleries keep loading the same JSON. At
startup each entry they name also becomes a source the user owns, of
kind model or backend, so local-ai library list shows it. The mapping is
additive: an entry whose kind and URL is already a source (a shipped
default, one added with the CLI, or one mapped at an earlier start) is
not added twice, and a derived id never collides with another source.

The sources then decide which galleries the server reads: a gallery
whose source is disabled or removed is left out, and a model library or
gallery added with local-ai library add is added. A list set by the flags
still replaces the shipped defaults. If the store cannot be opened, the
galleries stay as the flags set them. The autoload switches are not
touched.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* refactor(library): use id for every kind and seed the default libraries

The backend entries of the library used addonId while the model
entries use id. Release now has the field ID, written as id for every
kind. ReadIndex reads addonId as a legacy alias for one release, for
add-ons and backends, and refuses an entry that holds both names. The
backend index and the catalog generator write id.

The shipped libraries are default sources. The pilot backend library is
now on by default, like the official add-on library, and the model
library is a new default model source, official-models. The server
reads it next to the localai gallery. A source the user removed stays
removed, and a source the user adds is added to the defaults.

The model catalog header held a backtick that ended its raw string, so
the generator did not build. The header no longer has it.

Assisted-by: Claude Code:claude-sonnet-5-5 go node playwright
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(library): choose the default model source by build

A build read both the localai gallery and the official-models library
by default, so every model was listed twice. Now a build reads one of
them. library.ModelSource names it: "library" or "gallery". The model
source that is not chosen is still shipped, as a disabled default, and
local-ai library enable turns it on.

The value is a Go variable set at link time with -ldflags, because the
same source tree makes both kinds of build and a constant would need a
commit to change. It is "library" in the source, so a build from
master, go build and go test read the library. Only the exact value
"gallery" selects the gallery, so a mistyped value cannot leave a build
without a model source.

The Makefile sets it from LOCALAI_MODEL_SOURCE. When that is not set, a
commit that carries a tag gets "gallery" and any other commit gets
"library". .goreleaser.yaml passes the same variable and defaults to
"gallery". The release workflow sets it to "library" on a tag, which is
the cutover.

A default source is seeded once, so a data directory that an earlier
build seeded keeps its enabled flags. Switch it with local-ai library
enable and disable.

Tests assert the master default, the tagged default before the cutover
and after it, and that a mistyped value reads the library. The model
library header now says that CI checks it and when a build reads it.

Assisted-by: Claude Code:claude-sonnet-5-5 go node
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* ci(library): check the model library and cut over on tag

No workflow checked gallery/models/index.yaml, so it could go stale
when gallery/index.yaml changed. A new workflow, model-library.yml, runs
on pull requests and on master when the gallery, the library, the
generator or core/gallery change. It runs the generator tests and the
library shape tests (the file decodes, it has the library shape, every
real entry round trips), then renders the library again from
gallery/index.yaml and fails on any difference with git diff
--exit-code. The error message gives the command that fixes it.

release.yaml gets the cutover. On a tag, a step sets
LOCALAI_MODEL_SOURCE=library before GoReleaser runs, and
.goreleaser.yaml links it into the binary. Without that step a tagged
build reads the gallery. The step is the one place to remove when the
gallery is retired.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(library): make the model library the source of the gallery

The library, gallery/models/index.yaml, was rendered from the gallery.
Now it is the source and models are edited there. modelcatalog reads
the library and writes gallery/index.yaml, a generated copy that stays
only so releases before the cutover keep working.

The gallery file is written in the shape the host reads: the same
field order, floats such as 1.0 keep their form, and an empty variants
list stays apart from an absent one. The command converts every
library entry to a gallery entry and back, loads its own output the way
the host does, and fails when an entry comes back different.

The gallery copy drops what the library cannot carry: last_checked,
parameters and four capitalised keys (Base Model, Context Length,
License, Training Data). The gallery struct has no field for any of
them, so the host ignored them on load. Every run lists these keys and
how often the file being replaced still had each. Loading the old and
the new gallery with the host structs gives equal entries for all
2212 models.

The tests that read the library and the golden files follow in the
next commit.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* ci(library): check the library and that the gallery is its copy

The model-library workflow assumed the gallery was the source. It now
checks the library file, the new source. The library decodes, every
entry has the library shape, every entry converts to a gallery entry
and back, and the gallery reader loads the generated gallery and sees
the same names, file uris and digests. The workflow then generates
gallery/index.yaml again and fails on any diff with git diff
--exit-code. The message says the file is generated, not to edit it by
hand, and gives the command that regenerates it.

The tests in core/gallery read the library file now. The round trip
runs library to gallery and back on all 2212 real entries, a new test
compares the checked-in gallery with the generated copy so go test finds
a hand edit too, and the golden digests and samples are written from
the library. The version of an entry is no longer compared with a digest
of its content, since an edit to the library does not change it.

The docs say the library is the source, the gallery file is a generated
copy for releases before the cutover, and edits go to the library. The
agent guide for adding models says the same.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(library): add admin routes for library sources and an official libraries switch

The library sources of the add-on, backend and model kinds had a CLI
but no HTTP routes. Add them for administrators, on the same store and
the same functions as `local-ai library`, so the two cannot drift:

  GET    /api/library/sources
  POST   /api/library/sources
  POST   /api/library/sources/{id}/enable
  POST   /api/library/sources/{id}/disable
  DELETE /api/library/sources/{id}

The list carries kind, default, removed (a tombstone), suspended and the
conflict message of a source that clashes with another one. A change to
a model or backend source applies to the running server. A deleted
source drops its gallery by address; a removed default keeps its record.

Add the runtime setting official_libraries (default on), with the flag
--official-libraries. When it is off, every shipped default source of
the three kinds is suspended: it is not read, stays in the store marked
default, and comes back when the setting is on again. Sources the user
added are not affected.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): list library sources of all three kinds in the Libraries tab

The Libraries tab of the Add-ons page now lists the sources of the
add-on, backend and model kinds from the new library routes. It has a
kind filter with counts, a Default badge, the state of each source
(enabled, disabled, removed, or off while the official libraries are
off), turn on and off, a Restore button for a removed default, and the
conflict message next to a source that clashes. Adding a source takes a
kind and, for backends and models, an index format.

Settings gets the toggle "Use official libraries" for the
official_libraries setting.

Add unit tests for the list and the kind filter, and a Playwright spec
that runs on a fresh test server started with --library-sources (its own
config, port 8097): it lists the three kinds, adds a model source,
disables and removes a default, checks the conflict message and the
official libraries toggle.

Assisted-by: Claude Code:claude-sonnet-5-5 javascript
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(library): extend the backend body to carry what the gallery carries

The backend library entry only held an image and its digest. The backend
gallery holds more that matters at install and in the UI, so the library
could not replace it. Add the missing fields to the backend kind and keep
the strict reader.

New fields, all refused on an add-on entry:

- mirrors: ordered fallback images of the same backend, each oci://.
  The install pins them with the digest of the artifact.
- capabilities: a map from a host capability to a backend id. An entry
  with capabilities and no artifact is a meta backend. It has no digest,
  os or arch, is listed for every platform, and installing it installs the
  backend its capability names, in the same library and channel.
- license, urls, tags: display metadata, bounded and checked as text.
- icon: an https URL. The add-on ui.icon stays a path in the package. The
  host never fetches the icon.
- mutable: the artifact is a moving tag, such as a development image. The
  entry has no digest. The install resolves the tag to a digest, verifies
  that image and records the digest it installed.
- schemaVersion: the envelope version. A higher one is refused.

The index bounds grow to 8 MiB and 4000 entries, because the backend
library lists every image for every platform. Release now holds lists, so
the add-on staging compares it with Equal instead of ==.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(library): render the backend library from the whole backend gallery

Add the conversion between a gallery backend and its library entries in
core/gallery, and make scripts/backends/cmd/backendcatalog build the
library from the gallery and the gallery from the library.

The library now holds all 1093 gallery entries as 1088 backends, because
five names appear twice in the gallery with the same content and are
folded. That is 934 concrete backends and 154 meta backends, written as
1240 entries: a backend built for several platforms has one entry for
each, with the digest of that platform image.

- 539 release entries are pinned by the digest the registry serves for the
  platform.
- 543 development entries (master-* tags) keep their tag and are mutable.
  The install pins them.
- 4 release entries are not pinned, because the registry has no image for
  them: cpu-qdrant-store, metal-qdrant-store, cpu-gemxcpp and
  vulkan-gemxcpp. They are marked mutable and no digest is invented.
  Render them again with --repin once the images exist.

The generator can import a gallery once, pin the release images again, and
write the gallery file from the library without the network. Before it
writes it converts every backend to the library and back and fails if one
does not come back equal. A policy is no longer written on each entry,
because the host takes the policy of the library source.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(library): check that every backend gallery entry round trips

Prove that the backend library can replace the backend gallery. The golden
input is the real backend gallery from before the library became the
source: 1093 entries, kept under core/gallery/testdata/backend_library
with the pins the library holds and the digest of each generated entry.

TestBackendLibraryRoundTripsEveryRealGalleryEntry converts each entry to
library entries, writes them as an index, reads them as a host does,
validates them and converts them back. It asserts that all 1093 entries
come back equal on every field the gallery reader uses, and logs the
count. The five names that appear twice in the gallery have the same
content, so the twin is checked against the first one and folded.

The other tests check the library file in the repository: every entry
passes the host checks, every backend round trips, every meta backend
names concrete backends the library has, a development entry keeps its
master-* tag and has no digest, and the golden digests still match. Unit
tests cover each field, the fields the library cannot carry, which are
refused rather than dropped, and entries of one backend that disagree.

An entry with no artifact, digest, os or arch no longer writes them as
empty strings, so a meta backend and a mutable entry stay short.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(library): make the backend library the source of the backend gallery

Flip the source the way the model library did. The backend library,
gallery/backends/index.yaml, is where backends are edited. The backend
gallery, backend/index.yaml, is now generated from it by
scripts/backends/cmd/backendcatalog and stays only so releases before the
cutover keep working. It no longer has anchors or hand-written order, and
it holds 1088 backends: the five names that were listed twice with the same
content are folded.

Which source a build reads is set at build time, like the model source:

- core/library.BackendSource is "library" or "gallery". Only the exact value
  "gallery" selects the gallery, so a mistyped value cannot leave a build
  with no backend source.
- A build from master reads the library. The Makefile reads the gallery for
  a commit that carries a tag (LOCALAI_BACKEND_SOURCE), and GoReleaser
  defaults to the gallery.
- A step in release.yaml sets LOCALAI_BACKEND_SOURCE=library, so a tagged
  build cuts over by itself.
- Both sources are shipped and one is enabled. With
  --addons-backend-library=false every build reads the gallery.

The server hands the shipped backend library to the gallery reader as a
library, so the Backends page lists it and installs from it the way it did
from the gallery. A backend library the user adds stays with the add-on
catalog. The shipped library is now a backend source, not an add-on one.

The new workflow backend-library.yml runs the tests, regenerates
backend/index.yaml and fails on a diff. It never reads the registry.
backendcatalog --add merges backends written in the gallery shape into the
library, so adding a backend does not mean writing platform entries by
hand; the agent guide says so.

Assisted-by: Claude Code:claude-sonnet-5-5 go
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* docs(library): describe the backend library as the source of the backends

Rewrite the backends and add-ons pages for the backend library. The library
file is the source of truth and the backend gallery is a generated copy that
is never edited by hand.

- backends.md: the library and the generated gallery, which source a build
  reads (master, tagged before the cutover, tagged after it), the
  --addons-backend-library switch, how to add a backend and generate the
  gallery, and what CI checks.
- addons.md: the full backend entry with the new fields (mirrors,
  capabilities, license, urls, tags, icon URL, mutable, schemaVersion),
  meta backends, development images pinned at install, and the backend
  library section in place of the pilot one.
- compatibility-table.md: point to the library as the source.

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(library): mirrors on library sources, editable through the API

Library sources carry an optional list of mirrors. The mirrors go into the
gallery entries the server reads, and a source can be edited with
PUT /api/library/sources/:id. The mirror forms accepted are http(s),
github:, oci:// and file://, at most eight per source.

Sources saved before this change load without mirrors.

Assisted-by: Claude:claude-haiku-5-5 [Claude Code]
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): library chips on the model and backend pages

The model and backend pages manage their own library sources. Filter
chips above the list narrow it to one library, and a panel adds, edits,
turns on or off, refreshes and removes sources of that kind. The add-on
Libraries tab lists add-on sources only.

Settings shows the model and backend galleries as a read-only view of
the library sources, with their mirrors. Mirrors are edited in the panel.

Assisted-by: Claude:claude-haiku-5-5 [Claude Code]
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(ui): show the library chips when a kind has one library

The chips were hidden until a page had two libraries, so a single library
had no visible filter. The row now shows whenever a page has a library.

Assisted-by: Claude:claude-haiku-5-5 [Claude Code]
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* docs(gallery): state the mirror rule and the cutover for the old index

The library no longer has no mirrors: a source can list them, so the note
now says that the shipped official-models library has none. The mirror
section says that clearing a source's mirrors waits for a restart. The
cutover section says the old gallery file is removed in the cutover
release.

Assisted-by: Claude:claude-haiku-5-5 [Claude Code]
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* fix(gosec): tighten the modes the catalog generators write

The generators wrote generated files and sample folders with 0644 and
0755. The generated index copies are tracked by git, which keeps only the
executable bit, so the tracked files do not change. Local copies get
0600 and 0750. The library path read in mergeLibrary is the operator's
own argument, so that read is annotated.

Assisted-by: Claude:claude-haiku-5-5 [Claude Code]
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

---------

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>
Co-authored-by: Ettore Di Giacinto <mudler@localai.io>

.agents/adding-backends.md

@@ -32,7 +32,7 @@ For Rust backends, you'll typically need (see `backend/rust/kokoros/` as a refer
 
 The build matrix is data-only YAML at `.github/backend-matrix.yml` (not inside `backend.yml` itself). `backend.yml` (master push) and `backend_pr.yml` (PR) load it via `scripts/changed-backends.js`, which also handles per-file path filtering so only touched backends rebuild on PRs and master pushes alike. Add build matrix entries to `.github/backend-matrix.yml` for each platform/GPU type you want to support. Look at similar backends for reference — `chatterbox`/`faster-whisper` for Python, `piper`/`silero-vad` for Go, `kokoros` for Rust.
 
-**Without an entry here no image is ever built or pushed, and the gallery entry in `backend/index.yaml` will point at a tag that does not exist.** The `dockerfile:` field must point at `./backend/Dockerfile.<lang>` matching the language bucket from step 1 (e.g. `Dockerfile.python`, `Dockerfile.golang`, `Dockerfile.rust`). The `tag-suffix` must match the `uri:` in the corresponding `backend/index.yaml` image entry exactly.
+**Without an entry here no image is ever built or pushed, and the library entry in `gallery/backends/index.yaml` will point at a tag that does not exist.** The `dockerfile:` field must point at `./backend/Dockerfile.<lang>` matching the language bucket from step 1 (e.g. `Dockerfile.python`, `Dockerfile.golang`, `Dockerfile.rust`). The `tag-suffix` must match the `uri:` of the entry you give to `backendcatalog --add` (step 3) exactly.
 
 **Path-filter registration — REQUIRED for any new dockerfile suffix.** This is the single most common omission, because it has no effect on the PR that adds the backend (when no prior path filter could catch it anyway) — it only breaks the *next* PR that touches your backend's directory, which then gets zero CI jobs and looks broken for unrelated reasons. Edit `scripts/lib/backend-filter.mjs:inferBackendPath` and add a branch BEFORE the more-generic suffixes:
 
@@ -116,21 +116,32 @@ Entries whose `dockerfile` is `./backend/Dockerfile.{llama-cpp,ik-llama-cpp,turb
 Wiring a backend into `includeDarwin:` is more than the matrix entry:
 
 1. **`includeDarwin:` entry** — `tag-suffix: "-metal-darwin-arm64-<backend>"`, `build-type: "metal"`, `lang: "go"` for go+ggml backends; omit `build-type` for the bespoke C++ ones (llama-cpp / ds4 / privacy-filter). Match an existing entry of the same shape.
-2. **`backend/index.yaml`** — add `metal:` to the backend's `capabilities` map (main and `-development`) and concrete `metal-<backend>` / `metal-<backend>-development` image entries pointing at the `-metal-darwin-arm64-<backend>` images.
+2. **The backend library** (step 3) — add `metal:` to the backend's `capabilities` map (main and `-development`) and concrete `metal-<backend>` / `metal-<backend>-development` image entries pointing at the `-metal-darwin-arm64-<backend>` images.
 3. **C/C++ backends only** — add an `inferBackendPathDarwin` case in `scripts/lib/backend-filter.mjs` returning `backend/cpp/<backend>/` (the generic fallthrough assumes `backend/<lang>/`, which is wrong for a C++ source tree driven with `lang: go`), and give `run.sh` a Darwin branch that exports `DYLD_LIBRARY_PATH` instead of `LD_LIBRARY_PATH`. If the build is bespoke (single `grpc-server` + dylib bundling), model it on `scripts/build/ds4-darwin.sh` and add a `backends/<backend>-darwin` make target plus a gated step in `.github/workflows/backend_build_darwin.yml`.
 4. **C++ proto gotcha** — if the backend compiles the generated gRPC/protobuf in a separate CMake target (e.g. `hw_grpc_proto`), that target must link `protobuf::libprotobuf` + `gRPC::grpc++` so the Homebrew include dirs propagate; otherwise macOS fails with `google/protobuf/runtime_version.h not found` (Linux hides this because apt headers sit in `/usr/include`).
 
 The CI path filter only builds a backend on a PR when a file under its directory changes, so a darwin-only YAML edit builds nothing — touch a file under `backend/<lang>/<backend>/` (a one-line comment is enough) in the same PR.
 
-## 3. Add Backend Metadata to `backend/index.yaml`
+## 3. Add Backend Metadata to the Backend Library
 
-**Step 3a: Add Meta Definition**
+`gallery/backends/index.yaml` is the **backend library** and the source of truth for the backends. `backend/index.yaml` is the backend gallery: a **generated copy** that stays only so releases before the library cutover keep working. **Never edit `backend/index.yaml`**; CI (`.github/workflows/backend-library.yml`) fails when it differs from the generated copy.
 
-Add a YAML anchor definition in the `## metas` section (around line 2-300). Look for similar backends to use as a template such as `diffusers` or `chatterbox`
+You do not write library entries by hand. A library entry is one backend image for one platform, pinned by a digest, so a backend with ten variants has dozens of them. Write the backend the way the gallery shaped it, in a scratch file, and let `scripts/backends/cmd/backendcatalog` convert it. Put the scratch file under `assets/work/` or the system temp directory, not in the repository.
 
-**Step 3b: Add Image Entries**
+**Step 3a: Write the entries in gallery shape**
 
-Add image entries at the end of the file, following the pattern of similar backends such as `diffusers` or `chatterbox`. Include both `latest` (production) and `master` (development) tags.
+Use a YAML anchor for the meta definition and `<<: *anchor` for the image entries, as in the old `backend/index.yaml` (a similar backend such as `diffusers` or `chatterbox` is in `core/gallery/testdata/backend_library/gallery-before.yaml`, which keeps the whole gallery as it was before the library). A meta backend has `capabilities` and no `uri`. An image entry has `uri` (no `oci://` prefix), `mirrors` and, if you keep them, the same `capabilities`. Include both `latest-` (production) and `master-` (development) tags, and name the development entries `<name>-development`.
+
+**Step 3b: Merge them into the library**
+
+```bash
+go run ./scripts/backends/cmd/backendcatalog --add my-backend.yaml --library gallery/backends/index.yaml
+go run ./scripts/backends/cmd/backendcatalog --library gallery/backends/index.yaml --out backend/index.yaml
+```
+
+The first command converts the entries, pins every `latest-` image that is already in the registry to the digest of each platform, and merges the result into the library. Entries of other backends are not touched. An image that is not published yet (the usual case for a new backend, because CI builds it after the merge) is written unpinned and `mutable: true`: it installs by its tag, and a maintainer pins it with `--repin` once the image exists. A `master-` image is always `mutable`; the install pins it. The second command regenerates `backend/index.yaml`. Commit both files.
+
+To change a backend that is already there, put its new entries in the scratch file and run `--add` again: the entries of that backend are replaced where they stand. To pin every `latest-` image again after a release, run `go run ./scripts/backends/cmd/backendcatalog --library gallery/backends/index.yaml --repin`; this is the only mode that reads the registry, and a digest is never edited by hand.
 
 **Note on integrity:** OCI backends installed from a gallery whose `verification:` block is set are verified against a keyless-cosign policy before extraction; tarball/HTTP backends use the optional `sha256:` field. New backends do not need any extra YAML — the gallery-level `verification:` block covers every entry. See [.agents/backend-signing.md](backend-signing.md) for the producer-side CI step.
 
@@ -308,10 +319,9 @@ After adding a new backend, verify:
 
 - [ ] Backend directory structure is complete with all necessary files
 - [ ] Build configurations added to `.github/backend-matrix.yml` for all desired platforms (per-arch entries with `platform-tag` for multi-arch; `builder-base-image` for llama-cpp / ik-llama-cpp / turboquant)
-- [ ] **OS coverage considered**: added to `includeDarwin:` (macOS/Apple Silicon) if the backend can build there — with the `backend/index.yaml` `metal:` capability + `metal-<backend>` image entries, a `run.sh` Darwin/DYLD branch and `inferBackendPathDarwin` case (in `scripts/lib/backend-filter.mjs`) for C++ backends — or the PR explains why an OS is unsupported. Do not ship Linux-only by default.
-- [ ] Meta definition added to `backend/index.yaml` in the `## metas` section
-- [ ] Image entries added to `backend/index.yaml` for all build variants (latest + development)
-- [ ] Tag suffixes match between workflow file and index.yaml
+- [ ] **OS coverage considered**: added to `includeDarwin:` (macOS/Apple Silicon) if the backend can build there — with the `metal:` capability in the backend library + `metal-<backend>` image entries, a `run.sh` Darwin/DYLD branch and `inferBackendPathDarwin` case (in `scripts/lib/backend-filter.mjs`) for C++ backends — or the PR explains why an OS is unsupported. Do not ship Linux-only by default.
+- [ ] Meta definition and image entries added to the backend library with `backendcatalog --add`, for all build variants (latest + development), and `backend/index.yaml` regenerated (never edited by hand)
+- [ ] Tag suffixes match between the workflow file and the library entries
 - [ ] Makefile updated with all 6 required changes (`.NOTPARALLEL`, `prepare-test-extra`, `test-extra`, backend definition, docker-build target eval, `docker-build-backends`)
 - [ ] No YAML syntax errors (check with linter)
 - [ ] No Makefile syntax errors (check with linter)

.agents/adding-gallery-models.md

@@ -4,7 +4,9 @@ When adding a GGUF model from HuggingFace to the LocalAI model gallery, follow t
 
 ## Gallery file
 
-All models are defined in `gallery/index.yaml`. Find the appropriate section (embedding models near other embeddings, chat models near similar chat models) and add a new entry.
+The source of the models is the library file, `gallery/models/index.yaml`. Edit it there, in the library entry shape (header plus a `model:` body; see `docs/content/features/model-gallery.md`). `gallery/index.yaml` is a generated copy for releases before the cutover and is never edited by hand: after an edit run `go run ./scripts/models/cmd/modelcatalog --library gallery/models/index.yaml --out gallery/index.yaml` and commit both files. CI fails when the copy differs. The examples below use the gallery field names (`files`, `overrides`, `config_file`); in the library they sit under `model:`, with `config_file` written as `configFile`.
+
+Find the appropriate section (embedding models near other embeddings, chat models near similar chat models) and add a new entry.
 
 ## Getting the SHA256
 
@@ -207,7 +209,7 @@ Look at existing `.yaml` files in `gallery/` to find the right prompt template f
 1. **Find the GGUF file** on HuggingFace — note exact filename (case-sensitive)
 2. **Get the SHA256** using the `curl -sI` + `x-linked-etag` method above
 3. **Choose the right template** config from `gallery/` based on model architecture
-4. **Add the entry** to `gallery/index.yaml` near similar models
+4. **Add the entry** to `gallery/models/index.yaml` near similar models, then regenerate `gallery/index.yaml`
 5. **Set `embeddings: true`** if it's an embedding model
 6. **Include both URLs** — the original model page and the GGUF repo
 7. **Write a description** — mention model size, capabilities, and quantization type

.agents/localai-assistant-mcp.md

@@ -116,6 +116,12 @@ example Tables) follow a different, code-enforced rule, documented in
   `tools.Consumers` (`core/services/addons/tools/consumers.go`) as route or
   reject. The matrix test scans the sources and fails for an unclassified file.
 
+One backend route sits outside the add-on surface: `POST /backends/library/install`
+installs a backend (not an add-on) from a library entry. It is exposed as the
+`install_library_backend` tool and is a plain admin mutation under safety
+rule 1. Listing library entries stays on `/api/addons` and has no assistant
+tool, for the reason above.
+
 Do not rewrite the unrelated assistant tools to match this rule.
 
 ## Distributed mode

.github/workflows/backend-library.yml

@@ -0,0 +1,85 @@
+name: 'backend library'
+
+# gallery/backends/index.yaml is the backend library and the source of the
+# backends: edits go there. backend/index.yaml is a generated copy of it, kept
+# only so releases before the cutover keep working;
+# scripts/backends/cmd/backendcatalog writes it and it is never edited by hand.
+# This workflow fails when the library does not decode, an entry does not have
+# the library shape or does not round trip, the gallery reader does not load
+# the generated gallery, or backend/index.yaml differs from the generated copy.
+# It never reads the image registry: digests are pinned by hand-run
+# backendcatalog --repin, not by CI.
+
+on:
+  pull_request:
+    paths:
+      - 'backend/index.yaml'
+      - 'gallery/backends/**'
+      - 'scripts/backends/**'
+      - 'core/gallery/**'
+      - 'core/library/**'
+      - 'core/services/addons/catalog/**'
+      - 'core/services/addons/backendlib/**'
+      - '.github/workflows/backend-library.yml'
+  push:
+    branches: [master]
+    paths:
+      - 'backend/index.yaml'
+      - 'gallery/backends/**'
+      - 'scripts/backends/**'
+      - 'core/gallery/**'
+      - 'core/library/**'
+      - 'core/services/addons/catalog/**'
+      - 'core/services/addons/backendlib/**'
+      - '.github/workflows/backend-library.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: backend-library-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  backend-library:
+    name: 'Check the backend library'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+      - name: Generate the gRPC stubs the Go packages import
+        # The stubs are not in the tree. Same pinned tools as the test workflow.
+        run: |
+          curl -L -s https://github.com/protocolbuffers/protobuf/releases/download/v26.1/protoc-26.1-linux-x86_64.zip -o protoc.zip
+          sudo unzip -j -d /usr/local/bin protoc.zip bin/protoc
+          rm protoc.zip
+          go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.34.2
+          go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@1958fcbe2ca8bd93af633f11e97d44e567e945af
+          PATH="$PATH:$HOME/go/bin" make protogen-go
+      - name: Test the library, the generator and the gallery copy
+        # The library decodes and every entry has the library shape and passes
+        # the checks a host applies. The generator is deterministic. Every real
+        # gallery entry round trips through the library and back, a meta
+        # backend names backends the library has, and the gallery reader loads
+        # the generated gallery and sees the same backends as the library.
+        run: |
+          go test ./scripts/backends/...
+          go test ./core/services/addons/catalog/... ./core/services/addons/backendlib/...
+          go test ./core/gallery -run 'TestBackendLibrary|TestRealBackendLibrary|TestCheckedInBackendGalleryIsTheGeneratedCopy|TestLibraryGalleryReadsTheBackendLibrary|TestBackendRoundTrip|TestBackendsFromLibrary|TestToGalleryBackend|TestEncodeBackendGallery' -v
+      - name: Check that the gallery copy is the generated copy of the library
+        run: |
+          go run ./scripts/backends/cmd/backendcatalog --library gallery/backends/index.yaml --out backend/index.yaml
+          if ! git diff --exit-code -- backend/index.yaml; then
+            echo "::error file=backend/index.yaml::backend/index.yaml is generated from gallery/backends/index.yaml and must not be edited by hand. Edit the library file, then regenerate: go run ./scripts/backends/cmd/backendcatalog --library gallery/backends/index.yaml --out backend/index.yaml"
+            exit 1
+          fi
+      - name: Report the release entries that are not pinned
+        # A release image the registry had no image for when the library was
+        # rendered is marked mutable and has no digest. It installs, but it is
+        # not pinned. List them so a release does not ship them unnoticed.
+        run: |
+          go test ./core/gallery -run TestRealBackendLibraryHasTheLibraryShape -v | grep -E 'not pinned' | sed 's/^ *//; s/^/::warning::/' || true

.github/workflows/model-library.yml

@@ -0,0 +1,69 @@
+name: 'model library'
+
+# gallery/models/index.yaml is the model library and the source of the models:
+# edits go there. gallery/index.yaml is a generated copy of it, kept only so
+# releases before the cutover keep working; scripts/models/cmd/modelcatalog
+# writes it and it is never edited by hand. This workflow fails when the
+# library does not decode, an entry does not have the library shape or does
+# not round trip, the gallery reader does not load the generated gallery, or
+# gallery/index.yaml differs from the generated copy.
+
+on:
+  pull_request:
+    paths:
+      - 'gallery/index.yaml'
+      - 'gallery/models/**'
+      - 'scripts/models/**'
+      - 'core/gallery/**'
+      - '.github/workflows/model-library.yml'
+  push:
+    branches: [master]
+    paths:
+      - 'gallery/index.yaml'
+      - 'gallery/models/**'
+      - 'scripts/models/**'
+      - 'core/gallery/**'
+      - '.github/workflows/model-library.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: model-library-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  model-library:
+    name: 'Check the model library'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+      - name: Generate the gRPC stubs the Go packages import
+        # The stubs are not in the tree. Same pinned tools as the test workflow.
+        run: |
+          curl -L -s https://github.com/protocolbuffers/protobuf/releases/download/v26.1/protoc-26.1-linux-x86_64.zip -o protoc.zip
+          sudo unzip -j -d /usr/local/bin protoc.zip bin/protoc
+          rm protoc.zip
+          go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.34.2
+          go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@1958fcbe2ca8bd93af633f11e97d44e567e945af
+          PATH="$PATH:$HOME/go/bin" make protogen-go
+      - name: Test the library, the generator and the gallery copy
+        # The library decodes and every entry has the library shape. The
+        # generator is deterministic. Every real entry round trips through the
+        # generator to a gallery entry and back, and the gallery reader loads
+        # the generated gallery and sees the same names, uris and digests.
+        run: |
+          go test ./scripts/models/...
+          go test ./core/gallery -run 'TestModelLibrary|TestRealModelLibraryHasTheLibraryShape|TestGeneratedGalleryLoadsWithTheSameEntries|TestCheckedInGalleryIsTheGeneratedCopy|TestDecodeModelIndex'
+      - name: Check that the gallery copy is the generated copy of the library
+        run: |
+          go run ./scripts/models/cmd/modelcatalog --library gallery/models/index.yaml --out gallery/index.yaml
+          if ! git diff --exit-code -- gallery/index.yaml; then
+            echo "::error file=gallery/index.yaml::gallery/index.yaml is generated from gallery/models/index.yaml and must not be edited by hand. Edit the library file, then regenerate: go run ./scripts/models/cmd/modelcatalog --library gallery/models/index.yaml --out gallery/index.yaml"
+            exit 1
+          fi

.github/workflows/release.yaml

@@ -17,6 +17,18 @@ jobs:
         uses: actions/setup-go@v5
         with:
           go-version-file: go.mod
+      # The cutover. A tagged build reads the model gallery (localai) by default
+      # until this step runs; from here the tagged build reads the model library
+      # (official-models, gallery/models/index.yaml) and not the gallery.
+      # .goreleaser.yaml passes the value to the binary with -ldflags.
+      - name: Cut the default model source over to the library
+        run: echo "LOCALAI_MODEL_SOURCE=library" >> "$GITHUB_ENV"
+      # The same cutover for the backends: until this step runs, a tagged build
+      # reads the backend gallery (localai-backends, backend/index.yaml, which
+      # is generated from the backend library). From here it reads the backend
+      # library (official-backends, gallery/backends/index.yaml).
+      - name: Cut the default backend source over to the library
+        run: echo "LOCALAI_BACKEND_SOURCE=library" >> "$GITHUB_ENV"
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v7
         with:

.goreleaser.yaml

@@ -17,6 +17,12 @@ builds:
       - -s -w
       - -X "github.com/mudler/LocalAI/internal.Version={{ .Tag }}"
       - -X "github.com/mudler/LocalAI/internal.Commit={{ .FullCommit }}"
+      # A tagged build reads the gallery until the release workflow sets
+      # LOCALAI_MODEL_SOURCE=library (the cutover step in release.yaml).
+      - -X "github.com/mudler/LocalAI/core/library.ModelSource={{ envOrDefault "LOCALAI_MODEL_SOURCE" "gallery" }}"
+      # The same for the backends: a tagged build reads the backend gallery
+      # until the release workflow sets LOCALAI_BACKEND_SOURCE=library.
+      - -X "github.com/mudler/LocalAI/core/library.BackendSource={{ envOrDefault "LOCALAI_BACKEND_SOURCE" "gallery" }}"
     goos:
       - linux
       - darwin

AGENTS.md

@@ -48,7 +48,7 @@ LocalAI follows the Linux kernel project's [guidelines for AI coding assistants]
 - **Admin endpoints → MCP tool**: every admin endpoint that an admin would manage conversationally (install/list/edit/toggle/upgrade) MUST also be exposed as an MCP tool in `pkg/mcp/localaitools/`. The LocalAI Assistant chat modality and the standalone `local-ai mcp-server` consume that package; drift between REST and MCP is a real risk. Read [.agents/localai-assistant-mcp.md](.agents/localai-assistant-mcp.md) — the `TestToolHTTPRouteMappingComplete` test fails until you wire the new tool and update the route map.
 - **Releases ship with a post and clips**: a release is not done at the tag. It needs labelled PRs, `RELEASE_NOTES_vX.Y.Z.md`, a blog post under `website/content/blog/`, and a short demo clip in `website/static/media/` for each notable feature. See [.agents/preparing-a-release.md](.agents/preparing-a-release.md).
 - **Build**: Inspect `Makefile` and `.github/workflows/` — ask the user before running long builds
-- **Backend OS coverage**: a new backend must target every OS it can build for, not just Linux. `.github/backend-matrix.yml` has two matrices — `include:` (Linux) and `includeDarwin:` (macOS / Apple Silicon). Most C/C++/GGML and many Python backends build on Darwin too — wire the `includeDarwin` entry + `backend/index.yaml` `metal:` entries, or say in the PR why an OS is unsupported. See the darwin checklist in [.agents/adding-backends.md](.agents/adding-backends.md).
+- **Backend OS coverage**: a new backend must target every OS it can build for, not just Linux. `.github/backend-matrix.yml` has two matrices — `include:` (Linux) and `includeDarwin:` (macOS / Apple Silicon). Most C/C++/GGML and many Python backends build on Darwin too — wire the `includeDarwin` entry + the `metal:` entries of the backend library (`gallery/backends/index.yaml`, added with `backendcatalog --add`; `backend/index.yaml` is generated, never edited), or say in the PR why an OS is unsupported. See the darwin checklist in [.agents/adding-backends.md](.agents/adding-backends.md).
 - **Gallery variant ranking**: a gallery entry can declare `variants` (alternative builds of the same weights), and LocalAI ranks the ones a host can run by engine preference first, size second. A new backend that should be preferred on some hardware must be listed in `engineNamePreferenceRules` in `pkg/system/capabilities.go`; the sibling `backendBuildTagPreferenceRules` speaks build tags rather than engine names, and using the wrong table matches nothing without erroring. See [.agents/adding-backends.md](.agents/adding-backends.md).
 - **UI**: The active UI is the React app in `core/http/react-ui/`. The older Alpine.js/HTML UI in `core/http/static/` is pending deprecation — all new UI work goes in the React UI
 - **Distributed-aware state**: any feature that keeps runtime state (maps, caches, pins, schedulers, background loops) must choose shared (syncstate), single-runner (advisorylock), stateless, or documented per-instance behaviour for multi-frontend clusters. See [.agents/distributed-state.md](.agents/distributed-state.md).

Makefile

@@ -45,6 +45,19 @@ LAUNCHER_APP_VERSION?=$(shell v=$$(echo "$(VERSION)" | sed -E 's/^v//; s/[+-].*$
 LD_FLAGS?=-s -w
 override LD_FLAGS += -X "github.com/mudler/LocalAI/internal.Version=$(VERSION)"
 override LD_FLAGS += -X "github.com/mudler/LocalAI/internal.Commit=$(shell git rev-parse HEAD)"
+# The model source the binary reads by default: "library" (the model library) or
+# "gallery" (the gallery named localai). A build from master reads the library.
+# A build of a commit that carries a tag reads the gallery until the release
+# workflow cuts over by setting LOCALAI_MODEL_SOURCE=library (see release.yaml).
+LOCALAI_MODEL_SOURCE?=$(shell git describe --exact-match --tags >/dev/null 2>&1 && echo gallery || echo library)
+override LD_FLAGS += -X "github.com/mudler/LocalAI/core/library.ModelSource=$(LOCALAI_MODEL_SOURCE)"
+# The backend source follows the same rule: "library" (the backend library,
+# gallery/backends/index.yaml) or "gallery" (the gallery named localai-backends,
+# backend/index.yaml, which is generated from the library). A build from master
+# reads the library; a build of a commit that carries a tag reads the gallery
+# until the release workflow cuts over with LOCALAI_BACKEND_SOURCE=library.
+LOCALAI_BACKEND_SOURCE?=$(shell git describe --exact-match --tags >/dev/null 2>&1 && echo gallery || echo library)
+override LD_FLAGS += -X "github.com/mudler/LocalAI/core/library.BackendSource=$(LOCALAI_BACKEND_SOURCE)"
 
 OPTIONAL_TARGETS?=
 

core/application/application.go

@@ -16,7 +16,9 @@ import (
 	"github.com/mudler/LocalAI/core/config"
 	"github.com/mudler/LocalAI/core/http/auth"
 	mcpTools "github.com/mudler/LocalAI/core/http/endpoints/mcp"
+	"github.com/mudler/LocalAI/core/library"
 	"github.com/mudler/LocalAI/core/services/addons"
+	"github.com/mudler/LocalAI/core/services/addons/backendlib"
 	"github.com/mudler/LocalAI/core/services/addons/catalog"
 	"github.com/mudler/LocalAI/core/services/addons/gateway"
 	"github.com/mudler/LocalAI/core/services/addons/packages"
@@ -80,8 +82,14 @@ type Application struct {
 	addonGateway       *gateway.Gateway
 	addonServer        *http.Server
 	addonSources       *catalog.Sources
+	backendLibrary     *backendlib.Installer
 	addonManager       *addons.Manager
 	addonHostOps       *addonruntime.HostOps
+
+	// libraryStore is the library sources file when no add-on owner runs here.
+	libraryStore   *catalog.Sources
+	libraryStoreMu sync.Mutex
+
 	// The pin store is built once so the routes and the retention sweep share it.
 	addonPinStoreOnce    sync.Once
 	addonPinStore        pins.Store
@@ -679,6 +687,9 @@ func (a *Application) start() (startErr error) {
 		assistantClient.StatsRecorder = a.statsRecorder
 		assistantClient.FallbackUser = a.fallbackUser
 		assistantClient.VoiceProfiles = a.voiceProfileStore
+		if a.backendLibrary != nil {
+			assistantClient.BackendLibrary = libraryInstallNoProgress{a.backendLibrary}
+		}
 		if a.distributed != nil && a.distributed.Unloader != nil {
 			assistantClient.LoadStopper = a.distributed.Unloader
 		}
@@ -824,6 +835,10 @@ func (a *Application) StartAgentPool() {
 // AddonManager is nil unless the deployment explicitly enables addons.
 func (a *Application) AddonManager() *addons.Manager { return a.addonManager }
 
+// BackendLibrary installs backends from the library entries of kind backend.
+// It is nil unless this instance owns the add-on libraries.
+func (a *Application) BackendLibrary() *backendlib.Installer { return a.backendLibrary }
+
 // AddonSources exposes owner-only source administration and explicit live refresh.
 // Forwarders never load source configuration or perform catalog I/O.
 func (a *Application) AddonSources() *catalog.Sources { return a.addonSources }
@@ -867,8 +882,16 @@ func (a *Application) startAddons() error {
 		if err != nil {
 			return err
 		}
+		var defaults []catalog.Source
 		if c.OfficialLibrary {
-			if _, err = sources.SeedDefault(catalog.OfficialLibrary()); err != nil {
+			defaults = append(defaults, catalog.OfficialLibrary())
+		}
+		if c.OfficialBackendLibrary {
+			defaults = append(defaults, library.DefaultBackendLibrary())
+		}
+		sources.SetOfficial(a.applicationConfig.OfficialLibraries)
+		if len(defaults) > 0 {
+			if _, err = sources.SeedDefaults(defaults...); err != nil {
 				return err
 			}
 		}
@@ -936,6 +959,12 @@ func (a *Application) startAddons() error {
 		}
 	}
 	a.addonSources = cat.Sources
+	if cat.Sources != nil {
+		a.backendLibrary = &backendlib.Installer{
+			Catalog: cat, SystemState: a.applicationConfig.SystemState, ModelLoader: a.modelLoader,
+			MaxBytes: c.BackendMaxBytes, RequireIntegrity: a.applicationConfig.RequireBackendIntegrity,
+		}
+	}
 	a.addonManager = m
 	if c.InstanceID == c.OwnerID {
 		go a.runAddonAutoUpgrade(a.applicationConfig.Context, upgradeInitialDelay, upgradeCheckInterval)
@@ -946,3 +975,11 @@ func (a *Application) startAddons() error {
 	}
 	return nil
 }
+
+// libraryInstallNoProgress adapts the library installer to the assistant's
+// installer interface, which does not report progress.
+type libraryInstallNoProgress struct{ in *backendlib.Installer }
+
+func (l libraryInstallNoProgress) Install(ctx context.Context, sourceID, backend, version string) error {
+	return l.in.Install(ctx, sourceID, backend, version, backendlib.Progress{})
+}

core/application/library_sources.go

@@ -0,0 +1,77 @@
+package application
+
+import (
+	"context"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/gallery"
+	"github.com/mudler/LocalAI/core/library"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"github.com/mudler/xlog"
+)
+
+// LibrarySources returns the one store of library sources this process works
+// on. When the add-on owner runs here it is the owner's store, so a change made
+// through the HTTP routes and the add-on catalog cannot overwrite each other;
+// otherwise the store file under the data path is opened once. It is the file
+// `local-ai library` edits.
+func (a *Application) LibrarySources() (*catalog.Sources, error) {
+	if a.addonSources != nil {
+		return a.addonSources, nil
+	}
+	a.libraryStoreMu.Lock()
+	defer a.libraryStoreMu.Unlock()
+	if a.libraryStore != nil {
+		return a.libraryStore, nil
+	}
+	s, err := catalog.OpenStore(catalog.StorePath(a.applicationConfig.DataPath))
+	if err != nil {
+		return nil, err
+	}
+	s.SetOfficial(a.applicationConfig.OfficialLibraries)
+	a.libraryStore = s
+	return s, nil
+}
+
+// ApplyLibraries makes the running server follow the library store: it sets
+// the official-libraries switch, brings the model and backend galleries in line
+// with the enabled sources and, for sources the add-on catalog reads, fetches
+// those that just came back. dropped names the addresses of deleted sources.
+// It is called after the HTTP routes change a
+// source and after the official_libraries setting changes.
+func (a *Application) ApplyLibraries(dropped ...string) error {
+	store, err := a.LibrarySources()
+	if err != nil {
+		return err
+	}
+	cfg := a.applicationConfig
+	changed := store.SetOfficial(cfg.OfficialLibraries)
+	prevM, prevB := cfg.Galleries, cfg.BackendGalleries
+	cfg.Galleries, cfg.BackendGalleries = library.Reconcile(store, cfg.Galleries, cfg.BackendGalleries, dropped...)
+	gallery.ResetGalleryModelCacheIfChanged(prevM, prevB, cfg)
+	if changed || a.addonSources != nil {
+		go func() {
+			if err := store.RefreshEnabled(context.Background()); err != nil {
+				xlog.Warn("could not refresh the library sources", "error", err)
+			}
+		}()
+	}
+	return nil
+}
+
+// applyOfficialLibrariesAtStartup drops the shipped default galleries from the
+// lists the server reads when the persisted setting turned the official
+// libraries off. The command line default is on, so this only acts on a saved
+// setting.
+func applyOfficialLibrariesAtStartup(cfg *config.ApplicationConfig) {
+	if cfg.OfficialLibraries || cfg.DataPath == "" {
+		return
+	}
+	store, err := catalog.OpenStore(catalog.StorePath(cfg.DataPath))
+	if err != nil {
+		xlog.Warn("official libraries are not turned off", "error", err)
+		return
+	}
+	store.SetOfficial(false)
+	cfg.Galleries, cfg.BackendGalleries = library.Reconcile(store, cfg.Galleries, cfg.BackendGalleries)
+}

core/application/library_sources_test.go

@@ -0,0 +1,74 @@
+package application
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/library"
+)
+
+// shipped sets the galleries a run with the default flags starts with.
+func shipped(t *testing.T, cfg *config.ApplicationConfig) {
+	t.Helper()
+	if err := json.Unmarshal([]byte(config.DefaultGalleriesJSON), &cfg.Galleries); err != nil {
+		t.Fatal(err)
+	}
+	if err := json.Unmarshal([]byte(config.DefaultBackendGalleriesJSON), &cfg.BackendGalleries); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestApplyLibrariesFollowsTheOfficialSwitchInBothStates(t *testing.T) {
+	dir := t.TempDir()
+	cfg := config.NewApplicationConfig(config.WithDataPath(dir))
+	shipped(t, cfg)
+	library.Option(dir, true, false, true)(cfg)
+	wantModels, wantBackends := len(cfg.Galleries), len(cfg.BackendGalleries)
+	if wantModels == 0 || wantBackends == 0 {
+		t.Fatalf("the shipped galleries were not mapped: %d, %d", wantModels, wantBackends)
+	}
+	// A gallery of the user, so the off state has something left to read.
+	store, err := library.Open(dir, true, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := library.Add(store, "model", "https://example.org/team.yaml", "team", "Team", "gallery"); err != nil {
+		t.Fatal(err)
+	}
+	a := &Application{applicationConfig: cfg}
+
+	cfg.OfficialLibraries = false
+	if err := a.ApplyLibraries(); err != nil {
+		t.Fatal(err)
+	}
+	if len(cfg.Galleries) != 1 || cfg.Galleries[0].URL != "https://example.org/team.yaml" || len(cfg.BackendGalleries) != 0 {
+		t.Errorf("off: models %+v backends %+v", cfg.Galleries, cfg.BackendGalleries)
+	}
+
+	cfg.OfficialLibraries = true
+	if err := a.ApplyLibraries(); err != nil {
+		t.Fatal(err)
+	}
+	if len(cfg.Galleries) != wantModels+1 || len(cfg.BackendGalleries) != wantBackends {
+		t.Errorf("on: models %+v backends %+v", cfg.Galleries, cfg.BackendGalleries)
+	}
+}
+
+func TestOfficialLibrariesOffAtStartupDropsTheDefaultGalleries(t *testing.T) {
+	dir := t.TempDir()
+	cfg := config.NewApplicationConfig(config.WithDataPath(dir))
+	shipped(t, cfg)
+	library.Option(dir, true, false, true)(cfg)
+
+	cfg.OfficialLibraries = true
+	applyOfficialLibrariesAtStartup(cfg)
+	if len(cfg.Galleries) == 0 || len(cfg.BackendGalleries) == 0 {
+		t.Fatal("on: the default galleries were dropped")
+	}
+	cfg.OfficialLibraries = false
+	applyOfficialLibrariesAtStartup(cfg)
+	if len(cfg.Galleries) != 0 || len(cfg.BackendGalleries) != 0 {
+		t.Errorf("off: models %+v backends %+v", cfg.Galleries, cfg.BackendGalleries)
+	}
+}

core/application/startup.go

@@ -55,6 +55,7 @@ func New(opts ...config.AppOption) (*Application, error) {
 	// full restart. Env/CLI values win over the file (see
 	// ApplyRuntimeSettingsAtStartup).
 	loadStartupSettings(options)
+	applyOfficialLibrariesAtStartup(options)
 
 	// WithThreads no longer eagerly resolves 0 (so the settings merge can
 	// tell "unset" from "env-set"); resolve the physical-core default now
@@ -504,6 +505,13 @@ func New(opts ...config.AppOption) (*Application, error) {
 		bmFn := func() galleryop.BackendManager { return application.GalleryService().BackendManager() }
 		uc := NewUpgradeChecker(options, application.ModelLoader(), application.distributedDB(), bmFn)
 		application.upgradeChecker = uc
+		// Library backends follow the same auto_upgrade_backends switch.
+		uc.SetLibraryBackends(func() libraryUpgrader {
+			if l := application.BackendLibrary(); l != nil {
+				return l
+			}
+			return nil
+		})
 		// A request that proves a backend is older than the server marks it
 		// stale; refresh the upgrade cache so /backends/upgrades shows it.
 		gallery.SetStaleBackendNotifier(uc.TriggerCheck)

core/application/upgrade_checker.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/mudler/LocalAI/core/config"
 	"github.com/mudler/LocalAI/core/gallery"
+	"github.com/mudler/LocalAI/core/services/addons/backendlib"
 	"github.com/mudler/LocalAI/core/services/advisorylock"
 	"github.com/mudler/LocalAI/core/services/galleryop"
 	"github.com/mudler/LocalAI/pkg/model"
@@ -41,6 +42,11 @@ type UpgradeChecker struct {
 	// frontend filesystem — fixing the bug where upgrades never surfaced.
 	backendManagerFn func() galleryop.BackendManager
 
+	// libraryFn returns the installer of library backends, or nil when the
+	// host has none. It is read on each check because the add-on owner starts
+	// after the checker is built.
+	libraryFn func() libraryUpgrader
+
 	checkInterval time.Duration
 	stop          chan struct{}
 	done          chan struct{}
@@ -164,7 +170,46 @@ func (uc *UpgradeChecker) GetAvailableUpgrades() map[string]gallery.UpgradeInfo
 	return result
 }
 
+// libraryUpgrader is the part of the library backend installer the checker
+// needs: the newer builds the library lists, and the install of one.
+type libraryUpgrader interface {
+	Updates(ctx context.Context) ([]backendlib.Update, error)
+	Install(ctx context.Context, sourceID, backend, version string, progress backendlib.Progress) error
+}
+
+// SetLibraryBackends makes the checker upgrade library backends too. fn may
+// return nil while the host has no library.
+func (uc *UpgradeChecker) SetLibraryBackends(fn func() libraryUpgrader) { uc.libraryFn = fn }
+
+// upgradeLibraryBackends follows the same switch as the gallery backends:
+// with auto_upgrade_backends on, a library backend moves to the newer build
+// the library lists; with it off nothing is installed and the Update button on
+// the Backends page stays the only way. The switch is read on every check, so
+// a change in the runtime settings applies at the next one.
+func (uc *UpgradeChecker) upgradeLibraryBackends(ctx context.Context) {
+	if !uc.appConfig.AutoUpgradeBackends || uc.libraryFn == nil {
+		return
+	}
+	lib := uc.libraryFn()
+	if lib == nil {
+		return
+	}
+	updates, err := lib.Updates(ctx)
+	if err != nil {
+		xlog.Debug("Library backend upgrade check failed", "error", err)
+		return
+	}
+	for _, u := range updates {
+		xlog.Info("Auto-upgrading library backend", "backend", u.Name, "library", u.SourceID,
+			"from", u.InstalledVersion, "to", u.Version)
+		if err := lib.Install(ctx, u.SourceID, u.Name, u.Version, backendlib.Progress{}); err != nil {
+			xlog.Error("Failed to auto-upgrade library backend", "backend", u.Name, "error", err)
+		}
+	}
+}
+
 func (uc *UpgradeChecker) runCheck(ctx context.Context) {
+	defer uc.upgradeLibraryBackends(ctx)
 	var (
 		upgrades map[string]gallery.UpgradeInfo
 		err      error

core/application/upgrade_checker_library_test.go

@@ -0,0 +1,44 @@
+package application
+
+import (
+	"context"
+	"testing"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/services/addons/backendlib"
+)
+
+type fakeLibrary struct {
+	updates   []backendlib.Update
+	installed []string
+}
+
+func (f *fakeLibrary) Updates(context.Context) ([]backendlib.Update, error) { return f.updates, nil }
+func (f *fakeLibrary) Install(_ context.Context, source, name, version string, _ backendlib.Progress) error {
+	f.installed = append(f.installed, source+"/"+name+"@"+version)
+	return nil
+}
+
+func TestLibraryBackendsFollowAutoUpgradeSwitch(t *testing.T) {
+	for _, on := range []bool{true, false} {
+		lib := &fakeLibrary{updates: []backendlib.Update{{Name: "whisper", SourceID: "official-backends", Version: "1.2.0"}}}
+		uc := &UpgradeChecker{appConfig: &config.ApplicationConfig{AutoUpgradeBackends: on}}
+		uc.SetLibraryBackends(func() libraryUpgrader { return lib })
+		uc.upgradeLibraryBackends(context.Background())
+		if on && len(lib.installed) != 1 {
+			t.Fatalf("switch on: want one upgrade, got %v", lib.installed)
+		}
+		if on && lib.installed[0] != "official-backends/whisper@1.2.0" {
+			t.Fatalf("wrong install %v", lib.installed)
+		}
+		if !on && len(lib.installed) != 0 {
+			t.Fatalf("switch off: nothing may install, got %v", lib.installed)
+		}
+	}
+}
+
+func TestLibraryBackendsWithoutLibrary(t *testing.T) {
+	uc := &UpgradeChecker{appConfig: &config.ApplicationConfig{AutoUpgradeBackends: true}}
+	uc.SetLibraryBackends(func() libraryUpgrader { return nil })
+	uc.upgradeLibraryBackends(context.Background())
+}

core/cli/cli.go

@@ -15,6 +15,7 @@ var CLI struct {
 	Federated       FederatedCLI       `cmd:"" help:"Run LocalAI in federated mode"`
 	Models          ModelsCMD          `cmd:"" help:"Manage LocalAI models and definitions"`
 	Backends        BackendsCMD        `cmd:"" help:"Manage LocalAI backends and definitions"`
+	Library         LibraryCMD         `cmd:"" help:"Manage the library sources LocalAI reads add-ons, backends and models from"`
 	TTS             TTSCMD             `cmd:"" help:"Convert text to speech"`
 	SoundGeneration SoundGenerationCMD `cmd:"" help:"Generates audio files from text or audio"`
 	Transcript      TranscriptCMD      `cmd:"" help:"Convert audio to text"`

core/cli/library.go

@@ -0,0 +1,168 @@
+package cli
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"text/tabwriter"
+
+	cliContext "github.com/mudler/LocalAI/core/cli/context"
+	"github.com/mudler/LocalAI/core/library"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+)
+
+// LibraryFlags are shared by every `local-ai library` command. The sources are
+// stored under the data path, in the file the server reads, so the commands
+// work with the server stopped.
+type LibraryFlags struct {
+	DataPath              string `env:"LOCALAI_DATA_PATH" type:"path" default:"${basepath}/data" help:"Path for persistent data. The library sources are stored under it, in addons/sources.json, the file the server reads" group:"storage"`
+	AddonsOfficialLibrary bool   `name:"addons-official-library" env:"LOCALAI_ADDONS_OFFICIAL_LIBRARY" default:"true" help:"List the official add-on library as a default source" group:"addons"`
+	AddonsBackendLibrary  bool   `name:"addons-backend-library" env:"LOCALAI_ADDONS_BACKEND_LIBRARY" default:"true" help:"List the backend library as a default source. Turn it off to read the backend gallery only" group:"addons"`
+	OfficialLibraries     bool   `name:"official-libraries" env:"LOCALAI_OFFICIAL_LIBRARIES" default:"true" help:"Use the official (shipped default) library sources of every kind. Off: they stay in the list, shown as off" group:"addons"`
+}
+
+func (f LibraryFlags) open() (*catalog.Sources, error) {
+	store, err := library.Open(f.DataPath, f.AddonsOfficialLibrary, f.AddonsBackendLibrary)
+	if err != nil {
+		return nil, err
+	}
+	store.SetOfficial(f.OfficialLibraries)
+	return store, nil
+}
+
+// LibraryCMD manages the sources LocalAI reads add-ons, backends and models from.
+type LibraryCMD struct {
+	List    LibraryList    `cmd:"" default:"withargs" help:"List the library sources, with their kind, state and whether they are shipped defaults"`
+	Add     LibraryAdd     `cmd:"" help:"Add a library source of your own"`
+	Remove  LibraryRemove  `cmd:"" help:"Remove a source. A removed default stays removed at the next start"`
+	Enable  LibraryEnable  `cmd:"" help:"Turn a source on (this also brings back a removed default)"`
+	Disable LibraryDisable `cmd:"" help:"Turn a source off without removing it"`
+}
+
+type LibraryList struct {
+	LibraryFlags `embed:""`
+}
+
+type LibraryAdd struct {
+	URL    string `arg:"" name:"url" help:"URL of the library index"`
+	Kind   string `required:"" enum:"addon,backend,model" help:"What the source provides: addon, backend or model"`
+	ID     string `help:"Source id: lowercase letters, digits and dashes. Default: derived from the name or URL"`
+	Name   string `help:"Display name. Default: the id"`
+	Format string `default:"library" enum:"library,gallery" help:"library: an index in the shared library entry shape. gallery: a model or backend gallery index, as --galleries names"`
+
+	LibraryFlags `embed:""`
+}
+
+type LibraryRemove struct {
+	ID string `arg:"" name:"id" help:"Source id"`
+
+	LibraryFlags `embed:""`
+}
+
+type LibraryEnable struct {
+	ID string `arg:"" name:"id" help:"Source id"`
+
+	LibraryFlags `embed:""`
+}
+
+type LibraryDisable struct {
+	ID string `arg:"" name:"id" help:"Source id"`
+
+	LibraryFlags `embed:""`
+}
+
+func yesNo(b bool) string {
+	if b {
+		return "yes"
+	}
+	return "no"
+}
+
+// writeSources prints the table `library list` shows. Removed is "yes" only for
+// a default the user removed; such a record is kept as a tombstone.
+func writeSources(w io.Writer, entries []catalog.Source) error {
+	tw := tabwriter.NewWriter(w, 2, 4, 2, ' ', 0)
+	fmt.Fprintln(tw, "KIND\tID\tURL\tENABLED\tDEFAULT\tREMOVED")
+	for _, e := range entries {
+		fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\n", e.Kind, e.ID, e.URL, yesNo(e.Enabled && !e.Suspended), yesNo(e.Default), yesNo(e.Removed))
+	}
+	return tw.Flush()
+}
+
+func (c *LibraryList) Run(_ *cliContext.Context) error {
+	store, err := c.open()
+	if err != nil {
+		return err
+	}
+	return writeSources(os.Stdout, store.Entries())
+}
+
+func (c *LibraryAdd) Run(_ *cliContext.Context) error {
+	store, err := c.open()
+	if err != nil {
+		return err
+	}
+	format := ""
+	if c.Format == "gallery" {
+		format = catalog.FormatGallery
+	}
+	src, err := library.Add(store, catalog.Kind(c.Kind), c.URL, c.ID, c.Name, format)
+	if err != nil {
+		if errors.Is(err, catalog.ErrInvalid) {
+			return fmt.Errorf("cannot add %q as a %s source: the id must be lowercase letters, digits and dashes and start with a letter, and a library index URL must be http or https (use --format=gallery for a gallery index)", c.URL, c.Kind)
+		}
+		return err
+	}
+	fmt.Printf("added %s source %s (%s)\n", src.Kind, src.ID, src.URL)
+	return nil
+}
+
+func (c *LibraryRemove) Run(_ *cliContext.Context) error {
+	store, err := c.open()
+	if err != nil {
+		return err
+	}
+	wasDefault, err := library.Remove(store, c.ID)
+	if err != nil {
+		return notFound(err, c.ID)
+	}
+	if wasDefault {
+		fmt.Printf("removed default source %s; it stays removed at the next start (local-ai library enable %s brings it back)\n", c.ID, c.ID)
+	} else {
+		fmt.Printf("removed source %s\n", c.ID)
+	}
+	return nil
+}
+
+func (c *LibraryEnable) Run(_ *cliContext.Context) error {
+	store, err := c.open()
+	if err != nil {
+		return err
+	}
+	if err := store.SetEnabled(c.ID, true); err != nil {
+		return notFound(err, c.ID)
+	}
+	fmt.Printf("enabled source %s\n", c.ID)
+	return nil
+}
+
+func (c *LibraryDisable) Run(_ *cliContext.Context) error {
+	store, err := c.open()
+	if err != nil {
+		return err
+	}
+	if err := store.SetEnabled(c.ID, false); err != nil {
+		return notFound(err, c.ID)
+	}
+	fmt.Printf("disabled source %s\n", c.ID)
+	return nil
+}
+
+func notFound(err error, id string) error {
+	if errors.Is(err, catalog.ErrNotFound) {
+		return fmt.Errorf("no source with id %q; run `local-ai library list` to see them", strings.TrimSpace(id))
+	}
+	return err
+}

core/cli/library_test.go

@@ -0,0 +1,166 @@
+package cli
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/mudler/LocalAI/core/library"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+)
+
+func libFlags(t *testing.T, dir string) LibraryFlags {
+	t.Helper()
+	return LibraryFlags{DataPath: dir, AddonsOfficialLibrary: true}
+}
+
+func entry(t *testing.T, f LibraryFlags, id string) (catalog.Source, bool) {
+	t.Helper()
+	store, err := f.open()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, e := range store.Entries() {
+		if e.ID == id {
+			return e, true
+		}
+	}
+	return catalog.Source{}, false
+}
+
+func TestLibraryListShowsDefaultsOfEveryKind(t *testing.T) {
+	f := libFlags(t, t.TempDir())
+	store, err := f.open()
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out bytes.Buffer
+	if err := writeSources(&out, store.Entries()); err != nil {
+		t.Fatal(err)
+	}
+	got := out.String()
+	for _, want := range []string{"KIND", "ENABLED", "DEFAULT", "REMOVED", "addon", "official", "backend", "localai-backends", "model", "localai"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("list is missing %q:\n%s", want, got)
+		}
+	}
+	// A master build enables the model library and ships the localai gallery
+	// off, so every model is listed once.
+	for id, enabled := range map[string]bool{"official": true, "official-models": library.UseModelLibrary(), "localai": !library.UseModelLibrary(), "localai-backends": true} {
+		e, ok := entry(t, f, id)
+		if !ok || !e.Default || e.Enabled != enabled || e.Removed {
+			t.Errorf("default %s = %+v, %v, want enabled=%v", id, e, ok, enabled)
+		}
+	}
+}
+
+func TestLibraryAddKinds(t *testing.T) {
+	f := libFlags(t, t.TempDir())
+	for _, kind := range []string{"addon", "backend", "model"} {
+		c := LibraryAdd{URL: "https://example.org/" + kind + ".yaml", Kind: kind, ID: "mine-" + kind, Name: "Mine " + kind, Format: "library", LibraryFlags: f}
+		if err := c.Run(nil); err != nil {
+			t.Fatalf("add %s: %v", kind, err)
+		}
+		e, ok := entry(t, f, "mine-"+kind)
+		if !ok || e.Default || !e.Enabled || string(e.Kind) != kind || e.Name != "Mine "+kind {
+			t.Errorf("%s source = %+v, %v", kind, e, ok)
+		}
+	}
+	// The same URL and kind twice, and a taken id, are refused.
+	if err := (&LibraryAdd{URL: "https://example.org/addon.yaml", Kind: "addon", ID: "other", LibraryFlags: f, Format: "library"}).Run(nil); err == nil {
+		t.Error("the same url was added twice")
+	}
+	if err := (&LibraryAdd{URL: "https://example.org/x.yaml", Kind: "addon", ID: "mine-addon", LibraryFlags: f, Format: "library"}).Run(nil); err == nil {
+		t.Error("a taken id was accepted")
+	}
+	if err := (&LibraryAdd{URL: "not a url", Kind: "addon", LibraryFlags: f, Format: "library"}).Run(nil); err == nil {
+		t.Error("a bad url was accepted")
+	}
+}
+
+func TestLibraryAddDerivesTheID(t *testing.T) {
+	f := libFlags(t, t.TempDir())
+	if err := (&LibraryAdd{URL: "https://example.org/lib.yaml", Kind: "model", Name: "My Models", Format: "library", LibraryFlags: f}).Run(nil); err != nil {
+		t.Fatal(err)
+	}
+	if e, ok := entry(t, f, "my-models"); !ok || e.Name != "My Models" {
+		t.Errorf("derived id: %+v, %v", e, ok)
+	}
+}
+
+func TestLibraryRemoveLeavesATombstoneForADefault(t *testing.T) {
+	dir := t.TempDir()
+	f := libFlags(t, dir)
+	if err := (&LibraryRemove{ID: "official", LibraryFlags: f}).Run(nil); err != nil {
+		t.Fatal(err)
+	}
+	// A new open stands for the next start: the default must not come back.
+	e, ok := entry(t, f, "official")
+	if !ok || !e.Removed || e.Enabled || !e.Default {
+		t.Fatalf("after remove: %+v, %v", e, ok)
+	}
+	// Removing it again finds nothing to remove.
+	if err := (&LibraryRemove{ID: "official", LibraryFlags: f}).Run(nil); err == nil {
+		t.Error("a removed source was removed twice")
+	}
+	// Enable brings it back.
+	if err := (&LibraryEnable{ID: "official", LibraryFlags: f}).Run(nil); err != nil {
+		t.Fatal(err)
+	}
+	if e, _ := entry(t, f, "official"); e.Removed || !e.Enabled {
+		t.Errorf("after enable: %+v", e)
+	}
+}
+
+func TestLibraryRemoveDeletesAUserSource(t *testing.T) {
+	f := libFlags(t, t.TempDir())
+	if err := (&LibraryAdd{URL: "https://example.org/a.yaml", Kind: "addon", ID: "mine", Format: "library", LibraryFlags: f}).Run(nil); err != nil {
+		t.Fatal(err)
+	}
+	if err := (&LibraryRemove{ID: "mine", LibraryFlags: f}).Run(nil); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := entry(t, f, "mine"); ok {
+		t.Error("a removed user source left a record")
+	}
+}
+
+func TestLibraryEnableAndDisable(t *testing.T) {
+	f := libFlags(t, t.TempDir())
+	if err := (&LibraryDisable{ID: "localai", LibraryFlags: f}).Run(nil); err != nil {
+		t.Fatal(err)
+	}
+	if e, _ := entry(t, f, "localai"); e.Enabled || e.Removed {
+		t.Errorf("after disable: %+v", e)
+	}
+	if err := (&LibraryEnable{ID: "localai", LibraryFlags: f}).Run(nil); err != nil {
+		t.Fatal(err)
+	}
+	if e, _ := entry(t, f, "localai"); !e.Enabled {
+		t.Errorf("after enable: %+v", e)
+	}
+	if err := (&LibraryEnable{ID: "nope", LibraryFlags: f}).Run(nil); err == nil || !strings.Contains(err.Error(), "no source") {
+		t.Errorf("unknown id: %v", err)
+	}
+}
+
+// The store file is what the server reads: a second open sees the same state.
+func TestLibraryStateIsSharedThroughTheFile(t *testing.T) {
+	dir := t.TempDir()
+	f := libFlags(t, dir)
+	if err := (&LibraryAdd{URL: "https://example.org/a.yaml", Kind: "backend", ID: "mine", Format: "library", LibraryFlags: f}).Run(nil); err != nil {
+		t.Fatal(err)
+	}
+	store, err := catalog.OpenStore(catalog.StorePath(dir))
+	if err != nil {
+		t.Fatal(err)
+	}
+	found := false
+	for _, e := range store.Entries() {
+		found = found || e.ID == "mine"
+	}
+	if !found {
+		t.Error("the server store does not see the source")
+	}
+	_ = library.Defaults
+}

core/cli/run.go

@@ -16,6 +16,7 @@ import (
 	cliContext "github.com/mudler/LocalAI/core/cli/context"
 	"github.com/mudler/LocalAI/core/config"
 	"github.com/mudler/LocalAI/core/http"
+	"github.com/mudler/LocalAI/core/library"
 	"github.com/mudler/LocalAI/core/p2p"
 	"github.com/mudler/LocalAI/internal"
 	"github.com/mudler/LocalAI/pkg/diagnostics"
@@ -38,6 +39,9 @@ type RunCMD struct {
 	AddonsOwnershipMode       string `name:"addons-ownership-mode" env:"LOCALAI_ADDONS_OWNERSHIP_MODE" help:"Who may use add-ons: named-user (each account has its own access; needs authentication) or local-owner (every caller shares one owner). Default: local-owner when authentication is off, named-user when it is on" group:"addons"`
 	AutoUpgradeAddons         bool   `name:"auto-upgrade-addons" env:"LOCALAI_AUTO_UPGRADE_ADDONS" default:"false" help:"Upgrade installed add-ons on their own when a newer version appears in their library. Off by default; upgrades then stay manual" group:"addons"`
 	AddonsOfficialLibrary     bool   `name:"addons-official-library" env:"LOCALAI_ADDONS_OFFICIAL_LIBRARY" default:"true" help:"Register the official add-on library on the first start, when the add-on owner has no sources.json yet. A library the admin removes later stays removed. Turn it off with --addons-official-library=false" group:"addons"`
+	AddonsBackendLibrary      bool   `name:"addons-backend-library" env:"LOCALAI_ADDONS_BACKEND_LIBRARY" default:"true" help:"Register the backend library on the first start, when the add-on owner has no sources.json yet. A build from master reads it as the backend source; a tagged build reads the backend gallery until the release cutover. Turn it off to read the backend gallery only" group:"addons"`
+	OfficialLibraries         bool   `name:"official-libraries" env:"LOCALAI_OFFICIAL_LIBRARIES" default:"true" help:"Use the official (shipped default) library sources of add-ons, backends and models. Off: they stay in the list, shown as off, and are not read. Sources you added are not affected. Also a runtime setting (official_libraries)" group:"addons"`
+	AddonsBackendMaxBytes     int64  `name:"addons-backend-max-bytes" env:"LOCALAI_ADDONS_BACKEND_MAX_BYTES" default:"8589934592" help:"Largest compressed size, in bytes, of a backend image installed from a library. Add-ons keep their own limit of 512 MiB" group:"addons"`
 	Pprof                     bool   `name:"pprof" env:"LOCALAI_PPROF" default:"false" help:"Enable the private loopback profiling listener" group:"diagnostics"`
 	PprofAddress              string `name:"pprof-address" env:"LOCALAI_PPROF_ADDRESS" default:"127.0.0.1:6060" help:"Numeric loopback address and port for profiling" group:"diagnostics"`
 	PprofMutexProfileFraction int    `name:"pprof-mutex-profile-fraction" env:"LOCALAI_PPROF_MUTEX_PROFILE_FRACTION" default:"0" help:"Mutex sampling fraction (0 disables sampling); requires pprof" group:"diagnostics"`
@@ -350,6 +354,10 @@ func (r *RunCMD) Run(ctx *cliContext.Context) (result error) {
 		config.WithF16(r.F16),
 		config.WithStringGalleries(r.Galleries),
 		config.WithBackendGalleries(r.BackendGalleries),
+		// The galleries the flags named also become library sources, and the
+		// library sources decide which galleries are read. This must stay
+		// after the two options above.
+		library.Option(r.DataPath, r.AddonsOfficialLibrary, r.AddonsBackendLibrary, r.OfficialLibraries),
 		config.WithVRAMPersistentCache(r.VRAMPersistentCache),
 		config.WithCors(r.CORS),
 		config.WithCorsAllowOrigins(r.CORSAllowOrigins),
@@ -670,6 +678,8 @@ func (r *RunCMD) Run(ctx *cliContext.Context) (result error) {
 	}
 	if addonCfg.Enabled {
 		addonCfg.OfficialLibrary = r.AddonsOfficialLibrary
+		addonCfg.OfficialBackendLibrary = r.AddonsBackendLibrary
+		addonCfg.BackendMaxBytes = r.AddonsBackendMaxBytes
 		opts = append(opts, config.WithAddons(addonCfg))
 	}
 	if authEnabled {
@@ -807,6 +817,8 @@ func (r *RunCMD) Run(ctx *cliContext.Context) (result error) {
 		opts = append(opts, config.EnableBackendGalleriesAutoload)
 	}
 
+	opts = append(opts, config.WithOfficialLibraries(r.OfficialLibraries))
+
 	if r.AutoUpgradeBackends {
 		opts = append(opts, config.WithAutoUpgradeBackends(r.AutoUpgradeBackends))
 	}

core/cli/run_addons_test.go

@@ -51,6 +51,8 @@ var _ = Describe("Add-on owner flags", Serial, func() {
 		Expect(r.AddonsEnabled).To(BeTrue())
 		Expect(r.AddonsOwnershipMode).To(BeEmpty())
 		Expect(r.AddonsOfficialLibrary).To(BeTrue())
+		// The pilot backend library is a default source too.
+		Expect(r.AddonsBackendLibrary).To(BeTrue())
 		dir := GinkgoT().TempDir()
 		c, err := addonConfigFor(r.AddonsEnabled, r.AddonsOwnershipMode, dir, true)
 		Expect(err).NotTo(HaveOccurred())

core/config/application_config.go

@@ -36,6 +36,16 @@ type AddonConfig struct {
 	// when the owner has no sources.json yet. A sources.json that exists is
 	// never changed by it, so a library the admin removed stays removed.
 	OfficialLibrary bool
+	// OfficialBackendLibrary also registers the backend library on the first
+	// start, under the same rule: a sources.json that exists is never changed,
+	// so a library the admin removed stays removed. It is on by default, but
+	// whether it is enabled depends on the build (core/library.BackendSource):
+	// a build that reads the backend gallery lists the library and leaves it
+	// off.
+	OfficialBackendLibrary bool
+	// BackendMaxBytes bounds the compressed size of one backend image
+	// installed from a library; zero is 8 GiB. Add-ons keep their own limit.
+	BackendMaxBytes int64
 	Host            contract.HostCompatibility
 	AdminCheck      func(context.Context, contract.Actor) error `json:"-" yaml:"-"`
 	// BackupKeep is how many backups of one add-on the owner keeps; zero is
@@ -61,6 +71,10 @@ func WithAddons(c AddonConfig) AppOption {
 }
 
 type ApplicationConfig struct {
+	// OfficialLibraries is the switch for the shipped default library sources
+	// of every kind. On by default; off keeps them listed but unread.
+	OfficialLibraries bool
+
 	Addons AddonConfig `json:"-" yaml:"-"`
 
 	// AddonHostOps maps an add-on ID to the host operation prefixes it may
@@ -353,6 +367,7 @@ func NewApplicationConfig(o ...AppOption) *ApplicationConfig {
 		UploadLimitMB:             15,
 		Debug:                     true,
 		ModelArtifactMaterializer: modelartifacts.NewDefaultManager(),
+		OfficialLibraries:         true,
 		ModelPreloadRenderMode:    "dark",
 		// Capture backend process stdout/stderr into the per-model
 		// BackendLogStore by default so the UI "Backend Logs" page works out
@@ -670,6 +685,10 @@ var EnableBackendGalleriesAutoload = func(o *ApplicationConfig) {
 	o.AutoloadBackendGalleries = true
 }
 
+func WithOfficialLibraries(v bool) AppOption {
+	return func(o *ApplicationConfig) { o.OfficialLibraries = v }
+}
+
 func WithAutoUpgradeBackends(v bool) AppOption {
 	return func(o *ApplicationConfig) { o.AutoUpgradeBackends = v }
 }

core/config/application_config_test.go

@@ -136,6 +136,23 @@ var _ = Describe("ApplicationConfig RuntimeSettings Conversion", func() {
 			Expect(*rs.AutoUpgradeBackends).To(BeTrue())
 		})
 
+		It("should include official_libraries in both states", func() {
+			for _, on := range []bool{true, false} {
+				rs := (&ApplicationConfig{OfficialLibraries: on}).ToRuntimeSettings()
+				Expect(rs.OfficialLibraries).ToNot(BeNil())
+				Expect(*rs.OfficialLibraries).To(Equal(on))
+			}
+		})
+
+		It("should default official_libraries to on and take it from a persisted file", func() {
+			Expect(NewApplicationConfig().OfficialLibraries).To(BeTrue())
+			Expect(DefaultRuntimeBaseline().OfficialLibraries).To(BeTrue())
+			cfg := NewApplicationConfig()
+			off := false
+			cfg.ApplyRuntimeSettingsAtStartup(&RuntimeSettings{OfficialLibraries: &off})
+			Expect(cfg.OfficialLibraries).To(BeFalse())
+		})
+
 		It("should include auto_upgrade_addons, off by default", func() {
 			Expect((&ApplicationConfig{}).AutoUpgradeAddons).To(BeFalse())
 			rs := (&ApplicationConfig{}).ToRuntimeSettings()
@@ -523,6 +540,15 @@ var _ = Describe("ApplicationConfig RuntimeSettings Conversion", func() {
 			Expect(appConfig.AutoUpgradeBackends).To(BeTrue())
 		})
 
+		It("should apply official_libraries setting", func() {
+			appConfig := &ApplicationConfig{}
+			for _, v := range []bool{true, false} {
+				v := v
+				appConfig.ApplyRuntimeSettings(&RuntimeSettings{OfficialLibraries: &v})
+				Expect(appConfig.OfficialLibraries).To(Equal(v))
+			}
+		})
+
 		It("should apply auto_upgrade_addons setting", func() {
 			appConfig := &ApplicationConfig{}
 			v := true

core/config/gallery.go

@@ -48,8 +48,11 @@ type Gallery struct {
 	// always preferred, and a mirror is only consulted after the one before
 	// it fails. Any URI the gallery loader understands works here
 	// (https://, github:, file://, oci://).
-	Mirrors      []string             `json:"mirrors,omitempty" yaml:"mirrors,omitempty"`
-	Name         string               `json:"name" yaml:"name"`
+	Mirrors []string `json:"mirrors,omitempty" yaml:"mirrors,omitempty"`
+	Name    string   `json:"name" yaml:"name"`
+	// Library says the URL is a model library (the shared library entry
+	// shape), not a gallery index.
+	Library      bool                 `json:"library,omitempty" yaml:"library,omitempty"`
 	Verification *GalleryVerification `json:"verification,omitempty" yaml:"verification,omitempty"`
 	// ArtifactVerification overrides Verification only for the gallery OCI artifact.
 	// Backend images keep their separate Verification policy.

core/config/runtime_settings.go

@@ -20,6 +20,7 @@ type RuntimeSettings struct {
 	// Backend management
 	SingleBackend             *bool `json:"single_backend,omitempty"`              // Deprecated: use MaxActiveBackends = 1 instead
 	MaxActiveBackends         *int  `json:"max_active_backends,omitempty"`         // Maximum number of active backends (0 = unlimited, 1 = single backend mode)
+	OfficialLibraries         *bool `json:"official_libraries,omitempty"`          // Read the shipped default library sources of add-ons, backends and models
 	AutoUpgradeBackends       *bool `json:"auto_upgrade_backends,omitempty"`       // Automatically upgrade backends when new versions are detected
 	AutoUpgradeAddons         *bool `json:"auto_upgrade_addons,omitempty"`         // Automatically upgrade installed add-ons when their library lists a newer version
 	PreferDevelopmentBackends *bool `json:"prefer_development_backends,omitempty"` // Display/download preference; installed alias resolver changes require restart

core/config/runtime_settings_registry.go

@@ -163,6 +163,10 @@ var runtimeSettingsFields = []fieldSpec{
 			return cur.MaxActiveBackends != base.MaxActiveBackends || cur.SingleBackend != base.SingleBackend
 		},
 	},
+	field("official_libraries",
+		func(s *RuntimeSettings) **bool { return &s.OfficialLibraries },
+		func(o *ApplicationConfig) bool { return o.OfficialLibraries },
+		func(o *ApplicationConfig, v bool) { o.OfficialLibraries = v }),
 	field("auto_upgrade_backends",
 		func(s *RuntimeSettings) **bool { return &s.AutoUpgradeBackends },
 		func(o *ApplicationConfig) bool { return o.AutoUpgradeBackends },

core/gallery/backend_index_source.go

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+package gallery
+
+import (
+	"fmt"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"github.com/mudler/xlog"
+)
+
+const (
+	// OfficialBackendLibraryURL is the backend library, the source of the
+	// backends, kept in this repository. It is a default backend source. The
+	// gallery index is generated from it by scripts/backends/cmd/backendcatalog.
+	OfficialBackendLibraryURL = catalog.OfficialBackendLibraryURL
+)
+
+// backendLibraryFor returns the library to read for a gallery, or false when
+// the gallery is read as a gallery index. A gallery is a library when its entry
+// says so, which is how the backend library, shipped or added with
+// `local-ai library add`, is handed to the reader.
+func backendLibraryFor(g config.Gallery) (config.Gallery, bool) {
+	if !g.Library {
+		return config.Gallery{}, false
+	}
+	// The library has no mirrors of its own: the gallery's would describe
+	// another file. Its images are installed the way the gallery installs them,
+	// by the tag and the mirrors the entry names.
+	return config.Gallery{Name: g.Name, URL: g.URL}, true
+}
+
+// getBackendLibraryElements reads the backends of a gallery from the backend
+// library. A library that cannot be fetched or read is an error: falling back
+// to the gallery would hide the setting from the owner who chose it.
+func getBackendLibraryElements(g, lib config.Gallery, basePath string, requireIntegrity bool, isInstalled func(*GalleryBackend) bool) ([]*GalleryBackend, error) {
+	body, err := libraryBody(g, lib, basePath, requireIntegrity, "backend")
+	if err != nil {
+		return nil, err
+	}
+	res, err := catalog.ReadIndex(body, catalog.KindBackend)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read the backend library: %w", err)
+	}
+	if len(res.Skipped) > 0 {
+		xlog.Info("backend library entries of another kind were skipped", "gallery", g.Name, "count", len(res.Skipped))
+	}
+	backends, err := BackendsFromLibrary(res.Releases)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read the backend library: %w", err)
+	}
+	// Only a library that decodes is kept, so a bad file does not stay cached.
+	keepLibraryBody(lib, body)
+	for _, b := range backends {
+		b.SetGallery(g)
+		b.SetInstalled(isInstalled(b))
+	}
+	return backends, nil
+}

core/gallery/backend_library.go

@@ -0,0 +1,404 @@
+// SPDX-License-Identifier: MIT
+package gallery
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"reflect"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"gopkg.in/yaml.v3"
+)
+
+// The backend library, gallery/backends/index.yaml, is the source of truth for
+// the backends, the way the model library is for the models. The backend
+// gallery, backend/index.yaml, is a generated copy that stays only so releases
+// before the cutover keep working; scripts/backends/cmd/backendcatalog writes
+// it from the library and it is never edited by hand.
+//
+// A library entry is a catalog.Release of kind backend. One gallery backend
+// becomes one library entry per platform its image is built for, because the
+// library pins the digest of the image of each platform. A meta backend
+// becomes one entry with capabilities and no image. Converting library entries
+// back to a gallery entry gives the entry the gallery had, field for field,
+// for every field the gallery reader uses. The tests check that on every entry
+// of the real library.
+
+const (
+	// BackendChannelLatest and BackendChannelDevelopment are the channels of a
+	// backend entry. The tag of the image says which: latest-* is a release,
+	// master-* is the development build of the branch.
+	BackendChannelLatest      = "latest"
+	BackendChannelDevelopment = "development"
+
+	backendOCIPrefix = "oci://"
+)
+
+var backendTagPattern = regexp.MustCompile(`:(latest|master)-[A-Za-z0-9._-]+$`)
+
+// BackendPin is the digest of the image of one platform. An empty digest means
+// the image is not pinned in the library: a development image, which is pinned
+// at install, or a release image the registry could not be read for.
+type BackendPin struct {
+	OS     string
+	Arch   string
+	Digest string
+}
+
+// backendChannel is the channel of a gallery backend. A concrete backend takes
+// it from the tag of its image; a meta backend from its name, as the gallery
+// names its development variants.
+func backendChannel(b GalleryBackend) (string, error) {
+	if b.URI == "" {
+		if strings.HasSuffix(b.Name, "-"+defaultDevSuffix) {
+			return BackendChannelDevelopment, nil
+		}
+		return BackendChannelLatest, nil
+	}
+	m := backendTagPattern.FindStringSubmatch(b.URI)
+	switch {
+	case m == nil:
+		return "", fmt.Errorf("the image %q has no latest-* or master-* tag", b.URI)
+	case m[1] == "master":
+		return BackendChannelDevelopment, nil
+	}
+	return BackendChannelLatest, nil
+}
+
+// checkExpressible refuses a gallery backend that sets a field the library
+// body cannot carry, so nothing is lost without notice. The real gallery sets
+// none of them.
+func checkExpressible(b GalleryBackend) error {
+	switch {
+	case b.Name == "":
+		return errors.New("gallery entry has no name")
+	case b.Version != "":
+		return fmt.Errorf("backend %q sets version, which the library does not carry", b.Name)
+	case b.SHA256 != "":
+		return fmt.Errorf("backend %q sets sha256, which the library does not carry", b.Name)
+	case b.Metadata.URL != "", len(b.AdditionalFiles) > 0, b.Size != "", b.Metadata.Backend != "":
+		return fmt.Errorf("backend %q sets a model field (url, files, size or backend)", b.Name)
+	}
+	return nil
+}
+
+func ociRef(uri string) (string, error) {
+	if uri == "" || strings.Contains(uri, "://") {
+		return "", fmt.Errorf("the image %q must be a plain image reference: the library adds the oci:// scheme", uri)
+	}
+	return backendOCIPrefix + uri, nil
+}
+
+// BackendLibraryEntries converts a gallery backend to its library entries. A
+// concrete backend gets one entry for each pin; a meta backend takes no pins.
+// A development image is never pinned in the library, and neither is a pin
+// without a digest: such an entry is mutable and the install pins it.
+func BackendLibraryEntries(b GalleryBackend, pins []BackendPin) ([]catalog.Release, error) {
+	b = stripBackendRuntime(b)
+	if err := checkExpressible(b); err != nil {
+		return nil, err
+	}
+	channel, err := backendChannel(b)
+	if err != nil {
+		return nil, fmt.Errorf("backend %q: %w", b.Name, err)
+	}
+	base := catalog.Release{
+		Kind:          catalog.KindBackend,
+		ID:            b.Name,
+		Name:          b.Name,
+		Alias:         b.Alias,
+		Description:   b.Description,
+		Channel:       channel,
+		SchemaVersion: catalog.SchemaVersion,
+		License:       b.License,
+		URLs:          cloneList(b.URLs),
+		Tags:          cloneList(b.Tags),
+		Icon:          b.Icon,
+		Capabilities:  cloneMap(b.CapabilitiesMap),
+	}
+	if b.URI == "" {
+		if len(b.CapabilitiesMap) == 0 {
+			return nil, fmt.Errorf("backend %q has no image and no capabilities", b.Name)
+		}
+		if len(pins) > 0 || len(b.Mirrors) > 0 {
+			return nil, fmt.Errorf("meta backend %q has no image to pin or mirror", b.Name)
+		}
+		base.Version = "0.0.0-" + channel
+		return []catalog.Release{base}, nil
+	}
+	artifact, err := ociRef(b.URI)
+	if err != nil {
+		return nil, fmt.Errorf("backend %q: %w", b.Name, err)
+	}
+	base.Artifact = artifact
+	for _, m := range b.Mirrors {
+		ref, err := ociRef(m)
+		if err != nil {
+			return nil, fmt.Errorf("backend %q mirror: %w", b.Name, err)
+		}
+		base.Mirrors = append(base.Mirrors, ref)
+	}
+	if len(pins) == 0 {
+		return nil, fmt.Errorf("backend %q has no platform", b.Name)
+	}
+	sorted := append([]BackendPin(nil), pins...)
+	sort.SliceStable(sorted, func(i, j int) bool {
+		return sorted[i].OS+"/"+sorted[i].Arch < sorted[j].OS+"/"+sorted[j].Arch
+	})
+	var out []catalog.Release
+	for i, p := range sorted {
+		if p.OS == "" || p.Arch == "" {
+			return nil, fmt.Errorf("backend %q: a pin has no platform", b.Name)
+		}
+		if i > 0 && p.OS == sorted[i-1].OS && p.Arch == sorted[i-1].Arch {
+			return nil, fmt.Errorf("backend %q: two pins for %s/%s", b.Name, p.OS, p.Arch)
+		}
+		r := base
+		r.OS, r.Arch = p.OS, p.Arch
+		switch {
+		case p.Digest == "":
+			r.Mutable = true
+			r.Version = "0.0.0-" + channel
+		case channel == BackendChannelDevelopment:
+			return nil, fmt.Errorf("backend %q is a development image: it is pinned at install, not in the library", b.Name)
+		default:
+			hex := strings.TrimPrefix(p.Digest, "sha256:")
+			if len(hex) != 64 || hex == p.Digest {
+				return nil, fmt.Errorf("backend %q: %q is not a sha256 digest", b.Name, p.Digest)
+			}
+			r.Digest = p.Digest
+			r.Version = "0.0.0-" + channel + "." + hex[:12]
+		}
+		out = append(out, r)
+	}
+	return out, nil
+}
+
+// ToGalleryBackend converts one library entry of kind backend to the gallery
+// entry the installer and the listing read. The id is the name the gallery
+// knows the backend by.
+func ToGalleryBackend(r catalog.Release) (GalleryBackend, error) {
+	if r.EntryKind() != catalog.KindBackend {
+		return GalleryBackend{}, fmt.Errorf("entry %q is of kind %q, not backend", r.ID, r.EntryKind())
+	}
+	if err := catalog.ValidateEntry(r); err != nil {
+		return GalleryBackend{}, err
+	}
+	b := GalleryBackend{
+		Metadata: Metadata{
+			Name:        r.ID,
+			Description: r.Description,
+			License:     r.License,
+			URLs:        cloneList(r.URLs),
+			Icon:        r.Icon,
+			Tags:        cloneList(r.Tags),
+		},
+		Alias:           r.Alias,
+		CapabilitiesMap: cloneMap(r.Capabilities),
+	}
+	if r.Artifact != "" {
+		b.URI = strings.TrimPrefix(r.Artifact, backendOCIPrefix)
+	}
+	for _, m := range r.Mirrors {
+		b.Mirrors = append(b.Mirrors, strings.TrimPrefix(m, backendOCIPrefix))
+	}
+	return b, nil
+}
+
+// BackendsFromLibrary converts library entries of kind backend to gallery
+// backends, in the order the ids first appear. The entries of one id, one for
+// each platform, must describe the same gallery backend; if they differ the
+// library is refused, because the gallery cannot hold both. Entries of another
+// kind are skipped.
+func BackendsFromLibrary(releases []catalog.Release) ([]*GalleryBackend, error) {
+	var out []*GalleryBackend
+	index := map[string]int{}
+	for _, r := range releases {
+		if r.EntryKind() != catalog.KindBackend {
+			continue
+		}
+		b, err := ToGalleryBackend(r)
+		if err != nil {
+			return nil, err
+		}
+		i, seen := index[b.Name]
+		if !seen {
+			index[b.Name] = len(out)
+			out = append(out, &b)
+			continue
+		}
+		if d := firstBackendDifference(*out[i], b); d != "" {
+			return nil, fmt.Errorf("the library entries of backend %q disagree: %s", b.Name, d)
+		}
+	}
+	return out, nil
+}
+
+// LibraryPins collects the pins of the backend entries of a library by id.
+func LibraryPins(releases []catalog.Release) map[string][]BackendPin {
+	out := map[string][]BackendPin{}
+	for _, r := range releases {
+		if r.EntryKind() == catalog.KindBackend && r.Artifact != "" {
+			out[r.ID] = append(out[r.ID], BackendPin{OS: r.OS, Arch: r.Arch, Digest: r.Digest})
+		}
+	}
+	return out
+}
+
+func stripBackendRuntime(b GalleryBackend) GalleryBackend {
+	b.Gallery = config.Gallery{}
+	b.Installed = false
+	b.Library, b.MaxBytes, b.Stage = "", 0, nil
+	return b
+}
+
+// normalizeBackend makes an empty list or map the same as an absent one,
+// which is how the gallery reader sees them, and drops the runtime fields.
+func normalizeBackend(b GalleryBackend) GalleryBackend {
+	b = stripBackendRuntime(b)
+	if len(b.URLs) == 0 {
+		b.URLs = nil
+	}
+	if len(b.Tags) == 0 {
+		b.Tags = nil
+	}
+	if len(b.Mirrors) == 0 {
+		b.Mirrors = nil
+	}
+	if len(b.CapabilitiesMap) == 0 {
+		b.CapabilitiesMap = nil
+	}
+	return b
+}
+
+// SameBackend reports whether two gallery backends are equal on every field
+// the gallery reader uses.
+func SameBackend(a, b GalleryBackend) bool {
+	return reflect.DeepEqual(normalizeBackend(a), normalizeBackend(b))
+}
+
+// firstBackendDifference names the first field of two gallery backends that
+// differ, or "" when they are the same.
+func firstBackendDifference(a, b GalleryBackend) string {
+	a, b = normalizeBackend(a), normalizeBackend(b)
+	av, bv := reflect.ValueOf(a), reflect.ValueOf(b)
+	for i := 0; i < av.NumField(); i++ {
+		f := av.Type().Field(i)
+		if f.Name == "Metadata" {
+			mv, nv := reflect.ValueOf(a.Metadata), reflect.ValueOf(b.Metadata)
+			for j := 0; j < mv.NumField(); j++ {
+				if !reflect.DeepEqual(mv.Field(j).Interface(), nv.Field(j).Interface()) {
+					return fmt.Sprintf("%s: %#v became %#v", mv.Type().Field(j).Name, mv.Field(j).Interface(), nv.Field(j).Interface())
+				}
+			}
+			continue
+		}
+		if f.Type.Kind() == reflect.Func {
+			continue
+		}
+		if !reflect.DeepEqual(av.Field(i).Interface(), bv.Field(i).Interface()) {
+			return fmt.Sprintf("%s: %#v became %#v", f.Name, av.Field(i).Interface(), bv.Field(i).Interface())
+		}
+	}
+	return ""
+}
+
+// VerifyBackendRoundTrip checks that a gallery backend survives the library:
+// it is converted to library entries, written as an index, read the way a host
+// reads a library, validated as a host validates it, and converted back. The
+// result must equal the original on every field the gallery reader uses. It
+// returns a description of the first difference.
+func VerifyBackendRoundTrip(b GalleryBackend, pins []BackendPin) error {
+	entries, err := BackendLibraryEntries(b, pins)
+	if err != nil {
+		return err
+	}
+	raw, err := catalog.EncodeIndex(entries)
+	if err != nil {
+		return fmt.Errorf("writing the library entries: %w", err)
+	}
+	res, err := catalog.ReadIndex(raw, catalog.ReadableKinds...)
+	if err != nil {
+		return fmt.Errorf("reading the library entries: %w", err)
+	}
+	if len(res.Releases) != len(entries) {
+		return fmt.Errorf("%d library entries came back as %d", len(entries), len(res.Releases))
+	}
+	got, err := BackendsFromLibrary(res.Releases)
+	if err != nil {
+		return err
+	}
+	if len(got) != 1 {
+		return fmt.Errorf("the library entries came back as %d gallery backends", len(got))
+	}
+	if d := firstBackendDifference(b, *got[0]); d != "" {
+		return fmt.Errorf("gallery entry changed on the way through the library: %s", d)
+	}
+	return nil
+}
+
+// backendFileEntry is a gallery backend as it is written to the gallery file:
+// the fields of GalleryBackend in the order the file has always used.
+type backendFileEntry struct {
+	Name         string            `yaml:"name"`
+	Alias        string            `yaml:"alias,omitempty"`
+	License      string            `yaml:"license,omitempty"`
+	Icon         string            `yaml:"icon,omitempty"`
+	Description  string            `yaml:"description,omitempty"`
+	URLs         []string          `yaml:"urls,omitempty"`
+	Tags         []string          `yaml:"tags,omitempty"`
+	Capabilities map[string]string `yaml:"capabilities,omitempty"`
+	URI          string            `yaml:"uri,omitempty"`
+	Mirrors      []string          `yaml:"mirrors,omitempty"`
+}
+
+// EncodeBackendGalleryIndex writes gallery backends as the gallery file the
+// host reads (backend/index.yaml). The runtime fields are not written. It
+// refuses a backend that sets a field the file does not write, so the file
+// reads back as the entries it was written from.
+func EncodeBackendGalleryIndex(backends []GalleryBackend) ([]byte, error) {
+	out := make([]backendFileEntry, len(backends))
+	for i, b := range backends {
+		b = normalizeBackend(b)
+		if err := checkExpressible(b); err != nil {
+			return nil, err
+		}
+		out[i] = backendFileEntry{
+			Name: b.Name, Alias: b.Alias, License: b.License, Icon: b.Icon, Description: b.Description,
+			URLs: b.URLs, Tags: b.Tags, Capabilities: b.CapabilitiesMap, URI: b.URI, Mirrors: b.Mirrors,
+		}
+	}
+	var buf bytes.Buffer
+	enc := yaml.NewEncoder(&buf)
+	enc.SetIndent(2)
+	if err := enc.Encode(out); err != nil {
+		return nil, err
+	}
+	if err := enc.Close(); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+func cloneList(s []string) []string {
+	if s == nil {
+		return nil
+	}
+	return append([]string{}, s...)
+}
+
+func cloneMap(m map[string]string) map[string]string {
+	if m == nil {
+		return nil
+	}
+	out := make(map[string]string, len(m))
+	for k, v := range m {
+		out[k] = v
+	}
+	return out
+}

core/gallery/backend_library_generated_test.go

@@ -0,0 +1,165 @@
+package gallery
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/pkg/system"
+	"gopkg.in/yaml.v3"
+)
+
+// backend/index.yaml is generated and never edited. The CI check regenerates it
+// and fails on a diff; this test does the same in the Go suite, so a hand edit
+// is found by go test too.
+func TestCheckedInBackendGalleryIsTheGeneratedCopy(t *testing.T) {
+	list, err := BackendsFromLibrary(loadRealBackendLibrary(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	flat := make([]GalleryBackend, len(list))
+	for i, b := range list {
+		flat[i] = *b
+	}
+	want, err := EncodeBackendGalleryIndex(flat)
+	if err != nil {
+		t.Fatal(err)
+	}
+	have, err := os.ReadFile("../../backend/index.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	body := string(have)
+	for strings.HasPrefix(body, "#") {
+		_, rest, _ := strings.Cut(body, "\n")
+		body = rest
+	}
+	if body != string(want) {
+		t.Error("backend/index.yaml is not the copy generated from gallery/backends/index.yaml. It is generated; do not edit it by hand. Regenerate: go run ./scripts/backends/cmd/backendcatalog --library gallery/backends/index.yaml --out backend/index.yaml")
+	}
+	var loaded []GalleryBackend
+	if err := yaml.Unmarshal(have, &loaded); err != nil {
+		t.Fatalf("the gallery reader on the generated gallery: %v", err)
+	}
+	if len(loaded) != len(flat) {
+		t.Fatalf("the generated gallery loads %d entries, the library has %d backends", len(loaded), len(flat))
+	}
+	for i := range loaded {
+		if !SameBackend(loaded[i], flat[i]) {
+			t.Errorf("%s loads differently from the library", flat[i].Name)
+		}
+	}
+	t.Logf("generated gallery: %d entries read back equal to the library", len(loaded))
+}
+
+// A gallery marked as a library is read as a library; any other gallery is
+// read as an index. The server hands the shipped backend library to the reader
+// this way, so the backends it lists are the backends of the library.
+func TestLibraryGalleryReadsTheBackendLibrary(t *testing.T) {
+	library, err := os.ReadFile(realBackendLibrary)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var libraryHits, galleryHits int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/backends/index.yaml":
+			libraryHits++
+			_, _ = w.Write(library)
+		case "/gallery/index.yaml":
+			galleryHits++
+			_, _ = w.Write([]byte("- name: from-gallery\n  uri: quay.io/acme/backends:latest-cpu-x\n"))
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	t.Cleanup(srv.Close)
+
+	state, err := system.GetSystemState(system.WithBackendPath(t.TempDir()))
+	if err != nil {
+		t.Fatal(err)
+	}
+	names := func(g config.Gallery) GalleryElements[*GalleryBackend] {
+		t.Helper()
+		backends, err := AvailableBackendsUnfiltered([]config.Gallery{g}, state)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return backends
+	}
+	official := config.Gallery{Name: "localai", URL: srv.URL + "/gallery/index.yaml"}
+
+	// Default: the gallery index, and the library file is never requested.
+	if got := names(official); len(got) != 1 || got[0].Name != "from-gallery" {
+		t.Errorf("default source gave %d backends", len(got))
+	}
+	if libraryHits != 0 {
+		t.Errorf("the library was read %d times with the default source", libraryHits)
+	}
+
+	// Library: a gallery marked as a library is read as one.
+	official.Library = true
+	official.URL = srv.URL + "/backends/index.yaml"
+	backends := names(official)
+	if len(backends) != goldenGalleryNames {
+		t.Fatalf("the library gave %d backends, want %d", len(backends), goldenGalleryNames)
+	}
+	llama := backends.FindByName("llama-cpp")
+	if llama == nil || !llama.IsMeta() || llama.CapabilitiesMap["nvidia"] != "cuda12-llama-cpp" || llama.Alias != "llama-cpp" {
+		t.Fatalf("the meta backend lost its body: %+v", llama)
+	}
+	cpu := backends.FindByName("cpu-llama-cpp")
+	if cpu == nil || cpu.IsMeta() || !strings.HasPrefix(cpu.URI, "quay.io/go-skynet/local-ai-backends:latest-") || len(cpu.Mirrors) != 1 || cpu.License == "" || cpu.Icon == "" {
+		t.Fatalf("the concrete backend lost its body: %+v", cpu)
+	}
+	if g := cpu.GetGallery(); g.Name != "localai" || g.URL != official.URL || !g.Library {
+		t.Errorf("the entry should carry the configured gallery, got %+v", g)
+	}
+	// The backends the server lists are the backends of the generated gallery.
+	var generated []GalleryBackend
+	raw, err := os.ReadFile("../../backend/index.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := yaml.Unmarshal(raw, &generated); err != nil {
+		t.Fatal(err)
+	}
+	if len(generated) != len(backends) {
+		t.Fatalf("the generated gallery has %d backends, the library %d", len(generated), len(backends))
+	}
+	for i, b := range generated {
+		if !SameBackend(b, *backends[i]) {
+			t.Errorf("%s differs between the library and the generated gallery", b.Name)
+		}
+	}
+	// The meta backends resolve to a concrete one through the library.
+	if best := llama.FindBestBackendFromMeta(state, backends); best != nil && best.IsMeta() {
+		t.Errorf("a meta backend resolved to another meta backend: %s", best.Name)
+	}
+
+	// A gallery the owner added keeps its own index.
+	other := config.Gallery{Name: "mine", URL: srv.URL + "/gallery/index.yaml"}
+	if got := names(other); len(got) != 1 || got[0].Name != "from-gallery" {
+		t.Errorf("another gallery gave %d backends", len(got))
+	}
+
+	// An unreachable library is an error, not a silent fall back.
+	official.URL = srv.URL + "/missing.yaml"
+	if _, err := AvailableBackendsUnfiltered([]config.Gallery{official}, state); err == nil {
+		t.Error("a missing library fell back to the gallery")
+	}
+
+	// A library with an entry the host refuses is an error too, and is not kept.
+	bad := config.Gallery{Name: "bad", URL: srv.URL + "/bad.yaml", Library: true}
+	badSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte("- kind: backend\n  id: bad\n  name: bad\n  version: 0.0.0-latest\n  artifact: https://example.org/bad.tar\n  digest: " + strings.Repeat("x", 10) + "\n  os: linux\n  arch: amd64\n"))
+	}))
+	t.Cleanup(badSrv.Close)
+	bad.URL = badSrv.URL + "/bad.yaml"
+	if _, err := AvailableBackendsUnfiltered([]config.Gallery{bad}, state); err == nil {
+		t.Error("an invalid library entry was accepted")
+	}
+}

core/gallery/backend_library_test.go

@@ -0,0 +1,548 @@
+package gallery
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"gopkg.in/yaml.v3"
+)
+
+const (
+	realBackendLibrary  = "../../gallery/backends/index.yaml"
+	backendLibraryGolds = "testdata/backend_library"
+	// The gallery before the library became the source, kept as the golden
+	// input: 1093 entries, five of them twins of another entry's name.
+	goldenGalleryEntries = 1093
+	goldenGalleryNames   = 1088
+)
+
+func loadRealBackendLibrary(t *testing.T) []catalog.Release {
+	t.Helper()
+	src, err := os.ReadFile(realBackendLibrary)
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err := catalog.ReadIndex(src, catalog.ReadableKinds...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Releases) == 0 {
+		t.Fatal("the real backend library has no entries")
+	}
+	return res.Releases
+}
+
+func loadGoldenGallery(t *testing.T) []GalleryBackend {
+	t.Helper()
+	src, err := os.ReadFile(filepath.Join(backendLibraryGolds, "gallery-before.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var list []GalleryBackend
+	if err := yaml.Unmarshal(src, &list); err != nil {
+		t.Fatal(err)
+	}
+	return list
+}
+
+func loadGoldenPins(t *testing.T) map[string][]BackendPin {
+	t.Helper()
+	f, err := os.Open(filepath.Join(backendLibraryGolds, "pins.tsv"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = f.Close() }()
+	pins := map[string][]BackendPin{}
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		line := sc.Text()
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		p := strings.Split(line, "\t")
+		if len(p) != 4 {
+			t.Fatalf("malformed pin line %q", line)
+		}
+		pins[p[0]] = append(pins[p[0]], BackendPin{OS: p[1], Arch: p[2], Digest: p[3]})
+	}
+	return pins
+}
+
+func loadGoldenDigests(t *testing.T) map[string]string {
+	t.Helper()
+	f, err := os.Open(filepath.Join(backendLibraryGolds, "digests.tsv"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = f.Close() }()
+	out := map[string]string{}
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		line := sc.Text()
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		p := strings.Split(line, "\t")
+		if len(p) != 2 {
+			t.Fatalf("malformed golden line %q", line)
+		}
+		out[p[0]] = p[1]
+	}
+	return out
+}
+
+func backendDigest(t *testing.T, b GalleryBackend) string {
+	t.Helper()
+	raw, err := EncodeBackendGalleryIndex([]GalleryBackend{b})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sum := sha256.Sum256(raw)
+	return hex.EncodeToString(sum[:])
+}
+
+// Every entry of the real backend gallery, as it was before the library became
+// the source, must survive the library: gallery -> library -> gallery gives the
+// same entry on every field the gallery reader uses. The count is asserted and
+// logged so a run shows how many real entries it covered.
+func TestBackendLibraryRoundTripsEveryRealGalleryEntry(t *testing.T) {
+	entries := loadGoldenGallery(t)
+	if len(entries) != goldenGalleryEntries {
+		t.Fatalf("the golden gallery has %d entries, want %d", len(entries), goldenGalleryEntries)
+	}
+	pins := loadGoldenPins(t)
+	golden := loadGoldenDigests(t)
+	covered, meta, concrete, dev, platformsRows := 0, 0, 0, 0, 0
+	first := map[string]GalleryBackend{}
+	var failures []string
+	for _, b := range entries {
+		if twin, ok := first[b.Name]; ok {
+			// A name that appears twice must be the same entry, so folding it
+			// loses nothing.
+			if !SameBackend(twin, b) {
+				failures = append(failures, b.Name+": the twin entry differs from the first one")
+				continue
+			}
+		} else {
+			first[b.Name] = b
+		}
+		if err := VerifyBackendRoundTrip(b, pins[b.Name]); err != nil {
+			failures = append(failures, b.Name+": "+err.Error())
+			continue
+		}
+		// The generated gallery entry is the one the golden file recorded.
+		if want, ok := golden[b.Name]; !ok || backendDigest(t, b) != want {
+			failures = append(failures, b.Name+": the golden digest does not match the gallery entry")
+			continue
+		}
+		covered++
+		switch {
+		case b.URI == "":
+			meta++
+		case strings.Contains(b.URI, ":master-"):
+			concrete++
+			dev++
+		default:
+			concrete++
+		}
+		platformsRows += len(pins[b.Name])
+	}
+	for _, f := range failures {
+		t.Error(f)
+	}
+	t.Logf("backend library round trip: %d of %d gallery entries covered (%d names; %d concrete of which %d development, %d meta); the golden pins hold %d platform entries",
+		covered, len(entries), len(first), concrete, dev, meta, platformsRows)
+	if covered != goldenGalleryEntries {
+		t.Errorf("covered %d gallery entries, want %d", covered, goldenGalleryEntries)
+	}
+	if len(first) != goldenGalleryNames || len(golden) != goldenGalleryNames {
+		t.Errorf("%d names and %d golden digests, want %d", len(first), len(golden), goldenGalleryNames)
+	}
+}
+
+// The library file in the repository is read by the host, so it must decode and
+// every entry must pass the checks a host applies. Every backend must convert
+// to a gallery backend and come back as itself, and a meta backend must name
+// backends the library has.
+func TestRealBackendLibraryHasTheLibraryShape(t *testing.T) {
+	rows := loadRealBackendLibrary(t)
+	ids := map[string]bool{}
+	concrete := map[string]bool{}
+	keys := map[string]bool{}
+	pinned, development, unpinned, meta := 0, 0, 0, 0
+	for _, r := range rows {
+		if r.EntryKind() != catalog.KindBackend {
+			t.Errorf("%s is of kind %q", r.ID, r.EntryKind())
+			continue
+		}
+		if err := catalog.ValidateEntry(r); err != nil {
+			t.Error(err)
+		}
+		key := r.ID + "/" + r.OS + "/" + r.Arch
+		if keys[key] {
+			t.Errorf("%s is listed twice", key)
+		}
+		keys[key] = true
+		ids[r.ID] = true
+		if r.SchemaVersion != catalog.SchemaVersion {
+			t.Errorf("%s has schemaVersion %d", r.ID, r.SchemaVersion)
+		}
+		switch {
+		case r.IsMeta():
+			meta++
+		case r.Digest != "":
+			pinned++
+			concrete[r.ID] = true
+			if r.Channel != BackendChannelLatest || !strings.Contains(r.Artifact, ":latest-") {
+				t.Errorf("%s: a pinned entry is a release image: %s", r.ID, r.Artifact)
+			}
+		case r.Channel == BackendChannelDevelopment:
+			development++
+			concrete[r.ID] = true
+			if !r.Mutable || !strings.Contains(r.Artifact, ":master-") {
+				t.Errorf("%s: a development entry keeps its master-* tag and is mutable: %s", r.ID, r.Artifact)
+			}
+		default:
+			unpinned++
+			concrete[r.ID] = true
+			t.Logf("not pinned: %s (%s/%s)", r.ID, r.OS, r.Arch)
+		}
+	}
+	for _, r := range rows {
+		if !r.IsMeta() {
+			continue
+		}
+		for capability, target := range r.Capabilities {
+			if !concrete[target] {
+				t.Errorf("meta backend %s: capability %s names %s, which the library does not have as a concrete backend", r.ID, capability, target)
+			}
+		}
+	}
+	list, err := BackendsFromLibrary(rows)
+	if err != nil {
+		t.Fatal(err)
+	}
+	pins := LibraryPins(rows)
+	for _, b := range list {
+		if err := VerifyBackendRoundTrip(*b, pins[b.Name]); err != nil {
+			t.Errorf("%s: %v", b.Name, err)
+		}
+	}
+	t.Logf("backend library: %d entries for %d backends (%d meta, %d pinned by digest, %d development, %d release entries not pinned)", len(rows), len(list), meta, pinned, development, unpinned)
+}
+
+// An entry whose gallery digest is in the golden file must still produce the
+// recorded gallery entry. An entry changed or added since the golden file was
+// rendered has no matching digest and is covered by the round trip only.
+func TestBackendLibraryMatchesGoldenDigests(t *testing.T) {
+	golden := loadGoldenDigests(t)
+	list, err := BackendsFromLibrary(loadRealBackendLibrary(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	checked, unchanged := 0, 0
+	for _, b := range list {
+		want, ok := golden[b.Name]
+		if !ok {
+			continue
+		}
+		checked++
+		if backendDigest(t, *b) == want {
+			unchanged++
+		}
+	}
+	t.Logf("golden digests: %d of %d golden backends are in the library, %d unchanged", checked, len(golden), unchanged)
+	if checked < len(golden)*9/10 {
+		t.Errorf("only %d of %d golden backends are still in the library; render the golden files again", checked, len(golden))
+	}
+	if unchanged < checked*9/10 {
+		t.Errorf("only %d of %d golden backends kept their gallery entry; render the golden files again if the change is intended", unchanged, checked)
+	}
+}
+
+// The golden samples show what a library file holds and what the gallery copy
+// holds for the same backend.
+func TestBackendLibraryMatchesGoldenSamples(t *testing.T) {
+	libraries, err := filepath.Glob(filepath.Join(backendLibraryGolds, "samples", "*.library.yaml"))
+	if err != nil || len(libraries) == 0 {
+		t.Fatalf("no golden samples: %v", err)
+	}
+	for _, lpath := range libraries {
+		name := strings.TrimSuffix(filepath.Base(lpath), ".library.yaml")
+		t.Run(name, func(t *testing.T) {
+			src, err := os.ReadFile(lpath)
+			if err != nil {
+				t.Fatal(err)
+			}
+			galWant, err := os.ReadFile(strings.TrimSuffix(lpath, ".library.yaml") + ".gallery.yaml")
+			if err != nil {
+				t.Fatal(err)
+			}
+			res, err := catalog.ReadIndex(src, catalog.ReadableKinds...)
+			if err != nil || len(res.Releases) == 0 {
+				t.Fatalf("reading the sample: %v", err)
+			}
+			again, err := catalog.EncodeIndex(res.Releases)
+			if err != nil || string(again) != string(src) {
+				t.Errorf("the library sample does not encode back to itself: %v", err)
+			}
+			list, err := BackendsFromLibrary(res.Releases)
+			if err != nil || len(list) != 1 {
+				t.Fatalf("converting the sample: %v (%d backends)", err, len(list))
+			}
+			got, err := EncodeBackendGalleryIndex([]GalleryBackend{*list[0]})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if string(got) != string(galWant) {
+				t.Errorf("the gallery entry differs from the golden file:\n%s", got)
+			}
+			var loaded []GalleryBackend
+			if err := yaml.Unmarshal(galWant, &loaded); err != nil || len(loaded) != 1 {
+				t.Fatalf("the gallery reader on the golden entry: %v", err)
+			}
+			if !SameBackend(loaded[0], *list[0]) {
+				t.Errorf("the golden gallery entry does not load as the library entry")
+			}
+			if err := VerifyBackendRoundTrip(loaded[0], LibraryPins(res.Releases)[loaded[0].Name]); err != nil {
+				t.Error(err)
+			}
+		})
+	}
+}
+
+func demoBackend() GalleryBackend {
+	return GalleryBackend{
+		Metadata: Metadata{
+			Name: "cpu-demo", Description: "A demo.\n", License: "mit", Icon: "https://example.com/i.png",
+			URLs: []string{"https://example.com/demo"}, Tags: []string{"CPU", "LLM"},
+		},
+		Alias:           "demo",
+		URI:             "quay.io/acme/backends:latest-cpu-demo",
+		Mirrors:         []string{"docker.io/acme/backends:latest-cpu-demo", "ghcr.io/acme/backends:latest-cpu-demo"},
+		CapabilitiesMap: map[string]string{"default": "cpu-demo", "nvidia": "cuda12-demo"},
+	}
+}
+
+const (
+	pinAMD = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+	pinARM = "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+)
+
+func TestBackendLibraryEntriesExpressEveryField(t *testing.T) {
+	rows, err := BackendLibraryEntries(demoBackend(), []BackendPin{{"linux", "arm64", pinARM}, {"linux", "amd64", pinAMD}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 2 || rows[0].Arch != "amd64" || rows[1].Arch != "arm64" {
+		t.Fatalf("one entry for each platform, in a fixed order: %+v", rows)
+	}
+	r := rows[0]
+	if r.Kind != catalog.KindBackend || r.ID != "cpu-demo" || r.Alias != "demo" || r.License != "mit" || r.Icon != "https://example.com/i.png" ||
+		r.Description != "A demo.\n" || r.Artifact != "oci://quay.io/acme/backends:latest-cpu-demo" || r.Digest != pinAMD || r.Mutable ||
+		r.Channel != "latest" || r.SchemaVersion != 1 || r.Version != "0.0.0-latest.aaaaaaaaaaaa" || r.OS != "linux" {
+		t.Errorf("unexpected entry: %+v", r)
+	}
+	if strings.Join(r.Mirrors, " ") != "oci://docker.io/acme/backends:latest-cpu-demo oci://ghcr.io/acme/backends:latest-cpu-demo" {
+		t.Errorf("mirrors keep their order and get the oci scheme: %v", r.Mirrors)
+	}
+	if r.Capabilities["nvidia"] != "cuda12-demo" || len(r.URLs) != 1 || len(r.Tags) != 2 {
+		t.Errorf("capabilities, urls and tags: %+v", r)
+	}
+	// The entry holds copies, not the gallery's own list and map.
+	r.Capabilities["nvidia"] = "changed"
+	r.Tags[0] = "changed"
+	if b := demoBackend(); b.CapabilitiesMap["nvidia"] != "cuda12-demo" || b.Tags[0] != "CPU" {
+		t.Error("the library entry shares memory with the gallery entry")
+	}
+	for _, p := range []BackendPin{{"linux", "amd64", pinAMD}, {"linux", "arm64", pinARM}} {
+		if err := VerifyBackendRoundTrip(demoBackend(), []BackendPin{p}); err != nil {
+			t.Error(err)
+		}
+	}
+}
+
+func TestBackendLibraryKeepsDevelopmentTagsMutable(t *testing.T) {
+	b := demoBackend()
+	b.Name, b.URI = "cpu-demo-development", "quay.io/acme/backends:master-cpu-demo"
+	b.Mirrors = []string{"docker.io/acme/backends:master-cpu-demo"}
+	rows, err := BackendLibraryEntries(b, []BackendPin{{OS: "linux", Arch: "amd64"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := rows[0]
+	if !r.Mutable || r.Digest != "" || r.Channel != "development" || r.Version != "0.0.0-development" || r.Artifact != "oci://quay.io/acme/backends:master-cpu-demo" {
+		t.Errorf("a development entry keeps its tag and has no digest: %+v", r)
+	}
+	// A development image is pinned at install: a digest in the library is refused.
+	if _, err := BackendLibraryEntries(b, []BackendPin{{"linux", "amd64", pinAMD}}); err == nil {
+		t.Error("a development entry must not be pinned at render")
+	}
+	if err := VerifyBackendRoundTrip(b, []BackendPin{{OS: "linux", Arch: "amd64"}}); err != nil {
+		t.Error(err)
+	}
+}
+
+func TestBackendLibraryMetaBackend(t *testing.T) {
+	meta := GalleryBackend{
+		Metadata:        Metadata{Name: "demo", Description: "Meta", Tags: []string{"LLM"}},
+		Alias:           "demo",
+		CapabilitiesMap: map[string]string{"default": "cpu-demo", "nvidia": "cuda12-demo"},
+	}
+	rows, err := BackendLibraryEntries(meta, nil)
+	if err != nil || len(rows) != 1 {
+		t.Fatalf("%v %d", err, len(rows))
+	}
+	r := rows[0]
+	if !r.IsMeta() || r.Artifact != "" || r.Digest != "" || r.OS != "" || r.Arch != "" || r.Channel != "latest" || r.Version != "0.0.0-latest" {
+		t.Errorf("a meta entry has capabilities and no image: %+v", r)
+	}
+	if err := VerifyBackendRoundTrip(meta, nil); err != nil {
+		t.Error(err)
+	}
+	dev := meta
+	dev.Name = "demo-development"
+	if rows, _ := BackendLibraryEntries(dev, nil); rows[0].Channel != "development" {
+		t.Errorf("a development meta backend is on the development channel: %+v", rows[0])
+	}
+	if _, err := BackendLibraryEntries(meta, []BackendPin{{"linux", "amd64", pinAMD}}); err == nil {
+		t.Error("a meta backend has no image to pin")
+	}
+	meta.Mirrors = []string{"docker.io/acme/x:latest-y"}
+	if _, err := BackendLibraryEntries(meta, nil); err == nil {
+		t.Error("a meta backend has no image to mirror")
+	}
+	if _, err := BackendLibraryEntries(GalleryBackend{Metadata: Metadata{Name: "empty"}}, nil); err == nil {
+		t.Error("an entry with no image and no capabilities names nothing")
+	}
+}
+
+func TestBackendLibraryRefusesWhatItCannotCarry(t *testing.T) {
+	pins := []BackendPin{{"linux", "amd64", pinAMD}}
+	for name, mod := range map[string]func(*GalleryBackend){
+		"version":       func(b *GalleryBackend) { b.Version = "1.0" },
+		"sha256":        func(b *GalleryBackend) { b.SHA256 = "abc" },
+		"url":           func(b *GalleryBackend) { b.Metadata.URL = "https://x" },
+		"files":         func(b *GalleryBackend) { b.AdditionalFiles = []File{{Filename: "f"}} },
+		"size":          func(b *GalleryBackend) { b.Size = "1GB" },
+		"backend":       func(b *GalleryBackend) { b.Metadata.Backend = "x" },
+		"no name":       func(b *GalleryBackend) { b.Name = "" },
+		"uri scheme":    func(b *GalleryBackend) { b.URI = "oci://quay.io/acme/backends:latest-cpu-demo" },
+		"https uri":     func(b *GalleryBackend) { b.URI = "https://example.com/backend.tar" },
+		"mirror scheme": func(b *GalleryBackend) { b.Mirrors = []string{"https://example.com/b.tar"} },
+		"odd tag":       func(b *GalleryBackend) { b.URI = "quay.io/acme/backends:v1.2.3" },
+	} {
+		b := demoBackend()
+		mod(&b)
+		if _, err := BackendLibraryEntries(b, pins); err == nil {
+			t.Errorf("%s: a field the library cannot carry must be refused, not dropped", name)
+		}
+	}
+	if _, err := BackendLibraryEntries(demoBackend(), nil); err == nil {
+		t.Error("a concrete backend needs a platform")
+	}
+	if _, err := BackendLibraryEntries(demoBackend(), []BackendPin{{"linux", "amd64", pinAMD}, {"linux", "amd64", pinARM}}); err == nil {
+		t.Error("two pins for one platform")
+	}
+	if _, err := BackendLibraryEntries(demoBackend(), []BackendPin{{"linux", "amd64", "latest"}}); err == nil {
+		t.Error("a pin must be a sha256 digest")
+	}
+	if _, err := BackendLibraryEntries(demoBackend(), []BackendPin{{"", "amd64", pinAMD}}); err == nil {
+		t.Error("a pin needs a platform")
+	}
+}
+
+func TestBackendRoundTripTreatsEmptyAndAbsentAlike(t *testing.T) {
+	b := demoBackend()
+	b.URLs, b.Tags, b.Mirrors, b.Icon, b.License, b.Alias = []string{}, []string{}, []string{}, "", "", ""
+	if err := VerifyBackendRoundTrip(b, []BackendPin{{"linux", "amd64", pinAMD}}); err != nil {
+		t.Errorf("the gallery reader sees no difference between an empty list and an absent one: %v", err)
+	}
+}
+
+func TestBackendsFromLibraryRefusesEntriesThatDisagree(t *testing.T) {
+	rows, err := BackendLibraryEntries(demoBackend(), []BackendPin{{"linux", "amd64", pinAMD}, {"linux", "arm64", pinARM}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if list, err := BackendsFromLibrary(rows); err != nil || len(list) != 1 {
+		t.Fatalf("two platforms of one backend are one gallery backend: %v %d", err, len(list))
+	}
+	rows[1].License = "gpl"
+	if _, err := BackendsFromLibrary(rows); err == nil || !strings.Contains(err.Error(), "disagree") {
+		t.Errorf("the entries of one backend must agree, got %v", err)
+	}
+	rows[1] = rows[0]
+	rows[1].Arch = "arm64"
+	rows[1].Artifact = "oci://quay.io/acme/backends:latest-other"
+	if _, err := BackendsFromLibrary(rows); err == nil {
+		t.Error("two images for one name cannot be one gallery backend")
+	}
+}
+
+func TestBackendsFromLibrarySkipsOtherKindsAndKeepsOrder(t *testing.T) {
+	a, b := demoBackend(), demoBackend()
+	a.Name, b.Name = "z-first", "a-second"
+	ra, _ := BackendLibraryEntries(a, []BackendPin{{"linux", "amd64", pinAMD}})
+	rb, _ := BackendLibraryEntries(b, []BackendPin{{"linux", "amd64", pinAMD}})
+	other := catalog.Release{ID: "t", Name: "t", Version: "1.0.0"}
+	list, err := BackendsFromLibrary(append(append(ra, other), rb...))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The add-on entry has no kind, so it is an add-on and is skipped.
+	if len(list) != 2 || list[0].Name != "z-first" || list[1].Name != "a-second" {
+		t.Errorf("library order is kept: %+v", list)
+	}
+}
+
+func TestToGalleryBackendUsesTheIdAsTheName(t *testing.T) {
+	rows, _ := BackendLibraryEntries(demoBackend(), []BackendPin{{"linux", "amd64", pinAMD}})
+	rows[0].Name = "Display name"
+	b, err := ToGalleryBackend(rows[0])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if b.Name != "cpu-demo" || b.URI != "quay.io/acme/backends:latest-cpu-demo" {
+		t.Errorf("the id is the name the gallery knows: %+v", b)
+	}
+	if _, err := ToGalleryBackend(catalog.Release{Kind: catalog.KindModel, ID: "m"}); err == nil {
+		t.Error("only a backend entry converts to a gallery backend")
+	}
+	rows[0].Icon = "icons/x.png"
+	if _, err := ToGalleryBackend(rows[0]); err == nil {
+		t.Error("an entry the host would refuse does not convert")
+	}
+}
+
+func TestEncodeBackendGalleryIndexReadsBackAsTheEntries(t *testing.T) {
+	a := demoBackend()
+	b := GalleryBackend{Metadata: Metadata{Name: "demo", Description: "x"}, CapabilitiesMap: map[string]string{"default": "cpu-demo"}}
+	raw, err := EncodeBackendGalleryIndex([]GalleryBackend{a, b})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var loaded []GalleryBackend
+	if err := yaml.Unmarshal(raw, &loaded); err != nil || len(loaded) != 2 {
+		t.Fatalf("%v %d", err, len(loaded))
+	}
+	if !SameBackend(loaded[0], a) || !SameBackend(loaded[1], b) {
+		t.Error("the gallery file does not read back as the entries")
+	}
+	a.Installed = true
+	a.Gallery.Name = "runtime"
+	again, err := EncodeBackendGalleryIndex([]GalleryBackend{a, b})
+	if err != nil || string(again) != string(raw) {
+		t.Errorf("runtime fields are not written: %v", err)
+	}
+	a.Version = "1"
+	if _, err := EncodeBackendGalleryIndex([]GalleryBackend{a}); err == nil {
+		t.Error("a field the file does not write is refused")
+	}
+}

core/gallery/backend_types.go

@@ -27,6 +27,9 @@ type BackendMetadata struct {
 	URI string `json:"uri,omitempty"`
 	// Digest is the OCI image digest at install time (for upgrade detection)
 	Digest string `json:"digest,omitempty"`
+	// Library is the id of the library the backend was installed from. It is
+	// empty for a backend installed from a gallery.
+	Library string `json:"library,omitempty"`
 }
 
 type GalleryBackend struct {
@@ -39,8 +42,22 @@ type GalleryBackend struct {
 	// SHA256 is the expected sha256 of the backend tarball at URI / Mirrors.
 	// Empty disables the integrity check; OCI URIs carry their own digest.
 	SHA256 string `json:"sha256,omitempty" yaml:"sha256,omitempty"`
+
+	// Library and MaxBytes are set by the install from a library, never read
+	// from a gallery file. Library records the origin in the metadata of the
+	// installed backend; MaxBytes bounds the compressed size of the image.
+	Library  string `json:"-" yaml:"-"`
+	MaxBytes int64  `json:"-" yaml:"-"`
+	// Stage, when set, receives the name of each install stage as it starts:
+	// the downloader stages (verifying, size, fetching) and StageWriting. A
+	// caller that shows progress sets it; the gallery never does.
+	Stage func(stage string) `json:"-" yaml:"-"`
 }
 
+// StageWriting is the install stage that writes the metadata of the backend
+// and swaps it into place. It follows the download stages.
+const StageWriting = "writing"
+
 func (backend *GalleryBackend) FindBestBackendFromMeta(systemState *system.SystemState, backends GalleryElements[*GalleryBackend]) *GalleryBackend {
 	if systemState == nil {
 		return nil

core/gallery/backends.go

@@ -383,6 +383,12 @@ func InstallBackend(ctx context.Context, systemState *system.SystemState, modelL
 		return fmt.Errorf("backend %q: %w", config.Name, optsErr)
 	}
 	downloadOpts = append(downloadOpts, downloader.WithStagingDir(systemState.StagingPath))
+	if config.MaxBytes > 0 {
+		downloadOpts = append(downloadOpts, downloader.WithMaxBytes(config.MaxBytes))
+	}
+	if config.Stage != nil {
+		downloadOpts = append(downloadOpts, downloader.WithStageReporter(config.Stage))
+	}
 
 	// PreferDevelopmentBackends installs the development image as the primary URI,
 	// keeping the released image reachable as the first fallback — instead of only
@@ -481,6 +487,10 @@ func InstallBackend(ctx context.Context, systemState *system.SystemState, modelL
 		return fmt.Errorf("not a valid backend: run file not found %q", stagedRunFile)
 	}
 
+	if config.Stage != nil {
+		config.Stage(StageWriting)
+	}
+
 	// Create metadata for the backend (written into the staged dir so the
 	// atomic swap brings a complete, self-describing backend into place).
 	metadata := &BackendMetadata{
@@ -489,6 +499,7 @@ func InstallBackend(ctx context.Context, systemState *system.SystemState, modelL
 		InstalledAt: time.Now().Format(time.RFC3339),
 		Version:     config.Version,
 		URI:         string(uri),
+		Library:     config.Library,
 	}
 
 	// Record the OCI digest for upgrade detection (non-fatal on failure)

core/gallery/gallery.go

@@ -660,6 +660,27 @@ func getGalleryElements[T GalleryElement](gallery config.Gallery, basePath strin
 		}
 	}
 
+	// The model and backend libraries replace the index of the official gallery
+	// when the owner selects them.
+	if lib, ok := modelLibraryFor(gallery); ok {
+		if installed, isModel := any(isInstalledCallback).(func(*GalleryModel) bool); isModel {
+			found, err := getModelLibraryElements(gallery, lib, basePath, requireIntegrity, installed)
+			if err != nil {
+				return models, err
+			}
+			return any(found).([]T), nil
+		}
+	}
+	if lib, ok := backendLibraryFor(gallery); ok {
+		if installed, isBackend := any(isInstalledCallback).(func(*GalleryBackend) bool); isBackend {
+			found, err := getBackendLibraryElements(gallery, lib, basePath, requireIntegrity, installed)
+			if err != nil {
+				return models, err
+			}
+			return any(found).([]T), nil
+		}
+	}
+
 	cacheKey := galleryIndexCacheKey(gallery)
 	if galleryCache.Exists(cacheKey) {
 		entry := galleryCache.Get(cacheKey)

core/gallery/model_index_source.go

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: MIT
+package gallery
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"github.com/mudler/xlog"
+)
+
+const (
+	// OfficialModelGalleryName is the name of the default model gallery.
+	OfficialModelGalleryName = "localai"
+	// OfficialModelLibraryURL is the model library, the source of the models,
+	// kept in this repository. It is a default model source. The gallery
+	// index is generated from it by scripts/models/cmd/modelcatalog.
+	OfficialModelLibraryURL = catalog.OfficialModelLibraryURL
+)
+
+// modelLibraryFor returns the library to read for a gallery, or false when the
+// gallery is read as a gallery index. A gallery is a library when its entry
+// says so, which is how a model source added with `local-ai library add` is
+// handed to the reader.
+func modelLibraryFor(g config.Gallery) (config.Gallery, bool) {
+	if !g.Library {
+		return config.Gallery{}, false
+	}
+	// The library has no mirrors and no artifact policy of its own: the
+	// gallery's would describe another file.
+	return config.Gallery{Name: g.Name, URL: g.URL}, true
+}
+
+// getModelLibraryElements reads the models of a gallery from the model
+// library. A library that cannot be fetched or read is an error: falling back
+// to the gallery would hide the setting from the owner who chose it.
+func getModelLibraryElements(g, lib config.Gallery, basePath string, requireIntegrity bool, isInstalled func(*GalleryModel) bool) ([]*GalleryModel, error) {
+	body, err := libraryBody(g, lib, basePath, requireIntegrity, "model")
+	if err != nil {
+		return nil, err
+	}
+	res, err := DecodeModelIndex(body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read the model library: %w", err)
+	}
+	if len(res.Skipped) > 0 {
+		xlog.Info("model library entries of another kind were skipped", "gallery", g.Name, "count", len(res.Skipped))
+	}
+	models, err := ModelsFromLibrary(res.Entries)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read the model library: %w", err)
+	}
+	// Only a library that decodes is kept, so a bad file does not stay cached.
+	keepLibraryBody(lib, body)
+	for _, m := range models {
+		m.SetGallery(g)
+		m.SetInstalled(isInstalled(m))
+	}
+	return models, nil
+}
+
+// libraryBody returns the text of a library: the cached copy while it is fresh,
+// else a fetch that follows the mirrors, the cooldown and the last known good
+// copy of any gallery. what names the kind in the error.
+func libraryBody(g, lib config.Gallery, basePath string, requireIntegrity bool, what string) ([]byte, error) {
+	cacheKey := galleryIndexCacheKey(lib)
+	if galleryCache.Exists(cacheKey) {
+		if entry := galleryCache.Get(cacheKey); !entry.hasExpired() {
+			return entry.yamlEntry, nil
+		}
+		galleryCache.Delete(cacheKey)
+	}
+	fetched, servedBy, err := fetchGalleryIndex(context.Background(), lib, basePath, requireIntegrity)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read the %s library: %w", what, err)
+	}
+	if servedBy != lib.URL {
+		xlog.Info(what+" library served by a fallback source", "gallery", g.Name, "source", servedBy)
+	}
+	return fetched, nil
+}
+
+// keepLibraryBody caches the text of a library that has been read.
+func keepLibraryBody(lib config.Gallery, body []byte) {
+	galleryCache.Set(galleryIndexCacheKey(lib), galleryCacheEntry{yamlEntry: body, lastUpdated: time.Now()})
+}

core/gallery/model_library.go

@@ -0,0 +1,515 @@
+// SPDX-License-Identifier: MIT
+package gallery
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"reflect"
+	"strconv"
+	"strings"
+
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"gopkg.in/yaml.v3"
+)
+
+// The model library, gallery/models/index.yaml, is the source of truth for
+// the models. Edits go there. The gallery index, gallery/index.yaml, is a
+// generated copy that stays only so releases before the cutover keep
+// working; scripts/models/cmd/modelcatalog writes it from the library and it
+// is never edited by hand.
+//
+// An entry is the shared library envelope (catalog.Envelope) plus a body that
+// holds what a gallery entry holds beyond the header. Converting a library
+// entry to a gallery entry and back gives the same entry, apart from the
+// header fields a gallery entry has no place for (see GalleryHeaderLoss). The
+// tests check that on every entry of the real library.
+
+const (
+	// MaxModelIndexBytes and MaxModelIndexEntries bound one model library
+	// document. The model gallery is much larger than an add-on index.
+	MaxModelIndexBytes   = 32 << 20
+	MaxModelIndexEntries = 20000
+	// modelLibraryChannel is the channel the generated entries are on.
+	modelLibraryChannel = "gallery"
+)
+
+// ModelBody is the kind-specific part of a model library entry.
+type ModelBody struct {
+	// URL is the config file the model installs from, as in the gallery.
+	URL string `json:"url,omitempty" yaml:"url,omitempty"`
+	// Backend is the resolved backend engine, when the entry says it.
+	Backend string `json:"backend,omitempty" yaml:"backend,omitempty"`
+	// Size is an optional size string such as "14.5GB".
+	Size  string `json:"size,omitempty" yaml:"size,omitempty"`
+	Files []File `json:"files,omitempty" yaml:"files,omitempty"`
+	// ConfigFile is the base config of an entry that has no URL.
+	ConfigFile map[string]any `json:"configFile,omitempty" yaml:"configFile,omitempty"`
+	// Overrides override the config the URL names.
+	Overrides map[string]any `json:"overrides,omitempty" yaml:"overrides,omitempty"`
+	// Variants name other entries that are alternative builds of this one.
+	Variants variantList `json:"variants,omitempty" yaml:"variants,omitempty"`
+	// PromptTemplates are the prompt templates of the base config. The gallery
+	// carries them inside config_file as prompt_templates; the library lifts
+	// them out so a reader can show them without reading the whole config.
+	PromptTemplates []PromptTemplate `json:"promptTemplates,omitempty" yaml:"promptTemplates,omitempty"`
+}
+
+// variantList keeps an empty list apart from an absent one: 194 gallery entries
+// write "variants: []", and the entry must come back as it was written.
+type variantList []Variant
+
+// IsZero makes omitempty drop only a list that is absent.
+func (v variantList) IsZero() bool { return v == nil }
+
+// ModelLibraryEntry is one entry of the model index.
+type ModelLibraryEntry struct {
+	catalog.Envelope `json:",inline" yaml:",inline"`
+	Model            ModelBody `json:"model" yaml:"model"`
+}
+
+const promptTemplatesKey = "prompt_templates"
+
+// ModelLibraryEntryFromGallery converts a gallery entry to a library entry.
+// The runtime fields of the gallery entry, the gallery it came from and its
+// installed flag, are not part of the entry and are dropped.
+func ModelLibraryEntryFromGallery(m GalleryModel) (ModelLibraryEntry, error) {
+	if m.Name == "" {
+		return ModelLibraryEntry{}, errors.New("gallery entry has no name")
+	}
+	m = stripRuntime(m)
+	digest, err := galleryEntryDigest(m)
+	if err != nil {
+		return ModelLibraryEntry{}, err
+	}
+	body := ModelBody{
+		URL:        m.URL,
+		Backend:    m.Backend,
+		Size:       m.Size,
+		Files:      m.AdditionalFiles,
+		ConfigFile: m.ConfigFile,
+		Overrides:  m.Overrides,
+		Variants:   variantList(m.Variants),
+	}
+	body.ConfigFile, body.PromptTemplates = liftPromptTemplates(m.ConfigFile)
+	return ModelLibraryEntry{
+		Envelope: catalog.Envelope{
+			Kind:          catalog.KindModel,
+			ID:            m.Name,
+			Name:          m.Name,
+			Version:       "0.0.0-gallery." + digest[:12],
+			Description:   m.Description,
+			License:       m.License,
+			URLs:          m.URLs,
+			Tags:          m.Tags,
+			Icon:          m.Icon,
+			Channel:       modelLibraryChannel,
+			SchemaVersion: catalog.SchemaVersion,
+		},
+		Model: body,
+	}, nil
+}
+
+// ToGallery converts a library entry to the gallery entry the installer
+// reads. The id of the entry is the name the gallery knows the model by; the
+// header name is for display and is not read back.
+func (e ModelLibraryEntry) ToGallery() (GalleryModel, error) {
+	if err := e.validate(); err != nil {
+		return GalleryModel{}, err
+	}
+	b := e.Model
+	return GalleryModel{
+		Metadata: Metadata{
+			URL:             b.URL,
+			Name:            e.ID,
+			Description:     e.Description,
+			License:         e.License,
+			URLs:            e.URLs,
+			Icon:            e.Icon,
+			Tags:            e.Tags,
+			AdditionalFiles: b.Files,
+			Size:            b.Size,
+			Backend:         b.Backend,
+		},
+		ConfigFile: restorePromptTemplates(b.ConfigFile, b.PromptTemplates),
+		Overrides:  b.Overrides,
+		Variants:   []Variant(b.Variants),
+	}, nil
+}
+
+func (e ModelLibraryEntry) validate() error {
+	if e.Kind != catalog.KindModel {
+		return fmt.Errorf("entry %q is of kind %q, not model", e.ID, e.Kind)
+	}
+	if e.ID == "" || len(e.ID) > 256 || strings.ContainsAny(e.ID, "\r\n\x00") {
+		return fmt.Errorf("model entry has a malformed id %q", e.ID)
+	}
+	if e.SchemaVersion < 1 || e.SchemaVersion > catalog.SchemaVersion {
+		return fmt.Errorf("model entry %q has schemaVersion %d; this host reads up to %d", e.ID, e.SchemaVersion, catalog.SchemaVersion)
+	}
+	return nil
+}
+
+func stripRuntime(m GalleryModel) GalleryModel {
+	m.Gallery = GalleryModel{}.Gallery
+	m.Installed = false
+	return m
+}
+
+// galleryEntryDigest identifies the content of a gallery entry. Maps are
+// written with sorted keys, so the digest does not depend on their order.
+func galleryEntryDigest(m GalleryModel) (string, error) {
+	b, err := yaml.Marshal(m)
+	if err != nil {
+		return "", err
+	}
+	sum := sha256.Sum256(b)
+	return hex.EncodeToString(sum[:]), nil
+}
+
+// liftPromptTemplates moves prompt_templates out of a base config when every
+// template is a plain name and content pair. A config that holds anything else
+// under that key is left as it is, so nothing is reshaped on the way.
+func liftPromptTemplates(cfg map[string]any) (map[string]any, []PromptTemplate) {
+	raw, ok := cfg[promptTemplatesKey]
+	if !ok {
+		return cfg, nil
+	}
+	list, ok := raw.([]any)
+	if !ok || len(list) == 0 {
+		return cfg, nil
+	}
+	out := make([]PromptTemplate, 0, len(list))
+	for _, item := range list {
+		m, ok := item.(map[string]any)
+		if !ok || len(m) != 2 {
+			return cfg, nil
+		}
+		name, okName := m["name"].(string)
+		content, okContent := m["content"].(string)
+		if !okName || !okContent {
+			return cfg, nil
+		}
+		out = append(out, PromptTemplate{Name: name, Content: content})
+	}
+	rest := make(map[string]any, len(cfg)-1)
+	for k, v := range cfg {
+		if k != promptTemplatesKey {
+			rest[k] = v
+		}
+	}
+	if len(rest) == 0 {
+		rest = nil
+	}
+	return rest, out
+}
+
+func restorePromptTemplates(cfg map[string]any, templates []PromptTemplate) map[string]any {
+	if len(templates) == 0 {
+		return cfg
+	}
+	out := make(map[string]any, len(cfg)+1)
+	for k, v := range cfg {
+		out[k] = v
+	}
+	list := make([]any, 0, len(templates))
+	for _, t := range templates {
+		list = append(list, map[string]any{"name": t.Name, "content": t.Content})
+	}
+	out[promptTemplatesKey] = list
+	return out
+}
+
+// ModelIndexResult is what a reader made of a model index: the entries it
+// understands and a record of those it skipped.
+type ModelIndexResult struct {
+	Entries []ModelLibraryEntry
+	Skipped []catalog.SkippedEntry
+}
+
+// DecodeModelIndex reads a model index: one YAML block list of entries. It is
+// as strict as the add-on reader: an unknown field, a second document, a
+// duplicate key or id, a value of the wrong type or a document over the size
+// bounds is refused. An entry of a kind other than model is skipped without
+// being read further and is reported in the result, so a shared file can hold
+// other kinds later.
+func DecodeModelIndex(data []byte) (ModelIndexResult, error) {
+	if len(data) > MaxModelIndexBytes {
+		return ModelIndexResult{}, errors.New("model index is too large")
+	}
+	dec := yaml.NewDecoder(bytes.NewReader(data))
+	var doc yaml.Node
+	if err := dec.Decode(&doc); err != nil {
+		return ModelIndexResult{}, err
+	}
+	if err := dec.Decode(new(yaml.Node)); err != io.EOF {
+		return ModelIndexResult{}, errors.New("model index holds more than one document")
+	}
+	if doc.Kind != yaml.DocumentNode || len(doc.Content) != 1 || doc.Content[0].Kind != yaml.SequenceNode {
+		return ModelIndexResult{}, errors.New("model index must be a list of entries")
+	}
+	list := doc.Content[0]
+	if list.Style&yaml.FlowStyle != 0 && len(list.Content) > 0 {
+		return ModelIndexResult{}, errors.New("model index must be a YAML block list, not JSON")
+	}
+	if len(list.Content) > MaxModelIndexEntries {
+		return ModelIndexResult{}, errors.New("model index has too many entries")
+	}
+	res := ModelIndexResult{}
+	seen := make(map[string]struct{}, len(list.Content))
+	for i, node := range list.Content {
+		if node.Kind != yaml.MappingNode {
+			return ModelIndexResult{}, errors.New("model index entry must be a mapping")
+		}
+		kind, id, err := peekKind(node)
+		if err != nil {
+			return ModelIndexResult{}, err
+		}
+		if kind != catalog.KindModel {
+			res.Skipped = append(res.Skipped, catalog.SkippedEntry{Position: i, Kind: string(kind), ID: id})
+			continue
+		}
+		raw, err := yaml.Marshal(node)
+		if err != nil {
+			return ModelIndexResult{}, err
+		}
+		strict := yaml.NewDecoder(bytes.NewReader(raw))
+		strict.KnownFields(true)
+		var entry ModelLibraryEntry
+		if err := strict.Decode(&entry); err != nil {
+			return ModelIndexResult{}, fmt.Errorf("model index entry %d: %w", i, err)
+		}
+		if err := entry.validate(); err != nil {
+			return ModelIndexResult{}, err
+		}
+		if _, dup := seen[entry.ID]; dup {
+			return ModelIndexResult{}, fmt.Errorf("model index lists %q twice", entry.ID)
+		}
+		seen[entry.ID] = struct{}{}
+		res.Entries = append(res.Entries, entry)
+	}
+	return res, nil
+}
+
+// peekKind reads the kind of an entry without reading the rest. An entry
+// without a kind is an add-on, as in the add-on reader.
+func peekKind(node *yaml.Node) (catalog.Kind, string, error) {
+	kind, id := catalog.KindAddon, ""
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		key, val := node.Content[i], node.Content[i+1]
+		switch key.Value {
+		case "kind":
+			if val.Kind != yaml.ScalarNode || val.Tag != "!!str" || !catalog.ValidKindName(val.Value) {
+				return "", "", errors.New("model index entry has a malformed kind")
+			}
+			kind = catalog.Kind(val.Value)
+		case "id":
+			if val.Kind == yaml.ScalarNode && val.Tag == "!!str" {
+				id = val.Value
+			}
+		}
+	}
+	return kind, id, nil
+}
+
+// floatValue writes a float so that it reads back as a float. The YAML encoder
+// writes 1.0 as 1, which reads back as an integer and would change the type of
+// a number in an override.
+type floatValue float64
+
+func (f floatValue) MarshalYAML() (any, error) {
+	v := float64(f)
+	if math.IsNaN(v) || math.IsInf(v, 0) {
+		return v, nil
+	}
+	s := strconv.FormatFloat(v, 'g', -1, 64)
+	if !strings.ContainsAny(s, ".eE") {
+		s += ".0"
+	}
+	return &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!float", Value: s}, nil
+}
+
+// markFloats copies a config value and wraps its floats in floatValue.
+func markFloats(v any) any {
+	switch t := v.(type) {
+	case float64:
+		return floatValue(t)
+	case map[string]any:
+		if t == nil {
+			return t
+		}
+		out := make(map[string]any, len(t))
+		for k, x := range t {
+			out[k] = markFloats(x)
+		}
+		return out
+	case map[any]any:
+		if t == nil {
+			return t
+		}
+		out := make(map[any]any, len(t))
+		for k, x := range t {
+			out[k] = markFloats(x)
+		}
+		return out
+	case []any:
+		if t == nil {
+			return t
+		}
+		out := make([]any, len(t))
+		for i, x := range t {
+			out[i] = markFloats(x)
+		}
+		return out
+	}
+	return v
+}
+
+func markFloatMap(m map[string]any) map[string]any {
+	if m == nil {
+		return nil
+	}
+	return markFloats(m).(map[string]any)
+}
+
+// EncodeModelIndex writes entries as a model index.
+func EncodeModelIndex(entries []ModelLibraryEntry) ([]byte, error) {
+	marked := make([]ModelLibraryEntry, len(entries))
+	for i, e := range entries {
+		e.Model.ConfigFile = markFloatMap(e.Model.ConfigFile)
+		e.Model.Overrides = markFloatMap(e.Model.Overrides)
+		marked[i] = e
+	}
+	var buf bytes.Buffer
+	enc := yaml.NewEncoder(&buf)
+	enc.SetIndent(2)
+	if err := enc.Encode(marked); err != nil {
+		return nil, err
+	}
+	if err := enc.Close(); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+// galleryFileEntry is a gallery entry as it is written to the gallery file.
+// It has the fields and the order of GalleryModel, but keeps an empty variants
+// list apart from an absent one, as the gallery file did.
+type galleryFileEntry struct {
+	Metadata   `yaml:",inline"`
+	ConfigFile map[string]any `yaml:"config_file,omitempty"`
+	Overrides  map[string]any `yaml:"overrides,omitempty"`
+	Variants   variantList    `yaml:"variants,omitempty"`
+}
+
+// EncodeGalleryIndex writes gallery entries as the gallery file the host
+// reads (gallery/index.yaml). The runtime fields of an entry are not written
+// and a float keeps its form, so the file reads back as the entries it was
+// written from.
+func EncodeGalleryIndex(models []GalleryModel) ([]byte, error) {
+	out := make([]galleryFileEntry, len(models))
+	for i, m := range models {
+		m = stripRuntime(m)
+		out[i] = galleryFileEntry{
+			Metadata:   m.Metadata,
+			ConfigFile: markFloatMap(m.ConfigFile),
+			Overrides:  markFloatMap(m.Overrides),
+			Variants:   variantList(m.Variants),
+		}
+	}
+	var buf bytes.Buffer
+	enc := yaml.NewEncoder(&buf)
+	enc.SetIndent(2)
+	if err := enc.Encode(out); err != nil {
+		return nil, err
+	}
+	if err := enc.Close(); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+// GalleryHeaderLoss names the header fields of a library entry that the
+// gallery copy cannot carry and that the entry sets on purpose: a display name
+// that differs from the id, and a signature policy. The version, the channel
+// and the schema version are never carried; the host does not read any of
+// them from a gallery.
+func GalleryHeaderLoss(e ModelLibraryEntry) []string {
+	var lost []string
+	if e.Name != "" && e.Name != e.ID {
+		lost = append(lost, "name")
+	}
+	if !reflect.DeepEqual(e.Policy, catalog.VerificationPolicy{}) {
+		lost = append(lost, "policy")
+	}
+	return lost
+}
+
+// ModelsFromLibrary converts the entries of a model index to gallery entries,
+// in index order.
+func ModelsFromLibrary(entries []ModelLibraryEntry) ([]*GalleryModel, error) {
+	out := make([]*GalleryModel, 0, len(entries))
+	for _, e := range entries {
+		m, err := e.ToGallery()
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, &m)
+	}
+	return out, nil
+}
+
+// VerifyModelRoundTrip checks that a gallery entry survives the library: it is
+// converted to a library entry, written as an index, read back and converted
+// to a gallery entry again, and the result must equal the original. It returns
+// a description of the first difference.
+func VerifyModelRoundTrip(m GalleryModel) error {
+	want := stripRuntime(m)
+	entry, err := ModelLibraryEntryFromGallery(m)
+	if err != nil {
+		return err
+	}
+	raw, err := EncodeModelIndex([]ModelLibraryEntry{entry})
+	if err != nil {
+		return fmt.Errorf("writing the library entry: %w", err)
+	}
+	res, err := DecodeModelIndex(raw)
+	if err != nil {
+		return fmt.Errorf("reading the library entry: %w", err)
+	}
+	if len(res.Entries) != 1 {
+		return fmt.Errorf("the library entry came back as %d entries", len(res.Entries))
+	}
+	got, err := res.Entries[0].ToGallery()
+	if err != nil {
+		return err
+	}
+	if reflect.DeepEqual(got, want) {
+		return nil
+	}
+	return fmt.Errorf("gallery entry changed on the way through the library: %s", firstDifference(want, got))
+}
+
+// firstDifference names the first top-level field of two gallery entries that
+// differ.
+func firstDifference(a, b GalleryModel) string {
+	av, bv := reflect.ValueOf(a.Metadata), reflect.ValueOf(b.Metadata)
+	for i := 0; i < av.NumField(); i++ {
+		if !reflect.DeepEqual(av.Field(i).Interface(), bv.Field(i).Interface()) {
+			return fmt.Sprintf("%s: %#v became %#v", av.Type().Field(i).Name, av.Field(i).Interface(), bv.Field(i).Interface())
+		}
+	}
+	switch {
+	case !reflect.DeepEqual(a.ConfigFile, b.ConfigFile):
+		return fmt.Sprintf("ConfigFile: %#v became %#v", a.ConfigFile, b.ConfigFile)
+	case !reflect.DeepEqual(a.Overrides, b.Overrides):
+		return fmt.Sprintf("Overrides: %#v became %#v", a.Overrides, b.Overrides)
+	case !reflect.DeepEqual(a.Variants, b.Variants):
+		return fmt.Sprintf("Variants: %#v became %#v", a.Variants, b.Variants)
+	}
+	return "unknown field"
+}

core/gallery/model_library_digest.go

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+package gallery
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+)
+
+// ModelLibraryDigests returns short digests of a library entry and of the
+// gallery entry generated from it. They identify the content for the golden
+// file: when the library digest of an entry has not changed, its generated
+// gallery digest must not change either.
+func ModelLibraryDigests(e ModelLibraryEntry) (libraryDigest, galleryDigest string, err error) {
+	m, err := e.ToGallery()
+	if err != nil {
+		return "", "", err
+	}
+	g, err := galleryEntryDigest(stripRuntime(m))
+	if err != nil {
+		return "", "", err
+	}
+	raw, err := EncodeModelIndex([]ModelLibraryEntry{e})
+	if err != nil {
+		return "", "", err
+	}
+	sum := sha256.Sum256(raw)
+	return hex.EncodeToString(sum[:])[:16], g[:16], nil
+}

core/gallery/model_library_test.go

@@ -0,0 +1,549 @@
+package gallery
+
+import (
+	"bufio"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"github.com/mudler/LocalAI/pkg/system"
+	"gopkg.in/yaml.v3"
+)
+
+const (
+	realGalleryIndex  = "../../gallery/index.yaml"
+	realModelLibrary  = "../../gallery/models/index.yaml"
+	modelLibraryGolds = "testdata/model_library"
+)
+
+// loadRealLibrary reads the library file, the source of the models, the way
+// the host reads a library.
+func loadRealLibrary(t *testing.T) []ModelLibraryEntry {
+	t.Helper()
+	src, err := os.ReadFile(realModelLibrary)
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err := DecodeModelIndex(src)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Entries) == 0 {
+		t.Fatal("the real model library has no entries")
+	}
+	return res.Entries
+}
+
+// sameModelEntry compares two library entries apart from the generator-owned
+// header fields the gallery has no place for: the version, which is derived
+// from the content, and the channel.
+func sameModelEntry(t *testing.T, a, b ModelLibraryEntry) bool {
+	t.Helper()
+	a.Version, b.Version = "", ""
+	a.Channel, b.Channel = "", ""
+	x, err := EncodeModelIndex([]ModelLibraryEntry{a})
+	if err != nil {
+		t.Fatal(err)
+	}
+	y, err := EncodeModelIndex([]ModelLibraryEntry{b})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(x) == string(y)
+}
+
+// Every entry of the real library must survive the gallery copy unchanged:
+// library -> gallery -> library is the same entry, and gallery -> library ->
+// gallery is the same gallery entry. The count is logged so a run shows how
+// many real entries it covered.
+func TestModelLibraryRoundTripsEveryRealEntry(t *testing.T) {
+	entries := loadRealLibrary(t)
+	failed := 0
+	for _, e := range entries {
+		m, err := e.ToGallery()
+		if err != nil {
+			failed++
+			t.Errorf("%s: %v", e.ID, err)
+			continue
+		}
+		if err := VerifyModelRoundTrip(m); err != nil {
+			failed++
+			t.Errorf("%s: %v", e.ID, err)
+			continue
+		}
+		back, err := ModelLibraryEntryFromGallery(m)
+		if err != nil {
+			failed++
+			t.Errorf("%s: %v", e.ID, err)
+			continue
+		}
+		if !sameModelEntry(t, e, back) {
+			failed++
+			t.Errorf("%s: library -> gallery -> library changed the entry", e.ID)
+		}
+	}
+	t.Logf("round trip: %d of %d real library entries are equal after library -> gallery -> library", len(entries)-failed, len(entries))
+}
+
+// The gallery generated from the library is read by the gallery reader, and
+// the reader sees the same entries: the names, the file uris and the digests.
+func TestGeneratedGalleryLoadsWithTheSameEntries(t *testing.T) {
+	entries := loadRealLibrary(t)
+	models, err := ModelsFromLibrary(entries)
+	if err != nil {
+		t.Fatal(err)
+	}
+	flat := make([]GalleryModel, len(models))
+	for i, m := range models {
+		flat[i] = *m
+	}
+	body, err := EncodeGalleryIndex(flat)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The host reads the gallery file into a list of pointers.
+	var loaded []*GalleryModel
+	if err := yaml.Unmarshal(body, &loaded); err != nil {
+		t.Fatal(err)
+	}
+	if len(loaded) != len(entries) {
+		t.Fatalf("the gallery has %d entries, the library %d", len(loaded), len(entries))
+	}
+	files := 0
+	for i, e := range entries {
+		g := loaded[i]
+		if g.Name != e.ID {
+			t.Fatalf("entry %d is %q in the gallery and %q in the library", i, g.Name, e.ID)
+		}
+		if len(g.AdditionalFiles) != len(e.Model.Files) {
+			t.Errorf("%s: %d files in the gallery, %d in the library", e.ID, len(g.AdditionalFiles), len(e.Model.Files))
+			continue
+		}
+		for j, f := range e.Model.Files {
+			files++
+			if g.AdditionalFiles[j].URI != f.URI || g.AdditionalFiles[j].SHA256 != f.SHA256 || g.AdditionalFiles[j].Filename != f.Filename {
+				t.Errorf("%s: file %d differs: %+v and %+v", e.ID, j, g.AdditionalFiles[j], f)
+			}
+		}
+		if !reflect.DeepEqual(*g, *models[i]) {
+			t.Errorf("%s: the gallery reader sees a different entry than the library gives", e.ID)
+		}
+		gd, _ := galleryEntryDigest(*g)
+		wd, _ := galleryEntryDigest(*models[i])
+		if gd != wd {
+			t.Errorf("%s: gallery digest %s, library digest %s", e.ID, gd[:12], wd[:12])
+		}
+	}
+	t.Logf("generated gallery: %d entries and %d files read back equal to the library", len(loaded), files)
+}
+
+// gallery/index.yaml is generated and never edited. The CI check regenerates it
+// and fails on a diff; this test does the same in the Go suite, so a hand edit
+// is found by go test too.
+func TestCheckedInGalleryIsTheGeneratedCopy(t *testing.T) {
+	models, err := ModelsFromLibrary(loadRealLibrary(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	flat := make([]GalleryModel, len(models))
+	for i, m := range models {
+		flat[i] = *m
+	}
+	want, err := EncodeGalleryIndex(flat)
+	if err != nil {
+		t.Fatal(err)
+	}
+	have, err := os.ReadFile(realGalleryIndex)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The generator puts a comment header in front of the body.
+	body := string(have)
+	for strings.HasPrefix(body, "#") {
+		_, rest, _ := strings.Cut(body, "\n")
+		body = rest
+	}
+	if body != string(want) {
+		t.Error("gallery/index.yaml is not the copy generated from gallery/models/index.yaml. It is generated; do not edit it by hand. Regenerate: go run ./scripts/models/cmd/modelcatalog --library gallery/models/index.yaml --out gallery/index.yaml")
+	}
+}
+
+// An entry whose library digest is in the golden file must still produce the
+// recorded gallery entry. An entry changed or added since the golden file was
+// rendered has no recorded digest and is covered by the round trip only.
+func TestModelLibraryMatchesGoldenDigests(t *testing.T) {
+	f, err := os.Open(filepath.Join(modelLibraryGolds, "digests.tsv"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	type pair struct{ library, gallery string }
+	golden := map[string]pair{}
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		line := sc.Text()
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		parts := strings.Split(line, "\t")
+		if len(parts) != 3 {
+			t.Fatalf("malformed golden line %q", line)
+		}
+		golden[parts[0]] = pair{parts[1], parts[2]}
+	}
+	if err := sc.Err(); err != nil {
+		t.Fatal(err)
+	}
+	if len(golden) < 2000 {
+		t.Fatalf("the golden file lists %d entries; it should list the real library", len(golden))
+	}
+
+	checked, unchanged := 0, 0
+	for _, e := range loadRealLibrary(t) {
+		want, ok := golden[e.ID]
+		if !ok {
+			continue
+		}
+		l, g, err := ModelLibraryDigests(e)
+		if err != nil {
+			t.Fatalf("%s: %v", e.ID, err)
+		}
+		checked++
+		if l != want.library {
+			continue // the entry changed after the golden file was rendered
+		}
+		unchanged++
+		if g != want.gallery {
+			t.Errorf("%s: the generated gallery entry changed (digest %s, golden %s); render the golden files again only if the change is intended", e.ID, g, want.gallery)
+		}
+	}
+	t.Logf("golden digests: %d of %d golden entries are in the library, %d unchanged and compared", checked, len(golden), unchanged)
+	// Most entries are stable between renders. If almost none match, the digest
+	// of the library side has changed meaning and the check proves nothing.
+	if unchanged*2 < checked {
+		t.Errorf("only %d of %d golden entries kept their library digest; render the golden files again", unchanged, checked)
+	}
+}
+
+// The readable samples are written both ways: the library entry as it stands
+// in the library and the gallery entry generated from it.
+func TestModelLibraryMatchesGoldenSamples(t *testing.T) {
+	libraries, err := filepath.Glob(filepath.Join(modelLibraryGolds, "samples", "*.library.yaml"))
+	if err != nil || len(libraries) == 0 {
+		t.Fatalf("no golden samples: %v", err)
+	}
+	for _, lpath := range libraries {
+		name := strings.TrimSuffix(filepath.Base(lpath), ".library.yaml")
+		t.Run(name, func(t *testing.T) {
+			src, err := os.ReadFile(lpath)
+			if err != nil {
+				t.Fatal(err)
+			}
+			galWant, err := os.ReadFile(strings.TrimSuffix(lpath, ".library.yaml") + ".gallery.yaml")
+			if err != nil {
+				t.Fatal(err)
+			}
+			res, err := DecodeModelIndex(src)
+			if err != nil || len(res.Entries) != 1 {
+				t.Fatalf("reading the sample: %v (%d entries)", err, len(res.Entries))
+			}
+			// The library sample is what a library file holds.
+			again, err := EncodeModelIndex(res.Entries)
+			if err != nil || string(again) != string(src) {
+				t.Errorf("the library sample does not encode back to itself: %v", err)
+			}
+			m, err := res.Entries[0].ToGallery()
+			if err != nil {
+				t.Fatal(err)
+			}
+			got, err := EncodeGalleryIndex([]GalleryModel{m})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if string(got) != string(galWant) {
+				t.Errorf("the gallery entry differs from the golden file:\n%s", got)
+			}
+
+			var loaded []GalleryModel
+			if err := yaml.Unmarshal(galWant, &loaded); err != nil || len(loaded) != 1 {
+				t.Fatalf("the gallery reader on the golden entry: %v", err)
+			}
+			if d := firstDifference(stripRuntime(m), loaded[0]); d != "unknown field" {
+				t.Errorf("the golden gallery entry does not load as the library entry: %s", d)
+			}
+			if err := VerifyModelRoundTrip(loaded[0]); err != nil {
+				t.Error(err)
+			}
+		})
+	}
+}
+
+// The library file in the repository is the source and is read by the host,
+// so it must decode, and every entry must have the library shape: it converts
+// to a gallery entry and comes back as itself. Edited entries keep their own
+// version; only the content is compared.
+func TestRealModelLibraryHasTheLibraryShape(t *testing.T) {
+	src, err := os.ReadFile(realModelLibrary)
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err := DecodeModelIndex(src)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Skipped) != 0 {
+		t.Errorf("the model library skipped %d entries", len(res.Skipped))
+	}
+	for _, e := range res.Entries {
+		if e.Name != e.ID {
+			t.Errorf("%s: the name %q differs from the id; the gallery copy cannot carry it", e.ID, e.Name)
+		}
+		m, err := e.ToGallery()
+		if err != nil {
+			t.Fatalf("%s: %v", e.ID, err)
+		}
+		again, err := ModelLibraryEntryFromGallery(m)
+		if err != nil {
+			t.Fatalf("%s: %v", e.ID, err)
+		}
+		if !sameModelEntry(t, e, again) {
+			t.Errorf("%s: the entry changes on the way through the gallery copy; it has a field the gallery cannot carry", e.ID)
+		}
+	}
+	t.Logf("model library: %d entries have the library shape", len(res.Entries))
+}
+
+func libraryEntry(extra string) string {
+	return "- kind: model\n  id: m1\n  name: m1\n  version: 0.0.0-test\n  policy:\n    requireSignature: false\n  schemaVersion: 1\n" + extra
+}
+
+func TestDecodeModelIndexIsStrict(t *testing.T) {
+	cases := map[string]string{
+		"unknown header field": libraryEntry("  surprise: 1\n"),
+		"unknown body field":   libraryEntry("  model:\n    surprise: 1\n"),
+		"duplicate key":        libraryEntry("  tags: [a]\n  tags: [b]\n"),
+		"duplicate id":         libraryEntry("") + libraryEntry(""),
+		"future schema":        strings.Replace(libraryEntry(""), "schemaVersion: 1", "schemaVersion: 2", 1),
+		"no schema":            strings.Replace(libraryEntry(""), "schemaVersion: 1", "schemaVersion: 0", 1),
+		"empty id":             strings.Replace(libraryEntry(""), "id: m1", "id: \"\"", 1),
+		"malformed kind":       "- kind: 5\n  id: x\n",
+		"bad kind name":        "- kind: Model!\n  id: x\n",
+		"flow list":            "[{kind: model, id: m1}]\n",
+		"two documents":        libraryEntry("") + "---\n" + libraryEntry(""),
+		"not a list":           "kind: model\n",
+		"entry not a mapping":  "- 3\n",
+		"wrong type":           libraryEntry("  model:\n    files: yes\n"),
+	}
+	for name, doc := range cases {
+		t.Run(name, func(t *testing.T) {
+			if _, err := DecodeModelIndex([]byte(doc)); err == nil {
+				t.Errorf("the reader accepted %q", doc)
+			}
+		})
+	}
+	t.Run("too large", func(t *testing.T) {
+		if _, err := DecodeModelIndex(make([]byte, MaxModelIndexBytes+1)); err == nil {
+			t.Error("the reader accepted an oversized document")
+		}
+	})
+}
+
+func TestDecodeModelIndexSkipsOtherKinds(t *testing.T) {
+	doc := "- kind: backend\n  id: b1\n  anything: goes\n" +
+		"- id: legacy-addon\n  addonId: legacy-addon\n" +
+		"- kind: future-kind\n  id: f1\n" +
+		libraryEntry("")
+	res, err := DecodeModelIndex([]byte(doc))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Entries) != 1 || res.Entries[0].ID != "m1" {
+		t.Errorf("entries = %+v", res.Entries)
+	}
+	var kinds []string
+	for _, s := range res.Skipped {
+		kinds = append(kinds, s.Kind+":"+s.ID)
+	}
+	want := "backend:b1 addon:legacy-addon future-kind:f1"
+	if strings.Join(kinds, " ") != want {
+		t.Errorf("skipped = %v, want %s", kinds, want)
+	}
+}
+
+func TestModelLibraryKeepsAnAddonReaderWorking(t *testing.T) {
+	// The add-on reader skips model entries, so one file can later hold both.
+	doc, err := EncodeModelIndex([]ModelLibraryEntry{{
+		Envelope: catalog.Envelope{Kind: catalog.KindModel, ID: "m1", Name: "m1", Version: "1", SchemaVersion: 1},
+	}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err := catalog.ReadIndex(doc, catalog.ReadableKinds...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Releases) != 0 || len(res.Skipped) != 1 || res.Skipped[0].Kind != "model" {
+		t.Errorf("the add-on reader made %+v", res)
+	}
+}
+
+func TestPromptTemplatesAreLiftedAndRestored(t *testing.T) {
+	m := GalleryModel{
+		Metadata: Metadata{Name: "templated"},
+		ConfigFile: map[string]any{
+			"backend": "llama",
+			"prompt_templates": []any{
+				map[string]any{"name": "chat", "content": "{{.Input}}"},
+			},
+		},
+	}
+	e, err := ModelLibraryEntryFromGallery(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(e.Model.PromptTemplates) != 1 || e.Model.PromptTemplates[0].Name != "chat" {
+		t.Errorf("promptTemplates = %+v", e.Model.PromptTemplates)
+	}
+	if _, still := e.Model.ConfigFile["prompt_templates"]; still {
+		t.Error("prompt_templates was left in configFile")
+	}
+	if err := VerifyModelRoundTrip(m); err != nil {
+		t.Error(err)
+	}
+
+	// Only templates are in the config: nothing is left behind and it still
+	// round trips.
+	only := GalleryModel{
+		Metadata:   Metadata{Name: "only"},
+		ConfigFile: map[string]any{"prompt_templates": []any{map[string]any{"name": "a", "content": "b"}}},
+	}
+	if err := VerifyModelRoundTrip(only); err != nil {
+		t.Error(err)
+	}
+
+	// A template with another key is not reshaped.
+	odd := GalleryModel{
+		Metadata:   Metadata{Name: "odd"},
+		ConfigFile: map[string]any{"prompt_templates": []any{map[string]any{"name": "a", "content": "b", "extra": 1}}},
+	}
+	oe, _ := ModelLibraryEntryFromGallery(odd)
+	if len(oe.Model.PromptTemplates) != 0 {
+		t.Error("a template with an extra key was lifted")
+	}
+	if err := VerifyModelRoundTrip(odd); err != nil {
+		t.Error(err)
+	}
+}
+
+func TestRoundTripKeepsNumberTypesAndEmptyLists(t *testing.T) {
+	m := GalleryModel{
+		Metadata: Metadata{Name: "numbers", Tags: []string{"1.0", "yes", "null"}},
+		Overrides: map[string]any{
+			"temperature": 1.0,
+			"top_k":       20,
+			"min_p":       0.0,
+			"big":         1e21,
+			"nested":      map[string]any{"list": []any{1.0, 2, "3"}},
+			"flag":        true,
+			"nothing":     nil,
+		},
+		Variants: []Variant{},
+	}
+	if err := VerifyModelRoundTrip(m); err != nil {
+		t.Error(err)
+	}
+	if err := VerifyModelRoundTrip(GalleryModel{}); err == nil {
+		t.Error("an entry without a name was accepted")
+	}
+}
+
+func TestRuntimeFieldsAreNotPartOfTheEntry(t *testing.T) {
+	m := GalleryModel{Metadata: Metadata{Name: "runtime", Installed: true, Gallery: config.Gallery{Name: "x", URL: "y"}}}
+	e, err := ModelLibraryEntryFromGallery(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := EncodeModelIndex([]ModelLibraryEntry{e})
+	if strings.Contains(string(raw), "installed") || strings.Contains(string(raw), "gallery") && strings.Contains(string(raw), "url: y") {
+		t.Errorf("runtime fields reached the library:\n%s", raw)
+	}
+	if err := VerifyModelRoundTrip(m); err != nil {
+		t.Error(err)
+	}
+}
+
+// A gallery marked as a library is read as a library; any other gallery is read as an index.
+func TestLibraryGalleryReadsTheLibrary(t *testing.T) {
+	library := libraryEntry("  model:\n    files:\n      - filename: m1.gguf\n        sha256: abc\n        uri: https://example.invalid/m1.gguf\n    overrides:\n      backend: llama-cpp\n")
+	var libraryHits, galleryHits int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/models/index.yaml":
+			libraryHits++
+			_, _ = w.Write([]byte(library))
+		case "/gallery/index.yaml":
+			galleryHits++
+			_, _ = w.Write([]byte("- name: from-gallery\n  overrides:\n    backend: llama-cpp\n"))
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	t.Cleanup(srv.Close)
+
+	systemState, err := system.GetSystemState(system.WithModelPath(t.TempDir()))
+	if err != nil {
+		t.Fatal(err)
+	}
+	names := func(g config.Gallery) []string {
+		t.Helper()
+		models, err := AvailableGalleryModels([]config.Gallery{g}, systemState)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return galleryModelNames(models)
+	}
+	official := config.Gallery{Name: OfficialModelGalleryName, URL: srv.URL + "/gallery/index.yaml"}
+
+	// Default: the gallery index, and the library file is never requested.
+	if got := names(official); len(got) != 1 || got[0] != "from-gallery" {
+		t.Errorf("default source gave %v", got)
+	}
+	if libraryHits != 0 {
+		t.Errorf("the library was read %d times with the default source", libraryHits)
+	}
+
+	// Library: a gallery marked as a library is read as one.
+	official.Library = true
+	official.URL = srv.URL + "/models/index.yaml"
+	models, err := AvailableGalleryModels([]config.Gallery{official}, systemState)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := galleryModelNames(models); len(got) != 1 || got[0] != "m1" {
+		t.Errorf("library source gave %v", got)
+	}
+	if models[0].GetGallery().Name != OfficialModelGalleryName || models[0].GetGallery().URL != official.URL || !models[0].GetGallery().Library {
+		t.Errorf("the entry should carry the configured gallery, got %+v", models[0].GetGallery())
+	}
+	if len(models[0].AdditionalFiles) != 1 || models[0].Overrides["backend"] != "llama-cpp" {
+		t.Errorf("the entry lost its body: %+v", models[0])
+	}
+
+	// A gallery the owner added keeps its own index.
+	other := config.Gallery{Name: "mine", URL: srv.URL + "/gallery/index.yaml"}
+	if got := names(other); len(got) != 1 || got[0] != "from-gallery" {
+		t.Errorf("another gallery gave %v", got)
+	}
+
+	// An unreachable library is an error, not a silent fall back.
+	official.URL = srv.URL + "/missing.yaml"
+	if _, err := AvailableGalleryModels([]config.Gallery{official}, systemState); err == nil {
+		t.Error("a missing library fell back to the gallery")
+	}
+}

core/gallery/models.go

@@ -79,8 +79,8 @@ type File struct {
 }
 
 type PromptTemplate struct {
-	Name    string `yaml:"name"`
-	Content string `yaml:"content"`
+	Name    string `yaml:"name" json:"name"`
+	Content string `yaml:"content" json:"content"`
 }
 
 // variantOptions turns an entry's declared variants into selectable options,

core/gallery/testdata/backend_library/samples/development.gallery.yaml

@@ -0,0 +1,32 @@
+- name: cpu-locate-anything-cpp-development
+  alias: locate-anything
+  license: apache-2.0
+  description: |
+    Open-vocabulary object detection and visual grounding (NVIDIA
+    LocateAnything-3B) in C/C++ using GGML. Loads pre-built GGUF weights
+    and, given an image and a free-form text prompt, returns bounding
+    boxes, class labels, and confidence scores for the referred objects.
+  urls:
+    - https://github.com/mudler/locate-anything.cpp
+    - https://huggingface.co/nvidia/LocateAnything-3B
+  tags:
+    - object-detection
+    - visual-grounding
+    - open-vocabulary
+    - locate-anything
+    - gpu
+    - cpu
+  capabilities:
+    default: cpu-locate-anything-cpp
+    intel: intel-sycl-f32-locate-anything-cpp
+    metal: metal-locate-anything-cpp
+    nvidia: cuda12-locate-anything-cpp
+    nvidia-cuda-12: cuda12-locate-anything-cpp
+    nvidia-cuda-13: cuda13-locate-anything-cpp
+    nvidia-l4t: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-locate-anything-cpp
+    vulkan: vulkan-locate-anything-cpp
+  uri: quay.io/go-skynet/local-ai-backends:master-cpu-locate-anything-cpp
+  mirrors:
+    - localai/localai-backends:master-cpu-locate-anything-cpp

core/gallery/testdata/backend_library/samples/development.library.yaml

@@ -0,0 +1,40 @@
+- alias: locate-anything
+  arch: amd64
+  artifact: oci://quay.io/go-skynet/local-ai-backends:master-cpu-locate-anything-cpp
+  capabilities:
+    default: cpu-locate-anything-cpp
+    intel: intel-sycl-f32-locate-anything-cpp
+    metal: metal-locate-anything-cpp
+    nvidia: cuda12-locate-anything-cpp
+    nvidia-cuda-12: cuda12-locate-anything-cpp
+    nvidia-cuda-13: cuda13-locate-anything-cpp
+    nvidia-l4t: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-locate-anything-cpp
+    vulkan: vulkan-locate-anything-cpp
+  channel: development
+  description: |
+    Open-vocabulary object detection and visual grounding (NVIDIA
+    LocateAnything-3B) in C/C++ using GGML. Loads pre-built GGUF weights
+    and, given an image and a free-form text prompt, returns bounding
+    boxes, class labels, and confidence scores for the referred objects.
+  id: cpu-locate-anything-cpp-development
+  kind: backend
+  license: apache-2.0
+  mirrors:
+    - oci://localai/localai-backends:master-cpu-locate-anything-cpp
+  mutable: true
+  name: cpu-locate-anything-cpp-development
+  os: linux
+  schemaVersion: 1
+  tags:
+    - object-detection
+    - visual-grounding
+    - open-vocabulary
+    - locate-anything
+    - gpu
+    - cpu
+  urls:
+    - https://github.com/mudler/locate-anything.cpp
+    - https://huggingface.co/nvidia/LocateAnything-3B
+  version: 0.0.0-development

core/gallery/testdata/backend_library/samples/meta-development.gallery.yaml

@@ -0,0 +1,37 @@
+- name: vllm-cpp-development
+  alias: vllm-cpp
+  license: apache-2.0
+  description: |
+    ALPHA development builds. Try it, but llama-cpp stays the recommendation for
+    production use.
+
+    vllm.cpp is an Apache-2.0 C++20 inference engine maintained by the LocalAI team,
+    developed in its own repository and usable without LocalAI. It began as a port of
+    vLLM and keeps vLLM as its reference implementation, checking output against it and
+    benchmarking against it, while growing a featureset of its own. It implements vLLM's
+    V1 architecture (paged KV cache, continuous batching, prefix caching, scheduler,
+    sampler) on a portable tensor runtime with no Python, PyTorch or ggml at inference
+    time. It loads GGUF as well as Hugging Face safetensors, supports structured output
+    (JSON schema / regex / choice / GBNF grammar) enforced in-engine, ships speculative
+    decoding and KV offload, and runs on CPU, NVIDIA CUDA (Blackwell-family), Apple
+    Metal and Vulkan.
+
+    The project is expected to be renamed as it diverges further from vLLM; the new
+    name is still to be decided.
+  urls:
+    - https://github.com/mudler/vllm.cpp
+  tags:
+    - text-to-text
+    - LLM
+    - CPU
+    - GPU
+    - CUDA
+    - metal
+  capabilities:
+    default: cpu-vllm-cpp-development
+    metal: metal-vllm-cpp-development
+    nvidia: cuda13-vllm-cpp-development
+    nvidia-cuda-13: cuda13-vllm-cpp-development
+    nvidia-l4t: nvidia-l4t-arm64-vllm-cpp-development
+    nvidia-l4t-cuda-13: nvidia-l4t-arm64-vllm-cpp-development
+    vulkan: vulkan-vllm-cpp-development

core/gallery/testdata/backend_library/samples/meta-development.library.yaml

@@ -0,0 +1,42 @@
+- alias: vllm-cpp
+  capabilities:
+    default: cpu-vllm-cpp-development
+    metal: metal-vllm-cpp-development
+    nvidia: cuda13-vllm-cpp-development
+    nvidia-cuda-13: cuda13-vllm-cpp-development
+    nvidia-l4t: nvidia-l4t-arm64-vllm-cpp-development
+    nvidia-l4t-cuda-13: nvidia-l4t-arm64-vllm-cpp-development
+    vulkan: vulkan-vllm-cpp-development
+  channel: development
+  description: |
+    ALPHA development builds. Try it, but llama-cpp stays the recommendation for
+    production use.
+
+    vllm.cpp is an Apache-2.0 C++20 inference engine maintained by the LocalAI team,
+    developed in its own repository and usable without LocalAI. It began as a port of
+    vLLM and keeps vLLM as its reference implementation, checking output against it and
+    benchmarking against it, while growing a featureset of its own. It implements vLLM's
+    V1 architecture (paged KV cache, continuous batching, prefix caching, scheduler,
+    sampler) on a portable tensor runtime with no Python, PyTorch or ggml at inference
+    time. It loads GGUF as well as Hugging Face safetensors, supports structured output
+    (JSON schema / regex / choice / GBNF grammar) enforced in-engine, ships speculative
+    decoding and KV offload, and runs on CPU, NVIDIA CUDA (Blackwell-family), Apple
+    Metal and Vulkan.
+
+    The project is expected to be renamed as it diverges further from vLLM; the new
+    name is still to be decided.
+  id: vllm-cpp-development
+  kind: backend
+  license: apache-2.0
+  name: vllm-cpp-development
+  schemaVersion: 1
+  tags:
+    - text-to-text
+    - LLM
+    - CPU
+    - GPU
+    - CUDA
+    - metal
+  urls:
+    - https://github.com/mudler/vllm.cpp
+  version: 0.0.0-development

core/gallery/testdata/backend_library/samples/meta.gallery.yaml

@@ -0,0 +1,30 @@
+- name: llama-cpp
+  alias: llama-cpp
+  license: mit
+  icon: https://user-images.githubusercontent.com/1991296/230134379-7181e485-c521-4d23-a0d6-f7b3b61ba524.png
+  description: |
+    LLM inference in C/C++
+  urls:
+    - https://github.com/ggerganov/llama.cpp
+  tags:
+    - text-to-text
+    - text-to-speech
+    - TTS
+    - LLM
+    - CPU
+    - GPU
+    - Metal
+    - CUDA
+    - HIP
+  capabilities:
+    amd: rocm-llama-cpp
+    default: cpu-llama-cpp
+    intel: intel-sycl-f16-llama-cpp
+    metal: metal-llama-cpp
+    nvidia: cuda12-llama-cpp
+    nvidia-cuda-12: cuda12-llama-cpp
+    nvidia-cuda-13: cuda13-llama-cpp
+    nvidia-l4t: nvidia-l4t-arm64-llama-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-llama-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-llama-cpp
+    vulkan: vulkan-llama-cpp

core/gallery/testdata/backend_library/samples/meta.library.yaml

@@ -0,0 +1,35 @@
+- alias: llama-cpp
+  capabilities:
+    amd: rocm-llama-cpp
+    default: cpu-llama-cpp
+    intel: intel-sycl-f16-llama-cpp
+    metal: metal-llama-cpp
+    nvidia: cuda12-llama-cpp
+    nvidia-cuda-12: cuda12-llama-cpp
+    nvidia-cuda-13: cuda13-llama-cpp
+    nvidia-l4t: nvidia-l4t-arm64-llama-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-llama-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-llama-cpp
+    vulkan: vulkan-llama-cpp
+  channel: latest
+  description: |
+    LLM inference in C/C++
+  icon: https://user-images.githubusercontent.com/1991296/230134379-7181e485-c521-4d23-a0d6-f7b3b61ba524.png
+  id: llama-cpp
+  kind: backend
+  license: mit
+  name: llama-cpp
+  schemaVersion: 1
+  tags:
+    - text-to-text
+    - text-to-speech
+    - TTS
+    - LLM
+    - CPU
+    - GPU
+    - Metal
+    - CUDA
+    - HIP
+  urls:
+    - https://github.com/ggerganov/llama.cpp
+  version: 0.0.0-latest

core/gallery/testdata/backend_library/samples/multi-platform.gallery.yaml

@@ -0,0 +1,32 @@
+- name: vulkan-locate-anything-cpp
+  alias: locate-anything
+  license: apache-2.0
+  description: |
+    Open-vocabulary object detection and visual grounding (NVIDIA
+    LocateAnything-3B) in C/C++ using GGML. Loads pre-built GGUF weights
+    and, given an image and a free-form text prompt, returns bounding
+    boxes, class labels, and confidence scores for the referred objects.
+  urls:
+    - https://github.com/mudler/locate-anything.cpp
+    - https://huggingface.co/nvidia/LocateAnything-3B
+  tags:
+    - object-detection
+    - visual-grounding
+    - open-vocabulary
+    - locate-anything
+    - gpu
+    - cpu
+  capabilities:
+    default: cpu-locate-anything-cpp
+    intel: intel-sycl-f32-locate-anything-cpp
+    metal: metal-locate-anything-cpp
+    nvidia: cuda12-locate-anything-cpp
+    nvidia-cuda-12: cuda12-locate-anything-cpp
+    nvidia-cuda-13: cuda13-locate-anything-cpp
+    nvidia-l4t: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-locate-anything-cpp
+    vulkan: vulkan-locate-anything-cpp
+  uri: quay.io/go-skynet/local-ai-backends:latest-gpu-vulkan-locate-anything-cpp
+  mirrors:
+    - localai/localai-backends:latest-gpu-vulkan-locate-anything-cpp

core/gallery/testdata/backend_library/samples/multi-platform.library.yaml

@@ -0,0 +1,80 @@
+- alias: locate-anything
+  arch: amd64
+  artifact: oci://quay.io/go-skynet/local-ai-backends:latest-gpu-vulkan-locate-anything-cpp
+  capabilities:
+    default: cpu-locate-anything-cpp
+    intel: intel-sycl-f32-locate-anything-cpp
+    metal: metal-locate-anything-cpp
+    nvidia: cuda12-locate-anything-cpp
+    nvidia-cuda-12: cuda12-locate-anything-cpp
+    nvidia-cuda-13: cuda13-locate-anything-cpp
+    nvidia-l4t: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-locate-anything-cpp
+    vulkan: vulkan-locate-anything-cpp
+  channel: latest
+  description: |
+    Open-vocabulary object detection and visual grounding (NVIDIA
+    LocateAnything-3B) in C/C++ using GGML. Loads pre-built GGUF weights
+    and, given an image and a free-form text prompt, returns bounding
+    boxes, class labels, and confidence scores for the referred objects.
+  digest: sha256:856873f7908e97b4548c991b5970fe35935cf4189f4597b993844c4ee1a651c6
+  id: vulkan-locate-anything-cpp
+  kind: backend
+  license: apache-2.0
+  mirrors:
+    - oci://localai/localai-backends:latest-gpu-vulkan-locate-anything-cpp
+  name: vulkan-locate-anything-cpp
+  os: linux
+  schemaVersion: 1
+  tags:
+    - object-detection
+    - visual-grounding
+    - open-vocabulary
+    - locate-anything
+    - gpu
+    - cpu
+  urls:
+    - https://github.com/mudler/locate-anything.cpp
+    - https://huggingface.co/nvidia/LocateAnything-3B
+  version: 0.0.0-latest.856873f7908e
+- alias: locate-anything
+  arch: arm64
+  artifact: oci://quay.io/go-skynet/local-ai-backends:latest-gpu-vulkan-locate-anything-cpp
+  capabilities:
+    default: cpu-locate-anything-cpp
+    intel: intel-sycl-f32-locate-anything-cpp
+    metal: metal-locate-anything-cpp
+    nvidia: cuda12-locate-anything-cpp
+    nvidia-cuda-12: cuda12-locate-anything-cpp
+    nvidia-cuda-13: cuda13-locate-anything-cpp
+    nvidia-l4t: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-locate-anything-cpp
+    vulkan: vulkan-locate-anything-cpp
+  channel: latest
+  description: |
+    Open-vocabulary object detection and visual grounding (NVIDIA
+    LocateAnything-3B) in C/C++ using GGML. Loads pre-built GGUF weights
+    and, given an image and a free-form text prompt, returns bounding
+    boxes, class labels, and confidence scores for the referred objects.
+  digest: sha256:9e9d13626573ee32c132f2511d22c0cb7ac129ca9205d31ceb60b70dcf3b4523
+  id: vulkan-locate-anything-cpp
+  kind: backend
+  license: apache-2.0
+  mirrors:
+    - oci://localai/localai-backends:latest-gpu-vulkan-locate-anything-cpp
+  name: vulkan-locate-anything-cpp
+  os: linux
+  schemaVersion: 1
+  tags:
+    - object-detection
+    - visual-grounding
+    - open-vocabulary
+    - locate-anything
+    - gpu
+    - cpu
+  urls:
+    - https://github.com/mudler/locate-anything.cpp
+    - https://huggingface.co/nvidia/LocateAnything-3B
+  version: 0.0.0-latest.9e9d13626573

core/gallery/testdata/backend_library/samples/multiline-description.gallery.yaml

@@ -0,0 +1,28 @@
+- name: turboquant
+  alias: turboquant
+  license: mit
+  description: |
+    Fork of llama.cpp adding the TurboQuant KV-cache quantization scheme.
+    Reuses the LocalAI llama.cpp gRPC server sources against the fork's libllama.
+  urls:
+    - https://github.com/TheTom/llama-cpp-turboquant
+  tags:
+    - text-to-text
+    - LLM
+    - CPU
+    - GPU
+    - CUDA
+    - HIP
+    - turboquant
+    - kv-cache
+  capabilities:
+    amd: rocm-turboquant
+    default: cpu-turboquant
+    intel: intel-sycl-f16-turboquant
+    nvidia: cuda12-turboquant
+    nvidia-cuda-12: cuda12-turboquant
+    nvidia-cuda-13: cuda13-turboquant
+    nvidia-l4t: nvidia-l4t-arm64-turboquant
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-turboquant
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-turboquant
+    vulkan: vulkan-turboquant

core/gallery/testdata/backend_library/samples/multiline-description.library.yaml

@@ -0,0 +1,33 @@
+- alias: turboquant
+  capabilities:
+    amd: rocm-turboquant
+    default: cpu-turboquant
+    intel: intel-sycl-f16-turboquant
+    nvidia: cuda12-turboquant
+    nvidia-cuda-12: cuda12-turboquant
+    nvidia-cuda-13: cuda13-turboquant
+    nvidia-l4t: nvidia-l4t-arm64-turboquant
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-turboquant
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-turboquant
+    vulkan: vulkan-turboquant
+  channel: latest
+  description: |
+    Fork of llama.cpp adding the TurboQuant KV-cache quantization scheme.
+    Reuses the LocalAI llama.cpp gRPC server sources against the fork's libllama.
+  id: turboquant
+  kind: backend
+  license: mit
+  name: turboquant
+  schemaVersion: 1
+  tags:
+    - text-to-text
+    - LLM
+    - CPU
+    - GPU
+    - CUDA
+    - HIP
+    - turboquant
+    - kv-cache
+  urls:
+    - https://github.com/TheTom/llama-cpp-turboquant
+  version: 0.0.0-latest

core/gallery/testdata/backend_library/samples/no-description.gallery.yaml

@@ -0,0 +1,7 @@
+- name: rerankers
+  alias: rerankers
+  capabilities:
+    amd: rocm-rerankers
+    intel: intel-rerankers
+    metal: metal-rerankers
+    nvidia: cuda12-rerankers

core/gallery/testdata/backend_library/samples/no-description.library.yaml

@@ -0,0 +1,12 @@
+- alias: rerankers
+  capabilities:
+    amd: rocm-rerankers
+    intel: intel-rerankers
+    metal: metal-rerankers
+    nvidia: cuda12-rerankers
+  channel: latest
+  id: rerankers
+  kind: backend
+  name: rerankers
+  schemaVersion: 1
+  version: 0.0.0-latest

core/gallery/testdata/backend_library/samples/no-icon.gallery.yaml

@@ -0,0 +1,32 @@
+- name: cpu-locate-anything-cpp
+  alias: locate-anything
+  license: apache-2.0
+  description: |
+    Open-vocabulary object detection and visual grounding (NVIDIA
+    LocateAnything-3B) in C/C++ using GGML. Loads pre-built GGUF weights
+    and, given an image and a free-form text prompt, returns bounding
+    boxes, class labels, and confidence scores for the referred objects.
+  urls:
+    - https://github.com/mudler/locate-anything.cpp
+    - https://huggingface.co/nvidia/LocateAnything-3B
+  tags:
+    - object-detection
+    - visual-grounding
+    - open-vocabulary
+    - locate-anything
+    - gpu
+    - cpu
+  capabilities:
+    default: cpu-locate-anything-cpp
+    intel: intel-sycl-f32-locate-anything-cpp
+    metal: metal-locate-anything-cpp
+    nvidia: cuda12-locate-anything-cpp
+    nvidia-cuda-12: cuda12-locate-anything-cpp
+    nvidia-cuda-13: cuda13-locate-anything-cpp
+    nvidia-l4t: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-locate-anything-cpp
+    vulkan: vulkan-locate-anything-cpp
+  uri: quay.io/go-skynet/local-ai-backends:latest-cpu-locate-anything-cpp
+  mirrors:
+    - localai/localai-backends:latest-cpu-locate-anything-cpp

core/gallery/testdata/backend_library/samples/no-icon.library.yaml

@@ -0,0 +1,40 @@
+- alias: locate-anything
+  arch: amd64
+  artifact: oci://quay.io/go-skynet/local-ai-backends:latest-cpu-locate-anything-cpp
+  capabilities:
+    default: cpu-locate-anything-cpp
+    intel: intel-sycl-f32-locate-anything-cpp
+    metal: metal-locate-anything-cpp
+    nvidia: cuda12-locate-anything-cpp
+    nvidia-cuda-12: cuda12-locate-anything-cpp
+    nvidia-cuda-13: cuda13-locate-anything-cpp
+    nvidia-l4t: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-locate-anything-cpp
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-locate-anything-cpp
+    vulkan: vulkan-locate-anything-cpp
+  channel: latest
+  description: |
+    Open-vocabulary object detection and visual grounding (NVIDIA
+    LocateAnything-3B) in C/C++ using GGML. Loads pre-built GGUF weights
+    and, given an image and a free-form text prompt, returns bounding
+    boxes, class labels, and confidence scores for the referred objects.
+  digest: sha256:acb078c58ac5e78485e7254fd8f040ba901255f118edf3d8f881bfbd7384b673
+  id: cpu-locate-anything-cpp
+  kind: backend
+  license: apache-2.0
+  mirrors:
+    - oci://localai/localai-backends:latest-cpu-locate-anything-cpp
+  name: cpu-locate-anything-cpp
+  os: linux
+  schemaVersion: 1
+  tags:
+    - object-detection
+    - visual-grounding
+    - open-vocabulary
+    - locate-anything
+    - gpu
+    - cpu
+  urls:
+    - https://github.com/mudler/locate-anything.cpp
+    - https://huggingface.co/nvidia/LocateAnything-3B
+  version: 0.0.0-latest.acb078c58ac5

core/gallery/testdata/backend_library/samples/no-mirrors.gallery.yaml

@@ -0,0 +1,28 @@
+- name: intel-sycl-f32-stablediffusion-ggml
+  alias: stablediffusion-ggml
+  license: mit
+  icon: https://github.com/leejet/stable-diffusion.cpp/raw/master/assets/cat_with_sd_cpp_42.png
+  description: |
+    Stable Diffusion and Flux in pure C/C++
+  urls:
+    - https://github.com/leejet/stable-diffusion.cpp
+  tags:
+    - image-generation
+    - CPU
+    - GPU
+    - Metal
+    - CUDA
+    - HIP
+  capabilities:
+    amd: rocm-stablediffusion-ggml
+    default: cpu-stablediffusion-ggml
+    intel: intel-sycl-f16-stablediffusion-ggml
+    metal: metal-stablediffusion-ggml
+    nvidia: cuda12-stablediffusion-ggml
+    nvidia-cuda-12: cuda12-stablediffusion-ggml
+    nvidia-cuda-13: cuda13-stablediffusion-ggml
+    nvidia-l4t: nvidia-l4t-arm64-stablediffusion-ggml
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-stablediffusion-ggml
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-stablediffusion-ggml
+    vulkan: vulkan-stablediffusion-ggml
+  uri: quay.io/go-skynet/local-ai-backends:latest-gpu-intel-sycl-f32-stablediffusion-ggml

core/gallery/testdata/backend_library/samples/no-mirrors.library.yaml

@@ -0,0 +1,36 @@
+- alias: stablediffusion-ggml
+  arch: amd64
+  artifact: oci://quay.io/go-skynet/local-ai-backends:latest-gpu-intel-sycl-f32-stablediffusion-ggml
+  capabilities:
+    amd: rocm-stablediffusion-ggml
+    default: cpu-stablediffusion-ggml
+    intel: intel-sycl-f16-stablediffusion-ggml
+    metal: metal-stablediffusion-ggml
+    nvidia: cuda12-stablediffusion-ggml
+    nvidia-cuda-12: cuda12-stablediffusion-ggml
+    nvidia-cuda-13: cuda13-stablediffusion-ggml
+    nvidia-l4t: nvidia-l4t-arm64-stablediffusion-ggml
+    nvidia-l4t-cuda-12: nvidia-l4t-arm64-stablediffusion-ggml
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-stablediffusion-ggml
+    vulkan: vulkan-stablediffusion-ggml
+  channel: latest
+  description: |
+    Stable Diffusion and Flux in pure C/C++
+  digest: sha256:b3e306c0b628e830ae92c94f50afb9aebe48186a0c42ab68858c6a3afc1b9984
+  icon: https://github.com/leejet/stable-diffusion.cpp/raw/master/assets/cat_with_sd_cpp_42.png
+  id: intel-sycl-f32-stablediffusion-ggml
+  kind: backend
+  license: mit
+  name: intel-sycl-f32-stablediffusion-ggml
+  os: linux
+  schemaVersion: 1
+  tags:
+    - image-generation
+    - CPU
+    - GPU
+    - Metal
+    - CUDA
+    - HIP
+  urls:
+    - https://github.com/leejet/stable-diffusion.cpp
+  version: 0.0.0-latest.b3e306c0b628

core/gallery/testdata/backend_library/samples/release.gallery.yaml

@@ -0,0 +1,23 @@
+- name: metal-mlx
+  license: MIT
+  icon: https://avatars.githubusercontent.com/u/102832242?s=200&v=4
+  description: |
+    Run LLMs with MLX
+  urls:
+    - https://github.com/ml-explore/mlx-lm
+  tags:
+    - text-to-text
+    - LLM
+    - MLX
+  capabilities:
+    default: cpu-mlx
+    metal: metal-mlx
+    nvidia: cuda12-mlx
+    nvidia-cuda-12: cuda12-mlx
+    nvidia-cuda-13: cuda13-mlx
+    nvidia-l4t: nvidia-l4t-mlx
+    nvidia-l4t-cuda-12: nvidia-l4t-mlx
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-mlx
+  uri: quay.io/go-skynet/local-ai-backends:latest-metal-darwin-arm64-mlx
+  mirrors:
+    - localai/localai-backends:latest-metal-darwin-arm64-mlx

core/gallery/testdata/backend_library/samples/release.library.yaml

@@ -0,0 +1,31 @@
+- arch: arm64
+  artifact: oci://quay.io/go-skynet/local-ai-backends:latest-metal-darwin-arm64-mlx
+  capabilities:
+    default: cpu-mlx
+    metal: metal-mlx
+    nvidia: cuda12-mlx
+    nvidia-cuda-12: cuda12-mlx
+    nvidia-cuda-13: cuda13-mlx
+    nvidia-l4t: nvidia-l4t-mlx
+    nvidia-l4t-cuda-12: nvidia-l4t-mlx
+    nvidia-l4t-cuda-13: cuda13-nvidia-l4t-arm64-mlx
+  channel: latest
+  description: |
+    Run LLMs with MLX
+  digest: sha256:79efa3f8b96d1df41efbc75fbaa7f1e496b811ff4025a164307e0da185b46b90
+  icon: https://avatars.githubusercontent.com/u/102832242?s=200&v=4
+  id: metal-mlx
+  kind: backend
+  license: MIT
+  mirrors:
+    - oci://localai/localai-backends:latest-metal-darwin-arm64-mlx
+  name: metal-mlx
+  os: darwin
+  schemaVersion: 1
+  tags:
+    - text-to-text
+    - LLM
+    - MLX
+  urls:
+    - https://github.com/ml-explore/mlx-lm
+  version: 0.0.0-latest.79efa3f8b96d

core/gallery/testdata/model_library/samples/backend.gallery.yaml

@@ -0,0 +1,44 @@
+- url: github:mudler/LocalAI/gallery/kimodocpp.yaml@master
+  name: kimodo-soma-rp
+  description: |
+    Kimodo SOMA RP v1.1 text-to-motion on CPU or Vulkan, with F32 motion weights
+    and the shared monolithic Q8_0 Llama-3/LLM2Vec text encoder.
+    Exports an animated skeleton GLB without a mesh or skin. Motion and text
+    weights retain their respective NVIDIA Open Model License and Llama 3 terms.
+  urls:
+    - https://huggingface.co/LocalAI-io/Kimodo-SOMA-RP-v1.1-GGML
+    - https://huggingface.co/nvidia/Kimodo-SOMA-RP-v1.1
+    - https://huggingface.co/LocalAI-io/Llama-3-Kimodo-GGML
+  tags:
+    - 3d_animation
+    - text-to-motion
+    - gguf
+    - cpu
+    - vulkan
+    - kimodo
+    - q8_0
+  files:
+    - filename: kimodo/kimodo-soma-rp-v1.1-f32.gguf
+      sha256: 3bf1229f4c1eff1d28f5196a854113da2df9a11a5e21c60694630903bf948ee4
+      uri: https://huggingface.co/LocalAI-io/Kimodo-SOMA-RP-v1.1-GGML/resolve/65f8b8ab34ee7524161cc87b20ae4cb4f5d3a12d/models/kimodo-soma-rp-v1.1-f32.gguf
+    - filename: kimodo/text/tokenizer.gguf
+      sha256: 81614aca62a98846c02b72cc2e5378e5bdce8b4d507b88f96eb1faa90dae607e
+      uri: https://huggingface.co/LocalAI-io/Llama-3-Kimodo-GGML/resolve/3e8d958803beaddb6011ac534f2be972e2710c7d/tokenizer.gguf
+    - filename: kimodo/text/Llama-3-Kimodo-Q8_0.gguf
+      sha256: b26d0e74b115b33a7f2df5aca04426548365e99217cd590986f8abc4172e4c5c
+      uri: https://huggingface.co/LocalAI-io/Llama-3-Kimodo-GGML/resolve/3e8d958803beaddb6011ac534f2be972e2710c7d/Llama-3-Kimodo-Q8_0.gguf
+  backend: kimodocpp
+  overrides:
+    options:
+      - text_bundle:kimodo/text/Llama-3-Kimodo-Q8_0.gguf
+      - frames:150
+      - steps:100
+      - text_guidance:2
+    parameters:
+      model: kimodo/kimodo-soma-rp-v1.1-f32.gguf
+  variants:
+    - model: kimodo-soma-rp-bf16
+    - model: kimodo-soma-rp-q4_k
+    - model: kimodo-soma-rp-q4_k_m
+    - model: kimodo-soma-rp-q5_k
+    - model: kimodo-soma-rp-q6_k

core/gallery/testdata/model_library/samples/backend.library.yaml

@@ -0,0 +1,52 @@
+- kind: model
+  id: kimodo-soma-rp
+  name: kimodo-soma-rp
+  version: 0.0.0-gallery.dc25d437ae9e
+  description: |
+    Kimodo SOMA RP v1.1 text-to-motion on CPU or Vulkan, with F32 motion weights
+    and the shared monolithic Q8_0 Llama-3/LLM2Vec text encoder.
+    Exports an animated skeleton GLB without a mesh or skin. Motion and text
+    weights retain their respective NVIDIA Open Model License and Llama 3 terms.
+  urls:
+    - https://huggingface.co/LocalAI-io/Kimodo-SOMA-RP-v1.1-GGML
+    - https://huggingface.co/nvidia/Kimodo-SOMA-RP-v1.1
+    - https://huggingface.co/LocalAI-io/Llama-3-Kimodo-GGML
+  tags:
+    - 3d_animation
+    - text-to-motion
+    - gguf
+    - cpu
+    - vulkan
+    - kimodo
+    - q8_0
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    url: github:mudler/LocalAI/gallery/kimodocpp.yaml@master
+    backend: kimodocpp
+    files:
+      - filename: kimodo/kimodo-soma-rp-v1.1-f32.gguf
+        sha256: 3bf1229f4c1eff1d28f5196a854113da2df9a11a5e21c60694630903bf948ee4
+        uri: https://huggingface.co/LocalAI-io/Kimodo-SOMA-RP-v1.1-GGML/resolve/65f8b8ab34ee7524161cc87b20ae4cb4f5d3a12d/models/kimodo-soma-rp-v1.1-f32.gguf
+      - filename: kimodo/text/tokenizer.gguf
+        sha256: 81614aca62a98846c02b72cc2e5378e5bdce8b4d507b88f96eb1faa90dae607e
+        uri: https://huggingface.co/LocalAI-io/Llama-3-Kimodo-GGML/resolve/3e8d958803beaddb6011ac534f2be972e2710c7d/tokenizer.gguf
+      - filename: kimodo/text/Llama-3-Kimodo-Q8_0.gguf
+        sha256: b26d0e74b115b33a7f2df5aca04426548365e99217cd590986f8abc4172e4c5c
+        uri: https://huggingface.co/LocalAI-io/Llama-3-Kimodo-GGML/resolve/3e8d958803beaddb6011ac534f2be972e2710c7d/Llama-3-Kimodo-Q8_0.gguf
+    overrides:
+      options:
+        - text_bundle:kimodo/text/Llama-3-Kimodo-Q8_0.gguf
+        - frames:150
+        - steps:100
+        - text_guidance:2
+      parameters:
+        model: kimodo/kimodo-soma-rp-v1.1-f32.gguf
+    variants:
+      - model: kimodo-soma-rp-bf16
+      - model: kimodo-soma-rp-q4_k
+      - model: kimodo-soma-rp-q4_k_m
+      - model: kimodo-soma-rp-q5_k
+      - model: kimodo-soma-rp-q6_k

core/gallery/testdata/model_library/samples/config-file.gallery.yaml

@@ -0,0 +1,31 @@
+- name: vits-streaming-assistant
+  description: |
+    English voice assistant preset: Silero VAD, Parakeet TDT 0.6B v3, Qwen3
+    0.6B chat, and VITS-LJS English single-speaker TTS through sherpa-onnx.
+    Buffers streamed LLM output into clauses and emits audio progressively.
+    Each clause starts a separate synthesis; this is not native incremental
+    text input. This installs only the pipeline configuration. First install
+    silero-vad-ggml, parakeet-cpp-tdt-0.6b-v3, qwen3-0.6b, and vits-ljs-sherpa.
+    WebRTC also needs the opus backend. No browser or hardware performance
+    is established by this preset.
+  license: mit
+  urls:
+    - https://localai.io/features/openai-realtime/
+  tags:
+    - voice-assistant
+    - audio-pipeline
+    - realtime
+    - streaming
+    - english
+    - sherpa-onnx
+  config_file:
+    pipeline:
+      disable_thinking: true
+      llm: qwen3-0.6b
+      streaming:
+        clause_chunking: true
+        llm: true
+        tts: true
+      transcription: parakeet-cpp-tdt-0.6b-v3
+      tts: vits-ljs-sherpa
+      vad: silero-vad-ggml

core/gallery/testdata/model_library/samples/config-file.library.yaml

@@ -0,0 +1,39 @@
+- kind: model
+  id: vits-streaming-assistant
+  name: vits-streaming-assistant
+  version: 0.0.0-gallery.2adda7a87e2f
+  description: |
+    English voice assistant preset: Silero VAD, Parakeet TDT 0.6B v3, Qwen3
+    0.6B chat, and VITS-LJS English single-speaker TTS through sherpa-onnx.
+    Buffers streamed LLM output into clauses and emits audio progressively.
+    Each clause starts a separate synthesis; this is not native incremental
+    text input. This installs only the pipeline configuration. First install
+    silero-vad-ggml, parakeet-cpp-tdt-0.6b-v3, qwen3-0.6b, and vits-ljs-sherpa.
+    WebRTC also needs the opus backend. No browser or hardware performance
+    is established by this preset.
+  license: mit
+  urls:
+    - https://localai.io/features/openai-realtime/
+  tags:
+    - voice-assistant
+    - audio-pipeline
+    - realtime
+    - streaming
+    - english
+    - sherpa-onnx
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    configFile:
+      pipeline:
+        disable_thinking: true
+        llm: qwen3-0.6b
+        streaming:
+          clause_chunking: true
+          llm: true
+          tts: true
+        transcription: parakeet-cpp-tdt-0.6b-v3
+        tts: vits-ljs-sherpa
+        vad: silero-vad-ggml

core/gallery/testdata/model_library/samples/empty-variants.gallery.yaml

@@ -0,0 +1,56 @@
+- url: github:mudler/LocalAI/gallery/virtual.yaml@master
+  name: apodex-1.1-mini-q4-mtp
+  description: |
+    Apodex-1.1-mini with MTP speculative decoding enabled on the recommended
+    Q4_K_M GGUF. The model carries its native MTP head, so it needs no separate
+    draft model. The F16 vision projector supports multimodal prompts.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/apodex/Apodex-1.1-mini
+    - https://huggingface.co/abenzerps/Apodex-1.1-mini-GGUF
+  tags:
+    - llm
+    - gguf
+    - cpu
+    - gpu
+    - qwen
+    - moe
+    - reasoning
+    - thinking
+    - coding
+    - agent
+    - tools
+    - vision
+    - multimodal
+    - long-context
+    - mtp
+  files:
+    - filename: llama-cpp/models/apodex-1.1-mini/Apodex-1.1-mini-Q4_K_M.gguf
+      sha256: 13a580b1ab9350b90085c221cf66e8715a594b2428e5a80a7a956d8e0420be16
+      uri: huggingface://abenzerps/Apodex-1.1-mini-GGUF/Apodex-1.1-mini-Q4_K_M.gguf
+    - filename: llama-cpp/mmproj/apodex-1.1-mini/mmproj-F16.gguf
+      sha256: d0ccf814138020651bcab603d9ce5c080a0ada46f482c116f0aca0fbb84e091e
+      uri: huggingface://abenzerps/Apodex-1.1-mini-GGUF/mmproj-Apodex-1.1-mini-F16.gguf
+  overrides:
+    backend: llama-cpp
+    context_size: 262144
+    function:
+      automatic_tool_parsing_fallback: true
+      grammar:
+        disable: true
+    known_usecases:
+      - chat
+      - vision
+    mmproj: llama-cpp/mmproj/apodex-1.1-mini/mmproj-F16.gguf
+    options:
+      - use_jinja:true
+      - spec_type:draft-mtp
+      - spec_n_max:3
+    parameters:
+      model: llama-cpp/models/apodex-1.1-mini/Apodex-1.1-mini-Q4_K_M.gguf
+      repeat_penalty: 1.05
+      temperature: 1
+      top_p: 0.95
+    template:
+      use_tokenizer_template: true
+  variants: []

core/gallery/testdata/model_library/samples/empty-variants.library.yaml

@@ -0,0 +1,64 @@
+- kind: model
+  id: apodex-1.1-mini-q4-mtp
+  name: apodex-1.1-mini-q4-mtp
+  version: 0.0.0-gallery.d6c37c37d4f9
+  description: |
+    Apodex-1.1-mini with MTP speculative decoding enabled on the recommended
+    Q4_K_M GGUF. The model carries its native MTP head, so it needs no separate
+    draft model. The F16 vision projector supports multimodal prompts.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/apodex/Apodex-1.1-mini
+    - https://huggingface.co/abenzerps/Apodex-1.1-mini-GGUF
+  tags:
+    - llm
+    - gguf
+    - cpu
+    - gpu
+    - qwen
+    - moe
+    - reasoning
+    - thinking
+    - coding
+    - agent
+    - tools
+    - vision
+    - multimodal
+    - long-context
+    - mtp
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    url: github:mudler/LocalAI/gallery/virtual.yaml@master
+    files:
+      - filename: llama-cpp/models/apodex-1.1-mini/Apodex-1.1-mini-Q4_K_M.gguf
+        sha256: 13a580b1ab9350b90085c221cf66e8715a594b2428e5a80a7a956d8e0420be16
+        uri: huggingface://abenzerps/Apodex-1.1-mini-GGUF/Apodex-1.1-mini-Q4_K_M.gguf
+      - filename: llama-cpp/mmproj/apodex-1.1-mini/mmproj-F16.gguf
+        sha256: d0ccf814138020651bcab603d9ce5c080a0ada46f482c116f0aca0fbb84e091e
+        uri: huggingface://abenzerps/Apodex-1.1-mini-GGUF/mmproj-Apodex-1.1-mini-F16.gguf
+    overrides:
+      backend: llama-cpp
+      context_size: 262144
+      function:
+        automatic_tool_parsing_fallback: true
+        grammar:
+          disable: true
+      known_usecases:
+        - chat
+        - vision
+      mmproj: llama-cpp/mmproj/apodex-1.1-mini/mmproj-F16.gguf
+      options:
+        - use_jinja:true
+        - spec_type:draft-mtp
+        - spec_n_max:3
+      parameters:
+        model: llama-cpp/models/apodex-1.1-mini/Apodex-1.1-mini-Q4_K_M.gguf
+        repeat_penalty: 1.05
+        temperature: 1
+        top_p: 0.95
+      template:
+        use_tokenizer_template: true
+    variants: []

core/gallery/testdata/model_library/samples/float-override.gallery.yaml

@@ -0,0 +1,48 @@
+- url: github:mudler/LocalAI/gallery/virtual.yaml@master
+  name: thinkingcap-qwen3.8-27b
+  description: |
+    ThinkingCap is a 27B Qwen3.8 fine-tune trained to reduce reasoning tokens, with text and image input.
+    This Q4_K_M GGUF build uses llama.cpp, the embedded chat template, and the F16 vision projector.
+    Licensed under PolyForm Small Business 1.0.0 with the publisher's personal-use grant; see the model license for permitted use.
+  license: polyform-small-business-1.0.0
+  urls:
+    - https://huggingface.co/bottlecapai/ThinkingCap-Qwen3.8-27B
+    - https://huggingface.co/bottlecapai/ThinkingCap-Qwen3.8-27B-GGUF
+  tags:
+    - llm
+    - gguf
+    - cpu
+    - gpu
+    - vision
+    - multimodal
+    - reasoning
+  files:
+    - filename: ThinkingCap-Qwen3.8-27B-Q4_K_M.gguf
+      sha256: fafa890ce2ce8531b4ade225c7dbd5f5d72a92303ca9ef72890c6cf78f19f299
+      uri: https://huggingface.co/bottlecapai/ThinkingCap-Qwen3.8-27B-GGUF/resolve/108ff8f24ce8e9335fbf308844cd3c59c13380a4/ThinkingCap-Qwen3.8-27B-Q4_K_M.gguf
+    - filename: mmproj-ThinkingCap-Qwen3.8-27B-f16.gguf
+      sha256: 98fa9aad59b42449786a16bbce96bcd92204d03cac0aee0cdccca711c2adefd1
+      uri: https://huggingface.co/bottlecapai/ThinkingCap-Qwen3.8-27B-GGUF/resolve/108ff8f24ce8e9335fbf308844cd3c59c13380a4/mmproj-ThinkingCap-Qwen3.8-27B-f16.gguf
+  overrides:
+    backend: llama-cpp
+    context_size: 32768
+    function:
+      automatic_tool_parsing_fallback: true
+      grammar:
+        disable: true
+    known_usecases:
+      - chat
+      - vision
+    mmproj: mmproj-ThinkingCap-Qwen3.8-27B-f16.gguf
+    options:
+      - use_jinja:true
+    parameters:
+      min_p: 0.0
+      model: ThinkingCap-Qwen3.8-27B-Q4_K_M.gguf
+      temperature: 1.0
+      top_k: 20
+      top_p: 0.95
+    template:
+      use_tokenizer_template: true
+  variants:
+    - model: thinkingcap-qwen3.8-27b-q8

core/gallery/testdata/model_library/samples/float-override.library.yaml

@@ -0,0 +1,56 @@
+- kind: model
+  id: thinkingcap-qwen3.8-27b
+  name: thinkingcap-qwen3.8-27b
+  version: 0.0.0-gallery.741204929f7a
+  description: |
+    ThinkingCap is a 27B Qwen3.8 fine-tune trained to reduce reasoning tokens, with text and image input.
+    This Q4_K_M GGUF build uses llama.cpp, the embedded chat template, and the F16 vision projector.
+    Licensed under PolyForm Small Business 1.0.0 with the publisher's personal-use grant; see the model license for permitted use.
+  license: polyform-small-business-1.0.0
+  urls:
+    - https://huggingface.co/bottlecapai/ThinkingCap-Qwen3.8-27B
+    - https://huggingface.co/bottlecapai/ThinkingCap-Qwen3.8-27B-GGUF
+  tags:
+    - llm
+    - gguf
+    - cpu
+    - gpu
+    - vision
+    - multimodal
+    - reasoning
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    url: github:mudler/LocalAI/gallery/virtual.yaml@master
+    files:
+      - filename: ThinkingCap-Qwen3.8-27B-Q4_K_M.gguf
+        sha256: fafa890ce2ce8531b4ade225c7dbd5f5d72a92303ca9ef72890c6cf78f19f299
+        uri: https://huggingface.co/bottlecapai/ThinkingCap-Qwen3.8-27B-GGUF/resolve/108ff8f24ce8e9335fbf308844cd3c59c13380a4/ThinkingCap-Qwen3.8-27B-Q4_K_M.gguf
+      - filename: mmproj-ThinkingCap-Qwen3.8-27B-f16.gguf
+        sha256: 98fa9aad59b42449786a16bbce96bcd92204d03cac0aee0cdccca711c2adefd1
+        uri: https://huggingface.co/bottlecapai/ThinkingCap-Qwen3.8-27B-GGUF/resolve/108ff8f24ce8e9335fbf308844cd3c59c13380a4/mmproj-ThinkingCap-Qwen3.8-27B-f16.gguf
+    overrides:
+      backend: llama-cpp
+      context_size: 32768
+      function:
+        automatic_tool_parsing_fallback: true
+        grammar:
+          disable: true
+      known_usecases:
+        - chat
+        - vision
+      mmproj: mmproj-ThinkingCap-Qwen3.8-27B-f16.gguf
+      options:
+        - use_jinja:true
+      parameters:
+        min_p: 0.0
+        model: ThinkingCap-Qwen3.8-27B-Q4_K_M.gguf
+        temperature: 1.0
+        top_k: 20
+        top_p: 0.95
+      template:
+        use_tokenizer_template: true
+    variants:
+      - model: thinkingcap-qwen3.8-27b-q8

core/gallery/testdata/model_library/samples/multiline-description.gallery.yaml

@@ -0,0 +1,38 @@
+- url: github:mudler/LocalAI/gallery/virtual.yaml@master
+  name: adavar-3b-q8
+  description: |
+    AdaVaR-3B is a Qwen2.5-VL-3B-Instruct fine-tune for visual reasoning
+    through text or image-grounded coordinates. This Q8_0 GGUF build
+    includes the F16 vision projector. Adaptive reasoning uses the publisher's
+    system prompt and question suffix; see the model card for these prompts.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/ZejunLi/AdaVaR-3B
+    - https://huggingface.co/mradermacher/AdaVaR-3B-GGUF
+  tags:
+    - llm
+    - gguf
+    - vision
+    - reasoning
+    - cpu
+    - gpu
+  files:
+    - filename: AdaVaR-3B.Q8_0.gguf
+      sha256: 23495169a352b076dee53ffb74da1861b3f9670c7a081cbecd37788774c4b205
+      uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.Q8_0.gguf
+    - filename: AdaVaR-3B.mmproj-f16.gguf
+      sha256: 1ac6d198b191101cf7e84977f1770b60190adbfa33cefaaf6a5ece6ea9270d98
+      uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.mmproj-f16.gguf
+  overrides:
+    backend: llama-cpp
+    context_size: 32768
+    known_usecases:
+      - chat
+      - vision
+    mmproj: AdaVaR-3B.mmproj-f16.gguf
+    options:
+      - use_jinja:true
+    parameters:
+      model: AdaVaR-3B.Q8_0.gguf
+    template:
+      use_tokenizer_template: true

core/gallery/testdata/model_library/samples/multiline-description.library.yaml

@@ -0,0 +1,46 @@
+- kind: model
+  id: adavar-3b-q8
+  name: adavar-3b-q8
+  version: 0.0.0-gallery.4a2f0db86526
+  description: |
+    AdaVaR-3B is a Qwen2.5-VL-3B-Instruct fine-tune for visual reasoning
+    through text or image-grounded coordinates. This Q8_0 GGUF build
+    includes the F16 vision projector. Adaptive reasoning uses the publisher's
+    system prompt and question suffix; see the model card for these prompts.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/ZejunLi/AdaVaR-3B
+    - https://huggingface.co/mradermacher/AdaVaR-3B-GGUF
+  tags:
+    - llm
+    - gguf
+    - vision
+    - reasoning
+    - cpu
+    - gpu
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    url: github:mudler/LocalAI/gallery/virtual.yaml@master
+    files:
+      - filename: AdaVaR-3B.Q8_0.gguf
+        sha256: 23495169a352b076dee53ffb74da1861b3f9670c7a081cbecd37788774c4b205
+        uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.Q8_0.gguf
+      - filename: AdaVaR-3B.mmproj-f16.gguf
+        sha256: 1ac6d198b191101cf7e84977f1770b60190adbfa33cefaaf6a5ece6ea9270d98
+        uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.mmproj-f16.gguf
+    overrides:
+      backend: llama-cpp
+      context_size: 32768
+      known_usecases:
+        - chat
+        - vision
+      mmproj: AdaVaR-3B.mmproj-f16.gguf
+      options:
+        - use_jinja:true
+      parameters:
+        model: AdaVaR-3B.Q8_0.gguf
+      template:
+        use_tokenizer_template: true

core/gallery/testdata/model_library/samples/no-files.gallery.yaml

@@ -0,0 +1,34 @@
+- url: github:mudler/LocalAI/gallery/virtual.yaml@master
+  name: wemm-embedding-2b
+  description: |
+    WeMM-Embedding-2B is Tencent's Apache-2.0 multilingual embedding model
+    built on Qwen3.5. This entry serves the original bfloat16 safetensors with
+    LocalAI's Transformers backend and produces 2,048-dimensional normalized
+    embeddings for text retrieval, semantic search, and RAG.
+
+    The upstream model can also embed images and videos. LocalAI currently
+    exposes text input through its embeddings API for this backend.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/tencent/WeMM-Embedding-2B
+  tags:
+    - embeddings
+    - safetensors
+    - transformers
+    - multilingual
+    - retrieval
+    - rag
+    - gpu
+    - cpu
+  overrides:
+    backend: transformers
+    embeddings: true
+    known_usecases:
+      - embeddings
+    parameters:
+      model: tencent/WeMM-Embedding-2B
+    trust_remote_code: true
+    type: SentenceTransformer
+  variants:
+    - model: wemm-embedding-4b
+    - model: wemm-embedding-9b

core/gallery/testdata/model_library/samples/no-files.library.yaml

@@ -0,0 +1,42 @@
+- kind: model
+  id: wemm-embedding-2b
+  name: wemm-embedding-2b
+  version: 0.0.0-gallery.947cd4b61bb2
+  description: |
+    WeMM-Embedding-2B is Tencent's Apache-2.0 multilingual embedding model
+    built on Qwen3.5. This entry serves the original bfloat16 safetensors with
+    LocalAI's Transformers backend and produces 2,048-dimensional normalized
+    embeddings for text retrieval, semantic search, and RAG.
+
+    The upstream model can also embed images and videos. LocalAI currently
+    exposes text input through its embeddings API for this backend.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/tencent/WeMM-Embedding-2B
+  tags:
+    - embeddings
+    - safetensors
+    - transformers
+    - multilingual
+    - retrieval
+    - rag
+    - gpu
+    - cpu
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    url: github:mudler/LocalAI/gallery/virtual.yaml@master
+    overrides:
+      backend: transformers
+      embeddings: true
+      known_usecases:
+        - embeddings
+      parameters:
+        model: tencent/WeMM-Embedding-2B
+      trust_remote_code: true
+      type: SentenceTransformer
+    variants:
+      - model: wemm-embedding-4b
+      - model: wemm-embedding-9b

core/gallery/testdata/model_library/samples/no-url.gallery.yaml

@@ -0,0 +1,28 @@
+- name: aurore-reveil_koto-small-7b-it
+  description: |
+    Koto-Small-7B-IT is an instruct-tuned version of Koto-Small-7B-PT, which was trained on MiMo-7B-Base for almost a billion tokens of creative-writing data. This model is meant for roleplaying and instruct usecases.
+  license: mit
+  urls:
+    - https://huggingface.co/Aurore-Reveil/Koto-Small-7B-IT
+    - https://huggingface.co/bartowski/Aurore-Reveil_Koto-Small-7B-IT-GGUF
+  icon: https://cdn-uploads.huggingface.co/production/uploads/634262af8d8089ebaefd410e/9Bnn2AnIjfQFWBGkhDNmI.png
+  tags:
+    - koto
+    - 7b
+    - gguf
+    - quantized
+    - llm
+    - text-to-text
+    - chat
+    - creative-writing
+    - roleplay
+    - instruct-tuned
+  files:
+    - filename: Aurore-Reveil_Koto-Small-7B-IT-Q4_K_M.gguf
+      sha256: c5c38bfa5d8d5100e91a2e0050a0b2f3e082cd4bfd423cb527abc3b6f1ae180c
+      uri: huggingface://bartowski/Aurore-Reveil_Koto-Small-7B-IT-GGUF/Aurore-Reveil_Koto-Small-7B-IT-Q4_K_M.gguf
+  overrides:
+    known_usecases:
+      - chat
+    parameters:
+      model: Aurore-Reveil_Koto-Small-7B-IT-Q4_K_M.gguf

core/gallery/testdata/model_library/samples/no-url.library.yaml

@@ -0,0 +1,36 @@
+- kind: model
+  id: aurore-reveil_koto-small-7b-it
+  name: aurore-reveil_koto-small-7b-it
+  version: 0.0.0-gallery.7a65255bb4ce
+  description: |
+    Koto-Small-7B-IT is an instruct-tuned version of Koto-Small-7B-PT, which was trained on MiMo-7B-Base for almost a billion tokens of creative-writing data. This model is meant for roleplaying and instruct usecases.
+  license: mit
+  urls:
+    - https://huggingface.co/Aurore-Reveil/Koto-Small-7B-IT
+    - https://huggingface.co/bartowski/Aurore-Reveil_Koto-Small-7B-IT-GGUF
+  tags:
+    - koto
+    - 7b
+    - gguf
+    - quantized
+    - llm
+    - text-to-text
+    - chat
+    - creative-writing
+    - roleplay
+    - instruct-tuned
+  icon: https://cdn-uploads.huggingface.co/production/uploads/634262af8d8089ebaefd410e/9Bnn2AnIjfQFWBGkhDNmI.png
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    files:
+      - filename: Aurore-Reveil_Koto-Small-7B-IT-Q4_K_M.gguf
+        sha256: c5c38bfa5d8d5100e91a2e0050a0b2f3e082cd4bfd423cb527abc3b6f1ae180c
+        uri: huggingface://bartowski/Aurore-Reveil_Koto-Small-7B-IT-GGUF/Aurore-Reveil_Koto-Small-7B-IT-Q4_K_M.gguf
+    overrides:
+      known_usecases:
+        - chat
+      parameters:
+        model: Aurore-Reveil_Koto-Small-7B-IT-Q4_K_M.gguf

core/gallery/testdata/model_library/samples/plain.gallery.yaml

@@ -0,0 +1,38 @@
+- url: github:mudler/LocalAI/gallery/virtual.yaml@master
+  name: adavar-3b-q8
+  description: |
+    AdaVaR-3B is a Qwen2.5-VL-3B-Instruct fine-tune for visual reasoning
+    through text or image-grounded coordinates. This Q8_0 GGUF build
+    includes the F16 vision projector. Adaptive reasoning uses the publisher's
+    system prompt and question suffix; see the model card for these prompts.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/ZejunLi/AdaVaR-3B
+    - https://huggingface.co/mradermacher/AdaVaR-3B-GGUF
+  tags:
+    - llm
+    - gguf
+    - vision
+    - reasoning
+    - cpu
+    - gpu
+  files:
+    - filename: AdaVaR-3B.Q8_0.gguf
+      sha256: 23495169a352b076dee53ffb74da1861b3f9670c7a081cbecd37788774c4b205
+      uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.Q8_0.gguf
+    - filename: AdaVaR-3B.mmproj-f16.gguf
+      sha256: 1ac6d198b191101cf7e84977f1770b60190adbfa33cefaaf6a5ece6ea9270d98
+      uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.mmproj-f16.gguf
+  overrides:
+    backend: llama-cpp
+    context_size: 32768
+    known_usecases:
+      - chat
+      - vision
+    mmproj: AdaVaR-3B.mmproj-f16.gguf
+    options:
+      - use_jinja:true
+    parameters:
+      model: AdaVaR-3B.Q8_0.gguf
+    template:
+      use_tokenizer_template: true

core/gallery/testdata/model_library/samples/plain.library.yaml

@@ -0,0 +1,46 @@
+- kind: model
+  id: adavar-3b-q8
+  name: adavar-3b-q8
+  version: 0.0.0-gallery.4a2f0db86526
+  description: |
+    AdaVaR-3B is a Qwen2.5-VL-3B-Instruct fine-tune for visual reasoning
+    through text or image-grounded coordinates. This Q8_0 GGUF build
+    includes the F16 vision projector. Adaptive reasoning uses the publisher's
+    system prompt and question suffix; see the model card for these prompts.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/ZejunLi/AdaVaR-3B
+    - https://huggingface.co/mradermacher/AdaVaR-3B-GGUF
+  tags:
+    - llm
+    - gguf
+    - vision
+    - reasoning
+    - cpu
+    - gpu
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    url: github:mudler/LocalAI/gallery/virtual.yaml@master
+    files:
+      - filename: AdaVaR-3B.Q8_0.gguf
+        sha256: 23495169a352b076dee53ffb74da1861b3f9670c7a081cbecd37788774c4b205
+        uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.Q8_0.gguf
+      - filename: AdaVaR-3B.mmproj-f16.gguf
+        sha256: 1ac6d198b191101cf7e84977f1770b60190adbfa33cefaaf6a5ece6ea9270d98
+        uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.mmproj-f16.gguf
+    overrides:
+      backend: llama-cpp
+      context_size: 32768
+      known_usecases:
+        - chat
+        - vision
+      mmproj: AdaVaR-3B.mmproj-f16.gguf
+      options:
+        - use_jinja:true
+      parameters:
+        model: AdaVaR-3B.Q8_0.gguf
+      template:
+        use_tokenizer_template: true

core/gallery/testdata/model_library/samples/size.gallery.yaml

@@ -0,0 +1,21 @@
+- url: github:mudler/LocalAI/gallery/virtual.yaml@master
+  name: moonshine-tiny
+  description: |
+    Moonshine Tiny is a lightweight speech-to-text model optimized for fast transcription. It is designed for efficient on-device ASR with high accuracy relative to its size.
+  license: apache-2.0
+  urls:
+    - https://github.com/moonshine-ai/moonshine
+  tags:
+    - stt
+    - speech-to-text
+    - asr
+    - audio-transcription
+    - cpu
+    - gpu
+  size: 108MB
+  overrides:
+    backend: moonshine
+    known_usecases:
+      - transcript
+    parameters:
+      model: moonshine/tiny

core/gallery/testdata/model_library/samples/size.library.yaml

@@ -0,0 +1,29 @@
+- kind: model
+  id: moonshine-tiny
+  name: moonshine-tiny
+  version: 0.0.0-gallery.a07d0dc76057
+  description: |
+    Moonshine Tiny is a lightweight speech-to-text model optimized for fast transcription. It is designed for efficient on-device ASR with high accuracy relative to its size.
+  license: apache-2.0
+  urls:
+    - https://github.com/moonshine-ai/moonshine
+  tags:
+    - stt
+    - speech-to-text
+    - asr
+    - audio-transcription
+    - cpu
+    - gpu
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    url: github:mudler/LocalAI/gallery/virtual.yaml@master
+    size: 108MB
+    overrides:
+      backend: moonshine
+      known_usecases:
+        - transcript
+      parameters:
+        model: moonshine/tiny

core/gallery/testdata/model_library/samples/variants.gallery.yaml

@@ -0,0 +1,40 @@
+- url: github:mudler/LocalAI/gallery/virtual.yaml@master
+  name: adavar-3b-q4
+  description: |
+    AdaVaR-3B is a Qwen2.5-VL-3B-Instruct fine-tune for visual reasoning
+    through text or image-grounded coordinates. This Q4_K_M GGUF build
+    includes the F16 vision projector. Adaptive reasoning uses the publisher's
+    system prompt and question suffix; see the model card for these prompts.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/ZejunLi/AdaVaR-3B
+    - https://huggingface.co/mradermacher/AdaVaR-3B-GGUF
+  tags:
+    - llm
+    - gguf
+    - vision
+    - reasoning
+    - cpu
+    - gpu
+  files:
+    - filename: AdaVaR-3B.Q4_K_M.gguf
+      sha256: ab333b48b080d3f251d955c639a390691f7a44105c164fe58fa7a8d33b4fe51a
+      uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.Q4_K_M.gguf
+    - filename: AdaVaR-3B.mmproj-f16.gguf
+      sha256: 1ac6d198b191101cf7e84977f1770b60190adbfa33cefaaf6a5ece6ea9270d98
+      uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.mmproj-f16.gguf
+  overrides:
+    backend: llama-cpp
+    context_size: 32768
+    known_usecases:
+      - chat
+      - vision
+    mmproj: AdaVaR-3B.mmproj-f16.gguf
+    options:
+      - use_jinja:true
+    parameters:
+      model: AdaVaR-3B.Q4_K_M.gguf
+    template:
+      use_tokenizer_template: true
+  variants:
+    - model: adavar-3b-q8

core/gallery/testdata/model_library/samples/variants.library.yaml

@@ -0,0 +1,48 @@
+- kind: model
+  id: adavar-3b-q4
+  name: adavar-3b-q4
+  version: 0.0.0-gallery.aad216859953
+  description: |
+    AdaVaR-3B is a Qwen2.5-VL-3B-Instruct fine-tune for visual reasoning
+    through text or image-grounded coordinates. This Q4_K_M GGUF build
+    includes the F16 vision projector. Adaptive reasoning uses the publisher's
+    system prompt and question suffix; see the model card for these prompts.
+  license: apache-2.0
+  urls:
+    - https://huggingface.co/ZejunLi/AdaVaR-3B
+    - https://huggingface.co/mradermacher/AdaVaR-3B-GGUF
+  tags:
+    - llm
+    - gguf
+    - vision
+    - reasoning
+    - cpu
+    - gpu
+  channel: gallery
+  policy:
+    requireSignature: false
+  schemaVersion: 1
+  model:
+    url: github:mudler/LocalAI/gallery/virtual.yaml@master
+    files:
+      - filename: AdaVaR-3B.Q4_K_M.gguf
+        sha256: ab333b48b080d3f251d955c639a390691f7a44105c164fe58fa7a8d33b4fe51a
+        uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.Q4_K_M.gguf
+      - filename: AdaVaR-3B.mmproj-f16.gguf
+        sha256: 1ac6d198b191101cf7e84977f1770b60190adbfa33cefaaf6a5ece6ea9270d98
+        uri: https://huggingface.co/mradermacher/AdaVaR-3B-GGUF/resolve/580d869e53b6338bf3dbafc5d8488217cbd28265/AdaVaR-3B.mmproj-f16.gguf
+    overrides:
+      backend: llama-cpp
+      context_size: 32768
+      known_usecases:
+        - chat
+        - vision
+      mmproj: AdaVaR-3B.mmproj-f16.gguf
+      options:
+        - use_jinja:true
+      parameters:
+        model: AdaVaR-3B.Q4_K_M.gguf
+      template:
+        use_tokenizer_template: true
+    variants:
+      - model: adavar-3b-q8

core/http/endpoints/addons/catalogui_test.go

@@ -74,6 +74,23 @@ var _ = Describe("catalog and management actions", Label("catalogui"), func() {
 		s = newAppsStack()
 	})
 
+	It("lists add-ons by default, and takes a kind that this host reads", func() {
+		s.each(func(name string, e http.Handler) {
+			admin := bearerOf(s.tokens["alice"])
+			addons := send(e, "POST", "/api/addons/dispatch", dispatchBody("kind-addon-"+name, "", "catalog-search", 0, `{"kind":"addon"}`), admin)
+			Expect(addons.code).To(Equal(200), name)
+			Expect(payloadOf(addons)).To(HaveKeyWithValue("total", BeNumerically("==", 2)), name)
+			backends := send(e, "POST", "/api/addons/dispatch", dispatchBody("kind-backend-"+name, "", "catalog-search", 0, `{"kind":"backend"}`), admin)
+			Expect(backends.code).To(Equal(200), name)
+			Expect(payloadOf(backends)).To(HaveKeyWithValue("total", BeNumerically("==", 0)), name)
+			all := send(e, "POST", "/api/addons/dispatch", dispatchBody("kind-all-"+name, "", "catalog-search", 0, `{"kind":"all"}`), admin)
+			Expect(all.code).To(Equal(200), name)
+			Expect(payloadOf(all)).To(HaveKeyWithValue("total", BeNumerically("==", 2)), name)
+			model := send(e, "POST", "/api/addons/dispatch", dispatchBody("kind-model-"+name, "", "catalog-search", 0, `{"kind":"model"}`), admin)
+			Expect(model.code).To(Equal(403), name+": a kind this host does not read is a denied request")
+		})
+	})
+
 	It("serves catalog search, details and the installed management view to administrators only, the same from every frontend", func() {
 		s.each(func(name string, e http.Handler) {
 			admin := bearerOf(s.tokens["alice"])

core/http/endpoints/addons/gateway.go

@@ -169,7 +169,7 @@ func resultError(c echo.Context, e error) error {
 
 // Dispatch forwards typed operations to the explicitly configured owner.
 // @Summary Submit a typed addon lifecycle operation or read an addon resource
-// @Description Authenticates the named caller, checks the addons feature, requires administration for every action except read, and forwards the typed request to the designated addon owner. A mutation is never retried: after an outcome_unknown response keep the operationId and poll operation-status instead of submitting a new mutation. Lifecycle actions are install, upgrade, enable, disable and uninstall (arguments sourceId and version; enable and disable take the generation that was listed). The management reads, all administrator-only and never mutations, are catalog-search (arguments text, sourceId, offset, limit up to 100), catalog-details (addonId plus arguments sourceId and version), catalog-sources and addons-installed. The library changes are catalog-source-save (arguments are one source: id, name, url, enabled, policy, authReference; removed true deletes it and never touches installed addons) and catalog-source-refresh (argument sourceId). A library names a credential only by a reference the owner configured, never a secret. Unknown argument fields are denied. The update actions are update-status and update-check (no arguments; the check fetches the library again and applies nothing) and update-upgrade (arguments expectedDigest and candidateDigest, the pinned upgrade); each answers with a payload {error: {type, message, status}} or {data}, the same from every frontend. The browser pages use the dedicated routes under /api/addons/{id}/update and /api/addons/{id}/upgrade, which accept only an administrator's own browser session.
+// @Description Authenticates the named caller, checks the addons feature, requires administration for every action except read, and forwards the typed request to the designated addon owner. A mutation is never retried: after an outcome_unknown response keep the operationId and poll operation-status instead of submitting a new mutation. Lifecycle actions are install, upgrade, enable, disable and uninstall (arguments sourceId and version; enable and disable take the generation that was listed). The management reads, all administrator-only and never mutations, are catalog-search (arguments text, kind, sourceId, offset, limit up to 100; kind is addon by default, or backend, or all), catalog-details (addonId plus arguments sourceId and version), catalog-sources and addons-installed. The library changes are catalog-source-save (arguments are one source: id, name, url, enabled, policy, authReference; removed true deletes it and never touches installed addons) and catalog-source-refresh (argument sourceId). A library names a credential only by a reference the owner configured, never a secret. Unknown argument fields are denied. The update actions are update-status and update-check (no arguments; the check fetches the library again and applies nothing) and update-upgrade (arguments expectedDigest and candidateDigest, the pinned upgrade); each answers with a payload {error: {type, message, status}} or {data}, the same from every frontend. The browser pages use the dedicated routes under /api/addons/{id}/update and /api/addons/{id}/upgrade, which accept only an administrator's own browser session.
 // @Tags Addons
 // @Accept json
 // @Produce json

core/http/endpoints/localai/api_instructions_test.go

@@ -39,7 +39,7 @@ var _ = Describe("API Instructions Endpoints", func() {
 
 			instructions, ok := resp["instructions"].([]any)
 			Expect(ok).To(BeTrue())
-			Expect(instructions).To(HaveLen(25))
+			Expect(instructions).To(HaveLen(26))
 
 			// Verify each instruction has required fields and correct URL format
 			for _, s := range instructions {
@@ -69,6 +69,7 @@ var _ = Describe("API Instructions Endpoints", func() {
 
 			Expect(names).To(ContainElements(
 				"addons",
+				"library-sources",
 				"chat-inference",
 				"moderation",
 				"config-management",

core/http/endpoints/localai/backend_library.go

@@ -0,0 +1,190 @@
+package localai
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/labstack/echo/v4"
+	"github.com/mudler/LocalAI/core/http/middleware"
+	"github.com/mudler/LocalAI/core/schema"
+	"github.com/mudler/LocalAI/core/services/addons/backendlib"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"github.com/mudler/LocalAI/core/services/galleryop"
+	"github.com/mudler/LocalAI/pkg/downloader"
+	"github.com/mudler/xlog"
+)
+
+// BackendLibraryInstaller installs a backend from a library entry and lists
+// the installed ones that have a newer build in their library.
+type BackendLibraryInstaller interface {
+	Install(ctx context.Context, sourceID, backend, version string, progress backendlib.Progress) error
+	Updates(ctx context.Context) ([]backendlib.Update, error)
+}
+
+// BackendLibraryJobs records the status of an install under a job ID. The
+// gallery service is the one the backend gallery installs use, so the same
+// route, GET /backends/jobs/{id}, answers for both.
+type BackendLibraryJobs interface {
+	UpdateStatus(id string, op *galleryop.OpStatus)
+}
+
+// BackendLibraryInstallRequest names one library entry of kind backend.
+type BackendLibraryInstallRequest struct {
+	// SourceID is the library the entry comes from.
+	SourceID string `json:"sourceId"`
+	// Name is the backend name of the entry.
+	Name string `json:"name"`
+	// Version is the version or the channel of the entry.
+	Version string `json:"version"`
+}
+
+// libraryInstallTimeout bounds one install that runs after its request ended.
+const libraryInstallTimeout = time.Hour
+
+// InstallBackendFromLibraryEndpoint starts the install of a backend from a
+// library entry on this node and answers at once with a job. The job reports
+// the steps of the install (resolving, verifying, size, fetching, writing) as
+// the phase of its status, with the byte progress of the fetch, and ends with
+// the result or the reason of the refusal. The library resolves the entry, so
+// the request cannot name an image, a digest or a policy.
+// @Summary Install a backend from a library entry on this node.
+// @Tags backends
+// @Param request body BackendLibraryInstallRequest true "library, backend name and version"
+// @Success 200 {object} schema.BackendResponse "the job; read its status at the status URL"
+// @Failure 400 {object} schema.ErrorResponse "the request does not name an entry"
+// @Failure 409 {object} schema.ErrorResponse "the same backend is already being installed"
+// @Router /backends/library/install [post]
+func InstallBackendFromLibraryEndpoint(installer BackendLibraryInstaller, jobs BackendLibraryJobs) echo.HandlerFunc {
+	var mu sync.Mutex
+	running := map[string]bool{}
+	return func(c echo.Context) error {
+		var in BackendLibraryInstallRequest
+		if err := c.Bind(&in); err != nil {
+			return libraryError(c, http.StatusBadRequest, "invalid request")
+		}
+		if in.SourceID == "" || in.Name == "" || in.Version == "" {
+			return libraryError(c, http.StatusBadRequest, "sourceId, name and version are required")
+		}
+		// One install of a name at a time: two would write the same directory.
+		mu.Lock()
+		if running[in.Name] {
+			mu.Unlock()
+			return libraryError(c, http.StatusConflict, "this backend is already being installed")
+		}
+		running[in.Name] = true
+		mu.Unlock()
+
+		id := uuid.NewString()
+		jobs.UpdateStatus(id, &galleryop.OpStatus{Phase: backendlib.StepResolving, Message: stepMessage(backendlib.StepResolving), GalleryElementName: in.Name})
+		// The request ends before the install does, so the install keeps the
+		// values of the request and drops its cancellation.
+		ctx, cancel := context.WithTimeout(context.WithoutCancel(c.Request().Context()), libraryInstallTimeout)
+		go func() {
+			defer cancel()
+			defer func() {
+				mu.Lock()
+				delete(running, in.Name)
+				mu.Unlock()
+			}()
+			runLibraryInstall(ctx, installer, jobs, id, in)
+		}()
+		return c.JSON(http.StatusOK, schema.BackendResponse{ID: id, StatusURL: fmt.Sprintf("%sbackends/jobs/%s", middleware.BaseURL(c), id)})
+	}
+}
+
+// stepMessage is the text of a step in the status of a job.
+func stepMessage(step string) string {
+	switch step {
+	case backendlib.StepResolving:
+		return "Resolving the library entry"
+	case backendlib.StepVerifying:
+		return "Verifying the signature"
+	case backendlib.StepSize:
+		return "Checking the image size"
+	case backendlib.StepFetching:
+		return "Fetching the image"
+	case backendlib.StepWriting:
+		return "Writing the metadata"
+	}
+	return step
+}
+
+func runLibraryInstall(ctx context.Context, installer BackendLibraryInstaller, jobs BackendLibraryJobs, id string, in BackendLibraryInstallRequest) {
+	var mu sync.Mutex
+	phase := backendlib.StepResolving
+	post := func(op *galleryop.OpStatus) {
+		op.GalleryElementName = in.Name
+		jobs.UpdateStatus(id, op)
+	}
+	err := installer.Install(ctx, in.SourceID, in.Name, in.Version, backendlib.Progress{
+		Step: func(step string) {
+			mu.Lock()
+			phase = step
+			mu.Unlock()
+			post(&galleryop.OpStatus{Phase: step, Message: stepMessage(step)})
+		},
+		Bytes: func(file, current, total string, pct float64) {
+			mu.Lock()
+			p := phase
+			mu.Unlock()
+			// Bytes arrive while the image is fetched; a late tick must not
+			// move the job back from a step it has left.
+			if p != backendlib.StepFetching {
+				return
+			}
+			post(&galleryop.OpStatus{Phase: p, Message: stepMessage(p), FileName: file, Progress: pct, DownloadedFileSize: current, TotalFileSize: total})
+		},
+	})
+	if err == nil {
+		post(&galleryop.OpStatus{Phase: "done", Message: "completed", Processed: true, Progress: 100})
+		return
+	}
+	xlog.Warn("backend library install failed", "source", in.SourceID, "backend", in.Name, "error", err)
+	mu.Lock()
+	failed := phase
+	mu.Unlock()
+	// The phase stays at the step that failed, so the page can mark it.
+	post(&galleryop.OpStatus{Phase: failed, Error: err, Processed: true, Message: "error: " + libraryReason(err)})
+}
+
+// libraryReason words the failure of an install for the administrator.
+func libraryReason(err error) string {
+	switch {
+	case errors.Is(err, catalog.ErrNotFound):
+		return "the library has no such entry for this host"
+	case errors.Is(err, backendlib.ErrCollision):
+		return err.Error()
+	case errors.Is(err, catalog.ErrUnavailable), errors.Is(err, catalog.ErrRefresh):
+		return "the library is not available: " + err.Error()
+	case errors.Is(err, downloader.ErrImageTooLarge):
+		return "the image is over the size limit: " + err.Error()
+	}
+	return err.Error()
+}
+
+// BackendLibraryUpdatesEndpoint lists the installed library backends that have
+// a newer build in their library. It reads the cached index and installs
+// nothing.
+// @Summary List the installed library backends with a newer build in their library.
+// @Tags backends
+// @Success 200 {object} map[string][]backendlib.Update "updates"
+// @Router /backends/library/updates [get]
+func BackendLibraryUpdatesEndpoint(installer BackendLibraryInstaller) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		updates, err := installer.Updates(c.Request().Context())
+		if err != nil {
+			return libraryError(c, http.StatusInternalServerError, err.Error())
+		}
+		return c.JSON(http.StatusOK, map[string][]backendlib.Update{"updates": updates})
+	}
+}
+
+// libraryError answers in the error format of the other routes.
+func libraryError(c echo.Context, status int, message string) error {
+	return c.JSON(status, schema.ErrorResponse{Error: &schema.APIError{Code: status, Message: message, Type: "backend_library"}})
+}

core/http/endpoints/localai/backend_library_test.go

@@ -0,0 +1,193 @@
+package localai_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+
+	"github.com/labstack/echo/v4"
+	"github.com/mudler/LocalAI/core/http/endpoints/localai"
+	"github.com/mudler/LocalAI/core/services/addons/backendlib"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"github.com/mudler/LocalAI/core/services/galleryop"
+	"github.com/mudler/LocalAI/pkg/downloader"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type fakeLibrary struct {
+	err     error
+	steps   []string
+	updates []backendlib.Update
+	last    [3]string
+	block   chan struct{}
+}
+
+func (f *fakeLibrary) Install(_ context.Context, source, backend, version string, p backendlib.Progress) error {
+	f.last = [3]string{source, backend, version}
+	for _, s := range f.steps {
+		p.Step(s)
+		if s == backendlib.StepFetching {
+			p.Bytes("layer", "1 MB", "2 MB", 50)
+		}
+	}
+	if f.block != nil {
+		<-f.block
+	}
+	return f.err
+}
+
+func (f *fakeLibrary) Updates(context.Context) ([]backendlib.Update, error) {
+	return f.updates, nil
+}
+
+// fakeJobs keeps every status of every job, in order.
+type fakeJobs struct {
+	mu   sync.Mutex
+	logs map[string][]galleryop.OpStatus
+}
+
+func (j *fakeJobs) UpdateStatus(id string, op *galleryop.OpStatus) {
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	if j.logs == nil {
+		j.logs = map[string][]galleryop.OpStatus{}
+	}
+	j.logs[id] = append(j.logs[id], *op)
+}
+
+func (j *fakeJobs) history(id string) []galleryop.OpStatus {
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	return append([]galleryop.OpStatus(nil), j.logs[id]...)
+}
+
+var allSteps = []string{backendlib.StepResolving, backendlib.StepVerifying, backendlib.StepSize, backendlib.StepFetching, backendlib.StepWriting}
+
+var _ = Describe("install a backend from a library", func() {
+	post := func(f *fakeLibrary, jobs *fakeJobs, body string) *httptest.ResponseRecorder {
+		e := echo.New()
+		req := httptest.NewRequest(http.MethodPost, "/backends/library/install", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		rec := httptest.NewRecorder()
+		Expect(localai.InstallBackendFromLibraryEndpoint(f, jobs)(e.NewContext(req, rec))).To(Succeed())
+		return rec
+	}
+	jobID := func(rec *httptest.ResponseRecorder) string {
+		var out struct {
+			ID        string `json:"id"`
+			StatusURL string `json:"status_url"`
+		}
+		Expect(json.Unmarshal(rec.Body.Bytes(), &out)).To(Succeed())
+		Expect(out.ID).NotTo(BeEmpty())
+		Expect(out.StatusURL).To(HaveSuffix("backends/jobs/" + out.ID))
+		return out.ID
+	}
+	last := func(jobs *fakeJobs, id string) galleryop.OpStatus {
+		var op galleryop.OpStatus
+		Eventually(func() bool {
+			h := jobs.history(id)
+			if len(h) == 0 {
+				return false
+			}
+			op = h[len(h)-1]
+			return op.Processed
+		}).Should(BeTrue())
+		return op
+	}
+
+	It("answers with a job and reports every step, then the result", func() {
+		f := &fakeLibrary{steps: allSteps}
+		jobs := &fakeJobs{}
+		rec := post(f, jobs, `{"sourceId":"pilot","name":"cpu-demo","version":"latest"}`)
+		Expect(rec.Code).To(Equal(http.StatusOK))
+		id := jobID(rec)
+		done := last(jobs, id)
+		Expect(done.Message).To(Equal("completed"))
+		Expect(done.Progress).To(BeEquivalentTo(100))
+		Expect(done.Error).NotTo(HaveOccurred())
+		Expect(f.last).To(Equal([3]string{"pilot", "cpu-demo", "latest"}))
+		phases := []string{}
+		for _, s := range jobs.history(id) {
+			if len(phases) == 0 || phases[len(phases)-1] != s.Phase {
+				phases = append(phases, s.Phase)
+			}
+			Expect(s.GalleryElementName).To(Equal("cpu-demo"))
+		}
+		Expect(phases).To(Equal(append(append([]string{}, allSteps...), "done")))
+		// The fetch step carries the bytes of the image.
+		var fetch *galleryop.OpStatus
+		for _, s := range jobs.history(id) {
+			if s.Phase == backendlib.StepFetching && s.Progress > 0 {
+				fetch = &s
+			}
+		}
+		Expect(fetch).NotTo(BeNil())
+		Expect(fetch.Progress).To(BeEquivalentTo(50))
+		Expect(fetch.TotalFileSize).To(Equal("2 MB"))
+	})
+
+	It("keeps the failed step as the phase of the job and gives the reason", func() {
+		f := &fakeLibrary{steps: allSteps[:3], err: fmt.Errorf("image too big: %w", downloader.ErrImageTooLarge)}
+		jobs := &fakeJobs{}
+		id := jobID(post(f, jobs, `{"sourceId":"pilot","name":"cpu-demo","version":"latest"}`))
+		done := last(jobs, id)
+		Expect(done.Phase).To(Equal(backendlib.StepSize))
+		Expect(done.Error).To(MatchError(ContainSubstring(downloader.ErrImageTooLarge.Error())))
+		Expect(done.Message).To(HavePrefix("error: "))
+	})
+
+	It("words a collision and a missing entry for the administrator", func() {
+		for err, want := range map[error]string{
+			fmt.Errorf("%w: %q", backendlib.ErrCollision, "cpu-demo"): "already installed from another origin",
+			catalog.ErrNotFound: "no such entry",
+		} {
+			jobs := &fakeJobs{}
+			id := jobID(post(&fakeLibrary{err: err}, jobs, `{"sourceId":"p","name":"n","version":"v"}`))
+			Expect(last(jobs, id).Message).To(ContainSubstring(want))
+		}
+	})
+
+	It("refuses a second install of a name that is still running", func() {
+		f := &fakeLibrary{block: make(chan struct{})}
+		jobs := &fakeJobs{}
+		body := `{"sourceId":"pilot","name":"cpu-demo","version":"latest"}`
+		e := echo.New()
+		handler := localai.InstallBackendFromLibraryEndpoint(f, jobs)
+		call := func() *httptest.ResponseRecorder {
+			req := httptest.NewRequest(http.MethodPost, "/backends/library/install", strings.NewReader(body))
+			req.Header.Set("Content-Type", "application/json")
+			rec := httptest.NewRecorder()
+			Expect(handler(e.NewContext(req, rec))).To(Succeed())
+			return rec
+		}
+		first := call()
+		Expect(first.Code).To(Equal(http.StatusOK))
+		Expect(call().Code).To(Equal(http.StatusConflict))
+		close(f.block)
+		last(jobs, jobID(first))
+		Eventually(func() int { return call().Code }).Should(Equal(http.StatusOK))
+	})
+
+	It("refuses a request that does not name an entry", func() {
+		for _, body := range []string{`{}`, `{"sourceId":"pilot","name":"x"}`, `not json`} {
+			Expect(post(&fakeLibrary{}, &fakeJobs{}, body).Code).To(Equal(http.StatusBadRequest), body)
+		}
+	})
+
+	It("lists the updates of the installed library backends", func() {
+		f := &fakeLibrary{updates: []backendlib.Update{{Name: "cpu-demo", SourceID: "pilot", InstalledDigest: "sha256:a", Version: "2", Digest: "sha256:b"}}}
+		rec := httptest.NewRecorder()
+		e := echo.New()
+		Expect(localai.BackendLibraryUpdatesEndpoint(f)(e.NewContext(httptest.NewRequest(http.MethodGet, "/backends/library/updates", nil), rec))).To(Succeed())
+		var out struct {
+			Updates []backendlib.Update `json:"updates"`
+		}
+		Expect(json.Unmarshal(rec.Body.Bytes(), &out)).To(Succeed())
+		Expect(out.Updates).To(Equal(f.updates))
+	})
+})

core/http/endpoints/localai/library_sources.go

@@ -0,0 +1,277 @@
+package localai
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/labstack/echo/v4"
+	"github.com/mudler/LocalAI/core/library"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	"github.com/mudler/xlog"
+)
+
+// LibrarySourcesEndpoints serve the library sources of all three kinds
+// (add-ons, backends and models). They work on the store `local-ai library`
+// edits, through the same functions, so the command and the routes cannot
+// drift. The routes are registered behind the administrator middleware.
+type LibrarySourcesEndpoints struct {
+	// Store returns the one store of the running server.
+	Store func() (*catalog.Sources, error)
+	// Official says whether the official libraries are on.
+	Official func() bool
+	// Applied runs after a change, so the server reads the new state.
+	Applied func(dropped ...string) error
+}
+
+type LibrarySourcesResponse struct {
+	Sources           []library.Info `json:"sources"`
+	OfficialLibraries bool           `json:"officialLibraries"`
+}
+
+type addLibrarySourceRequest struct {
+	Kind   string `json:"kind"`
+	URL    string `json:"url"`
+	ID     string `json:"id"`
+	Name   string `json:"name"`
+	Format string `json:"format"`
+	// Mirrors are fallback addresses of a model or backend source.
+	Mirrors []string `json:"mirrors,omitempty"`
+}
+
+type updateLibrarySourceRequest struct {
+	Mirrors []string `json:"mirrors"`
+}
+
+func librarySourceError(c echo.Context, code int, message string) error {
+	return c.JSON(code, map[string]any{"error": map[string]any{"code": code, "message": message}})
+}
+
+func (e LibrarySourcesEndpoints) open(c echo.Context) (*catalog.Sources, error) {
+	store, err := e.Store()
+	if err != nil {
+		xlog.Warn("library sources are not available", "error", err)
+		return nil, librarySourceError(c, http.StatusServiceUnavailable, "the library sources are not available")
+	}
+	return store, nil
+}
+
+func (e LibrarySourcesEndpoints) applied(dropped ...string) {
+	if e.Applied == nil {
+		return
+	}
+	if err := e.Applied(dropped...); err != nil {
+		xlog.Warn("could not apply the library sources", "error", err)
+	}
+}
+
+func (e LibrarySourcesEndpoints) official() bool {
+	if e.Official == nil {
+		return true
+	}
+	return e.Official()
+}
+
+// storeError maps a store error to the status the caller sees.
+func storeError(c echo.Context, err error, id string) error {
+	switch {
+	case errors.Is(err, catalog.ErrNotFound):
+		return librarySourceError(c, http.StatusNotFound, "no source with id "+id)
+	case errors.Is(err, catalog.ErrExists), errors.Is(err, library.ErrDuplicate):
+		return librarySourceError(c, http.StatusConflict, err.Error())
+	case errors.Is(err, catalog.ErrInvalid):
+		return librarySourceError(c, http.StatusBadRequest, "the id must be lowercase letters, digits and dashes and start with a letter, and a library index URL must be http or https (use format gallery for a gallery index)")
+	}
+	xlog.Warn("library source change failed", "error", err)
+	return librarySourceError(c, http.StatusInternalServerError, "the change could not be stored")
+}
+
+// List godoc
+// @Summary List the library sources
+// @Description Every library source of the add-on, backend and model kinds, with its state: kind, id, name, url, enabled (what the host does with it), default (shipped), removed (a default the user removed; a tombstone), suspended (a default while the official libraries are off), the conflict message when it clashes with another source, and the last fetch state when there is one. Administrators only.
+// @Tags library
+// @Produce json
+// @Success 200 {object} localai.LibrarySourcesResponse
+// @Router /api/library/sources [get]
+func (e LibrarySourcesEndpoints) List() echo.HandlerFunc {
+	return func(c echo.Context) error {
+		store, err := e.open(c)
+		if store == nil {
+			return err
+		}
+		return c.JSON(http.StatusOK, LibrarySourcesResponse{Sources: library.List(store), OfficialLibraries: e.official()})
+	}
+}
+
+// cleanMirrors trims the mirrors and checks them as a gallery address is
+// checked. An add-on source takes none.
+func cleanMirrors(kind string, in []string) ([]string, error) {
+	var out []string
+	for _, m := range in {
+		if m = strings.TrimSpace(m); m != "" {
+			out = append(out, m)
+		}
+	}
+	if len(out) > 0 && kind == string(catalog.KindAddon) {
+		return nil, errors.New("an add-on source takes no mirrors")
+	}
+	if err := catalog.ValidateMirrors(out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// Update godoc
+// @Summary Change the mirrors of a library source
+// @Description Replaces the mirrors of a model or backend source; an empty list clears them. Each mirror is an http(s), github:, oci:// or file:// address. Administrators only.
+// @Tags library
+// @Accept json
+// @Produce json
+// @Param id path string true "Source id"
+// @Success 200 {object} library.Info
+// @Router /api/library/sources/{id} [put]
+func (e LibrarySourcesEndpoints) Update() echo.HandlerFunc {
+	return func(c echo.Context) error {
+		id := c.Param("id")
+		var req updateLibrarySourceRequest
+		if err := c.Bind(&req); err != nil {
+			return librarySourceError(c, http.StatusBadRequest, "the request is not valid JSON")
+		}
+		store, err := e.open(c)
+		if store == nil {
+			return err
+		}
+		kind := ""
+		for _, in := range library.List(store) {
+			if in.ID == id {
+				kind = string(in.Kind)
+			}
+		}
+		mirrors, err := cleanMirrors(kind, req.Mirrors)
+		if err != nil {
+			return librarySourceError(c, http.StatusBadRequest, err.Error())
+		}
+		if err := store.SetMirrors(id, mirrors); err != nil {
+			return storeError(c, err, id)
+		}
+		e.applied()
+		for _, in := range library.List(store) {
+			if in.ID == id {
+				return c.JSON(http.StatusOK, in)
+			}
+		}
+		return c.NoContent(http.StatusNoContent)
+	}
+}
+
+// Add godoc
+// @Summary Add a library source
+// @Description Adds a source of your own. kind is addon, backend or model; format is library (default) or gallery. The id is derived from the name or URL when it is empty. A source with the same kind and URL is refused (409), as is a taken id. Administrators only.
+// @Tags library
+// @Accept json
+// @Produce json
+// @Success 201 {object} library.Info
+// @Router /api/library/sources [post]
+func (e LibrarySourcesEndpoints) Add() echo.HandlerFunc {
+	return func(c echo.Context) error {
+		var req addLibrarySourceRequest
+		if err := c.Bind(&req); err != nil {
+			return librarySourceError(c, http.StatusBadRequest, "the request is not valid JSON")
+		}
+		req.URL, req.ID, req.Name = strings.TrimSpace(req.URL), strings.TrimSpace(req.ID), strings.TrimSpace(req.Name)
+		switch req.Kind {
+		case string(catalog.KindAddon), string(catalog.KindBackend), string(catalog.KindModel):
+		default:
+			return librarySourceError(c, http.StatusBadRequest, "kind must be addon, backend or model")
+		}
+		format := ""
+		switch req.Format {
+		case "", "library":
+		case "gallery":
+			format = catalog.FormatGallery
+		default:
+			return librarySourceError(c, http.StatusBadRequest, "format must be library or gallery")
+		}
+		if req.URL == "" {
+			return librarySourceError(c, http.StatusBadRequest, "url is required")
+		}
+		mirrors, err := cleanMirrors(req.Kind, req.Mirrors)
+		if err != nil {
+			return librarySourceError(c, http.StatusBadRequest, err.Error())
+		}
+		store, err := e.open(c)
+		if store == nil {
+			return err
+		}
+		src, err := library.AddWithMirrors(store, catalog.Kind(req.Kind), req.URL, req.ID, req.Name, format, mirrors)
+		if err != nil {
+			return storeError(c, err, req.ID)
+		}
+		e.applied()
+		for _, in := range library.List(store) {
+			if in.ID == src.ID {
+				return c.JSON(http.StatusCreated, in)
+			}
+		}
+		return c.JSON(http.StatusCreated, library.Info{Kind: src.Kind, ID: src.ID, Name: src.Name, URL: src.URL, Enabled: true})
+	}
+}
+
+// SetEnabled godoc
+// @Summary Turn a library source on or off
+// @Description Enabling a removed default brings it back. Administrators only.
+// @Tags library
+// @Produce json
+// @Param id path string true "Source id"
+// @Success 200 {object} library.Info
+// @Router /api/library/sources/{id}/enable [post]
+// @Router /api/library/sources/{id}/disable [post]
+func (e LibrarySourcesEndpoints) SetEnabled(enabled bool) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		id := c.Param("id")
+		store, err := e.open(c)
+		if store == nil {
+			return err
+		}
+		if err := store.SetEnabled(id, enabled); err != nil {
+			return storeError(c, err, id)
+		}
+		e.applied()
+		for _, in := range library.List(store) {
+			if in.ID == id {
+				return c.JSON(http.StatusOK, in)
+			}
+		}
+		return c.NoContent(http.StatusNoContent)
+	}
+}
+
+// Remove godoc
+// @Summary Remove a library source
+// @Description A source of your own is deleted. A shipped default is not: it stays as a tombstone (removed true), so it does not come back at the next start; enabling it brings it back. Administrators only.
+// @Tags library
+// @Produce json
+// @Param id path string true "Source id"
+// @Success 200 {object} map[string]any
+// @Router /api/library/sources/{id} [delete]
+func (e LibrarySourcesEndpoints) Remove() echo.HandlerFunc {
+	return func(c echo.Context) error {
+		id := c.Param("id")
+		store, err := e.open(c)
+		if store == nil {
+			return err
+		}
+		url := library.URLOf(store, id)
+		wasDefault, err := library.Remove(store, id)
+		if err != nil {
+			return storeError(c, err, id)
+		}
+		// A tombstone keeps its record, so only a deleted source is dropped by address.
+		if wasDefault {
+			e.applied()
+		} else {
+			e.applied(url)
+		}
+		return c.JSON(http.StatusOK, map[string]any{"id": id, "default": wasDefault, "tombstone": wasDefault})
+	}
+}

core/http/endpoints/localai/library_sources_test.go

@@ -0,0 +1,258 @@
+package localai_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/labstack/echo/v4"
+	"github.com/mudler/LocalAI/core/http/auth"
+	. "github.com/mudler/LocalAI/core/http/endpoints/localai"
+	"github.com/mudler/LocalAI/core/library"
+	"github.com/mudler/LocalAI/core/services/addons/catalog"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// The routes sit behind auth.RequireAdmin, as RegisterLocalAIRoutes wires them.
+var _ = Describe("Library source routes", func() {
+	var (
+		app      *echo.Echo
+		dir      string
+		store    *catalog.Sources
+		applied  int
+		official bool
+		dropped  []string
+	)
+
+	// call sends one request as the given role ("" = not signed in).
+	call := func(role, method, path, body string) *httptest.ResponseRecorder {
+		req := httptest.NewRequest(method, path, strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		if role != "" {
+			req.Header.Set("X-Test-Role", role)
+		}
+		rec := httptest.NewRecorder()
+		app.ServeHTTP(rec, req)
+		return rec
+	}
+	list := func() (sources []map[string]any) {
+		rec := call(auth.RoleAdmin, http.MethodGet, "/api/library/sources", "")
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+		var resp struct {
+			Sources []map[string]any `json:"sources"`
+		}
+		Expect(json.Unmarshal(rec.Body.Bytes(), &resp)).To(Succeed())
+		return resp.Sources
+	}
+	find := func(id string) map[string]any {
+		for _, s := range list() {
+			if s["id"] == id {
+				return s
+			}
+		}
+		return nil
+	}
+
+	BeforeEach(func() {
+		dir = GinkgoT().TempDir()
+		var err error
+		store, err = library.Open(dir, true, false)
+		Expect(err).NotTo(HaveOccurred())
+		applied, official, dropped = 0, true, nil
+		app = echo.New()
+		app.Use(func(next echo.HandlerFunc) echo.HandlerFunc {
+			return func(c echo.Context) error {
+				if role := c.Request().Header.Get("X-Test-Role"); role != "" {
+					c.Set("auth_user", &auth.User{ID: "u-" + role, Role: role})
+				}
+				return next(c)
+			}
+		})
+		e := LibrarySourcesEndpoints{
+			Store:    func() (*catalog.Sources, error) { return store, nil },
+			Official: func() bool { return official },
+			Applied:  func(d ...string) error { applied++; dropped = append(dropped, d...); return nil },
+		}
+		admin := auth.RequireAdmin()
+		app.GET("/api/library/sources", e.List(), admin)
+		app.POST("/api/library/sources", e.Add(), admin)
+		app.POST("/api/library/sources/:id/enable", e.SetEnabled(true), admin)
+		app.POST("/api/library/sources/:id/disable", e.SetEnabled(false), admin)
+		app.PUT("/api/library/sources/:id", e.Update(), admin)
+		app.DELETE("/api/library/sources/:id", e.Remove(), admin)
+	})
+
+	It("refuses every route to a caller who is not an administrator", func() {
+		routes := [][2]string{
+			{http.MethodGet, "/api/library/sources"},
+			{http.MethodPost, "/api/library/sources"},
+			{http.MethodPost, "/api/library/sources/localai-backends/enable"},
+			{http.MethodPost, "/api/library/sources/localai-backends/disable"},
+			{http.MethodDelete, "/api/library/sources/localai-backends"},
+		}
+		for _, r := range routes {
+			Expect(call(auth.RoleUser, r[0], r[1], `{"kind":"model","url":"https://example.org/m.yaml"}`).Code).To(Equal(http.StatusForbidden), r[0]+" "+r[1])
+			Expect(call("", r[0], r[1], `{}`).Code).To(Equal(http.StatusUnauthorized), r[0]+" "+r[1])
+		}
+		// Nothing was changed by the refused calls.
+		Expect(applied).To(BeZero())
+		Expect(find("localai-backends")["enabled"]).To(BeTrue())
+		Expect(find("localai-backends")["removed"]).To(BeFalse())
+	})
+
+	It("lists the sources of all three kinds with their flags", func() {
+		kinds := map[any]bool{}
+		for _, s := range list() {
+			kinds[s["kind"]] = true
+			Expect(s["default"]).To(BeTrue())
+			Expect(s["removed"]).To(BeFalse())
+			Expect(s["suspended"]).To(BeFalse())
+		}
+		Expect(find("official")["enabled"]).To(BeTrue())
+		Expect(find("localai-backends")["enabled"]).To(BeTrue())
+		Expect(kinds).To(HaveKey("addon"))
+		Expect(kinds).To(HaveKey("backend"))
+		Expect(kinds).To(HaveKey("model"))
+	})
+
+	It("adds a model source of the user and refuses the same URL twice", func() {
+		rec := call(auth.RoleAdmin, http.MethodPost, "/api/library/sources", `{"kind":"model","format":"gallery","name":"Team Models","url":"https://example.org/models.yaml"}`)
+		Expect(rec.Code).To(Equal(http.StatusCreated), rec.Body.String())
+		var created map[string]any
+		Expect(json.Unmarshal(rec.Body.Bytes(), &created)).To(Succeed())
+		Expect(created).To(HaveKeyWithValue("id", "team-models"))
+		Expect(created).To(HaveKeyWithValue("kind", "model"))
+		Expect(created).To(HaveKeyWithValue("default", false))
+		Expect(applied).To(Equal(1))
+
+		// The file the CLI reads has it.
+		again, err := library.Open(dir, true, false)
+		Expect(err).NotTo(HaveOccurred())
+		found := false
+		for _, i := range library.List(again) {
+			found = found || i.ID == "team-models"
+		}
+		Expect(found).To(BeTrue())
+
+		dup := call(auth.RoleAdmin, http.MethodPost, "/api/library/sources", `{"kind":"model","format":"gallery","id":"other","url":"https://example.org/models.yaml"}`)
+		Expect(dup.Code).To(Equal(http.StatusConflict), dup.Body.String())
+		taken := call(auth.RoleAdmin, http.MethodPost, "/api/library/sources", `{"kind":"model","id":"team-models","url":"https://example.org/other.yaml"}`)
+		Expect(taken.Code).To(Equal(http.StatusConflict), taken.Body.String())
+	})
+
+	It("refuses a bad kind, format, id or URL", func() {
+		for _, body := range []string{
+			`{"kind":"nope","url":"https://example.org/m.yaml"}`,
+			`{"kind":"model","format":"zip","url":"https://example.org/m.yaml"}`,
+			`{"kind":"model","url":""}`,
+			`{"kind":"model","id":"Bad Id","url":"https://example.org/m.yaml"}`,
+			`{"kind":"model","url":"ftp://example.org/m.yaml"}`,
+			`not json`,
+		} {
+			Expect(call(auth.RoleAdmin, http.MethodPost, "/api/library/sources", body).Code).To(Equal(http.StatusBadRequest), body)
+		}
+		Expect(applied).To(BeZero())
+	})
+
+	It("disables and enables a default without removing it", func() {
+		rec := call(auth.RoleAdmin, http.MethodPost, "/api/library/sources/localai-backends/disable", "")
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+		Expect(find("localai-backends")).To(And(HaveKeyWithValue("enabled", false), HaveKeyWithValue("removed", false)))
+		Expect(call(auth.RoleAdmin, http.MethodPost, "/api/library/sources/localai-backends/enable", "").Code).To(Equal(http.StatusOK))
+		Expect(find("localai-backends")).To(HaveKeyWithValue("enabled", true))
+		Expect(call(auth.RoleAdmin, http.MethodPost, "/api/library/sources/nope/disable", "").Code).To(Equal(http.StatusNotFound))
+	})
+
+	It("leaves a tombstone for a removed default, as the CLI does, and deletes a source of the user", func() {
+		rec := call(auth.RoleAdmin, http.MethodDelete, "/api/library/sources/localai-backends", "")
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+		Expect(rec.Body.String()).To(ContainSubstring(`"tombstone":true`))
+		tomb := find("localai-backends")
+		Expect(tomb).To(And(HaveKeyWithValue("removed", true), HaveKeyWithValue("enabled", false), HaveKeyWithValue("default", true)))
+
+		// A restart seeds the defaults again; the tombstone stays.
+		again, err := library.Open(dir, true, false)
+		Expect(err).NotTo(HaveOccurred())
+		for _, i := range library.List(again) {
+			if i.ID == "localai-backends" {
+				Expect(i.Removed).To(BeTrue())
+			}
+		}
+		// Removing it again finds nothing to remove; enabling brings it back.
+		Expect(call(auth.RoleAdmin, http.MethodDelete, "/api/library/sources/localai-backends", "").Code).To(Equal(http.StatusNotFound))
+		Expect(call(auth.RoleAdmin, http.MethodPost, "/api/library/sources/localai-backends/enable", "").Code).To(Equal(http.StatusOK))
+		Expect(find("localai-backends")).To(And(HaveKeyWithValue("removed", false), HaveKeyWithValue("enabled", true)))
+
+		Expect(call(auth.RoleAdmin, http.MethodPost, "/api/library/sources", `{"kind":"backend","format":"gallery","id":"mine","url":"https://example.org/b.yaml"}`).Code).To(Equal(http.StatusCreated))
+		del := call(auth.RoleAdmin, http.MethodDelete, "/api/library/sources/mine", "")
+		Expect(del.Code).To(Equal(http.StatusOK))
+		Expect(del.Body.String()).To(ContainSubstring(`"tombstone":false`))
+		// The server drops the gallery of a deleted source by its address; a
+		// tombstone keeps its record, so nothing is dropped for it.
+		Expect(dropped).To(Equal([]string{"https://example.org/b.yaml"}))
+		Expect(find("mine")).To(BeNil())
+	})
+
+	It("shows the defaults as off and suspended while the official libraries are off", func() {
+		store.SetOfficial(false)
+		official = false
+		for _, s := range list() {
+			Expect(s).To(HaveKeyWithValue("enabled", false))
+			Expect(s).To(HaveKeyWithValue("suspended", true))
+			Expect(s).To(HaveKeyWithValue("default", true))
+		}
+		rec := call(auth.RoleAdmin, http.MethodGet, "/api/library/sources", "")
+		Expect(rec.Body.String()).To(ContainSubstring(`"officialLibraries":false`))
+	})
+
+	It("carries the conflict message for sources that list one entry", func() {
+		serve := func(id string) string {
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				_ = catalog.WriteIndex(w, []catalog.Release{{ID: id, Name: id, Version: "1.0.0", Artifact: "oci://registry.example/" + id, Digest: "sha256:" + strings.Repeat("a", 64), OS: "linux", Arch: "amd64"}})
+			}))
+			DeferCleanup(srv.Close)
+			return srv.URL
+		}
+		for _, id := range []string{"first", "second"} {
+			rec := call(auth.RoleAdmin, http.MethodPost, "/api/library/sources", `{"kind":"addon","id":"`+id+`","url":"`+serve("tables")+`"}`)
+			Expect(rec.Code).To(Equal(http.StatusCreated), rec.Body.String())
+			_, err := store.Refresh(GinkgoT().Context(), id)
+			Expect(err).NotTo(HaveOccurred())
+		}
+		for _, id := range []string{"first", "second"} {
+			msg, _ := find(id)["conflict"].(string)
+			Expect(msg).To(ContainSubstring(`"tables"`))
+			Expect(msg).To(ContainSubstring("two of your library sources"))
+		}
+		Expect(find("first")).NotTo(BeNil())
+	})
+
+	It("stores mirrors on add, returns them in the list and replaces them with a PUT", func() {
+		rec := call(auth.RoleAdmin, http.MethodPost, "/api/library/sources", `{"kind":"model","format":"gallery","id":"team","url":"https://example.org/m.yaml","mirrors":[" https://mirror.example/m.yaml ","github:org/repo/m.yaml@main",""]}`)
+		Expect(rec.Code).To(Equal(http.StatusCreated), rec.Body.String())
+		Expect(find("team")["mirrors"]).To(Equal([]any{"https://mirror.example/m.yaml", "github:org/repo/m.yaml@main"}))
+		rec = call(auth.RoleAdmin, http.MethodPut, "/api/library/sources/team", `{"mirrors":["oci://registry.example/m"]}`)
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+		Expect(find("team")["mirrors"]).To(Equal([]any{"oci://registry.example/m"}))
+		rec = call(auth.RoleAdmin, http.MethodPut, "/api/library/sources/team", `{"mirrors":[]}`)
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+		Expect(find("team")).NotTo(HaveKey("mirrors"))
+	})
+
+	It("refuses a mirror that is not an accepted address, and mirrors on an add-on source", func() {
+		for _, body := range []string{
+			`{"kind":"model","url":"https://example.org/m.yaml","mirrors":["ftp://x/m.yaml"]}`,
+			`{"kind":"model","url":"https://example.org/m.yaml","mirrors":["https://a b/m.yaml"]}`,
+			`{"kind":"model","url":"https://example.org/m.yaml","mirrors":["1","2","3","4","5","6","7","8","9"]}`,
+			`{"kind":"addon","url":"https://example.org/a.yaml","mirrors":["https://mirror.example/a.yaml"]}`,
+		} {
+			rec := call(auth.RoleAdmin, http.MethodPost, "/api/library/sources", body)
+			Expect(rec.Code).To(Equal(http.StatusBadRequest), body+" "+rec.Body.String())
+		}
+		Expect(call(auth.RoleAdmin, http.MethodPut, "/api/library/sources/localai-backends", `{"mirrors":["file"]}`).Code).To(Equal(http.StatusBadRequest))
+		Expect(call(auth.RoleAdmin, http.MethodPut, "/api/library/sources/nope", `{"mirrors":[]}`).Code).To(Equal(http.StatusNotFound))
+		Expect(find("localai-backends")).NotTo(HaveKey("mirrors"))
+	})
+})

core/http/endpoints/localai/settings.go

@@ -195,6 +195,12 @@ func UpdateSettingsEndpoint(app *application.Application) echo.HandlerFunc {
 		watchdogChanged := appConfig.ApplyRuntimeSettings(&settings)
 		restartRequired := prevDevelopmentPreference != appConfig.PreferDevelopmentBackends
 		gallery.ResetGalleryModelCacheIfChanged(prevGalleries, prevBackendGalleries, appConfig)
+		if settings.OfficialLibraries != nil {
+			// The shipped default sources of every kind follow the switch now.
+			if err := app.ApplyLibraries(); err != nil {
+				xlog.Warn("could not apply the official libraries setting", "error", err)
+			}
+		}
 		if settings.VRAMPersistentCache != nil || settings.AutoloadGalleries != nil {
 			if appConfig.VRAMPersistentCache && appConfig.AutoloadGalleries {
 				vram.ConfigurePersistentCache(filepath.Join(appConfig.SystemState.Model.ModelsPath, "..", "cache", "vram"), 24*time.Hour)

core/http/react-ui/e2e/addons-backend-library.spec.js

@@ -0,0 +1,228 @@
+import { test, expect } from '@playwright/test'
+import { ADMIN, release, sessionFor, mockAddons } from './addons-fixtures.js'
+
+// Backends in the library (phase 1): an entry has a kind, the Browse tab shows
+// it, and a backend installs through the backend route, not the add-on
+// lifecycle. The server is the authority, so these specs drive the page
+// against a stand-in and assert what the page sent.
+
+const POLICY = { requireSignature: true, issuer: 'https://token.actions.githubusercontent.com', identityRegex: '^https://github\\.com/o/r/\\.github/workflows/w\\.yml@refs/(heads/master|tags/.+)$' }
+const backend = (over = {}) => release('cpu-local-store', {
+  kind: 'backend', name: 'cpu-local-store', alias: 'local-store', description: 'A vector store.', version: '0.0.0-latest.0a1056fd8633',
+  sourceId: 'official-backends', artifact: 'oci://registry.example/backends:latest-cpu-local-store', policy: POLICY, ...over,
+})
+
+async function signIn(page) {
+  await page.route('**/api/auth/status', route => route.fulfill({ json: sessionFor(ADMIN) }))
+}
+
+// The backend routes of the host. `installed` is the mutable list GET /backends
+// answers. An install is a job: the request answers with its ID and the job
+// route reports the steps in `phases`, one per read, then the result. `fail`
+// ends the job with that error at the last step reached.
+async function mockBackends(page, { installed = [], phases = ['resolving', 'size', 'fetching', 'writing'], fail, refuse } = {}) {
+  const state = { installed: [...installed], installs: [], reads: 0 }
+  await page.route(/\/backends$/, route => route.fulfill({ json: state.installed }))
+  await page.route(/\/backends\/library\/install$/, route => {
+    const body = route.request().postDataJSON()
+    state.installs.push(body)
+    state.reads = 0
+    if (refuse) return route.fulfill(refuse)
+    return route.fulfill({ json: { id: 'job-1', status_url: '/backends/jobs/job-1' } })
+  })
+  await page.route(/\/backends\/jobs\/job-1$/, route => {
+    const body = state.installs.at(-1)
+    const at = state.reads++
+    const phase = phases[Math.min(at, phases.length - 1)]
+    const last = at >= phases.length
+    if (last && fail) return route.fulfill({ json: { phase, processed: true, error: fail, message: `error: ${fail}` } })
+    if (last) {
+      state.installed.push({ Name: body.name, Metadata: { library: body.sourceId } })
+      return route.fulfill({ json: { phase: 'done', processed: true, progress: 100, message: 'completed' } })
+    }
+    return route.fulfill({ json: { phase, processed: false, progress: phase === 'fetching' ? 40 : 0 } })
+  })
+  return state
+}
+
+test.describe('Library backends', () => {
+  test('browse: an entry shows its kind, and add-ons are still add-ons', async ({ page }) => {
+    await signIn(page)
+    const state = await mockAddons(page, { installed: [], releases: [release('tables'), backend()] })
+    await mockBackends(page)
+    await page.goto('/app/addons?tab=browse')
+    await expect(page.locator('.cat-item')).toHaveCount(2)
+    await expect(page.locator('.cat-item', { hasText: 'Tables' }).getByTestId('entry-kind')).toHaveText('Add-on')
+    const row = page.locator('.cat-item', { hasText: 'cpu-local-store' })
+    await expect(row.getByTestId('entry-kind')).toHaveText('Backend')
+    await expect(row.getByTestId('entry-kind')).toHaveAttribute('data-kind', 'backend')
+    // The page asks for every kind this host reads.
+    expect(state.log.dispatch.find(d => d.action === 'catalog-search').arguments.kind).toBe('all')
+  })
+
+  test('browse: a backend installs through the backend route and never through the add-on lifecycle', async ({ page }) => {
+    await signIn(page)
+    const state = await mockAddons(page, { installed: [], releases: [backend()] })
+    const backends = await mockBackends(page)
+    await page.goto('/app/addons?tab=browse')
+    const row = page.locator('.cat-item', { hasText: 'cpu-local-store' })
+    await row.getByRole('button', { name: 'Install' }).click()
+    const dialog = page.getByRole('alertdialog')
+    await expect(dialog).toContainText('Install cpu-local-store?')
+    await expect(dialog).toContainText('backend gallery is not changed')
+    await expect(dialog).toContainText('native code')
+    expect(backends.installs).toHaveLength(0)
+    await dialog.getByRole('button', { name: 'Install' }).click()
+    // The steps show while the job runs: a signed library lists the signature step.
+    const steps = row.getByTestId('install-steps')
+    await expect(steps.locator('[data-step]')).toHaveCount(5)
+    await expect(steps.locator('[data-step="fetching"]')).toHaveAttribute('data-state', /active|done/)
+    await expect(row.getByText('Installed as a backend on this node')).toBeVisible()
+    await expect(steps).toHaveCount(0)
+    expect(backends.installs).toEqual([{ sourceId: 'official-backends', name: 'cpu-local-store', version: '0.0.0-latest.0a1056fd8633' }])
+    expect(state.log.dispatch.filter(d => d.action === 'install')).toHaveLength(0)
+    // Once installed the entry says so and offers no second install.
+    await expect(row.getByText('Installed', { exact: true })).toBeVisible()
+    await expect(row.getByRole('button', { name: 'Install' })).toBeDisabled()
+  })
+
+  test('browse: a refusal of the host is shown with its own reason', async ({ page }) => {
+    await signIn(page)
+    await mockAddons(page, { installed: [], releases: [backend()] })
+    await mockBackends(page, {
+      phases: ['resolving'],
+      fail: 'backend is already installed from another origin: "cpu-local-store"',
+    })
+    await page.goto('/app/addons?tab=browse')
+    const row = page.locator('.cat-item', { hasText: 'cpu-local-store' })
+    await row.getByRole('button', { name: 'Install' }).click()
+    await page.getByRole('alertdialog').getByRole('button', { name: 'Install' }).click()
+    await expect(row.getByRole('alert')).toContainText('The backend was not installed.')
+    await expect(row.getByRole('alert')).toContainText('already installed from another origin')
+    await expect(row.getByRole('button', { name: 'Install' })).toBeEnabled()
+    // The step that failed stays marked.
+    await expect(row.locator('[data-step="resolving"]')).toHaveAttribute('data-state', 'failed')
+    await expect(row.locator('[data-step="fetching"]')).toHaveAttribute('data-state', 'pending')
+  })
+
+  test('browse: a request the host refuses is shown with its reason', async ({ page }) => {
+    await signIn(page)
+    await mockAddons(page, { installed: [], releases: [backend()] })
+    await mockBackends(page, { refuse: { status: 409, json: { error: { type: 'backend_library', code: 409, message: 'this backend is already being installed' } } } })
+    await page.goto('/app/addons?tab=browse')
+    const row = page.locator('.cat-item', { hasText: 'cpu-local-store' })
+    await row.getByRole('button', { name: 'Install' }).click()
+    await page.getByRole('alertdialog').getByRole('button', { name: 'Install' }).click()
+    await expect(row.getByRole('alert')).toContainText('already being installed')
+  })
+
+  test('browse: the details give the kind, the alias and the signer pattern', async ({ page }) => {
+    await signIn(page)
+    await mockAddons(page, { installed: [], releases: [backend()] })
+    await mockBackends(page)
+    await page.goto('/app/addons?tab=browse')
+    await page.locator('.cat-item', { hasText: 'cpu-local-store' }).getByRole('button', { name: 'Details' }).click()
+    await expect(page.getByTestId('details-kind')).toHaveText('Backend')
+    await expect(page.getByText('local-store', { exact: true })).toBeVisible()
+    await expect(page.getByText('workflows/w', { exact: false })).toBeVisible()
+  })
+
+  test('libraries: a signer pattern is edited and saved without an exact identity, and skipped entries are reported', async ({ page }) => {
+    await signIn(page)
+    const state = await mockAddons(page, {
+      sources: [{ id: 'official-backends', name: 'Official backends', url: 'https://catalog.example/backends.yaml', enabled: true, policy: POLICY, refresh: { checkedAt: new Date().toISOString(), lastSuccess: new Date().toISOString(), count: 1, skipped: 2, skippedKinds: ['model'], failed: false } }],
+    })
+    await mockBackends(page)
+    await page.goto('/app/addons?tab=libraries')
+    await expect(page.getByTestId('skipped-kinds')).toContainText('2 entries skipped: kind model')
+    await page.getByRole('button', { name: 'Edit' }).click()
+    const pattern = page.getByLabel('Signer identity pattern (optional)')
+    await expect(pattern).toHaveValue(POLICY.identityRegex)
+    await page.getByRole('button', { name: 'Save' }).click()
+    await expect.poll(() => state.log.dispatch.filter(d => d.action === 'catalog-source-save').length).toBe(1)
+    const saved = state.log.dispatch.find(d => d.action === 'catalog-source-save').arguments
+    expect(saved.policy).toEqual(POLICY)
+  })
+})
+
+// The Backends page (phase 2): a backend that came from a library says so, and
+// a newer build in its library is an update the administrator starts.
+const PINNED = 'sha256:' + 'a1'.repeat(32)
+const NEWER = 'sha256:' + 'b2'.repeat(32)
+
+async function mockBackendsPage(page, { updates = true, phases = ['resolving', 'verifying', 'size', 'fetching', 'writing'] } = {}) {
+  const state = { digest: PINNED, updates: updates ? [{ name: 'cpu-local-store', sourceId: 'official-backends', installedVersion: '0.0.0-latest.0a1056fd8633', installedDigest: PINNED, version: '0.0.0-latest.0b2', digest: NEWER, signed: true }] : [], installs: [], reads: 0 }
+  await page.route('**/api/backends?*', route => route.fulfill({ json: { backends: [] } }))
+  await page.route('**/api/backends/upgrades', route => route.fulfill({ json: { 'llama-cpp': { backend_name: 'llama-cpp', installed_version: '1', available_version: '2' } } }))
+  await page.route(/\/backends$/, route => route.fulfill({
+    json: [
+      { Name: 'cpu-local-store', Metadata: { name: 'cpu-local-store', library: 'official-backends', digest: state.digest, version: '0.0.0-latest.0a1056fd8633' } },
+      { Name: 'llama-cpp', Metadata: { name: 'llama-cpp', gallery_url: 'https://gallery.example/index.yaml', version: '1' } },
+    ],
+  }))
+  await page.route(/\/backends\/library\/updates$/, route => route.fulfill({ json: { updates: state.updates } }))
+  await page.route(/\/backends\/library\/install$/, route => {
+    state.installs.push(route.request().postDataJSON())
+    state.reads = 0
+    return route.fulfill({ json: { id: 'job-2', status_url: '/backends/jobs/job-2' } })
+  })
+  await page.route(/\/backends\/jobs\/job-2$/, route => {
+    const at = state.reads++
+    if (at >= phases.length) {
+      state.digest = NEWER
+      state.updates = []
+      return route.fulfill({ json: { phase: 'done', processed: true, progress: 100, message: 'completed' } })
+    }
+    return route.fulfill({ json: { phase: phases[at], processed: false, progress: 0 } })
+  })
+  return state
+}
+
+test.describe('Backends page and libraries', () => {
+  test('a library backend carries its library and the digest it pinned; a gallery backend does not', async ({ page }) => {
+    await signIn(page)
+    await mockBackendsPage(page)
+    await page.goto('/app/backends?view=installed')
+    const row = page.locator('[data-entity="cpu-local-store"]')
+    await expect(row.getByTestId('backend-library')).toContainText('Library: official-backends')
+    await expect(page.locator('[data-entity="llama-cpp"]').getByTestId('backend-library')).toHaveCount(0)
+    await row.click()
+    const detail = page.getByTestId('backend-detail')
+    await expect(detail.getByTestId('library-id')).toHaveText('official-backends')
+    await expect(detail).toContainText('Pinned digest')
+    await expect(detail).toContainText(PINNED)
+  })
+
+  test('a newer build in the library shows as an update and is installed only on request', async ({ page }) => {
+    await signIn(page)
+    const state = await mockBackendsPage(page)
+    await page.goto('/app/backends?view=installed')
+    const row = page.locator('[data-entity="cpu-local-store"]')
+    await expect(row).toContainText('Update available')
+    // Nothing is installed by looking at the page.
+    expect(state.installs).toHaveLength(0)
+    await row.click()
+    await expect(page.getByTestId('library-update-facts')).toContainText('sha256:b2b2b2b2b2b2')
+    await row.getByTestId('backend-library-update').click()
+    await expect.poll(() => state.installs).toEqual([{ sourceId: 'official-backends', name: 'cpu-local-store', version: '0.0.0-latest.0b2' }])
+    // The steps of the install show in the detail while it runs.
+    await expect(page.getByTestId('backend-detail').getByTestId('install-steps').locator('[data-step]')).toHaveCount(5)
+    // When it ends the row is current and pins the new digest.
+    await expect(row).not.toContainText('Update available', { timeout: 15000 })
+    await expect(page.getByTestId('backend-detail')).toContainText(NEWER)
+    await expect(row.getByTestId('backend-library-update')).toHaveCount(0)
+  })
+
+  test('with no newer build the library backend is current, and gallery upgrades are unchanged', async ({ page }) => {
+    await signIn(page)
+    const state = await mockBackendsPage(page, { updates: false })
+    await page.goto('/app/backends?view=installed')
+    await expect(page.locator('[data-entity="cpu-local-store"]')).toContainText('Current')
+    await expect(page.locator('[data-entity="cpu-local-store"]').getByTestId('backend-library-update')).toHaveCount(0)
+    // The gallery backend keeps the gallery upgrade state and button.
+    const gallery = page.locator('[data-entity="llama-cpp"]')
+    await expect(gallery).toContainText('Update')
+    await expect(gallery.getByRole('button', { name: 'Update llama-cpp' })).toBeVisible()
+    expect(state.installs).toHaveLength(0)
+  })
+})

core/http/react-ui/e2e/addons-fixtures.js

@@ -51,7 +51,7 @@ export async function mockAddons(page, options = {}) {
     installed: options.installed || [installedAddon()],
     sources: options.sources || [{ id: 'main', name: 'Main', url: 'https://catalog.example/releases.json', enabled: true, policy: { requireSignature: false }, refresh: { checkedAt: new Date().toISOString(), lastSuccess: new Date().toISOString(), count: 2, failed: false } }],
     releases: options.releases || [release('notes'), release('tables', { policy: { requireSignature: true, issuer: 'https://issuer.example', identity: 'release@catalog.example' } })],
-    log: { appsList: 0, start: [], stop: [], dispatch: [], check: [], upgrade: [] },
+    log: { appsList: 0, start: [], stop: [], dispatch: [], check: [], upgrade: [], library: [] },
     // Overrides for the update routes: each takes the parsed body.
     check: options.check || null,
     upgrade: options.upgrade || null,
@@ -116,6 +116,37 @@ export async function mockAddons(page, options = {}) {
     if (a && a.update) { a.generation += 1; a.version = a.update.version; a.digest = a.update.digest; delete a.update }
     return route.fulfill(ok({ OperationID: body.operationId, AddonID: id, Phase: 'completed', Generation: a?.generation }))
   })
+  // The library source routes (all three kinds). The records in state.sources
+  // are listed as they are, with the flags the host adds filled in; a removed
+  // default stays listed as a tombstone, as the host does.
+  await page.route(/\/api\/library\/sources(\/[^/]+(\/(enable|disable))?)?$/, route => {
+    const req = route.request()
+    const parts = new URL(req.url()).pathname.split('/')
+    const id = parts[4] || ''
+    const verb = parts[5] || ''
+    const body = req.postData() ? JSON.parse(req.postData()) : null
+    state.log.library.push({ method: req.method(), id, verb, body })
+    const json = (status, payload) => route.fulfill({ status, contentType: 'application/json', body: JSON.stringify(payload) })
+    const find = () => state.sources.find(x => x.id === id)
+    if (req.method() === 'GET') {
+      return json(200, { sources: state.sources.map(x => ({ kind: 'addon', default: false, removed: false, suspended: false, ...x })), officialLibraries: !state.sources.some(x => x.suspended) })
+    }
+    if (req.method() === 'POST' && !id) {
+      if (state.sources.some(x => x.kind === body.kind && x.url === body.url)) return json(409, { error: { code: 409, message: `${body.url} is already a ${body.kind} source` } })
+      const added = { kind: body.kind, id: body.id || (body.name || body.url).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''), name: body.name || body.id, url: body.url, format: body.format === 'gallery' ? 'gallery' : undefined, enabled: true, policy: { requireSignature: false } }
+      state.sources = [...state.sources, added]
+      return json(201, { default: false, removed: false, suspended: false, ...added })
+    }
+    const source = find()
+    if (!source) return json(404, { error: { code: 404, message: `no source with id ${id}` } })
+    if (req.method() === 'POST') {
+      source.enabled = verb === 'enable'
+      if (source.removed) source.removed = false
+      return json(200, { default: false, removed: false, suspended: false, ...source })
+    }
+    if (source.default) { source.removed = true; source.enabled = false } else state.sources = state.sources.filter(x => x.id !== id)
+    return json(200, { id, default: Boolean(source.default), tombstone: Boolean(source.default) })
+  })
   await page.route(/\/api\/addons\/dispatch$/, route => {
     const body = JSON.parse(route.request().postData() || '{}')
     state.log.dispatch.push(body)

core/http/react-ui/e2e/addons-gallery.spec.js

@@ -548,9 +548,9 @@ test.describe('Add-ons: libraries', () => {
     await expect(dialog).toContainText('stay installed and keep running')
     await dialog.getByRole('button', { name: 'Remove' }).click()
     await expect(page.locator('[data-source="main"]')).toHaveCount(0)
-    const removal = state.log.dispatch.find(d => d.action === 'catalog-source-save')
-    expect(removal.arguments.removed).toBe(true)
-    expect(removal.arguments.id).toBe('main')
+    // A removal goes through the library route, the same one the other kinds use.
+    const removal = state.log.library.find(c => c.method === 'DELETE')
+    expect(removal.id).toBe('main')
     await tab(page, 'Installed').click()
     await expect(page.locator('[data-addon="notes"]')).toBeVisible()
     expect(state.installed).toHaveLength(1)

core/http/react-ui/e2e/library-sources.spec.js

@@ -0,0 +1,196 @@
+import { test, expect } from './coverage-fixtures.js'
+
+// Library sources of all three kinds: add-ons on the Add-ons Libraries tab,
+// models on the Models page and backends on the Backends page, each in the
+// panel its "Manage libraries" button opens, against a real
+// server that starts like a normal install (playwright.library.config.js): the
+// default sources of the add-on, backend and model kinds are in the store, and
+// the routes change the store the `local-ai library` command edits. The specs
+// share one server and change its sources, so they run in order.
+//
+// The conflict message needs two sources whose fetched indexes list one entry,
+// which a test server without a network cannot give; that spec answers the list
+// call itself and checks what the page shows of the message.
+
+test.describe.configure({ mode: 'serial' })
+
+const ROW = (page, id) => page.locator(`[data-source="${id}"]`)
+// The defaults this build enables. The model gallery index `localai` is a default
+// too, but a build reads the model library or the gallery, not both, so it is
+// listed turned off.
+const OFFICIAL = { addon: 'official', backend: 'localai-backends', model: 'official-models' }
+
+const PAGES = { addon: '/app/addons?tab=libraries', model: '/app/models', backend: '/app/backends' }
+
+async function openLibraries(page, kind = 'addon') {
+  await page.goto(PAGES[kind])
+  if (kind !== 'addon') await page.getByRole('button', { name: 'Manage libraries' }).click()
+  await expect(page.getByRole('list', { name: 'Libraries' })).toBeVisible()
+}
+
+async function sources(page) {
+  const res = await page.request.get('/api/library/sources')
+  expect(res.ok()).toBe(true)
+  return (await res.json())
+}
+
+test.describe('Library sources: all three kinds', () => {
+  test('each page lists only its own kind, with a Default badge and no kind filter', async ({ page }) => {
+    const expected = { addon: ['official'], backend: ['localai-backends'], model: ['official-models', 'localai'] }
+    for (const [kind, ids] of Object.entries(expected)) {
+      await openLibraries(page, kind)
+      await expect(page.locator('[data-source]')).toHaveCount(ids.length)
+      for (const id of ids) {
+        const row = ROW(page, id)
+        await expect(row).toBeVisible()
+        await expect(row).toHaveAttribute('data-kind', kind)
+        await expect(row.getByTestId('source-default')).toHaveText('Default')
+      }
+      await expect(ROW(page, OFFICIAL[kind]).getByTestId('source-state')).toHaveText('Enabled')
+      await expect(page.getByRole('group', { name: 'Filter by kind' })).toHaveCount(0)
+    }
+    await openLibraries(page, 'model')
+    await expect(ROW(page, 'localai').getByTestId('source-state')).toHaveText('Disabled')
+  })
+
+  test('adds a model source of your own, which has no Default badge and stays after a reload', async ({ page }) => {
+    await openLibraries(page, 'model')
+    await page.getByRole('button', { name: 'Add a library' }).click()
+    const sheet = page.getByTestId('source-editor')
+    await expect(sheet.getByLabel('Kind')).toHaveCount(0)
+    await sheet.getByLabel('Index format').selectOption('gallery')
+    await sheet.getByLabel('Name').fill('Team models')
+    await sheet.getByLabel('Catalog URL').fill('https://models.example.org/index.yaml')
+    await sheet.getByRole('button', { name: 'Save' }).click()
+    const row = ROW(page, 'team-models')
+    await expect(row).toBeVisible()
+    await expect(row).toHaveAttribute('data-kind', 'model')
+    await expect(row.getByTestId('source-default')).toHaveCount(0)
+    await expect(row.getByTestId('source-state')).toHaveText('Enabled')
+
+    const stored = (await sources(page)).sources.find(s => s.id === 'team-models')
+    expect(stored).toMatchObject({ kind: 'model', format: 'gallery', default: false, enabled: true, url: 'https://models.example.org/index.yaml' })
+    await page.reload()
+    await page.getByRole('button', { name: 'Manage libraries' }).click()
+    await expect(ROW(page, 'team-models')).toBeVisible()
+
+    // The same address twice is refused with the reason.
+    await page.getByRole('button', { name: 'Add a library' }).click()
+    const again = page.getByTestId('source-editor')
+    await again.getByLabel('Name').fill('Same address')
+    await again.getByLabel('Catalog URL').fill('https://models.example.org/index.yaml')
+    await again.getByRole('button', { name: 'Save' }).click()
+    await expect(page.getByRole('alert').filter({ hasText: 'already a model source' })).toBeVisible()
+  })
+
+  test('turns a default off and removes it: it stays listed as removed, and restoring brings it back', async ({ page }) => {
+    await openLibraries(page, 'model')
+    const row = ROW(page, 'official-models')
+    await row.locator('[data-action="disable"]').click()
+    await expect(row.getByTestId('source-state')).toHaveText('Disabled')
+    await expect(row).toHaveAttribute('data-state', 'disabled')
+    expect((await sources(page)).sources.find(s => s.id === 'official-models')).toMatchObject({ enabled: false, removed: false, default: true })
+
+    await row.locator('[data-action="remove"]').click()
+    const dialog = page.getByRole('alertdialog')
+    await expect(dialog).toContainText('stays removed at the next start')
+    await dialog.getByRole('button', { name: 'Remove' }).click()
+    await expect(row).toHaveAttribute('data-state', 'removed')
+    await expect(row.getByTestId('source-state')).toHaveText('Removed')
+    await expect(row.getByTestId('source-default')).toHaveText('Default')
+    // The tombstone is in the store the CLI reads, not only on the page.
+    expect((await sources(page)).sources.find(s => s.id === 'official-models')).toMatchObject({ removed: true, enabled: false, default: true })
+    await page.reload()
+    await page.getByRole('button', { name: 'Manage libraries' }).click()
+    await expect(ROW(page, 'official-models')).toHaveAttribute('data-state', 'removed')
+
+    await ROW(page, 'official-models').locator('[data-action="restore"]').click()
+    await expect(ROW(page, 'official-models')).toHaveAttribute('data-state', 'enabled')
+    expect((await sources(page)).sources.find(s => s.id === 'official-models')).toMatchObject({ removed: false, enabled: true })
+
+    // A source of your own is deleted, not kept as a tombstone.
+    await ROW(page, 'team-models').locator('[data-action="remove"]').click()
+    await page.getByRole('alertdialog').getByRole('button', { name: 'Remove' }).click()
+    await expect(ROW(page, 'team-models')).toHaveCount(0)
+    expect((await sources(page)).sources.find(s => s.id === 'team-models')).toBeUndefined()
+  })
+
+  test('shows the conflict message the store gives next to the source that clashes', async ({ page }) => {
+    const message = 'the addon "tables" is listed by two of your library sources, "first" and "second"; disable or remove one of them (local-ai library disable second)'
+    await page.route('**/api/library/sources', route => route.request().method() === 'GET'
+      ? route.fulfill({
+        json: {
+          officialLibraries: true,
+          sources: [
+            { kind: 'addon', id: 'first', name: 'First', url: 'https://one.example/index.yaml', enabled: true, default: false, removed: false, suspended: false, conflict: message },
+            { kind: 'addon', id: 'second', name: 'Second', url: 'https://two.example/index.yaml', enabled: true, default: false, removed: false, suspended: false, conflict: message },
+            { kind: 'addon', id: 'official', name: 'Official', url: 'https://off.example/index.yaml', enabled: true, default: true, removed: false, suspended: false, conflict: 'the addon "tables" is provided by your source "first", so this default source is ignored for it' },
+          ],
+        },
+      })
+      : route.fallback())
+    await openLibraries(page)
+    await expect(ROW(page, 'first').getByTestId('source-conflict')).toContainText('two of your library sources')
+    await expect(ROW(page, 'second').getByTestId('source-conflict')).toContainText('disable or remove one of them')
+    await expect(ROW(page, 'official').getByTestId('source-conflict')).toContainText('this default source is ignored for it')
+  })
+})
+
+test.describe('Library sources: Use official libraries', () => {
+  const settingRow = page => page.locator('[data-field="official_libraries"]')
+
+  async function setOfficial(page, on) {
+    await page.goto('/app/settings')
+    await page.getByRole('button', { name: /^Backends and galleries/ }).click()
+    const toggle = settingRow(page).getByRole('switch')
+    await expect(settingRow(page)).toContainText('Use official libraries')
+    await expect(toggle).toHaveAttribute('aria-checked', on ? 'false' : 'true')
+    await toggle.click()
+    await page.getByRole('button', { name: 'Apply' }).click()
+    await expect(page.getByText('Settings saved successfully')).toBeVisible()
+  }
+
+  const settings = async page => (await (await page.request.get('/api/settings')).json())
+
+  test('turning it off hides the default galleries and shows the defaults as off, and on brings them back', async ({ page }) => {
+    // On: the default model and backend galleries are read.
+    const on = await settings(page)
+    expect(on.official_libraries).toBe(true)
+    expect(on.galleries.length).toBeGreaterThan(0)
+    expect(on.backend_galleries.length).toBeGreaterThan(0)
+    const defaultUrls = [...on.galleries, ...on.backend_galleries].map(g => g.url)
+
+    // A source of your own, so there is something that must stay.
+    const added = await page.request.post('/api/library/sources', { data: { kind: 'model', format: 'gallery', id: 'mine', name: 'Mine', url: 'https://mine.example.org/index.yaml' } })
+    expect(added.status()).toBe(201)
+
+    await setOfficial(page, false)
+    const off = await settings(page)
+    expect(off.official_libraries).toBe(false)
+    expect(off.galleries.map(g => g.url)).toEqual(['https://mine.example.org/index.yaml'])
+    expect(off.backend_galleries).toEqual([])
+
+    // The Libraries tab lists the defaults, shown as off; the source of your own is on.
+    for (const [kind, id] of Object.entries(OFFICIAL)) {
+      await openLibraries(page, kind)
+      await expect(page.getByTestId('official-off')).toBeVisible()
+      await expect(ROW(page, id)).toHaveAttribute('data-state', 'suspended')
+      await expect(ROW(page, id).getByTestId('source-default')).toBeVisible()
+      await expect(ROW(page, id).getByTestId('source-state')).toContainText('Off')
+    }
+    await openLibraries(page, 'model')
+    await expect(ROW(page, 'mine')).toHaveAttribute('data-state', 'enabled')
+
+    await setOfficial(page, true)
+    const back = await settings(page)
+    expect(back.official_libraries).toBe(true)
+    expect(back.galleries.map(g => g.url)).toEqual(expect.arrayContaining([...on.galleries.map(g => g.url), 'https://mine.example.org/index.yaml']))
+    expect(back.backend_galleries.map(g => g.url)).toEqual(on.backend_galleries.map(g => g.url))
+    for (const [kind, id] of Object.entries(OFFICIAL)) {
+      await openLibraries(page, kind)
+      await expect(page.getByTestId('official-off')).toHaveCount(0)
+      await expect(ROW(page, id)).toHaveAttribute('data-state', 'enabled')
+    }
+    await page.request.delete('/api/library/sources/mine')
+  })
+})

core/http/react-ui/e2e/settings-fixtures.js

@@ -8,7 +8,7 @@ export function settingsFixture(overrides = {}) {
   return {
     watchdog_enabled: true, watchdog_idle_enabled: true, watchdog_busy_enabled: false,
     watchdog_idle_timeout: '15m0s', watchdog_busy_timeout: '5m0s', watchdog_interval: '500ms',
-    max_active_backends: 0, auto_upgrade_backends: false, auto_upgrade_addons: false, prefer_development_backends: false,
+    max_active_backends: 0, official_libraries: true, auto_upgrade_backends: false, auto_upgrade_addons: false, prefer_development_backends: false,
     memory_reclaimer_enabled: true, memory_reclaimer_threshold: 0.9,
     force_eviction_when_busy: false, size_aware_eviction: false,
     lru_eviction_max_retries: 50, lru_eviction_retry_interval: '1s',

core/http/react-ui/e2e/settings-page.spec.js

@@ -284,17 +284,13 @@ test.describe('Settings: fields with a different wire form', () => {
     await expect(hist.getByRole('button', { name: 'Revert' })).toHaveCount(0)
   })
 
-  test('a gallery list is parsed, and bad JSON stops Apply', async ({ page }) => {
+  test('the gallery lists are read-only views with a link to the Manage libraries panel', async ({ page }) => {
     await group(page, 'Backends and galleries').click()
-    const box = row(page, 'galleries').getByRole('textbox')
-    await box.fill('{oops')
-    await page.getByRole('button', { name: 'Show diff' }).click()
-    await expect(page.getByLabel('Checks')).toContainText('this must be a JSON list')
-    await expect(page.getByRole('button', { name: 'Apply' })).toBeDisabled()
-    await box.fill('[{"url":"https://example.org/models","name":"mine"}]')
-    await page.getByRole('button', { name: 'Apply' }).click()
-    await expect(page.getByTestId('settings-undo-toast')).toBeVisible()
-    expect(state.posts[0]).toEqual({ galleries: [{ url: 'https://example.org/models', name: 'mine' }] })
+    const models = row(page, 'galleries')
+    await expect(models.getByRole('textbox')).toHaveCount(0)
+    await expect(models.getByTestId('settings-sources-model')).toBeVisible()
+    await expect(models.getByRole('link', { name: 'Manage libraries' })).toHaveAttribute('href', '/app/models?libraries=1')
+    await expect(row(page, 'backend_galleries').getByRole('link', { name: 'Manage libraries' })).toHaveAttribute('href', '/app/backends?libraries=1')
   })
 
   test('the GPU memory budget is checked the way the server checks it', async ({ page }) => {

core/http/react-ui/playwright.config.js

@@ -6,12 +6,13 @@ export default defineConfig({
   // add-on owner and a ready file the matching runner passes in an ADDONS_*
   // variable; each reads it when the file loads, so the default run must not
   // load them. Every one has its own config (playwright.<suite>.config.js) and
-  // is started by scripts/addons/*.sh.
+  // is started by scripts/addons/*.sh. The library sources spec needs a server
+  // started with --library-sources and runs from playwright.library.config.js.
   testIgnore: [
     '**/addons-foundation.spec.js', '**/addons-gallery.spec.js', '**/addons-proposals.spec.js',
     '**/addons-recovery.spec.js', '**/addons-runtime.spec.js', '**/addons-slots.spec.js',
     '**/addons-upgrade.spec.js', '**/tables-acceptance.spec.js', '**/tables-artifacts.spec.js',
-    '**/tables-ui.spec.js',
+    '**/tables-ui.spec.js', '**/library-sources.spec.js',
   ],
   globalSetup: './e2e/global-setup.js',
   timeout: 30_000,

core/http/react-ui/playwright.library.config.js

@@ -0,0 +1,22 @@
+import { defineConfig } from '@playwright/test'
+import base from './playwright.config.js'
+
+// The library sources spec runs against a real server that starts like a normal
+// install (default galleries and default sources of the three kinds), on its
+// own port, with a fresh data directory. LIBRARY_UI_PORT and LIBRARY_UI_LOG
+// change the port and the server log.
+const port = Number(process.env.LIBRARY_UI_PORT || 8097)
+
+export default defineConfig({
+  ...base,
+  testIgnore: [],
+  testMatch: ['**/library-sources.spec.js'],
+  globalSetup: undefined,
+  use: { ...base.use, baseURL: `http://127.0.0.1:${port}` },
+  webServer: process.env.PLAYWRIGHT_EXTERNAL_SERVER ? undefined : {
+    command: `../../../tests/e2e-ui/ui-test-server --mock-backend=../../../tests/e2e/mock-backend/mock-backend --port=${port} --library-sources > ${process.env.LIBRARY_UI_LOG || '/dev/null'} 2>&1`,
+    port,
+    timeout: 120_000,
+    reuseExistingServer: false,
+  },
+})

core/http/react-ui/public/locales/de/addons.json

@@ -76,7 +76,18 @@
     "installedSame": "Installiert {{version}}",
     "installedState": "Installiert",
     "installing": "Wird installiert",
-    "search": "Bibliotheken durchsuchen"
+    "search": "Bibliotheken durchsuchen",
+    "kind": {
+      "addon": "Add-on",
+      "backend": "Backend"
+    },
+    "installedBackend": "Installed",
+    "installedBackendNote": "Installed as a backend on this node. Models can use it now.",
+    "confirmBackendBody": "Version {{version}} of the backend from the library {{library}} will be downloaded, checked against its digest and signature, and installed on this node. The backend gallery is not changed.",
+    "confirmBackendNote": "A backend runs native code with the rights of LocalAI. Install it only from a library you trust.",
+    "backendFailed": "The backend was not installed.",
+    "alias": "Alias",
+    "kindLabel": "Kind"
   },
   "catalog": {
     "allLibraries": "Alle Bibliotheken",
@@ -156,7 +167,9 @@
       "required": "Erforderlich, wenn eine Signatur verlangt wird.",
       "url": "Gib eine http- oder https-Adresse ein.",
       "urlCredentials": "Die Adresse darf keinen Benutzernamen und kein Passwort enthalten.",
-      "urlQuery": "Die Adresse darf keinen Query-String und kein Fragment enthalten."
+      "urlQuery": "Die Adresse darf keinen Query-String und kein Fragment enthalten.",
+      "either": "Use the exact identity or the pattern, not both.",
+      "urlEmpty": "Enter the address of the index."
     },
     "fields": {
       "enabled": "Aktiviert",
@@ -166,12 +179,17 @@
       "name": "Name",
       "reference": "Zugangsdaten-Referenz (optional)",
       "requireSignature": "Signatur verlangen",
-      "url": "Katalog-URL"
+      "url": "Katalog-URL",
+      "identityRegex": "Signer identity pattern (optional)",
+      "kind": "Kind",
+      "format": "Index format"
     },
     "hints": {
       "id": "Kleinbuchstaben, Ziffern und Bindestriche. Kann später nicht geändert werden.",
       "reference": "Der Name einer Zugangsdaten-Konfiguration des Betreibers. Füge hier nie ein Token oder Passwort ein.",
-      "url": "Eine https-Adresse ohne Zugangsdaten und ohne Query-String."
+      "url": "Eine https-Adresse ohne Zugangsdaten und ohne Query-String.",
+      "identityRegex": "An anchored pattern, from ^ to $, used instead of the exact identity. Backend libraries use it so builds from master and from tags both verify.",
+      "format": "A library index uses the shared library entry shape. A gallery index is a model or backend gallery, as the gallery flags name it."
     },
     "lastRefresh": "Aktualisiert {{when}}, {{count}} Einträge",
     "lead": "Eine Bibliothek ist ein Katalogdokument, das Add-ons auflistet. Zugangsdaten werden hier nie eingetippt: Eine private Bibliothek nennt eine Zugangsdaten-Referenz, die der Betreiber eingerichtet hat.",
@@ -187,7 +205,43 @@
     "removeTitle": "{{name}} entfernen?",
     "removed": "{{name}} entfernt.",
     "save": "Speichern",
-    "saved": "{{name}} gespeichert."
+    "saved": "{{name}} gespeichert.",
+    "skipped_one": "{{count}} entry skipped: kind {{kinds}} is not read by this version",
+    "skipped_other": "{{count}} entries skipped: kind {{kinds}} is not read by this version",
+    "default": "Default",
+    "emptyKindBody": "Add a library of this kind, or pick another filter.",
+    "emptyKindTitle": "No libraries of this kind",
+    "formats": {
+      "library": "Library index",
+      "gallery": "Gallery index"
+    },
+    "gallery": "Gallery index",
+    "kind": {
+      "addon": "Add-on",
+      "backend": "Backend",
+      "model": "Model"
+    },
+    "kindFilter": "Filter by kind",
+    "kinds": {
+      "all": "All",
+      "addon": "Add-ons",
+      "backend": "Backends",
+      "model": "Models"
+    },
+    "officialOff": "Official libraries are off in Settings. The default libraries stay listed, shown as off, and are not read. Libraries you added are not affected.",
+    "removeDefaultBody": "This is a default library that comes with LocalAI. It is removed from the list and stays removed at the next start. You can restore it from the list. Installed items are not touched.",
+    "removedDefault": "Removed {{name}}. It stays removed at the next start; restore it to bring it back.",
+    "restore": "Restore",
+    "state": {
+      "enabled": "Enabled",
+      "disabled": "Disabled",
+      "removed": "Removed",
+      "suspended": "Off (official libraries are off)"
+    },
+    "turnOff": "Turn off",
+    "turnOn": "Turn on",
+    "turnedOff": "Turned off {{name}}.",
+    "turnedOn": "Turned on {{name}}."
   },
   "manage": {
     "api": "Add-on-API",

core/http/react-ui/public/locales/en/addons.json

@@ -67,7 +67,7 @@
     "details": "Details",
     "detailsLead": "Library entry for {{id}}",
     "emptyBody": "Add a library on the Libraries tab, then refresh it.",
-    "emptyTitle": "No add-ons found",
+    "emptyTitle": "No library entries found",
     "fromLibrary": "from {{library}}",
     "install": "Install",
     "installedDetail": "Version {{version}}, generation {{generation}}",
@@ -76,7 +76,18 @@
     "installedSame": "Installed {{version}}",
     "installedState": "Installed",
     "installing": "Installing",
-    "search": "Search the libraries"
+    "search": "Search the libraries",
+    "kind": {
+      "addon": "Add-on",
+      "backend": "Backend"
+    },
+    "installedBackend": "Installed",
+    "installedBackendNote": "Installed as a backend on this node. Models can use it now.",
+    "confirmBackendBody": "Version {{version}} of the backend from the library {{library}} will be downloaded, checked against its digest and signature, and installed on this node. The backend gallery is not changed.",
+    "confirmBackendNote": "A backend runs native code with the rights of LocalAI. Install it only from a library you trust.",
+    "backendFailed": "The backend was not installed.",
+    "alias": "Alias",
+    "kindLabel": "Kind"
   },
   "catalog": {
     "allLibraries": "All libraries",
@@ -143,10 +154,13 @@
   "libraries": {
     "add": "Add a library",
     "addTitle": "Add a library",
+    "default": "Default",
     "disabled": "Disabled",
     "edit": "Edit",
     "editTitle": "Edit {{name}}",
-    "emptyBody": "Add a library to browse and install add-ons.",
+    "emptyBody": "Add a library to browse and install add-ons, backends and models.",
+    "emptyKindBody": "Add a library of this kind, or pick another filter.",
+    "emptyKindTitle": "No libraries of this kind",
     "emptyTitle": "No libraries",
     "enabled": "Enabled",
     "errors": {
@@ -156,7 +170,10 @@
       "required": "Required when a signature is required.",
       "url": "Enter an http or https address.",
       "urlCredentials": "The address must not contain a user name or password.",
-      "urlQuery": "The address must not contain a query string or fragment."
+      "urlQuery": "The address must not contain a query string or fragment.",
+      "either": "Use the exact identity or the pattern, not both.",
+      "urlEmpty": "Enter the address of the index.",
+      "mirrors": "Each mirror must start with https://, http://, github:, oci:// or file://, and at most 8 are allowed."
     },
     "fields": {
       "enabled": "Enabled",
@@ -166,28 +183,74 @@
       "name": "Name",
       "reference": "Credential reference (optional)",
       "requireSignature": "Require a signature",
-      "url": "Catalog URL"
+      "url": "Catalog URL",
+      "identityRegex": "Signer identity pattern (optional)",
+      "kind": "Kind",
+      "format": "Index format",
+      "mirrors": "Mirrors"
     },
+    "formats": {
+      "library": "Library index",
+      "gallery": "Gallery index"
+    },
+    "gallery": "Gallery index",
     "hints": {
       "id": "Lowercase letters, digits and hyphens. It cannot change later.",
       "reference": "The name of a credential the owner configured. Never paste a token or password here.",
-      "url": "An https address without credentials or a query string."
+      "url": "An https address without credentials or a query string.",
+      "identityRegex": "An anchored pattern, from ^ to $, used instead of the exact identity. Backend libraries use it so builds from master and from tags both verify.",
+      "format": "A library index uses the shared library entry shape. A gallery index is a model or backend gallery, as the gallery flags name it.",
+      "mirrors": "Fallback addresses, one per line, tried in order when the main address cannot be fetched."
+    },
+    "kind": {
+      "addon": "Add-on",
+      "backend": "Backend",
+      "model": "Model"
+    },
+    "kindFilter": "Filter by kind",
+    "kinds": {
+      "all": "All",
+      "addon": "Add-ons",
+      "backend": "Backends",
+      "model": "Models"
     },
     "lastRefresh": "Refreshed {{when}}, {{count}} entries",
-    "lead": "A library is a catalog document that lists add-ons. Credentials are never typed here: a private library names a credential the owner configured.",
+    "lead": "A library is an index that lists add-ons, backends or models. Credentials are never typed here: a private add-on library names a credential the owner configured.",
     "listLabel": "Libraries",
     "loading": "Loading libraries",
     "notRefreshed": "Not refreshed yet",
+    "officialOff": "Official libraries are off in Settings. The default libraries stay listed, shown as off, and are not read. Libraries you added are not affected.",
     "reference": "Credential reference: {{name}}",
     "refresh": "Refresh",
     "refreshFailed": "Last refresh failed",
     "refreshed": "Refreshed {{name}}.",
     "remove": "Remove",
     "removeBody": "The library is removed from this list. Add-ons that were installed from it stay installed and keep running.",
+    "removeDefaultBody": "This is a default library that comes with LocalAI. It is removed from the list and stays removed at the next start. You can restore it from the list. Installed items are not touched.",
     "removeTitle": "Remove {{name}}?",
     "removed": "Removed {{name}}.",
+    "removedDefault": "Removed {{name}}. It stays removed at the next start; restore it to bring it back.",
+    "restore": "Restore",
     "save": "Save",
-    "saved": "Saved {{name}}."
+    "saved": "Saved {{name}}.",
+    "skipped_one": "{{count}} entry skipped: kind {{kinds}} is not read by this version",
+    "skipped_other": "{{count}} entries skipped: kind {{kinds}} is not read by this version",
+    "state": {
+      "enabled": "Enabled",
+      "disabled": "Disabled",
+      "removed": "Removed",
+      "suspended": "Off (official libraries are off)"
+    },
+    "turnOff": "Turn off",
+    "turnOn": "Turn on",
+    "turnedOff": "Turned off {{name}}.",
+    "turnedOn": "Turned on {{name}}.",
+    "manage": "Manage libraries",
+    "manageTitle": {
+      "backend": "Backend libraries",
+      "model": "Model libraries",
+      "addon": "Add-on libraries"
+    }
   },
   "manage": {
     "api": "Add-on API",
@@ -534,5 +597,27 @@
       "network": "The network is not reachable.",
       "unavailable": "The add-on owner is not available. Try again."
     }
+  },
+  "install": {
+    "stepsLabel": "Install steps",
+    "step": {
+      "resolving": "Resolve the library entry",
+      "verifying": "Verify the signature",
+      "size": "Check the image size",
+      "fetching": "Fetch the image",
+      "writing": "Write the metadata"
+    },
+    "state": {
+      "pending": "Waiting",
+      "active": "Running",
+      "done": "Done",
+      "failed": "Failed"
+    }
+  },
+  "settingsView": {
+    "loadFailed": "The library sources could not be read.",
+    "none": "No library sources of this kind.",
+    "listLabel": "Library sources",
+    "mirrors": "Mirrors: {{list}}"
   }
 }

core/http/react-ui/public/locales/en/models.json

@@ -180,6 +180,7 @@
   "empty": {
     "title": "No models found",
     "withFilters": "No models match your current search or filters.",
+    "library": "The library {{name}} has no models on this page.",
     "collapsedVariantsHint": "Alternative builds that another entry already offers are hidden. Turn off \"One row per model\" to include them.",
     "noFilters": "The model gallery is empty."
   },