msgmodel 3.2.1__py3-none-any.whl

msgmodel/__init__.py

@@ -0,0 +1,81 @@
+"""
+msgmodel
+~~~~~~~~
+
+A unified Python library for interacting with LLM providers.
+
+Supports OpenAI and Google Gemini with a single, consistent interface.
+
+Basic usage:
+    >>> from msgmodel import query
+    >>> response = query("openai", "Hello, world!")
+    >>> print(response.text)
+
+Streaming:
+    >>> from msgmodel import stream
+    >>> for chunk in stream("openai", "Tell me a story"):
+    ...     print(chunk, end="", flush=True)
+
+With custom configuration:
+    >>> from msgmodel import query, OpenAIConfig
+    >>> config = OpenAIConfig(model="gpt-4o-mini", temperature=0.7)
+    >>> response = query("openai", "Hello!", config=config)
+"""
+
+__version__ = "3.2.1"
+__author__ = "Leo Dias"
+
+# Core API
+from .core import query, stream, LLMResponse
+
+# Configuration
+from .config import (
+    Provider,
+    OpenAIConfig,
+    GeminiConfig,
+    get_default_config,
+)
+
+# Exceptions
+from .exceptions import (
+    MsgModelError,
+    ConfigurationError,
+    AuthenticationError,
+    FileError,
+    APIError,
+    ProviderError,
+    StreamingError,
+)
+
+# Providers (for advanced usage)
+from .providers import OpenAIProvider, GeminiProvider
+
+# Security (v3.2.1+)
+from .security import RequestSigner
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core API
+    "query",
+    "stream",
+    "LLMResponse",
+    # Configuration
+    "Provider",
+    "OpenAIConfig",
+    "GeminiConfig",
+    "get_default_config",
+    # Exceptions
+    "MsgModelError",
+    "ConfigurationError",
+    "AuthenticationError",
+    "FileError",
+    "APIError",
+    "ProviderError",
+    "StreamingError",
+    # Providers
+    "OpenAIProvider",
+    "GeminiProvider",
+    # Security
+    "RequestSigner",
+]

msgmodel/__main__.py

@@ -0,0 +1,224 @@
+"""
+msgmodel CLI
+~~~~~~~~~~~~
+
+Command-line interface for msgmodel.
+
+Usage:
+    python -m msgmodel --provider openai --prompt "Hello, world!"
+    python -m msgmodel -p g -f prompt.txt --stream
+"""
+
+import argparse
+import sys
+import logging
+from pathlib import Path
+
+from . import (
+    __version__,
+    query,
+    stream,
+    Provider,
+    OpenAIConfig,
+    GeminiConfig,
+    ClaudeConfig,
+    MsgModelError,
+    ConfigurationError,
+    AuthenticationError,
+    FileError,
+    APIError,
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(levelname)s: %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger(__name__)
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        prog="msgmodel",
+        description="Unified LLM API - Query OpenAI, Gemini, or Claude from the command line.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s -p openai "Hello, world!"
+  %(prog)s -p gemini -f prompt.txt
+  %(prog)s -p claude "Tell me a story" --stream
+  %(prog)s -p o "Analyze this" -i instructions.txt -b image.jpg
+""",
+    )
+    
+    parser.add_argument(
+        "-p", "--provider",
+        required=True,
+        help="LLM provider: 'openai'/'o', 'gemini'/'g', or 'claude'/'c'",
+    )
+    
+    parser.add_argument(
+        "prompt",
+        nargs="?",
+        help="The prompt text (or use -f for file input)",
+    )
+    
+    parser.add_argument(
+        "-f", "--prompt-file",
+        help="Read prompt from file instead of command line",
+    )
+    
+    parser.add_argument(
+        "-i", "--instruction",
+        help="System instruction (text or path to file)",
+    )
+    
+    parser.add_argument(
+        "-b", "--binary-file",
+        help="Path to binary file (image, PDF, etc.)",
+    )
+    
+    parser.add_argument(
+        "-k", "--api-key",
+        help="API key (overrides environment variable and key file)",
+    )
+    
+    parser.add_argument(
+        "-m", "--model",
+        help="Model to use (overrides default)",
+    )
+    
+    parser.add_argument(
+        "-t", "--max-tokens",
+        type=int,
+        default=1000,
+        help="Maximum tokens to generate (default: 1000)",
+    )
+    
+    parser.add_argument(
+        "--temperature",
+        type=float,
+        help="Sampling temperature (0.0 to 2.0)",
+    )
+    
+    parser.add_argument(
+        "-s", "--stream",
+        action="store_true",
+        help="Stream the response",
+    )
+    
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output raw JSON response",
+    )
+    
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable verbose logging",
+    )
+    
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    
+    return parser.parse_args()
+
+
+def read_file_content(path: str) -> str:
+    """Read content from a file."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+    except IOError as e:
+        raise FileError(f"Cannot read file {path}: {e}")
+
+
+def main() -> int:
+    """Main entry point for the CLI."""
+    args = parse_args()
+    
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    
+    try:
+        # Get the prompt
+        if args.prompt:
+            prompt = args.prompt
+        elif args.prompt_file:
+            prompt = read_file_content(args.prompt_file)
+        else:
+            logger.error("Either prompt text or -f/--prompt-file is required")
+            return 1
+        
+        # Get system instruction
+        system_instruction = None
+        if args.instruction:
+            # Check if it's a file path
+            if Path(args.instruction).exists():
+                system_instruction = read_file_content(args.instruction)
+            else:
+                system_instruction = args.instruction
+        
+        # Common kwargs
+        kwargs = {
+            "provider": args.provider,
+            "prompt": prompt,
+            "api_key": args.api_key,
+            "system_instruction": system_instruction,
+            "file_path": args.binary_file,
+            "max_tokens": args.max_tokens,
+            "model": args.model,
+            "temperature": args.temperature,
+        }
+        
+        if args.stream:
+            # Streaming mode
+            for chunk in stream(**kwargs):
+                print(chunk, end="", flush=True)
+            print()  # Final newline
+        else:
+            # Non-streaming mode
+            response = query(**kwargs)
+            
+            if args.json:
+                import json
+                print(json.dumps(response.raw_response, indent=2))
+            else:
+                print(response.text)
+                
+                if args.verbose:
+                    logger.info(f"Model: {response.model}")
+                    logger.info(f"Provider: {response.provider}")
+                    if response.usage:
+                        logger.info(f"Usage: {response.usage}")
+        
+        return 0
+        
+    except ConfigurationError as e:
+        logger.error(f"Configuration error: {e}")
+        return 1
+    except AuthenticationError as e:
+        logger.error(f"Authentication error: {e}")
+        return 2
+    except FileError as e:
+        logger.error(f"File error: {e}")
+        return 3
+    except APIError as e:
+        logger.error(f"API error: {e}")
+        return 4
+    except MsgModelError as e:
+        logger.error(f"Error: {e}")
+        return 5
+    except KeyboardInterrupt:
+        logger.info("\nOperation cancelled")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

msgmodel/config.py

@@ -0,0 +1,159 @@
+"""
+msgmodel.config
+~~~~~~~~~~~~~~~
+
+Configuration dataclasses for LLM providers.
+
+These classes provide type-safe, runtime-configurable settings
+for each supported provider. Defaults match the original script's
+hardcoded values.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, List
+from enum import Enum
+
+
+class Provider(str, Enum):
+    """Supported LLM providers."""
+    OPENAI = "openai"
+    GEMINI = "gemini"
+    
+    @classmethod
+    def from_string(cls, value: str) -> "Provider":
+        """
+        Convert string to Provider enum.
+        
+        Args:
+            value: Provider name or shorthand ('o', 'g', 'openai', 'gemini')
+            
+        Returns:
+            Provider enum member
+            
+        Raises:
+            ValueError: If the value is not a valid provider
+        """
+        value = value.lower().strip()
+        
+        # Support shorthand codes
+        shortcuts = {
+            'o': cls.OPENAI,
+            'g': cls.GEMINI,
+        }
+        
+        if value in shortcuts:
+            return shortcuts[value]
+        
+        # Support full names
+        for provider in cls:
+            if provider.value == value:
+                return provider
+        
+        valid = ", ".join([f"'{p.value}'" for p in cls] + ["'o'", "'g'"])
+        raise ValueError(f"Invalid provider '{value}'. Valid options: {valid}")
+
+
+# ============================================================================
+# API URLs (constants, not configurable per-request)
+# ============================================================================
+OPENAI_URL = "https://api.openai.com/v1/chat/completions"
+GEMINI_URL = "https://generativelanguage.googleapis.com"
+
+# Environment variable names for API keys
+OPENAI_API_KEY_ENV = "OPENAI_API_KEY"
+GEMINI_API_KEY_ENV = "GEMINI_API_KEY"
+
+# Default API key file names (for backward compatibility)
+OPENAI_API_KEY_FILE = "openai-api.key"
+GEMINI_API_KEY_FILE = "gemini-api.key"
+
+
+@dataclass
+class OpenAIConfig:
+    """
+    Configuration for OpenAI API calls.
+    
+    **PRIVACY ENFORCEMENT**: Zero Data Retention (ZDR) is REQUIRED and non-negotiable.
+    The X-OpenAI-No-Store header is automatically added to all requests.
+    
+    OpenAI will NOT use your prompts or responses for model training or improvements.
+    See: https://platform.openai.com/docs/guides/zero-data-retention
+    
+    Attributes:
+        model: Model identifier (e.g., 'gpt-4o', 'gpt-4o-mini')
+        temperature: Sampling temperature (0.0 to 2.0)
+        top_p: Nucleus sampling parameter
+        max_tokens: Maximum tokens to generate
+        n: Number of completions to generate
+    
+    Note: File uploads are only supported via inline base64-encoding in prompts.
+    Files are limited to practical API size constraints (~15-20MB).
+    """
+    model: str = "gpt-4o"
+    temperature: float = 1.0
+    top_p: float = 1.0
+    max_tokens: int = 1000
+    n: int = 1
+
+
+@dataclass
+class GeminiConfig:
+    """
+    Configuration for Google Gemini API calls.
+    
+    **PRIVACY ENFORCEMENT**: PAID API TIER IS REQUIRED AND ENFORCED.
+    
+    Gemini paid services (with active Google Cloud Billing and paid quota):
+    - Do NOT use your prompts or responses for model training
+    - Retain data temporarily for abuse detection only (24-72 hours)
+    - Provide near-stateless operation for sensitive materials
+    
+    UNPAID TIER IS NOT SUPPORTED. Google retains data indefinitely for training
+    on unpaid services. This library will verify paid access and raise an error
+    if you attempt to use unpaid quota.
+    
+    See: https://ai.google.dev/gemini-api/terms
+    
+    Attributes:
+        model: Model identifier (e.g., 'gemini-2.5-flash', 'gemini-1.5-pro')
+        temperature: Sampling temperature (0.0 to 2.0)
+        top_p: Nucleus sampling parameter
+        top_k: Top-k sampling parameter
+        max_tokens: Maximum tokens to generate
+        candidate_count: Number of response candidates
+        safety_threshold: Content safety filtering level
+        api_version: API version to use
+        cache_control: Whether to enable caching
+    
+    Note: File uploads are only supported via inline base64-encoding in prompts.
+    Files are limited to practical API size constraints (~22MB).
+    """
+    model: str = "gemini-2.5-flash"
+    temperature: float = 1.0
+    top_p: float = 0.95
+    top_k: int = 40
+    max_tokens: int = 1000
+    candidate_count: int = 1
+    safety_threshold: str = "BLOCK_NONE"
+    api_version: str = "v1beta"
+    cache_control: bool = False
+
+# Type alias for supported configs
+ProviderConfig = OpenAIConfig | GeminiConfig
+
+
+def get_default_config(provider: Provider) -> ProviderConfig:
+    """
+    Get the default configuration for a provider.
+    
+    Args:
+        provider: The LLM provider
+        
+    Returns:
+        Default configuration dataclass for the provider
+    """
+    configs = {
+        Provider.OPENAI: OpenAIConfig,
+        Provider.GEMINI: GeminiConfig,
+    }
+    return configs[provider]()