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

{askai_python-0.4.1/askai_python.egg-info → askai_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: askai-python
-Version: 0.4.1
+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,28 +20,33 @@ 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
 Requires-Dist: Pillow>=9.0.0; extra == "media"
 Provides-Extra: httpx
 Requires-Dist: httpx>=0.24.0; extra == "httpx"
+Provides-Extra: structured
+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"
+Requires-Dist: pydantic>=1.10; extra == "all"
+Requires-Dist: jsonschema>=4.0; extra == "all"
 Dynamic: license-file
 
 # askai-python 🚀
@@ -59,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
 
@@ -197,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.4.1 → askai_python-0.6.0}/README.md

@@ -22,9 +22,10 @@
   No frameworks. No servers. No overengineering.
 </p>
 
+
 [![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/)
 
 
 
@@ -33,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
 
@@ -111,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:
 
@@ -123,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)
@@ -159,7 +180,7 @@ for chunk in ai.ask_stream("Write a short story about a blue dragon"):
 
 # Async Streaming
 async def stream_example():
-    async for chunk in await ai.ask_stream_async("Write a short story"):
+    async for chunk in ai.ask_stream_async("Write a short story"):
         print(chunk, end="", flush=True)
 ```
 
@@ -221,15 +242,166 @@ print(user.name)  # "Alice"
 print(user.age)   # 30
 ```
 
+### ✅ Validated Structured Responses
+
+Structured responses support Pydantic models, dataclasses, `TypedDict`, and JSON
+Schema dictionaries. The raw provider text remains available separately:
+
+```python
+from dataclasses import dataclass
+from ask_ai import OpenAI
+
+@dataclass
+class User:
+    name: str
+    age: int
+
+response = OpenAI().ask(
+    "Extract: Alice is 30.",
+    response_model=User,
+    validation_retries=2,
+)
+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
+`ask_stream()` API unchanged:
+
+```python
+from ask_ai import Completed, OpenAI, TextDelta
+
+for event in OpenAI().ask_stream_events("Tell me a story"):
+    if isinstance(event, TextDelta):
+        print(event.text, end="")
+    elif isinstance(event, Completed):
+        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, 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
+
+ai = OpenAI().use(Observability(on_event=print))
+response = ai.ask("Explain tracing")
+print(response.metadata.latency_ms)
+print(response.metadata.usage)
+```
+
+### Provider Capabilities
+
+Inspect advisory capability metadata before selecting a provider:
+
+```python
+from ask_ai import OpenAI
+
+capabilities = OpenAI().capabilities()
+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
+`most_reliable` policies. Supply static `profiles` for meaningful ordering:
+
+```python
+from ask_ai import Groq, OpenAI, Router
+
+openai = OpenAI()  # Requires OPENAI_API_KEY
+groq = Groq()  # Requires GROQ_API_KEY
+router = Router(
+    [openai, groq],
+    policy="fastest",
+    profiles={
+        "OpenAIProvider": {"latency_ms": 100},
+        "GroqProvider": {"latency_ms": 50},
+    },
+)
+response = router.ask("Explain routing")
+```
+
+### 🔒 Secure Media Downloads
+
+Provider media downloads can be constrained by HTTPS, host, detected MIME, size,
+and timeout policy. DNS results resolving to private, loopback, link-local, or
+reserved IP addresses are rejected by default. `allowed_hosts` is optional;
+set it for an explicit hostname allowlist. Only opt in to `allow_private=True`
+when downloading from trusted private-network hosts. Redirects are rejected:
+
+```python
+from ask_ai import MediaPolicy, download_media
+
+data = download_media(
+    "https://example.com/image.png",
+    MediaPolicy(
+        max_bytes=10 * 1024 * 1024,
+        allowed_mime_types={"image/png"},
+        allowed_hosts={"example.com"},
+    ),
+)
+```
+
+### Conversation Sessions
+
+Create optional in-memory conversation state without changing the normal
+provider API:
+
+```python
+session = OpenAI().session(max_messages=20)
+session.ask("My name is Ada.")
+print(session.ask("What is my name?").text)
+```
+
+Session requests do not support `response_model` validation yet.
+
 ---
 
 ## 🗺️ Roadmap
 
 ### 🚀 Roadmap 2.0 (Active)
 - [x] Provider Fallback chaining & Pydantic Structured Output support
-- [ ] Multi-Modal Vision input (image to text) for all key providers
+- [x] Multi-Modal Vision input (image to text) for all key providers
 - [ ] Native support for tools/function calling execution
-- [ ] Memory buffer / session-based conversation management
+- [x] Optional in-memory session-based conversation management
 
 ### 🏁 Roadmap 1.0 (Completed)
 - ~~[x] OpenAI, Groq, Gemini, Anthropic, Azure, OpenRouter support~~

askai_python-0.6.0/ask_ai/__init__.py

@@ -0,0 +1,81 @@
+"""
+ask-ai: A minimal Python SDK to switch between LLM providers in one line.
+"""
+
+__version__ = "0.6.0"
+
+from .base import Response
+from .capabilities import Capabilities
+from .config import AdvancedConfig
+from .events import Completed, Error, TextDelta, ToolCall, UsageUpdate
+from .exceptions import (
+    AskAIConfigError,
+    AskAIError,
+    AskAINetworkError,
+    AskAIParsingError,
+    AskAIRateLimitError,
+    MediaSecurityError,
+    MediaTypeNotSupportedError,
+    ProviderAuthError,
+    ProviderConnectionError,
+    ProviderError,
+    ProviderInvalidRequestError,
+    ProviderRateLimitError,
+    ProviderTimeoutError,
+    ProviderUnavailableError,
+    StreamNotSupportedError,
+    StructuredValidationError,
+)
+from .media import AudioObject, ImageObject
+from .media_security import MediaPolicy, download_media
+from .observability import Observability, ResponseMetadata, Usage
+from .providers import Anthropic, Azure, Google, Groq, OpenAI, OpenRouter
+from .router import Router
+from .session import ConversationSession
+from .structured import parse_structured
+
+__all__ = [
+    # Providers
+    "OpenAI",
+    "Anthropic",
+    "Google",
+    "Groq",
+    "Azure",
+    "OpenRouter",
+    # Core
+    "AdvancedConfig",
+    "Response",
+    "ImageObject",
+    "AudioObject",
+    # Exceptions
+    "AskAIError",
+    "AskAIConfigError",
+    "AskAINetworkError",
+    "AskAIRateLimitError",
+    "AskAIParsingError",
+    "ProviderError",
+    "ProviderAuthError",
+    "ProviderConnectionError",
+    "ProviderRateLimitError",
+    "ProviderTimeoutError",
+    "ProviderInvalidRequestError",
+    "ProviderUnavailableError",
+    "MediaTypeNotSupportedError",
+    "MediaSecurityError",
+    "StreamNotSupportedError",
+    "StructuredValidationError",
+    "parse_structured",
+    "TextDelta",
+    "ToolCall",
+    "UsageUpdate",
+    "Completed",
+    "Error",
+    "Observability",
+    "ResponseMetadata",
+    "Usage",
+    "Capabilities",
+    "Router",
+    "ConversationSession",
+    "MediaPolicy",
+    "download_media",
+]