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

ask_ai/__init__.py

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

ask_ai/base.py

@@ -1,13 +1,19 @@
-from typing import Optional, Union, List, Dict, Any
 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 easyai requests.
+    Unified response object for all ask-ai requests.
     """
     def __init__(self, text: str = "", media: Union[ImageObject, AudioObject, None] = None, **kwargs):
         self._raw_text = text
@@ -34,17 +40,21 @@ class Response:
         from .utils import parse_json
         return parse_json(self._raw_text)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.text
 
-    def save(self, path: str):
+    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)
-            print(f"Text saved to {path}")
+
 
 class BaseProvider:
     """
@@ -52,17 +62,10 @@ class BaseProvider:
     Implements the core 'ask' logic and configuration management.
     """
     def __init__(self, api_key: str = None, model: str = None, persona: str = None, **kwargs):
-        # 1. Zero-Config: Try env var if key not provided
+        # Zero-Config: Try env var if key not provided
         self.api_key = api_key or os.environ.get(self._get_api_key_env_var())
-        if not self.api_key:
-             # Some providers might not need it (e.g. local), but generally they do.
-             # We allow subclass to handle granular validation, but warn here.
-             pass
-
         self.model = model or self._get_default_model()
         self.persona = persona
-        
-        # Global Advanced Config
         self.config = AdvancedConfig(**kwargs)
 
     def _get_api_key_env_var(self) -> str:
@@ -73,116 +76,198 @@ class BaseProvider:
         """Subclasses should return a default model"""
         raise NotImplementedError
 
-    def advanced(self, **kwargs):
+    def advanced(self, **kwargs) -> None:
         """
         Update global advanced settings for this instance.
         Merges new settings with existing ones.
         """
         new_conf = AdvancedConfig(**kwargs)
-        # primitive merge: update self.config with new values
         for k, v in new_conf.__dict__.items():
+            if k == 'extra':
+                continue
             if v is not None:
                 setattr(self.config, k, v)
-        
-        # Handle extra kwargs
         if new_conf.extra:
             self.config.extra.update(new_conf.extra)
 
+    # ─── Sync API ───────────────────────────────────────────
+
     def ask(self, query: str, **kwargs) -> Response:
         """
-        The main entry point. 
+        The main entry point. Sync version.
         Detects intent, manages config, and returns a unified Response.
         """
-        # 1. Merge Request Config with Global Config
-        request_config = AdvancedConfig(**kwargs)
-        final_config = self._merge_configs(self.config, request_config)
+        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)
 
-        # 2. Add System/Persona Message
+        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 ──────────────────────────────────────────
 
-        # 3. Check for specific output_type override (e.g. user forced image)
+    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')
-        
-        # 4. Extract timeout and retry safely
-        timeout_val = kwargs.get('timeout', final_config.extra.get('timeout', 30))
-        retry_val = kwargs.get('retry', final_config.extra.get('retry', 0))
-        
-        timeout = float(timeout_val) if timeout_val is not None else 30.0
-        retry = int(retry_val) if retry_val is not None else 0
-        
-        final_config.extra['timeout'] = timeout # Pass down to providers
-
-        # 5. Execute with Retry Logic
+        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 = self._send_request(messages, final_config, output_type)
-                # Attach parsing arguments to the response object dynamically
-                response._kwargs.update(kwargs)
+                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 = 2 ** attempts # 2s, 4s, 8s...
-                    print(f"[ask-ai] Transient error ({e.__class__.__name__}). Retrying in {delay}s... ({attempts}/{retry})")
-                    import time
+                    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 e
-                    
-        # Fallback if loop exits without returning
+                    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()
-        
-        # Explicit ask-ai errors
-        from .exceptions import AskAINetworkError, AskAIRateLimitError
-        if isinstance(e, (AskAINetworkError, AskAIRateLimitError)): return True
-        
-        # Heuristics for underlying provider SDKs (OpenAI, Anthropic, etc.)
-        if "ratelimit" in err_cls or "rate_limit" in err_cls or "429" in err_str: return True
-        if "timeout" in err_cls or "timeout" in err_str: return True
-        if "connection" in err_cls or "connecterror" in err_cls: return True
-        
-        return False
-
-    def _merge_configs(self, global_conf: AdvancedConfig, req_conf: AdvancedConfig) -> AdvancedConfig:
-        return global_conf.merge(req_conf) # We need to implement merge logic in AdvancedConfig properly or here
 
-    def _prepare_messages(self, query: str, config: AdvancedConfig) -> List[Dict[str, str]]:
-        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()
+        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)
 
-        if system_msg:
-            messages.append({"role": "system", "content": system_msg})
-        
-        messages.append({"role": "user", "content": query})
-        return messages
+    # ─── Abstract Methods (Subclasses Must Implement) ──────
 
     def _send_request(self, messages: List[Dict[str, str]], config: AdvancedConfig, output_type: str = None) -> Response:
-        """Subclasses must implement this."""
+        """Sync request — subclasses must implement."""
         raise NotImplementedError
 
-    # --- Tool Definitions for Smart Intent ---
+    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.",
+                    "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": {
@@ -199,7 +284,9 @@ class BaseProvider:
                 "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.",
+                    "description": (
+                        "Generate audio speech from text. Use this when the user asks to say something, speak, or read aloud."
+                    ),
                     "parameters": {
                         "type": "object",
                         "properties": {

ask_ai/cli.py

@@ -1,77 +1,107 @@
 import sys
 import argparse
-from .providers import OpenAI
-from .exceptions import EasyAIError
+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="easyai CLI: Ask AI anything directly from your terminal.")
-    parser.add_argument("query", help="The text query to ask the AI.")
-    parser.add_argument("--provider", default="openai", choices=["openai", "groq", "google", "openrouter", "azure", "anthropic"], help="The AI provider to use.")
-    parser.add_argument("--model", help="Specific model to use (optional).")
-    parser.add_argument("--temp", type=float, help="Temperature setting (optional).")
-    
+    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()
 
-    # Map provider name to class
-    providers = {
-        "openai": OpenAI,
-        # Lazy load others to avoid unnecessary imports if cli is used often? 
-        # But we already imported OpenAI. 
-        # Let's import dynamically or just map if already imported in __init__.
-    }
-    
-    # We need to import others dynamically or statically. 
-    # Since __init__ exposes them, let's use that.
-    import easyai
-    
-    provider_class = getattr(easyai, args.provider.capitalize(), None)
-    if args.provider == "openrouter": # naming case mismatch
-        provider_class = easyai.OpenRouter
-    elif args.provider == "openai":
-         provider_class = easyai.OpenAI
-    elif args.provider == "groq":
-         provider_class = easyai.Groq
-    elif args.provider == "google":
-         provider_class = easyai.Google
-    elif args.provider == "azure":
-         provider_class = easyai.Azure
-    elif args.provider == "anthropic":
-         provider_class = easyai.Anthropic
+    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
-        kwargs = {}
+        init_kwargs = {}
         if args.model:
-            kwargs["model"] = args.model
-        
-        ai = provider_class(**kwargs)
-        
-        # Ask
+            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
 
-        print(f"[{args.provider.upper()}] Thinking...")
-        response = ai.ask(args.query, **ask_kwargs)
-        
-        if response.media:
-            print(f"Generated Media: {response.media.type}")
-            response.media.show()
-            # auto save to current directory?
-            filename = f"output.{'png' if response.media.type == 'image' else 'mp3'}"
-            response.media.save(filename)
-            print(f"Saved to {filename}")
+        # 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:
-            print(response.text)
+            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 EasyAIError as e:
-        print(f"EasyAI Error: {e}")
+    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}")
+        print(f"Unexpected Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
 
 if __name__ == "__main__":
     main()

ask_ai/config.py

@@ -1,8 +1,10 @@
-from typing import Optional, Dict, Any
+from typing import Optional, Dict, Any, List
+
 
 class AdvancedConfig:
     """
     Configuration class for advanced AI settings.
+    Supports both direct init and aliased parameters for usability.
     """
     def __init__(
         self,
@@ -11,7 +13,7 @@ class AdvancedConfig:
         top_p: Optional[float] = None,
         frequency_penalty: Optional[float] = None,
         presence_penalty: Optional[float] = None,
-        stop: Optional[list] = None,
+        stop: Optional[List[str]] = None,
         system_message: Optional[str] = None,
         safe_mode: bool = False,
         **kwargs
@@ -22,35 +24,58 @@ class AdvancedConfig:
         self.frequency_penalty = frequency_penalty
         self.presence_penalty = presence_penalty
         self.stop = stop
-        self.stop = stop
-        
+
         # Smart Aliases for 10/10 Usability
         # If user passes 'prompt' or 'system', treat it as 'system_message'
         if system_message is None:
-            system_message = kwargs.get("prompt") or kwargs.get("system")
-        
+            system_message = kwargs.pop("prompt", None) or kwargs.pop("system", None)
+        else:
+            # Remove aliases from kwargs if system_message was explicitly set
+            kwargs.pop("prompt", None)
+            kwargs.pop("system", None)
+
         self.system_message = system_message
         self.safe_mode = safe_mode
-        self.extra = kwargs
+        self.extra: Dict[str, Any] = kwargs
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert config to a dictionary, filtering None values."""
-        return {k: v for k, v in self.__dict__.items() if v is not None and k != 'extra'}
+        result = {}
+        for k, v in self.__dict__.items():
+            if k == 'extra':
+                continue
+            if v is not None:
+                result[k] = v
+        return result
 
-    def merge(self, other_config: 'AdvancedConfig') -> 'AdvancedConfig':
-        """Merge another config into this one (other overrides self)."""
-        new_config = AdvancedConfig()
-        # Copy self
+    def merge(self, other: 'AdvancedConfig') -> 'AdvancedConfig':
+        """
+        Merge another config into this one (other overrides self).
+        Returns a new AdvancedConfig without mutating either input.
+        """
+        merged = AdvancedConfig()
+
+        # Copy self values
         for k, v in self.__dict__.items():
-            setattr(new_config, k, v)
-        
-        # Override with other
-        for k, v in other_config.__dict__.items():
+            if k == 'extra':
+                continue
+            setattr(merged, k, v)
+
+        # Override with other values (only non-None)
+        for k, v in other.__dict__.items():
+            if k == 'extra':
+                continue
             if v is not None:
-                setattr(new_config, k, v)
-        
-        return new_config
-    
+                setattr(merged, k, v)
+
+        # Deep merge extra dicts
+        merged_extra = dict(self.extra)
+        merged_extra.update(other.extra)
+        merged.extra = merged_extra
+
+        return merged
+
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> 'AdvancedConfig':
+        """Create an AdvancedConfig from a dictionary."""
         return cls(**data)