# API stability

> **Upcoming in 1.0 (preview). These pages describe the main branch of LLMSlim Core, which becomes the 0.13 release candidate and then 1.0. `pip install llmslim` installs 0.12.0 today, which doesn't have everything described here.** Docs for what pip installs: https://www.llmslim.app/docs.md

> What 1.0 freezes, what stays experimental, and how anything is ever removed.

LLMSlim's public API contract from 1.0: semantic versioning, the deprecation policy, experimental and internal API, and the command line, HTTP routes, MCP tools and stored memory.

Category: API Reference · Version: 1.0 · Updated: November 2026 · 5 min read

## 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__`.

| Release | May contain |
|---|---|
| Major (2.0.0) | Removals and incompatible changes to the stable API, each deprecated first. |
| Minor (1.1.0) | New features and additive changes, new deprecations, changes to experimental API. |
| Patch (1.0.1) | Bug fixes only: no API changes and no new deprecations. |

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.

a deprecation warning:

```text
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.

| Module | What it holds |
|---|---|
| `llmslim` | Compression, context planning, the agent context runtime, cache planning, token counting and the rewrite engine |
| `llmslim.memory` | `Memory`, its stores and result types |
| `llmslim.memory.compat` | `Mem0Memory`, the Mem0-compatible facade |
| `llmslim.planning`, `llmslim.context`, `llmslim.tokens` | The planner and its data model, context sources and stores, token counting |
| `llmslim.tools`, `llmslim.mcp` | Tool-schema contracts, and MCP catalog ingestion and planning |
| `llmslim.mcp_server`, `llmslim.server` | `build_server`, `fit_text`, `create_app`, and the `llmslim mcp` and `llmslim serve` entry points |
| `llmslim.integrations.*` | Each integration's documented classes, functions, result types and errors |

## 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](https://github.com/Thanatos9404/llmslim/blob/main/docs/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](https://www.llmslim.app/docs/1.0/api-llmslim) and [llmslim.memory](https://www.llmslim.app/docs/1.0/api-llmslim-memory).

## FAQ

### Is output text part of the API?

No. Which turns or sentences are kept, scores, token counts and the wording of messages may change in a minor release to improve results, and in a patch release only to fix a bug. Within one release, the same input and options give the same output.

### How do I see deprecation warnings?

Python shows `DeprecationWarning` by default only in `__main__` and test runners. Run with `python -W default::DeprecationWarning`, or set `PYTHONWARNINGS=default::DeprecationWarning`.

## Related

- [API reference: llmslim](https://www.llmslim.app/docs/1.0/api-llmslim.md)
- [API reference: llmslim.memory](https://www.llmslim.app/docs/1.0/api-llmslim-memory.md)
- [Upgrade from 0.x to 1.0](https://www.llmslim.app/docs/1.0/migrate-to-1-0.md)

Canonical page: https://www.llmslim.app/docs/1.0/api-stability