Python SDK

pip install classer

import classer

# Uses CLASSER_API_KEY environment variable
result = classer.classify(
    text="I can't log in",
    labels=["billing", "technical", "sales"]
)

print(result.label)      # "technical"
print(result.confidence) # 0.94

export CLASSER_API_KEY=your-api-key

from classer import ClasserClient

client = ClasserClient(
    api_key="your-api-key",
    timeout=30.0  # optional, in seconds
)

result = client.classify(
    text="I can't log in to my account",
    labels=["billing", "technical", "sales"],
    descriptions={                          # optional
        "billing": "Payment or invoice issues",
        "technical": "Login, bugs, errors",
        "sales": "Pricing or plan questions",
    },
    priority="standard",                    # optional: "standard" (default, <1s) or "fast" (<200ms)
    cache=True,                             # optional: set False to bypass cache
)

result.label        # "technical"
result.confidence   # 0.94
result.tokens       # 142
result.latency_ms   # 87.0
result.cached       # False

result = client.classify(
    text="I can't log in",
    classifier="support-tickets",       # or "support-tickets@v2"
)

# URL
result = client.classify(
    image="https://example.com/photo.jpg",
    labels=["cat", "dog", "bird"],
)

# Base64
result = client.classify(
    image=base64_string,
    labels=["cat", "dog", "bird"],
)

# Text + image together
result = client.classify(
    text="What animal is this?",
    image="https://example.com/photo.jpg",
    labels=["cat", "dog", "bird"],
)

result.visual_tokens  # image tokens used

# Also accepts a URL or local file path. Can be combined with text and image inputs.
result = client.classify(
    file=base64_string,
    labels=["invoice", "receipt", "contract"],
)

result.tokens         # text tokens
result.visual_tokens  # page image tokens

result = client.tag(
    text="Breaking: Tech stocks surge amid AI boom",
    labels=["politics", "technology", "finance", "sports"],
    threshold=0.5,                          # optional (default: 0.5)
    descriptions={"technology": "Tech industry news"},  # optional
    priority="standard",                    # optional: "standard" (default, <1s) or "fast" (<200ms)
    cache=True,                             # optional: set False to bypass cache
)

for t in result.labels:
    print(f"{t.label}: {t.confidence}")
# technology: 0.92
# finance: 0.78

result.tokens       # 200
result.latency_ms   # 203.0
result.cached       # False

result = client.classify_batch(
    texts=["I can't log in", "What's the pricing?", "My invoice is wrong"],
    labels=["billing", "technical", "sales"],
)

for r in result.results:
    print(f"{r.label}: {r.confidence}")

result.total_tokens  # total across all texts
result.latency_ms    # total request time

result = client.classify_batch(
    texts=["What is this?", "Describe the document"],
    file="report.pdf",
    labels=["report", "invoice", "contract"],
)

result = client.tag_batch(
    texts=["Tech stocks surge", "Election results are in"],
    labels=["politics", "technology", "finance"],
    threshold=0.5,
)

for r in result.results:
    for t in r.labels:
        print(f"{t.label}: {t.confidence}")

import classer

result = classer.classify(text="...", labels=["a", "b"])
result = classer.tag(text="...", labels=["a", "b"], threshold=0.5)
result = classer.classify(file="document.pdf", labels=["a", "b"])
result = classer.classify_batch(texts=["x", "y"], labels=["a", "b"])
result = classer.tag_batch(texts=["x", "y"], labels=["a", "b"])

from classer import ClasserClient, ClasserError

client = ClasserClient(api_key="your-key")

try:
    result = client.classify(
        text="Hello",
        labels=["greeting", "question"]
    )
except ClasserError as e:
    print(f"Error: {e.message}")
    print(f"Status: {e.status}")    # HTTP status code (e.g. 400, 401, 422, 429)
    print(f"Detail: {e.detail}")    # Error detail from the API

@dataclass
class ClassifyResponse:
    label: Optional[str] = None
    confidence: Optional[float] = None
    tokens: int = 0
    visual_tokens: int = 0
    latency_ms: float = 0.0
    cached: bool = False

@dataclass
class TagResponse:
    labels: list[TagLabel]  # empty list when nothing matches
    tokens: int = 0
    visual_tokens: int = 0
    latency_ms: float = 0.0
    cached: bool = False

@dataclass
class TagLabel:
    label: str
    confidence: float

@dataclass
class BatchClassifyResponse:
    results: list[BatchClassifyResult]
    total_tokens: int = 0
    latency_ms: float = 0.0

@dataclass
class BatchClassifyResult:
    label: Optional[str] = None
    confidence: Optional[float] = None
    tokens: int = 0
    visual_tokens: int = 0
    error: Optional[str] = None
    cached: bool = False

@dataclass
class BatchTagResponse:
    results: list[BatchTagResult]
    total_tokens: int = 0
    latency_ms: float = 0.0

@dataclass
class BatchTagResult:
    labels: list[TagLabel]
    tokens: int = 0
    visual_tokens: int = 0
    error: Optional[str] = None
    cached: bool = False

class ClasserError(Exception):
    message: str
    status: Optional[int]
    detail: Optional[str]