From ce76acadff3e30dc642fc335a3043079a6136066 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Wed, 11 Nov 2026 13:32:53 +0000 Subject: [PATCH 01/10] feat(sessions): support call disclosure configuration --- CHANGELOG.md | 11 ++++ docs/http-api.md | 26 +++++++- docs/sdk-api.md | 31 ++++++++- src/pine_assistant/__init__.py | 2 + src/pine_assistant/models/session.py | 6 +- src/pine_assistant/sessions.py | 58 +++++++++++++++-- tests/test_profile_and_session_config.py | 82 ++++++++++++++++++++++++ 7 files changed, 206 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aadd94d..afb08fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/). +## [Unreleased] + +### Added + +- Session call disclosures on both async and sync clients: + `sessions.update_config(ai_disclosure="on_request", recording_disclosure=False)`. + Each setting, including `caller_id`, may be updated independently. Omitted + fields stay unchanged; `None` and invalid values are rejected before sending. +- `SessionConfig` reads effective AI and recording disclosure values, and the + public `AIDisclosure` type describes the managed-user modes. + ## [0.5.0rc4] - 2026-10-23 ### New diff --git a/docs/http-api.md b/docs/http-api.md index 1575fc9..9dc2f46 100644 --- a/docs/http-api.md +++ b/docs/http-api.md @@ -154,8 +154,8 @@ These routes take the two headers above. | `POST /v2/sessions` | Creates a session. | `sessions.create()` | | `GET /v2/sessions` | Lists the user's sessions. | `sessions.list()` | | `GET /v2/sessions/{id}` | Returns one session. | `sessions.get()` | -| `GET /v2/sessions/{id}/config` | Returns the session config, for example `{"caller_id": "platform"}`, or `{}`. | `sessions.get_config()` | -| `PUT /v2/sessions/{id}/config` | Sets the caller ID. Body: `{"caller_id": "user"}` or `{"caller_id": "platform"}`. See "Caller ID". | `sessions.update_config()` | +| `GET /v2/sessions/{id}/config` | Returns session config with effective `ai_disclosure` and `recording_disclosure` values. | `sessions.get_config()` | +| `PUT /v2/sessions/{id}/config` | Updates supplied session settings. See "Caller ID" and "Call disclosures". | `sessions.update_config()` | | `POST /v2/sessions/{id}/messages` | Sends a message. Body: `{"content": "...", "client_now_date": "..."}`; `client_now_date` is optional, see "The user's time". | `sessions.send_message()` | | `GET /v2/sessions/{id}/messages` | Reads the stored messages, newest first. | `sessions.history()` | | `POST /v2/sessions/{id}/start` | Starts a prepared or paused task, or continues a stopped session. See "Stop and continue". | `sessions.start_task()` | @@ -205,10 +205,30 @@ caller ID. `caller_id` is a session setting that selects it: while the session is paused applies when the session resumes. - `caller_id` does not change how the agent reaches the user. The agent still uses the user's phone for that. -- Any other key or value returns 400 `invalid_request`. +- Invalid values or unsupported config keys return 400 `invalid_request`. - 503 `session_config_push_failed` means that the value is saved, but the running agent did not get it yet. Send the same request again. +### Call disclosures + +The config API accepts these additional fields for managed users: + +| Field | Values | Default | +|---|---|---| +| `ai_disclosure` | `"proactive"` (introduce as AI), `"on_request"` (disclose when asked) | `"proactive"` | +| `recording_disclosure` | JSON `true` or `false` | `true` | + +For example, `PUT /v2/sessions/{id}/config` with +`{"ai_disclosure": "on_request", "recording_disclosure": false}` changes both. +Omitted fields stay unchanged; `null` is invalid. Recording disclosure controls +the spoken notice, not whether the call is recorded. Changes affect subsequent +calls; calls already placed keep their settings. The same 503 push-failure +behavior described above applies. + +`GET` returns the effective disclosure values, including defaults. Pine's own +users default to `"off"` and `false`; config API access restrictions remain +unchanged. Managed users cannot set `ai_disclosure="off"`. + ### The user's time The agent must know the user's time zone to understand words such as diff --git a/docs/sdk-api.md b/docs/sdk-api.md index 83f6af4..a5474c7 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -122,7 +122,7 @@ user = await partner_client.platform.managed_users.update( | `sessions.list(...)` | `SessionListResponse` | | `sessions.get(session_id)` | `SessionInfo` | | `sessions.get_config(session_id)` | `SessionConfig` | -| `sessions.update_config(session_id, *, caller_id)` | `SessionConfig` after the change | +| `sessions.update_config(session_id, *, caller_id=…, ai_disclosure=…, recording_disclosure=…)` | `SessionConfig` after the change | | `sessions.send_message(session_id, content, ..., client_now_date=None)` | `SessionMessageStatus` | | `sessions.history(session_id, *, limit=30, before_message_id=None)` | `SessionHistoryPage`: one page of stored messages, newest first | | `sessions.start_task(session_id)` | `dict` | @@ -172,6 +172,35 @@ await client.sessions.update_config(session["id"], caller_id="platform") await client.sessions.send_message(session["id"], "Call the clinic to book a visit") ``` +### Call disclosures + +Managed-user sessions default to `ai_disclosure="proactive"` and +`recording_disclosure=True`. `"proactive"` makes the assistant introduce itself +as AI; `"on_request"` makes it disclose that identity when asked. Managed users +cannot select `"off"`. Pine's own users default to `"off"` and `False`; this +does not grant them access to the config API. + +```python +session = await client.sessions.create() +config = await client.sessions.update_config( + session["id"], ai_disclosure="on_request", recording_disclosure=False, +) +await client.sessions.send_message(session["id"], "Call the clinic to book a visit") +``` + +Both `AsyncPineAI` and `PineAI` support these settings. Supply at least one +setting. Omitted settings stay unchanged; `None`, invalid modes and non-boolean +recording values raise `ValueError` before any request is sent. Setting +`recording_disclosure=False` disables the spoken recording notice, not recording. +Changes affect subsequent calls; calls already placed keep their settings. +The same 503 `session_config_push_failed` behavior described above applies. + +`sessions.get_config()` returns the effective disclosure values from the server. +`SessionConfig.ai_disclosure` can also be `"off"` on reads; both disclosure +fields are `None` when an older server omits them. The SDK does not choose +product defaults locally. `AIDisclosure`, exported from `pine_assistant`, types +the two modes accepted by `update_config()`. + ### The user's time The agent must know the user's time zone to understand words such as diff --git a/src/pine_assistant/__init__.py b/src/pine_assistant/__init__.py index 02c0e85..accee25 100644 --- a/src/pine_assistant/__init__.py +++ b/src/pine_assistant/__init__.py @@ -22,6 +22,7 @@ ) from pine_assistant.models.platform import ManagedUser, ManagedUserAssistant from pine_assistant.models.session import ( + AIDisclosure, CallerID, SessionConfig, SessionHistoryMessage, @@ -75,6 +76,7 @@ "SessionInfo", "SessionConfig", "CallerID", + "AIDisclosure", "SessionHistoryMessage", "SessionHistoryPage", "SessionListResponse", diff --git a/src/pine_assistant/models/session.py b/src/pine_assistant/models/session.py index 6677051..3d7cff6 100644 --- a/src/pine_assistant/models/session.py +++ b/src/pine_assistant/models/session.py @@ -4,9 +4,10 @@ from typing import Any, Literal -from pydantic import BaseModel, ConfigDict, field_validator +from pydantic import BaseModel, ConfigDict, StrictBool, field_validator CallerID = Literal["user", "platform"] +AIDisclosure = Literal["proactive", "on_request"] class SessionInfo(BaseModel): @@ -40,6 +41,9 @@ class SessionConfig(BaseModel): model_config = ConfigDict(extra="allow") caller_id: str | None = None + # Missing values preserve compatibility with servers predating disclosure settings. + ai_disclosure: str | None = None + recording_disclosure: StrictBool | None = None class SessionListResponse(BaseModel): diff --git a/src/pine_assistant/sessions.py b/src/pine_assistant/sessions.py index 20d641e..4b349dd 100644 --- a/src/pine_assistant/sessions.py +++ b/src/pine_assistant/sessions.py @@ -6,12 +6,14 @@ import re from datetime import datetime +from enum import Enum from typing import Any, get_args from pydantic import ValidationError from pine_assistant.errors import PineAIError, SessionError from pine_assistant.models.session import ( + AIDisclosure, CallerID, SessionConfig, SessionHistoryPage, @@ -54,6 +56,31 @@ def _caller_id(caller_id: CallerID) -> CallerID: return caller_id +class _Unset(Enum): + VALUE = "unset" + + +def _config_update( + caller_id: CallerID | _Unset, + ai_disclosure: AIDisclosure | _Unset, + recording_disclosure: bool | _Unset, +) -> dict[str, Any]: + body: dict[str, Any] = {} + if caller_id is not _Unset.VALUE: + body["caller_id"] = _caller_id(caller_id) + if ai_disclosure is not _Unset.VALUE: + if ai_disclosure not in get_args(AIDisclosure): + raise ValueError('ai_disclosure must be "proactive" or "on_request"') + body["ai_disclosure"] = ai_disclosure + if recording_disclosure is not _Unset.VALUE: + if not isinstance(recording_disclosure, bool): + raise ValueError("recording_disclosure must be a boolean") + body["recording_disclosure"] = recording_disclosure + if not body: + raise ValueError("provide at least one session config setting") + return body + + def _config_path(session_id: str | int) -> str: return f"/v2/sessions/{_session_id(session_id)}/config" @@ -181,8 +208,21 @@ async def get_config(self, session_id: str | int) -> SessionConfig: except PineAIError as exc: raise _session_error(exc) from exc - async def update_config(self, session_id: str | int, *, caller_id: CallerID) -> SessionConfig: - """Set the caller ID of the calls the agent places in this session. + async def update_config( + self, + session_id: str | int, + *, + caller_id: CallerID | _Unset = _Unset.VALUE, + ai_disclosure: AIDisclosure | _Unset = _Unset.VALUE, + recording_disclosure: bool | _Unset = _Unset.VALUE, + ) -> SessionConfig: + """Update settings for the next calls the agent places in this session. + + Omitted fields stay unchanged; explicit None is invalid. Managed users + default to proactive AI disclosure and recording disclosure enabled. + Set ai_disclosure="on_request" to disclose AI identity only when asked; + "off" is not a managed-user setting. recording_disclosure=False disables + the spoken notice, not recording. Calls already placed keep their settings. ``"user"``, or not set, presents the user's assistant number if it has one, else the user's phone, else a number of the platform's pool; @@ -191,7 +231,7 @@ async def update_config(self, session_id: str | int, *, caller_id: CallerID) -> ``session_config_push_failed`` means the value is saved but has not reached the running agent yet; send the same value again. """ - body = {"caller_id": _caller_id(caller_id)} + body = _config_update(caller_id, ai_disclosure, recording_disclosure) try: return _parse_session_config(await self._http.put(_config_path(session_id), body)) except PineAIError as exc: @@ -362,8 +402,16 @@ def get_config(self, session_id: str | int) -> SessionConfig: except PineAIError as exc: raise _session_error(exc) from exc - def update_config(self, session_id: str | int, *, caller_id: CallerID) -> SessionConfig: - body = {"caller_id": _caller_id(caller_id)} + def update_config( + self, + session_id: str | int, + *, + caller_id: CallerID | _Unset = _Unset.VALUE, + ai_disclosure: AIDisclosure | _Unset = _Unset.VALUE, + recording_disclosure: bool | _Unset = _Unset.VALUE, + ) -> SessionConfig: + """Update next-call settings; see :meth:`SessionsAPI.update_config` for semantics.""" + body = _config_update(caller_id, ai_disclosure, recording_disclosure) try: return _parse_session_config(self._http.put(_config_path(session_id), body)) except PineAIError as exc: diff --git a/tests/test_profile_and_session_config.py b/tests/test_profile_and_session_config.py index a0183df..3b8cdfb 100644 --- a/tests/test_profile_and_session_config.py +++ b/tests/test_profile_and_session_config.py @@ -366,3 +366,85 @@ def test_socketio_message_carries_client_now_date_only_when_given(): ) with pytest.raises(ValueError, match="client_now_date"): ChatEngine._build_message_data("hi", client_now_date="2026-10-21T09:00:00") + + +@pytest.mark.parametrize("sync", [False, True]) +@pytest.mark.parametrize("settings", [ + {"ai_disclosure": "proactive"}, + {"ai_disclosure": "on_request"}, + {"recording_disclosure": False}, + {"recording_disclosure": True}, + {"caller_id": "platform", "ai_disclosure": "on_request", "recording_disclosure": False}, +]) +async def test_disclosure_update_preserves_false_and_omits_unprovided_fields(sync, settings): + recorder = Recorder() + if sync: + with PineAI( + api_key=API_KEY, user_id=PINE_USER_ID, base_url=BASE_URL, http_transport=httpx.MockTransport(recorder), + ) as client: + config = client.sessions.update_config(7, **settings) + else: + async with async_client(recorder, user_id=PINE_USER_ID) as client: + config = await client.sessions.update_config(7, **settings) + + assert recorder.body() == settings + assert config.model_dump(exclude_unset=True) == settings + [request] = recorder.requests + assert (request.method, request.url.path) == ("PUT", "/api/v2/sessions/7/config") + assert request.headers[MANAGED_USER_HEADER] == PINE_USER_ID + + +@pytest.mark.parametrize("sync", [False, True]) +@pytest.mark.parametrize("settings", [ + {}, + {"caller_id": None}, + {"ai_disclosure": None}, + {"ai_disclosure": "off"}, + {"ai_disclosure": "PROACTIVE"}, + {"ai_disclosure": True}, + {"recording_disclosure": None}, + {"recording_disclosure": "false"}, + {"recording_disclosure": 0}, + {"recording_disclosure": 1}, +]) +async def test_invalid_disclosure_update_never_sends_request(sync, settings): + recorder = Recorder() + if sync: + with PineAI( + api_key=API_KEY, user_id=PINE_USER_ID, base_url=BASE_URL, http_transport=httpx.MockTransport(recorder), + ) as client, pytest.raises(ValueError): + client.sessions.update_config(7, **settings) + else: + async with async_client(recorder, user_id=PINE_USER_ID) as client: + with pytest.raises(ValueError): + await client.sessions.update_config(7, **settings) + assert recorder.requests == [] + + +@pytest.mark.parametrize("sync", [False, True]) +@pytest.mark.parametrize("payload", [ + {"ai_disclosure": "proactive", "recording_disclosure": True}, + {"ai_disclosure": "on_request", "recording_disclosure": False}, + {"ai_disclosure": "off", "recording_disclosure": False}, + {}, +]) +async def test_read_disclosure_config_and_older_servers(sync, payload): + recorder = Recorder(httpx.Response(200, json=success(payload))) + if sync: + with PineAI( + api_key=API_KEY, user_id=PINE_USER_ID, base_url=BASE_URL, http_transport=httpx.MockTransport(recorder), + ) as client: + config = client.sessions.get_config(7) + else: + async with async_client(recorder, user_id=PINE_USER_ID) as client: + config = await client.sessions.get_config(7) + assert config.ai_disclosure == payload.get("ai_disclosure") + assert config.recording_disclosure is payload.get("recording_disclosure") + + +@pytest.mark.parametrize("recording_disclosure", ["false", 0, 1]) +async def test_malformed_disclosure_response_is_not_coerced(recording_disclosure): + recorder = Recorder(httpx.Response(200, json=success({"recording_disclosure": recording_disclosure}))) + async with async_client(recorder, user_id=PINE_USER_ID) as client: + with pytest.raises(SessionError, match="invalid session config response"): + await client.sessions.get_config(7) From 55cfd261acdb2598e1385b7716386d7dbbbce901 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Wed, 11 Nov 2026 13:38:45 +0000 Subject: [PATCH 02/10] docs(sessions): clarify uncertain configuration delivery --- docs/http-api.md | 4 ++-- docs/sdk-api.md | 4 ++-- src/pine_assistant/sessions.py | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/http-api.md b/docs/http-api.md index 9dc2f46..2b2e72c 100644 --- a/docs/http-api.md +++ b/docs/http-api.md @@ -206,8 +206,8 @@ caller ID. `caller_id` is a session setting that selects it: - `caller_id` does not change how the agent reaches the user. The agent still uses the user's phone for that. - Invalid values or unsupported config keys return 400 `invalid_request`. -- 503 `session_config_push_failed` means that the value is saved, but the - running agent did not get it yet. Send the same request again. +- 503 `session_config_push_failed` means that the value is saved, but delivery to + the running agent was not confirmed. Send the same request again. ### Call disclosures diff --git a/docs/sdk-api.md b/docs/sdk-api.md index a5474c7..db4426c 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -162,8 +162,8 @@ caller ID. `caller_id` is a session setting that selects it: while the session is paused applies when the session resumes. - `caller_id` does not change how the agent reaches the user. The agent still uses the user's phone for that. -- A 503 `session_config_push_failed` means that the value is saved, but the - running agent did not get it yet. Send the same value again. +- A 503 `session_config_push_failed` means that the value is saved, but delivery to + the running agent was not confirmed. Send the same value again. - Any other value raises `ValueError` before any request is sent. ```python diff --git a/src/pine_assistant/sessions.py b/src/pine_assistant/sessions.py index 4b349dd..a70c931 100644 --- a/src/pine_assistant/sessions.py +++ b/src/pine_assistant/sessions.py @@ -228,8 +228,8 @@ async def update_config( one, else the user's phone, else a number of the platform's pool; ``"platform"`` presents a number of the platform's pool. Set it at any time: the agent uses the value for its next call. A 503 - ``session_config_push_failed`` means the value is saved but has not - reached the running agent yet; send the same value again. + ``session_config_push_failed`` means the value is saved but delivery to + the running agent was not confirmed; send the same value again. """ body = _config_update(caller_id, ai_disclosure, recording_disclosure) try: From 2fecd0a83c90aa445e990a70c56d84bd8a113bd2 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Wed, 11 Nov 2026 16:50:22 +0000 Subject: [PATCH 03/10] fix(sessions): let the server decide which disclosure modes a user may set Accept ai_disclosure "off" client-side; the server rejects it for managed users with 400 and allows it for test accounts. Unknown values, None and non-strings are still refused before any request. Disclosure update tests now parse a realistic server response instead of the mock's echo. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 ++- docs/http-api.md | 11 +++++----- docs/sdk-api.md | 23 +++++++++---------- src/pine_assistant/models/session.py | 2 +- src/pine_assistant/sessions.py | 7 +++--- tests/test_profile_and_session_config.py | 28 +++++++++++++++++++++--- 6 files changed, 50 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index afb08fa..aaf3ea4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,8 @@ project adheres to [Semantic Versioning](https://semver.org/). Each setting, including `caller_id`, may be updated independently. Omitted fields stay unchanged; `None` and invalid values are rejected before sending. - `SessionConfig` reads effective AI and recording disclosure values, and the - public `AIDisclosure` type describes the managed-user modes. + public `AIDisclosure` type describes the disclosure modes. The server decides + which modes a user may set. ## [0.5.0rc4] - 2026-10-23 diff --git a/docs/http-api.md b/docs/http-api.md index 2b2e72c..09fbe7c 100644 --- a/docs/http-api.md +++ b/docs/http-api.md @@ -211,12 +211,12 @@ caller ID. `caller_id` is a session setting that selects it: ### Call disclosures -The config API accepts these additional fields for managed users: +The config API accepts these additional fields: | Field | Values | Default | |---|---|---| -| `ai_disclosure` | `"proactive"` (introduce as AI), `"on_request"` (disclose when asked) | `"proactive"` | -| `recording_disclosure` | JSON `true` or `false` | `true` | +| `ai_disclosure` | `"proactive"` (introduce as AI), `"on_request"` (disclose when asked), `"off"` (no AI disclosure) | `"proactive"` for managed users | +| `recording_disclosure` | JSON `true` or `false` | `true` for managed users | For example, `PUT /v2/sessions/{id}/config` with `{"ai_disclosure": "on_request", "recording_disclosure": false}` changes both. @@ -226,8 +226,9 @@ calls; calls already placed keep their settings. The same 503 push-failure behavior described above applies. `GET` returns the effective disclosure values, including defaults. Pine's own -users default to `"off"` and `false`; config API access restrictions remain -unchanged. Managed users cannot set `ai_disclosure="off"`. +users default to `"off"` and `false`. The server decides which modes a user may +set: managed users cannot set `ai_disclosure="off"`, and the request returns 400 +`invalid_request`. ### The user's time diff --git a/docs/sdk-api.md b/docs/sdk-api.md index db4426c..e50d762 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -176,9 +176,10 @@ await client.sessions.send_message(session["id"], "Call the clinic to book a vis Managed-user sessions default to `ai_disclosure="proactive"` and `recording_disclosure=True`. `"proactive"` makes the assistant introduce itself -as AI; `"on_request"` makes it disclose that identity when asked. Managed users -cannot select `"off"`. Pine's own users default to `"off"` and `False`; this -does not grant them access to the config API. +as AI; `"on_request"` makes it disclose that identity when asked; `"off"` +disables AI disclosure. The server decides which modes a user may set: it +rejects `"off"` for managed users with 400 `invalid_request`. Pine's own users +default to `"off"` and `False`. ```python session = await client.sessions.create() @@ -189,17 +190,16 @@ await client.sessions.send_message(session["id"], "Call the clinic to book a vis ``` Both `AsyncPineAI` and `PineAI` support these settings. Supply at least one -setting. Omitted settings stay unchanged; `None`, invalid modes and non-boolean +setting. Omitted settings stay unchanged; `None`, unknown modes and non-boolean recording values raise `ValueError` before any request is sent. Setting `recording_disclosure=False` disables the spoken recording notice, not recording. Changes affect subsequent calls; calls already placed keep their settings. The same 503 `session_config_push_failed` behavior described above applies. `sessions.get_config()` returns the effective disclosure values from the server. -`SessionConfig.ai_disclosure` can also be `"off"` on reads; both disclosure -fields are `None` when an older server omits them. The SDK does not choose -product defaults locally. `AIDisclosure`, exported from `pine_assistant`, types -the two modes accepted by `update_config()`. +Both disclosure fields are `None` when an older server omits them. The SDK does +not choose product defaults locally. `AIDisclosure`, exported from +`pine_assistant`, types the three modes accepted by `update_config()`. ### The user's time @@ -282,9 +282,10 @@ from `auth.*`, and `SessionError` from `sessions.list`, `get`, `get_config`, | 404 | `platform_managed_user_not_found` | No managed user of yours has this `external_id`. | | 429 | `too_many_requests` | Too many requests. | -`SessionError` from `sessions.get_config()` and `update_config()`: 403 -`forbidden` when the client is neither a managed user nor a test account, and 503 -`session_config_push_failed` (see "Caller ID"). +`SessionError` from `sessions.get_config()` and `update_config()`: 400 +`invalid_request` when the server rejects a value (for example `"off"` for a +managed user), 403 `forbidden` when the user may not use the config API, and +503 `session_config_push_failed` (see "Caller ID"). The codes for managed users are listed in [docs/http-api.md](http-api.md). Error messages never contain the key, the `external_id` or the user ID. diff --git a/src/pine_assistant/models/session.py b/src/pine_assistant/models/session.py index 3d7cff6..a07adba 100644 --- a/src/pine_assistant/models/session.py +++ b/src/pine_assistant/models/session.py @@ -7,7 +7,7 @@ from pydantic import BaseModel, ConfigDict, StrictBool, field_validator CallerID = Literal["user", "platform"] -AIDisclosure = Literal["proactive", "on_request"] +AIDisclosure = Literal["off", "on_request", "proactive"] class SessionInfo(BaseModel): diff --git a/src/pine_assistant/sessions.py b/src/pine_assistant/sessions.py index a70c931..f2cd60a 100644 --- a/src/pine_assistant/sessions.py +++ b/src/pine_assistant/sessions.py @@ -70,7 +70,7 @@ def _config_update( body["caller_id"] = _caller_id(caller_id) if ai_disclosure is not _Unset.VALUE: if ai_disclosure not in get_args(AIDisclosure): - raise ValueError('ai_disclosure must be "proactive" or "on_request"') + raise ValueError('ai_disclosure must be "off", "on_request" or "proactive"') body["ai_disclosure"] = ai_disclosure if recording_disclosure is not _Unset.VALUE: if not isinstance(recording_disclosure, bool): @@ -220,8 +220,9 @@ async def update_config( Omitted fields stay unchanged; explicit None is invalid. Managed users default to proactive AI disclosure and recording disclosure enabled. - Set ai_disclosure="on_request" to disclose AI identity only when asked; - "off" is not a managed-user setting. recording_disclosure=False disables + Set ai_disclosure="on_request" to disclose AI identity only when asked. + The server decides which modes a user may set and rejects "off" for + managed users with 400 ``invalid_request``. recording_disclosure=False disables the spoken notice, not recording. Calls already placed keep their settings. ``"user"``, or not set, presents the user's assistant number if it has diff --git a/tests/test_profile_and_session_config.py b/tests/test_profile_and_session_config.py index 3b8cdfb..826cc61 100644 --- a/tests/test_profile_and_session_config.py +++ b/tests/test_profile_and_session_config.py @@ -372,12 +372,15 @@ def test_socketio_message_carries_client_now_date_only_when_given(): @pytest.mark.parametrize("settings", [ {"ai_disclosure": "proactive"}, {"ai_disclosure": "on_request"}, + {"ai_disclosure": "off"}, {"recording_disclosure": False}, {"recording_disclosure": True}, {"caller_id": "platform", "ai_disclosure": "on_request", "recording_disclosure": False}, ]) async def test_disclosure_update_preserves_false_and_omits_unprovided_fields(sync, settings): - recorder = Recorder() + # The server always answers with both effective disclosure values. + effective = {"caller_id": "platform", "ai_disclosure": "proactive", "recording_disclosure": True} + recorder = Recorder(httpx.Response(200, json=success(effective))) if sync: with PineAI( api_key=API_KEY, user_id=PINE_USER_ID, base_url=BASE_URL, http_transport=httpx.MockTransport(recorder), @@ -388,7 +391,7 @@ async def test_disclosure_update_preserves_false_and_omits_unprovided_fields(syn config = await client.sessions.update_config(7, **settings) assert recorder.body() == settings - assert config.model_dump(exclude_unset=True) == settings + assert config == SessionConfig(**effective) [request] = recorder.requests assert (request.method, request.url.path) == ("PUT", "/api/v2/sessions/7/config") assert request.headers[MANAGED_USER_HEADER] == PINE_USER_ID @@ -399,8 +402,8 @@ async def test_disclosure_update_preserves_false_and_omits_unprovided_fields(syn {}, {"caller_id": None}, {"ai_disclosure": None}, - {"ai_disclosure": "off"}, {"ai_disclosure": "PROACTIVE"}, + {"ai_disclosure": "unknown"}, {"ai_disclosure": True}, {"recording_disclosure": None}, {"recording_disclosure": "false"}, @@ -421,6 +424,25 @@ async def test_invalid_disclosure_update_never_sends_request(sync, settings): assert recorder.requests == [] +@pytest.mark.parametrize("sync", [False, True]) +async def test_server_rejection_of_disclosure_mode_surfaces_as_session_error(sync): + recorder = Recorder(httpx.Response( + 400, json={"status": "error", "error": {"code": "invalid_request", "message": "invalid ai_disclosure"}}, + )) + if sync: + with PineAI( + api_key=API_KEY, user_id=PINE_USER_ID, base_url=BASE_URL, http_transport=httpx.MockTransport(recorder), + ) as client, pytest.raises(SessionError) as excinfo: + client.sessions.update_config(7, ai_disclosure="off") + else: + async with async_client(recorder, user_id=PINE_USER_ID) as client: + with pytest.raises(SessionError) as excinfo: + await client.sessions.update_config(7, ai_disclosure="off") + + assert (excinfo.value.code, excinfo.value.status_code) == ("invalid_request", 400) + assert recorder.body() == {"ai_disclosure": "off"} + + @pytest.mark.parametrize("sync", [False, True]) @pytest.mark.parametrize("payload", [ {"ai_disclosure": "proactive", "recording_disclosure": True}, From 717a7fc7b25741262c8822cb7d3744407fb8fdf4 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Wed, 11 Nov 2026 17:20:44 +0000 Subject: [PATCH 04/10] feat(sessions): use string modes for both call disclosure settings ai_disclosure takes disabled|on_request|proactive and recording_disclosure takes disabled|proactive, replacing "off" and the boolean. Updates accept only known strings; SessionConfig reads both as plain strings so a mode added by the server still parses. Docs describe test-account defaults, note that older servers may accept these settings without applying them, and the update_config docstring groups caller ID and disclosures. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 12 ++++--- docs/http-api.md | 17 ++++++---- docs/sdk-api.md | 41 +++++++++++++--------- src/pine_assistant/__init__.py | 2 ++ src/pine_assistant/models/session.py | 12 ++++--- src/pine_assistant/sessions.py | 43 +++++++++++++----------- tests/test_profile_and_session_config.py | 42 ++++++++++++----------- 7 files changed, 98 insertions(+), 71 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aaf3ea4..7572c84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,15 +7,17 @@ project adheres to [Semantic Versioning](https://semver.org/). ## [Unreleased] -### Added +### New - Session call disclosures on both async and sync clients: - `sessions.update_config(ai_disclosure="on_request", recording_disclosure=False)`. + `sessions.update_config(ai_disclosure="on_request", recording_disclosure="disabled")`. Each setting, including `caller_id`, may be updated independently. Omitted - fields stay unchanged; `None` and invalid values are rejected before sending. + fields stay unchanged; `None` and unknown values are rejected before sending. + Requires a server with session disclosure support; an older server may + silently accept these settings for test accounts without applying them. - `SessionConfig` reads effective AI and recording disclosure values, and the - public `AIDisclosure` type describes the disclosure modes. The server decides - which modes a user may set. + public `AIDisclosure` and `RecordingDisclosure` types describe the modes. The + server decides which modes a user may set. ## [0.5.0rc4] - 2026-10-23 diff --git a/docs/http-api.md b/docs/http-api.md index 09fbe7c..b06d888 100644 --- a/docs/http-api.md +++ b/docs/http-api.md @@ -215,20 +215,23 @@ The config API accepts these additional fields: | Field | Values | Default | |---|---|---| -| `ai_disclosure` | `"proactive"` (introduce as AI), `"on_request"` (disclose when asked), `"off"` (no AI disclosure) | `"proactive"` for managed users | -| `recording_disclosure` | JSON `true` or `false` | `true` for managed users | +| `ai_disclosure` | `"proactive"` (introduce as AI), `"on_request"` (disclose when asked), `"disabled"` | `"proactive"` for managed users | +| `recording_disclosure` | `"proactive"` (announce that the call is recorded), `"disabled"` | `"proactive"` for managed users | For example, `PUT /v2/sessions/{id}/config` with -`{"ai_disclosure": "on_request", "recording_disclosure": false}` changes both. +`{"ai_disclosure": "on_request", "recording_disclosure": "disabled"}` changes both. Omitted fields stay unchanged; `null` is invalid. Recording disclosure controls the spoken notice, not whether the call is recorded. Changes affect subsequent calls; calls already placed keep their settings. The same 503 push-failure behavior described above applies. -`GET` returns the effective disclosure values, including defaults. Pine's own -users default to `"off"` and `false`. The server decides which modes a user may -set: managed users cannot set `ai_disclosure="off"`, and the request returns 400 -`invalid_request`. +`GET` returns the effective disclosure values, including defaults. Pine test +accounts default to `"disabled"` for both. The server decides which modes a user +may set: managed users cannot set `ai_disclosure="disabled"`, and the request +returns 400 `invalid_request`. + +These fields require a server with session disclosure support. An older server +may silently accept them for test accounts without applying them. ### The user's time diff --git a/docs/sdk-api.md b/docs/sdk-api.md index e50d762..ef62ac4 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -174,32 +174,43 @@ await client.sessions.send_message(session["id"], "Call the clinic to book a vis ### Call disclosures -Managed-user sessions default to `ai_disclosure="proactive"` and -`recording_disclosure=True`. `"proactive"` makes the assistant introduce itself -as AI; `"on_request"` makes it disclose that identity when asked; `"off"` -disables AI disclosure. The server decides which modes a user may set: it -rejects `"off"` for managed users with 400 `invalid_request`. Pine's own users -default to `"off"` and `False`. +Two settings control what the assistant says on a call: + +| Setting | Values | +|---|---| +| `ai_disclosure` | `"proactive"` (introduce itself as AI), `"on_request"` (disclose that identity when asked), `"disabled"` | +| `recording_disclosure` | `"proactive"` (announce that the call is recorded), `"disabled"` | + +Managed-user sessions default to `"proactive"` for both. Pine test accounts +default to `"disabled"` for both. The server decides which modes a user may +set: it rejects `ai_disclosure="disabled"` for managed users with 400 +`invalid_request`. + +These settings require a server with session disclosure support. An older +server may silently accept them for test accounts without applying them. ```python session = await client.sessions.create() config = await client.sessions.update_config( - session["id"], ai_disclosure="on_request", recording_disclosure=False, + session["id"], ai_disclosure="on_request", recording_disclosure="disabled", ) await client.sessions.send_message(session["id"], "Call the clinic to book a visit") ``` Both `AsyncPineAI` and `PineAI` support these settings. Supply at least one -setting. Omitted settings stay unchanged; `None`, unknown modes and non-boolean -recording values raise `ValueError` before any request is sent. Setting -`recording_disclosure=False` disables the spoken recording notice, not recording. +setting. Omitted settings stay unchanged; `None`, non-strings and unknown modes +raise `ValueError` before any request is sent. Setting +`recording_disclosure="disabled"` turns off the spoken recording notice, not +recording. Changes affect subsequent calls; calls already placed keep their settings. The same 503 `session_config_push_failed` behavior described above applies. `sessions.get_config()` returns the effective disclosure values from the server. -Both disclosure fields are `None` when an older server omits them. The SDK does -not choose product defaults locally. `AIDisclosure`, exported from -`pine_assistant`, types the three modes accepted by `update_config()`. +Both disclosure fields are `None` when an older server omits them. They are +read as plain strings, so a mode added later by the server still parses. The +SDK does not choose product defaults locally. `AIDisclosure` and +`RecordingDisclosure`, exported from `pine_assistant`, type the modes accepted +by `update_config()`. ### The user's time @@ -283,8 +294,8 @@ from `auth.*`, and `SessionError` from `sessions.list`, `get`, `get_config`, | 429 | `too_many_requests` | Too many requests. | `SessionError` from `sessions.get_config()` and `update_config()`: 400 -`invalid_request` when the server rejects a value (for example `"off"` for a -managed user), 403 `forbidden` when the user may not use the config API, and +`invalid_request` when the server rejects a value (for example +`ai_disclosure="disabled"` for a managed user), 403 `forbidden` when the user may not use the config API, and 503 `session_config_push_failed` (see "Caller ID"). The codes for managed users are listed in [docs/http-api.md](http-api.md). diff --git a/src/pine_assistant/__init__.py b/src/pine_assistant/__init__.py index accee25..1295469 100644 --- a/src/pine_assistant/__init__.py +++ b/src/pine_assistant/__init__.py @@ -24,6 +24,7 @@ from pine_assistant.models.session import ( AIDisclosure, CallerID, + RecordingDisclosure, SessionConfig, SessionHistoryMessage, SessionHistoryPage, @@ -77,6 +78,7 @@ "SessionConfig", "CallerID", "AIDisclosure", + "RecordingDisclosure", "SessionHistoryMessage", "SessionHistoryPage", "SessionListResponse", diff --git a/src/pine_assistant/models/session.py b/src/pine_assistant/models/session.py index a07adba..6bbe8f4 100644 --- a/src/pine_assistant/models/session.py +++ b/src/pine_assistant/models/session.py @@ -4,10 +4,11 @@ from typing import Any, Literal -from pydantic import BaseModel, ConfigDict, StrictBool, field_validator +from pydantic import BaseModel, ConfigDict, StrictStr, field_validator CallerID = Literal["user", "platform"] -AIDisclosure = Literal["off", "on_request", "proactive"] +AIDisclosure = Literal["disabled", "on_request", "proactive"] +RecordingDisclosure = Literal["disabled", "proactive"] class SessionInfo(BaseModel): @@ -41,9 +42,10 @@ class SessionConfig(BaseModel): model_config = ConfigDict(extra="allow") caller_id: str | None = None - # Missing values preserve compatibility with servers predating disclosure settings. - ai_disclosure: str | None = None - recording_disclosure: StrictBool | None = None + # None means a server predating disclosure settings. Both are plain strings, + # not the update Literals, on purpose: a mode added by the server still parses. + ai_disclosure: StrictStr | None = None + recording_disclosure: StrictStr | None = None class SessionListResponse(BaseModel): diff --git a/src/pine_assistant/sessions.py b/src/pine_assistant/sessions.py index f2cd60a..cc37729 100644 --- a/src/pine_assistant/sessions.py +++ b/src/pine_assistant/sessions.py @@ -15,6 +15,7 @@ from pine_assistant.models.session import ( AIDisclosure, CallerID, + RecordingDisclosure, SessionConfig, SessionHistoryPage, SessionInfo, @@ -63,18 +64,18 @@ class _Unset(Enum): def _config_update( caller_id: CallerID | _Unset, ai_disclosure: AIDisclosure | _Unset, - recording_disclosure: bool | _Unset, + recording_disclosure: RecordingDisclosure | _Unset, ) -> dict[str, Any]: body: dict[str, Any] = {} if caller_id is not _Unset.VALUE: body["caller_id"] = _caller_id(caller_id) if ai_disclosure is not _Unset.VALUE: if ai_disclosure not in get_args(AIDisclosure): - raise ValueError('ai_disclosure must be "off", "on_request" or "proactive"') + raise ValueError('ai_disclosure must be "disabled", "on_request" or "proactive"') body["ai_disclosure"] = ai_disclosure if recording_disclosure is not _Unset.VALUE: - if not isinstance(recording_disclosure, bool): - raise ValueError("recording_disclosure must be a boolean") + if recording_disclosure not in get_args(RecordingDisclosure): + raise ValueError('recording_disclosure must be "disabled" or "proactive"') body["recording_disclosure"] = recording_disclosure if not body: raise ValueError("provide at least one session config setting") @@ -214,23 +215,27 @@ async def update_config( *, caller_id: CallerID | _Unset = _Unset.VALUE, ai_disclosure: AIDisclosure | _Unset = _Unset.VALUE, - recording_disclosure: bool | _Unset = _Unset.VALUE, + recording_disclosure: RecordingDisclosure | _Unset = _Unset.VALUE, ) -> SessionConfig: """Update settings for the next calls the agent places in this session. - Omitted fields stay unchanged; explicit None is invalid. Managed users - default to proactive AI disclosure and recording disclosure enabled. - Set ai_disclosure="on_request" to disclose AI identity only when asked. - The server decides which modes a user may set and rejects "off" for - managed users with 400 ``invalid_request``. recording_disclosure=False disables - the spoken notice, not recording. Calls already placed keep their settings. - - ``"user"``, or not set, presents the user's assistant number if it has - one, else the user's phone, else a number of the platform's pool; - ``"platform"`` presents a number of the platform's pool. Set it at any - time: the agent uses the value for its next call. A 503 - ``session_config_push_failed`` means the value is saved but delivery to - the running agent was not confirmed; send the same value again. + Omitted fields stay unchanged; explicit None is invalid. Calls already + placed keep their settings. A 503 ``session_config_push_failed`` means + the value is saved but delivery to the running agent was not confirmed; + send the same value again. + + caller_id selects the number the call shows. ``"user"``, or not set, + presents the user's assistant number if it has one, else the user's + phone, else a number of the platform's pool; ``"platform"`` presents a + number of the platform's pool. + + ai_disclosure and recording_disclosure control what the assistant says + on the call. Managed users default to ``"proactive"`` for both and the + server rejects ai_disclosure="disabled" for them with 400 + ``invalid_request``; the server decides which modes a user may set. + ai_disclosure="on_request" discloses AI identity only when asked. + recording_disclosure="disabled" turns off the spoken notice, not + recording. """ body = _config_update(caller_id, ai_disclosure, recording_disclosure) try: @@ -409,7 +414,7 @@ def update_config( *, caller_id: CallerID | _Unset = _Unset.VALUE, ai_disclosure: AIDisclosure | _Unset = _Unset.VALUE, - recording_disclosure: bool | _Unset = _Unset.VALUE, + recording_disclosure: RecordingDisclosure | _Unset = _Unset.VALUE, ) -> SessionConfig: """Update next-call settings; see :meth:`SessionsAPI.update_config` for semantics.""" body = _config_update(caller_id, ai_disclosure, recording_disclosure) diff --git a/tests/test_profile_and_session_config.py b/tests/test_profile_and_session_config.py index 826cc61..ba1483e 100644 --- a/tests/test_profile_and_session_config.py +++ b/tests/test_profile_and_session_config.py @@ -372,14 +372,14 @@ def test_socketio_message_carries_client_now_date_only_when_given(): @pytest.mark.parametrize("settings", [ {"ai_disclosure": "proactive"}, {"ai_disclosure": "on_request"}, - {"ai_disclosure": "off"}, - {"recording_disclosure": False}, - {"recording_disclosure": True}, - {"caller_id": "platform", "ai_disclosure": "on_request", "recording_disclosure": False}, + {"ai_disclosure": "disabled"}, + {"recording_disclosure": "disabled"}, + {"recording_disclosure": "proactive"}, + {"caller_id": "platform", "ai_disclosure": "on_request", "recording_disclosure": "disabled"}, ]) -async def test_disclosure_update_preserves_false_and_omits_unprovided_fields(sync, settings): +async def test_disclosure_update_sends_only_provided_fields(sync, settings): # The server always answers with both effective disclosure values. - effective = {"caller_id": "platform", "ai_disclosure": "proactive", "recording_disclosure": True} + effective = {"caller_id": "platform", "ai_disclosure": "proactive", "recording_disclosure": "proactive"} recorder = Recorder(httpx.Response(200, json=success(effective))) if sync: with PineAI( @@ -400,15 +400,15 @@ async def test_disclosure_update_preserves_false_and_omits_unprovided_fields(syn @pytest.mark.parametrize("sync", [False, True]) @pytest.mark.parametrize("settings", [ {}, - {"caller_id": None}, {"ai_disclosure": None}, + {"ai_disclosure": "off"}, {"ai_disclosure": "PROACTIVE"}, - {"ai_disclosure": "unknown"}, {"ai_disclosure": True}, {"recording_disclosure": None}, - {"recording_disclosure": "false"}, + {"recording_disclosure": "on_request"}, + {"recording_disclosure": False}, + {"recording_disclosure": True}, {"recording_disclosure": 0}, - {"recording_disclosure": 1}, ]) async def test_invalid_disclosure_update_never_sends_request(sync, settings): recorder = Recorder() @@ -433,21 +433,22 @@ async def test_server_rejection_of_disclosure_mode_surfaces_as_session_error(syn with PineAI( api_key=API_KEY, user_id=PINE_USER_ID, base_url=BASE_URL, http_transport=httpx.MockTransport(recorder), ) as client, pytest.raises(SessionError) as excinfo: - client.sessions.update_config(7, ai_disclosure="off") + client.sessions.update_config(7, ai_disclosure="disabled") else: async with async_client(recorder, user_id=PINE_USER_ID) as client: with pytest.raises(SessionError) as excinfo: - await client.sessions.update_config(7, ai_disclosure="off") + await client.sessions.update_config(7, ai_disclosure="disabled") assert (excinfo.value.code, excinfo.value.status_code) == ("invalid_request", 400) - assert recorder.body() == {"ai_disclosure": "off"} + assert recorder.body() == {"ai_disclosure": "disabled"} @pytest.mark.parametrize("sync", [False, True]) @pytest.mark.parametrize("payload", [ - {"ai_disclosure": "proactive", "recording_disclosure": True}, - {"ai_disclosure": "on_request", "recording_disclosure": False}, - {"ai_disclosure": "off", "recording_disclosure": False}, + {"ai_disclosure": "proactive", "recording_disclosure": "proactive"}, + {"ai_disclosure": "on_request", "recording_disclosure": "disabled"}, + {"ai_disclosure": "disabled", "recording_disclosure": "disabled"}, + {"ai_disclosure": "a_future_mode", "recording_disclosure": "a_future_mode"}, {}, ]) async def test_read_disclosure_config_and_older_servers(sync, payload): @@ -461,12 +462,13 @@ async def test_read_disclosure_config_and_older_servers(sync, payload): async with async_client(recorder, user_id=PINE_USER_ID) as client: config = await client.sessions.get_config(7) assert config.ai_disclosure == payload.get("ai_disclosure") - assert config.recording_disclosure is payload.get("recording_disclosure") + assert config.recording_disclosure == payload.get("recording_disclosure") -@pytest.mark.parametrize("recording_disclosure", ["false", 0, 1]) -async def test_malformed_disclosure_response_is_not_coerced(recording_disclosure): - recorder = Recorder(httpx.Response(200, json=success({"recording_disclosure": recording_disclosure}))) +@pytest.mark.parametrize("field", ["ai_disclosure", "recording_disclosure"]) +@pytest.mark.parametrize("value", [True, 0, 1]) +async def test_malformed_disclosure_response_is_not_coerced(field, value): + recorder = Recorder(httpx.Response(200, json=success({field: value}))) async with async_client(recorder, user_id=PINE_USER_ID) as client: with pytest.raises(SessionError, match="invalid session config response"): await client.sessions.get_config(7) From a5ce4b6025c920623f1a1d6c95cbb1a858b7bff8 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Wed, 11 Nov 2026 17:39:49 +0000 Subject: [PATCH 05/10] refactor(sessions): treat None as unchanged in update_config Match the SDK's partial-update convention: None leaves a session setting unchanged and is not sent, replacing the private sentinel; a call with nothing to change still raises ValueError before any request. Response disclosure fields use plain str. Docs note that a 500 means the change was not saved, and the changelog says caller_id is no longer required. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 22 ++++++---- docs/http-api.md | 7 +-- docs/sdk-api.md | 19 +++++---- src/pine_assistant/models/session.py | 6 +-- src/pine_assistant/sessions.py | 54 +++++++++++++----------- tests/test_profile_and_session_config.py | 9 ++-- 6 files changed, 64 insertions(+), 53 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7572c84..7dd54b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,15 +9,19 @@ project adheres to [Semantic Versioning](https://semver.org/). ### New -- Session call disclosures on both async and sync clients: - `sessions.update_config(ai_disclosure="on_request", recording_disclosure="disabled")`. - Each setting, including `caller_id`, may be updated independently. Omitted - fields stay unchanged; `None` and unknown values are rejected before sending. - Requires a server with session disclosure support; an older server may - silently accept these settings for test accounts without applying them. -- `SessionConfig` reads effective AI and recording disclosure values, and the - public `AIDisclosure` and `RecordingDisclosure` types describe the modes. The - server decides which modes a user may set. +- **Choose call disclosures.** + `sessions.update_config(ai_disclosure="on_request", recording_disclosure="disabled")` + sets whether the assistant says it is an AI and that the call is recorded, on + both async and sync clients. Requires a server with session disclosure + support; an older server may silently accept these settings for test + accounts without applying them. +- **`caller_id` is no longer required.** `update_config()` changes only the + settings given; `None` leaves a setting unchanged. A call with nothing to + change, or an unknown value, raises `ValueError` before sending. +- **Read disclosures.** `SessionConfig` has the effective `ai_disclosure` and + `recording_disclosure`, and the public `AIDisclosure` and + `RecordingDisclosure` types describe the modes. The server decides which + modes a user may set. ## [0.5.0rc4] - 2026-10-23 diff --git a/docs/http-api.md b/docs/http-api.md index b06d888..3ac68b1 100644 --- a/docs/http-api.md +++ b/docs/http-api.md @@ -207,7 +207,8 @@ caller ID. `caller_id` is a session setting that selects it: uses the user's phone for that. - Invalid values or unsupported config keys return 400 `invalid_request`. - 503 `session_config_push_failed` means that the value is saved, but delivery to - the running agent was not confirmed. Send the same request again. + the running agent was not confirmed. Send the same request again. A 500 means + that the change was not saved. ### Call disclosures @@ -222,8 +223,8 @@ For example, `PUT /v2/sessions/{id}/config` with `{"ai_disclosure": "on_request", "recording_disclosure": "disabled"}` changes both. Omitted fields stay unchanged; `null` is invalid. Recording disclosure controls the spoken notice, not whether the call is recorded. Changes affect subsequent -calls; calls already placed keep their settings. The same 503 push-failure -behavior described above applies. +calls; calls already placed keep their settings. The same 503 and 500 behavior +described above applies. `GET` returns the effective disclosure values, including defaults. Pine test accounts default to `"disabled"` for both. The server decides which modes a user diff --git a/docs/sdk-api.md b/docs/sdk-api.md index ef62ac4..f319460 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -122,7 +122,7 @@ user = await partner_client.platform.managed_users.update( | `sessions.list(...)` | `SessionListResponse` | | `sessions.get(session_id)` | `SessionInfo` | | `sessions.get_config(session_id)` | `SessionConfig` | -| `sessions.update_config(session_id, *, caller_id=…, ai_disclosure=…, recording_disclosure=…)` | `SessionConfig` after the change | +| `sessions.update_config(session_id, *, caller_id=None, ai_disclosure=None, recording_disclosure=None)` | `SessionConfig` after the change | | `sessions.send_message(session_id, content, ..., client_now_date=None)` | `SessionMessageStatus` | | `sessions.history(session_id, *, limit=30, before_message_id=None)` | `SessionHistoryPage`: one page of stored messages, newest first | | `sessions.start_task(session_id)` | `dict` | @@ -163,7 +163,8 @@ caller ID. `caller_id` is a session setting that selects it: - `caller_id` does not change how the agent reaches the user. The agent still uses the user's phone for that. - A 503 `session_config_push_failed` means that the value is saved, but delivery to - the running agent was not confirmed. Send the same value again. + the running agent was not confirmed. Send the same value again. A 500 means + that the change was not saved. - Any other value raises `ValueError` before any request is sent. ```python @@ -197,13 +198,14 @@ config = await client.sessions.update_config( await client.sessions.send_message(session["id"], "Call the clinic to book a visit") ``` -Both `AsyncPineAI` and `PineAI` support these settings. Supply at least one -setting. Omitted settings stay unchanged; `None`, non-strings and unknown modes -raise `ValueError` before any request is sent. Setting +Both `AsyncPineAI` and `PineAI` support these settings. `update_config()` +changes only the settings given; `None` leaves a setting unchanged and is not +sent. A call with no setting to change, a non-string or an unknown mode raises +`ValueError` before any request is sent. Setting `recording_disclosure="disabled"` turns off the spoken recording notice, not recording. Changes affect subsequent calls; calls already placed keep their settings. -The same 503 `session_config_push_failed` behavior described above applies. +The same 503 and 500 behavior described above applies. `sessions.get_config()` returns the effective disclosure values from the server. Both disclosure fields are `None` when an older server omits them. They are @@ -295,8 +297,9 @@ from `auth.*`, and `SessionError` from `sessions.list`, `get`, `get_config`, `SessionError` from `sessions.get_config()` and `update_config()`: 400 `invalid_request` when the server rejects a value (for example -`ai_disclosure="disabled"` for a managed user), 403 `forbidden` when the user may not use the config API, and -503 `session_config_push_failed` (see "Caller ID"). +`ai_disclosure="disabled"` for a managed user), 403 `forbidden` when the user +may not use the config API, 503 `session_config_push_failed` when the change is +saved but not delivered, and 500 when it was not saved (see "Caller ID"). The codes for managed users are listed in [docs/http-api.md](http-api.md). Error messages never contain the key, the `external_id` or the user ID. diff --git a/src/pine_assistant/models/session.py b/src/pine_assistant/models/session.py index 6bbe8f4..60c32a3 100644 --- a/src/pine_assistant/models/session.py +++ b/src/pine_assistant/models/session.py @@ -4,7 +4,7 @@ from typing import Any, Literal -from pydantic import BaseModel, ConfigDict, StrictStr, field_validator +from pydantic import BaseModel, ConfigDict, field_validator CallerID = Literal["user", "platform"] AIDisclosure = Literal["disabled", "on_request", "proactive"] @@ -44,8 +44,8 @@ class SessionConfig(BaseModel): caller_id: str | None = None # None means a server predating disclosure settings. Both are plain strings, # not the update Literals, on purpose: a mode added by the server still parses. - ai_disclosure: StrictStr | None = None - recording_disclosure: StrictStr | None = None + ai_disclosure: str | None = None + recording_disclosure: str | None = None class SessionListResponse(BaseModel): diff --git a/src/pine_assistant/sessions.py b/src/pine_assistant/sessions.py index cc37729..fdb5c6b 100644 --- a/src/pine_assistant/sessions.py +++ b/src/pine_assistant/sessions.py @@ -6,7 +6,6 @@ import re from datetime import datetime -from enum import Enum from typing import Any, get_args from pydantic import ValidationError @@ -57,26 +56,30 @@ def _caller_id(caller_id: CallerID) -> CallerID: return caller_id -class _Unset(Enum): - VALUE = "unset" +def _ai_disclosure(ai_disclosure: AIDisclosure) -> AIDisclosure: + if ai_disclosure not in get_args(AIDisclosure): + raise ValueError('ai_disclosure must be "disabled", "on_request" or "proactive"') + return ai_disclosure + + +def _recording_disclosure(recording_disclosure: RecordingDisclosure) -> RecordingDisclosure: + if recording_disclosure not in get_args(RecordingDisclosure): + raise ValueError('recording_disclosure must be "disabled" or "proactive"') + return recording_disclosure def _config_update( - caller_id: CallerID | _Unset, - ai_disclosure: AIDisclosure | _Unset, - recording_disclosure: RecordingDisclosure | _Unset, + caller_id: CallerID | None, + ai_disclosure: AIDisclosure | None, + recording_disclosure: RecordingDisclosure | None, ) -> dict[str, Any]: body: dict[str, Any] = {} - if caller_id is not _Unset.VALUE: + if caller_id is not None: body["caller_id"] = _caller_id(caller_id) - if ai_disclosure is not _Unset.VALUE: - if ai_disclosure not in get_args(AIDisclosure): - raise ValueError('ai_disclosure must be "disabled", "on_request" or "proactive"') - body["ai_disclosure"] = ai_disclosure - if recording_disclosure is not _Unset.VALUE: - if recording_disclosure not in get_args(RecordingDisclosure): - raise ValueError('recording_disclosure must be "disabled" or "proactive"') - body["recording_disclosure"] = recording_disclosure + if ai_disclosure is not None: + body["ai_disclosure"] = _ai_disclosure(ai_disclosure) + if recording_disclosure is not None: + body["recording_disclosure"] = _recording_disclosure(recording_disclosure) if not body: raise ValueError("provide at least one session config setting") return body @@ -213,16 +216,17 @@ async def update_config( self, session_id: str | int, *, - caller_id: CallerID | _Unset = _Unset.VALUE, - ai_disclosure: AIDisclosure | _Unset = _Unset.VALUE, - recording_disclosure: RecordingDisclosure | _Unset = _Unset.VALUE, + caller_id: CallerID | None = None, + ai_disclosure: AIDisclosure | None = None, + recording_disclosure: RecordingDisclosure | None = None, ) -> SessionConfig: """Update settings for the next calls the agent places in this session. - Omitted fields stay unchanged; explicit None is invalid. Calls already - placed keep their settings. A 503 ``session_config_push_failed`` means - the value is saved but delivery to the running agent was not confirmed; - send the same value again. + Change only the settings given; ``None`` leaves a setting unchanged. + Calls already placed keep their settings. A 503 + ``session_config_push_failed`` means the value is saved but delivery to + the running agent was not confirmed; send the same value again. A 500 + means the change was not saved. caller_id selects the number the call shows. ``"user"``, or not set, presents the user's assistant number if it has one, else the user's @@ -412,9 +416,9 @@ def update_config( self, session_id: str | int, *, - caller_id: CallerID | _Unset = _Unset.VALUE, - ai_disclosure: AIDisclosure | _Unset = _Unset.VALUE, - recording_disclosure: RecordingDisclosure | _Unset = _Unset.VALUE, + caller_id: CallerID | None = None, + ai_disclosure: AIDisclosure | None = None, + recording_disclosure: RecordingDisclosure | None = None, ) -> SessionConfig: """Update next-call settings; see :meth:`SessionsAPI.update_config` for semantics.""" body = _config_update(caller_id, ai_disclosure, recording_disclosure) diff --git a/tests/test_profile_and_session_config.py b/tests/test_profile_and_session_config.py index ba1483e..cdfa1a8 100644 --- a/tests/test_profile_and_session_config.py +++ b/tests/test_profile_and_session_config.py @@ -228,7 +228,7 @@ async def test_update_config_puts_the_caller_id_as_the_managed_user(caller_id): @pytest.mark.asyncio -@pytest.mark.parametrize("caller_id", ["pine", "", None, "PLATFORM"]) +@pytest.mark.parametrize("caller_id", ["pine", "", "PLATFORM"]) async def test_invalid_caller_id_is_refused_before_any_request(caller_id): recorder = Recorder() async with async_client(recorder, user_id=PINE_USER_ID) as client: @@ -372,10 +372,10 @@ def test_socketio_message_carries_client_now_date_only_when_given(): @pytest.mark.parametrize("settings", [ {"ai_disclosure": "proactive"}, {"ai_disclosure": "on_request"}, - {"ai_disclosure": "disabled"}, {"recording_disclosure": "disabled"}, {"recording_disclosure": "proactive"}, {"caller_id": "platform", "ai_disclosure": "on_request", "recording_disclosure": "disabled"}, + {"caller_id": None, "ai_disclosure": "on_request", "recording_disclosure": None}, ]) async def test_disclosure_update_sends_only_provided_fields(sync, settings): # The server always answers with both effective disclosure values. @@ -390,7 +390,7 @@ async def test_disclosure_update_sends_only_provided_fields(sync, settings): async with async_client(recorder, user_id=PINE_USER_ID) as client: config = await client.sessions.update_config(7, **settings) - assert recorder.body() == settings + assert recorder.body() == {key: value for key, value in settings.items() if value is not None} assert config == SessionConfig(**effective) [request] = recorder.requests assert (request.method, request.url.path) == ("PUT", "/api/v2/sessions/7/config") @@ -400,11 +400,10 @@ async def test_disclosure_update_sends_only_provided_fields(sync, settings): @pytest.mark.parametrize("sync", [False, True]) @pytest.mark.parametrize("settings", [ {}, - {"ai_disclosure": None}, + {"caller_id": None, "ai_disclosure": None, "recording_disclosure": None}, {"ai_disclosure": "off"}, {"ai_disclosure": "PROACTIVE"}, {"ai_disclosure": True}, - {"recording_disclosure": None}, {"recording_disclosure": "on_request"}, {"recording_disclosure": False}, {"recording_disclosure": True}, From ca305607f8736fb89563cc1faead8d64a616ae39 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 12 Nov 2026 04:34:28 +0000 Subject: [PATCH 06/10] docs(sessions): match the server's wording for a 500 on config updates Co-Authored-By: Claude Opus 5.5 --- docs/http-api.md | 5 +++-- docs/sdk-api.md | 7 ++++--- src/pine_assistant/sessions.py | 3 ++- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/http-api.md b/docs/http-api.md index 3ac68b1..8523669 100644 --- a/docs/http-api.md +++ b/docs/http-api.md @@ -207,8 +207,9 @@ caller ID. `caller_id` is a session setting that selects it: uses the user's phone for that. - Invalid values or unsupported config keys return 400 `invalid_request`. - 503 `session_config_push_failed` means that the value is saved, but delivery to - the running agent was not confirmed. Send the same request again. A 500 means - that the change was not saved. + the running agent was not confirmed. Send the same request again. A 500 normally + means the change was not saved; if unsure, GET the settings or resend the same + PUT. ### Call disclosures diff --git a/docs/sdk-api.md b/docs/sdk-api.md index f319460..7735710 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -163,8 +163,9 @@ caller ID. `caller_id` is a session setting that selects it: - `caller_id` does not change how the agent reaches the user. The agent still uses the user's phone for that. - A 503 `session_config_push_failed` means that the value is saved, but delivery to - the running agent was not confirmed. Send the same value again. A 500 means - that the change was not saved. + the running agent was not confirmed. Send the same value again. A 500 normally means + that the change was not saved; if unsure, call `get_config()` or send the same + value again. - Any other value raises `ValueError` before any request is sent. ```python @@ -299,7 +300,7 @@ from `auth.*`, and `SessionError` from `sessions.list`, `get`, `get_config`, `invalid_request` when the server rejects a value (for example `ai_disclosure="disabled"` for a managed user), 403 `forbidden` when the user may not use the config API, 503 `session_config_push_failed` when the change is -saved but not delivered, and 500 when it was not saved (see "Caller ID"). +saved but not delivered, and 500 when it was normally not saved (see "Caller ID"). The codes for managed users are listed in [docs/http-api.md](http-api.md). Error messages never contain the key, the `external_id` or the user ID. diff --git a/src/pine_assistant/sessions.py b/src/pine_assistant/sessions.py index fdb5c6b..d34f5c9 100644 --- a/src/pine_assistant/sessions.py +++ b/src/pine_assistant/sessions.py @@ -226,7 +226,8 @@ async def update_config( Calls already placed keep their settings. A 503 ``session_config_push_failed`` means the value is saved but delivery to the running agent was not confirmed; send the same value again. A 500 - means the change was not saved. + normally means the change was not saved; if unsure, call + :meth:`get_config` or send the same value again. caller_id selects the number the call shows. ``"user"``, or not set, presents the user's assistant number if it has one, else the user's From 7c52a10dce3eef121c6b1fdad1fb50c4d7af5790 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 12 Nov 2026 09:06:36 +0000 Subject: [PATCH 07/10] docs(sessions): note that a timed-out config update may have been saved Co-Authored-By: Claude Opus 5.5 --- docs/sdk-api.md | 5 +++-- src/pine_assistant/sessions.py | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/sdk-api.md b/docs/sdk-api.md index 7735710..c231ce6 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -164,8 +164,9 @@ caller ID. `caller_id` is a session setting that selects it: uses the user's phone for that. - A 503 `session_config_push_failed` means that the value is saved, but delivery to the running agent was not confirmed. Send the same value again. A 500 normally means - that the change was not saved; if unsure, call `get_config()` or send the same - value again. + that the change was not saved. After a timeout, a dropped connection or a 502/504 + the change may or may not be saved. If unsure, call `get_config()` or send the + same value again; sending it again is safe. - Any other value raises `ValueError` before any request is sent. ```python diff --git a/src/pine_assistant/sessions.py b/src/pine_assistant/sessions.py index d34f5c9..74f4c0b 100644 --- a/src/pine_assistant/sessions.py +++ b/src/pine_assistant/sessions.py @@ -226,8 +226,9 @@ async def update_config( Calls already placed keep their settings. A 503 ``session_config_push_failed`` means the value is saved but delivery to the running agent was not confirmed; send the same value again. A 500 - normally means the change was not saved; if unsure, call - :meth:`get_config` or send the same value again. + normally means the change was not saved. After a timeout, a dropped + connection or a 502/504 it may or may not be saved. If unsure, call + :meth:`get_config` or send the same value again; resending is safe. caller_id selects the number the call shows. ``"user"``, or not set, presents the user's assistant number if it has one, else the user's From a7a27f831d0efcb5d1efb4fb1f7e01b560091415 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Fri, 13 Nov 2026 08:57:59 +0000 Subject: [PATCH 08/10] refactor(sessions): stop exposing the recording disclosure setting The SDK offers ai_disclosure and caller_id only. Remove recording_disclosure from update_config() and SessionConfig, drop the RecordingDisclosure type, and remove it from the docs and changelog. SessionConfig still allows extra fields, so a server response that carries recording_disclosure still parses. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 18 +++++----- docs/http-api.md | 42 +++++++++++------------ docs/sdk-api.md | 43 +++++++++++------------- src/pine_assistant/__init__.py | 2 -- src/pine_assistant/models/session.py | 6 ++-- src/pine_assistant/sessions.py | 33 +++++------------- tests/test_profile_and_session_config.py | 30 ++++++++--------- 7 files changed, 73 insertions(+), 101 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7dd54b3..7a1c101 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,19 +9,17 @@ project adheres to [Semantic Versioning](https://semver.org/). ### New -- **Choose call disclosures.** - `sessions.update_config(ai_disclosure="on_request", recording_disclosure="disabled")` - sets whether the assistant says it is an AI and that the call is recorded, on - both async and sync clients. Requires a server with session disclosure - support; an older server may silently accept these settings for test - accounts without applying them. +- **Choose AI disclosure.** + `sessions.update_config(ai_disclosure="on_request")` sets whether the + assistant says it is an AI, on both async and sync clients. Requires a + server with session disclosure support; an older server may silently accept + the setting for test accounts without applying it. - **`caller_id` is no longer required.** `update_config()` changes only the settings given; `None` leaves a setting unchanged. A call with nothing to change, or an unknown value, raises `ValueError` before sending. -- **Read disclosures.** `SessionConfig` has the effective `ai_disclosure` and - `recording_disclosure`, and the public `AIDisclosure` and - `RecordingDisclosure` types describe the modes. The server decides which - modes a user may set. +- **Read AI disclosure.** `SessionConfig` has the effective `ai_disclosure`, + and the public `AIDisclosure` type describes the modes. The server decides + which modes a user may set. ## [0.5.0rc4] - 2026-10-23 diff --git a/docs/http-api.md b/docs/http-api.md index 8523669..293e20a 100644 --- a/docs/http-api.md +++ b/docs/http-api.md @@ -154,8 +154,8 @@ These routes take the two headers above. | `POST /v2/sessions` | Creates a session. | `sessions.create()` | | `GET /v2/sessions` | Lists the user's sessions. | `sessions.list()` | | `GET /v2/sessions/{id}` | Returns one session. | `sessions.get()` | -| `GET /v2/sessions/{id}/config` | Returns session config with effective `ai_disclosure` and `recording_disclosure` values. | `sessions.get_config()` | -| `PUT /v2/sessions/{id}/config` | Updates supplied session settings. See "Caller ID" and "Call disclosures". | `sessions.update_config()` | +| `GET /v2/sessions/{id}/config` | Returns session config with the effective `ai_disclosure` value. | `sessions.get_config()` | +| `PUT /v2/sessions/{id}/config` | Updates supplied session settings. See "Caller ID" and "AI disclosure". | `sessions.update_config()` | | `POST /v2/sessions/{id}/messages` | Sends a message. Body: `{"content": "...", "client_now_date": "..."}`; `client_now_date` is optional, see "The user's time". | `sessions.send_message()` | | `GET /v2/sessions/{id}/messages` | Reads the stored messages, newest first. | `sessions.history()` | | `POST /v2/sessions/{id}/start` | Starts a prepared or paused task, or continues a stopped session. See "Stop and continue". | `sessions.start_task()` | @@ -211,29 +211,29 @@ caller ID. `caller_id` is a session setting that selects it: means the change was not saved; if unsure, GET the settings or resend the same PUT. -### Call disclosures +### AI disclosure -The config API accepts these additional fields: +The config API also accepts `ai_disclosure`, which controls whether the +assistant says it is an AI on a call: -| Field | Values | Default | -|---|---|---| -| `ai_disclosure` | `"proactive"` (introduce as AI), `"on_request"` (disclose when asked), `"disabled"` | `"proactive"` for managed users | -| `recording_disclosure` | `"proactive"` (announce that the call is recorded), `"disabled"` | `"proactive"` for managed users | +| Value | Meaning | +|---|---| +| `"proactive"` | Introduce itself as AI. | +| `"on_request"` | Disclose that identity when asked. | +| `"disabled"` | Do not disclose it. | For example, `PUT /v2/sessions/{id}/config` with -`{"ai_disclosure": "on_request", "recording_disclosure": "disabled"}` changes both. -Omitted fields stay unchanged; `null` is invalid. Recording disclosure controls -the spoken notice, not whether the call is recorded. Changes affect subsequent -calls; calls already placed keep their settings. The same 503 and 500 behavior -described above applies. - -`GET` returns the effective disclosure values, including defaults. Pine test -accounts default to `"disabled"` for both. The server decides which modes a user -may set: managed users cannot set `ai_disclosure="disabled"`, and the request -returns 400 `invalid_request`. - -These fields require a server with session disclosure support. An older server -may silently accept them for test accounts without applying them. +`{"ai_disclosure": "on_request"}` changes it. Omitted fields stay unchanged; +`null` is invalid. Changes affect subsequent calls; calls already placed keep +their settings. The same 503 and 500 behavior described above applies. + +`GET` returns the effective value, including the default. Managed users default +to `"proactive"`; Pine test accounts default to `"disabled"`. The server decides +which modes a user may set: managed users cannot set `ai_disclosure="disabled"`, +and the request returns 400 `invalid_request`. + +This field requires a server with session disclosure support. An older server +may silently accept it for test accounts without applying it. ### The user's time diff --git a/docs/sdk-api.md b/docs/sdk-api.md index c231ce6..4e4c5fb 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -122,7 +122,7 @@ user = await partner_client.platform.managed_users.update( | `sessions.list(...)` | `SessionListResponse` | | `sessions.get(session_id)` | `SessionInfo` | | `sessions.get_config(session_id)` | `SessionConfig` | -| `sessions.update_config(session_id, *, caller_id=None, ai_disclosure=None, recording_disclosure=None)` | `SessionConfig` after the change | +| `sessions.update_config(session_id, *, caller_id=None, ai_disclosure=None)` | `SessionConfig` after the change | | `sessions.send_message(session_id, content, ..., client_now_date=None)` | `SessionMessageStatus` | | `sessions.history(session_id, *, limit=30, before_message_id=None)` | `SessionHistoryPage`: one page of stored messages, newest first | | `sessions.start_task(session_id)` | `dict` | @@ -175,46 +175,43 @@ await client.sessions.update_config(session["id"], caller_id="platform") await client.sessions.send_message(session["id"], "Call the clinic to book a visit") ``` -### Call disclosures +### AI disclosure -Two settings control what the assistant says on a call: +`ai_disclosure` controls whether the assistant says it is an AI on a call: -| Setting | Values | +| Value | Meaning | |---|---| -| `ai_disclosure` | `"proactive"` (introduce itself as AI), `"on_request"` (disclose that identity when asked), `"disabled"` | -| `recording_disclosure` | `"proactive"` (announce that the call is recorded), `"disabled"` | +| `"proactive"` | Introduce itself as AI. | +| `"on_request"` | Disclose that identity when asked. | +| `"disabled"` | Do not disclose it. | -Managed-user sessions default to `"proactive"` for both. Pine test accounts -default to `"disabled"` for both. The server decides which modes a user may -set: it rejects `ai_disclosure="disabled"` for managed users with 400 -`invalid_request`. +Managed-user sessions default to `"proactive"`. Pine test accounts default to +`"disabled"`. The server decides which modes a user may set: it rejects +`ai_disclosure="disabled"` for managed users with 400 `invalid_request`. -These settings require a server with session disclosure support. An older -server may silently accept them for test accounts without applying them. +This setting requires a server with session disclosure support. An older +server may silently accept it for test accounts without applying it. ```python session = await client.sessions.create() config = await client.sessions.update_config( - session["id"], ai_disclosure="on_request", recording_disclosure="disabled", + session["id"], ai_disclosure="on_request", ) await client.sessions.send_message(session["id"], "Call the clinic to book a visit") ``` -Both `AsyncPineAI` and `PineAI` support these settings. `update_config()` +Both `AsyncPineAI` and `PineAI` support this setting. `update_config()` changes only the settings given; `None` leaves a setting unchanged and is not sent. A call with no setting to change, a non-string or an unknown mode raises -`ValueError` before any request is sent. Setting -`recording_disclosure="disabled"` turns off the spoken recording notice, not -recording. +`ValueError` before any request is sent. Changes affect subsequent calls; calls already placed keep their settings. The same 503 and 500 behavior described above applies. -`sessions.get_config()` returns the effective disclosure values from the server. -Both disclosure fields are `None` when an older server omits them. They are -read as plain strings, so a mode added later by the server still parses. The -SDK does not choose product defaults locally. `AIDisclosure` and -`RecordingDisclosure`, exported from `pine_assistant`, type the modes accepted -by `update_config()`. +`sessions.get_config()` returns the effective `ai_disclosure` from the server. +It is `None` when an older server omits it. It is read as a plain string, so a +mode added later by the server still parses. The SDK does not choose product +defaults locally. `AIDisclosure`, exported from `pine_assistant`, types the +modes accepted by `update_config()`. ### The user's time diff --git a/src/pine_assistant/__init__.py b/src/pine_assistant/__init__.py index 1295469..accee25 100644 --- a/src/pine_assistant/__init__.py +++ b/src/pine_assistant/__init__.py @@ -24,7 +24,6 @@ from pine_assistant.models.session import ( AIDisclosure, CallerID, - RecordingDisclosure, SessionConfig, SessionHistoryMessage, SessionHistoryPage, @@ -78,7 +77,6 @@ "SessionConfig", "CallerID", "AIDisclosure", - "RecordingDisclosure", "SessionHistoryMessage", "SessionHistoryPage", "SessionListResponse", diff --git a/src/pine_assistant/models/session.py b/src/pine_assistant/models/session.py index 60c32a3..b46f6c5 100644 --- a/src/pine_assistant/models/session.py +++ b/src/pine_assistant/models/session.py @@ -8,7 +8,6 @@ CallerID = Literal["user", "platform"] AIDisclosure = Literal["disabled", "on_request", "proactive"] -RecordingDisclosure = Literal["disabled", "proactive"] class SessionInfo(BaseModel): @@ -42,10 +41,9 @@ class SessionConfig(BaseModel): model_config = ConfigDict(extra="allow") caller_id: str | None = None - # None means a server predating disclosure settings. Both are plain strings, - # not the update Literals, on purpose: a mode added by the server still parses. + # None means a server predating disclosure settings. A plain string, not the + # update Literal, on purpose: a mode added by the server still parses. ai_disclosure: str | None = None - recording_disclosure: str | None = None class SessionListResponse(BaseModel): diff --git a/src/pine_assistant/sessions.py b/src/pine_assistant/sessions.py index 74f4c0b..dd0fa57 100644 --- a/src/pine_assistant/sessions.py +++ b/src/pine_assistant/sessions.py @@ -14,7 +14,6 @@ from pine_assistant.models.session import ( AIDisclosure, CallerID, - RecordingDisclosure, SessionConfig, SessionHistoryPage, SessionInfo, @@ -62,24 +61,12 @@ def _ai_disclosure(ai_disclosure: AIDisclosure) -> AIDisclosure: return ai_disclosure -def _recording_disclosure(recording_disclosure: RecordingDisclosure) -> RecordingDisclosure: - if recording_disclosure not in get_args(RecordingDisclosure): - raise ValueError('recording_disclosure must be "disabled" or "proactive"') - return recording_disclosure - - -def _config_update( - caller_id: CallerID | None, - ai_disclosure: AIDisclosure | None, - recording_disclosure: RecordingDisclosure | None, -) -> dict[str, Any]: +def _config_update(caller_id: CallerID | None, ai_disclosure: AIDisclosure | None) -> dict[str, Any]: body: dict[str, Any] = {} if caller_id is not None: body["caller_id"] = _caller_id(caller_id) if ai_disclosure is not None: body["ai_disclosure"] = _ai_disclosure(ai_disclosure) - if recording_disclosure is not None: - body["recording_disclosure"] = _recording_disclosure(recording_disclosure) if not body: raise ValueError("provide at least one session config setting") return body @@ -218,7 +205,6 @@ async def update_config( *, caller_id: CallerID | None = None, ai_disclosure: AIDisclosure | None = None, - recording_disclosure: RecordingDisclosure | None = None, ) -> SessionConfig: """Update settings for the next calls the agent places in this session. @@ -235,15 +221,13 @@ async def update_config( phone, else a number of the platform's pool; ``"platform"`` presents a number of the platform's pool. - ai_disclosure and recording_disclosure control what the assistant says - on the call. Managed users default to ``"proactive"`` for both and the - server rejects ai_disclosure="disabled" for them with 400 - ``invalid_request``; the server decides which modes a user may set. - ai_disclosure="on_request" discloses AI identity only when asked. - recording_disclosure="disabled" turns off the spoken notice, not - recording. + ai_disclosure controls whether the assistant says it is an AI on the + call. Managed users default to ``"proactive"`` and the server rejects + ai_disclosure="disabled" for them with 400 ``invalid_request``; the + server decides which modes a user may set. ai_disclosure="on_request" + discloses AI identity only when asked. """ - body = _config_update(caller_id, ai_disclosure, recording_disclosure) + body = _config_update(caller_id, ai_disclosure) try: return _parse_session_config(await self._http.put(_config_path(session_id), body)) except PineAIError as exc: @@ -420,10 +404,9 @@ def update_config( *, caller_id: CallerID | None = None, ai_disclosure: AIDisclosure | None = None, - recording_disclosure: RecordingDisclosure | None = None, ) -> SessionConfig: """Update next-call settings; see :meth:`SessionsAPI.update_config` for semantics.""" - body = _config_update(caller_id, ai_disclosure, recording_disclosure) + body = _config_update(caller_id, ai_disclosure) try: return _parse_session_config(self._http.put(_config_path(session_id), body)) except PineAIError as exc: diff --git a/tests/test_profile_and_session_config.py b/tests/test_profile_and_session_config.py index cdfa1a8..d1d4bbf 100644 --- a/tests/test_profile_and_session_config.py +++ b/tests/test_profile_and_session_config.py @@ -372,13 +372,12 @@ def test_socketio_message_carries_client_now_date_only_when_given(): @pytest.mark.parametrize("settings", [ {"ai_disclosure": "proactive"}, {"ai_disclosure": "on_request"}, - {"recording_disclosure": "disabled"}, - {"recording_disclosure": "proactive"}, - {"caller_id": "platform", "ai_disclosure": "on_request", "recording_disclosure": "disabled"}, - {"caller_id": None, "ai_disclosure": "on_request", "recording_disclosure": None}, + {"caller_id": "platform", "ai_disclosure": "on_request"}, + {"caller_id": None, "ai_disclosure": "on_request"}, ]) async def test_disclosure_update_sends_only_provided_fields(sync, settings): - # The server always answers with both effective disclosure values. + # The server answers with every effective disclosure value, including ones + # the SDK does not expose. effective = {"caller_id": "platform", "ai_disclosure": "proactive", "recording_disclosure": "proactive"} recorder = Recorder(httpx.Response(200, json=success(effective))) if sync: @@ -400,14 +399,11 @@ async def test_disclosure_update_sends_only_provided_fields(sync, settings): @pytest.mark.parametrize("sync", [False, True]) @pytest.mark.parametrize("settings", [ {}, - {"caller_id": None, "ai_disclosure": None, "recording_disclosure": None}, + {"caller_id": None, "ai_disclosure": None}, {"ai_disclosure": "off"}, {"ai_disclosure": "PROACTIVE"}, {"ai_disclosure": True}, - {"recording_disclosure": "on_request"}, - {"recording_disclosure": False}, - {"recording_disclosure": True}, - {"recording_disclosure": 0}, + {"ai_disclosure": 0}, ]) async def test_invalid_disclosure_update_never_sends_request(sync, settings): recorder = Recorder() @@ -444,10 +440,13 @@ async def test_server_rejection_of_disclosure_mode_surfaces_as_session_error(syn @pytest.mark.parametrize("sync", [False, True]) @pytest.mark.parametrize("payload", [ + {"ai_disclosure": "proactive"}, + {"ai_disclosure": "on_request"}, + {"ai_disclosure": "disabled"}, + {"ai_disclosure": "a_future_mode"}, + # The server also returns settings the SDK does not expose; they still parse. {"ai_disclosure": "proactive", "recording_disclosure": "proactive"}, - {"ai_disclosure": "on_request", "recording_disclosure": "disabled"}, {"ai_disclosure": "disabled", "recording_disclosure": "disabled"}, - {"ai_disclosure": "a_future_mode", "recording_disclosure": "a_future_mode"}, {}, ]) async def test_read_disclosure_config_and_older_servers(sync, payload): @@ -461,13 +460,12 @@ async def test_read_disclosure_config_and_older_servers(sync, payload): async with async_client(recorder, user_id=PINE_USER_ID) as client: config = await client.sessions.get_config(7) assert config.ai_disclosure == payload.get("ai_disclosure") - assert config.recording_disclosure == payload.get("recording_disclosure") + assert "recording_disclosure" not in SessionConfig.model_fields -@pytest.mark.parametrize("field", ["ai_disclosure", "recording_disclosure"]) @pytest.mark.parametrize("value", [True, 0, 1]) -async def test_malformed_disclosure_response_is_not_coerced(field, value): - recorder = Recorder(httpx.Response(200, json=success({field: value}))) +async def test_malformed_disclosure_response_is_not_coerced(value): + recorder = Recorder(httpx.Response(200, json=success({"ai_disclosure": value}))) async with async_client(recorder, user_id=PINE_USER_ID) as client: with pytest.raises(SessionError, match="invalid session config response"): await client.sessions.get_config(7) From 3b445b5e01c02b80b5854bf35e3660c773b585fc Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Fri, 13 Nov 2026 09:46:51 +0000 Subject: [PATCH 09/10] refactor(sessions): drop recording_disclosure from session config responses The server still returns recording_disclosure, and SessionConfig allows extra fields, so it surfaced as an untyped attribute and in model_dump(). Drop the key before validation so the SDK never exposes it; other extra fields are unchanged. Also rewrap a paragraph in docs/sdk-api.md. Co-Authored-By: Claude Opus 5.5 --- docs/sdk-api.md | 6 +++--- src/pine_assistant/models/session.py | 11 ++++++++++- tests/test_profile_and_session_config.py | 24 ++++++++++++++++++++---- 3 files changed, 33 insertions(+), 8 deletions(-) diff --git a/docs/sdk-api.md b/docs/sdk-api.md index 4e4c5fb..6fa2f4d 100644 --- a/docs/sdk-api.md +++ b/docs/sdk-api.md @@ -203,9 +203,9 @@ await client.sessions.send_message(session["id"], "Call the clinic to book a vis Both `AsyncPineAI` and `PineAI` support this setting. `update_config()` changes only the settings given; `None` leaves a setting unchanged and is not sent. A call with no setting to change, a non-string or an unknown mode raises -`ValueError` before any request is sent. -Changes affect subsequent calls; calls already placed keep their settings. -The same 503 and 500 behavior described above applies. +`ValueError` before any request is sent. Changes affect subsequent calls; calls +already placed keep their settings. The same 503 and 500 behavior described +above applies. `sessions.get_config()` returns the effective `ai_disclosure` from the server. It is `None` when an older server omits it. It is read as a plain string, so a diff --git a/src/pine_assistant/models/session.py b/src/pine_assistant/models/session.py index b46f6c5..34d7339 100644 --- a/src/pine_assistant/models/session.py +++ b/src/pine_assistant/models/session.py @@ -4,7 +4,7 @@ from typing import Any, Literal -from pydantic import BaseModel, ConfigDict, field_validator +from pydantic import BaseModel, ConfigDict, field_validator, model_validator CallerID = Literal["user", "platform"] AIDisclosure = Literal["disabled", "on_request", "proactive"] @@ -45,6 +45,15 @@ class SessionConfig(BaseModel): # update Literal, on purpose: a mode added by the server still parses. ai_disclosure: str | None = None + @model_validator(mode="before") + @classmethod + def omit_recording_disclosure(cls, data: Any) -> Any: + # The server returns recording_disclosure; the SDK deliberately does not + # expose it, not even as an extra field. + if isinstance(data, dict) and "recording_disclosure" in data: + data = {key: value for key, value in data.items() if key != "recording_disclosure"} + return data + class SessionListResponse(BaseModel): sessions: list[SessionInfo] diff --git a/tests/test_profile_and_session_config.py b/tests/test_profile_and_session_config.py index d1d4bbf..600db8e 100644 --- a/tests/test_profile_and_session_config.py +++ b/tests/test_profile_and_session_config.py @@ -444,9 +444,6 @@ async def test_server_rejection_of_disclosure_mode_surfaces_as_session_error(syn {"ai_disclosure": "on_request"}, {"ai_disclosure": "disabled"}, {"ai_disclosure": "a_future_mode"}, - # The server also returns settings the SDK does not expose; they still parse. - {"ai_disclosure": "proactive", "recording_disclosure": "proactive"}, - {"ai_disclosure": "disabled", "recording_disclosure": "disabled"}, {}, ]) async def test_read_disclosure_config_and_older_servers(sync, payload): @@ -460,7 +457,26 @@ async def test_read_disclosure_config_and_older_servers(sync, payload): async with async_client(recorder, user_id=PINE_USER_ID) as client: config = await client.sessions.get_config(7) assert config.ai_disclosure == payload.get("ai_disclosure") - assert "recording_disclosure" not in SessionConfig.model_fields + + +@pytest.mark.parametrize("sync", [False, True]) +@pytest.mark.parametrize("method", ["get_config", "update_config"]) +async def test_recording_disclosure_from_server_is_omitted(sync, method): + payload = {"caller_id": "user", "ai_disclosure": "proactive", "recording_disclosure": "proactive", "other": 1} + recorder = Recorder(httpx.Response(200, json=success(payload))) + kwargs = {"ai_disclosure": "proactive"} if method == "update_config" else {} + if sync: + with PineAI( + api_key=API_KEY, user_id=PINE_USER_ID, base_url=BASE_URL, http_transport=httpx.MockTransport(recorder), + ) as client: + config = getattr(client.sessions, method)(7, **kwargs) + else: + async with async_client(recorder, user_id=PINE_USER_ID) as client: + config = await getattr(client.sessions, method)(7, **kwargs) + + assert config.ai_disclosure == "proactive" + assert not hasattr(config, "recording_disclosure") + assert config.model_dump() == {"caller_id": "user", "ai_disclosure": "proactive", "other": 1} @pytest.mark.parametrize("value", [True, 0, 1]) From 0858d7eb477151aebcc04b96c635038ee7b15637 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Fri, 13 Nov 2026 10:50:25 +0000 Subject: [PATCH 10/10] refactor(sessions): leave the server's other disclosure settings unmodeled Drop the response filter and its test so the SDK carries no code for settings it does not offer; SessionConfig keeps main's handling of extra fields. Co-Authored-By: Claude Opus 5.5 --- src/pine_assistant/models/session.py | 11 +---------- tests/test_profile_and_session_config.py | 24 +----------------------- 2 files changed, 2 insertions(+), 33 deletions(-) diff --git a/src/pine_assistant/models/session.py b/src/pine_assistant/models/session.py index 34d7339..b46f6c5 100644 --- a/src/pine_assistant/models/session.py +++ b/src/pine_assistant/models/session.py @@ -4,7 +4,7 @@ from typing import Any, Literal -from pydantic import BaseModel, ConfigDict, field_validator, model_validator +from pydantic import BaseModel, ConfigDict, field_validator CallerID = Literal["user", "platform"] AIDisclosure = Literal["disabled", "on_request", "proactive"] @@ -45,15 +45,6 @@ class SessionConfig(BaseModel): # update Literal, on purpose: a mode added by the server still parses. ai_disclosure: str | None = None - @model_validator(mode="before") - @classmethod - def omit_recording_disclosure(cls, data: Any) -> Any: - # The server returns recording_disclosure; the SDK deliberately does not - # expose it, not even as an extra field. - if isinstance(data, dict) and "recording_disclosure" in data: - data = {key: value for key, value in data.items() if key != "recording_disclosure"} - return data - class SessionListResponse(BaseModel): sessions: list[SessionInfo] diff --git a/tests/test_profile_and_session_config.py b/tests/test_profile_and_session_config.py index 600db8e..91967f7 100644 --- a/tests/test_profile_and_session_config.py +++ b/tests/test_profile_and_session_config.py @@ -376,9 +376,7 @@ def test_socketio_message_carries_client_now_date_only_when_given(): {"caller_id": None, "ai_disclosure": "on_request"}, ]) async def test_disclosure_update_sends_only_provided_fields(sync, settings): - # The server answers with every effective disclosure value, including ones - # the SDK does not expose. - effective = {"caller_id": "platform", "ai_disclosure": "proactive", "recording_disclosure": "proactive"} + effective = {"caller_id": "platform", "ai_disclosure": "proactive"} recorder = Recorder(httpx.Response(200, json=success(effective))) if sync: with PineAI( @@ -459,26 +457,6 @@ async def test_read_disclosure_config_and_older_servers(sync, payload): assert config.ai_disclosure == payload.get("ai_disclosure") -@pytest.mark.parametrize("sync", [False, True]) -@pytest.mark.parametrize("method", ["get_config", "update_config"]) -async def test_recording_disclosure_from_server_is_omitted(sync, method): - payload = {"caller_id": "user", "ai_disclosure": "proactive", "recording_disclosure": "proactive", "other": 1} - recorder = Recorder(httpx.Response(200, json=success(payload))) - kwargs = {"ai_disclosure": "proactive"} if method == "update_config" else {} - if sync: - with PineAI( - api_key=API_KEY, user_id=PINE_USER_ID, base_url=BASE_URL, http_transport=httpx.MockTransport(recorder), - ) as client: - config = getattr(client.sessions, method)(7, **kwargs) - else: - async with async_client(recorder, user_id=PINE_USER_ID) as client: - config = await getattr(client.sessions, method)(7, **kwargs) - - assert config.ai_disclosure == "proactive" - assert not hasattr(config, "recording_disclosure") - assert config.model_dump() == {"caller_id": "user", "ai_disclosure": "proactive", "other": 1} - - @pytest.mark.parametrize("value", [True, 0, 1]) async def test_malformed_disclosure_response_is_not_coerced(value): recorder = Recorder(httpx.Response(200, json=success({"ai_disclosure": value})))