Changelog
All notable changes to the Trustwise SDK will be documented in this file.
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.modelsandclient.mcp_serverseach gainedorg_list,org_get,org_create,org_updateandorg_delete, which address a component by ID with noproject_id. The existing project-scoped methods are unchanged.Component associations — all three resources gained
org_associations,org_add_associationandorg_remove_association, plus the project-scopedassociations,add_associationandremove_association. An association names a target component, its type (agent,model,mcp_server,rest_apiormessage_queue) and the relationship (usesordepends_on). Adds theAIComponentAssociationRequest,AIComponentAssociationResponse,AIComponentAssociationTypeandAIComponentTypeValuemodels.Project assignment —
assignandunassignonclient.agents,client.modelsandclient.mcp_serversmake an organization-scoped component available to a project, replacing creation-inside-a-project as the way a component reaches one. AddsAIComponentProjectAssignmentResponse.Organization-scoped agent operations —
client.agentsgainedorg_query,org_status_history,org_update_status,org_assign_assessmentandorg_unassign_assessment, the ID-addressed counterparts of the existing project-scoped calls.org_queryreturns the newAgentQueryResponse, andorg_listreturnsAgentListItem.Project members (
client.projects) —list_members,add_member,remove_member,list_assignable_rolesandlist_assignable_users.add_memberreturns an assignment whoseidis whatremove_membertakes. Adds theProjectMemberCreate,ProjectMemberResponseandProjectMemberCandidatemodels.Users (
client.users) — new read-only resource withlistfor the organization’s users, via the newUserResponsemodel.RBAC metadata (
client.rbac) — new read-only resource withmeta, returning the organization’s roles, scopes and actions as adict(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),downloadandpdf(both returningbytes, or aDownloadedFilewithas_file=True), plus thecatalogue_templates,catalogue_template,catalogue_components,catalogue_componentandcatalogue_datasourcesdiscovery calls. AddsReportListItem,ReportGenerateDataandReportStatusData. These endpoints existed before 4.9.0 but were not wrapped.Azure AI Foundry agent runtime —
runtime_provider_configaccepts a newazure_foundryprovider via theFoundryRuntimeConfigmodel (project_endpointandagent_namerequired), and gained theServicePrincipalAuthauth type alongside the existing no-auth, basic, bearer and API-key schemes. Discoverable throughclient.runtime_providers.list.Project component inventory (
client.components) — new resource withlist, returning every AI component assigned to a project whatever its type, via theComponentListItemmodel. This endpoint also predates 4.9.0 and was previously unwrapped.
Breaking Changes
MCPServerResponseandMCPServerListItemno longer carryproject_id. MCP servers are organization-scoped records that hold project assignments instead of a single owning project — read the assignment fromassign/unassignorclient.components.listinstead. Code that readsserver.project_idmust 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.deletenow accepts an optional JSON body. The AI component/associationsdelete routes describe the edge to remove in the request body rather than the path; every other delete route is unaffected.OrganizationCreateRequestandBootstrapOrganizationRequestgainedseed_default_policies.Generated-model changes in endpoint groups excluded from the SDK surface (no callable methods are affected):
EffectivePermissionsResponsegainedprimary_role_nameandrole_names,MappingUpdategainedclaim_key,CardandCardListItemgained display metadata,DashboardListItemreplacedcardswithconfigand related fields, and theDashboard,DashboardConfig,DashboardResponse,CardCategory,CardSizeandCardVisualizationmodels were added.TWBaseModelis 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_evaluationandagents.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, andclient.policieseach gainedexport(filter byslugs,format="json"or"yaml") andimport_(multipart upload with aconflict_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, andrestore_import. Therestore_*pair preserves record identifiers for same-organization backup and restore.Background Jobs (
client.jobs) — new resource withlist(filter bystatusandjob_type) andgetfor polling asynchronous operations such as artifact imports. Adds theBackgroundJobResponseandBackgroundJobStatusmodels.Assessments (
client.assessments) —get_magic_linkreturns details of an assessment’s active magic link (holder, expiry, and a masked token, never the full token), via the newAssessmentMagicLinkDetailsResponsemodel.Guardrail evaluations —
GuardrailEvaluationListItemandGuardrailEvaluationDatanow carry aguardrail_namefield, so evaluation results identify the guardrail by name without a second lookup.Transport —
PlatformHTTPgainedpost_multipart(file uploads),post_binary, andget_binary(non-JSON responses such as zip and YAML), which the export/import surface is built on.get_filefetches a route that answers withContent-Disposition: attachmentand returns aDownloadedFile— the body bytes plus the server-suggested filename.Export as a file — the five per-resource
exportmethods acceptas_file=True, returning theDownloadedFilerather than parsed records, so a bundle can be written to disk under the name the server chose or handed back toimport_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, andclient.metrics.tool_output_relevancy. TheDangerousCode,DangerousCodeRequest,CodeVulnerabilities,SimpleScore,ToolCallFaithfulness,ToolCallFaithfulnessRequest,ToolChoiceRelevancyRequest, andToolOutputRelevancyRequestmodels have been removed fromtrustwise.sdk.platform._models. Callers of these four metrics have no replacement endpoint.Guardrail-Input/Guardrail-Outputcollapsed into a singleGuardrailmodel, andListFilters/MetadataModelwere split into-Input/-Outputvariants, 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), andStatement.sentence_span(client.metrics.faithfulness). Each element is now aRootModel[int](SpanItem,IntervalItem,SentenceSpanItem), sospan[0] == 3is no longer true — readspan[0].root, or callmodel_dump(), which still serializes these as plain[start, end]lists. The spec’smaxItems: 2andminimum: 0constraints are now enforced on these fields. The high-level SDK (``trustwise.sdk.metrics.v4.types``) is unaffected — it keepslist[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(), andclient.mcp_servers.export()raisedAttributeError: 'list' object has no attribute 'get'. These five routes are file downloads: the API setsContent-Disposition: attachmentand 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 asapplication/json, so the SDK now keys off theContent-Dispositionheader rather than guessing from the body shape.export()returns the list of exported records as before; theformat="yaml"path is unchanged.raw=Trueis 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 characterwhenever a record carriedguardrail_name: "", which the API returns routinely. The upstream spec declaresguardrail_name(andpolicy_name) withminLength: 1and a pattern alongside adefaultof""— constraints its own default cannot satisfy — and the generated models enforced them verbatim. Affectedguardrails.list_evaluations_for_guardrail,guardrails.list_evaluations,guardrails.get_evaluation_by_id, and policy evaluation responses.Model generation —
scripts/generate_platform_models.pynow drops value constraints that a schema’s owndefaultviolates, 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 toNonekeeps its constraints. The generator also formats its output and strips unused imports, so a fresh regeneration is byte-reproducible and passesmake lintunaided.
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
aiohttpto>=3.14.3(runtime dependency) anddatamodel-code-generatorto>=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 —
guardrailsnested evaluation lookup (/guardrails/{id}/evaluations/{eval_id}, superseded byget_evaluation_by_id) andagents.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_assessre-runs the assessment workflow after changes, andresolve_magic_linkresolves a magic-link token back to the assessment it grants access to.Agents (
client.agents) — completed the AI Gateway lifecycle:undeploy_gatewayremoves a deployed agent from the gateway, andregenerate_gateway_keyrotates its gateway API key.Guardrails (
client.guardrails) —list_evaluations_for_guardraillists evaluations scoped to a single guardrail, andget_evaluation_by_idfetches one evaluation by its ID alone.Models (
client.models) —list_providersandget_providerexpose the supported model-provider catalog and per-provider configuration.Risk Engine (
client.risk_engine) —list_templatesandget_templatelist and fetch risk templates.
Breaking Changes
client.risk_engine.classifyandclient.agents.risk_classifynow return a plaindict(the rawdatapayload) instead of aRiskClassificationResultmodel. The endpoint’s response is now untyped in the platform spec, andRiskClassificationResulthas been removed fromtrustwise.sdk.platform._models.
Other
Regenerated the platform Pydantic models from the latest platform + metrics OpenAPI specs (adds the
RiskTiermodel). 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
DetectedEncodingspans. Available both through the high-level SDK (trustwise.metrics.input_type.evaluate(text=...), sync and async, returningInputTypeResponse) and the platform client (client.metrics.input_type, returningInputTypeOutput).Organizations (
client.organizations) — addedorg_type,org_data(includingbranding), andauth_provider_configsupport.OrganizationResponsenow surfacesorg_typeandorg_data, and create/bootstrap requests accept these fields plusauth_provider_config(e.g. a Keycloak providerdomain).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 viaclient.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, andrefusalnow return their dedicatedAdherenceOutput/CompletionOutput/RefusalOutputmodels (each{score}) instead of the genericSimpleScore, matching the v4 spec.client.metrics.stabilitynow returnsStabilityOutput({avg, min}); theStabilityScoremodel has been removed.
v4.6.0 (2026-05-29)
New Features
MCP Servers (
client.mcp_servers) — project-scoped CRUD plustest_connection()and AI Gatewaydeploy_gateway()/undeploy_gateway()for registering and deploying MCP servers.Models (
client.models) — project-scoped registry of LLM endpoints (provider + credentials) with CRUD,test_connection(), anddeploy_gateway().Gateway (
client.gateway) — addedlist_mcp_servers()to browse MCP servers available in the AI Gateway.Agents (
client.agents) —create,update, and responses now accept and returnmodel_idsandmcp_server_idsto associate agents with registered models and MCP servers.New metric outputs —
adherence,completion,refusal, andstabilityadded toEvaluationOutput(with correspondingAdherenceOutput,CompletionOutput,RefusalOutput, andStabilityOutputmodels).Richer list/report fields —
EvaluationListItemgainsresultsandtrust_score;GuardrailEvaluationListItemgainslatency_ms,policy_id,results, andtarget_blocked;EvaluationReportgainsfailed_prompt_count.New event types — MCP-server and model lifecycle events (
created/updated/deleted/status_changed, plusmodel_deployed) added toEventType.
Other
Bumped minimum
urllib3requirement to>=2.7.0.
v4.5.0 (2026-04-30)
Breaking Changes
Agents are now project-scoped — all
client.agentsmethods now require aproject_idas the first argument. The old/v1alpha/agents/endpoints have been removed from the API.``ProjectResource`` —
list_components,assign_component, andunassign_componentmethods removed (endpoints removed from the API).``EvaluationResource.update`` — now uses
PATCHinstead ofPUT.``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_logomethods added.Guardrail Provider extensions (
client.guardrails) —provider_guardrails()andprovider_regions()for browsing guardrails and regions available from external providers (e.g. AWS Bedrock).Policy batch evaluate (
client.policies) — newevaluate_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=Trueenvelope access.
Deprecations
TrustwiseSDK is deprecated with a
FutureWarning. Migrate toTrustwiseClient. See Migrating from TrustwiseSDK to TrustwiseClient for details.
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