> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lasscyber.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> How the Python and TypeScript SDKs version, how the API contract version works, and the deprecation cadence.

The Agnes SDKs follow [Semantic Versioning 2.0](https://semver.org/).
Each language package versions **independently** — Python
`agnes-security` 1.3 and TypeScript `@lasscyber/agnes-security` 1.1 are
perfectly valid at the same time.

## What changes a version number

* **MAJOR** (`X.y.z` → `(X+1).0.0`) — removed public symbols, renamed
  parameters, breaking behaviour changes, Python / Node minimum
  version bumps.
* **MINOR** (`x.Y.z` → `x.(Y+1).0`) — new public surface, additional
  optional parameters, new error subclasses, new canonical analyzer
  names. Fully backwards compatible with code using the prior minor.
* **PATCH** (`x.y.Z` → `x.y.(Z+1)`) — bug fixes, doc updates, internal
  refactors with no observable change.

## API version vs SDK version

* The SDK version is independent from the **server API version**.
* Server APIs are versioned by a **date** string (`info.version` in
  the OpenAPI document, currently `2026-04-16`).
* Pin an API version on a client to decouple your code from server
  evolution:

  ```python theme={null}
  Agnes(api_version="2026-04-16")
  ```

  ```ts theme={null}
  new Agnes({ apiVersion: "2026-04-16" })
  ```

  The value is sent as the `Agnes-Version` HTTP header on every
  request. The server records it today; future minor API changes will
  branch on it to keep older clients working.

## Deprecation cadence

* New deprecations ship in a MINOR release behind a runtime warning
  (`warnings.warn` in Python, `console.warn` in TypeScript) plus a
  CHANGELOG mention.
* Deprecated symbols are removed in the next MAJOR release, **at least
  six months** after the first deprecation warning.
* Dropping a Python minor or a Node major counts as a breaking
  change.

## Analyzer name evolution

Canonical analyzer names (the `prompt-injection-jailbreak` /
`safe-responsible-ai` / etc. set) are part of the SDK's public contract:

* Adding a new canonical name is a **MINOR** change.
* Renaming a canonical name is a **MAJOR** change; the old name must
  remain as an alias for one MAJOR.
* Server-side renames (e.g.
  `adversarial_detection_analyzer` → `prompt_injection_jailbreak`)
  are invisible to SDK users; only the mapping table flips.

The canonical mapping lives at
[`sdk/openapi/analyzer_names.json`](https://github.com/lasscyber/agnes-docs/tree/main/policy-fixtures);
both SDKs generate their `_names` modules from it.

## Release process

The release cadence is the same for both SDKs:

1. Update `CHANGELOG.md` in the target package.
2. Bump the version in `pyproject.toml` / `package.json` /
   `VERSION` constant.
3. Open a PR tagged `release/python` or `release/typescript`.
4. Merge → CI tags `python-vX.Y.Z` / `ts-vX.Y.Z` and publishes to
   PyPI / npm via trusted publisher.

## Picking a version constraint

In `requirements.txt` / `pyproject.toml`:

```
agnes-security>=2.0,<3.0
```

In `package.json`:

```
"@lasscyber/agnes-security": "^2.0"
```

A caret / `<MAJOR+1` constraint is the recommended default. It picks
up new analyzer names and additional convenience methods automatically
while protecting you from breaking renames.

## Reading the changelog

Both SDKs ship a `CHANGELOG.md` in the package source. The PyPI and
npm release pages also surface it. CHANGELOG entries follow a simple
format:

```markdown theme={null}
## [1.4.0] - 2026-05-01

### Added
- New canonical analyzer name `semantic-threat-intelligence`.

### Changed
- `Decision.blocked_by` now returns canonical names instead of
  server keys.

### Deprecated
- `Decision.blocked_by_legacy` — will be removed in 2.0.
```

If you ever spot a *Removed* entry in a MINOR release, it's a bug —
file an issue.

## Need help?

* See [API reference](/api-reference/overview) for the wire contract.
* See [Errors](/errors/overview) for stable error codes.
* See [Authentication](/get-started/authentication) for `Agnes-Version`
  pinning.