mirror of
https://github.com/mudler/LocalAI.git
synced 2026-06-03 13:56:46 -04:00
5a0013defe
The UI coverage gate was tightened to 0.1pp against a fast-local measurement (39.86% baseline); CI's slower runners measure ~0.9pp lower, so tests-ui-e2e failed there. UI e2e coverage is diffusely non-deterministic and tracks machine speed — a 0.1pp band can't hold across environments. Rather than loosen the gate, raise the floor under it: a render-smoke spec mounts each lazy page (navigate + assert the header renders), covering a dozen previously-untested pages and lifting coverage from ~39% to ~42.7% locally. Restore the tolerance to 0.8pp and set the baseline conservatively (40.0), below the slow-CI floor, so the ratchet holds without flapping. Document the coverage policy — install the git hooks and don't bypass them (no --no-verify, no hand-lowering the baseline or widening the tolerance); raise coverage by adding tests instead; set the UI baseline below the slow-CI floor — in AGENTS.md, CONTRIBUTING.md and .agents/building-and-testing.md. Assisted-by: Claude:claude-opus-4-8 [Claude Code] Signed-off-by: Richard Palethorpe <io@richiejp.com>
5.7 KiB
5.7 KiB
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-byfrom 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 |
Quick Reference
- Git hooks & coverage gates: Run
make install-hooksonce per clone so the pre-commit lint + coverage gates run. Never bypass them withgit commit --no-verify, and 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
anyoverinterface{} - Comments: Explain why, not what
- Docs: Update
docs/content/when adding features or changing config - New API endpoints: LocalAI advertises its capability surface in several independent places — swagger
@Tags,/api/instructionsregistry, authRouteFeatureRegistry, React UIcapabilities.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 standalonelocal-ai mcp-serverconsume that package; drift between REST and MCP is a real risk. Read .agents/localai-assistant-mcp.md — theTestToolHTTPRouteMappingCompletetest fails until you wire the new tool and update the route map. - Build: Inspect
Makefileand.github/workflows/— ask the user before running long builds - UI: The active UI is the React app in
core/http/react-ui/. The older Alpine.js/HTML UI incore/http/static/is pending deprecation — all new UI work goes in the React UI