msgmodel 3.2.1__py3-none-any.whl

msgmodel/security.py

@@ -0,0 +1,165 @@
+"""
+msgmodel.security
+~~~~~~~~~~~~~~~~~
+
+Security utilities for msgmodel, including request signing and verification.
+
+v3.2.1 Enhancement: Request signing for multi-tenant deployments.
+"""
+
+import hmac
+import hashlib
+import json
+import logging
+from typing import Optional, Any, Dict
+
+logger = logging.getLogger(__name__)
+
+
+class RequestSigner:
+    """
+    Stateless request signer for verifying request authenticity in multi-user deployments.
+    
+    v3.2.1 Enhancement: Provides optional request signing to prevent unauthorized API calls
+    in shared environments. Signing is deterministic and does not require server state.
+    
+    Example:
+        >>> signer = RequestSigner(secret_key="my-secret-key")
+        >>> signature = signer.sign_request(
+        ...     provider="openai",
+        ...     message="Hello, world!",
+        ...     model="gpt-4o"
+        ... )
+        >>> 
+        >>> # Verify signature on receiving end
+        >>> is_valid = signer.verify_signature(
+        ...     signature=signature,
+        ...     provider="openai",
+        ...     message="Hello, world!",
+        ...     model="gpt-4o"
+        ... )
+    """
+    
+    def __init__(self, secret_key: str):
+        """
+        Initialize the request signer.
+        
+        Args:
+            secret_key: Secret key for HMAC signing (must be kept confidential)
+        """
+        if not secret_key or not isinstance(secret_key, str):
+            raise ValueError("secret_key must be a non-empty string")
+        self.secret = secret_key
+    
+    def _canonicalize(self, provider: str, message: str, **kwargs) -> str:
+        """
+        Create a canonical string representation of a request for signing.
+        
+        The canonical format is deterministic and order-independent for kwargs.
+        
+        Args:
+            provider: LLM provider name
+            message: User message/prompt
+            **kwargs: Additional request parameters
+            
+        Returns:
+            Canonical request string
+        """
+        # Sort kwargs by key for deterministic ordering
+        sorted_kwargs = sorted(kwargs.items())
+        canonical = f"{provider}|{message}|{json.dumps(sorted_kwargs, sort_keys=True)}"
+        return canonical
+    
+    def sign_request(self, provider: str, message: str, **kwargs) -> str:
+        """
+        Generate HMAC-SHA256 signature for a request.
+        
+        The signature covers the provider, message, and all additional parameters.
+        Signatures are deterministic—the same request always produces the same signature.
+        
+        Args:
+            provider: LLM provider name ('openai', 'gemini', etc.)
+            message: User message/prompt
+            **kwargs: Additional request parameters (model, temperature, file_hash, etc.)
+            
+        Returns:
+            Hex-encoded HMAC-SHA256 signature
+        """
+        canonical = self._canonicalize(provider, message, **kwargs)
+        signature = hmac.new(
+            self.secret.encode("utf-8"),
+            canonical.encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+        return signature
+    
+    def verify_signature(
+        self,
+        signature: str,
+        provider: str,
+        message: str,
+        **kwargs
+    ) -> bool:
+        """
+        Verify a request signature.
+        
+        Uses constant-time comparison to prevent timing attacks.
+        
+        Args:
+            signature: Hex-encoded signature to verify
+            provider: LLM provider name
+            message: User message/prompt
+            **kwargs: Additional request parameters (must match original request)
+            
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        try:
+            expected_signature = self.sign_request(provider, message, **kwargs)
+            # Use constant-time comparison to prevent timing attacks
+            return hmac.compare_digest(signature, expected_signature)
+        except Exception as e:
+            logger.warning(f"Signature verification failed: {e}")
+            return False
+    
+    def sign_dict(self, request_dict: Dict[str, Any]) -> str:
+        """
+        Sign a request dictionary containing 'provider', 'message', and optional other fields.
+        
+        Args:
+            request_dict: Dictionary with at least 'provider' and 'message' keys
+            
+        Returns:
+            Hex-encoded HMAC-SHA256 signature
+            
+        Raises:
+            ValueError: If required keys are missing
+        """
+        if "provider" not in request_dict or "message" not in request_dict:
+            raise ValueError("request_dict must contain 'provider' and 'message' keys")
+        
+        provider = request_dict["provider"]
+        message = request_dict["message"]
+        kwargs = {k: v for k, v in request_dict.items() if k not in ("provider", "message")}
+        
+        return self.sign_request(provider, message, **kwargs)
+    
+    def verify_dict(self, signature: str, request_dict: Dict[str, Any]) -> bool:
+        """
+        Verify a signature for a request dictionary.
+        
+        Args:
+            signature: Hex-encoded signature to verify
+            request_dict: Dictionary with at least 'provider' and 'message' keys
+            
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        if "provider" not in request_dict or "message" not in request_dict:
+            return False
+        
+        provider = request_dict["provider"]
+        message = request_dict["message"]
+        kwargs = {k: v for k, v in request_dict.items() if k not in ("provider", "message")}
+        
+        return self.verify_signature(signature, provider, message, **kwargs)

msgmodel-3.2.1.dist-info/METADATA

@@ -0,0 +1,416 @@
+Metadata-Version: 2.4
+Name: msgmodel
+Version: 3.2.1
+Summary: Privacy-focused Python library for interacting with LLM providers (OpenAI, Gemini). Zero-retention middleware with stateless BytesIO-only file uploads.
+Author-email: Leo Dias <leoodiass@outlook.com>
+Maintainer-email: Leo Dias <leoodiass@outlook.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/LeoooDias/msgModel
+Project-URL: Repository, https://github.com/LeoooDias/msgModel
+Project-URL: Documentation, https://github.com/LeoooDias/msgModel#readme
+Project-URL: Issues, https://github.com/LeoooDias/msgModel/issues
+Project-URL: Changelog, https://github.com/LeoooDias/msgModel/releases
+Keywords: llm,openai,gemini,gpt,ai,machine-learning,chatbot,api,unified,wrapper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.18.0; extra == "claude"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.18.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# msgmodel
+
+[![PyPI version](https://badge.fury.io/py/msgmodel.svg)](https://badge.fury.io/py/msgmodel)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A unified Python library and CLI for interacting with multiple Large Language Model (LLM) providers with **privacy-first, zero-retention design**.
+
+## Overview
+
+`msgmodel` provides both a **Python library** and a **command-line interface** to interact with two major LLM providers:
+- **OpenAI** (GPT models) — Zero Data Retention enforced
+- **Google Gemini** (Paid tier) — Abuse-monitoring retention only
+
+**Privacy Guarantee**: All files are processed via in-memory BytesIO objects with base64 inline encoding. No persistent file storage, no server-side uploads, no training data retention (when configured correctly).
+
+## Features
+
+- **Unified API**: Single `query()` and `stream()` functions work with all providers
+- **Library & CLI**: Use as a Python module or command-line tool
+- **Streaming support**: Stream responses in real-time
+- **File attachments**: Process images, PDFs, and text files with in-memory BytesIO only
+- **Flexible configuration**: Dataclass-based configs with sensible defaults
+- **Multiple API key sources**: Direct parameter, environment variable, or key file
+- **Exception-based error handling**: Clean errors, no `sys.exit()` in library code
+- **Type-safe**: Full type hints throughout
+- **Privacy-first**: Mandatory zero-retention enforcement, stateless design, BytesIO-only file transfers
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install msgmodel
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/LeoooDias/msgmodel.git
+cd msgmodel
+
+# Install the package
+pip install -e .
+
+# Or with development dependencies
+pip install -e ".[dev]"
+```
+
+### Prerequisites
+
+- Python 3.10 or higher
+- API keys from the providers you wish to use
+
+## Quick Start
+
+### As a Library
+
+```python
+from msgmodel import query, stream
+
+# Simple query (uses OPENAI_API_KEY env var)
+response = query("openai", "What is Python?")
+print(response.text)
+
+# With explicit API key
+response = query("gemini", "Hello!", api_key="your-api-key")
+
+# Streaming
+for chunk in stream("openai", "Tell me a story"):
+    print(chunk, end="", flush=True)
+
+# With file attachment (in-memory BytesIO only)
+import io
+file_obj = io.BytesIO(your_binary_data)
+response = query("gemini", "Describe this image", file_like=file_obj, filename="photo.jpg")
+
+# With custom configuration
+from msgmodel import OpenAIConfig
+
+config = OpenAIConfig(model="gpt-4o-mini", temperature=0.7, max_tokens=2000)
+response = query("openai", "Write a poem", config=config)
+```
+
+### As a CLI
+
+```bash
+# Basic usage
+python -m msgmodel -p openai "What is Python?"
+
+# Using shorthand provider codes
+python -m msgmodel -p g "Hello, Gemini!"  # g = gemini
+python -m msgmodel -p o "Hello, OpenAI!"  # o = openai
+
+# With streaming
+python -m msgmodel -p openai "Tell me a story" --stream
+
+# From a file
+python -m msgmodel -p gemini -f prompt.txt
+
+# With system instruction
+python -m msgmodel -p openai "Analyze this" -i "You are a data analyst"
+
+# With file attachment (base64 inline)
+python -m msgmodel -p gemini "Describe this" -b image.jpg
+
+# Custom parameters
+python -m msgmodel -p openai "Hello" -m gpt-4o-mini -t 500 --temperature 0.7
+
+# Get full JSON response instead of just text
+python -m msgmodel -p openai "Hello" --json
+
+# Verbose output (shows model, provider, token usage)
+python -m msgmodel -p openai "Hello" -v
+```
+
+## API Key Configuration
+
+API keys can be provided in three ways (in order of priority):
+
+1. **Direct parameter**: `query("openai", "Hello", api_key="sk-...")`
+2. **Environment variable**:
+   - `OPENAI_API_KEY` for OpenAI
+   - `GEMINI_API_KEY` for Gemini
+3. **Key file** in current directory:
+   - `openai-api.key`
+   - `gemini-api.key`
+
+## Configuration
+
+Each provider has its own configuration dataclass with sensible defaults:
+
+```python
+from msgmodel import OpenAIConfig, GeminiConfig
+
+# OpenAI configuration
+openai_config = OpenAIConfig(
+    model="gpt-4o",           # Model to use
+    temperature=1.0,          # Sampling temperature
+    top_p=1.0,                # Nucleus sampling
+    max_tokens=1000,          # Max output tokens
+)
+
+# Gemini configuration
+gemini_config = GeminiConfig(
+    model="gemini-2.5-flash",
+    temperature=1.0,
+    top_p=0.95,
+    top_k=40,
+    safety_threshold="BLOCK_NONE",
+)
+```
+
+## Data Retention & Privacy
+
+`msgmodel` is designed with **statelessness** as a core principle. Here's what you need to know:
+
+### OpenAI (Zero Data Retention)
+
+When using OpenAI:
+
+- **What's protected**: Input prompts, system instructions, and model responses
+- **How**: The `X-OpenAI-No-Store` header is automatically added to all Chat Completions requests
+- **Result**: OpenAI does **not** use these interactions for service improvements or model training
+- **Persistence**: Inputs/outputs are **not stored** beyond the immediate request-response cycle
+- **File handling**: All files are base64-encoded and embedded inline in prompts — no server-side uploads
+
+**Important limitations**:
+- OpenAI's **API logs** may retain minimal metadata (timestamps, API version, token counts) for ~30 days for debugging purposes, but not the actual content
+- **Billing records** will still show API usage but not interaction content
+
+Example (ZDR enforced):
+```python
+from msgmodel import query
+
+response = query("openai", "Sensitive prompt")
+# Zero Data Retention is enforced automatically by the X-OpenAI-No-Store header
+```
+
+### Google Gemini (Paid Tier Required)
+
+Google Gemini's data retention policy **depends on which service tier you use**. No API parameter controls this; it's determined by your Google Cloud account configuration.
+
+**Paid Services (Google Cloud Billing + Paid Quota)**
+
+- **What's protected**: Data is NOT used for model training or product improvement
+- **What IS retained**: Prompts and responses retained temporarily for abuse detection only (typically 24-72 hours)
+- **Human review**: NO (unless abuse is detected)
+- **Statelessness**: ✅ ACHIEVABLE — within abuse monitoring requirements
+- **File handling**: Base64-encoded inline embedding — no persistent storage
+
+```python
+from msgmodel import query
+
+# Paid tier: Data protected from training, used only for abuse monitoring
+response = query("gemini", "Sensitive prompt", api_key="your-api-key")
+```
+
+**Important**: Using Gemini assumes your Google Cloud project has:
+1. Cloud Billing account linked
+2. Paid API quota enabled (not on free quota tier)
+
+If not enabled, Google will apply unpaid service terms regardless of your code.
+
+**Learn more**: [Google Gemini API Terms — How Google Uses Your Data](https://ai.google.dev/gemini-api/terms)
+
+### Summary Comparison
+
+| Provider | Statelessness Achievable | How | Caveat |
+|----------|--------------------------|-----|---------|
+| **OpenAI** | ✅ YES | Automatic ZDR header | Metadata ~30 days |
+| **Gemini (Paid)** | ✅ MOSTLY | Cloud Billing + paid quota | Abuse monitoring ~24-72 hours |
+| **Gemini (Unpaid)** | ❌ NO | No configuration possible | Data retained for training indefinitely |
+
+For maximum privacy, use **OpenAI with zero-retention** (default) or **Gemini with paid Cloud Billing**.
+
+## File Uploads
+
+### The BytesIO-Only Approach
+
+All file uploads in msgmodel v3.2.0+ use **in-memory BytesIO objects** with base64 inline encoding:
+
+```python
+import io
+from msgmodel import query
+
+# Read file into memory
+with open("document.pdf", "rb") as f:
+    file_data = f.read()
+
+# Create BytesIO object
+file_obj = io.BytesIO(file_data)
+
+# Query with file
+response = query(
+    "openai",
+    "Summarize this document",
+    file_like=file_obj,
+    filename="document.pdf"  # Enables MIME type detection
+)
+```
+
+**Why BytesIO only?**
+- No disk persistence between requests
+- No server-side file uploads (Files API not used)
+- Better privacy—files never stored on provider servers
+- Stateless operation—each request is completely independent
+
+**File Size Limits**
+- **OpenAI**: ~15-20MB practical limit (base64 overhead + token limits)
+- **Gemini**: ~22MB practical limit (base64 overhead + token limits)
+
+If API returns a size-related error, the file exceeds practical limits for that provider.
+
+## Error Handling
+
+The library uses exceptions instead of `sys.exit()`:
+
+```python
+from msgmodel import query, MsgModelError, AuthenticationError, APIError
+
+try:
+    response = query("openai", "Hello")
+except AuthenticationError as e:
+    print(f"API key issue: {e}")
+except APIError as e:
+    print(f"API call failed: {e}")
+    print(f"Status code: {e.status_code}")
+except MsgModelError as e:
+    print(f"General error: {e}")
+```
+
+## Response Object
+
+The `query()` function returns an `LLMResponse` object:
+
+```python
+response = query("openai", "Hello")
+
+print(response.text)          # The generated text
+print(response.model)         # Model used (e.g., "gpt-4o")
+print(response.provider)      # Provider name (e.g., "openai")
+print(response.usage)         # Token usage dict (if available)
+print(response.raw_response)  # Complete API response
+```
+
+## Project Structure
+
+```
+msgmodel/
+├── msgmodel/                    # Python package
+│   ├── __init__.py              # Public API exports
+│   ├── __main__.py              # CLI entry point
+│   ├── core.py                  # Core query/stream functions
+│   ├── config.py                # Configuration dataclasses
+│   ├── exceptions.py            # Custom exceptions
+│   ├── py.typed                 # PEP 561 marker for typed package
+│   └── providers/               # Provider implementations
+│       ├── __init__.py
+│       ├── openai.py
+│       └── gemini.py
+├── tests/                       # Test suite
+│   ├── test_config.py
+│   ├── test_core.py
+│   └── test_exceptions.py
+├── pyproject.toml               # Package configuration
+├── LICENSE                      # MIT License
+├── MANIFEST.in                  # Distribution manifest
+├── requirements.txt             # Dependencies
+└── README.md
+```
+
+## CLI Usage
+
+After installation, the `msgmodel` command is available:
+
+```bash
+# Basic usage
+msgmodel -p openai "What is Python?"
+
+# Or using python -m
+python -m msgmodel -p openai "What is Python?"
+
+# Provider shortcuts: o=openai, g=gemini
+msgmodel -p g "Hello, Gemini!"
+
+# With streaming
+msgmodel -p openai "Tell me a story" --stream
+
+# From a file
+msgmodel -p gemini -f prompt.txt
+```
+
+## Running Tests
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=msgmodel
+```
+
+## Building & Publishing
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build the package
+python -m build
+
+# Check the distribution
+twine check dist/*
+
+# Upload to PyPI (requires PyPI account)
+twine upload dist/*
+
+# Upload to TestPyPI first (recommended)
+twine upload --repository testpypi dist/*
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Author
+
+Leo Dias
+

msgmodel-3.2.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+msgmodel/__init__.py,sha256=HCivZ1dIjhiMtZN9j4hcIlSY6mLY2hbuzrZtlQT_NDI,1663
+msgmodel/__main__.py,sha256=n-A86IWf8A4X3lAWjPBR_bilewNxZJrdZbv7pB5b24Y,5755
+msgmodel/config.py,sha256=Gz4BHLmD3LMv3x8XXSv-kxaNc3X357VkjKO04YkdE_Y,5005
+msgmodel/core.py,sha256=kPlykiCxicmKBKZfy8fccc-6YGfKNRiPlSTCdjsyqOY,17329
+msgmodel/exceptions.py,sha256=DdtQs8UfaL_KBoAwtLN-t6tYsyh10s6fMxsGbJDmr3o,1973
+msgmodel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+msgmodel/security.py,sha256=46_BHRwXN9GUeLpBen9_siBwPiq7kxSuT7WjqvryMIM,5739
+msgmodel/providers/__init__.py,sha256=tH7tCRE97XlVDyUEgjpztMj148v2TTH2cda_galYPvQ,219
+msgmodel/providers/gemini.py,sha256=jK7uAQ4714tkn17aVeReXdaiKKuoLNPHnmxbruCI1Ag,12280
+msgmodel/providers/openai.py,sha256=sEz8CpILV5d0nZE62fkC37mkPZ2H_xcCmeDx4RuXW08,13003
+msgmodel-3.2.1.dist-info/licenses/LICENSE,sha256=yrOPs41SkWzJmldAS0ggL7o6Prx2VcdKp5cYceHznW8,1065
+msgmodel-3.2.1.dist-info/METADATA,sha256=dKgvkIktNDDDTjrmwu5nCGfU1t8DQiMOMjlreNtRshk,13163
+msgmodel-3.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+msgmodel-3.2.1.dist-info/entry_points.txt,sha256=TmynPfL2ClRVbo5lQjijdNuNxFSQrGFmn3BGFRteb6I,52
+msgmodel-3.2.1.dist-info/top_level.txt,sha256=IGJ3DqDqBj44i1BReNf1BxtpT86Wx9HGC4aURDsfFS8,9
+msgmodel-3.2.1.dist-info/RECORD,,

msgmodel-3.2.1.dist-info/WHEEL

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

msgmodel-3.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+msgmodel = msgmodel.__main__:main

msgmodel-3.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Leo Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

msgmodel-3.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+msgmodel