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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: askai-python
-Version: 0.4.1
+Version: 0.5.0
 Summary: AI Made Stupid Simple. Unified API for OpenAI, Groq, Google, Anthropic, and more.
 Author-email: Hossein Ghorbani <hosseingh1068@gmail.com>
 License: MIT
@@ -36,6 +36,9 @@ 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"
@@ -43,6 +46,8 @@ Requires-Dist: google-generativeai>=0.5.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 🚀

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

@@ -22,6 +22,7 @@
   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/)
@@ -159,7 +160,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 +222,135 @@ 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)
+```
+
+### 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")
+```
+
+### 📊 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:
+
+```python
+from ask_ai import Observability, OpenAI
+
+ai = OpenAI().use(Observability(on_event=print))
+response = ai.ask("Explain tracing")
+print(response.metadata.latency_ms)
+```
+
+### 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")
+```
+
+### 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.5.0/ask_ai/__init__.py

@@ -0,0 +1,79 @@
+"""
+ask-ai: A minimal Python SDK to switch between LLM providers in one line.
+"""
+
+__version__ = "0.5.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,
+    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",
+    "ProviderRateLimitError",
+    "ProviderTimeoutError",
+    "ProviderInvalidRequestError",
+    "ProviderUnavailableError",
+    "MediaTypeNotSupportedError",
+    "MediaSecurityError",
+    "StreamNotSupportedError",
+    "StructuredValidationError",
+    "parse_structured",
+    "TextDelta",
+    "ToolCall",
+    "UsageUpdate",
+    "Completed",
+    "Error",
+    "Observability",
+    "ResponseMetadata",
+    "Usage",
+    "Capabilities",
+    "Router",
+    "ConversationSession",
+    "MediaPolicy",
+    "download_media",
+]