Skip to main content

Synchronous Acknowledgment

The synchronous acknowledgment method is the primary way to report the final LLM response back to Adstract after enhancement. It sends an acknowledgment payload to close the ad workflow cycle.

Why this method is critical​

This method closes the full ad workflow cycle.

  • It confirms that the enhancement flow reached final output handling.
  • It submits the required acknowledgment data for reporting.
  • It is required for publisher-side monetization flow, because the reporting confirmation is part of how ad placement opportunity is accounted for.

Method signature​

client.acknowledge(
    enhancement_result=result,
    llm_response=llm_response,
)

Inputs​

  • enhancement_result

    • Type: EnhancementResult
    • Meaning: Result returned from the enhancement method.
    • Role: Source object used for reporting context.

  • llm_response

    • Type: str
    • Meaning: Final text returned by your LLM.
    • Role: The actual model response that was produced with the enhanced prompt.

  • raise_exception

    • Type: bool
    • Default: True
    • Meaning: Controls error handling behavior.
    • Behavior:
      • True (default): raises exceptions on failure.
      • False: logs errors but does not raise, avoiding disruption to main application flow.

For result object details, see EnhancementResult.

Output​

This method returns AdAckResponse on successful acknowledgment.

If enhancement_result.success is False, acknowledgment is skipped and the method returns None.

Behavior model​

The method flow is:

  1. Check whether enhancement succeeded.
  2. If enhancement did not succeed, reporting is skipped.
  3. If enhancement succeeded, build the acknowledgment payload.
  4. Send the acknowledgment payload to Adstract.
  5. Parse the acknowledgment response and return AdAckResponse.

Exception behavior​

With raise_exception=True (default), acknowledge raises on any reporting failure.

With raise_exception=False, errors are logged but not raised, avoiding disruption to the main application flow.

If the backend returns invalid acknowledgment JSON or an unexpected acknowledgment response shape, acknowledge raises UnexpectedResponseError.

For full exception reference, see Exception.

Privacy and data-protection note​

The raw final LLM response text is sent to the backend for acknowledgment and compliance verification. The flow is designed with privacy and safety constraints in mind, and all analytics and compliance metrics are computed on the backend. Adstract does not save llm_response in any form. It is used only during acknowledgment processing.

Minimal integration pattern​

from adstractai import Adstract
from adstractai.models import AdRequestContext

client = Adstract(api_key="your-api-key")

context = AdRequestContext(
    session_id="session-abc",
    user_agent="Mozilla/5.0 (X11; Linux x86_64)",
    user_ip="203.0.113.10",
)

result = client.request_ad(
    prompt="How can I improve user retention?",
    context=context,
)

llm_response = "Your final model output here"

ack = client.acknowledge(
    enhancement_result=result,
    llm_response=llm_response,
)

if ack is not None:
    print(ack.ad_ack_id)
    print(ack.status)

Next steps​