mirror of https://github.com/mudler/LocalAI.git synced 2026-08-01 02:49:51 -04:00

Files

mudler's LocalAI [bot] 94d5affcea feat(website): split the site, move docs to /docs, add a landing page (#11243 )

* feat(website): split the site, move docs to /docs, add a landing page

The Hugo docs site has always been localai.io itself, which left nowhere to
explain what LocalAI is or show what the team builds. This adds a separate
marketing site at the root and moves the documentation under /docs/.

Docs:
  The existing site keeps its content tree and its Relearn theme, and now
  builds with baseURL <root>/docs/. Its _index.md, which held a hand written
  landing page, becomes a real documentation home.

  Every previously published URL keeps working. GitHub Pages has no server
  side rewrites, so .github/ci/gen-redirects.sh walks the built docs output
  and leaves a meta refresh plus a canonical link at each old root path. It
  covers bare .html files too, which is what keeps /gallery.html alive, and
  it never overwrites a path the marketing site already owns.

Website:
  A second Hugo site under website/ with its own layouts and no external
  theme, so the marketing side does not have to fight Relearn's home rooted
  menu and asset pipeline. CI builds both and merges them into one Pages
  artifact.

  The design is derived from the project logo rather than invented: the navy
  of the triangle, the cyan of the llama, the purple of the speed bars. Those
  offset bars became the motion signature. The background renders a real
  depth-anything.cpp depth map as contour lines and switches to a
  locate-anything.cpp style detection overlay over the engines section.

  Also included: an /engines/ index driven entirely by data/engines.yaml, a
  /blog/ section with five posts written from the release notes and the
  engine benchmark suites, install.sh and a Kubernetes manifest since the
  site advertises both, and a rule in .agents/ that release preparation now
  includes a blog post and demo clips.

Every figure on the site is derived from the repository or the GitHub API,
not from memory. Correcting them against their sources found one error in
README.md: voxtral-tts.c is text to speech, not speech to text.

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>
Assisted-by: Claude Code:claude-opus-5 [Bash] [Edit] [Write] [Agent]

* feat(website): add a star history chart, rewrite the history post in first person

The history post read like a changelog written by a committee. It is now in
Ettore's voice, first person, with the admissions left in.

The numbers paragraph in particular read like a directory listing. It now says
what the figures mean rather than which file they came from.

Adds an interactive star history chart, built from the GitHub stargazers API
rather than embedded from a third party, so the page makes no external request
and cannot break when someone else's service is down. The four releases the
post is organised around are marked on the curve, and the labels stack into
rows because three of them land within two months of each other.

The API stops paginating at 40,000 items, so the curve is measured up to
December 2025 and the segment from there to today's total is drawn dashed,
labelled as an estimate in the caption and in the tooltip. It is a straight
line between two known points, and the chart says so rather than implying it
is data.

Also drops "marketing site" from the README heading and everywhere else it
appeared, and calls it the main site instead.

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

---------

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

2026-07-31 09:00:56 +02:00

7.4 KiB

Raw Blame History

LocalAI Agent Instructions

This file is the entry point for AI coding assistants (Claude Code, Cursor, Copilot, Codex, Aider, etc.) working on LocalAI. It is an index to detailed topic guides in the .agents/ directory. Read the relevant file(s) for the task at hand — you don't need to load all of them.

Human contributors: see CONTRIBUTING.md for the development workflow.

Policy for AI-Assisted Contributions

LocalAI follows the Linux kernel project's guidelines for AI coding assistants. Before submitting AI-assisted code, read .agents/ai-coding-assistants.md. Key rules:

No Signed-off-by from AI. Only the human submitter may sign off on the Developer Certificate of Origin.
No Co-Authored-By: <AI> trailers. The human contributor owns the change.
Use an Assisted-by: trailer to attribute AI involvement. Format: Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2].
The human submitter is responsible for reviewing, testing, and understanding every line of generated code.

Topics

File	When to read
.agents/ai-coding-assistants.md	Policy for AI-assisted contributions — licensing, DCO, attribution
.agents/building-and-testing.md	Building the project, running tests, Docker builds for specific platforms
.agents/ci-caching.md	CI build cache layout (registry-backed BuildKit cache on quay.io/go-skynet/ci-cache, per-arch keys), `DEPS_REFRESH` weekly cache-buster for unpinned Python deps, prebuilt `base-grpc-*` images for llama.cpp variants, per-arch native + manifest-merge pattern, `setup-build-disk` `/mnt` relocation, path filter on master push, manual eviction
.agents/adding-backends.md	Adding a new backend (Python, Go, or C++) — full step-by-step checklist, including importer integration (the `/import-model` dropdown is server-driven from `GET /backends/known`)
.agents/coding-style.md	Code style, editorconfig, logging, documentation conventions
.agents/llama-cpp-backend.md	Working on the llama.cpp backend — architecture, updating, tool call parsing
.agents/vllm-backend.md	Working on the vLLM / vLLM-omni backends — native parsers, ChatDelta, CPU build, libnuma packaging, backend hooks
.agents/sglang-backend.md	Working on the SGLang backend — `engine_args` validation against ServerArgs, speculative-decoding (EAGLE/EAGLE3/DFLASH/MTP) recipes, parser handling
.agents/ds4-backend.md	Working on the ds4 backend - DSML state machine, thinking modes, KV cache, Metal+CUDA matrix
.agents/testing-mcp-apps.md	Testing MCP Apps (interactive tool UIs) in the React UI
.agents/api-endpoints-and-auth.md	Adding API endpoints, auth middleware, feature permissions, user access control
.agents/debugging-backends.md	Debugging runtime backend failures, dependency conflicts, rebuilding backends
.agents/adding-gallery-models.md	Adding GGUF models from HuggingFace to the model gallery
.agents/localai-assistant-mcp.md	LocalAI Assistant chat modality — adding admin tools to the in-process MCP server, editing skill prompts, keeping REST + MCP + skills in sync
.agents/backend-signing.md	Backend OCI image signing (keyless cosign + sigstore-go) — producer-side CI setup, consumer-side gallery `verification:` block, strict mode (`LOCALAI_REQUIRE_BACKEND_INTEGRITY`), revocation via `not_before`
.agents/preparing-a-release.md	Cutting a release: PR labels, `RELEASE_NOTES_vX.Y.Z.md`, the blog post under `website/content/blog/`, and the demo clips under `website/static/media/`

Quick Reference

Coverage gates: Never lower a coverage baseline or widen a gate's tolerance to turn a red gate green — the coverage ratchet only moves up. If a change drops coverage, add tests to raise it (e.g. render-smoke specs). See .agents/building-and-testing.md.
Logging: Use github.com/mudler/xlog (same API as slog)
Go style: Prefer any over interface{}
Comments: Explain why, not what
Docs (docs-with-code rule): When you change user-facing behavior (API endpoints, CLI flags, config keys, or features), update the corresponding page under docs/content/ in the SAME change, not as a follow-up. A user-facing change without a matching docs update is incomplete. See also the documentation conventions in .agents/coding-style.md.
New API endpoints: LocalAI advertises its capability surface in several independent places — swagger @Tags, /api/instructions registry, auth RouteFeatureRegistry, React UI capabilities.js, docs. Read .agents/api-endpoints-and-auth.md and follow its checklist — missing any surface means clients, admins, and the UI won't know the endpoint exists.
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 — 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.
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.
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.
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

7.4 KiB Raw Blame History

LocalAI Agent Instructions

Policy for AI-Assisted Contributions

Topics

Quick Reference

7.4 KiB

Raw Blame History