Changelog

All notable changes to the Trustwise SDK will be documented in this file.

v4.11.0 (2026-09-18)

New Features

  • Runtime connectors (client.runtime_connectors) — a new organization-scoped resource for registering and deploying runtime connectors. Covers list, get, create, update, delete, deploy, status and update_status, plus test_connection for a pre-deploy connectivity check. Adds the RuntimeConnectorListItem, RuntimeConnectorGetResponse and RuntimeConnectorTestResponse models alongside the RuntimeConnectorCreateRequest, RuntimeConnectorUpdateRequest, RuntimeConnectorStatusUpdateRequest and RuntimeConnectorTestRequest payloads.

  • Connector wheel and TLS uploads — each connector artifact can be uploaded two ways: directly as multipart/form-data via upload_wheel and upload_tls, or through a presigned URL obtained from request_wheel_upload_url and request_tls_upload_url and PUT by the caller. upload_wheel takes an optional expected_sha256 the server verifies against; upload_tls takes kind (ca, client_cert or client_key). Adds WheelUploadResponse, WheelUploadUrlResponse, WheelUploadUrlRequest, TlsUploadResponse, TlsUploadUrlResponse and TlsUploadUrlRequest.

  • v2alpha evaluations (client.evaluations.v2_*) — the evaluation surface is now also served on /v2alpha, via v2_list, v2_get, v2_create, v2_update, v2_classification, v2_org_list and v2_list_for_agent. The existing /v1alpha methods are unchanged and still supported. The two versions differ in the payload accepted by create — PromptShieldEvaluationCreateRequest on v2alpha versus the new PromptShieldEvaluationCreateRequestV1Alpha on v1alpha — so they are exposed as separate methods rather than a version flag. Unlike their v1alpha counterparts, the v2alpha methods parse into Evaluation, EvaluationListItem and EvaluationReport rather than returning bare dictionaries.

  • Connector TLS configuration — HTTPConnectorRuntimeConfig gained a tls field, described by the new HTTPConnectorTLSConfig model (ca_bundle, client_cert, client_key), plus the new CustomGrpcRuntimeConfig and RpcTestResult models.

  • Encrypted auth material — ApiKeyAuth, BasicAuth, BearerAuth, NoAuth and ProviderAuth each gained an aes_key field, described by the new AesKey model.

  • Richer policy evaluation audit logs — PolicyEvaluationAuditLogSummary and PolicyEvaluationAuditLogDetail gained call_type and interaction_id.

  • Prompt classification bypass turn — PromptClassification gained first_bypass_turn, the index of the first turn that bypassed the shield.

  • Hypothesis-based sensitivity — TrustWiseEvaluatorParamConfig gained hypotheses, usable in place of topics.

Breaking Changes

  • None. No endpoints, models or fields were removed this release, and every schema change listed above is additive.

Other

  • The RBAC, Dashboard and Internal endpoint groups remain excluded from the generated SDK; the exclusion now covers 31 operations, up from 27, as the RBAC group grew upstream.

  • Two client methods call endpoints the spec no longer describes — guardrails.get_evaluation (GET /v1alpha/guardrails/{guardrail_id}/evaluations/{evaluation_id}) and agents.risk_classify (POST /v1alpha/projects/{project_id}/agents/{agent_id}/risk-classify). Both predate this release and are left in place; they are flagged here so the dead routes are tracked rather than silently retained.

  • Constrained string fields on the generated models are emitted as RootModel wrappers, so their value is reached through .root (for example WheelUploadResponse.wheel_sha256.root).

v4.10.0 (2026-09-04)

New Features

  • Partial updates for AI components — client.agents, client.models and client.mcp_servers each gained patch (project-scoped) and org_patch (organization-scoped). Unlike update, which replaces the record, patch changes only the fields supplied and leaves the rest untouched. Adds the AgentPatchRequest, ModelPatchRequest and MCPServerPatchRequest models.

  • Component version history — the same three resources gained versions and version (project-scoped) plus org_versions and org_version (organization-scoped), listing every revision of a component or fetching one by version. The list calls take the standard page, limit, sort_by and sort_order pagination, and a skip_keys filter that drops fields from each returned revision. Adds the PaginationParams model and the APIResponseBase_list_AgentResponse__ and APIResponseBase_list_MCPServerResponse__ envelopes.

  • Organization-wide evaluation listing — client.evaluations.org_list lists every evaluation in the organization, and client.guardrails.org_list_evaluations does the same for guardrail evaluations. Both accept the project-scoped filters plus project_ids to narrow to a set of projects.

  • Per-agent evaluation listing — client.evaluations.list_for_agent returns the evaluations recorded against a single agent, returning EvaluationListItem.

  • Assessment bundle export/import — client.assessments.export returns the bundle documents plus a presigned download URL per evidence file, and client.assessments.import_ bootstraps an assessment from an unzipped bundle, creating it in importing status and minting one presigned upload per evidence file. Adds AssessmentExportResponse, AssessmentImportRequest, AssessmentImportResponse, ExportEvidenceFile and ImportUpload. Bundle file contents must be written to the zip byte-for-byte — the result_hash.json digests are computed over those exact strings, so re-serializing them breaks verification on re-import.

  • Sensitivity custom hypotheses — metrics.sensitivity.evaluate (sync and async) accepts hypotheses, a list of full statements scored in place of bare topic labels; each hypothesis comes back as the label of its score. topics and hypotheses are mutually exclusive and exactly one must be supplied, so topics is now optional on SensitivityRequest. Omitting both raises TrustwiseValidationError (previously TypeError).

Breaking Changes

  • ``PromptShieldConfig`` prompt sourcing restructured. The thirteen flat generation fields — num_generate, benign_ratio, random_seed, custom_personas, max_num_personas, nl_policies, domain_taxonomy, required_inputs, system_prompt, custom_prompts, custom_goals, seed_only_prompts and seed_from_custom_prompts — moved into a nested prompts object discriminated on source. Pass {"source": "generate", ...} with the same field names to generate a set, or {"source": "reuse", "from_evaluation_id": ...} to reuse an existing evaluation’s prompts verbatim. The schema rejects unknown keys, so payloads using the old flat form now fail validation. Adds the GeneratePrompts and ReusePromptSet models.

  • ``PromptClassification.first_bypass_turn`` renamed to ``first_non_refusal_turn``. Same 0-based turn index, clearer name: it marks the first turn where a harmful prompt was not refused, so it counts the turns of pressure the agent withstood.

Other

  • Metric requests accept allow_unsafe_chunking — AdherenceRequest, ContextRelevancyRequest, FaithfulnessRequest, MetricEvaluationRequest, PIIRequest, QueryResponseRequest, TextRequest, TextRequestWithSeverity and ToneRequest.

  • New response fields: is_imported on Assessment, AssessmentListItem and AssessmentResponse; project_id on Evaluation and EvaluationListItem; project_ids on AgentListItem; roles on UserResponse (via the new UserRoleSummary model); reused on GenerationPlan; and prompt_set_from_evaluation_id on RequestedPlan.

  • No endpoints were removed from the spec this release, and no dependencies changed.

  • Every endpoint the spec exposes is now wrapped except the /, /health and /status infrastructure routes, which remain intentionally omitted.

v4.9.0 (2026-08-18)

New Features

  • Organization-scoped component catalogue — agents, models, and MCP servers now exist as organization-wide records in addition to their project-scoped form. client.agents, client.models and client.mcp_servers each gained org_list, org_get, org_create, org_update and org_delete, which address a component by ID with no project_id. The existing project-scoped methods are unchanged.

  • Component associations — all three resources gained org_associations, org_add_association and org_remove_association, plus the project-scoped associations, add_association and remove_association. An association names a target component, its type (agent, model, mcp_server, rest_api or message_queue) and the relationship (uses or depends_on). Adds the AIComponentAssociationRequest, AIComponentAssociationResponse, AIComponentAssociationType and AIComponentTypeValue models.

  • Project assignment — assign and unassign on client.agents, client.models and client.mcp_servers make an organization-scoped component available to a project, replacing creation-inside-a-project as the way a component reaches one. Adds AIComponentProjectAssignmentResponse.

  • Organization-scoped agent operations — client.agents gained org_query, org_status_history, org_update_status, org_assign_assessment and org_unassign_assessment, the ID-addressed counterparts of the existing project-scoped calls. org_query returns the new AgentQueryResponse, and org_list returns AgentListItem.

  • Project members (client.projects) — list_members, add_member, remove_member, list_assignable_roles and list_assignable_users. add_member returns an assignment whose id is what remove_member takes. Adds the ProjectMemberCreate, ProjectMemberResponse and ProjectMemberCandidate models.

  • Users (client.users) — new read-only resource with list for the organization’s users, via the new UserResponse model.

  • RBAC metadata (client.rbac) — new read-only resource with meta, returning the organization’s roles, scopes and actions as a dict (the response is untyped in the spec). The RBAC role, permission, mapping and assignment management routes remain excluded from the SDK.

  • Report Engine (client.reports) — new resource covering report generation end to end: generate, status, refresh, list, view (HTML), download and pdf (both returning bytes, or a DownloadedFile with as_file=True), plus the catalogue_templates, catalogue_template, catalogue_components, catalogue_component and catalogue_datasources discovery calls. Adds ReportListItem, ReportGenerateData and ReportStatusData. These endpoints existed before 4.9.0 but were not wrapped.

  • Azure AI Foundry agent runtime — runtime_provider_config accepts a new azure_foundry provider via the FoundryRuntimeConfig model (project_endpoint and agent_name required), and gained the ServicePrincipalAuth auth type alongside the existing no-auth, basic, bearer and API-key schemes. Discoverable through client.runtime_providers.list.

  • Project component inventory (client.components) — new resource with list, returning every AI component assigned to a project whatever its type, via the ComponentListItem model. This endpoint also predates 4.9.0 and was previously unwrapped.

Breaking Changes

  • MCPServerResponse and MCPServerListItem no longer carry project_id. MCP servers are organization-scoped records that hold project assignments instead of a single owning project — read the assignment from assign/unassign or client.components.list instead. Code that reads server.project_id must be updated.

Other

  • Regenerated the platform models from the current OpenAPI specs: 242 operations, up from 191, and 515 component schemas, up from 489. No schemas were removed and no endpoints were dropped.

  • PlatformHTTP.delete now accepts an optional JSON body. The AI component /associations delete routes describe the edge to remove in the request body rather than the path; every other delete route is unaffected.

  • OrganizationCreateRequest and BootstrapOrganizationRequest gained seed_default_policies.

  • Generated-model changes in endpoint groups excluded from the SDK surface (no callable methods are affected): EffectivePermissionsResponse gained primary_role_name and role_names, MappingUpdate gained claim_key, Card and CardListItem gained display metadata, DashboardListItem replaced cards with config and related fields, and the Dashboard, DashboardConfig, DashboardResponse, CardCategory, CardSize and CardVisualization models were added. TWBaseModel is a new generated base class with no fields of its own.

  • Two client methods call endpoints absent from the spec and are left in place for now: guardrails.get_evaluation and agents.risk_classify. Both predate this release.

  • No dependency changes.

v4.8.0 (2026-08-04)

New Features

  • Per-resource export/import — client.agents, client.guardrails, client.models, client.mcp_servers, and client.policies each gained export (filter by slugs, format="json" or "yaml") and import_ (multipart upload with a conflict_strategy). Agents, models, and MCP servers are project-scoped; guardrails and policies are organization-scoped.

  • Artifact bundles (client.artifacts) — new resource for moving several artifact types at once as a zip archive: export, import_, restore_export, and restore_import. The restore_* pair preserves record identifiers for same-organization backup and restore.

  • Background Jobs (client.jobs) — new resource with list (filter by status and job_type) and get for polling asynchronous operations such as artifact imports. Adds the BackgroundJobResponse and BackgroundJobStatus models.

  • Assessments (client.assessments) — get_magic_link returns details of an assessment’s active magic link (holder, expiry, and a masked token, never the full token), via the new AssessmentMagicLinkDetailsResponse model.

  • Guardrail evaluations — GuardrailEvaluationListItem and GuardrailEvaluationData now carry a guardrail_name field, so evaluation results identify the guardrail by name without a second lookup.

  • Transport — PlatformHTTP gained post_multipart (file uploads), post_binary, and get_binary (non-JSON responses such as zip and YAML), which the export/import surface is built on. get_file fetches a route that answers with Content-Disposition: attachment and returns a DownloadedFile — the body bytes plus the server-suggested filename.

  • Export as a file — the five per-resource export methods accept as_file=True, returning the DownloadedFile rather than parsed records, so a bundle can be written to disk under the name the server chose or handed back to import_ byte-for-byte.

Breaking Changes

  • Removed four metrics dropped from the v4 metrics spec: client.metrics.dangerous_code, client.metrics.tool_choice_relevancy, client.metrics.tool_faithfulness, and client.metrics.tool_output_relevancy. The DangerousCode, DangerousCodeRequest, CodeVulnerabilities, SimpleScore, ToolCallFaithfulness, ToolCallFaithfulnessRequest, ToolChoiceRelevancyRequest, and ToolOutputRelevancyRequest models have been removed from trustwise.sdk.platform._models. Callers of these four metrics have no replacement endpoint.

  • Guardrail-Input/Guardrail-Output collapsed into a single Guardrail model, and ListFilters / MetadataModel were split into -Input/-Output variants, following the spec. These are internal schema shapes and are not referenced by the client surface.

  • Three platform-client metric fields now yield wrapped item models instead of plain integers, because the model generator no longer discards the spec’s item constraints: DetectedEncoding.span (client.metrics.input_type), OwnedPII.interval (client.metrics.pii), and Statement.sentence_span (client.metrics.faithfulness). Each element is now a RootModel[int] (SpanItem, IntervalItem, SentenceSpanItem), so span[0] == 3 is no longer true — read span[0].root, or call model_dump(), which still serializes these as plain [start, end] lists. The spec’s maxItems: 2 and minimum: 0 constraints are now enforced on these fields. The high-level SDK (``trustwise.sdk.metrics.v4.types``) is unaffected — it keeps list[int]; only the platform client’s generated models changed.

Bug Fixes

  • Per-resource export — client.agents.export(), client.guardrails.export(), client.models.export(), client.policies.export(), and client.mcp_servers.export() raised AttributeError: 'list' object has no attribute 'get'. These five routes are file downloads: the API sets Content-Disposition: attachment and the body is the exported file itself, not the {success, data, ...} envelope the response parser assumed. Both a file download and an ordinary response are served as application/json, so the SDK now keys off the Content-Disposition header rather than guessing from the body shape. export() returns the list of exported records as before; the format="yaml" path is unchanged. raw=True is still accepted but has no effect on these routes, since a file body is already the payload.

  • Guardrail and policy evaluations with an empty name — listing evaluations raised ValidationError: String should have at least 1 character whenever a record carried guardrail_name: "", which the API returns routinely. The upstream spec declares guardrail_name (and policy_name) with minLength: 1 and a pattern alongside a default of "" — constraints its own default cannot satisfy — and the generated models enforced them verbatim. Affected guardrails.list_evaluations_for_guardrail, guardrails.list_evaluations, guardrails.get_evaluation_by_id, and policy evaluation responses.

  • Model generation — scripts/generate_platform_models.py now drops value constraints that a schema’s own default violates, so this class of upstream defect cannot reach the generated models on a future regeneration. Only properties whose default fails every branch are relaxed; a nullable field defaulting to None keeps its constraints. The generator also formats its output and strips unused imports, so a fresh regeneration is byte-reproducible and passes make lint unaided.

Other

  • Regenerated the platform Pydantic models from the latest platform + metrics OpenAPI specs (191 operations, up from 165). RBAC and Dashboard endpoints remain excluded from the generated SDK surface. The spec now also carries the Report Engine and project components endpoints; models are generated for them, but no client methods are exposed yet.

  • Security — bumped aiohttp to >=3.14.3 (runtime dependency) and datamodel-code-generator to >=0.64.0 (dev dependency) to fix known vulnerabilities. The generator bump is why the regenerated models now carry the item constraints noted above.

  • Two client methods call endpoints absent from the spec and are expected to 404 — guardrails nested evaluation lookup (/guardrails/{id}/evaluations/{eval_id}, superseded by get_evaluation_by_id) and agents.risk_classify (/agents/{id}/risk-classify). Both predate this release and are left in place pending a decision on removal.

v4.7.1 (2026-07-17)

New Features

  • Assessments (client.assessments) — two new endpoints: re_assess re-runs the assessment workflow after changes, and resolve_magic_link resolves a magic-link token back to the assessment it grants access to.

  • Agents (client.agents) — completed the AI Gateway lifecycle: undeploy_gateway removes a deployed agent from the gateway, and regenerate_gateway_key rotates its gateway API key.

  • Guardrails (client.guardrails) — list_evaluations_for_guardrail lists evaluations scoped to a single guardrail, and get_evaluation_by_id fetches one evaluation by its ID alone.

  • Models (client.models) — list_providers and get_provider expose the supported model-provider catalog and per-provider configuration.

  • Risk Engine (client.risk_engine) — list_templates and get_template list and fetch risk templates.

Breaking Changes

  • client.risk_engine.classify and client.agents.risk_classify now return a plain dict (the raw data payload) instead of a RiskClassificationResult model. The endpoint’s response is now untyped in the platform spec, and RiskClassificationResult has been removed from trustwise.sdk.platform._models.

Other

  • Regenerated the platform Pydantic models from the latest platform + metrics OpenAPI specs (adds the RiskTier model). RBAC endpoints remain excluded from the generated SDK surface.

v4.7.0 (2026-06-04)

New Features

  • Input Type metric — detects encoded segments (binary, hex, base64, …) in text, returning a list of DetectedEncoding spans. Available both through the high-level SDK (trustwise.metrics.input_type.evaluate(text=...), sync and async, returning InputTypeResponse) and the platform client (client.metrics.input_type, returning InputTypeOutput).

  • Organizations (client.organizations) — added org_type, org_data (including branding), and auth_provider_config support. OrganizationResponse now surfaces org_type and org_data, and create/bootstrap requests accept these fields plus auth_provider_config (e.g. a Keycloak provider domain).

  • Assessments (client.assessments) — new resource covering the assessment lifecycle (create, list, get, update, delete, save answers, validate, submit) and the review/vendor workflow (classify, decide, reopen, request-clarification, magic links, send/revoke-to-vendor, status, submissions). Assessments can also be assigned to agents via client.agents.assign_assessment / unassign_assessment.

  • Assessment evidence (client.risk_engine) — attach supporting files to an assessment: list_evidence, initiate_evidence_upload, get_evidence, download_evidence, upload_evidence, delete_evidence.

Breaking Changes

  • client.metrics.adherence, completion, and refusal now return their dedicated AdherenceOutput / CompletionOutput / RefusalOutput models (each {score}) instead of the generic SimpleScore, matching the v4 spec.

  • client.metrics.stability now returns StabilityOutput ({avg, min}); the StabilityScore model has been removed.

v4.6.0 (2026-05-29)

New Features

  • MCP Servers (client.mcp_servers) — project-scoped CRUD plus test_connection() and AI Gateway deploy_gateway() / undeploy_gateway() for registering and deploying MCP servers.

  • Models (client.models) — project-scoped registry of LLM endpoints (provider + credentials) with CRUD, test_connection(), and deploy_gateway().

  • Gateway (client.gateway) — added list_mcp_servers() to browse MCP servers available in the AI Gateway.

  • Agents (client.agents) — create, update, and responses now accept and return model_ids and mcp_server_ids to associate agents with registered models and MCP servers.

  • New metric outputs — adherence, completion, refusal, and stability added to EvaluationOutput (with corresponding AdherenceOutput, CompletionOutput, RefusalOutput, and StabilityOutput models).

  • Richer list/report fields — EvaluationListItem gains results and trust_score; GuardrailEvaluationListItem gains latency_ms, policy_id, results, and target_blocked; EvaluationReport gains failed_prompt_count.

  • New event types — MCP-server and model lifecycle events (created/updated/deleted/status_changed, plus model_deployed) added to EventType.

Other

  • Bumped minimum urllib3 requirement to >=2.7.0.

v4.5.0 (2026-04-30)

Breaking Changes

  • Agents are now project-scoped — all client.agents methods now require a project_id as the first argument. The old /v1alpha/agents/ endpoints have been removed from the API.

  • ``ProjectResource`` — list_components, assign_component, and unassign_component methods removed (endpoints removed from the API).

  • ``EvaluationResource.update`` — now uses PATCH instead of PUT.

  • ``GuardrailResource.provider_schemas`` — no longer accepts a provider argument; returns schemas for all providers.

New Features

  • Events (client.events) — list, get, and dismiss platform event notifications with filtering by severity, status, type, and project.

  • Subscriptions (client.subscriptions) — full CRUD for event subscriptions; supports webhook, email, Slack, and Teams handlers.

  • Runtime Providers (client.runtime_providers) — browse available agent runtime provider types and their auth schemas.

  • Organization Logo (client.organizations) — upload_logo, get_logo, update_logo, delete_logo methods added.

  • Guardrail Provider extensions (client.guardrails) — provider_guardrails() and provider_regions() for browsing guardrails and regions available from external providers (e.g. AWS Bedrock).

  • Policy batch evaluate (client.policies) — new evaluate_batch() method evaluates content against multiple policies in a single API call.

  • ``PlatformHTTP`` — added patch() method.

Other

  • Package status promoted from Beta to Production/Stable.

v4.4.0b1 (2026-04-08)

New Features

  • TrustwiseClient – New unified platform client providing access to all Trustwise APIs through a single interface: agents, guardrails, policies, evaluations, risk engine, red-team generation, and all v4 metrics.

  • Platform API resources – 11 resource classes covering 80+ API endpoints with typed return values and raw=True envelope access.

Deprecations

v1.0.0b10 (10-07-2025)

Deprecation Notices

  • V3 Metrics Deprecation: V3 metrics are now deprecated and will be removed in a future version. Please migrate to V4 metrics for continued support and enhanced features.

  • Future Default Behavior: V4 metrics will become the default when calling metrics.* without version specification once V3 is fully deprecated.

Features

  • Added support for V4 (alpha) metrics

  • Python 3.13 support

Migration

  • Added comprehensive migration guide for V3 to V4 metrics transition

  • Enhanced V4 metrics documentation with all available metrics

  • Improved type safety and response structures in V4 metrics

v1.0.0 (06-20-2025)

Features

  • Initial release of Trustwise Python SDK

  • Unified interface for evaluating AI-generated content across 14+ metrics: - Faithfulness - Answer Relevancy - Context Relevancy - Summarization - Prompt Injection Detection - PII Detection - Clarity - Helpfulness - Toxicity - Tone - Formality - Simplicity - Sensitivity - Cost Estimation - Carbon Emissions

  • Experimental guardrails system for multi-metric validation, threshold configuration, and block-on-failure functionality

  • Cost and carbon emissions estimation for model runs

  • Flexible configuration via environment variables or direct instantiation (API key, base URL, etc.)

  • Strong type definitions for all request and response objects

  • Serialization support: all responses can be converted to JSON and Python dicts for easy integration

  • Explicit and default API versioning with version switching and fallback

  • Designed for extensibility to support future metrics and features

  • Comprehensive documentation, including quickstart, usage, and API reference

  • Added async SDK (TrustwiseSDKAsync) for full asynchronous metric evaluation.

  • Added support for inline explanations for each metric evaluation call.

Metrics

  • Added support for context-based faithfulness, answer relevancy, and other metrics

  • Implemented query-response alignment scoring

  • Added cost and carbon evaluation for model runs

  • Added support for stability, adherence, completion and refusal metrics

Guardrails System (Experimental)

  • Added multi-metric guardrail system with configurable thresholds

  • Implemented block-on-failure functionality

  • Added support for comprehensive evaluation result aggregation

  • Introduced flexible threshold configuration per metric

Version Management

  • Added explicit version support for all API endpoints

  • Added version switching capabilities

  • Introduced version-aware evaluation methods

Configuration

  • Added environment variable based configuration

  • Implemented direct configuration through TrustwiseConfig

  • Added support for API key and base URL configuration

  • Introduced flexible configuration options for all features