Changelog

​

[0.6.1] — 2026-04-14

​

Added

• ConversationEvent (autoplay_sdk.chatbot) — dataclass for chatbot session-link webhooks.
• BaseChatbotWriter session-link webhook flow — SESSION_LINK_WEBHOOK_TOPICS, extract_conversation_event(), _parse_session_link_webhook_payload() (subclasses override parse only).
• autoplay_sdk.integrations.intercom — webhook topic constants, intercom_chatbot_webhook_url(), optional format_reactive_session_link_script (no logging from this subpackage).

​

Removed

• format_proactive_session_start_script and the proactive /sessions/start snippet — use Intercom webhooks to POST /chatbot-webhook/{product_id}; optional format_reactive_session_link_script remains for POST /sessions/link.

​

Documentation

• Logging — logger hierarchy, app-owned logging configuration, third-party subclass guidance, changelog cross-link.
• README — logging section aligned with the above; metrics pointer (SdkMetricsHook).
• Intercom integration — SDK helpers and connector mapping (webhooks, optional snippet, inbox UX).

​

Breaking changes

• format_proactive_session_start_script removed from autoplay_sdk.integrations.intercom.

​

Deprecations

​

[0.6.0] — 2026-04-13

​

Documentation

• BaseChatbotWriter — Note body format — BaseChatbotWriter now documents the full plain-text contract for _post_note bodies (header via format_chatbot_note_header, sorted 1-based action lines, binning vs post-link, empty list, summary notes). _format_note docstring points to that page as the single source of truth.
• Logging — New Logging reference page (module loggers, % formatting, exc_info, structured extra, secrets guidance including HTTP bodies, common logging mistakes). Quickstart links to it for discoverability.

​

Bug fixes / observability

• BaseChatbotWriter — pre-link flush failure warning now includes structured extra (session_id, product_id, conversation_id).
• BaseChatbotWriter — post-link debounced flush: if _post_note returns no part id after the debounce buffer was popped, logs a warning with the same extra shape and explains that this flush is not retried automatically.

​

Breaking changes

​

Deprecations

​

[0.5.0] — 2026-04-10

​

New features

• ActionsPayload.merge(payloads) — class method that merges a non-empty list of ActionsPayload objects for the same session into one. Actions are concatenated and re-indexed from 0; user_id/email resolved from the first non-None value; forwarded_at set to the latest timestamp. Raises ValueError on empty input.
• AsyncAgentContextWriter(debounce_ms=N) — new optional constructor parameter for a per-session trailing-edge accumulation window. When > 0, multiple add() calls arriving within the window are merged via ActionsPayload.merge() before write_actions is called, reducing destination API calls during event bursts. Default is 0 (no debounce — existing behaviour unchanged).
• BaseChatbotWriter (autoplay_sdk.chatbot) — new public base class providing the complete pre-link/post-link delivery policy for building chatbot destinations. Subclass it and implement _post_note and _redact_part; pre-link buffering (sliding window), at-link flush (binned note), and post-link debouncing are all included. IntercomChatbot in the event connector already extends this class.

​

Breaking changes

• AsyncAgentContextWriter.__init__ gains debounce_ms: int = 0 — existing code passing positional or keyword arguments is unaffected.
• ActionsPayload.merge() is a new class method; no existing method is renamed or removed.
• BaseChatbotWriter is a new public export; no existing symbols are removed.

​

Deprecations

​

Bug fixes / error handling improvements

• BaseChatbotWriter.on_session_linked — now no-ops when the same conversation_id is passed again (idempotent guard). The product worker includes the conv_id on every batch for already-linked sessions; without this guard, each batch would cancel the in-flight 150ms post-link debounce task and restart the window, causing notes to be delayed indefinitely during fast user interactions.
• BaseChatbotWriter.on_session_linked — pre-link buffer (_pending) is now only cleared after _post_note confirms success (returns a non-None part id). Previously the buffer was popped before the API call; a transient Intercom failure would permanently lose those events. On failure the buffer is now preserved and the _conv_map entry is rolled back so the next on_session_linked call retries automatically.
• BaseChatbotWriter.write_actions: the post-link debounce asyncio.Task now has a done_callback that logs any unhandled exception at ERROR level with structured extra (previously silent — Python only emitted a DEBUG-level “Task exception was never retrieved”).
• AsyncAgentContextWriter._flush_session done-callback: now includes product_id in the log message and extra dict for structured log filtering.

​

Migration notes

# CORRECT — BaseChatbotWriter handles debouncing; no stacking needed
writer = AsyncAgentContextWriter(
    summarizer=summarizer,
    write_actions=chatbot_subclass.write_actions_cb,
    overwrite_with_summary=overwrite_cb,
    debounce_ms=0,   # ← default, explicit for clarity
)

# AVOID — stacks two debounce windows, adds latency without benefit
writer = AsyncAgentContextWriter(..., debounce_ms=200)

​

[0.4.0] — 2026-04-09

​

Bug fixes

• Fixed TOCTOU race in RedisEventBuffer._get_redis(): concurrent callers could each create their own connection pool; now serialised with asyncio.Lock and double-checked locking.
• Fixed AsyncSessionSummarizer.flush() cancellation safety: replaced sequential for q in queues: await q.join() with asyncio.gather(*[asyncio.shield(q.join()) for q in queues]) so all queues are drained even when the caller is cancelled.

​

Other

• Added CHANGELOG.md to document breaking changes and new features going forward.

​

[0.3.0] — 2026-04-09

​

Breaking changes

• AsyncSessionSummarizer.get_context(session_id) is now async — callers must await it.
• AsyncSessionSummarizer.reset(session_id) is now async — callers must await it.
• AsyncSessionSummarizer.active_sessions is now an async property — callers must await it.
• AsyncSessionSummarizer.add() now returns immediately — the LLM call is dispatched to a background worker queue rather than awaited inline. Code that relied on the LLM having completed by the time await add() returned must call await summarizer.flush() before inspecting state.

​

New features

• AsyncSessionSummarizer.flush() — waits for all queued payloads to be fully processed; cancellation-safe via asyncio.gather + asyncio.shield.
• SdkMetricsHook protocol (autoplay_sdk.metrics) — a @runtime_checkable Protocol that customers can implement to receive Prometheus / Datadog / OTEL counters for: dropped events, summarizer latency, Redis operation latency, queue depth, and semaphore timeouts.
• metrics= constructor parameter on ConnectorClient, AsyncConnectorClient, AsyncSessionSummarizer, and RedisEventBuffer.
• initial_backoff_s, max_backoff_s, max_retries constructor parameters on both SSE clients — exposes and documents the reconnect policy with configurable jitter-backed exponential backoff.
• Per-session ordering guarantee in AsyncSessionSummarizer — each session now has its own asyncio.Queue + background asyncio.Task worker, ensuring that concurrent add() calls for the same session are always processed in arrival order, even if an earlier LLM call fails.
• py.typed marker — the package is now PEP 561-compliant; static type-checkers will find type stubs automatically.

​

Bug fixes (v0.2.x → v0.3.0)

• Fixed AsyncSessionSummarizer ordering bug: concurrent adds during an LLM failure could produce out-of-order on_summary callbacks (replaced single lock with per-session queue).
• Fixed TOCTOU race in RedisEventBuffer._get_redis(): concurrent callers could each create their own connection pool; now serialised with asyncio.Lock and double-checked locking.
• Replaced asyncio.Semaphore._value (private API, breaks across CPython minor versions) with an explicit _TrackedSemaphore counter.
• Replaced asyncio.get_event_loop() (deprecated) with asyncio.get_running_loop() in app.py and async_client.py.
• Replaced asyncio.ensure_future() with loop.create_task() in async_client.py.
• Added done_callback on fire-and-forget asyncio.Tasks to log unhandled exceptions instead of silently swallowing them.

• RedisEventBuffer._payload_from_json() now wraps json.loads in try/except json.JSONDecodeError; corrupt ZSET members no longer crash the drain loop.
• ConnectorClient now sets self._running = False on KeyboardInterrupt so callers can inspect the state after shutdown.
• All except clauses that were swallowing exceptions now pass exc_info=True to the logger so tracebacks appear in structured logs.

• RedisEventBuffer ZSET members now carry a unique UUID prefix, preventing silent deduplication when two events arrive at the same millisecond timestamp.
• SessionSummarizer now deletes _history[session_id] and _counts[session_id] after summarisation to prevent unbounded memory growth.
• AsyncConnectorClient._session_semaphores changed from plain dict to collections.OrderedDict with LRU eviction to cap memory when many short-lived sessions are processed.

• Extracted LazyRedisClient helper (storage/_redis.py) so all storage modules share one lazily-initialised, thread-safe Redis client instead of each implementing the same racy pattern.
• session_store now uses LazyRedisClient and exposes a SessionState.from_redis_link() classmethod that owns the full reconstruction logic (preventing silent field omissions on restore).
• SessionState gains an error: Optional[str] field to surface last-known error reason through the API.

• Replaced custom _JsonFormatter in app.py that ignored extra={} fields with a correct implementation that merges them into the JSON line.
• All structured log calls now use extra={} dicts consistently.
• Metrics instrumentation added at every observability-relevant site: event drops, queue depth, semaphore timeouts, summarizer latency, Redis add/drain latency.

• Added __all__ exports to __init__.py so from autoplay_sdk import * is well-defined.
• Added __version__ = "0.3.0" to __init__.py.
• Added py.typed marker for PEP 561 compliance.
• Removed dead _dropped_count / _total_count metrics fields that were incremented but never surfaced.
• Standardised public API: on_drop callback signature is now consistent across ConnectorClient, AsyncConnectorClient, and RedisEventBuffer.

​

[0.2.0] — prior