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.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