classer 0.0.3__py3-none-any.whl

classer/__init__.py

@@ -0,0 +1,69 @@
+"""Classer SDK - Low-cost, fast AI classification API."""
+
+from typing import Optional
+
+from .client import ClasserClient
+from .exceptions import ClasserError
+from .types import (
+    ClassifyResponse,
+    TagLabel,
+    TagResponse,
+)
+
+__all__ = [
+    "ClasserClient",
+    "ClasserError",
+    "ClassifyResponse",
+    "TagLabel",
+    "TagResponse",
+    "classify",
+    "tag",
+]
+
+# Default client instance
+_default_client: ClasserClient | None = None
+
+
+def _get_default_client() -> ClasserClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = ClasserClient()
+    return _default_client
+
+
+def classify(
+    text: str,
+    labels: Optional[list[str]] = None,
+    classifier: Optional[str] = None,
+    descriptions: Optional[dict[str, str]] = None,
+    speed: Optional[str] = None,
+    cache: Optional[bool] = None,
+) -> ClassifyResponse:
+    """Classify text into one of the provided labels (single-label).
+
+    See ClasserClient.classify for full parameter documentation.
+    """
+    return _get_default_client().classify(
+        text, labels=labels, classifier=classifier,
+        descriptions=descriptions, speed=speed, cache=cache,
+    )
+
+
+def tag(
+    text: str,
+    labels: Optional[list[str]] = None,
+    classifier: Optional[str] = None,
+    descriptions: Optional[dict[str, str]] = None,
+    threshold: Optional[float] = None,
+    speed: Optional[str] = None,
+    cache: Optional[bool] = None,
+) -> TagResponse:
+    """Tag text with multiple labels (multi-label).
+
+    See ClasserClient.tag for full parameter documentation.
+    """
+    return _get_default_client().tag(
+        text, labels=labels, classifier=classifier,
+        descriptions=descriptions, threshold=threshold,
+        speed=speed, cache=cache,
+    )

classer/client.py

@@ -0,0 +1,186 @@
+"""Classer client implementation."""
+
+import os
+from typing import Optional
+
+import httpx
+
+from .exceptions import ClasserError
+from .types import (
+    ClassifyResponse,
+    TagLabel,
+    TagResponse,
+)
+
+
+class ClasserClient:
+    """Client for the Classer API."""
+
+    BASE_URL = "https://api.classer.ai"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        """
+        Initialize the Classer client.
+
+        Args:
+            api_key: API key for authentication. Falls back to CLASSER_API_KEY env var.
+            timeout: Request timeout in seconds.
+        """
+        self.api_key = api_key or os.environ.get("CLASSER_API_KEY", "")
+        self.timeout = timeout
+
+    def _request(self, endpoint: str, body: dict) -> dict:
+        """Make a POST request to the API."""
+        url = f"{self.BASE_URL}{endpoint}"
+
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        response = httpx.post(url, json=body, headers=headers, timeout=self.timeout)
+
+        if not response.is_success:
+            detail = None
+            try:
+                error_data = response.json()
+                detail = error_data.get("detail") if isinstance(error_data, dict) else None
+            except (ValueError, TypeError):
+                detail = response.text[:200] if response.text else None
+            raise ClasserError(
+                f"Request failed with status {response.status_code}",
+                status=response.status_code,
+                detail=detail,
+            )
+
+        return response.json()
+
+    @staticmethod
+    def _build_body(
+        text: str,
+        labels: Optional[list[str]] = None,
+        classifier: Optional[str] = None,
+        descriptions: Optional[dict[str, str]] = None,
+        speed: Optional[str] = None,
+        cache: Optional[bool] = None,
+        threshold: Optional[float] = None,
+    ) -> dict:
+        """Build a request body dict, omitting None/empty fields."""
+        body: dict = {"text": text}
+        if classifier:
+            body["classifier"] = classifier
+        if labels:
+            body["labels"] = labels
+        if descriptions:
+            body["descriptions"] = descriptions
+        if threshold is not None:
+            body["threshold"] = threshold
+        if speed:
+            body["speed"] = speed
+        if cache is not None:
+            body["cache"] = cache
+        return body
+
+    def classify(
+        self,
+        text: str,
+        labels: Optional[list[str]] = None,
+        classifier: Optional[str] = None,
+        descriptions: Optional[dict[str, str]] = None,
+        speed: Optional[str] = None,
+        cache: Optional[bool] = None,
+    ) -> ClassifyResponse:
+        """
+        Classify text into one of the provided labels (single-label).
+
+        Args:
+            text: Text to classify.
+            labels: List of possible labels (1-200).
+            classifier: Saved classifier name or "name@vN" reference.
+            descriptions: Maps label name to description for better accuracy.
+            speed: Speed tier — "standard" (default, <1s) or "fast" (<200ms).
+            cache: Set to False to bypass cache. Default: True.
+
+        Returns:
+            ClassifyResponse with label and confidence.
+
+        Example:
+            >>> result = classer.classify(
+            ...     text="I can't log in",
+            ...     labels=["billing", "technical_support", "sales"]
+            ... )
+            >>> print(result.label)  # "technical_support"
+        """
+        body = self._build_body(
+            text, labels=labels, classifier=classifier,
+            descriptions=descriptions, speed=speed, cache=cache,
+        )
+
+        data = self._request("/v1/classify", body)
+
+        return ClassifyResponse(
+            label=data.get("label"),
+            confidence=data.get("confidence"),
+            tokens=data.get("tokens", 0),
+            latency_ms=data.get("latency_ms", 0),
+            cached=data.get("cached", False),
+            public=data.get("public"),
+        )
+
+    def tag(
+        self,
+        text: str,
+        labels: Optional[list[str]] = None,
+        classifier: Optional[str] = None,
+        descriptions: Optional[dict[str, str]] = None,
+        threshold: Optional[float] = None,
+        speed: Optional[str] = None,
+        cache: Optional[bool] = None,
+    ) -> TagResponse:
+        """
+        Tag text with multiple labels that exceed a confidence threshold.
+
+        Args:
+            text: Text to tag.
+            labels: List of possible labels (1-200).
+            classifier: Saved classifier name or "name@vN" reference.
+            descriptions: Maps label name to description for better accuracy.
+            threshold: Confidence threshold (0-1). Default: 0.3.
+            speed: Speed tier — "standard" (default, <1s) or "fast" (<200ms).
+            cache: Set to False to bypass cache. Default: True.
+
+        Returns:
+            TagResponse with labels list (each has label and confidence).
+
+        Example:
+            >>> result = classer.tag(
+            ...     text="Breaking: Tech stocks surge amid AI boom",
+            ...     labels=["politics", "technology", "finance", "sports"],
+            ...     threshold=0.3
+            ... )
+            >>> for tag in result.labels:
+            ...     print(f"{tag.label}: {tag.confidence}")
+        """
+        body = self._build_body(
+            text, labels=labels, classifier=classifier,
+            descriptions=descriptions, threshold=threshold,
+            speed=speed, cache=cache,
+        )
+
+        data = self._request("/v1/tag", body)
+
+        tag_labels = [
+            TagLabel(label=item["label"], confidence=item["confidence"])
+            for item in data.get("labels") or []
+        ]
+
+        return TagResponse(
+            labels=tag_labels,
+            tokens=data.get("tokens", 0),
+            latency_ms=data.get("latency_ms", 0),
+            cached=data.get("cached", False),
+            public=data.get("public"),
+        )

classer/exceptions.py

@@ -0,0 +1,26 @@
+"""Exception classes for the Classer SDK."""
+
+from typing import Optional
+
+
+class ClasserError(Exception):
+    """Base exception for Classer SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status: Optional[int] = None,
+        detail: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.detail = detail
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status:
+            parts.append(f"(status: {self.status})")
+        if self.detail:
+            parts.append(f"- {self.detail}")
+        return " ".join(parts)

classer/types.py

@@ -0,0 +1,35 @@
+"""Type definitions for the Classer SDK."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class ClassifyResponse:
+    """Response from single-label classification."""
+
+    label: Optional[str] = None
+    confidence: Optional[float] = None
+    tokens: int = 0
+    latency_ms: float = 0.0
+    cached: bool = False
+    public: Optional[bool] = None
+
+
+@dataclass
+class TagLabel:
+    """Single label with confidence in a tag response."""
+
+    label: str
+    confidence: float
+
+
+@dataclass
+class TagResponse:
+    """Response from multi-label tagging."""
+
+    labels: list[TagLabel] = field(default_factory=list)
+    tokens: int = 0
+    latency_ms: float = 0.0
+    cached: bool = False
+    public: Optional[bool] = None

classer-0.0.3.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: classer
+Version: 0.0.3
+Summary: High-performance AI classification — <200ms latency, up to 100x cheaper, beats GPT-5 mini accuracy
+Project-URL: Homepage, https://classer.ai
+Project-URL: Documentation, https://docs.classer.ai
+Project-URL: Repository, https://github.com/classer-ai/classer-python
+Author: Classer.ai
+License-Expression: MIT
+Keywords: ai,classification,llm,machine-learning,nlp,text-classification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+exit
+# [classer](https://classer.ai)
+
+High-performance AI classification
+
+<200ms latency · up to 100x cheaper · beats GPT-5 mini accuracy · self-calibrating accuracy · no prompt engineering
+
+## Installation
+
+```bash
+pip install classer
+```
+
+## Quick Start
+
+```python
+import classer
+
+# Single-label classification
+result = classer.classify(
+    text="I can't log in and need a password reset.",
+    labels=["billing", "technical_support", "sales", "spam"]
+)
+print(result.label)      # "technical_support"
+print(result.confidence) # 0.94
+
+# With descriptions for better accuracy
+lead = classer.classify(
+    text="We need a solution for 500 users, what's your enterprise pricing?",
+    labels=["hot", "warm", "cold"],
+    descriptions={
+        "hot": "Ready to buy, asking for pricing or demo",
+        "warm": "Interested but exploring options",
+        "cold": "Just browsing, no clear intent"
+    }
+)
+print(lead.label)  # "hot"
+
+# Multi-label tagging
+result = classer.tag(
+    text="Breaking: Tech stocks surge amid AI boom",
+    labels=["politics", "technology", "finance", "sports"],
+    threshold=0.3
+)
+for t in result.labels:
+    print(f"{t.label}: {t.confidence}")
+# technology: 0.92
+# finance: 0.78
+```
+
+## Configuration
+
+No API key is needed to get started. To unlock higher rate limits, get an API key from [classer.ai/api-keys](https://classer.ai/api-keys).
+
+```bash
+export CLASSER_API_KEY=your-api-key
+```
+
+Or configure programmatically:
+
+```python
+from classer import ClasserClient
+
+client = ClasserClient(
+    api_key="your-api-key"
+)
+```
+
+## API Reference
+
+### `classify(text, labels=None, classifier=None, descriptions=None, speed=None, cache=None)`
+
+Classify text into exactly one of the provided labels.
+
+```python
+result = classer.classify(
+    text="Text to classify",
+    labels=["label1", "label2"],  # 1-200 possible labels
+    descriptions={"label1": "Description for better accuracy"},
+    speed="standard",   # "standard" (default, <1s) or "fast" (<200ms)
+    cache=True          # Set to False to bypass cache. Default: True
+)
+
+result.label        # Selected label
+result.confidence   # 0-1 confidence score
+result.tokens       # Total tokens used
+result.latency_ms   # Processing time in ms
+result.cached       # Whether served from cache
+```
+
+### `tag(text, labels=None, classifier=None, descriptions=None, threshold=None, speed=None, cache=None)`
+
+Multi-label tagging — returns all labels above a confidence threshold.
+
+```python
+result = classer.tag(
+    text="Text to tag",
+    labels=["label1", "label2"],  # 1-200 possible labels
+    descriptions={"label1": "Description"},
+    threshold=0.3,  # Default: 0.3
+    speed="standard",  # "standard" (default, <1s) or "fast" (<200ms)
+    cache=True      # Set to False to bypass cache. Default: True
+)
+
+for t in result.labels:
+    print(f"{t.label}: {t.confidence}")
+
+result.tokens       # Total tokens used
+result.latency_ms   # Processing time in ms
+result.cached       # Whether served from cache
+```
+
+## Error Handling
+
+```python
+from classer import ClasserError
+
+try:
+    result = classer.classify(text="hello", labels=["a", "b"])
+except ClasserError as e:
+    print(e.status)  # HTTP status code
+    print(e.detail)  # Error detail from API
+```
+
+## Documentation
+
+Full API reference and guides at [docs.classer.ai](https://docs.classer.ai).
+
+## GitHub
+
+[github.com/classer-ai/classer-python](https://github.com/classer-ai/classer-python)
+
+## License
+
+MIT

classer-0.0.3.dist-info/RECORD

@@ -0,0 +1,7 @@
+classer/__init__.py,sha256=CMP550ePsx_AEofILAY_6q72FySK-q0NBQyQNTLG7Lo,1764
+classer/client.py,sha256=j0QT1DGQN5Xy-skxfkAZGgnGBqpfPDsftuzZQc9D2fs,6122
+classer/exceptions.py,sha256=98CxeqMJ1OW8VzSLIPu3dWzEPR6VHGQ-vzihOz_Rlk0,656
+classer/types.py,sha256=Bctr4OCDiRPAe0uyhDf5pgBZbHVKG_-x1oX7FVdssc4,750
+classer-0.0.3.dist-info/METADATA,sha256=W41-9xJCOnHg9novtJXpUkmrcr7AHMwYvBtBOPa1YcI,4603
+classer-0.0.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+classer-0.0.3.dist-info/RECORD,,

classer-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any