risk-mirror 1.0.0__py3-none-any.whl

risk_mirror/__init__.py

@@ -0,0 +1,28 @@
+"""
+Risk Mirror SDK - Python
+========================
+Deterministic, stateless AI safety toolkit
+
+US-0001 to US-0020: SDKs (JS/Python) feature
+"""
+from .client import RiskMirror, RiskMirrorError
+from .types import (
+    ScanResponse,
+    ScanPolicy,
+    Finding,
+    AuditSummary,
+    Verdict,
+    Severity,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "RiskMirror",
+    "RiskMirrorError",
+    "ScanResponse",
+    "ScanPolicy",
+    "Finding",
+    "AuditSummary",
+    "Verdict",
+    "Severity",
+]

risk_mirror/client.py

@@ -0,0 +1,346 @@
+"""
+Risk Mirror SDK - Python Client
+================================
+Deterministic, stateless AI safety toolkit
+Drop-in integration for prompt security
+
+US-0001: Core Behavior
+US-0002: Policy Controls
+US-0006: Edge Cases
+US-0007: Performance
+US-0008: Security
+US-0009: Audit Evidence
+US-0010: Privacy (no storage)
+US-0011: Compliance
+US-0012: Rate Limits
+US-0013: Logging
+US-0015: Rollback
+US-0020: Error Handling
+"""
+import time
+import logging
+from typing import Optional, Callable, Dict, Any
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError, URLError
+import json
+
+from .types import ScanResponse, ScanPolicy, OptimizeResponse, Verdict
+
+# Constants
+DEFAULT_BASE_URL = "https://risk-mirror-auth.anonymous617461746174.workers.dev"
+DEFAULT_TIMEOUT = 30
+DEFAULT_RETRIES = 3
+SDK_VERSION = "1.0.0"
+ENGINE_VERSION = "6.0-ULTRA"
+
+logger = logging.getLogger("risk_mirror")
+
+
+class RiskMirrorError(Exception):
+    """Base exception for Risk Mirror SDK.
+    
+    US-0020: Error Handling
+    """
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        retryable: bool = False,
+        status_code: Optional[int] = None
+    ):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        self.status_code = status_code
+
+
+class RiskMirror:
+    """
+    Risk Mirror SDK Client
+    ======================
+    Deterministic AI safety scanning with zero content storage.
+    
+    Example:
+        >>> client = RiskMirror(api_key="your-key")
+        >>> result = client.scan("Check this prompt for safety")
+        >>> print(result.verdict)
+        'SAFE'
+    
+    US-0001: Core Behavior
+    """
+    
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        debug: bool = False,
+    ):
+        """
+        Initialize the Risk Mirror client.
+        
+        Args:
+            base_url: API base URL
+            api_key: Optional API key for authentication
+            timeout: Request timeout in seconds
+            retries: Number of retries on failure
+            debug: Enable debug logging
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.retries = retries
+        self.debug = debug
+        self._telemetry_callback: Optional[Callable[[Dict[str, Any]], None]] = None
+        
+        if debug:
+            logging.basicConfig(level=logging.DEBUG)
+    
+    def on_telemetry(self, callback: Callable[[Dict[str, Any]], None]) -> None:
+        """
+        Set telemetry callback (receives no content, only metadata).
+        
+        US-0018: Analytics without storing content
+        """
+        self._telemetry_callback = callback
+    
+    def _log(self, msg: str, *args: Any) -> None:
+        if self.debug:
+            logger.debug(f"[RiskMirror] {msg}", *args)
+    
+    def _request(
+        self,
+        endpoint: str,
+        method: str = "POST",
+        body: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Make HTTP request with retry logic.
+        
+        US-0012: Rate Limits
+        US-0020: Error Handling
+        """
+        url = f"{self.base_url}{endpoint}"
+        headers = {
+            "Content-Type": "application/json",
+            "X-SDK-Version": SDK_VERSION,
+        }
+        
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        
+        last_error: Optional[Exception] = None
+        
+        for attempt in range(self.retries + 1):
+            try:
+                self._log(f"Request attempt {attempt + 1}: {method} {endpoint}")
+                
+                data = json.dumps(body).encode("utf-8") if body else None
+                req = Request(url, data=data, headers=headers, method=method)
+                
+                with urlopen(req, timeout=self.timeout) as response:
+                    return json.loads(response.read().decode("utf-8"))
+                    
+            except HTTPError as e:
+                last_error = e
+                
+                # US-0012: Rate limit handling
+                if e.code == 429:
+                    retry_after = e.headers.get("Retry-After", "1")
+                    wait_secs = int(retry_after)
+                    self._log(f"Rate limited, waiting {wait_secs}s")
+                    time.sleep(wait_secs)
+                    continue
+                
+                # Retryable server errors
+                if e.code >= 500 and attempt < self.retries:
+                    wait_secs = min(2 ** attempt, 10)
+                    self._log(f"Server error {e.code}, retry in {wait_secs}s")
+                    time.sleep(wait_secs)
+                    continue
+                
+                raise RiskMirrorError(
+                    code="API_ERROR",
+                    message=f"API returned {e.code}: {e.read().decode('utf-8', errors='ignore')}",
+                    retryable=e.code >= 500,
+                    status_code=e.code
+                )
+                
+            except URLError as e:
+                last_error = e
+                if attempt < self.retries:
+                    wait_secs = min(2 ** attempt, 10)
+                    self._log(f"Network error, retry in {wait_secs}s: {e.reason}")
+                    time.sleep(wait_secs)
+                    continue
+                raise RiskMirrorError(
+                    code="NETWORK_ERROR",
+                    message=str(e.reason),
+                    retryable=True
+                )
+            except Exception as e:
+                last_error = e
+                raise RiskMirrorError(
+                    code="UNKNOWN_ERROR",
+                    message=str(e),
+                    retryable=False
+                )
+        
+        raise last_error or RiskMirrorError("UNKNOWN_ERROR", "Request failed", False)
+    
+    def scan(
+        self,
+        input_text: str,
+        policy: Optional[ScanPolicy] = None,
+        mode: str = "default"
+    ) -> ScanResponse:
+        """
+        Scan input for safety issues.
+        
+        US-0001: Core behavior - deterministic scanning
+        US-0002: Policy controls - configurable detection
+        US-0010: Privacy - no content storage
+        
+        Args:
+            input_text: Text to scan
+            policy: Optional policy configuration
+            mode: Scan mode (default, strict, paranoid)
+        
+        Returns:
+            ScanResponse with verdict, findings, and safe_output
+        
+        Raises:
+            RiskMirrorError: On validation or API errors
+        """
+        start = time.perf_counter()
+        
+        # US-0006: Edge cases - input validation
+        if not input_text or not isinstance(input_text, str):
+            raise RiskMirrorError(
+                code="INVALID_INPUT",
+                message="Input must be a non-empty string",
+                retryable=False
+            )
+        
+        # US-0008: Security - size limit
+        max_length = policy.max_length if policy else 100000
+        if len(input_text) > max_length:
+            raise RiskMirrorError(
+                code="INPUT_TOO_LARGE",
+                message=f"Input exceeds maximum length of {max_length} characters",
+                retryable=False
+            )
+        
+        # Build request
+        policy = policy or ScanPolicy()
+        request_body = {
+            "prompt": input_text,
+            "policy": {
+                "detect_pii": policy.pii,
+                "detect_secrets": policy.secrets,
+                "detect_injection": policy.injection,
+            },
+        }
+        
+        if policy.pii_classes:
+            request_body["policy"]["pii_classes"] = policy.pii_classes
+        
+        response_data = self._request("/firewall/audit", "POST", request_body)
+        
+        latency_ms = (time.perf_counter() - start) * 1000
+        response_data["latency_ms"] = latency_ms
+        response_data["privacy"] = {"stateless": True, "content_logged": False}
+        
+        # US-0018: Analytics telemetry (no content)
+        if self._telemetry_callback:
+            self._telemetry_callback({
+                "operation": "scan",
+                "verdict": response_data.get("verdict", "SAFE"),
+                "findings_count": len(response_data.get("findings", [])),
+                "latency_ms": latency_ms,
+                "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            })
+        
+        return ScanResponse.from_dict(response_data)
+    
+    def audit(
+        self,
+        input_text: str,
+        policy: Optional[ScanPolicy] = None
+    ) -> ScanResponse:
+        """
+        Audit scan for compliance reporting.
+        
+        US-0009: Audit Evidence
+        
+        Args:
+            input_text: Text to audit
+            policy: Optional policy configuration
+        
+        Returns:
+            ScanResponse with detailed audit evidence
+        """
+        return self.scan(input_text, policy, mode="strict")
+    
+    def optimize(
+        self,
+        input_text: str,
+        mode: str = "compress"
+    ) -> OptimizeResponse:
+        """
+        Optimize prompt for token efficiency.
+        
+        Args:
+            input_text: Text to optimize
+            mode: compress, refine, or strip
+        
+        Returns:
+            OptimizeResponse with optimized text
+        """
+        if not input_text or not isinstance(input_text, str):
+            raise RiskMirrorError(
+                code="INVALID_INPUT",
+                message="Input must be a non-empty string",
+                retryable=False
+            )
+        
+        response_data = self._request("/optimize/prompt", "POST", {
+            "prompt": input_text,
+            "mode": mode,
+        })
+        
+        return OptimizeResponse.from_dict(response_data)
+    
+    def get_version(self) -> Dict[str, str]:
+        """
+        Get SDK and engine version.
+        
+        US-0015: Rollback - version tracking
+        """
+        return {
+            "sdk": SDK_VERSION,
+            "engine": ENGINE_VERSION,
+        }
+
+
+# ============ Quick Helpers ============
+_default_client: Optional[RiskMirror] = None
+
+
+def configure(**kwargs: Any) -> None:
+    """Configure the default client."""
+    global _default_client
+    _default_client = RiskMirror(**kwargs)
+
+
+def scan(
+    input_text: str,
+    policy: Optional[ScanPolicy] = None,
+    mode: str = "default"
+) -> ScanResponse:
+    """Quick scan using default client."""
+    global _default_client
+    if _default_client is None:
+        _default_client = RiskMirror()
+    return _default_client.scan(input_text, policy, mode)

risk_mirror/types.py

@@ -0,0 +1,135 @@
+"""
+Risk Mirror SDK - Type Definitions
+==================================
+Dataclasses for SDK request/response models
+
+US-0004: API Surface
+US-0005: Data Model
+"""
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any, Literal
+from enum import Enum
+
+
+class Verdict(str, Enum):
+    SAFE = "SAFE"
+    REVIEW = "REVIEW"
+    HIGH_RISK = "HIGH_RISK"
+
+
+class Severity(str, Enum):
+    LOW = "LOW"
+    MED = "MED"
+    HIGH = "HIGH"
+
+
+@dataclass
+class Finding:
+    """A single finding from the scan."""
+    category: str
+    severity: Severity
+    count: int
+    match: Optional[str] = None
+
+
+@dataclass
+class AuditSummary:
+    """Summary of modifications made."""
+    phrases_removed: int = 0
+    pii_redacted: int = 0
+    secrets_masked: int = 0
+    injections_blocked: int = 0
+
+
+@dataclass
+class ScanPolicy:
+    """Configuration for scan behavior.
+    
+    US-0002: Policy Controls
+    """
+    pii: bool = True
+    secrets: bool = True
+    injection: bool = True
+    pii_classes: Optional[List[str]] = None
+    max_length: int = 100000
+
+
+@dataclass
+class Privacy:
+    """Privacy guarantees."""
+    stateless: bool = True
+    content_logged: bool = False
+
+
+@dataclass
+class ScanResponse:
+    """Response from scan operation.
+    
+    US-0009: Audit Evidence
+    US-0010: Privacy
+    US-0011: Compliance
+    """
+    verdict: Verdict
+    findings: List[Finding]
+    safe_output: str
+    audit_summary: AuditSummary
+    policy_hash: str
+    engine_version: str
+    latency_ms: float
+    privacy: Optional[Privacy] = None
+    compliance_tags: List[str] = field(default_factory=list)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ScanResponse":
+        """Create ScanResponse from API response dict."""
+        findings = [
+            Finding(
+                category=f.get("category", "unknown"),
+                severity=Severity(f.get("severity", "LOW")),
+                count=f.get("count", 1),
+                match=f.get("match"),
+            )
+            for f in data.get("findings", [])
+        ]
+        
+        audit_data = data.get("audit_summary", {})
+        audit_summary = AuditSummary(
+            phrases_removed=audit_data.get("phrases_removed", 0),
+            pii_redacted=audit_data.get("pii_redacted", 0),
+            secrets_masked=audit_data.get("secrets_masked", 0),
+            injections_blocked=audit_data.get("injections_blocked", 0),
+        )
+        
+        privacy_data = data.get("privacy")
+        privacy = Privacy(
+            stateless=privacy_data.get("stateless", True),
+            content_logged=privacy_data.get("content_logged", False),
+        ) if privacy_data else Privacy()
+        
+        return cls(
+            verdict=Verdict(data.get("verdict", "SAFE")),
+            findings=findings,
+            safe_output=data.get("safe_output", ""),
+            audit_summary=audit_summary,
+            policy_hash=data.get("policy_hash", ""),
+            engine_version=data.get("engine_version", "6.0-ULTRA"),
+            latency_ms=data.get("latency_ms", 0.0),
+            privacy=privacy,
+            compliance_tags=data.get("compliance_tags", []),
+        )
+
+
+@dataclass
+class OptimizeResponse:
+    """Response from optimize operation."""
+    optimized: str
+    tokens_saved: int
+    compression_ratio: float
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "OptimizeResponse":
+        return cls(
+            optimized=data.get("optimized", ""),
+            tokens_saved=data.get("tokens_saved", 0),
+            compression_ratio=data.get("compression_ratio", 1.0),
+        )

risk_mirror-1.0.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: risk-mirror
+Version: 1.0.0
+Summary: Deterministic AI Safety Toolkit - Python SDK
+Home-page: https://github.com/myProjectsRavi/risk-mirror-core
+Author: RTN Labs
+Author-email: support@risk-mirror.com
+Keywords: ai-safety,pii,secrets,prompt-security,deterministic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# Risk Mirror SDK - Python
+
+Deterministic AI Safety Toolkit for prompt security.
+
+## Installation
+
+```bash
+pip install risk-mirror
+```
+
+## Quick Start
+
+```python
+from risk_mirror import RiskMirror
+
+# Initialize client
+client = RiskMirror(api_key="your-api-key")
+
+# Scan for safety issues
+result = client.scan("Check this text for PII and secrets")
+
+print(result.verdict)  # SAFE, REVIEW, or HIGH_RISK
+print(result.findings)  # List of findings
+print(result.safe_output)  # Redacted text
+```
+
+## Features
+
+- **PII Detection**: Email, phone, SSN, etc.
+- **Secrets Detection**: API keys, tokens, passwords
+- **Injection Detection**: Prompt injection attempts
+- **Zero Storage**: No content is stored
+- **Deterministic**: Same input = same output
+
+## License
+
+MIT

risk_mirror-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+risk_mirror/__init__.py,sha256=-rkpepWwQeJ8LLYUNg8xwWIUYrZ0g7q6jAuOHw5vVbE,492
+risk_mirror/client.py,sha256=Cge24tZukgPYKHQASYlDuAhkoxxrALHyk54ar4uJ4ME,10764
+risk_mirror/types.py,sha256=-QLCxNTRBGXR8cSHrDRl7Z97sPfU2OaM7SXB3wZtU0Q,3599
+risk_mirror-1.0.0.dist-info/METADATA,sha256=GarpjZrNHW-ci8hXsNyp44IcZLT7XJ-TG2-ui_FoSQk,2066
+risk_mirror-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+risk_mirror-1.0.0.dist-info/top_level.txt,sha256=BtKjDWugw6OoRR_DSXHJ0qxiqQxcul69MFko0szkZ-I,12
+risk_mirror-1.0.0.dist-info/RECORD,,

risk_mirror-1.0.0.dist-info/WHEEL

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

risk_mirror-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+risk_mirror