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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.