diff --git a/.agents/ai-coding-assistants.md b/.agents/ai-coding-assistants.md new file mode 100644 index 000000000..d0d9c882c --- /dev/null +++ b/.agents/ai-coding-assistants.md @@ -0,0 +1,101 @@ +# AI Coding Assistants + +This document provides guidance for AI tools and developers using AI +assistance when contributing to LocalAI. + +**LocalAI follows the same guidelines as the Linux kernel project for +AI-assisted contributions.** See the upstream policy here: + + +The rules below mirror that policy, adapted to LocalAI's license and +project layout. If anything is unclear, the kernel document is the +authoritative reference for intent. + +AI tools helping with LocalAI development should follow the standard +project development process: + +- [CONTRIBUTING.md](../CONTRIBUTING.md) — development workflow, commit + conventions, and PR guidelines +- [.agents/coding-style.md](coding-style.md) — code style, editorconfig, + logging, and documentation conventions +- [.agents/building-and-testing.md](building-and-testing.md) — build and + test procedures + +## Licensing and Legal Requirements + +All contributions must comply with LocalAI's licensing requirements: + +- LocalAI is licensed under the **MIT License** — see the [LICENSE](../LICENSE) + file +- New source files should use the SPDX license identifier `MIT` where + applicable to the file type +- Contributions must be compatible with the MIT License and must not + introduce code under incompatible licenses (e.g., GPL) without an + explicit discussion with maintainers + +## Signed-off-by and Developer Certificate of Origin + +**AI agents MUST NOT add `Signed-off-by` tags.** Only humans can legally +certify the Developer Certificate of Origin (DCO). The human submitter +is responsible for: + +- Reviewing all AI-generated code +- Ensuring compliance with licensing requirements +- Adding their own `Signed-off-by` tag (when the project requires DCO) + to certify the contribution +- Taking full responsibility for the contribution + +AI agents MUST NOT add `Co-Authored-By` trailers for themselves either. +A human reviewer owns the contribution; the AI's involvement is recorded +via `Assisted-by` (see below). + +## Attribution + +When AI tools contribute to LocalAI development, proper attribution helps +track the evolving role of AI in the development process. Contributions +should include an `Assisted-by` tag in the commit message trailer in the +following format: + +``` +Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2] +``` + +Where: + +- `AGENT_NAME` — name of the AI tool or framework (e.g., `Claude`, + `Copilot`, `Cursor`) +- `MODEL_VERSION` — specific model version used (e.g., + `claude-opus-4-7`, `gpt-5`) +- `[TOOL1] [TOOL2]` — optional specialized analysis tools invoked by the + agent (e.g., `golangci-lint`, `staticcheck`, `go vet`) + +Basic development tools (git, go, make, editors) should **not** be listed. + +### Example + +``` +fix(llama-cpp): handle empty tool call arguments + +Previously the parser panicked when the model returned a tool call with +an empty arguments object. Fall back to an empty JSON object in that +case so downstream consumers receive a valid payload. + +Assisted-by: Claude:claude-opus-4-7 golangci-lint +Signed-off-by: Jane Developer +``` + +## Scope and Responsibility + +Using an AI assistant does not reduce the contributor's responsibility. +The human submitter must: + +- Understand every line that lands in the PR +- Verify that generated code compiles, passes tests, and follows the + project style +- Confirm that any referenced APIs, flags, or file paths actually exist + in the current tree (AI models may hallucinate identifiers) +- Not submit AI output verbatim without review + +Reviewers may ask for clarification on any change regardless of how it +was produced. "An AI wrote it" is not an acceptable answer to a design +question. diff --git a/AGENTS.md b/AGENTS.md index 207f5e83e..fbd2146b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,11 +1,23 @@ # LocalAI Agent Instructions -This file 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. +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](CONTRIBUTING.md) for the development workflow. + +## Policy for AI-Assisted Contributions + +LocalAI follows the Linux kernel project's [guidelines for AI coding assistants](https://docs.kernel.org/process/coding-assistants.html). Before submitting AI-assisted code, read [.agents/ai-coding-assistants.md](.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: ` 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](.agents/ai-coding-assistants.md) | Policy for AI-assisted contributions — licensing, DCO, attribution | | [.agents/building-and-testing.md](.agents/building-and-testing.md) | Building the project, running tests, Docker builds for specific platforms | | [.agents/adding-backends.md](.agents/adding-backends.md) | Adding a new backend (Python, Go, or C++) — full step-by-step checklist | | [.agents/coding-style.md](.agents/coding-style.md) | Code style, editorconfig, logging, documentation conventions | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a04bee185..775367b0b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,6 +13,7 @@ Thank you for your interest in contributing to LocalAI! We appreciate your time - [Development Workflow](#development-workflow) - [Creating a Pull Request (PR)](#creating-a-pull-request-pr) - [Coding Guidelines](#coding-guidelines) +- [AI Coding Assistants](#ai-coding-assistants) - [Testing](#testing) - [Documentation](#documentation) - [Community and Communication](#community-and-communication) @@ -185,7 +186,7 @@ Before jumping into a PR for a massive feature or big change, it is preferred to This project uses an [`.editorconfig`](.editorconfig) file to define formatting standards (indentation, line endings, charset, etc.). Please configure your editor to respect it. -For AI-assisted development, see [`CLAUDE.md`](CLAUDE.md) for agent-specific guidelines including build instructions and backend architecture details. +For AI-assisted development, see [`AGENTS.md`](AGENTS.md) (or the equivalent [`CLAUDE.md`](CLAUDE.md) symlink) for agent-specific guidelines including build instructions and backend architecture details. Contributions produced with AI assistance must follow the rules in the [AI Coding Assistants](#ai-coding-assistants) section below. ### General Principles @@ -211,6 +212,26 @@ For AI-assisted development, see [`CLAUDE.md`](CLAUDE.md) for agent-specific gui - Reviewers will check for correctness, test coverage, adherence to these guidelines, and clarity of intent. - Be responsive to review feedback and keep discussions constructive. +## AI Coding Assistants + +LocalAI follows the **same guidelines as the Linux kernel project** for AI-assisted contributions: . + +The full policy for this repository lives in [`.agents/ai-coding-assistants.md`](.agents/ai-coding-assistants.md). Summary: + +- **AI agents MUST NOT add `Signed-off-by` tags.** Only humans can certify the Developer Certificate of Origin. +- **AI agents MUST NOT add `Co-Authored-By` trailers** attributing themselves as co-authors. +- **Attribute AI involvement with an `Assisted-by` trailer** in the commit message: + + ``` + Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2] + ``` + + Example: `Assisted-by: Claude:claude-opus-4-7 golangci-lint` + + Basic development tools (git, go, make, editors) should not be listed. +- **The human submitter is responsible** for reviewing, testing, and fully understanding every line of AI-generated code — including verifying that any referenced APIs, flags, or file paths actually exist in the tree. +- Contributions must remain compatible with LocalAI's **MIT License**. + ## Testing All new features and bug fixes should include test coverage. The project uses [Ginkgo](https://onsi.github.io/ginkgo/) as its test framework. diff --git a/docs/content/reference/_index.md b/docs/content/reference/_index.md index efc16d9e5..d8a280377 100644 --- a/docs/content/reference/_index.md +++ b/docs/content/reference/_index.md @@ -130,6 +130,19 @@ Reference for system information commands and diagnostics. --- +### 🤖 [AI Coding Assistants](ai-coding-assistants.md) +Policy for AI-assisted contributions — licensing, DCO, and attribution. + +**Key topics:** +- Aligned with the Linux kernel's AI assistants policy +- Signed-off-by and DCO rules +- `Assisted-by` commit trailer format +- Scope and responsibility of the human submitter + +**Recommended for:** Contributors using AI coding assistants (Claude, Copilot, Cursor, Codex, etc.) + +--- + ## Quick Links | Task | Documentation | @@ -138,6 +151,7 @@ Reference for system information commands and diagnostics. | CLI commands | [CLI Reference](cli-reference.md) | | Check compatibility | [Compatibility Table](compatibility-table.md) | | System diagnostics | [System Info](system-info.md) | +| Contribute with AI assistance | [AI Coding Assistants](ai-coding-assistants.md) | --- diff --git a/docs/content/reference/ai-coding-assistants.md b/docs/content/reference/ai-coding-assistants.md new file mode 100644 index 000000000..bb235ab87 --- /dev/null +++ b/docs/content/reference/ai-coding-assistants.md @@ -0,0 +1,79 @@ + ++++ +disableToc = false +title = "AI Coding Assistants" +weight = 28 ++++ + +This document provides guidance for AI tools and developers using AI assistance when contributing to LocalAI. + +**LocalAI follows the same guidelines as the Linux kernel project for AI-assisted contributions.** See the upstream policy here: . The rules below mirror that policy, adapted to LocalAI's license and project layout. + +AI tools helping with LocalAI development should follow the standard project development process: + +- [CONTRIBUTING.md](https://github.com/mudler/LocalAI/blob/master/CONTRIBUTING.md) — development workflow, commit conventions, and PR guidelines +- [AGENTS.md](https://github.com/mudler/LocalAI/blob/master/AGENTS.md) — the agent entry point with links to all detailed topic guides +- [.agents/ai-coding-assistants.md](https://github.com/mudler/LocalAI/blob/master/.agents/ai-coding-assistants.md) — the full policy source of truth + +## Licensing and Legal Requirements + +All contributions must comply with LocalAI's licensing requirements: + +- LocalAI is licensed under the **MIT License** +- New source files should use the SPDX license identifier `MIT` where applicable to the file type +- Contributions must be compatible with the MIT License and must not introduce code under incompatible licenses (e.g., GPL) without an explicit discussion with maintainers + +## Signed-off-by and Developer Certificate of Origin + +**AI agents MUST NOT add `Signed-off-by` tags.** Only humans can legally certify the Developer Certificate of Origin (DCO). The human submitter is responsible for: + +- Reviewing all AI-generated code +- Ensuring compliance with licensing requirements +- Adding their own `Signed-off-by` tag (when the project requires DCO) to certify the contribution +- Taking full responsibility for the contribution + +AI agents MUST NOT add `Co-Authored-By` trailers for themselves either. A human reviewer owns the contribution; the AI's involvement is recorded via `Assisted-by` (see below). + +## Attribution + +When AI tools contribute to LocalAI development, proper attribution helps track the evolving role of AI in the development process. Contributions should include an `Assisted-by` tag in the commit message trailer in the following format: + +``` +Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2] +``` + +Where: + +- `AGENT_NAME` — name of the AI tool or framework (e.g., `Claude`, `Copilot`, `Cursor`) +- `MODEL_VERSION` — specific model version used (e.g., `claude-opus-4-7`, `gpt-5`) +- `[TOOL1] [TOOL2]` — optional specialized analysis tools invoked by the agent (e.g., `golangci-lint`, `staticcheck`, `go vet`) + +Basic development tools (git, go, make, editors) should **not** be listed. + +### Example + +``` +fix(llama-cpp): handle empty tool call arguments + +Previously the parser panicked when the model returned a tool call with +an empty arguments object. Fall back to an empty JSON object in that +case so downstream consumers receive a valid payload. + +Assisted-by: Claude:claude-opus-4-7 golangci-lint +Signed-off-by: Jane Developer +``` + +## Scope and Responsibility + +Using an AI assistant does not reduce the contributor's responsibility. The human submitter must: + +- Understand every line that lands in the PR +- Verify that generated code compiles, passes tests, and follows the project style +- Confirm that any referenced APIs, flags, or file paths actually exist in the current tree (AI models may hallucinate identifiers) +- Not submit AI output verbatim without review + +Reviewers may ask for clarification on any change regardless of how it was produced. "An AI wrote it" is not an acceptable answer to a design question. + +{{% notice note %}} +This policy is a living document. If you're unsure how to apply it to a specific contribution, open an issue or ask in the [Discord channel](https://discord.gg/uJAeKSAGDy) before submitting. +{{% /notice %}}