Merge pull request #11 from ofspectrum/sync-sdk-v1.4.0

Sync SDK v1.4.0 from neo

Author: jlw463195395

.env.example

@@ -0,0 +1,13 @@
+ELEVENLABS_API_KEY=
+GEMINI_API_KEY=
+GOOGLE_CLOUD_TTS_API_KEY=
+OPENAI_API_KEY=
+AZURE_SPEECH_KEY=
+AZURE_SPEECH_REGION=
+AZURE_SPEECH_ENDPOINT=
+AZURE_OPENAI_API_KEY=
+AZURE_OPENAI_ENDPOINT=
+AZURE_OPENAI_API_VERSION=
+AZURE_OPENAI_TTS_DEPLOYMENT=
+OFSPECTRUM_API_KEY=
+OFSPECTRUM_TOKEN_ID=

AGENT_GUIDE.md

@@ -12,8 +12,8 @@ The public SDK repository is:
 https://github.com/ofspectrum/python-sdk
 ```
 
-Customer applications should normally install SDK `1.3.1` with
-`pip install "ofspectrum==1.3.1"`; they should not need the private Neo
+Customer applications should normally install SDK `1.4.0` with
+`pip install "ofspectrum==1.4.0"`; they should not need the private Neo
 monorepo source.
 
 If an agent needs SDK source orientation, use the public SDK repository above. From that repository root, inspect these files first:
@@ -237,16 +237,16 @@ Current public token types:
 
 | Type | Notebook Contract | Permanent Account Capacity | Use When |
 |------|-------------------|----------------------------|----------|
-| Standard | One public notebook; no new private notebooks (zero) | Permanent 1 GiB | The app needs neither a custom verification key nor a new private notebook. |
-| Pro | One public notebook; five private notebooks | Permanent 6 GiB | The workflow needs a configurable `public_key` or any new private notebook. |
-| Enterprise | One public notebook; ten private notebooks | Permanent 11 GiB | Admin-managed Enterprise workflows. Public SDK callers cannot create this type. |
+| Standard | One public notebook; no new private notebooks (zero) | Permanent 100 MiB | The app needs neither a custom verification key nor a new private notebook. |
+| Pro | One public notebook; five private notebooks | Permanent 100 MiB | The workflow needs a configurable `public_key` or any new private notebook. |
+| Enterprise | One public notebook; ten private notebooks | Permanent 100 MiB | Admin-managed Enterprise workflows. Public SDK callers cannot create this type. |
 
 Recommended behavior:
 
 - Create Standard tokens by default.
 - Create Pro tokens when the customer needs a configurable verification key or any new private notebook.
 - Existing tokens can be upgraded from Standard to Pro, but cannot be downgraded.
-- A Standard-to-Pro upgrade replaces that token's 1 GiB entitlement with 6 GiB; it does not produce 7 GiB.
+- A Standard-to-Pro upgrade replaces the token type; storage entitlement stays 100 MiB and does not stack.
 - Permanent capacity remains with the account after token retirement.
 - A token type upgrade may consume quota or incur a billing charge.
 - Store token IDs in the customer app database.
@@ -513,7 +513,7 @@ Additional constraints:
 - Private notebook credentials must be unique under the same token.
 - Private notebook credentials are optional at the SDK level, but apps that need credential-gated private metadata should explicitly pass `credential_val`.
 - Notebook media is limited to detected image, audio, and video content. Each notebook accepts at most 500 current files, each file may be up to 100 MiB, and notebook text is limited to 10 MiB of UTF-8 data.
-- Media consumes account capacity. Each acquired Standard, Pro, or Enterprise token contributes a permanent 1, 6, or 11 GiB entitlement respectively; available capacity may also include legacy credit and paid whole-GiB blocks.
+- Media consumes account capacity. Each acquired Standard, Pro, or Enterprise token contributes a permanent 100 MiB entitlement; available capacity may also include legacy credit and paid whole-GiB blocks.
 - Standard tokens cannot create new private notebooks. Existing Standard private notebooks are grandfathered and remain editable or deletable, but cannot be replaced after deletion.
 - Pro tokens support five private notebooks, and Enterprise tokens support ten.
 - If a token already has a public notebook, update the existing notebook instead of creating another one.
@@ -913,7 +913,7 @@ Recommended runtime flow:
 - API keys are created in the OfSpectrum dashboard, not through the SDK.
 - Token IDs, notebook IDs, media IDs, and current revisions should be stored in the customer app database.
 - Standard tokens are the safest default for new workflows.
-- Standard, Pro, and Enterprise tokens contribute permanent 1, 6, and 11 GiB account capacity respectively.
+- Standard, Pro, and Enterprise tokens each contribute a permanent 100 MiB account capacity.
 - Pro tokens are needed when the workflow requires a configurable `public_key` or up to five private notebooks; Enterprise creation is Admin-managed.
 - Account defaults and storage charge authorization are configured in the Web Console, not through an API key.
 - A staged save begins one session and reuses its `save_session_id` across all files and the commit.

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## Unreleased
+
+## 1.4.0 - 2026-10-02
+
+- Async TTS calls consume synchronous complete-audio iterators and perform
+  blocking completion work outside the caller's event loop.
+- Replacing controller-owned watermark clients preserves in-flight encode
+  snapshots and retires old clients only after their last active encode.
+  Caller-owned clients remain caller-owned; explicit close still aborts active
+  owned clients.
+- Concurrent readers of one Azure synthesis future share one watermark encode
+  and a cached terminal outcome. Separate synthesis futures remain concurrent.
+
+- Added `TTS(provider, client).synthesize(...)` and `synthesize_async(...)` as a
+  provider-neutral completed-audio interface for ElevenLabs, Gemini, Google
+  Cloud Text-to-Speech, OpenAI, Azure OpenAI-compatible deployments, and Azure
+  AI Speech. `TTSResult` returns encoded bytes plus normalized format metadata
+  and retains the native provider response. Advanced provider arguments remain
+  available through `provider_options`.
+- Added transparent ElevenLabs, Gemini, Google Cloud Text-to-Speech, OpenAI,
+  and Azure Speech wrappers; Azure OpenAI Speech uses the OpenAI wrapper.
+  Azure Speech covers completed text, SSML, and audio-config synthesis. The
+  wrappers include async Gemini/OpenAI clients and OpenAI Chat Completions
+  audio from models such as `gpt-audio-1.5`. Completed provider audio uses the
+  existing persistent stream pool by default, so repeated calls on one wrapper reuse
+  connections automatically. Raw PCM is returned in its original shape after
+  encoding, and file-only options retain the OneFile path.
+- Added a cross-provider latency benchmark mode that compares the normal file
+  encoder with a prewarmed persistent stream pool on identical TTS output.
+- Permanent token storage entitlement is 100 MiB for Standard, Pro, and Enterprise. Paid whole-GiB overage blocks are unchanged.
+
 ## 1.3.1 - 2026-08-24
 
 - `open_stream_pool(..., keepalive_interval_seconds=120)` heartbeats every pooled connection so idle Neo model sessions are not retired.