> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Python SDK (velt-py) Changelog
> Release notes for the velt-py Python SDK for self-hosting
### Libraries
* `velt-py`
### New Features
* \[**Self Hosting**]: New pluggable, fail-closed `sdk.selfHosting.verifyToken` helper authenticates the credential the Velt frontend forwards to endpoint-based self-hosting resolvers. Opt in via a `resolver_auth` config block; it supports a built-in JWT/JWKS verifier (HS256/RS256/ES256 with algorithm pinning, HTTPS-only JWKS, claim enforcement, leeway, opt-in `exp` requirement) and a custom-callback escape hatch. It returns a structured `VerifyTokenResult` and never raises for a verification outcome. Adds the optional `velt-py[auth]` extra (PyJWT>=2.8.0, cryptography>=42.0.0) and new exports `VerifyTokenResult` and `ResolverAuthService`. [Learn more →](/backend-sdks/python)
* \[**Self Hosting**]: New 14-member `CommentResolverSaveEvent` `(str, Enum)` covers additional comment-resolver save events (status change, priority change, assign, approve, comment-level reactions, subscribe/unsubscribe, and more) the frontend can opt into sending via `ResolverConfig.additionalSaveEvents`. `SaveCommentResolverRequest.event` is widened to `Optional[Union[ResolverActions, CommentResolverSaveEvent, str]]` and stays fully additive — every existing `ResolverActions` value still parses to the same member. Exported from `velt_py` and `velt_py.models`. [Learn more →](/backend-sdks/python)
* \[**Self Hosting**]: New optional `SaveCommentResolverRequest.targetComment: Optional[PartialComment]` field carries the comment the action occurred on (resolved by the frontend from `commentId`). `from_dict` parses it fail-open; it is request context for your handler only and `saveComments` never persists it. [Learn more →](/backend-sdks/python)
### Bug Fixes
* \[**Self Hosting**]: Legacy reaction documents stored under the old `user` key are read transparently. `from_dict()` accepts either `from` or the legacy `user` key (`from` wins when both are present) and populates `from_`, while `to_dict()` always emits `from`. No data migration is needed. [Learn more →](/backend-sdks/python)
* \[**Self Hosting**]: The self-hosting package now exports all wired services. `RecorderService`, `NotificationService`, and `ActivityService` are now importable from `velt_py.services.self_hosting` and listed in its `__all__`. [Learn more →](/backend-sdks/python)
### New Features
* \[**REST API**]: New `agents` service (`sdk.api.agents`) for managing AI agents, versions, executions, prompt tooling, and agent groups (24 methods). [Learn more →](/backend-sdks/python)
* \[**REST API**]: New `memory` service (`sdk.api.memory`) for semantic search, judgments, knowledge ingestion, reviewer profiles/patterns/stats, and alerts (24 methods). [Learn more →](/backend-sdks/python)
* \[**REST API**]: New `workflow` service (`sdk.api.workflow`) for Approval Engine / workflow orchestration, covering definitions, executions, lifecycle events, and step resolution (14 methods). [Learn more →](/backend-sdks/python)
* \[**REST API**]: `users` service additions for user invitations (invite/respond/list), counts, and document-user queries; `getUsers` gains optional `includeInvolvedDocuments` and `searchKey` filters. [Learn more →](/backend-sdks/python)
* \[**REST API**]: `documents` service adds `getDocumentsCount`, which can optionally exclude folder documents or scope the count to a specific folder. [Learn more →](/backend-sdks/python)
* \[**REST API**]: `crdt` service adds `deleteCrdtData`, which targets specific `editorIds` or deletes all editors for a document when omitted. [Learn more →](/backend-sdks/python)
* \[**REST API**]: `workspace` service adds 19 new methods covering domain requests, API key configuration/copy, notification/permission-provider/activity configs, and advanced (Svix) webhook endpoint management. [Learn more →](/backend-sdks/python)
### Improvements
* \[**REST API**]: New opt-in `filter_unknown_fields` keyword (default `False`) on the add/update methods of `commentAnnotations`, `activities`, and `notifications` filters request entity collections to only the fields the Velt API accepts, dropping unknown top-level custom keys. It applies to top-level fields only (nested open-typed fields pass through whole) and fails open, never blocking a write. Backed by a new `velt_py.models.field_allowlists` module.
### Bug Fixes
* \[**REST API**]: `sdk.api.workspace.getApiKeyMetadata` now targets the canonical `/v2/workspace/apikeyconfig/get` endpoint (previously `/v2/workspace/apikeymetadata/get`, which remains a legacy alias). No call-site change is required — the method signature is unchanged.
### New Features
* \[**Self Hosting**]: `PartialCommentAnnotation` now exposes `from` (comment author), `assignedTo`, `targetTextRange`, and `resolvedByUserId` as first-class typed fields. These four keys previously fell through silently via `extra_fields`. [Learn more →](/backend-sdks/python)
* \[**Self Hosting**]: New `PartialTargetTextRange` dataclass (exported from `velt_py.models`) represents the selected text snippet a comment annotation is anchored to. [Learn more →](/backend-sdks/python)
### Improvements
* \[**Self Hosting**]: `BaseMetadata` now models `sdkVersion` and `documentMetadata`, which were previously dropped silently; self-hosted Mongo writes now preserve both fields.
* \[**Self Hosting**]: Introduced an `UNSET` sentinel on `resolvedByUserId` to distinguish "field absent from payload" (no Mongo write) from "explicit null" (the frontend's unresolve action — writes null to Mongo).
### Bug Fixes
None.
### New Features
* \[**REST API Backend**]: The `sdk.api.*` namespace is now available, introducing a REST API backend for the Python SDK with feature parity with the Velt Node SDK. [Learn more →](/backend-sdks/python)
* \[**REST API Services**]: 17 services are included: `organizations`, `folders`, `documents`, `users`, `userGroups`, `notifications`, `commentAnnotations`, `activities`, `accessControl`, `crdt`, `presence`, `livestate`, `recordings`, `rewriter`, `gdpr`, `workspace`, and `token`.
* \[**Typed Request Dataclasses**]: Every `sdk.api.*` method accepts a typed `@dataclass` request object (e.g., `AddOrganizationsRequest`) and returns the raw Velt API response without local reshaping or validation.
* \[**camelCase Method Names**]: All `sdk.api.*` method names are camelCase and match the JavaScript/Node SDK one-to-one.
* \[**Custom Error Classes**]: Three new error classes are available: `VeltValidationError`, `VeltTokenError`, and `VeltApiError`, all extending the base `VeltSDKError`.
* \[**Environment Variable Support**]: The SDK reads `VELT_API_KEY`, `VELT_AUTH_TOKEN`, `VELT_WORKSPACE_ID`, and `VELT_WORKSPACE_AUTH_TOKEN` from the environment for credential configuration.
* \[**PyPI Distribution**]: The package is published to PyPI as `velt-py`. Requires Python 3.8+; the `requests` library is installed automatically as a dependency.