Locus follows Semantic Versioning (since 1.0, tagged 2026-06-09). This file explains how breaking changes and deprecations work.
- Major version bumps can remove deprecated API. Breaking changes
are called out in
CHANGELOG.mdunder the version that ships them, in a### Removedor### Changedsection, with a one-line migration note. - Minor version bumps can add deprecations but not remove API.
- Patch version bumps are bug fixes only.
Consumers should pin a major (locus-sdk>=5,<6) and read the
CHANGELOG before bumping across majors.
A deprecated API will:
- Still work for at least one full minor version.
- Emit
LocusDeprecationWarningon use. - Be listed in
CHANGELOG.mdwith its planned removal version and a migration snippet.
- The
locus.securitycompatibility shim;locus.controlis the import path. - The
locus.looppackage (ReActLoop,LoopRunner,BatchRunner,StreamingCollector, the nodes and the router);Agentis the supported loop. FallbackChain.last_tier; readresponse.metadata["fallback"]orlocus.models.fallback.served_tier().- The
toolkey on thetool.integrity.refusedpayload; readtool_name.
Agent(tool_call_integrity=...)defaults toTrue; passFalseto turn the check off. A hook that rewritesevent.argumentsnow callsevent.resign(by=...)afterwards, or the executor refuses the call.
Internal callers emit deprecation warnings like this:
from locus.core.warnings import LocusDeprecationWarning
import warnings
def old_api(...):
warnings.warn(
"old_api() is deprecated; use new_api() instead. "
"old_api() will be removed in Locus 1.1.",
LocusDeprecationWarning,
stacklevel=2,
)
return new_api(...)Consumers can opt into failing on deprecations during their own test suites:
import warnings
from locus.core.warnings import LocusDeprecationWarning
warnings.simplefilter("error", LocusDeprecationWarning)That turns every deprecated call into a test failure, so you find out before the removal release — not after.
Only names in a module's __all__ and in the top-level locus
namespace are public. Anything under a leading underscore
(_private), or inside a submodule that's not re-exported, is
implementation detail and can change in any release without
deprecation.
If you're importing from locus.core.reducers,
locus.tools.executor._internal, locus.agent.agent._parse_*, or
anything similar — that is your risk to carry.