Python SDK (velt-py) Changelog

​

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 →
• [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 →
• [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 →

​

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 →
• [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 →

​

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 →
• [REST API]: New memory service (sdk.api.memory) for semantic search, judgments, knowledge ingestion, reviewer profiles/patterns/stats, and alerts (24 methods). Learn more →
• [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 →
• [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 →
• [REST API]: documents service adds getDocumentsCount, which can optionally exclude folder documents or scope the count to a specific folder. Learn more →
• [REST API]: crdt service adds deleteCrdtData, which targets specific editorIds or deletes all editors for a document when omitted. Learn more →
• [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 →

​

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 →
• [Self Hosting]: New PartialTargetTextRange dataclass (exported from velt_py.models) represents the selected text snippet a comment annotation is anchored to. Learn more →

​

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

​

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 →
• [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.