ai_api_unified 2.5.3__tar.gz → 2.7.0__tar.gz

{ai_api_unified-2.5.3 → ai_api_unified-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ai_api_unified
-Version: 2.5.3
+Version: 2.7.0
 Summary: Unified access layer for AI completions (LLM), embedding (semantic), image, video, and voice services
 License: MIT
 Keywords: llm,openai,bedrock,gemini,vertex,embeddings,completion,video,voice,api
@@ -33,7 +33,7 @@ Requires-Dist: boto3 (>=1.34.0,<2.0.0) ; extra == "bedrock"
 Requires-Dist: elevenlabs (>=2.3.0,<3.0.0) ; extra == "elevenlabs"
 Requires-Dist: google-cloud-speech (>=2.25.0,<3.0.0) ; extra == "google-gemini"
 Requires-Dist: google-cloud-texttospeech (>=2.29.0) ; extra == "google-gemini"
-Requires-Dist: google-genai (>=1.41.0,<2.0.0) ; extra == "google-gemini"
+Requires-Dist: google-genai (>=2.10.0,<3.0.0) ; extra == "google-gemini"
 Requires-Dist: googleapis-common-protos (>=1.63.0,<2.0.0) ; extra == "google-gemini"
 Requires-Dist: httpx (>=0.27.0,<1.0.0)
 Requires-Dist: imageio (>=2.37.0,<3.0.0) ; extra == "video-frames"
@@ -60,7 +60,7 @@ Requires-Dist: usaddress (>=0.5.16,<0.6.0) ; extra == "middleware-pii-redaction-
 Requires-Dist: usaddress (>=0.5.16,<0.6.0) ; extra == "middleware-pii-redaction-small"
 Description-Content-Type: text/markdown
 
-# ai-api-unified 2.5.0
+# ai-api-unified 2.7.0
 
 `ai-api-unified` is a unified Python library for AI completions, embeddings, image generation, video generation, and voice. Application code targets stable base interfaces and factory entry points while concrete providers are selected at runtime from environment configuration.
 
@@ -109,7 +109,7 @@ The public entry points are the stable base interfaces and factories:
 Default model guidance in the checked-in OSS env files:
 
 - Google completions: `gemini-2.5-flash`
-- Google embeddings: `gemini-embedding-001`
+- Google embeddings: `gemini-embedding-001` (text-only) or `gemini-embedding-2` (multimodal)
 - Google images: `imagen-4.0-generate-001`
 - Google videos: `veo-3.1-lite-generate-preview`
 - Google voice: `gemini-2.5-pro-tts`
@@ -218,6 +218,27 @@ response: str = client.send_prompt("Say hello in one short sentence.")
 print(response)
 ```
 
+### Streaming Completions
+
+Every completions client exposes a `capabilities` descriptor with a
+`supports_streaming` flag set per model. Models without streaming support raise
+`AiProviderCapabilityUnsupportedError` from `send_prompt_streaming`. OpenAI,
+Google Gemini, and Bedrock chat models all stream:
+
+```python
+from ai_api_unified import AIFactory
+
+client = AIFactory.get_ai_completions_client()
+
+if client.capabilities.supports_streaming:
+    for chunk in client.send_prompt_streaming("Tell me a short story."):
+        print(chunk, end="", flush=True)
+```
+
+Streaming is unavailable while the PII redaction middleware is enabled
+(`AiProviderConfigurationError`): redaction cannot be guaranteed across chunk
+boundaries, so use `send_prompt` in PII-redacting deployments.
+
 ### Embeddings
 
 ```python
@@ -229,6 +250,40 @@ embedding = result.get("embedding")
 print(len(embedding) if embedding else None)
 ```
 
+### Multimodal Embeddings
+
+Every embeddings client exposes a `capabilities` descriptor stating which input
+types the configured model supports. Text-only models raise
+`AiProviderCapabilityUnsupportedError` from `generate_embeddings_multimodal`.
+Google `gemini-embedding-2` embeds interleaved text, images, video, audio, and
+PDFs into one vector space (set `EMBEDDING_MODEL_NAME=gemini-embedding-2`):
+
+```python
+from ai_api_unified import (
+    AIEmbeddingsMultimodalParams,
+    AIFactory,
+    SupportedDataType,
+)
+
+client = AIFactory.get_ai_embedding_client()  # EMBEDDING_MODEL_NAME=gemini-embedding-2
+
+if SupportedDataType.IMAGE in client.capabilities.supported_data_types:
+    with open("bicycle.png", "rb") as file_image:
+        params = AIEmbeddingsMultimodalParams(
+            text="a red bicycle",
+            included_types=[SupportedDataType.IMAGE],
+            included_data=[file_image.read()],
+            included_mime_types=["image/png"],
+        )
+    result = client.generate_embeddings_multimodal(params)
+    print(result["dimensions"])
+```
+
+Media attachments are capped at 20MB per attachment and per request. They also
+require API-key auth (`GOOGLE_AUTH_METHOD=api_key`): the google-genai SDK sends
+only text parts to the Vertex embedding endpoint, so in service-account mode
+the client rejects media attachments up front.
+
 ### Image Generation
 
 ```python
@@ -378,7 +433,7 @@ There is no implicit default provider. Set the selector for each capability you
 | Environment variable        | Notes                                                                                       |
 | --------------------------- | ------------------------------------------------------------------------------------------- |
 | `COMPLETIONS_MODEL_NAME`    | Optional completions model override                                                         |
-| `EMBEDDING_MODEL_NAME`      | Optional embeddings model override                                                          |
+| `EMBEDDING_MODEL_NAME`      | Optional embeddings model override. `gemini-embedding-2` enables multimodal embeddings.     |
 | `IMAGE_MODEL_NAME`          | Optional image model override                                                               |
 | `VIDEO_MODEL_NAME`          | Optional video model override                                                               |
 | `VIDEO_OUTPUT_DIR`          | Optional local output directory for materialized video artifacts                            |
@@ -449,6 +504,32 @@ Optional service-account mode:
 
 This auth policy applies across Google completions, embeddings, images, videos, and voice.
 
+##### Google auth modes per capability
+
+The two `GOOGLE_AUTH_METHOD` values select different google-genai clients:
+`api_key` creates the Gemini Developer client
+(`genai.Client(api_key=...)`, generativelanguage endpoint) and
+`service_account` creates the Vertex client
+(`genai.Client(vertexai=True, project=..., location=...)`). Some capabilities
+work in only one client:
+
+| Google capability | `api_key` (Developer) | `service_account` (Vertex) | Notes |
+| --- | :---: | :---: | --- |
+| Completions (incl. streaming) | ✅ | ✅ | |
+| Text embeddings | ✅ | ✅ | |
+| Image generation (Imagen) | ✅ | ✅ | |
+| Multimodal (media) embeddings | ✅ | ❌ | the SDK sends only text parts to the Vertex embedding endpoint, so the library raises `NotImplementedError` when media is attached in Vertex mode |
+| Text-to-video with local download | ✅ | ❌ | downloaded via the Files API (`client.files.download`), which the SDK supports only in the Developer client; under Vertex set `download_outputs=False` to receive a remote `gs://` URI instead |
+| `source_video` (video continuation) | ❌ | ✅ | the library raises `NotImplementedError` in `api_key` mode; this path requires Vertex |
+| Voice (Gemini TTS / STT) | ⚠️ | ✅ | the library wires API keys into the Cloud TTS/STT clients, but Google may reject API keys that are not enabled for those APIs; `service_account` is the reliable mode |
+
+Pick the mode for what you need: multimodal-media embeddings and
+text-to-video-with-download require `api_key`, and `source_video` requires
+`service_account`. Running both families means switching `GOOGLE_AUTH_METHOD`
+between runs or constructing two clients. For a single call, `get_client(...,
+use_api_key=True)` on the shared Google base forces the Developer client
+without changing the environment.
+
 #### Azure TTS
 
 Required:
@@ -480,6 +561,11 @@ from ai_api_unified import (
     AIBaseImages,
     AIBaseVideos,
     AIVoiceBase,
+    AIEmbeddingsCapabilitiesBase,
+    AIEmbeddingsMultimodalParams,
+    AIIncludedMediaParamsBase,
+    AiProviderCapabilityUnsupportedError,
+    SupportedDataType,
 )
 ```
 
@@ -504,6 +590,7 @@ Typical factory failure modes:
 - unsupported engine selector: `ValueError`
 - selected provider extra is not installed: `AiProviderDependencyUnavailableError`
 - provider load/runtime failure: `AiProviderRuntimeError`
+- input modality unsupported by the configured embedding model: `AiProviderCapabilityUnsupportedError`
 
 ## Middleware
 
@@ -641,8 +728,10 @@ Before publishing:
 
 1. Bump the version in `pyproject.toml`.
 2. Bump the version in `src/ai_api_unified/__version__.py`.
-3. Ensure the working tree is clean.
-4. Ensure your PyPI token is configured for Poetry.
+3. Bump the version in the `README.md` title heading (line 1).
+4. Run `poetry run pytest tests/test_version_sync.py` to confirm all three agree.
+5. Ensure the working tree is clean.
+6. Ensure your PyPI token is configured for Poetry.
 
 Publish with the checked-in script:
 

{ai_api_unified-2.5.3 → ai_api_unified-2.7.0}/README.md

@@ -1,4 +1,4 @@
-# ai-api-unified 2.5.0
+# ai-api-unified 2.7.0
 
 `ai-api-unified` is a unified Python library for AI completions, embeddings, image generation, video generation, and voice. Application code targets stable base interfaces and factory entry points while concrete providers are selected at runtime from environment configuration.
 
@@ -47,7 +47,7 @@ The public entry points are the stable base interfaces and factories:
 Default model guidance in the checked-in OSS env files:
 
 - Google completions: `gemini-2.5-flash`
-- Google embeddings: `gemini-embedding-001`
+- Google embeddings: `gemini-embedding-001` (text-only) or `gemini-embedding-2` (multimodal)
 - Google images: `imagen-4.0-generate-001`
 - Google videos: `veo-3.1-lite-generate-preview`
 - Google voice: `gemini-2.5-pro-tts`
@@ -156,6 +156,27 @@ response: str = client.send_prompt("Say hello in one short sentence.")
 print(response)
 ```
 
+### Streaming Completions
+
+Every completions client exposes a `capabilities` descriptor with a
+`supports_streaming` flag set per model. Models without streaming support raise
+`AiProviderCapabilityUnsupportedError` from `send_prompt_streaming`. OpenAI,
+Google Gemini, and Bedrock chat models all stream:
+
+```python
+from ai_api_unified import AIFactory
+
+client = AIFactory.get_ai_completions_client()
+
+if client.capabilities.supports_streaming:
+    for chunk in client.send_prompt_streaming("Tell me a short story."):
+        print(chunk, end="", flush=True)
+```
+
+Streaming is unavailable while the PII redaction middleware is enabled
+(`AiProviderConfigurationError`): redaction cannot be guaranteed across chunk
+boundaries, so use `send_prompt` in PII-redacting deployments.
+
 ### Embeddings
 
 ```python
@@ -167,6 +188,40 @@ embedding = result.get("embedding")
 print(len(embedding) if embedding else None)
 ```
 
+### Multimodal Embeddings
+
+Every embeddings client exposes a `capabilities` descriptor stating which input
+types the configured model supports. Text-only models raise
+`AiProviderCapabilityUnsupportedError` from `generate_embeddings_multimodal`.
+Google `gemini-embedding-2` embeds interleaved text, images, video, audio, and
+PDFs into one vector space (set `EMBEDDING_MODEL_NAME=gemini-embedding-2`):
+
+```python
+from ai_api_unified import (
+    AIEmbeddingsMultimodalParams,
+    AIFactory,
+    SupportedDataType,
+)
+
+client = AIFactory.get_ai_embedding_client()  # EMBEDDING_MODEL_NAME=gemini-embedding-2
+
+if SupportedDataType.IMAGE in client.capabilities.supported_data_types:
+    with open("bicycle.png", "rb") as file_image:
+        params = AIEmbeddingsMultimodalParams(
+            text="a red bicycle",
+            included_types=[SupportedDataType.IMAGE],
+            included_data=[file_image.read()],
+            included_mime_types=["image/png"],
+        )
+    result = client.generate_embeddings_multimodal(params)
+    print(result["dimensions"])
+```
+
+Media attachments are capped at 20MB per attachment and per request. They also
+require API-key auth (`GOOGLE_AUTH_METHOD=api_key`): the google-genai SDK sends
+only text parts to the Vertex embedding endpoint, so in service-account mode
+the client rejects media attachments up front.
+
 ### Image Generation
 
 ```python
@@ -316,7 +371,7 @@ There is no implicit default provider. Set the selector for each capability you
 | Environment variable        | Notes                                                                                       |
 | --------------------------- | ------------------------------------------------------------------------------------------- |
 | `COMPLETIONS_MODEL_NAME`    | Optional completions model override                                                         |
-| `EMBEDDING_MODEL_NAME`      | Optional embeddings model override                                                          |
+| `EMBEDDING_MODEL_NAME`      | Optional embeddings model override. `gemini-embedding-2` enables multimodal embeddings.     |
 | `IMAGE_MODEL_NAME`          | Optional image model override                                                               |
 | `VIDEO_MODEL_NAME`          | Optional video model override                                                               |
 | `VIDEO_OUTPUT_DIR`          | Optional local output directory for materialized video artifacts                            |
@@ -387,6 +442,32 @@ Optional service-account mode:
 
 This auth policy applies across Google completions, embeddings, images, videos, and voice.
 
+##### Google auth modes per capability
+
+The two `GOOGLE_AUTH_METHOD` values select different google-genai clients:
+`api_key` creates the Gemini Developer client
+(`genai.Client(api_key=...)`, generativelanguage endpoint) and
+`service_account` creates the Vertex client
+(`genai.Client(vertexai=True, project=..., location=...)`). Some capabilities
+work in only one client:
+
+| Google capability | `api_key` (Developer) | `service_account` (Vertex) | Notes |
+| --- | :---: | :---: | --- |
+| Completions (incl. streaming) | ✅ | ✅ | |
+| Text embeddings | ✅ | ✅ | |
+| Image generation (Imagen) | ✅ | ✅ | |
+| Multimodal (media) embeddings | ✅ | ❌ | the SDK sends only text parts to the Vertex embedding endpoint, so the library raises `NotImplementedError` when media is attached in Vertex mode |
+| Text-to-video with local download | ✅ | ❌ | downloaded via the Files API (`client.files.download`), which the SDK supports only in the Developer client; under Vertex set `download_outputs=False` to receive a remote `gs://` URI instead |
+| `source_video` (video continuation) | ❌ | ✅ | the library raises `NotImplementedError` in `api_key` mode; this path requires Vertex |
+| Voice (Gemini TTS / STT) | ⚠️ | ✅ | the library wires API keys into the Cloud TTS/STT clients, but Google may reject API keys that are not enabled for those APIs; `service_account` is the reliable mode |
+
+Pick the mode for what you need: multimodal-media embeddings and
+text-to-video-with-download require `api_key`, and `source_video` requires
+`service_account`. Running both families means switching `GOOGLE_AUTH_METHOD`
+between runs or constructing two clients. For a single call, `get_client(...,
+use_api_key=True)` on the shared Google base forces the Developer client
+without changing the environment.
+
 #### Azure TTS
 
 Required:
@@ -418,6 +499,11 @@ from ai_api_unified import (
     AIBaseImages,
     AIBaseVideos,
     AIVoiceBase,
+    AIEmbeddingsCapabilitiesBase,
+    AIEmbeddingsMultimodalParams,
+    AIIncludedMediaParamsBase,
+    AiProviderCapabilityUnsupportedError,
+    SupportedDataType,
 )
 ```
 
@@ -442,6 +528,7 @@ Typical factory failure modes:
 - unsupported engine selector: `ValueError`
 - selected provider extra is not installed: `AiProviderDependencyUnavailableError`
 - provider load/runtime failure: `AiProviderRuntimeError`
+- input modality unsupported by the configured embedding model: `AiProviderCapabilityUnsupportedError`
 
 ## Middleware
 
@@ -579,8 +666,10 @@ Before publishing:
 
 1. Bump the version in `pyproject.toml`.
 2. Bump the version in `src/ai_api_unified/__version__.py`.
-3. Ensure the working tree is clean.
-4. Ensure your PyPI token is configured for Poetry.
+3. Bump the version in the `README.md` title heading (line 1).
+4. Run `poetry run pytest tests/test_version_sync.py` to confirm all three agree.
+5. Ensure the working tree is clean.
+6. Ensure your PyPI token is configured for Poetry.
 
 Publish with the checked-in script:
 

{ai_api_unified-2.5.3 → ai_api_unified-2.7.0}/pyproject.toml

@@ -36,7 +36,7 @@
 [project]
 name = "ai_api_unified"
 
-version = "2.5.3" # keep in sync with src/ai_api_unified/__version__.py
+version = "2.7.0" # keep in sync with src/ai_api_unified/__version__.py and the README.md title
 description = "Unified access layer for AI completions (LLM), embedding (semantic), image, video, and voice services"
 authors = [{ name = "Dave Thomas", email = "davidcthomas@gmail.com" }]
 license = "MIT"
@@ -87,7 +87,7 @@ google_gemini = [
   "google-cloud-speech>=2.25.0,<3.0.0",
   "protobuf>=3.20.2,<5.0.0dev",
   "googleapis-common-protos>=1.63.0,<2.0.0",
-  "google-genai (>=1.41.0,<2.0.0)",
+  "google-genai (>=2.10.0,<3.0.0)",
   "google-cloud-texttospeech (>=2.29.0)",
 ]
 middleware-pii-redaction = [

{ai_api_unified-2.5.3 → ai_api_unified-2.7.0}/src/ai_api_unified/__init__.py

@@ -27,6 +27,9 @@ from .ai_base import (
     AIBaseVideos,
     AICompletionsCapabilitiesBase,
     AICompletionsPromptParamsBase,
+    AIEmbeddingsCapabilitiesBase,
+    AIEmbeddingsMultimodalParams,
+    AIIncludedMediaParamsBase,
     AIMediaReference,
     AIVideoArtifact,
     AIVideoGenerationJob,
@@ -36,6 +39,7 @@ from .ai_base import (
     SupportedDataType,
 )
 from .ai_completions_exceptions import StructuredResponseTokenLimitError
+from .ai_provider_exceptions import AiProviderCapabilityUnsupportedError
 from .ai_factory import AIFactory
 from .voice.ai_voice_base import AIVoiceBase, AIVoiceCapabilities, AIVoiceSelectionBase
 from .voice.ai_voice_factory import AIVoiceFactory
@@ -59,6 +63,10 @@ __all__: list[str] = [
     "AIStructuredPrompt",
     "AICompletionsCapabilitiesBase",
     "AICompletionsPromptParamsBase",
+    "AIEmbeddingsCapabilitiesBase",
+    "AIEmbeddingsMultimodalParams",
+    "AIIncludedMediaParamsBase",
+    "AiProviderCapabilityUnsupportedError",
     "StructuredResponseTokenLimitError",
     "SupportedDataType",
     "AIVoiceSelectionBase",

{ai_api_unified-2.5.3 → ai_api_unified-2.7.0}/src/ai_api_unified/__version__.py

@@ -9,4 +9,4 @@ from __future__ import annotations
 
 __all__: list[str] = ["__version__"]
 
-__version__: str = "2.5.3"
+__version__: str = "2.7.0"