API stability

What a version number promises

From 1.0.0, LLMSlim follows semantic versioning for its public API: the modules listed below, and in each one only the names in its __all__.

A breaking change is anything that can stop correct code from working: removing or renaming a public name, parameter, command, flag, route, MCP tool or environment variable; adding a required parameter; narrowing what a parameter accepts; or changing a return type or a flag's meaning. Adding names, keyword parameters with defaults, fields, routes or tools is not.

How anything is removed

Deprecate in a minor release, keep it for at least two minor releases and at least 90 days, whichever is longer, and remove it only in a major release. The old name keeps working and raises a DeprecationWarning that names its replacement and the release that removes it. Each step is in the CHANGELOG. The same policy covers flags, HTTP routes and fields, MCP tools and their inputs, and environment variables.

DeprecationWarning: llmslim.squeeze is deprecated since llmslim 1.2 and will be removed in 2.0; use llmslim.fit instead.

Stable modules

In each, the names in __all__ are stable, except those listed as experimental below.

Experimental

Importable and documented, but a minor release may change or remove it, and the CHANGELOG says so each time:

• llmslim.proxy, and the llmslim proxy and llmslim wrap commands.
• The chat endpoint of llmslim serve: /v1/chat/completions, /v1/models, their X-LLMSlim-* headers and flags, ChatUpstream and the chat argument of create_app.
• llmslim mcp --transport http and its flags and variables.
• llmslim.tool_retrieval, llmslim.semantic_retrieval, tool ranking and selection in llmslim.tools, PlanMode.SELECTIVE and TransformersKVSession.

Internal

Everything else may change in any release: modules or names with a part starting with _; names a public module doesn't list in __all__, even without an underscore; and implementation modules such as llmslim.core, llmslim.runtime, llmslim.memory.stores and llmslim.memory.mongo, whose public names you import from llmslim, llmslim.planning or llmslim.memory.

Command line, HTTP, MCP and stored memory

The same promise covers the interfaces outside Python:

• Command line: llmslim, llmslim context, llmslim plan, llmslim tools, llmslim import, llmslim mcp and llmslim serve and their flags. --json output may gain fields but keeps the ones it has; human-readable output may change.
• HTTP: /healthz and the /v1 routes of llmslim serve other than the chat endpoint, their fields and error types. An incompatible change would come under /v2.
• MCP: the tool names, their input and output schemas and their hints, over stdio and HTTP. Tool descriptions are prompts for models and may change in a minor release.
• Stored memory: a store written by a 1.x release opens in every later 1.x release.
• The formats llmslim import reads belong to other tools, so what it reads from each is output content: a minor release may follow a change in a format.

The full contract, with every environment variable, is API_STABILITY.md. A test compares the live API with a recorded snapshot and fails on any difference.

The generated reference

Every public name of llmslim and llmslim.memory, with its signature, type annotations and docstring, generated from the source: llmslim and llmslim.memory.