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

askai_python-0.4.1/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: askai-python
+Version: 0.4.1
+Summary: AI Made Stupid Simple. Unified API for OpenAI, Groq, Google, Anthropic, and more.
+Author-email: Hossein Ghorbani <hosseingh1068@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Hosseinghorbani0/ask-ai
+Project-URL: Documentation, https://github.com/Hosseinghorbani0/ask-ai#readme
+Project-URL: Bug Tracker, https://github.com/Hosseinghorbani0/ask-ai/issues
+Project-URL: Changelog, https://github.com/Hosseinghorbani0/ask-ai/releases
+Keywords: ai,llm,openai,anthropic,gemini,groq,sdk,api
+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
+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
+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"
+Provides-Extra: google
+Requires-Dist: google-generativeai>=0.5.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: 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: groq>=0.4.0; extra == "all"
+Requires-Dist: Pillow>=9.0.0; extra == "all"
+Requires-Dist: httpx>=0.24.0; extra == "all"
+Dynamic: license-file
+
+# askai-python 🚀
+
+**A minimal Python SDK to switch between LLM providers in one line.**  
+No frameworks. No servers. No overengineering.
+
+[![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)
+[![GitHub](https://img.shields.io/badge/GitHub-View%20Source-blue.svg)](https://github.com/Hosseinghorbani0/askai-python)
+
+---
+
+## ⚡ Quick Start (5 seconds)
+
+```bash
+pip install askai-python
+```
+
+```python
+from ask_ai import OpenAI, Groq
+
+# Auto-detects OPENAI_API_KEY from environment
+print(OpenAI().ask("Explain black holes like I'm 5").text)
+
+# Switch provider instantly
+print(Groq().ask("Explain black holes like I'm 5").text)
+```
+
+---
+
+## 🧐 Why askai-python?
+
+- **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="https://raw.githubusercontent.com/Hosseinghorbani0/askai-python/main/assets/features.svg" alt="askai-python features parsing banner" width="100%">
+</p>
+Stop writing Regex to clean up model outputs! `askai-python` 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 Resiliency (Retries & Timeouts)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Hosseinghorbani0/askai-python/main/assets/resiliency.svg" alt="askai-python resiliency banner" width="100%">
+</p>
+
+Build reliable apps without writing your own loops. `askai-python` handles rate limits (`429`) and network drops via an internal exponential backoff.
+
+```python
+from ask_ai import OpenAI
+
+ai = OpenAI()
+
+# Automatically retries up to 3 times on transient errors, with a 15-second timeout
+response = ai.ask(
+    "Write a complex python script", 
+    retry=3, 
+    timeout=15 
+)
+```
+
+## 🎨 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 |
+|----------|-------|-------------|
+| **OpenAI** | `OpenAI` | Text, Images (DALL-E), Vision |
+| **Anthropic** | `Anthropic` | Text, Vision (Claude 3.5) |
+| **Google** | `Google` | Text, Images, Video, Audio |
+| **Groq** | `Groq` | Ultra-fast Llama 3 & Mixtral |
+| **Azure** | `Azure` | Enterprise-grade OpenAI |
+| **OpenRouter**| `OpenRouter`| 100+ community models |
+
+---
+
+## 🗺️ Roadmap
+
+### 🚀 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)~~
+
+---
+
+## 🔗 Important Links
+
+- **GitHub Repository**: [Hosseinghorbani0/askai-python](https://github.com/Hosseinghorbani0/askai-python) (Star us! ⭐)
+- **Official Website**: [hosseinghorbani0.ir](https://hosseinghorbani0.ir/)
+- **Bug Tracker**: [Report an Issue](https://github.com/Hosseinghorbani0/askai-python/issues)

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

@@ -24,7 +24,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.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 
 
 
@@ -125,15 +125,120 @@ 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 await 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
+```
+
+---
+
 ## 🗺️ Roadmap
 
-- [x] OpenAI, Groq, Gemini, Anthropic, Azure, OpenRouter support
-- [x] Text to Image (DALL-E) and Text to Audio
-- [x] Automated Retry & Timeout controls
-- [ ] Async Support (`await ask_async`)
-- [ ] Provider Fallback (`ask(..., providers=[OpenAI, Groq])`)
-- [ ] Streaming Support (`ask_stream`)
-- [ ] Structured Output (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] 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)~~
 
 ---
 

askai_python-0.4.1/ask_ai/__init__.py

@@ -0,0 +1,51 @@
+"""
+ask-ai: A minimal Python SDK to switch between LLM providers in one line.
+"""
+
+__version__ = "0.4.1"
+
+from .providers import (
+    OpenAI,
+    Anthropic,
+    Google,
+    Groq,
+    Azure,
+    OpenRouter
+)
+from .config import AdvancedConfig
+from .base import Response
+from .media import ImageObject, AudioObject
+from .exceptions import (
+    AskAIError,
+    AskAIConfigError,
+    AskAINetworkError,
+    AskAIRateLimitError,
+    AskAIParsingError,
+    ProviderError,
+    MediaTypeNotSupportedError,
+    StreamNotSupportedError,
+)
+
+__all__ = [
+    # Providers
+    "OpenAI",
+    "Anthropic",
+    "Google",
+    "Groq",
+    "Azure",
+    "OpenRouter",
+    # Core
+    "AdvancedConfig",
+    "Response",
+    "ImageObject",
+    "AudioObject",
+    # Exceptions
+    "AskAIError",
+    "AskAIConfigError",
+    "AskAINetworkError",
+    "AskAIRateLimitError",
+    "AskAIParsingError",
+    "ProviderError",
+    "MediaTypeNotSupportedError",
+    "StreamNotSupportedError",
+]