Skip to content

v1.0.1 — First Stable Release

Latest
Latest

Choose a tag to compare

View all tags
@Itonkdong Itonkdong released this 12 Mar 17:22
· 12 commits to main since this release
v1.0.1
3f2485e

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
Assets 2
Loading