rairos 0.2.0__tar.gz

rairos-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: rairos
+Version: 0.2.0
+Summary: Python SDK for Rairos API
+Author-email: Rairos Team <team@rairos.ai>
+License: MIT
+Project-URL: Homepage, https://rairos.ai
+Project-URL: Documentation, https://docs.rairos.ai
+Project-URL: Repository, https://github.com/shushuzn/Rairos
+Project-URL: Changelog, https://github.com/shushuzn/Rairos/blob/main/sdks/python/CHANGELOG.md
+Keywords: rairos,api,research,ai
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: urllib3>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# Rairos Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/rairos.svg)](https://pypi.org/project/rairos/)
+[![Python versions](https://img.shields.io/pypi/pyversions/rairos.svg)](https://pypi.org/project/rairos/)
+[![License](https://img.shields.io/pypi/l/rairos.svg)](https://github.com/shushuzn/Rairos/blob/main/sdks/python/pyproject.toml)
+
+Python SDK for the Rairos API platform.
+
+## Installation
+
+```bash
+# From PyPI (coming soon)
+pip install rairos
+
+# From source
+cd sdks/python && pip install -e . && cd ../..
+```
+
+## Quick Start
+
+```python
+from rairos import RairosClient
+
+# Initialize client
+client = RairosClient(api_key="your_api_key_here")
+
+# Search papers
+results = client.search_papers(query="machine learning", page=1, per_page=20)
+print(results)
+
+# Detect research gaps (requires Pro tier)
+gaps = client.detect_gap(query="neural network architecture")
+print(gaps)
+
+# Get usage statistics
+usage = client.get_usage()
+print(usage)
+```
+
+## Authentication
+
+You can provide your API key in three ways:
+
+1. **Environment variable** (recommended):
+   ```bash
+   export RAIROS_API_KEY=your_api_key_here
+   ```
+
+2. **Constructor parameter**:
+   ```python
+   client = RairosClient(api_key="your_api_key_here")
+   ```
+
+3. **Register/Login** to get a new API key:
+   ```python
+   # Register
+   auth = client.register(email="user@example.com", password="secure_password")
+
+   # Login
+   auth = client.login(email="user@example.com", password="secure_password")
+   print(auth["api_key"])  # Use this key
+   ```
+
+## API Reference
+
+### Papers
+
+```python
+# Search papers
+results = client.search_papers(query="quantum computing")
+
+# Get specific paper
+paper = client.get_paper(paper_id="uuid-here")
+```
+
+### Gap Detection (Pro tier)
+
+```python
+# Detect research gaps
+gaps = client.detect_gap(
+    query="What are the gaps in transformer architecture research?",
+    categories=["cs.AI", "cs.LG"]
+)
+```
+
+### Research (Team tier)
+
+```python
+# Run automated research
+results = client.run_research(
+    query="Analyze the state of AI safety research in 2025"
+)
+```
+
+### Subscriptions
+
+```python
+# Get available tiers
+tiers = client.get_tiers()
+
+# Create checkout session
+checkout = client.create_checkout(
+    price_id="price_pro_monthly",
+    success_url="https://yourapp.com/success",
+    cancel_url="https://yourapp.com/pricing"
+)
+print(checkout["checkout_url"])  # Redirect user to this URL
+
+# Get subscription status
+status = client.get_subscription_status()
+```
+
+## Error Handling
+
+```python
+from rairos import (
+    RairosClient,
+    RairosError,
+    AuthenticationError,
+    RateLimitError
+)
+
+try:
+    client = RairosClient(api_key="invalid_key")
+    results = client.search_papers(query="test")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limit exceeded - wait and retry")
+except RairosError as e:
+    print(f"API error: {e.message}")
+```
+
+## License
+
+MIT License

rairos-0.2.0/README.md

@@ -0,0 +1,136 @@
+# Rairos Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/rairos.svg)](https://pypi.org/project/rairos/)
+[![Python versions](https://img.shields.io/pypi/pyversions/rairos.svg)](https://pypi.org/project/rairos/)
+[![License](https://img.shields.io/pypi/l/rairos.svg)](https://github.com/shushuzn/Rairos/blob/main/sdks/python/pyproject.toml)
+
+Python SDK for the Rairos API platform.
+
+## Installation
+
+```bash
+# From PyPI (coming soon)
+pip install rairos
+
+# From source
+cd sdks/python && pip install -e . && cd ../..
+```
+
+## Quick Start
+
+```python
+from rairos import RairosClient
+
+# Initialize client
+client = RairosClient(api_key="your_api_key_here")
+
+# Search papers
+results = client.search_papers(query="machine learning", page=1, per_page=20)
+print(results)
+
+# Detect research gaps (requires Pro tier)
+gaps = client.detect_gap(query="neural network architecture")
+print(gaps)
+
+# Get usage statistics
+usage = client.get_usage()
+print(usage)
+```
+
+## Authentication
+
+You can provide your API key in three ways:
+
+1. **Environment variable** (recommended):
+   ```bash
+   export RAIROS_API_KEY=your_api_key_here
+   ```
+
+2. **Constructor parameter**:
+   ```python
+   client = RairosClient(api_key="your_api_key_here")
+   ```
+
+3. **Register/Login** to get a new API key:
+   ```python
+   # Register
+   auth = client.register(email="user@example.com", password="secure_password")
+
+   # Login
+   auth = client.login(email="user@example.com", password="secure_password")
+   print(auth["api_key"])  # Use this key
+   ```
+
+## API Reference
+
+### Papers
+
+```python
+# Search papers
+results = client.search_papers(query="quantum computing")
+
+# Get specific paper
+paper = client.get_paper(paper_id="uuid-here")
+```
+
+### Gap Detection (Pro tier)
+
+```python
+# Detect research gaps
+gaps = client.detect_gap(
+    query="What are the gaps in transformer architecture research?",
+    categories=["cs.AI", "cs.LG"]
+)
+```
+
+### Research (Team tier)
+
+```python
+# Run automated research
+results = client.run_research(
+    query="Analyze the state of AI safety research in 2025"
+)
+```
+
+### Subscriptions
+
+```python
+# Get available tiers
+tiers = client.get_tiers()
+
+# Create checkout session
+checkout = client.create_checkout(
+    price_id="price_pro_monthly",
+    success_url="https://yourapp.com/success",
+    cancel_url="https://yourapp.com/pricing"
+)
+print(checkout["checkout_url"])  # Redirect user to this URL
+
+# Get subscription status
+status = client.get_subscription_status()
+```
+
+## Error Handling
+
+```python
+from rairos import (
+    RairosClient,
+    RairosError,
+    AuthenticationError,
+    RateLimitError
+)
+
+try:
+    client = RairosClient(api_key="invalid_key")
+    results = client.search_papers(query="test")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limit exceeded - wait and retry")
+except RairosError as e:
+    print(f"API error: {e.message}")
+```
+
+## License
+
+MIT License

rairos-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rairos"
+version = "0.2.0"
+description = "Python SDK for Rairos API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Rairos Team", email = "team@rairos.ai"}
+]
+keywords = ["rairos", "api", "research", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "urllib3>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://rairos.ai"
+Documentation = "https://docs.rairos.ai"
+Repository = "https://github.com/shushuzn/Rairos"
+Changelog = "https://github.com/shushuzn/Rairos/blob/main/sdks/python/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["rairos*"]
+
+[tool.black]
+line-length = 88
+target-version = ['py38', 'py39', 'py310', 'py311']
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true

rairos-0.2.0/rairos/__init__.py

@@ -0,0 +1,32 @@
+"""Rairos API Python SDK
+
+A Python SDK for the Rairos API platform.
+"""
+
+__version__ = "0.2.0"
+
+from .client import RairosClient
+from .exceptions import (
+    RairosError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    NotFoundError,
+    ForbiddenError,
+    ServerError,
+    PaymentError,
+    raise_from_response,
+)
+
+__all__ = [
+    "RairosClient",
+    "RairosError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "ForbiddenError",
+    "ServerError",
+    "PaymentError",
+    "raise_from_response",
+]

rairos-0.2.0/rairos/client.py

@@ -0,0 +1,392 @@
+"""Rairos API Client
+
+Main client for interacting with the Rairos API.
+"""
+
+import os
+import time
+from typing import Optional, Dict, Any, List
+from .exceptions import (
+    RairosError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    NotFoundError,
+    ForbiddenError,
+    ServerError,
+    PaymentError,
+    raise_from_response,
+)
+
+
+class RairosClient:
+    """Python SDK for Rairos API.
+
+    Example:
+        >>> client = RairosClient(api_key="your-api-key")
+        >>> usage = client.get_usage()
+        >>> papers = client.search_papers(query="machine learning")
+    """
+
+    BASE_URL = os.environ.get("RAIROS_API_URL", "https://api.rairos.ai/api/v1")
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        timeout: Optional[int] = 30
+    ):
+        """Initialize the Rairos client.
+
+        Args:
+            api_key: Your Rairos API key. If not provided, will look for RAIROS_API_KEY env var.
+            max_retries: Maximum number of retries for failed requests (default: 3)
+            retry_delay: Initial delay between retries in seconds (default: 1.0)
+            timeout: Request timeout in seconds (default: 30)
+        """
+        self.api_key = api_key or os.environ.get("RAIROS_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError("API key is required. Pass api_key or set RAIROS_API_KEY env var.")
+
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.timeout = timeout
+
+    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
+        """Make an HTTP request to the Rairos API with automatic retry.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            **kwargs: Additional arguments passed to requests.request
+
+        Returns:
+            Parsed JSON response
+
+        Raises:
+            AuthenticationError: If API key is invalid
+            RateLimitError: If rate limit is exceeded
+            RairosError: For other errors
+        """
+        import requests
+        from requests.adapters import HTTPAdapter
+        from urllib3.util.retry import Retry
+
+        url = f"{self.BASE_URL}{endpoint}"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        headers.update(kwargs.pop("headers", {}))
+
+        timeout = kwargs.pop("timeout", self.timeout)
+
+        session = requests.Session()
+        retry_strategy = Retry(
+            total=self.max_retries,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["HEAD", "GET", "OPTIONS", "POST"],
+            raise_on_status=False
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        session.mount("http://", adapter)
+        session.mount("https://", adapter)
+
+        try:
+            response = session.request(
+                method,
+                url,
+                headers=headers,
+                timeout=timeout,
+                **kwargs
+            )
+
+            if response.status_code == 401:
+                raise AuthenticationError(
+                    "Invalid or expired API key",
+                    details={"endpoint": endpoint}
+                )
+
+            if response.status_code == 429:
+                error_data = {}
+                try:
+                    error_data = response.json()
+                except ValueError:
+                    pass
+
+                limit = error_data.get("error", {}).get("limit")
+                reset_at = error_data.get("error", {}).get("reset_at")
+
+                raise RateLimitError(
+                    "Rate limit exceeded. Please retry after the reset time.",
+                    limit=limit,
+                    reset_at=reset_at,
+                    details=error_data
+                )
+
+            if not response.ok:
+                error_data = {}
+                try:
+                    error_data = response.json()
+                except ValueError:
+                    error_data = {"error": {"message": response.text or "Unknown error"}}
+
+                raise_from_response(response.status_code, error_data)
+
+            if response.content:
+                return response.json()
+            return {}
+
+        except requests.exceptions.Timeout:
+            raise RairosError(
+                f"Request timed out after {timeout}s: {endpoint}",
+                code="TIMEOUT",
+                details={"endpoint": endpoint, "timeout": timeout}
+            )
+        except requests.exceptions.ConnectionError as e:
+            raise RairosError(
+                f"Connection failed: {str(e)}",
+                code="CONNECTION_ERROR",
+                details={"endpoint": endpoint}
+            )
+        except RairosError:
+            raise
+        except Exception as e:
+            raise RairosError(
+                f"Request failed: {str(e)}",
+                code="UNKNOWN_ERROR",
+                details={"endpoint": endpoint, "error": str(e)}
+            )
+
+    # Authentication
+    def register(self, email: str, password: str) -> Dict[str, Any]:
+        """Register a new user.
+
+        Args:
+            email: User email
+            password: User password (min 8 characters)
+
+        Returns:
+            Auth response with user_id and API key
+
+        Raises:
+            ValidationError: If email or password is invalid
+        """
+        return self._request(
+            "POST",
+            "/auth/register",
+            json={"email": email, "password": password}
+        )
+
+    def login(self, email: str, password: str) -> Dict[str, Any]:
+        """Login and get a new API key.
+
+        Args:
+            email: User email
+            password: User password
+
+        Returns:
+            Auth response with user_id and API key
+        """
+        return self._request(
+            "POST",
+            "/auth/login",
+            json={"email": email, "password": password}
+        )
+
+    # API Keys
+    def list_keys(self) -> List[Dict[str, Any]]:
+        """List all API keys for the current user.
+
+        Returns:
+            List of API key objects
+        """
+        return self._request("GET", "/keys")
+
+    def create_key(self, name: Optional[str] = None) -> Dict[str, Any]:
+        """Create a new API key.
+
+        Args:
+            name: Optional name for the key
+
+        Returns:
+            New API key details including the raw key (only shown once)
+        """
+        return self._request(
+            "POST",
+            "/keys",
+            json={"name": name} if name else {}
+        )
+
+    def rotate_key(
+        self,
+        key_id: str,
+        grace_period_hours: int = 24
+    ) -> Dict[str, Any]:
+        """Rotate an API key with a grace period.
+
+        The old key remains valid during the grace period.
+
+        Args:
+            key_id: ID of the key to rotate
+            grace_period_hours: Hours until old key expires (default: 24)
+
+        Returns:
+            New key details and old key expiration time
+        """
+        return self._request(
+            "POST",
+            "/keys/rotate",
+            json={
+                "key_id": key_id,
+                "grace_period_hours": grace_period_hours
+            }
+        )
+
+    # Usage
+    def get_usage(self) -> Dict[str, Any]:
+        """Get current API usage statistics.
+
+        Returns:
+            Usage statistics including tier, requests used/remaining
+        """
+        return self._request("GET", "/usage")
+
+    def get_usage_dashboard(self) -> Dict[str, Any]:
+        """Get detailed usage dashboard with breakdowns.
+
+        Returns:
+            Detailed usage stats including endpoint breakdown and trends
+        """
+        return self._request("GET", "/usage/dashboard")
+
+    # Papers
+    def search_papers(
+        self,
+        query: Optional[str] = None,
+        page: int = 1,
+        per_page: int = 20
+    ) -> Dict[str, Any]:
+        """Search papers.
+
+        Args:
+            query: Search query (searches title and abstract)
+            page: Page number (default: 1)
+            per_page: Results per page (default: 20, max: 100)
+
+        Returns:
+            Paginated paper results
+        """
+        params = {"page": page, "per_page": per_page}
+        if query:
+            params["q"] = query
+
+        return self._request("GET", "/papers/search", params=params)
+
+    def get_paper(self, paper_id: str) -> Dict[str, Any]:
+        """Get a specific paper by ID.
+
+        Args:
+            paper_id: Paper UUID
+
+        Returns:
+            Paper details
+        """
+        return self._request("GET", f"/papers/{paper_id}")
+
+    # Gap Detection (Pro+)
+    def detect_gap(self, query: str, **kwargs) -> Dict[str, Any]:
+        """Detect research gaps for a query. Requires Pro tier or higher.
+
+        Args:
+            query: Research query to analyze
+            **kwargs: Additional parameters for gap detection
+
+        Returns:
+            Gap detection results with identified gaps
+
+        Raises:
+            ForbiddenError: If tier is insufficient
+        """
+        return self._request(
+            "POST",
+            "/gap/detect",
+            json={"query": query, **kwargs}
+        )
+
+    # Research (Team+)
+    def run_research(self, query: str, **kwargs) -> Dict[str, Any]:
+        """Run automated research. Requires Team tier or higher.
+
+        Args:
+            query: Research query
+            **kwargs: Additional parameters for research
+
+        Returns:
+            Research results
+
+        Raises:
+            ForbiddenError: If tier is insufficient
+        """
+        return self._request(
+            "POST",
+            "/research/run",
+            json={"query": query, **kwargs}
+        )
+
+    # Subscriptions
+    def get_tiers(self) -> Dict[str, Any]:
+        """Get available subscription tiers.
+
+        Returns:
+            List of available tiers with pricing
+        """
+        return self._request("GET", "/tiers")
+
+    def create_checkout(
+        self,
+        price_id: str,
+        success_url: str = "https://rairos.ai/success",
+        cancel_url: str = "https://rairos.ai/pricing"
+    ) -> Dict[str, Any]:
+        """Create a Stripe checkout session for subscription.
+
+        Args:
+            price_id: Stripe price ID for the tier
+            success_url: URL to redirect on success
+            cancel_url: URL to redirect on cancel
+
+        Returns:
+            Checkout URL and session ID
+        """
+        return self._request(
+            "POST",
+            "/subscription/checkout",
+            json={
+                "price_id": price_id,
+                "success_url": success_url,
+                "cancel_url": cancel_url
+            }
+        )
+
+    def create_portal(self, return_url: str = "https://rairos.ai/dashboard") -> Dict[str, Any]:
+        """Create a Stripe customer portal session.
+
+        Args:
+            return_url: URL to redirect after using the portal
+
+        Returns:
+            Portal URL
+        """
+        return self._request(
+            "POST",
+            "/subscription/portal",
+            json={"return_url": return_url}
+        )
+
+    def get_subscription_status(self) -> Dict[str, Any]:
+        """Get current subscription status.
+
+        Returns:
+            Subscription status including tier and Stripe info
+        """
+        return self._request("GET", "/subscription/status")

rairos-0.2.0/rairos/exceptions.py

@@ -0,0 +1,181 @@
+"""Rairos SDK Exceptions."""
+
+from datetime import datetime
+from typing import Optional
+
+
+class RairosError(Exception):
+    """Base exception for Rairos SDK errors.
+
+    Attributes:
+        message: Error message
+        code: Error code (e.g., 'RATE_LIMITED', 'AUTH')
+        status_code: HTTP status code if available
+        details: Additional error details from API
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "ERROR",
+        status_code: Optional[int] = None,
+        details: Optional[dict] = None
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        if self.code != "ERROR":
+            return f"[{self.code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(RairosError):
+    """Raised when authentication fails (invalid or expired API key).
+
+    HTTP Status: 401
+    Error Codes: AUTH, INVALID_API_KEY, UNAUTHORIZED
+    """
+
+    def __init__(self, message: str = "Authentication failed", details: Optional[dict] = None):
+        super().__init__(message, code="AUTH", status_code=401, details=details)
+
+
+class RateLimitError(RairosError):
+    """Raised when rate limit is exceeded.
+
+    HTTP Status: 429
+    Error Code: RATE_LIMITED
+
+    Attributes:
+        limit: The rate limit that was exceeded
+        reset_at: When the rate limit will reset
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        limit: Optional[int] = None,
+        reset_at: Optional[datetime] = None,
+        details: Optional[dict] = None
+    ):
+        super().__init__(message, code="RATE_LIMITED", status_code=429, details=details)
+        self.limit = limit
+        self.reset_at = reset_at
+
+    def __str__(self) -> str:
+        parts = [f"[RATE_LIMITED] {self.message}"]
+        if self.limit:
+            parts.append(f"Limit: {self.limit}")
+        if self.reset_at:
+            parts.append(f"Resets at: {self.reset_at.isoformat()}")
+        return " | ".join(parts)
+
+
+class ValidationError(RairosError):
+    """Raised when request validation fails.
+
+    HTTP Status: 400
+    Error Codes: VALIDATION_ERROR, BAD_REQUEST
+    """
+
+    def __init__(self, message: str = "Validation failed", details: Optional[dict] = None):
+        super().__init__(message, code="VALIDATION_ERROR", status_code=400, details=details)
+
+
+class NotFoundError(RairosError):
+    """Raised when a resource is not found.
+
+    HTTP Status: 404
+    Error Codes: NOT_FOUND
+    """
+
+    def __init__(self, message: str = "Resource not found", details: Optional[dict] = None):
+        super().__init__(message, code="NOT_FOUND", status_code=404, details=details)
+
+
+class ForbiddenError(RairosError):
+    """Raised when access to a resource is forbidden (insufficient tier).
+
+    HTTP Status: 403
+    Error Codes: FORBIDDEN, INSUFFICIENT_PERMISSIONS
+    """
+
+    def __init__(self, message: str = "Access forbidden", details: Optional[dict] = None):
+        super().__init__(message, code="FORBIDDEN", status_code=403, details=details)
+
+
+class ServerError(RairosError):
+    """Raised when an internal server error occurs.
+
+    HTTP Status: 500+
+    Error Codes: INTERNAL_ERROR, DATABASE_ERROR, SERVER_ERROR
+    """
+
+    def __init__(self, message: str = "Internal server error", details: Optional[dict] = None):
+        super().__init__(message, code="SERVER_ERROR", status_code=500, details=details)
+
+
+class PaymentError(RairosError):
+    """Raised when a payment-related error occurs.
+
+    HTTP Status: 402
+    Error Codes: PAYMENT_ERROR
+    """
+
+    def __init__(self, message: str = "Payment error", details: Optional[dict] = None):
+        super().__init__(message, code="PAYMENT_ERROR", status_code=402, details=details)
+
+
+def parse_error_response(response_data: dict) -> tuple[str, dict]:
+    """Parse error response from API.
+
+    Returns:
+        Tuple of (error_code, error_details)
+    """
+    error = response_data.get("error", {})
+    code = error.get("code", "ERROR")
+    details = {
+        "limit": error.get("limit"),
+        "reset_at": error.get("reset_at"),
+    }
+    return code, details
+
+
+def raise_from_response(status_code: int, response_data: dict):
+    """Raise appropriate exception from API error response.
+
+    Args:
+        status_code: HTTP status code
+        response_data: Parsed JSON response
+
+    Raises:
+        Appropriate RairosError subclass
+    """
+    code, details = parse_error_response(response_data)
+    message = response_data.get("error", {}).get("message", "Unknown error")
+
+    error_mapping = {
+        400: (ValidationError, "VALIDATION_ERROR"),
+        401: (AuthenticationError, "AUTH"),
+        403: (ForbiddenError, "FORBIDDEN"),
+        404: (NotFoundError, "NOT_FOUND"),
+        402: (PaymentError, "PAYMENT_ERROR"),
+        429: (RateLimitError, "RATE_LIMITED"),
+    }
+
+    if status_code in error_mapping:
+        exc_class, expected_code = error_mapping[status_code]
+        if status_code == 429 and details.get("limit"):
+            reset_at_str = details.get("reset_at")
+            reset_at = datetime.fromisoformat(reset_at_str.replace("Z", "+00:00")) if reset_at_str else None
+            raise exc_class(message, limit=details["limit"], reset_at=reset_at, details=details)
+        raise exc_class(message, details=details)
+
+    if status_code >= 500:
+        raise ServerError(message, details=details)
+
+    raise RairosError(message, code=code, status_code=status_code, details=details)

rairos-0.2.0/rairos.egg-info/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: rairos
+Version: 0.2.0
+Summary: Python SDK for Rairos API
+Author-email: Rairos Team <team@rairos.ai>
+License: MIT
+Project-URL: Homepage, https://rairos.ai
+Project-URL: Documentation, https://docs.rairos.ai
+Project-URL: Repository, https://github.com/shushuzn/Rairos
+Project-URL: Changelog, https://github.com/shushuzn/Rairos/blob/main/sdks/python/CHANGELOG.md
+Keywords: rairos,api,research,ai
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: urllib3>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# Rairos Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/rairos.svg)](https://pypi.org/project/rairos/)
+[![Python versions](https://img.shields.io/pypi/pyversions/rairos.svg)](https://pypi.org/project/rairos/)
+[![License](https://img.shields.io/pypi/l/rairos.svg)](https://github.com/shushuzn/Rairos/blob/main/sdks/python/pyproject.toml)
+
+Python SDK for the Rairos API platform.
+
+## Installation
+
+```bash
+# From PyPI (coming soon)
+pip install rairos
+
+# From source
+cd sdks/python && pip install -e . && cd ../..
+```
+
+## Quick Start
+
+```python
+from rairos import RairosClient
+
+# Initialize client
+client = RairosClient(api_key="your_api_key_here")
+
+# Search papers
+results = client.search_papers(query="machine learning", page=1, per_page=20)
+print(results)
+
+# Detect research gaps (requires Pro tier)
+gaps = client.detect_gap(query="neural network architecture")
+print(gaps)
+
+# Get usage statistics
+usage = client.get_usage()
+print(usage)
+```
+
+## Authentication
+
+You can provide your API key in three ways:
+
+1. **Environment variable** (recommended):
+   ```bash
+   export RAIROS_API_KEY=your_api_key_here
+   ```
+
+2. **Constructor parameter**:
+   ```python
+   client = RairosClient(api_key="your_api_key_here")
+   ```
+
+3. **Register/Login** to get a new API key:
+   ```python
+   # Register
+   auth = client.register(email="user@example.com", password="secure_password")
+
+   # Login
+   auth = client.login(email="user@example.com", password="secure_password")
+   print(auth["api_key"])  # Use this key
+   ```
+
+## API Reference
+
+### Papers
+
+```python
+# Search papers
+results = client.search_papers(query="quantum computing")
+
+# Get specific paper
+paper = client.get_paper(paper_id="uuid-here")
+```
+
+### Gap Detection (Pro tier)
+
+```python
+# Detect research gaps
+gaps = client.detect_gap(
+    query="What are the gaps in transformer architecture research?",
+    categories=["cs.AI", "cs.LG"]
+)
+```
+
+### Research (Team tier)
+
+```python
+# Run automated research
+results = client.run_research(
+    query="Analyze the state of AI safety research in 2025"
+)
+```
+
+### Subscriptions
+
+```python
+# Get available tiers
+tiers = client.get_tiers()
+
+# Create checkout session
+checkout = client.create_checkout(
+    price_id="price_pro_monthly",
+    success_url="https://yourapp.com/success",
+    cancel_url="https://yourapp.com/pricing"
+)
+print(checkout["checkout_url"])  # Redirect user to this URL
+
+# Get subscription status
+status = client.get_subscription_status()
+```
+
+## Error Handling
+
+```python
+from rairos import (
+    RairosClient,
+    RairosError,
+    AuthenticationError,
+    RateLimitError
+)
+
+try:
+    client = RairosClient(api_key="invalid_key")
+    results = client.search_papers(query="test")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limit exceeded - wait and retry")
+except RairosError as e:
+    print(f"API error: {e.message}")
+```
+
+## License
+
+MIT License

rairos-0.2.0/rairos.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+rairos/__init__.py
+rairos/client.py
+rairos/exceptions.py
+rairos.egg-info/PKG-INFO
+rairos.egg-info/SOURCES.txt
+rairos.egg-info/dependency_links.txt
+rairos.egg-info/requires.txt
+rairos.egg-info/top_level.txt

rairos-0.2.0/rairos.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rairos-0.2.0/rairos.egg-info/requires.txt

@@ -0,0 +1,8 @@
+requests>=2.28.0
+urllib3>=2.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+black>=23.0.0
+mypy>=1.0.0

rairos-0.2.0/rairos.egg-info/top_level.txt

@@ -0,0 +1 @@
+rairos

rairos-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+