Skip to main content

superion-s1

Python client for Superion S1 by Punky Tiger Labs — a calibrated decision API. Send a text and typed questions (yes/no, choice, score); get one calibrated probability distribution per question in a single call, with no text generation.

pip install superion-s1
export SUPERION_API_KEY=s1k_...   # free key: https://punkytigerlabs.com/s1/

Quickstart

from superion_s1 import Superion, noul, choice, score

s1 = Superion()  # reads SUPERION_API_KEY

d = s1.decide(
    "Message: The laptop arrived broken. I want my money back now, this is unacceptable.",
    {
        "refund":    noul("Does the customer ask for a refund or a replacement?"),
        "sentiment": choice("Overall sentiment of the message.",
                            {"pos": "positive", "neg": "negative", "neu": "neutral"}),
        "urgency":   score("How urgent is a reply?",
                           ["not urgent", "somewhat urgent", "very urgent"]),
    },
)

d["refund"].p             # 0.9998  probability of "true"
d["sentiment"].best       # "neg"
d["sentiment"].probabilities  # {"pos": 0.0003, "neg": 0.9943, "neu": 0.0054}
d["urgency"].best_label   # "very urgent"
d["urgency"].expected     # 1.81   expected level index (0..2)
d.usage.input_tokens      # 135    billed tokens; output is always 0

One question? Use the shortcuts:

p = s1.noul(text, "Is this message spam?")                 # float
c = s1.choice(text, "Which team?", ["billing", "tech", "sales"])   # .best, .p, .ranked()
s = s1.score(text, "Toxicity?", ["none", "mild", "severe"])        # .best, .expected, .normalized

Async

import asyncio
from superion_s1 import AsyncSuperion, noul

async def main():
    async with AsyncSuperion() as s1:
        results = await asyncio.gather(*[
            s1.noul(t, "Does the customer ask for a refund?") for t in tickets
        ])

asyncio.run(main())

Question types

builder criteria answer
noul(instructions, true="yes", false="no") what true / false mean NoulAnswer.p = probability of true
choice(instructions, options) dict id → description or list of labels (2–255) ChoiceAnswer.probabilities, .best, .p
score(instructions, levels) 2–16 ordered levels, lowest first ScoreAnswer.probabilities by index, .best, .best_label, .expected, .normalized

Write instructions and criteria as you would for a careful human reviewer: answers depend on the wording. Asking more questions about the same state only adds the questions' own tokens (the state is billed once per request).

Configuration

argument env var default
api_key SUPERION_API_KEY — (required)
model SUPERION_MODEL superion-s1-v6-int4e-vllm-kv1@sha256:e6dc49dc
base_url SUPERION_BASE_URL https://api.punkytigerlabs.com
timeout 120 s (a large state can wait up to ~70 s in the fair queue)
max_retries 2 (429, 5xx, connection errors; honours Retry-After)
max_retry_wait 60 s — a longer Retry-After (e.g. daily quota) raises at once

Model IDs are immutable; s1.models() lists what is served. Other endpoints: s1.usage() (plan, counters, Prepaid balance), s1.health(), s1.rotate_key(), s1.revoke_key(). Rate-limit headers are on d.rate_limit; Prepaid balance after the call on d.balance_usd.

Errors

All errors inherit from superion_s1.SuperionError.

status exception what to do
400 BadRequestError fix the request (message says what)
401 AuthenticationError check the key
402 InsufficientBalanceError (.balance_usd) add credits
413 RequestTooLargeError body over 4 MB: split it
422 UnprocessableError over 32,768 tokens per question / 65,536 per request, or too many options/levels
429 RateLimitError (.retry_after) quota, per-minute limit or queue full
503 ServiceUnavailableError (.retry_after) retried automatically
— APIConnectionError, APITimeoutError network

Failed requests are never charged. The API refuses over-long inputs with 422; it never truncates.

Examples

See examples/: ticket triage, moderation, an LLM router and an agent guardrail.

Development

pip install -e ".[dev]"
pytest                                   # offline, mocked
S1_LIVE=1 SUPERION_API_KEY=s1k_... pytest tests/test_live.py   # 2 real calls

About Superion S1

#1 of 214 on S1MB English v1 — Task Average 75.06 · Borda 89.82 (12 Nov 2026) — leaderboard. Calibrated probabilities, one call, no text generation, sub-second, deterministic within a pinned model version. Built on Gemma 4 26B-A4B, INT4 experts.

Plan Price
Free 20 M input tokens per day per key, permanent
Prepaid 0.042 USD per million input tokens, output free
Contract dedicated key, price on request

Get a key: https://punkytigerlabs.com/s1/ · Docs: https://punkytigerlabs.com/s1/docs · Status: https://punkytigerlabs.com/s1/status

Custom & industry models

Punky Tiger Labs also builds custom and industry-specific decision models — fitted to your own taxonomy, labels and data, for a specific industry or objective — served on a dedicated instance. Contact: alvaro.lopez@punkytigerlabs.com.

License

This client is MIT-licensed (see LICENSE). The Superion S1 model and API are proprietary services of Punky Tiger Labs, Inc., used under the API terms.

Metadata

Release files for superion-s1 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for superion-s1 0.1.0
File Size Uploaded Provenance Actions
superion_s1-0.1.0.tar.gz 13.8 kB Without provenance Details for superion_s1-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for superion-s1 0.1.0
File Interpreter ABI Platform Actions
superion_s1-0.1.0-py3-none-any.whl Python 3 none any Details for superion_s1-0.1.0-py3-none-any.whl

Total release size: 27.1 kB

Release files / superion_s1-0.1.0.tar.gz

Download URL superion_s1-0.1.0.tar.gz
Size 13.8 kB
Tags Source
SHA-256 checksum
How to use checksums
5f14469d63eb8375b7bb576da05f76463bb504cba408411df408605adfb7c372
BLAKE2b-256 checksum
How to use checksums
6dbdcbdd864296f8d4a0c5644b1b5942b33f2f1ce1a299af07ddad9dedd41276
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / superion_s1-0.1.0-py3-none-any.whl

Download URL superion_s1-0.1.0-py3-none-any.whl
Size 13.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0391c4ce6356d85a8dca5f2e950102915b393531585206481d9247adfc029e2f
BLAKE2b-256 checksum
How to use checksums
b324f61c63ebcb5228a661c98432337197dad9ffeb80d9b8aa596edaf6a16ad8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for superion-s1 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page