askai-python 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

ask_ai/__init__.py

@@ -2,7 +2,7 @@
 ask-ai: A minimal Python SDK to switch between LLM providers in one line.
 """
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 from .providers import (
     OpenAI,

ask_ai/base.py

@@ -15,9 +15,10 @@ class Response:
     """
     Unified response object for all ask-ai requests.
     """
-    def __init__(self, text: str = "", media: Union[ImageObject, AudioObject, None] = None, **kwargs):
+    def __init__(self, text: str = "", media: Union[ImageObject, AudioObject, None] = None, response_model: Any = None, **kwargs):
         self._raw_text = text
         self.media = media
+        self.response_model = response_model
         self._kwargs = kwargs
 
     @property
@@ -40,6 +41,25 @@ class Response:
         from .utils import parse_json
         return parse_json(self._raw_text)
 
+    @property
+    def pydantic(self) -> Any:
+        """Returns parsed Pydantic model instance if response_model was provided."""
+        if not self.response_model:
+            raise ValueError("No response_model was specified for this request.")
+        return self.to_model(self.response_model)
+
+    def to_model(self, model_class: Any) -> Any:
+        """Parse the response text into a specified Pydantic model."""
+        text_content = self.text
+        if hasattr(model_class, "model_validate_json"):
+            return model_class.model_validate_json(text_content)
+        elif hasattr(model_class, "parse_raw"):
+            return model_class.parse_raw(text_content)
+        else:
+            import json
+            data = json.loads(text_content)
+            return model_class(**data)
+
     def __str__(self) -> str:
         return self.text
 
@@ -97,19 +117,68 @@ class BaseProvider:
         The main entry point. Sync version.
         Detects intent, manages config, and returns a unified Response.
         """
+        providers = kwargs.pop("providers", None) or kwargs.pop("fallback", None)
+        if providers:
+            if not isinstance(providers, (list, tuple)):
+                providers = [providers]
+            errors = []
+            for p in providers:
+                if isinstance(p, type):
+                    try:
+                        p_inst = p()
+                    except Exception as e:
+                        errors.append(f"{p.__name__} init failed: {e}")
+                        continue
+                else:
+                    p_inst = p
+                try:
+                    return p_inst.ask(query, **kwargs)
+                except Exception as e:
+                    errors.append(f"{p_inst.__class__.__name__}: {e}")
+                    logger.warning("Provider fallback failed for %s: %s", p_inst.__class__.__name__, e)
+            from .exceptions import ProviderError
+            raise ProviderError(f"All fallback providers failed: {errors}")
+
         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)
+        response_model = kwargs.get('response_model')
 
-        return self._execute_with_retry(
+        response = self._execute_with_retry(
             self._send_request, messages, final_config, output_type, retry
         )
+        if response_model:
+            response.response_model = response_model
+        return response
 
     def ask_stream(self, query: str, **kwargs) -> Iterator[str]:
         """
         Streaming text generation. Yields text chunks.
         """
+        providers = kwargs.pop("providers", None) or kwargs.pop("fallback", None)
+        if providers:
+            if not isinstance(providers, (list, tuple)):
+                providers = [providers]
+            errors = []
+            for p in providers:
+                if isinstance(p, type):
+                    try:
+                        p_inst = p()
+                    except Exception as e:
+                        errors.append(f"{p.__name__} init failed: {e}")
+                        continue
+                else:
+                    p_inst = p
+                try:
+                    yield from p_inst.ask_stream(query, **kwargs)
+                    return
+                except Exception as e:
+                    errors.append(f"{p_inst.__class__.__name__}: {e}")
+                    logger.warning("Provider fallback failed for %s: %s", p_inst.__class__.__name__, e)
+            from .exceptions import ProviderError
+            raise ProviderError(f"All fallback providers failed: {errors}")
+
         final_config = self._build_final_config(kwargs)
         messages = self._prepare_messages(query, final_config)
         yield from self._send_request_stream(messages, final_config)
@@ -121,19 +190,69 @@ class BaseProvider:
         Native async version of ask().
         Uses provider's async client directly — no thread pool wrapping.
         """
+        providers = kwargs.pop("providers", None) or kwargs.pop("fallback", None)
+        if providers:
+            if not isinstance(providers, (list, tuple)):
+                providers = [providers]
+            errors = []
+            for p in providers:
+                if isinstance(p, type):
+                    try:
+                        p_inst = p()
+                    except Exception as e:
+                        errors.append(f"{p.__name__} init failed: {e}")
+                        continue
+                else:
+                    p_inst = p
+                try:
+                    return await p_inst.ask_async(query, **kwargs)
+                except Exception as e:
+                    errors.append(f"{p_inst.__class__.__name__}: {e}")
+                    logger.warning("Provider fallback failed for %s: %s", p_inst.__class__.__name__, e)
+            from .exceptions import ProviderError
+            raise ProviderError(f"All fallback providers failed: {errors}")
+
         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)
+        response_model = kwargs.get('response_model')
 
-        return await self._execute_with_retry_async(
+        response = await self._execute_with_retry_async(
             self._send_request_async, messages, final_config, output_type, retry
         )
+        if response_model:
+            response.response_model = response_model
+        return response
 
     async def ask_stream_async(self, query: str, **kwargs) -> AsyncIterator[str]:
         """
         Async streaming text generation. Yields text chunks.
         """
+        providers = kwargs.pop("providers", None) or kwargs.pop("fallback", None)
+        if providers:
+            if not isinstance(providers, (list, tuple)):
+                providers = [providers]
+            errors = []
+            for p in providers:
+                if isinstance(p, type):
+                    try:
+                        p_inst = p()
+                    except Exception as e:
+                        errors.append(f"{p.__name__} init failed: {e}")
+                        continue
+                else:
+                    p_inst = p
+                try:
+                    async for chunk in await p_inst.ask_stream_async(query, **kwargs):
+                        yield chunk
+                    return
+                except Exception as e:
+                    errors.append(f"{p_inst.__class__.__name__}: {e}")
+                    logger.warning("Provider fallback failed for %s: %s", p_inst.__class__.__name__, e)
+            from .exceptions import ProviderError
+            raise ProviderError(f"All fallback providers failed: {errors}")
+
         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):
@@ -158,8 +277,31 @@ class BaseProvider:
 
         system_msg = config.system_message or self.persona or ""
 
-        # Smart capability: if json=True, enforce JSON system prompt
-        if config.extra.get('json'):
+        # 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 schema:
+                import json
+                schema_str = json.dumps(schema)
+                json_instruction = (
+                    f"You must respond with valid JSON matching the following JSON schema:\n"
+                    f"{schema_str}\n"
+                    f"Do not include any markdown markup, explanation, or HTML tags."
+                )
+            else:
+                json_instruction = "You must respond with valid JSON only."
+
+            system_msg = f"{system_msg}\n{json_instruction}".strip()
+            config.extra['json'] = True
+
+        elif config.extra.get('json'):
             json_instruction = "You must respond with valid JSON only, without any markdown formatting or tags."
             system_msg = f"{system_msg}\n{json_instruction}".strip()
 

ask_ai/providers/openrouter_provider.py

@@ -54,13 +54,70 @@ class OpenRouterProvider(OpenAIProvider):
         return []
 
     def _generate_image(self, messages, config):
-        raise ProviderError("OpenRouter does not support Image Generation via this library.")
+        prompt = messages[-1]["content"]
+        try:
+            import httpx
+        except ImportError:
+            raise ProviderError("httpx client library is required for OpenRouter Image Generation. Run: pip install httpx")
+        
+        from ..media import ImageObject
+        from .openai_provider import _download_bytes
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json"
+        }
+        payload = {
+            "model": self.model,
+            "prompt": prompt
+        }
+        try:
+            response = httpx.post("https://openrouter.ai/api/v1/images", json=payload, headers=headers, timeout=60.0)
+            response.raise_for_status()
+            data = response.json()
+            image_url = data["data"][0]["url"]
+            img_data = _download_bytes(image_url)
+            return Response(
+                text=f"Generated image via OpenRouter ({self.model}) for: {prompt}",
+                media=ImageObject(img_data)
+            )
+        except Exception as e:
+            raise ProviderError(f"OpenRouter Image Generation Error: {e}") from e
+
+    async def _generate_image_async(self, messages, config):
+        prompt = messages[-1]["content"]
+        try:
+            import httpx
+        except ImportError:
+            raise ProviderError("httpx client library is required for OpenRouter Image Generation. Run: pip install httpx")
+
+        from ..media import ImageObject
+        from .openai_provider import _download_bytes_async
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json"
+        }
+        payload = {
+            "model": self.model,
+            "prompt": prompt
+        }
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post("https://openrouter.ai/api/v1/images", json=payload, headers=headers, timeout=60.0)
+                response.raise_for_status()
+                data = response.json()
+            image_url = data["data"][0]["url"]
+            img_data = await _download_bytes_async(image_url)
+            return Response(
+                text=f"Generated image via OpenRouter ({self.model}) for: {prompt}",
+                media=ImageObject(img_data)
+            )
+        except Exception as e:
+            raise ProviderError(f"OpenRouter Image Generation Error: {e}") from e
 
     def _generate_audio(self, messages, config):
         raise ProviderError("OpenRouter does not support Audio Generation via this library.")
 
-    async def _generate_image_async(self, messages, config):
-        raise ProviderError("OpenRouter does not support Image Generation via this library.")
-
     async def _generate_audio_async(self, messages, config):
         raise ProviderError("OpenRouter does not support Audio Generation via this library.")

{askai_python-0.4.0.dist-info → askai_python-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: askai-python
-Version: 0.4.0
+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
@@ -143,6 +143,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 +206,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.4.0.dist-info → askai_python-0.4.1.dist-info}/RECORD

@@ -1,6 +1,6 @@
-ask_ai/__init__.py,sha256=Q-wjxDV6wB0f4T3XW4LVwLXqL71BF1EyMq_LMLIKxIg,959
+ask_ai/__init__.py,sha256=HS8rfHKtsMeaWrb-8D_KcJHH1zlPq8oKkuaN9SITHJY,959
 ask_ai/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
-ask_ai/base.py,sha256=m3ECA-fvNjxBmOfGwQsTtM7d06qO-f6iDBPLZzA5kHg,12554
+ask_ai/base.py,sha256=EvYHJF_dxp0HNnL3copjf0FoP9I747q4--0rUcriT9k,18742
 ask_ai/cli.py,sha256=t8iN3YGP4dgNVZ1THKfdm-U4eJF1zdB8UwNP7R9XUUw,3229
 ask_ai/config.py,sha256=xM5pySnWWWjyg_WHGtGWY8XZ_aTDdIIOf65Xs1Vc2UY,2664
 ask_ai/exceptions.py,sha256=i3qW9R7jeYEJiLhuEA6Pr65bEPTbZtMqASSt8ol_V2w,1025
@@ -13,10 +13,10 @@ ask_ai/providers/azure_provider.py,sha256=F97Na3aaEQ9EJx5rI6ekk1RTPTAl1NwVWAWoyU
 ask_ai/providers/google_provider.py,sha256=svXMqIHufI6ztkK51Ahgzz0aYUBirPk4ym7QETnbL88,5911
 ask_ai/providers/groq_provider.py,sha256=zF4LmGEsC8PKJ_jc_aoN8JHHALmpMuyeKmr5HNKB9NI,4877
 ask_ai/providers/openai_provider.py,sha256=_kRPvmV6jy1i69nqD22AlCu8vcw3lj7VjFoQOFAmwmU,10476
-ask_ai/providers/openrouter_provider.py,sha256=GEsu50GBZsF00BkOPdN44byRqZc5TI_f-WoIdkZjNEA,2319
-askai_python-0.4.0.dist-info/licenses/LICENSE,sha256=SUSbAUsh_Uqw7NDEKwAGRVPS7sojihBHIBGBx6WZxvg,1073
-askai_python-0.4.0.dist-info/METADATA,sha256=z6-8kdHqHieI3_xYhnzvVJz1LvhVyYeL23ip6S_nlBs,6052
-askai_python-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-askai_python-0.4.0.dist-info/entry_points.txt,sha256=Vh_PDH-aoeiZEFtZMM18kVLqVBE70EP9yvvXeZ9Lo4U,43
-askai_python-0.4.0.dist-info/top_level.txt,sha256=fW2GapXaz6f-2UAuzVVPUPNfZUK_ZS1dpLyCllcE03s,7
-askai_python-0.4.0.dist-info/RECORD,,
+ask_ai/providers/openrouter_provider.py,sha256=SzjULohgRhL8Uff_S_0OlFLffdiyde_0wNC-NNuNQHU,4506
+askai_python-0.4.1.dist-info/licenses/LICENSE,sha256=SUSbAUsh_Uqw7NDEKwAGRVPS7sojihBHIBGBx6WZxvg,1073
+askai_python-0.4.1.dist-info/METADATA,sha256=NtqvYM2uJCWGxSjzFc8MoDRrq6jWrViszzJ-VVu3qxs,7481
+askai_python-0.4.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+askai_python-0.4.1.dist-info/entry_points.txt,sha256=Vh_PDH-aoeiZEFtZMM18kVLqVBE70EP9yvvXeZ9Lo4U,43
+askai_python-0.4.1.dist-info/top_level.txt,sha256=fW2GapXaz6f-2UAuzVVPUPNfZUK_ZS1dpLyCllcE03s,7
+askai_python-0.4.1.dist-info/RECORD,,

{askai_python-0.4.0.dist-info → askai_python-0.4.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (83.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any