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

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

@@ -1,20 +1,48 @@
 Metadata-Version: 2.4
 Name: askai-python
-Version: 0.2.1
-Summary: AI Made Stupid Simple. Unified API for OpenAI, Groq, Google, and more.
+Version: 0.4.0
+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://hosseinghorbani0.ir/
+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
-Requires-Python: >=3.8
+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
-Requires-Dist: openai>=1.0.0
-Requires-Dist: groq
-Requires-Dist: google-generativeai
-Requires-Dist: anthropic
-Requires-Dist: requests
-Requires-Dist: Pillow
+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 🚀
@@ -24,7 +52,7 @@ 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/ask-ai)
+[![GitHub](https://img.shields.io/badge/GitHub-View%20Source-blue.svg)](https://github.com/Hosseinghorbani0/askai-python)
 
 ---
 
@@ -46,7 +74,7 @@ print(Groq().ask("Explain black holes like I'm 5").text)
 
 ---
 
-## 🧐 Why ask-ai?
+## 🧐 Why askai-python?
 
 - **One function**: Just call `.ask()`
 - **Multiple providers**: OpenAI, Anthropic, Google Gemini, Groq, Azure, OpenRouter
@@ -66,7 +94,11 @@ It does one thing perfectly: **Simplifying the API call to LLMs.**
 ## 🛠️ Advanced Usage
 
 ### 🧰 Developer QoL Utilities (Auto-Parsing)
-Stop writing Regex to clean up model outputs! `ask-ai` comes with built-in text processing flags:
+
+<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
@@ -92,6 +124,10 @@ 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
@@ -132,6 +168,6 @@ response = ai.ask(
 
 ## 🔗 Important Links
 
-- **GitHub Repository**: [Hosseinghorbani0/ask-ai](https://github.com/Hosseinghorbani0/ask-ai) (Star us! ⭐)
+- **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/ask-ai/issues)
+- **Bug Tracker**: [Report an Issue](https://github.com/Hosseinghorbani0/askai-python/issues)

{askai_python-0.2.1 → askai_python-0.4.0}/README.md

@@ -12,6 +12,11 @@
   <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.
@@ -21,6 +26,8 @@
 [![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/)
 
+
+
 ---
 
 ## ⚡ Quick Start (5 seconds)
@@ -61,6 +68,10 @@ 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
@@ -86,6 +97,10 @@ 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
@@ -110,12 +125,31 @@ 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())
+```
+
+---
+
 ## 🗺️ 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`)
+- [x] Async Support (`await ask_async`)
 - [ ] Provider Fallback (`ask(..., providers=[OpenAI, Groq])`)
 - [ ] Streaming Support (`ask_stream`)
 - [ ] Structured Output (Pydantic Support)

askai_python-0.4.0/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.0"
+
+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",
+]

askai_python-0.4.0/ask_ai/base.py

@@ -0,0 +1,302 @@
+import os
+import time
+import random
+import asyncio
+import logging
+from typing import Union, List, Dict, Any, Iterator, AsyncIterator
+
+from .config import AdvancedConfig
+from .media import ImageObject, AudioObject
+
+logger = logging.getLogger("ask_ai")
+
+
+class Response:
+    """
+    Unified response object for all ask-ai requests.
+    """
+    def __init__(self, text: str = "", media: Union[ImageObject, AudioObject, None] = None, **kwargs):
+        self._raw_text = text
+        self.media = media
+        self._kwargs = kwargs
+
+    @property
+    def text(self) -> str:
+        text = self._raw_text
+        if self._kwargs.get('strip'):
+            from .utils import strip_tags
+            text = strip_tags(text)
+        if self._kwargs.get('clean'):
+            from .utils import clean_markdown
+            text = clean_markdown(text)
+        if self._kwargs.get('code'):
+            from .utils import extract_code
+            text = extract_code(text)
+        return text
+
+    @property
+    def json(self) -> Union[Dict[str, Any], list]:
+        """Returns parsed JSON. If 'json=True' was passed, this is highly reliable."""
+        from .utils import parse_json
+        return parse_json(self._raw_text)
+
+    def __str__(self) -> str:
+        return self.text
+
+    def __repr__(self) -> str:
+        preview = self._raw_text[:80] + "..." if len(self._raw_text) > 80 else self._raw_text
+        return f'<Response text="{preview}">'
+
+    def save(self, path: str) -> None:
+        """Smart save based on content type."""
+        if self.media:
+            self.media.save(path)
+        else:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(self.text)
+
+
+class BaseProvider:
+    """
+    Abstract base class for all AI providers.
+    Implements the core 'ask' logic and configuration management.
+    """
+    def __init__(self, api_key: str = None, model: str = None, persona: str = None, **kwargs):
+        # Zero-Config: Try env var if key not provided
+        self.api_key = api_key or os.environ.get(self._get_api_key_env_var())
+        self.model = model or self._get_default_model()
+        self.persona = persona
+        self.config = AdvancedConfig(**kwargs)
+
+    def _get_api_key_env_var(self) -> str:
+        """Subclasses should return the env var name, e.g. 'OPENAI_API_KEY'"""
+        raise NotImplementedError
+
+    def _get_default_model(self) -> str:
+        """Subclasses should return a default model"""
+        raise NotImplementedError
+
+    def advanced(self, **kwargs) -> None:
+        """
+        Update global advanced settings for this instance.
+        Merges new settings with existing ones.
+        """
+        new_conf = AdvancedConfig(**kwargs)
+        for k, v in new_conf.__dict__.items():
+            if k == 'extra':
+                continue
+            if v is not None:
+                setattr(self.config, k, v)
+        if new_conf.extra:
+            self.config.extra.update(new_conf.extra)
+
+    # ─── Sync API ───────────────────────────────────────────
+
+    def ask(self, query: str, **kwargs) -> Response:
+        """
+        The main entry point. Sync version.
+        Detects intent, manages config, and returns a unified Response.
+        """
+        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)
+
+        return self._execute_with_retry(
+            self._send_request, messages, final_config, output_type, retry
+        )
+
+    def ask_stream(self, query: str, **kwargs) -> Iterator[str]:
+        """
+        Streaming text generation. Yields text chunks.
+        """
+        final_config = self._build_final_config(kwargs)
+        messages = self._prepare_messages(query, final_config)
+        yield from self._send_request_stream(messages, final_config)
+
+    # ─── Async API ──────────────────────────────────────────
+
+    async def ask_async(self, query: str, **kwargs) -> Response:
+        """
+        Native async version of ask().
+        Uses provider's async client directly — no thread pool wrapping.
+        """
+        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)
+
+        return await self._execute_with_retry_async(
+            self._send_request_async, messages, final_config, output_type, retry
+        )
+
+    async def ask_stream_async(self, query: str, **kwargs) -> AsyncIterator[str]:
+        """
+        Async streaming text generation. Yields text chunks.
+        """
+        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):
+            yield chunk
+
+    # ─── Config Helpers ─────────────────────────────────────
+
+    def _build_final_config(self, kwargs: Dict[str, Any]) -> AdvancedConfig:
+        """Build final config by merging global config with per-request kwargs."""
+        request_config = AdvancedConfig(**kwargs)
+        final_config = self.config.merge(request_config)
+
+        # Ensure timeout has a default
+        timeout = kwargs.get('timeout', final_config.extra.get('timeout', 30))
+        final_config.extra['timeout'] = float(timeout) if timeout is not None else 30.0
+
+        return final_config
+
+    def _prepare_messages(self, query: str, config: AdvancedConfig) -> List[Dict[str, str]]:
+        """Build the messages list from query, persona, and config."""
+        messages = []
+
+        system_msg = config.system_message or self.persona or ""
+
+        # Smart capability: if json=True, enforce JSON system prompt
+        if 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()
+
+        if system_msg:
+            messages.append({"role": "system", "content": system_msg})
+
+        messages.append({"role": "user", "content": query})
+        return messages
+
+    # ─── Retry Logic ────────────────────────────────────────
+
+    def _execute_with_retry(self, func, messages, config, output_type, retry):
+        """Execute a sync function with exponential backoff + jitter."""
+        attempts = 0
+        last_error = None
+
+        while attempts <= retry:
+            try:
+                response = func(messages, config, output_type)
+                return response
+            except Exception as e:
+                last_error = e
+                if self._is_retryable_error(e) and attempts < retry:
+                    attempts += 1
+                    delay = min(2 ** attempts + random.uniform(0, 1), 30)
+                    logger.warning(
+                        "Transient error (%s). Retrying in %.1fs... (%d/%d)",
+                        e.__class__.__name__, delay, attempts, retry
+                    )
+                    time.sleep(delay)
+                else:
+                    raise
+
+        from .exceptions import AskAINetworkError
+        raise AskAINetworkError(f"Request failed after {retry} retries. Last error: {last_error}")
+
+    async def _execute_with_retry_async(self, func, messages, config, output_type, retry):
+        """Execute an async function with exponential backoff + jitter."""
+        attempts = 0
+        last_error = None
+
+        while attempts <= retry:
+            try:
+                response = await func(messages, config, output_type)
+                return response
+            except Exception as e:
+                last_error = e
+                if self._is_retryable_error(e) and attempts < retry:
+                    attempts += 1
+                    delay = min(2 ** attempts + random.uniform(0, 1), 30)
+                    logger.warning(
+                        "Transient error (%s). Retrying in %.1fs... (%d/%d)",
+                        e.__class__.__name__, delay, attempts, retry
+                    )
+                    await asyncio.sleep(delay)
+                else:
+                    raise
+
+        from .exceptions import AskAINetworkError
+        raise AskAINetworkError(f"Request failed after {retry} retries. Last error: {last_error}")
+
+    def _is_retryable_error(self, e: Exception) -> bool:
+        """Dynamically detect rate limits and network timeouts across different provider SDKs."""
+        from .exceptions import AskAINetworkError, AskAIRateLimitError
+        if isinstance(e, (AskAINetworkError, AskAIRateLimitError)):
+            return True
+
+        err_str = str(e).lower()
+        err_cls = e.__class__.__name__.lower()
+
+        retryable_indicators = ("ratelimit", "rate_limit", "429", "timeout", "connection", "connecterror")
+        return any(indicator in err_cls or indicator in err_str for indicator in retryable_indicators)
+
+    # ─── Abstract Methods (Subclasses Must Implement) ──────
+
+    def _send_request(self, messages: List[Dict[str, str]], config: AdvancedConfig, output_type: str = None) -> Response:
+        """Sync request — subclasses must implement."""
+        raise NotImplementedError
+
+    async def _send_request_async(self, messages: List[Dict[str, str]], config: AdvancedConfig, output_type: str = None) -> Response:
+        """Async request — subclasses should override for native async."""
+        # Default fallback: run sync in thread pool
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._send_request, messages, config, output_type)
+
+    def _send_request_stream(self, messages: List[Dict[str, str]], config: AdvancedConfig) -> Iterator[str]:
+        """Sync streaming — subclasses should override."""
+        from .exceptions import StreamNotSupportedError
+        raise StreamNotSupportedError(f"{self.__class__.__name__} does not support streaming.")
+
+    async def _send_request_stream_async(self, messages: List[Dict[str, str]], config: AdvancedConfig) -> AsyncIterator[str]:
+        """Async streaming — subclasses should override for native async."""
+        # Default fallback: wrap sync stream
+        loop = asyncio.get_running_loop()
+        for chunk in await loop.run_in_executor(None, lambda: list(self._send_request_stream(messages, config))):
+            yield chunk
+
+    # ─── Tool Definitions for Smart Intent ─────────────────
+
+    def _get_media_tools(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": "generate_image",
+                    "description": (
+                        "Generate an image based on a prompt. Use this when the user asks to draw, create, or show an image."
+                    ),
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "prompt": {
+                                "type": "string",
+                                "description": "The detailed description of the image to generate."
+                            }
+                        },
+                        "required": ["prompt"]
+                    }
+                }
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "generate_speech",
+                    "description": (
+                        "Generate audio speech from text. Use this when the user asks to say something, speak, or read aloud."
+                    ),
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "text": {
+                                "type": "string",
+                                "description": "The text to speak."
+                            }
+                        },
+                        "required": ["text"]
+                    }
+                }
+            }
+        ]

askai_python-0.4.0/ask_ai/cli.py

@@ -0,0 +1,107 @@
+import sys
+import argparse
+from . import __version__
+from . import (
+    OpenAI,
+    Groq,
+    Google,
+    OpenRouter,
+    Azure,
+    Anthropic,
+    AskAIError
+)
+
+
+PROVIDER_MAP = {
+    "openai": OpenAI,
+    "groq": Groq,
+    "google": Google,
+    "openrouter": OpenRouter,
+    "azure": Azure,
+    "anthropic": Anthropic,
+}
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="ask-ai CLI: Ask AI anything directly from your terminal."
+    )
+    parser.add_argument("query", nargs="?", help="The text query to ask the AI.")
+    parser.add_argument(
+        "--provider", "-p",
+        default="openai",
+        choices=list(PROVIDER_MAP.keys()),
+        help="The AI provider to use (default: openai)."
+    )
+    parser.add_argument("--model", "-m", help="Specific model to use.")
+    parser.add_argument("--temp", type=float, help="Temperature setting.")
+    parser.add_argument("--system", "-s", help="System prompt.")
+    parser.add_argument("--json", action="store_true", help="Request JSON output.")
+    parser.add_argument("--stream", action="store_true", help="Enable streaming output.")
+    parser.add_argument("--version", "-v", action="version", version=f"ask-ai {__version__}")
+
+    args = parser.parse_args()
+
+    if not args.query:
+        parser.print_help()
+        sys.exit(0)
+
+    provider_class = PROVIDER_MAP.get(args.provider.lower())
+    if not provider_class:
+        print(f"Error: Provider '{args.provider}' not found.")
+        sys.exit(1)
+
+    try:
+        # Init provider
+        init_kwargs = {}
+        if args.model:
+            init_kwargs["model"] = args.model
+
+        ai = provider_class(**init_kwargs)
+
+        # Build ask kwargs
+        ask_kwargs = {}
+        if args.temp is not None:
+            ask_kwargs["temperature"] = args.temp
+        if args.system:
+            ask_kwargs["system_message"] = args.system
+        if args.json:
+            ask_kwargs["json"] = True
+
+        # Stream or regular
+        if args.stream:
+            try:
+                for chunk in ai.ask_stream(args.query, **ask_kwargs):
+                    print(chunk, end="", flush=True)
+                print()  # newline at end
+            except Exception:
+                # Fallback to non-streaming if provider doesn't support it
+                response = ai.ask(args.query, **ask_kwargs)
+                print(response.text)
+        else:
+            response = ai.ask(args.query, **ask_kwargs)
+
+            if response.media:
+                print(f"Generated Media: {response.media.type}")
+                filename = f"output.{'png' if response.media.type == 'image' else 'mp3'}"
+                response.media.save(filename)
+                print(f"Saved to {filename}")
+            elif args.json:
+                import json
+                print(json.dumps(response.json, indent=2, ensure_ascii=False))
+            else:
+                print(response.text)
+
+    except AskAIError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        sys.exit(130)
+    except Exception as e:
+        print(f"Unexpected Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()