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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: askai-python
-Version: 0.4.0
+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 🚀
@@ -143,6 +148,54 @@ response = ai.ask(
 )
 ```
 
+## 🎨 Media Generation (Image & Audio)
+
+Generate images or speech with compatible providers:
+
+```python
+from ask_ai import OpenAI
+
+ai = OpenAI()
+
+# Generate an Image (DALL-E)
+img_response = ai.ask("A majestic lion in a neon city", output_type="image")
+img_response.save("lion.png")
+
+# Generate Speech (TTS)
+audio_response = ai.ask("Hello, this is a voice.", output_type="audio")
+audio_response.save("welcome.mp3")
+```
+
+## 🔗 Provider Fallback
+
+Never experience downtime by supplying fallback providers:
+
+```python
+from ask_ai import OpenAI, Groq
+
+ai = OpenAI()
+response = ai.ask("Explain quantum physics", providers=[ai, Groq])
+print(response.text)
+```
+
+## 📋 Structured Output (Pydantic Support)
+
+Force LLMs to strictly respond matching a Pydantic schema:
+
+```python
+from pydantic import BaseModel
+from ask_ai import OpenAI
+
+class User(BaseModel):
+    name: str
+    age: int
+
+ai = OpenAI()
+response = ai.ask("Extract name: Alice is 30.", response_model=User)
+user = response.pydantic
+print(user.name)  # "Alice"
+```
+
 ## 🔌 Supported Providers
 
 | Provider | Class | Capabilities |
@@ -158,11 +211,19 @@ response = ai.ask(
 
 ## 🗺️ Roadmap
 
-- [x] Baseline multiple providers
-- [x] Automated Retry & Timeout controls
-- [ ] Async API (`await ask_async`)
-- [ ] Provider Fallback (`fallback=[Groq()]`)
-- [ ] Structured Outputs (Pydantic Support)
+### 🚀 Roadmap 2.0 (Active)
+- [x] Provider Fallback chaining & Pydantic Structured Output support
+- [ ] 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~~
+- ~~[x] Automated Retry & Timeout controls~~
+- ~~[x] Async API (`await ask_async`)~~
+- ~~[x] Streaming Support (`ask_stream` / `ask_stream_async`)~~
+- ~~[x] Provider Fallback (`fallback=[Groq()]`)~~
+- ~~[x] Structured Outputs (Pydantic Support)~~
 
 ---
 

askai_python-0.5.0/README.md

@@ -0,0 +1,371 @@
+# ask-ai
+
+<p align="center">
+  🌍 <b>Readme:</b>
+  <a href="README.md"><img src="https://flagcdn.com/20x15/us.png" alt="English"> English</a> · 
+  <a href="docs/README_fa.md"><img src="https://flagcdn.com/20x15/ir.png" alt="Persian"> فارسی</a> · 
+  <a href="docs/README_zh.md"><img src="https://flagcdn.com/20x15/cn.png" alt="Chinese"> 中文</a> · 
+  <a href="docs/README_tr.md"><img src="https://flagcdn.com/20x15/tr.png" alt="Turkish"> Türkçe</a> · 
+  <a href="docs/README_ar.md"><img src="https://flagcdn.com/20x15/sa.png" alt="Arabic"> العربية</a> · 
+  <a href="docs/README_ru.md"><img src="https://flagcdn.com/20x15/ru.png" alt="Russian"> Русский</a> · 
+  <a href="docs/README_es.md"><img src="https://flagcdn.com/20x15/es.png" alt="Spanish"> Español</a> · 
+  <a href="docs/README_ja.md"><img src="https://flagcdn.com/20x15/jp.png" alt="Japanese"> 日本語</a>
+</p>
+
+
+<p align="center">
+  <img src="assets/banner.svg" alt="ask-ai animated banner" width="100%">
+</p>
+
+<p align="center">
+  <b>A minimal Python SDK to switch between LLM providers in one line.</b><br/>
+  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/)
+
+
+
+---
+
+## ⚡ Quick Start (5 seconds)
+
+```bash
+pip install askai-python
+```
+
+```python
+from ask_ai import OpenAI, Groq
+
+# Auto-detects OPENAI_API_KEY from environment
+OpenAI().ask("Explain black holes like I'm 5").text
+
+# Switch provider effortlessly
+Groq().ask("Explain black holes like I'm 5").text
+```
+
+---
+
+## 🧐 Why ask-ai?
+
+- **One function**: Just call `.ask()`
+- **Multiple providers**: OpenAI, Anthropic, Google Gemini, Groq, Azure, OpenRouter
+- **Zero config**: Keys are pulled from the environment automatically
+- **SDK-first, not a framework**: It stays out of your way.
+
+## 🚫 What this project is NOT
+
+> ❌ Not an AI framework  
+> ❌ Not an API gateway  
+> ❌ Not an agent memory system  
+
+It does one thing perfectly: **Simplifying the API call to LLMs.**
+
+---
+
+## 🛠️ Advanced Usage
+
+### 🧰 Developer QoL Utilities (Auto-Parsing)
+
+<p align="center">
+  <img src="assets/features.svg" alt="ask-ai features parsing banner" width="100%">
+</p>
+Stop writing Regex to clean up model outputs! `ask-ai` comes with built-in text processing flags:
+
+```python
+from ask_ai import OpenAI
+ai = OpenAI()
+
+# 1. Clean Markdown (Removes ```json and ``` tags)
+# Perfect for extracting raw data from models that wrap everything in markdown
+clean_text = ai.ask("Write JSON", clean=True).text
+
+# 2. Extract Code (Returns ONLY the code block, ignores conversational filler)
+# Great for automation pipelines
+code = ai.ask("Write a python ping script", code=True).text
+
+# 3. Strip Tags (Removes <think> blocks and HTML)
+# Essential for reasoning models like DeepSeek-R1
+answer_only = ai.ask("What is 1+1?", strip=True).text
+
+# 4. Enforce & Parse JSON (Directly returns a Parsed Python Dictionary)
+# Adds JSON instructions to the prompt and safely runs json.loads()
+data_dict = ai.ask("Extract user info", json=True).json
+print(data_dict['name'])
+```
+
+### 🔄 Built-in Retries & Timeout (Resiliency)
+
+<p align="center">
+  <img src="assets/resiliency.svg" alt="ask-ai resiliency banner" width="100%">
+</p>
+Handle rate limits (`429`) and network drops automatically:
+
+```python
+from ask_ai import OpenAI
+ai = OpenAI()
+
+# Will retry up to 3 times on RateLimit/Network errors, with generic timeout
+response = ai.ask("Write a script", retry=3, timeout=10)
+```
+
+### System Configuration 
+Set system prompts and temperature directly:
+
+```python
+ai.advanced(
+    temperature=0.7,
+    prompt="You are a senior DevOps engineer."
+)
+
+print(ai.ask("How do I optimize a Dockerfile?").text)
+```
+
+---
+
+### 🚀 Async Support (FastAPI / Aiogram)
+
+`ask-ai` works perfectly in asynchronous environments:
+
+```python
+import asyncio
+from ask_ai import OpenAI
+
+async def main():
+    ai = OpenAI()
+    # Runs non-blocking in your event loop
+    response = await ai.ask_async("What is the capital of France?")
+    print(response.text)
+
+asyncio.run(main())
+```
+
+---
+
+### 🌊 Streaming Support (Sync & Async)
+
+Stream responses token-by-token easily:
+
+```python
+from ask_ai import OpenAI
+
+ai = OpenAI()
+
+# Sync Streaming
+for chunk in ai.ask_stream("Write a short story about a blue dragon"):
+    print(chunk, end="", flush=True)
+
+# Async Streaming
+async def stream_example():
+    async for chunk in ai.ask_stream_async("Write a short story"):
+        print(chunk, end="", flush=True)
+```
+
+---
+
+### 🎨 Media Generation (Image & Audio)
+
+Generate images or speech with compatible providers:
+
+```python
+from ask_ai import OpenAI
+
+ai = OpenAI()
+
+# Generate an Image (DALL-E)
+img_response = ai.ask("A majestic lion in a neon city", output_type="image")
+img_response.save("lion.png")
+
+# Generate Speech (TTS)
+audio_response = ai.ask("Hello, this is a generated voice.", output_type="audio")
+audio_response.save("welcome.mp3")
+```
+
+---
+
+### 🔗 Provider Fallback
+
+Never experience downtime by supplying alternative fallback providers:
+
+```python
+from ask_ai import OpenAI, Groq
+
+ai = OpenAI()
+
+# If OpenAI fails or rate-limits, it automatically switches to Groq
+response = ai.ask("Explain quantum physics", providers=[ai, Groq])
+print(response.text)
+```
+
+---
+
+### 📋 Structured Output (Pydantic Support)
+
+Force LLMs to strictly respond matching a Pydantic schema:
+
+```python
+from pydantic import BaseModel
+from ask_ai import OpenAI
+
+class User(BaseModel):
+    name: str
+    age: int
+
+ai = OpenAI()
+response = ai.ask("Extract name: Alice is 30 years old.", response_model=User)
+
+user = response.pydantic
+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
+- [x] Multi-Modal Vision input (image to text) for all key providers
+- [ ] Native support for tools/function calling execution
+- [x] Optional in-memory session-based conversation management
+
+### 🏁 Roadmap 1.0 (Completed)
+- ~~[x] OpenAI, Groq, Gemini, Anthropic, Azure, OpenRouter support~~
+- ~~[x] Text to Image (DALL-E) and Text to Audio~~
+- ~~[x] Automated Retry & Timeout controls~~
+- ~~[x] Async Support (`await ask_async`)~~
+- ~~[x] Streaming Support (`ask_stream` / `ask_stream_async`)~~
+- ~~[x] Provider Fallback (`ask(..., providers=[OpenAI, Groq])`)~~
+- ~~[x] Structured Output (Pydantic Support)~~
+
+---
+
+## 🔗 Important Links
+
+- **PyPI**: [askai-python](https://pypi.org/project/askai-python/)
+- **GitHub Repository**: [Hosseinghorbani0/ask-ai](https://github.com/Hosseinghorbani0/ask-ai) (Star us! ⭐)
+- **Official Website**: [hosseinghorbani0.ir](https://hosseinghorbani0.ir/)
+- **Bug Tracker**: [Report an Issue](https://github.com/Hosseinghorbani0/ask-ai/issues)

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",
+]