v1.0.1 — First Stable Release

This is the current stable release of the Adstract AI Python SDK.

The SDK API is stable and production-ready. Version 1.0.1 includes the
stable 1.0.0 surface together with the latest acknowledgment response model
and backend-aligned exception handling.

---

What's new in v1.0.1

Structured acknowledgment responses
Successful acknowledge and acknowledge_async calls now return an
AdAckResponse object with:

• ad_ack_id
• status
• success

Acknowledgment status now reflects the finalized backend contract:

• ok → acknowledgment completed successfully
• no_ad_used → acknowledgment completed successfully, but the final LLM response did not use the ad
• recoverable_error → acknowledgment was accepted, but Adstract encountered a recoverable backend-side issue during follow-up processing

Acknowledgment-specific exception types
Known acknowledgment failures now map to dedicated SDK exceptions:

• AdResponseNotFoundError
• UnsuccessfulAdResponseError
• DuplicateAcknowledgmentError

This makes acknowledgment error handling explicit instead of treating these
cases as generic unexpected responses.

Backend-aligned HTTP error mapping
Enhancement and acknowledgment methods now match the current backend behavior
for:

• bad API key format
• missing or invalid API key
• revoked API key
• inactive platform or publisher state
• duplicate ad requests
• duplicate acknowledgments
• unsuccessful acknowledgment targets

---

Included from v1.0.0

Optional targeting context
Pass an OptionalContext to request_ad / request_ad_async to provide
additional signals for ad targeting: country, region, city, ASN, age, and
gender. All fields are optional and validated.

Status-based enhancement error types
The enhancement response status field maps to specific error classes:

• PromptRejectedError — prompt was not suitable for ad injection
• NoFillError — prompt was suitable but no ad inventory was available

Both are subclasses of AdEnhancementError.

Cleaner API naming

• AdRequestContext.x_forwarded_for → user_ip
• AdResponse.prompt → enhanced_prompt
• analyse_and_report / analyse_and_report_async → acknowledge / acknowledge_async

---

Breaking changes carried into the stable API

From v0.4.0

• AdRequestContext.x_forwarded_for renamed to user_ip
• AdResponse.prompt renamed to enhanced_prompt
• analyse_and_report renamed to acknowledge
• analyse_and_report_async renamed to acknowledge_async

From v0.3.x

• AdRequestConfiguration renamed to AdRequestContext
• request_ad_or_default renamed to request_ad
• request_ad_or_default_async renamed to request_ad_async
• request_ad, request_ad_async, acknowledge, and acknowledge_async
  now raise exceptions by default — set raise_exception=False for
  graceful fallback behavior
• Analytics, compliance, and metadata processing moved to the backend, and
  the related SDK-side model classes were removed

---

Install

pip install adstractai==1.0.1

Adstract AI Python SDK v0.3.0

Adstract SDK 0.3.0 (2026-02-18)

This release introduces a major API simplification and backend-driven analytics/compliance model.
It includes multiple breaking changes to request/response shapes and method naming/default behavior.

Breaking changes

• Removed Conversation class from request flow.
• EnhancementResult now returns session_id: str instead of conversation: Conversation.
• Renamed AdRequestConfiguration to AdRequestContext.
• AdRequestContext is now sent as a wrapped object with:
  • session_id
  • user_agent
  • x_forwarded_for
• Added RequestConfiguration class to wrap wrapping_type.
• AdRequest now sends structured objects:
  • request_context (AdRequestContext)
  • diagnostics (Diagnostics)
  • request_configuration (RequestConfiguration)
• Removed metadata/analytics/compliance-related models from SDK payload construction:
  • ClientMetadata
  • Metadata
  • Analytics
  • Compliance
  • ErrorTracking
  • ExternalMetadata
• AdAck payload simplified to:
  • ad_response_id
  • llm_response
  • diagnostics
• Removed AepiData.
• AdResponse simplified to:
  • ad_request_id
  • ad_response_id
  • success
  • execution_time_ms
  • prompt (optional)
  • product_name (optional)
• Removed fields from AdResponse:
  • aepi
  • tracking_url
  • tracking_identifier
  • sponsored_label
• Renamed methods:
  • request_ad_or_default -> request_ad
  • request_ad_or_default_async -> request_ad_async
• Default behavior changes:
  • request_ad / request_ad_async now use raise_exception=True by default.
  • analyse_and_report / analyse_and_report_async now use raise_exception=True by default.
  • Set raise_exception=False for graceful/fallback-style behavior.

Migration notes

• Replace all usages of AdRequestConfiguration with AdRequestContext.
• Update code expecting EnhancementResult.conversation to use EnhancementResult.session_id.
• Update method calls to request_ad / request_ad_async.
• Review error-handling flow due to new default raise_exception=True.

Adstract AI Python SDK v0.2.0

Adstract AI Python SDK v0.2.0

This release stabilizes the pre-release line (v0.0.1 to v0.0.12) into v0.2.0.

Breaking changes

• AdRequestConfiguration now requires session_id.
• Passing a conversation object in request config is no longer supported.
• Conversation data is now generated internally from session_id (including message_id).

Added

• Configurable API base URL support.
• Expanded AdResponse metadata and wrapping support.
• Analysis pipeline for ad-injected responses.
• Reporting flow that still reports ad acknowledgments when analysis fails.

Changed

• Request flow refactored and simplified.
• Session/conversation handling unified around session_id.
• SDK/package version updated to 0.2.0.

Removed

• Non-default request helper methods replaced by the unified flow.

Fixed

• Required-parameter validation and error behavior improvements.