classer 0.0.3__tar.gz

classer-0.0.3/.gitignore

@@ -0,0 +1 @@
+sst.pyi

classer-0.0.3/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,135 @@
+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/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "classer"
+version = "0.0.3"
+description = "High-performance AI classification — <200ms latency, up to 100x cheaper, beats GPT-5 mini accuracy"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Classer.ai" }]
+keywords = ["ai", "classification", "nlp", "machine-learning", "text-classification", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.25.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.23.0", "ruff>=0.1.0"]
+
+[project.urls]
+Homepage = "https://classer.ai"
+Documentation = "https://docs.classer.ai"
+Repository = "https://github.com/classer-ai/classer-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/classer"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

classer-0.0.3/src/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-0.0.3/src/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-0.0.3/src/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-0.0.3/src/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/tests/test_client.py

@@ -0,0 +1,635 @@
+"""Tests for the Classer SDK."""
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from classer import (
+    ClasserClient,
+    ClasserError,
+    ClassifyResponse,
+    TagResponse,
+    TagLabel,
+    classify,
+    tag,
+)
+
+
+class TestClasserClient:
+    """Tests for ClasserClient class."""
+
+    def test_constructor_accepts_custom_config(self):
+        client = ClasserClient(
+            api_key="test-key",
+        )
+        assert client.api_key == "test-key"
+
+    def test_constructor_reads_api_key_from_environment(self):
+        with patch.dict(os.environ, {"CLASSER_API_KEY": "env-api-key"}):
+            client = ClasserClient()
+            assert client.api_key == "env-api-key"
+
+    def test_constructor_explicit_api_key_overrides_env(self):
+        with patch.dict(os.environ, {"CLASSER_API_KEY": "env-key"}):
+            client = ClasserClient(api_key="explicit-key")
+            assert client.api_key == "explicit-key"
+
+    def test_constructor_default_timeout(self):
+        client = ClasserClient()
+        assert client.timeout == 30.0
+
+    def test_constructor_custom_timeout(self):
+        client = ClasserClient(timeout=10.0)
+        assert client.timeout == 10.0
+
+    @patch("classer.client.httpx.post")
+    def test_passes_timeout_to_httpx(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "a",
+            "confidence": 0.9,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(timeout=5.0)
+        client.classify(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        assert call_args[1]["timeout"] == 5.0
+
+
+class TestClassify:
+    """Tests for classify method."""
+
+    @patch("classer.client.httpx.post")
+    def test_classify_text_successfully(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "technical_support",
+            "confidence": 0.94,
+            "tokens": 101,
+            "latency_ms": 45,
+            "cached": False,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.classify(
+            text="I can't log in",
+            labels=["billing", "technical_support", "sales"],
+        )
+
+        assert isinstance(result, ClassifyResponse)
+        assert result.label == "technical_support"
+        assert result.confidence == 0.94
+        assert result.tokens == 101
+        assert result.latency_ms == 45
+        assert result.cached is False
+
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        assert call_args[0][0] == "https://api.classer.ai/v1/classify"
+        assert call_args[1]["headers"]["Authorization"] == "Bearer test-key"
+
+    @patch("classer.client.httpx.post")
+    def test_classify_includes_descriptions(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "hot",
+            "confidence": 0.92,
+            "latency_ms": 38,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        client.classify(
+            text="I need enterprise pricing for 500 users",
+            labels=["hot", "warm", "cold"],
+            descriptions={
+                "hot": "Ready to buy",
+                "warm": "Interested but exploring",
+                "cold": "Just browsing",
+            },
+        )
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert body["descriptions"] == {
+            "hot": "Ready to buy",
+            "warm": "Interested but exploring",
+            "cold": "Just browsing",
+        }
+
+    @patch("classer.client.httpx.post")
+    def test_classify_handles_api_errors(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = False
+        mock_response.status_code = 400
+        mock_response.json.return_value = {"detail": "labels cannot be empty"}
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+
+        with pytest.raises(ClasserError) as exc_info:
+            client.classify(text="test", labels=[])
+
+        assert exc_info.value.status == 400
+        assert exc_info.value.detail == "labels cannot be empty"
+
+    @patch("classer.client.httpx.post")
+    def test_classify_handles_network_errors(self, mock_post):
+        mock_post.side_effect = Exception("Network error")
+
+        client = ClasserClient(api_key="test-key")
+
+        with pytest.raises(Exception, match="Network error"):
+            client.classify(text="test", labels=["a", "b"])
+
+    @patch("classer.client.httpx.post")
+    def test_classify_does_not_send_mode(self, mock_post):
+        """classify() should NOT send mode in the request body."""
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "a",
+            "confidence": 0.9,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        client.classify(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert "mode" not in body
+        assert "threshold" not in body
+
+    @patch("classer.client.httpx.post")
+    def test_classify_with_classifier_param(self, mock_post):
+        """classify() sends classifier instead of labels when provided."""
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "billing",
+            "confidence": 0.88,
+            "latency_ms": 42,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.classify(text="test", classifier="support-tickets@v2")
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert body["classifier"] == "support-tickets@v2"
+        assert "labels" not in body
+        assert result.label == "billing"
+
+    @patch("classer.client.httpx.post")
+    def test_classify_omits_none_optional_fields(self, mock_post):
+        """Optional params that are None should not appear in the request body."""
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "a",
+            "confidence": 0.9,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        client.classify(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert body == {"text": "test", "labels": ["a", "b"]}
+
+    @patch("classer.client.httpx.post")
+    def test_classify_defaults_when_fields_missing(self, mock_post):
+        """tokens and cached should default when absent from response."""
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "a",
+            "confidence": 0.9,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.classify(text="test", labels=["a", "b"])
+
+        assert result.tokens == 0
+        assert result.cached is False
+
+
+class TestTag:
+    """Tests for tag method."""
+
+    @patch("classer.client.httpx.post")
+    def test_tag_with_multiple_labels(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [
+                {"label": "technology", "confidence": 0.65},
+                {"label": "finance", "confidence": 0.42},
+            ],
+            "tokens": 200,
+            "latency_ms": 52,
+            "cached": False,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.tag(
+            text="Tech stocks surge amid AI boom",
+            labels=["politics", "technology", "finance", "sports"],
+            threshold=0.3,
+        )
+
+        assert isinstance(result, TagResponse)
+        assert len(result.labels) == 2
+        assert result.labels[0].label == "technology"
+        assert result.labels[0].confidence == 0.65
+        assert result.labels[1].label == "finance"
+        assert result.tokens == 200
+        assert result.cached is False
+
+        call_args = mock_post.call_args
+        assert call_args[0][0] == "https://api.classer.ai/v1/tag"
+
+    @patch("classer.client.httpx.post")
+    def test_tag_sends_threshold(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [{"label": "technology", "confidence": 0.85}],
+            "latency_ms": 48,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        client.tag(
+            text="AI is transforming industries",
+            labels=["technology", "sports"],
+            threshold=0.5,
+        )
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert body["threshold"] == 0.5
+
+    @patch("classer.client.httpx.post")
+    def test_tag_returns_empty_when_nothing_matches(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [],
+            "latency_ms": 35,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.tag(
+            text="Random unrelated text",
+            labels=["sports", "politics"],
+            threshold=0.9,
+        )
+
+        assert result.labels == []
+
+    @patch("classer.client.httpx.post")
+    def test_tag_returns_empty_when_labels_is_null(self, mock_post):
+        """API may return null instead of empty array."""
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": None,
+            "latency_ms": 35,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.tag(text="test", labels=["a", "b"])
+
+        assert result.labels == []
+
+    @patch("classer.client.httpx.post")
+    def test_tag_does_not_send_mode(self, mock_post):
+        """tag() should NOT send mode in the request body."""
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [{"label": "a", "confidence": 0.8}],
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        client.tag(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert "mode" not in body
+
+    @patch("classer.client.httpx.post")
+    def test_tag_omits_threshold_when_not_provided(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [{"label": "a", "confidence": 0.8}],
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        client.tag(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert "threshold" not in body
+
+    @patch("classer.client.httpx.post")
+    def test_tag_with_classifier_param(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [{"label": "urgent", "confidence": 0.91}],
+            "latency_ms": 55,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.tag(text="test", classifier="priority-tagger")
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert body["classifier"] == "priority-tagger"
+        assert "labels" not in body
+        assert result.labels[0].label == "urgent"
+
+    @patch("classer.client.httpx.post")
+    def test_tag_with_descriptions(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [{"label": "tech", "confidence": 0.85}],
+            "latency_ms": 40,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        client.tag(
+            text="test",
+            labels=["tech", "sports"],
+            descriptions={"tech": "Technology news", "sports": "Sports news"},
+        )
+
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert body["descriptions"] == {
+            "tech": "Technology news",
+            "sports": "Sports news",
+        }
+
+    @patch("classer.client.httpx.post")
+    def test_tag_handles_api_errors(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = False
+        mock_response.status_code = 422
+        mock_response.json.return_value = {"detail": "At least 2 labels required"}
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+
+        with pytest.raises(ClasserError) as exc_info:
+            client.tag(text="test", labels=["only_one"])
+
+        assert exc_info.value.status == 422
+        assert exc_info.value.detail == "At least 2 labels required"
+
+    @patch("classer.client.httpx.post")
+    def test_tag_defaults_when_fields_missing(self, mock_post):
+        """tokens and cached should default when absent from response."""
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [{"label": "a", "confidence": 0.8}],
+            "latency_ms": 50,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.tag(text="test", labels=["a", "b"])
+
+        assert result.tokens == 0
+        assert result.cached is False
+
+    @patch("classer.client.httpx.post")
+    def test_tag_latency_ms(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [],
+            "latency_ms": 203,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+        result = client.tag(text="test", labels=["a", "b"])
+
+        assert result.latency_ms == 203
+
+
+class TestDefaultExports:
+    """Tests for module-level convenience functions."""
+
+    @patch("classer.client.httpx.post")
+    def test_classify_function_works(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "greeting",
+            "confidence": 0.95,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        result = classify(
+            text="Hello there!",
+            labels=["greeting", "question", "complaint"],
+        )
+
+        assert result.label == "greeting"
+
+    @patch("classer.client.httpx.post")
+    def test_tag_function_works(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [
+                {"label": "news", "confidence": 0.8},
+                {"label": "technology", "confidence": 0.6},
+            ],
+            "latency_ms": 45,
+        }
+        mock_post.return_value = mock_response
+
+        result = tag(
+            text="Apple announces new iPhone",
+            labels=["news", "technology", "sports"],
+        )
+
+        assert len(result.labels) == 2
+        assert result.labels[0].label == "news"
+
+
+class TestClasserError:
+    """Tests for ClasserError exception."""
+
+    @patch("classer.client.httpx.post")
+    def test_error_contains_status_and_detail(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = False
+        mock_response.status_code = 422
+        mock_response.json.return_value = {"detail": "Validation error"}
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+
+        with pytest.raises(ClasserError) as exc_info:
+            client.classify(text="", labels=["a"])
+
+        assert exc_info.value.status == 422
+        assert exc_info.value.detail == "Validation error"
+
+    @patch("classer.client.httpx.post")
+    def test_error_handles_non_json_responses(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = False
+        mock_response.status_code = 500
+        mock_response.text = ""
+        mock_response.json.side_effect = ValueError("Invalid JSON")
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="test-key")
+
+        with pytest.raises(ClasserError) as exc_info:
+            client.classify(text="test", labels=["a", "b"])
+
+        assert exc_info.value.status == 500
+        assert exc_info.value.detail is None
+
+    def test_error_str_includes_status_and_detail(self):
+        err = ClasserError("Request failed", status=429, detail="Rate limit exceeded")
+        assert "429" in str(err)
+        assert "Rate limit exceeded" in str(err)
+
+    def test_error_str_without_detail(self):
+        err = ClasserError("Request failed", status=500)
+        assert "500" in str(err)
+        assert str(err) == "Request failed (status: 500)"
+
+    def test_error_str_without_status(self):
+        err = ClasserError("Something went wrong")
+        assert str(err) == "Something went wrong"
+
+
+class TestRequestHeaders:
+    """Tests for request header handling."""
+
+    @patch("classer.client.httpx.post")
+    def test_includes_authorization_header_when_api_key_set(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "a",
+            "confidence": 0.9,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient(api_key="my-secret-key")
+        client.classify(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        assert call_args[1]["headers"]["Authorization"] == "Bearer my-secret-key"
+
+    @patch("classer.client.httpx.post")
+    def test_no_authorization_header_when_api_key_empty(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "a",
+            "confidence": 0.9,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        with patch.dict(os.environ, {}, clear=True):
+            client = ClasserClient(api_key="")
+            client.classify(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        assert "Authorization" not in call_args[1]["headers"]
+
+    @patch("classer.client.httpx.post")
+    def test_always_includes_content_type_header(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "a",
+            "confidence": 0.9,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient()
+        client.classify(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        assert call_args[1]["headers"]["Content-Type"] == "application/json"
+
+
+class TestEndpoints:
+    """Tests for correct endpoint URLs."""
+
+    @patch("classer.client.httpx.post")
+    def test_classify_uses_correct_endpoint(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "label": "a",
+            "confidence": 0.9,
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient()
+        client.classify(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        assert call_args[0][0] == "https://api.classer.ai/v1/classify"
+
+    @patch("classer.client.httpx.post")
+    def test_tag_uses_correct_endpoint(self, mock_post):
+        mock_response = MagicMock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "labels": [{"label": "a", "confidence": 0.9}],
+            "latency_ms": 30,
+        }
+        mock_post.return_value = mock_response
+
+        client = ClasserClient()
+        client.tag(text="test", labels=["a", "b"])
+
+        call_args = mock_post.call_args
+        assert call_args[0][0] == "https://api.classer.ai/v1/tag"