polari-sdk 0.2.0__py3-none-any.whl

polari/__init__.py

@@ -0,0 +1,95 @@
+"""Polari SDK - Official Python SDK for Polari API.
+
+Example:
+    >>> from polari import PolariClient, ArticleInput
+    >>>
+    >>> client = PolariClient(api_key="pk_...")
+    >>> article = ArticleInput(
+    ...     title="Breaking News",
+    ...     content="Article content here...",
+    ...     url="https://example.com/article"
+    ... )
+    >>> result = await client.layer0.analyze(article)
+    >>> print(f"Quality: {result.quality_score}")
+"""
+
+from .client import PolariClient
+from .config import PolariConfig
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    PolariAPIError,
+    PolariError,
+    ProcessingError,
+    RateLimitError,
+    RetryExhaustedError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from .types import (
+    # Input types
+    ArticleInput,
+    # Layer result types
+    Layer0Result,
+    Layer1Result,
+    # Layer 2 result types
+    ClusterResult,
+    ClusterBatchResult,
+    ClusterSummary,
+    ClusterStats,
+    ClusterMember,
+    # Shared types
+    HealthStatus,
+    Metrics,
+    CostSummary,
+    # Deprecated — retained for import compatibility, will be removed in v1.0
+    Layer2Result,
+    Layer3Result,
+    GraphNode,
+    GraphEdge,
+    Entity,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Main client
+    "PolariClient",
+    "PolariConfig",
+    # Input types
+    "ArticleInput",
+    # Layer 0 results
+    "Layer0Result",
+    # Layer 1 results
+    "Layer1Result",
+    # Layer 2 results
+    "ClusterResult",
+    "ClusterBatchResult",
+    "ClusterSummary",
+    "ClusterStats",
+    "ClusterMember",
+    # Shared types
+    "HealthStatus",
+    "Metrics",
+    "CostSummary",
+    # Exceptions
+    "PolariError",
+    "PolariAPIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "ServerError",
+    "NetworkError",
+    "TimeoutError",
+    "ConfigurationError",
+    "ProcessingError",
+    "RetryExhaustedError",
+    # Deprecated — will be removed in v1.0
+    "Layer2Result",
+    "Layer3Result",
+    "GraphNode",
+    "GraphEdge",
+    "Entity",
+]

polari/client.py

@@ -0,0 +1,190 @@
+"""Polari SDK main client."""
+
+import logging
+from typing import Optional
+
+import httpx
+
+from .config import PolariConfig
+from .exceptions import ConfigurationError
+from .layers.layer0 import Layer0
+from .types import CostSummary, HealthStatus, Metrics
+from .utils import CostTracker, MetricsCollector
+
+logger = logging.getLogger(__name__)
+
+
+class PolariClient:
+    """Main entry point for Polari SDK.
+
+    Example:
+        >>> client = PolariClient(api_key="pk_...")
+        >>> result = await client.layer0.analyze(article)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://localhost:8000",
+        timeout: int = 30,
+        max_retries: int = 3,
+        enable_metrics: bool = True,
+        enable_cost_tracking: bool = True,
+        log_level: str = "INFO",
+        **config_overrides,
+    ):
+        """Initialize Polari SDK client.
+
+        Args:
+            api_key: Polari API key
+            base_url: Base API URL (Layer 0). Layer 1-3 URLs come from config or defaults.
+            timeout: Request timeout in seconds
+            max_retries: Maximum retry attempts
+            enable_metrics: Enable performance metrics collection
+            enable_cost_tracking: Enable cost tracking
+            log_level: Logging level
+            **config_overrides: Additional config overrides (e.g. layer1_url, layer2_url)
+        """
+        logging.basicConfig(
+            level=getattr(logging, log_level.upper()),
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        )
+
+        self.config = PolariConfig(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            enable_metrics=enable_metrics,
+            enable_cost_tracking=enable_cost_tracking,
+            log_level=log_level,
+            **config_overrides,
+        )
+
+        self._metrics = MetricsCollector(enabled=enable_metrics)
+        self._cost_tracker = CostTracker(enabled=enable_cost_tracking)
+
+        self._http_client = httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "polari-sdk-python/0.2.0",
+            },
+            timeout=httpx.Timeout(
+                timeout=timeout,
+                connect=self.config.connect_timeout,
+                read=self.config.read_timeout,
+            ),
+        )
+
+        # Lazy-initialized layer instances
+        self._layer0 = None
+        self._layer1 = None
+        self._layer2 = None
+        self._layer3 = None
+
+    @property
+    def layer0(self) -> "Layer0":
+        """Layer 0: Token Intelligence (port 8003)."""
+        if self._layer0 is None:
+            from polari.layers.layer0 import Layer0
+            self._layer0 = Layer0(self)
+        return self._layer0
+
+    @property
+    def layer1(self):
+        """Layer 1: Semantic Analysis (port 8004)."""
+        if self._layer1 is None:
+            from polari.layers.layer1 import Layer1
+            layer1_url = getattr(self.config, "layer1_url", "http://localhost:8004")
+            self._layer1 = Layer1(self, base_url=layer1_url)
+        return self._layer1
+
+    @property
+    def layer2(self):
+        """Layer 2: Story Clustering (port 8005)."""
+        if self._layer2 is None:
+            from polari.layers.layer2 import Layer2
+            layer2_url = getattr(self.config, "layer2_url", "http://localhost:8005")
+            self._layer2 = Layer2(self, base_url=layer2_url)
+        return self._layer2
+
+    @property
+    def layer3(self):
+        """Layer 3: Intelligence Graph (port 8006)."""
+        if self._layer3 is None:
+            from polari.layers.layer3 import Layer3
+            layer3_url = getattr(self.config, "layer3_url", "http://localhost:8006")
+            self._layer3 = Layer3(self, base_url=layer3_url)
+        return self._layer3
+
+    async def health_check(self) -> HealthStatus:
+        """Check API health across all four layers concurrently.
+
+        Returns:
+            HealthStatus with per-layer results and overall status:
+                healthy  — all four layers responding
+                degraded — at least one layer responding
+                down     — no layers responding
+        """
+        import asyncio
+        import time
+
+        start = time.time()
+        results = await asyncio.gather(
+            self.layer0.health_check(),
+            self.layer1.health_check(),
+            self.layer2.health_check(),
+            self.layer3.health_check(),
+            return_exceptions=True,
+        )
+        layers_status = {
+            "layer0": results[0] is True,
+            "layer1": results[1] is True,
+            "layer2": results[2] is True,
+            "layer3": results[3] is True,
+        }
+        latency_ms = (time.time() - start) * 1000
+
+        if all(layers_status.values()):
+            status = "healthy"
+        elif any(layers_status.values()):
+            status = "degraded"
+        else:
+            status = "down"
+
+        return HealthStatus(status=status, layers=layers_status, latency_ms=latency_ms)
+
+
+    def get_metrics(self) -> Metrics:
+        """Get performance metrics."""
+        return self._metrics.get_metrics()
+
+    def get_cost_summary(self) -> CostSummary:
+        """Get API cost summary."""
+        return self._cost_tracker.get_cost_summary()
+
+    async def close(self) -> None:
+        """Close HTTP client and cleanup resources."""
+        await self._http_client.aclose()
+        logger.info("PolariClient closed")
+
+    async def __aenter__(self) -> "PolariClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    @classmethod
+    def from_env(cls, **overrides) -> "PolariClient":
+        """Create client from environment variables (POLARI_API_KEY)."""
+        config = PolariConfig.from_env(**overrides)
+        return cls(
+            api_key=config.api_key,
+            base_url=config.base_url,
+            timeout=config.timeout,
+            max_retries=config.max_retries,
+            enable_metrics=config.enable_metrics,
+            enable_cost_tracking=config.enable_cost_tracking,
+            log_level=config.log_level,
+        )

polari/config.py

@@ -0,0 +1,112 @@
+"""Configuration management for Polari SDK."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional, Tuple
+
+from .exceptions import ConfigurationError
+
+
+@dataclass
+class PolariConfig:
+    """SDK Configuration."""
+
+    # Authentication
+    api_key: str
+    base_url: str = "https://api.polariapi.com"
+    layer0_url: str = "https://layer0.api.polariapi.com"
+    layer1_url: str = "https://layer1.api.polariapi.com"
+    layer2_url: str = "https://layer2.api.polariapi.com"
+    layer3_url: str = "https://layer3.api.polariapi.com"
+    # Timeouts (seconds)
+    timeout: int = 30
+    connect_timeout: int = 10
+    read_timeout: int = 30
+
+    # Retry policy
+    max_retries: int = 3
+    retry_backoff_factor: float = 1.0
+    retry_statuses: Tuple[int, ...] = (429, 500, 502, 503, 504)
+
+    # Batch processing
+    default_batch_size: int = 10
+    max_batch_size: int = 50
+
+    # Features
+    enable_metrics: bool = True
+    enable_cost_tracking: bool = True
+    enable_caching: bool = False
+
+    # Logging
+    log_level: str = "INFO"
+    log_requests: bool = False
+    log_responses: bool = False
+
+    # Layer-specific thresholds
+    layer0_quality_threshold: float = 0.55
+    layer2_similarity_threshold: float = 0.7
+    layer2_min_cluster_size: int = 2
+
+    # Internal
+    _validated: bool = field(default=False, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        if not self._validated:
+            self._validate()
+            self._validated = True
+
+    def _validate(self) -> None:
+        """Validate configuration values."""
+        if not self.api_key:
+            raise ConfigurationError("API key is required")
+
+        if self.timeout <= 0:
+            raise ConfigurationError("Timeout must be positive")
+
+        if self.max_retries < 0:
+            raise ConfigurationError("Max retries cannot be negative")
+
+        if not 0.0 <= self.layer0_quality_threshold <= 1.0:
+            raise ConfigurationError("Quality threshold must be between 0 and 1")
+
+        if not 0.0 <= self.layer2_similarity_threshold <= 1.0:
+            raise ConfigurationError("Similarity threshold must be between 0 and 1")
+
+        if self.layer2_min_cluster_size < 2:
+            raise ConfigurationError("Min cluster size must be at least 2")
+
+        if self.default_batch_size > self.max_batch_size:
+            raise ConfigurationError("Default batch size cannot exceed max batch size")
+
+    @classmethod
+    def from_env(cls, **overrides: any) -> "PolariConfig":
+        """Load configuration from environment variables.
+
+        Args:
+            **overrides: Override specific config values
+
+        Returns:
+            PolariConfig instance
+
+        Environment Variables:
+            POLARI_API_KEY: API key (required)
+            POLARI_BASE_URL: Base API URL
+            POLARI_TIMEOUT: Request timeout in seconds
+            POLARI_MAX_RETRIES: Maximum retry attempts
+            POLARI_LOG_LEVEL: Logging level
+        """
+        api_key = os.getenv("POLARI_API_KEY")
+        if not api_key and "api_key" not in overrides:
+            raise ConfigurationError("POLARI_API_KEY environment variable not set")
+
+        return cls(
+            api_key=overrides.get("api_key", api_key or ""),
+            base_url=overrides.get("base_url", os.getenv("POLARI_BASE_URL", cls.base_url)),
+            timeout=int(overrides.get("timeout", os.getenv("POLARI_TIMEOUT", cls.timeout))),
+            max_retries=int(
+                overrides.get("max_retries", os.getenv("POLARI_MAX_RETRIES", cls.max_retries))
+            ),
+            log_level=overrides.get("log_level", os.getenv("POLARI_LOG_LEVEL", cls.log_level)),
+            **{k: v for k, v in overrides.items() if k not in ["api_key", "base_url", "timeout", "max_retries", "log_level"]},
+        )

polari/exceptions.py

@@ -0,0 +1,90 @@
+"""Polari SDK exception hierarchy."""
+
+from typing import Any, Dict, Optional
+
+
+class PolariError(Exception):
+    """Base exception for all Polari SDK errors."""
+
+    pass
+
+
+class PolariAPIError(PolariError):
+    """API returned an error response."""
+
+    def __init__(self, status_code: int, message: str, response: Optional[Dict[str, Any]] = None):
+        self.status_code = status_code
+        self.message = message
+        self.response = response or {}
+        super().__init__(f"API Error {status_code}: {message}")
+
+
+class RateLimitError(PolariAPIError):
+    """Rate limit exceeded (429)."""
+
+    def __init__(self, message: str = "Rate limit exceeded", response: Optional[Dict[str, Any]] = None):
+        super().__init__(429, message, response)
+
+
+class AuthenticationError(PolariAPIError):
+    """Authentication failed (401)."""
+
+    def __init__(self, message: str = "Authentication failed", response: Optional[Dict[str, Any]] = None):
+        super().__init__(401, message, response)
+
+
+class ValidationError(PolariAPIError):
+    """Request validation failed (400/422)."""
+
+    def __init__(
+        self,
+        message: str = "Validation failed",
+        status_code: int = 400,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(status_code, message, response)
+
+
+class ServerError(PolariAPIError):
+    """Server error (5xx)."""
+
+    def __init__(
+        self,
+        message: str = "Server error",
+        status_code: int = 500,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(status_code, message, response)
+
+
+class NetworkError(PolariError):
+    """Network connectivity issue."""
+
+    pass
+
+
+class TimeoutError(PolariError):
+    """Request timeout."""
+
+    pass
+
+
+class ConfigurationError(PolariError):
+    """Invalid configuration."""
+
+    pass
+
+
+class ProcessingError(PolariError):
+    """Error during article processing."""
+
+    pass
+
+
+class RetryExhaustedError(PolariError):
+    """Max retry attempts exhausted."""
+
+    def __init__(self, attempts: int, last_error: Optional[Exception] = None):
+        self.attempts = attempts
+        self.last_error = last_error
+        super().__init__(f"Retry exhausted after {attempts} attempts")

polari/layers/__init__.py

@@ -0,0 +1,5 @@
+"""Layer implementations."""
+
+from .layer0 import Layer0
+
+__all__ = ["Layer0"]

polari/layers/base.py

@@ -0,0 +1,144 @@
+"""Base layer interface for all Polari layers."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from ..config import PolariConfig
+from ..exceptions import (
+    AuthenticationError,
+    NetworkError,
+    PolariAPIError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from ..utils import CostTracker, MetricsCollector
+from ..utils.retry import ExponentialBackoff
+
+logger = logging.getLogger(__name__)
+
+
+class BaseLayer(ABC):
+    """Abstract base class for all layer implementations."""
+
+    def __init__(
+        self,
+        http_client: httpx.AsyncClient,
+        config: PolariConfig,
+        metrics: MetricsCollector,
+        cost_tracker: CostTracker,
+    ):
+        """Initialize base layer.
+
+        Args:
+            http_client: Shared HTTP client
+            config: SDK configuration
+            metrics: Metrics collector
+            cost_tracker: Cost tracker
+        """
+        self.http_client = http_client
+        self.config = config
+        self.metrics = metrics
+        self.cost_tracker = cost_tracker
+        self.layer_name = self.__class__.__name__.lower()
+
+    @abstractmethod
+    def get_endpoint(self) -> str:
+        """Get the API endpoint for this layer.
+
+        Returns:
+            Endpoint path (e.g., "/v1/layer0/process")
+        """
+        pass
+
+    async def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make HTTP request with error handling and exponential backoff retry.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            data: Request body data
+            params: Query parameters
+
+        Returns:
+            Response JSON
+
+        Raises:
+            PolariAPIError: On API errors
+            NetworkError: On network errors
+            TimeoutError: On request timeout
+        """
+        url = f"{getattr(self, 'base_url', self.config.base_url)}{endpoint}"
+
+        retry = ExponentialBackoff(
+            max_retries=self.config.max_retries,
+            base_delay=self.config.retry_backoff_factor,
+        )
+
+        async def _do_request():
+            try:
+                response = await self.http_client.request(
+                    method=method,
+                    url=url,
+                    json=data,
+                    params=params,
+                    timeout=self.config.timeout,
+                )
+
+                if response.status_code >= 400:
+                    # Only retry 429 (rate limit) and 5xx (server errors)
+                    # Never retry 401/403/400/422 - these won't change on retry
+                    if response.status_code in (401, 403, 400, 404, 422):
+
+                        self._handle_error_response(response)  # Raises, NOT retried
+                    else:
+                        self._handle_error_response(response)  # 429/5xx - retried
+
+                return response.json()
+
+            except httpx.TimeoutException as e:
+                logger.error(f"Request timeout: {e}")
+                raise TimeoutError(f"Request timeout after {self.config.timeout}s") from e
+            except httpx.NetworkError as e:
+                logger.error(f"Network error: {e}")
+                raise NetworkError(f"Network error: {e}") from e
+
+        return await retry.execute(_do_request)
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Handle error HTTP responses.
+
+        Args:
+            response: HTTP response object
+
+        Raises:
+            Appropriate PolariAPIError subclass
+        """
+        try:
+            error_data = response.json()
+            message = error_data.get("detail", error_data.get("message", "Unknown error"))
+        except Exception:
+            message = response.text or "Unknown error"
+
+        status_code = response.status_code
+
+        if status_code == 401:
+            raise AuthenticationError(message, response=error_data if 'error_data' in locals() else None)
+        elif status_code == 429:
+            raise RateLimitError(message, response=error_data if 'error_data' in locals() else None)
+        elif status_code in (400, 422):
+            raise ValidationError(message, status_code, response=error_data if 'error_data' in locals() else None)
+        elif status_code >= 500:
+            raise ServerError(message, status_code, response=error_data if 'error_data' in locals() else None)
+        else:
+            raise PolariAPIError(status_code, message, response=error_data if 'error_data' in locals() else None)