askai-python 0.5.0__tar.gz → 0.6.0__tar.gz

{askai_python-0.5.0 → askai_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: askai-python
-Version: 0.5.0
+Version: 0.6.0
 Summary: AI Made Stupid Simple. Unified API for OpenAI, Groq, Google, Anthropic, and more.
 Author-email: Hossein Ghorbani <hosseingh1068@gmail.com>
 License: MIT
@@ -13,7 +13,6 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -21,15 +20,15 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == "openai"
 Provides-Extra: anthropic
-Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
+Requires-Dist: anthropic>=1.0.0; extra == "anthropic"
 Provides-Extra: google
-Requires-Dist: google-generativeai>=0.5.0; extra == "google"
+Requires-Dist: google-genai>=1.0.0; extra == "google"
 Provides-Extra: groq
 Requires-Dist: groq>=0.4.0; extra == "groq"
 Provides-Extra: media
@@ -41,8 +40,8 @@ Requires-Dist: pydantic>=1.10; extra == "structured"
 Requires-Dist: jsonschema>=4.0; extra == "structured"
 Provides-Extra: all
 Requires-Dist: openai>=1.0.0; extra == "all"
-Requires-Dist: anthropic>=0.20.0; extra == "all"
-Requires-Dist: google-generativeai>=0.5.0; extra == "all"
+Requires-Dist: anthropic>=1.0.0; extra == "all"
+Requires-Dist: google-genai>=1.0.0; extra == "all"
 Requires-Dist: groq>=0.4.0; extra == "all"
 Requires-Dist: Pillow>=9.0.0; extra == "all"
 Requires-Dist: httpx>=0.24.0; extra == "all"
@@ -64,9 +63,16 @@ No frameworks. No servers. No overengineering.
 ## ⚡ Quick Start (5 seconds)
 
 ```bash
-pip install askai-python
+pip install "askai-python[openai,groq]"
 ```
 
+Provider SDKs are optional. Install the extras you need:
+
+- `pip install "askai-python[openai]"` for OpenAI, Azure, and OpenRouter.
+- `pip install "askai-python[anthropic]"`, `pip install "askai-python[google]"`,
+  or `pip install "askai-python[groq]"` for those providers.
+- `pip install "askai-python[all]"` for every provider SDK.
+
 ```python
 from ask_ai import OpenAI, Groq
 
@@ -202,20 +208,33 @@ print(user.name)  # "Alice"
 |----------|-------|-------------|
 | **OpenAI** | `OpenAI` | Text, Images (DALL-E), Vision |
 | **Anthropic** | `Anthropic` | Text, Vision (Claude 3.5) |
-| **Google** | `Google` | Text, Images, Video, Audio |
+| **Google** | `Google` | Text, Vision |
 | **Groq** | `Groq` | Ultra-fast Llama 3 & Mixtral |
 | **Azure** | `Azure` | Enterprise-grade OpenAI |
 | **OpenRouter**| `OpenRouter`| 100+ community models |
 
 ---
 
+## Conversation Sessions
+
+Sessions provide optional in-memory conversation history:
+
+```python
+session = OpenAI().session(max_messages=20)
+session.ask("My name is Ada.")
+print(session.ask("What is my name?").text)
+```
+
+Session state is not persisted, and session requests do not support
+`response_model` validation yet.
+
 ## 🗺️ Roadmap
 
 ### 🚀 Roadmap 2.0 (Active)
 - [x] Provider Fallback chaining & Pydantic Structured Output support
+- [x] Optional in-memory conversation sessions
 - [ ] Multi-Modal Vision input (image to text) for all key providers
 - [ ] Native support for tools/function calling execution
-- [ ] Memory buffer / session-based conversation management
 
 ### 🏁 Roadmap 1.0 (Completed)
 - ~~[x] Baseline multiple providers~~

{askai_python-0.5.0 → askai_python-0.6.0}/README.md

@@ -25,7 +25,7 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/askai-python.svg)](https://pypi.org/project/askai-python/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 
 
 
@@ -34,9 +34,18 @@
 ## ⚡ Quick Start (5 seconds)
 
 ```bash
-pip install askai-python
+pip install "askai-python[openai,groq]"
 ```
 
+Provider SDKs are optional dependencies. Install the extras you need:
+
+- `pip install "askai-python[openai]"` for OpenAI, Azure, and OpenRouter.
+- `pip install "askai-python[anthropic]"`, `pip install "askai-python[google]"`,
+  or `pip install "askai-python[groq]"` for those providers.
+- `pip install "askai-python[all]"` for every provider SDK.
+
+Python 3.10 or newer is required.
+
 ```python
 from ask_ai import OpenAI, Groq
 
@@ -112,6 +121,12 @@ ai = OpenAI()
 response = ai.ask("Write a script", retry=3, timeout=10)
 ```
 
+Requests default to `retry=2` (up to three attempts) for retryable timeout,
+connection, rate-limit (`429`), and server (`5xx`) errors. Authentication and
+invalid-request errors are not retried; use `retry=0` to disable retries.
+Streaming retries occur only before the first chunk/event, so already-emitted
+output is never duplicated.
+
 ### System Configuration 
 Set system prompts and temperature directly:
 
@@ -124,6 +139,11 @@ ai.advanced(
 print(ai.ask("How do I optimize a Dockerfile?").text)
 ```
 
+Unknown option names produce a `UserWarning` with a spelling suggestion. Pass
+`strict_options=True` to a provider (or to an individual request) to raise a
+`ValueError` instead. `safe_mode` currently has no defined behavior and is
+deprecated; passing it emits a `DeprecationWarning`.
+
 ---
 
 ### 🚀 Async Support (FastAPI / Aiogram)
@@ -245,6 +265,24 @@ print(response.raw)
 print(response.parsed.name)
 ```
 
+For supported schemas, `response_model` also requests native JSON Schema output
+from OpenAI/Azure, Anthropic, Groq, Google, and OpenRouter. When an adapter
+receives a clear unsupported-schema response (HTTP 400/422), it retries once
+without the native schema and keeps local validation enabled. Authentication,
+rate-limit, and server errors are propagated, not retried as prompt-only
+fallbacks. Schemas that cannot be represented in the provider's strict schema
+format use prompt instructions and local validation directly. Provider/model
+support varies; these request parameters have mock-based tests but have not
+been verified against live APIs.
+
+Provider parameters follow their documented APIs:
+[OpenAI Chat Completions](https://developers.openai.com/api/docs/guides/structured-outputs),
+[Azure OpenAI](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/structured-outputs),
+[Anthropic](https://platform.claude.com/docs/en/build-with-claude/structured-outputs),
+[Groq](https://console.groq.com/docs/structured-outputs),
+[Google GenAI](https://ai.google.dev/gemini-api/docs/structured-output), and
+[OpenRouter Chat Completions](https://openrouter.ai/docs/guides/features/structured-outputs).
+
 ### Streaming Events
 
 Use typed events for text, completion, and errors while keeping the legacy
@@ -260,12 +298,21 @@ for event in OpenAI().ask_stream_events("Tell me a story"):
         print("\nDone")
 ```
 
+`UsageUpdate` events are emitted when an adapter receives usage in its stream.
+`ToolCall` is a reserved event type and is not emitted by the current adapters.
+Streaming usage extraction is mock-tested and has not been verified against
+live provider APIs.
+
 ### 📊 Observability
 
-Attach optional middleware to receive provider, model, latency, and retry
-metadata. Provider usage extraction and failure-reason reporting are not
-supported yet. Estimated cost is only calculated when a response already
-contains usage data; the bundled provider adapters do not currently supply it:
+Attach optional middleware to receive provider, model, latency, retry, and
+provider-reported token usage. Usage field names are normalized to
+`input_tokens`, `output_tokens`, and `total_tokens`. Estimated cost is only
+calculated when usage is available and pricing for the model is supplied;
+missing usage never produces a cost estimate. Mock tests cover usage extraction
+for supported adapters; live provider APIs have not been verified. On failures,
+middleware emits a `failed` event with `failure_reason`, then the exception is
+propagated:
 
 ```python
 from ask_ai import Observability, OpenAI
@@ -273,6 +320,7 @@ from ask_ai import Observability, OpenAI
 ai = OpenAI().use(Observability(on_event=print))
 response = ai.ask("Explain tracing")
 print(response.metadata.latency_ms)
+print(response.metadata.usage)
 ```
 
 ### Provider Capabilities
@@ -287,6 +335,9 @@ if capabilities.structured_output:
     print("Structured output is available")
 ```
 
+Capabilities are advisory provider-level metadata, not guarantees for every
+model.
+
 ### Smart Router
 
 Route requests across providers using deterministic `cheapest`, `fastest`, or

{askai_python-0.5.0 → askai_python-0.6.0}/ask_ai/__init__.py

@@ -2,7 +2,7 @@
 ask-ai: A minimal Python SDK to switch between LLM providers in one line.
 """
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 from .base import Response
 from .capabilities import Capabilities
@@ -17,6 +17,7 @@ from .exceptions import (
     MediaSecurityError,
     MediaTypeNotSupportedError,
     ProviderAuthError,
+    ProviderConnectionError,
     ProviderError,
     ProviderInvalidRequestError,
     ProviderRateLimitError,
@@ -54,6 +55,7 @@ __all__ = [
     "AskAIParsingError",
     "ProviderError",
     "ProviderAuthError",
+    "ProviderConnectionError",
     "ProviderRateLimitError",
     "ProviderTimeoutError",
     "ProviderInvalidRequestError",

{askai_python-0.5.0 → askai_python-0.6.0}/ask_ai/base.py

@@ -7,13 +7,14 @@ from collections.abc import AsyncIterator, Iterator
 from typing import Any, Optional, Union
 
 from .capabilities import Capabilities
-from .config import AdvancedConfig
+from .config import CONFIG_OPTION_NAMES, AdvancedConfig, validate_option_names
 from .events import Completed, Error, TextDelta, ToolCall, UsageUpdate
 from .exceptions import StructuredValidationError
 from .media import AudioObject, ImageObject
 from .observability import Observability, ResponseMetadata, Usage
 
 logger = logging.getLogger("ask_ai")
+DEFAULT_RETRY_COUNT = 2
 
 
 class Response:
@@ -26,12 +27,14 @@ class Response:
         media: Union[ImageObject, AudioObject, None] = None,
         response_model: Any = None,
         metadata: Any = None,
+        usage: Optional[Usage] = None,
         **kwargs,
     ):
         self._raw_text = text
         self.media = media
         self.response_model = response_model
         self.metadata = metadata
+        self.usage = usage
         self._kwargs = kwargs
 
     @property
@@ -110,7 +113,18 @@ class BaseProvider:
     Abstract base class for all AI providers.
     Implements the core 'ask' logic and configuration management.
     """
-    def __init__(self, api_key: str = None, model: str = None, persona: str = None, **kwargs):
+    option_names = frozenset()
+
+    def __init__(
+        self,
+        api_key: str = None,
+        model: str = None,
+        persona: str = None,
+        strict_options: bool = False,
+        **kwargs,
+    ):
+        self.strict_options = strict_options
+        self._validate_option_names(kwargs, CONFIG_OPTION_NAMES | self.option_names, strict_options)
         # Zero-Config: Try env var if key not provided
         self.api_key = api_key or os.environ.get(self._get_api_key_env_var())
         self.model = model or self._get_default_model()
@@ -118,14 +132,33 @@ class BaseProvider:
         self.config = AdvancedConfig(**kwargs)
         self._middleware: list[Observability] = []
 
+    @staticmethod
+    def _validate_option_names(options, allowed, strict=False):
+        validate_option_names(options, allowed, strict)
+
     def use(self, middleware: Observability) -> "BaseProvider":
         """Attach optional observability middleware and return this provider."""
         self._middleware.append(middleware)
         return self
 
-    def session(self, max_messages: Optional[int] = None):
+    def session(
+        self,
+        max_messages: Optional[int] = None,
+        strict_options: Optional[bool] = None,
+        **kwargs,
+    ):
+        strict = (
+            getattr(self, "strict_options", False)
+            if strict_options is None
+            else strict_options
+        )
+        validate_option_names(kwargs, {"max_messages", "strict_options"}, strict)
         from .session import ConversationSession
-        return ConversationSession(self, max_messages=max_messages)
+        return ConversationSession(
+            self,
+            max_messages=max_messages,
+            strict_options=strict,
+        )
 
     def capabilities(self) -> Capabilities:
         """Return conservative capabilities for custom providers."""
@@ -197,6 +230,13 @@ class BaseProvider:
                 response = self._execute_with_retry(
                     self._send_request, request_messages, config, output_type, retry
                 )
+                response._kwargs.update(
+                    {
+                        option: config.extra[option]
+                        for option in ("clean", "strip", "code")
+                        if option in config.extra
+                    }
+                )
                 retry_count += getattr(self, "_retry_count", 0)
                 if response_model is None:
                     return self._attach_metadata(response, started_at, retry_count)
@@ -234,6 +274,13 @@ class BaseProvider:
                 response = await self._execute_with_retry_async(
                     self._send_request_async, request_messages, config, output_type, retry
                 )
+                response._kwargs.update(
+                    {
+                        option: config.extra[option]
+                        for option in ("clean", "strip", "code")
+                        if option in config.extra
+                    }
+                )
                 retry_count += getattr(self, "_retry_count", 0)
                 if response_model is None:
                     return self._attach_metadata(response, started_at, retry_count)
@@ -265,6 +312,8 @@ class BaseProvider:
         Update global advanced settings for this instance.
         Merges new settings with existing ones.
         """
+        strict = kwargs.pop("strict_options", self.strict_options)
+        self._validate_option_names(kwargs, CONFIG_OPTION_NAMES | self.option_names, strict)
         new_conf = AdvancedConfig(**kwargs)
         for k, v in new_conf.__dict__.items():
             if k in ('extra', '_safe_mode_provided'):
@@ -308,7 +357,9 @@ class BaseProvider:
         final_config = self._build_final_config(kwargs)
         messages = self._prepare_messages(query, final_config)
         output_type = kwargs.get('output_type')
-        retry = int(kwargs.get('retry', final_config.extra.get('retry', 0)) or 0)
+        retry = int(
+            kwargs.get("retry", final_config.extra.get("retry", DEFAULT_RETRY_COUNT)) or 0
+        )
         response_model = kwargs.get('response_model')
         validation_retries = int(kwargs.get("validation_retries", 0) or 0)
 
@@ -352,7 +403,14 @@ class BaseProvider:
 
         final_config = self._build_final_config(kwargs)
         messages = self._prepare_messages(query, final_config)
-        yield from self._send_request_stream(messages, final_config)
+        retry = int(
+            kwargs.get("retry", final_config.extra.get("retry", DEFAULT_RETRY_COUNT))
+            or 0
+        )
+        yield from self._iter_with_retry(
+            lambda: self._send_request_stream(messages, final_config),
+            retry,
+        )
 
     def ask_stream_events(self, query: str, **kwargs) -> Iterator[Any]:
         """Yield typed events while preserving the legacy text stream API."""
@@ -360,18 +418,44 @@ class BaseProvider:
         if fallback_providers:
             if not isinstance(fallback_providers, (list, tuple)):
                 fallback_providers = [fallback_providers]
+            last_error = None
             for provider in fallback_providers:
-                provider_instance = provider() if isinstance(provider, type) else provider
-                yield from provider_instance.ask_stream_events(query, **kwargs)
-                return
+                emitted = False
+                try:
+                    provider_instance = provider() if isinstance(provider, type) else provider
+                    for event in provider_instance.ask_stream_events(query, **kwargs):
+                        if isinstance(event, Error):
+                            if not emitted and event.emitted_chunks == 0:
+                                last_error = event
+                                break
+                            yield event
+                            return
+                        emitted = True
+                        yield event
+                    else:
+                        return
+                except Exception as error:
+                    if emitted:
+                        raise
+                    last_error = Error(error=error, emitted_chunks=0)
+            if last_error is not None:
+                yield last_error
+            return
 
         emitted_chunks = 0
         text_parts = []
         usage = None
         final_config = self._build_final_config(kwargs)
         messages = self._prepare_messages(query, final_config)
+        retry = int(
+            kwargs.get("retry", final_config.extra.get("retry", DEFAULT_RETRY_COUNT))
+            or 0
+        )
         try:
-            for event in self._send_request_stream_events(messages, final_config):
+            for event in self._iter_with_retry(
+                lambda: self._send_request_stream_events(messages, final_config),
+                retry,
+            ):
                 if isinstance(event, TextDelta):
                     emitted_chunks += 1
                     text_parts.append(event.text)
@@ -419,7 +503,9 @@ class BaseProvider:
         final_config = self._build_final_config(kwargs)
         messages = self._prepare_messages(query, final_config)
         output_type = kwargs.get('output_type')
-        retry = int(kwargs.get('retry', final_config.extra.get('retry', 0)) or 0)
+        retry = int(
+            kwargs.get("retry", final_config.extra.get("retry", DEFAULT_RETRY_COUNT)) or 0
+        )
         response_model = kwargs.get('response_model')
         validation_retries = int(kwargs.get("validation_retries", 0) or 0)
 
@@ -463,7 +549,14 @@ class BaseProvider:
 
         final_config = self._build_final_config(kwargs)
         messages = self._prepare_messages(query, final_config)
-        async for chunk in self._send_request_stream_async(messages, final_config):
+        retry = int(
+            kwargs.get("retry", final_config.extra.get("retry", DEFAULT_RETRY_COUNT))
+            or 0
+        )
+        async for chunk in self._aiter_with_retry(
+            lambda: self._send_request_stream_async(messages, final_config),
+            retry,
+        ):
             yield chunk
 
     async def ask_stream_events_async(self, query: str, **kwargs) -> AsyncIterator[Any]:
@@ -472,19 +565,44 @@ class BaseProvider:
         if fallback_providers:
             if not isinstance(fallback_providers, (list, tuple)):
                 fallback_providers = [fallback_providers]
+            last_error = None
             for provider in fallback_providers:
-                provider_instance = provider() if isinstance(provider, type) else provider
-                async for event in provider_instance.ask_stream_events_async(query, **kwargs):
-                    yield event
-                return
+                emitted = False
+                try:
+                    provider_instance = provider() if isinstance(provider, type) else provider
+                    async for event in provider_instance.ask_stream_events_async(query, **kwargs):
+                        if isinstance(event, Error):
+                            if not emitted and event.emitted_chunks == 0:
+                                last_error = event
+                                break
+                            yield event
+                            return
+                        emitted = True
+                        yield event
+                    else:
+                        return
+                except Exception as error:
+                    if emitted:
+                        raise
+                    last_error = Error(error=error, emitted_chunks=0)
+            if last_error is not None:
+                yield last_error
+            return
 
         emitted_chunks = 0
         text_parts = []
         usage = None
         final_config = self._build_final_config(kwargs)
         messages = self._prepare_messages(query, final_config)
+        retry = int(
+            kwargs.get("retry", final_config.extra.get("retry", DEFAULT_RETRY_COUNT))
+            or 0
+        )
         try:
-            async for event in self._send_request_stream_events_async(messages, final_config):
+            async for event in self._aiter_with_retry(
+                lambda: self._send_request_stream_events_async(messages, final_config),
+                retry,
+            ):
                 if isinstance(event, TextDelta):
                     emitted_chunks += 1
                     text_parts.append(event.text)
@@ -504,11 +622,20 @@ class BaseProvider:
 
     def _build_final_config(self, kwargs: dict[str, Any]) -> AdvancedConfig:
         """Build final config by merging global config with per-request kwargs."""
-        request_config = AdvancedConfig(**kwargs)
+        options = dict(kwargs)
+        strict = options.pop("strict_options", getattr(self, "strict_options", False))
+        validate_option_names(
+            options,
+            CONFIG_OPTION_NAMES
+            | self.option_names
+            | {"strict_options", "providers", "fallback"},
+            strict,
+        )
+        request_config = AdvancedConfig(**options)
         final_config = self.config.merge(request_config)
 
         # Ensure timeout has a default
-        timeout = kwargs.get('timeout', final_config.extra.get('timeout', 30))
+        timeout = options.get('timeout', final_config.extra.get('timeout', 30))
         final_config.extra['timeout'] = float(timeout) if timeout is not None else 30.0
 
         return final_config
@@ -521,14 +648,10 @@ class BaseProvider:
 
         # Smart capability: if json=True or response_model is specified
         response_model = config.extra.get('response_model')
-        if response_model:
-            if hasattr(response_model, "model_json_schema"):
-                schema = response_model.model_json_schema()
-            elif hasattr(response_model, "schema"):
-                schema = response_model.schema()
-            else:
-                schema = None
+        if response_model is not None:
+            from .structured import json_schema_for_model
 
+            schema = json_schema_for_model(response_model)
             if schema:
                 import json
                 schema_str = json.dumps(schema)
@@ -555,6 +678,58 @@ class BaseProvider:
 
     # ─── Retry Logic ────────────────────────────────────────
 
+    def _iter_with_retry(self, iterator_factory, retry: int):
+        attempts = 0
+        self._retry_count = 0
+        while True:
+            emitted = False
+            try:
+                for item in iterator_factory():
+                    emitted = True
+                    yield item
+                self._retry_count = attempts
+                return
+            except Exception as error:
+                if emitted or attempts >= retry or not self._is_retryable_error(error):
+                    raise
+                attempts += 1
+                self._retry_count = attempts
+                delay = min(2 ** attempts + random.uniform(0, 1), 30)
+                logger.warning(
+                    "Transient streaming error (%s). Retrying in %.1fs... (%d/%d)",
+                    error.__class__.__name__,
+                    delay,
+                    attempts,
+                    retry,
+                )
+                time.sleep(delay)
+
+    async def _aiter_with_retry(self, iterator_factory, retry: int):
+        attempts = 0
+        self._retry_count = 0
+        while True:
+            emitted = False
+            try:
+                async for item in iterator_factory():
+                    emitted = True
+                    yield item
+                self._retry_count = attempts
+                return
+            except Exception as error:
+                if emitted or attempts >= retry or not self._is_retryable_error(error):
+                    raise
+                attempts += 1
+                self._retry_count = attempts
+                delay = min(2 ** attempts + random.uniform(0, 1), 30)
+                logger.warning(
+                    "Transient async streaming error (%s). Retrying in %.1fs... (%d/%d)",
+                    error.__class__.__name__,
+                    delay,
+                    attempts,
+                    retry,
+                )
+                await asyncio.sleep(delay)
+
     def _execute_with_retry(self, func, messages, config, output_type, retry):
         """Execute a sync function with exponential backoff + jitter."""
         attempts = 0

{askai_python-0.5.0 → askai_python-0.6.0}/ask_ai/config.py

@@ -1,7 +1,49 @@
-from typing import Any, Optional
+import difflib
+import warnings
+from typing import Any, Iterable, Optional
 
 _NOT_PROVIDED = object()
 
+CONFIG_OPTION_NAMES = frozenset(
+    {
+        "temperature",
+        "max_tokens",
+        "top_p",
+        "frequency_penalty",
+        "presence_penalty",
+        "stop",
+        "system_message",
+        "prompt",
+        "system",
+        "safe_mode",
+        "timeout",
+        "retry",
+        "response_model",
+        "validation_retries",
+        "output_type",
+        "clean",
+        "strip",
+        "code",
+        "json",
+    }
+)
+
+
+def validate_option_names(
+    options: Iterable[str],
+    allowed: Iterable[str],
+    strict: bool = False,
+) -> None:
+    allowed_set = set(allowed)
+    allowed_names = sorted(allowed_set)
+    for name in sorted(set(options) - allowed_set):
+        suggestions = difflib.get_close_matches(name, allowed_names, n=1, cutoff=0.6)
+        suggestion = f" Did you mean '{suggestions[0]}'?" if suggestions else ""
+        message = f"Unknown option '{name}'.{suggestion}"
+        if strict:
+            raise ValueError(message)
+        warnings.warn(message, UserWarning, stacklevel=3)
+
 
 class AdvancedConfig:
     """
@@ -37,6 +79,12 @@ class AdvancedConfig:
             kwargs.pop("system", None)
 
         self.system_message = system_message
+        if safe_mode is not _NOT_PROVIDED:
+            warnings.warn(
+                "safe_mode is deprecated and has no defined behavior; it will be removed in a future release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         self.safe_mode = False if safe_mode is _NOT_PROVIDED else safe_mode
         self._safe_mode_provided = safe_mode is not _NOT_PROVIDED
         self.extra: dict[str, Any] = kwargs