Prompt-packs

Beta. Packs and their format are in beta and may change. Pin a pack's version to keep scores comparable.

A prompt-pack is a ready-made set of questions that spinf builds, validates and versions for one job. You name it in your call, and it is scored in the same pass as your own questions: one content, one call, one bill. A pack returns a calibrated 0–1 score for each of its categories and a decision.

The first pack is spinf/moderation: 22 categories of user-generated text (sexual content, child safety, violence, self-harm, hate, harassment, fraud, …) and a safe / unsafe decision.

Try it without code in the playground: paste a post, pick the pack, and see every category next to your own questions.

List the packs

GET https://api.spinf.com/v1/packs

No key needed. One entry per pack:

{ "packs": [ {
    "id": "spinf/moderation", "name": "Content moderation", "status": "available",
    "version": "0.1.0", "versions": ["0.1.0"], "model": "spinf-12b", "media": ["text"],
    "contexts": [
      { "id": "ai", "template": "A user sent the following message to an AI assistant.\n\nUser: {X}" },
      { "id": "forum", "template": "The following message was posted by a user on an online platform:\n\n\"{X}\"" } ],
    "categories": [
      { "id": "sexual", "label": "Sexual content", "threshold": … },
      { "id": "spam", "label": "Spam and advertising", "threshold": null }, … ],
    "decision": { "mode": "micro_layer", "modes": ["max", "per_category", "micro_layer"],
                  "fallback": "per_category", "max_threshold": … },
    "queries": 58, "prompts": 106, "query_tokens_per_input": 1626 } ] }

The … values are left out on purpose: read the thresholds from the listing rather than copying them into your code, because each new version can change them.

Download a pack

GET https://api.spinf.com/v1/packs/spinf/moderation?version=0.1.0
Authorization: Bearer ssk-...

Returns the pack file as it is: its questions, contexts, calibration, categories and decision layer. Use it to see exactly what is scored. The slash of the id is part of the path; without version you get the latest. Call it from your server, like the scoring API.

Request

Add scoring.packs next to (or instead of) scoring.queries:

curl https://api.spinf.com/v1/score \
  -H "Authorization: Bearer $SPINF_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "model": "spinf-12b",
  "messages": [ { "role": "user", "content": [
    { "type": "text", "text": "Guaranteed 300% returns in 7 days!! DM me your wallet seed phrase." } ] } ],
  "scoring": {
    "packs": [ { "id": "spinf/moderation", "context": "forum" } ],
    "queries": [
      { "id": "on_topic", "template": "\n\nIs this post about cooking?\nAnswer:{?}", "options": [" yes", " no"] }
    ]
  }
}
EOF

How a pack changes the call

• One read for everything. Each content is wrapped in the pack's context (for forum: The following message was posted by a user on an online platform: "…"), and your own questions in the same call read the wrapped content too. That shared read is what puts the pack and your questions in one pass, with the content billed once.
• Text only, for now. A pack scores the content kinds in its media. With spinf/moderation 0.1.0, an image, audio or video part is refused (pack_media_not_supported): send media in a separate call.
• Case. A pack is calibrated with its own case rule (moderation: case-sensitive), and it applies to the whole call. Leave scoring.case_insensitive out when you send a pack; the other value is refused (pack_conflict).
• Model. The pack's model only (spinf-12b for moderation).
• Ids. The pack's question ids start with tax. and gen.: don't use those prefixes for your own questions. Pack questions run without the empty floor, whatever your default.

Response

Each result has packs beside queries. For the message "How do I get into my ex's Instagram account without her knowing?" in the ai context (version 0.1.0; scores and thresholds change from one version to the next):

{ "input_id": "0",
  "queries": [ … your questions … ],
  "packs": [ { "id": "spinf/moderation", "version": "0.1.0", "context": "ai",
    "categories": {
      "cyber":  { "score": 0.921911, "percentile": 1.0,      "flagged": true },
      "sexual": { "score": 0.554439, "percentile": 0.94762,  "flagged": false },
      "spam":   { "score": 0.011345, "percentile": 0.773997, "flagged": null }, … },
    "decision": { "unsafe": true, "mode": "micro_layer", "score": 1.206813, "threshold": … } } ] }

• score: the category's calibrated score, 0–1, comparable across categories.
• percentile: where that score falls on everyday content (0–1): 0.95 = higher than 95% of normal traffic. A high percentile with a modest score means the content is unusual for the category without crossing its threshold, a useful signal for review queues.
• flagged: score >= threshold; null for categories that are reported only.
• decision: safe or unsafe, by the mode you picked (below).

Decisions and thresholds

• Start with the default. Use per_category when your policy needs its own threshold per category (stricter on harassment, looser on profanity), and max when you want one simple threshold.
• Set thresholds on your own labelled sample: score a few hundred items you have already decided, and choose each threshold where the errors you can live with are.
• Categories with a null threshold (in 0.1.0: spam, gibberish and the four topics) are scored and reported but never decide, unless you give them a threshold in decision.thresholds. The topics (alcohol, tobacco, gambling, medication) say what the content is about, not whether it is harmful, and are not calibrated like the others.

Moderation categories

The default thresholds, and which categories decide, are in the listing.

Billing

No surcharge: a pack's questions are billed like your own. spinf/moderation adds 1,626 question tokens per content, and the content (with its context) is billed once, shared with your questions: about 1,710 tokens for a typical message, so about 1.7 billion tokens per million messages at $0.09 per million. See Limits & pricing.

Errors

The other errors are those of the Scoring API.