--- title: Tuatara Decide — train a classifier from your labels url: https://cymetica.com/decide api: https://cymetica.com/api/v1/decide mcp: https://cymetica.com/mcp/v1 openapi: https://cymetica.com/openapi-public.json --- # Tuatara Decide Train a specialist text classifier from labelled examples in minutes, then call it for a label and calibrated probabilities in about 10 ms. Built for fixed decisions that run at volume: routing support messages, tagging intents, sorting documents, screening headlines. Texts under 0.7 confidence get a second opinion: an open decision model re-ranks the top 5 labels (about half a second each, least sure first, at most 6 s per call; `"second_opinion": false` in the predict body skips it). Texts still unsure can go to the caller's own TypeSafe System One key (`X-Fallback-Key`, used per call, never stored). ## Quickstart for agents ``` # 1. key (skip if your human gave you one) curl -s https://cymetica.com/mcp/v1/register -H "Content-Type: application/json" \ -d '{"name": "my-agent", "contact_email": "owner@example.com", "intended_use": "text classification"}' # 2. train curl -s https://cymetica.com/api/v1/decide/classifiers -H "X-API-Key: $EVT_KEY" -H "Content-Type: application/json" \ -d '{"name": "support-intents", "examples": [{"text": "my card never arrived", "label": "card"}, {"text": "where is my new card", "label": "card"}, {"text": "I was charged twice", "label": "refund"}, {"text": "please give me my money back", "label": "refund"}]}' # 3. poll until "status": "ready" curl -s https://cymetica.com/api/v1/decide/classifiers/$ID -H "X-API-Key: $EVT_KEY" # 4. decide (up to 256 texts a call) curl -s https://cymetica.com/api/v1/decide/classifiers/$ID/predict -H "X-API-Key: $EVT_KEY" -H "Content-Type: application/json" \ -d '{"texts": ["the card still has not come"]}' ``` Each result: `label`, `confidence`, `probabilities` (every label), `unsure` (confidence under the classifier's `threshold`, 0.5 by default), `source` (`specialist` or `fallback`). Treat `unsure: true` as needing review. ## Step by step 1. **Have an account and an API key** — Sign up or log in. Every account includes Decide on the Free plan. Open https://cymetica.com/account, find the "API Keys" card, type a key name and create the key. Copy it when it is shown. An AI agent can instead register itself with POST https://cymetica.com/mcp/v1/register {name, contact_email, intended_use} and use the api_key that returns. *Done when:* They have a key that starts with evt_ saved somewhere safe. 2. **Collect labelled examples** — Write down real texts from their own work and the decision each should get, for example support messages labelled card / refund / other. At least 2 labels and at least 2 examples per label; up to 255 labels and 200,000 examples. More examples per label gives better answers; a few dozen per label is a good start. Add a catch-all label such as "other" if some texts fit nothing. *Done when:* They have a list, or a CSV with a header row of text,label, covering every label. 3. **Train the classifier** — Send the examples: POST https://cymetica.com/api/v1/decide/classifiers with {"name", "examples": [{"text", "label"}]} and the X-API-Key header, or upload the CSV to POST https://cymetica.com/api/v1/decide/classifiers/upload (form fields name and file). The copy-ready commands are under Quickstart on https://cymetica.com/decide. Training runs in the background; a few thousand examples take a few minutes. *Done when:* The reply shows an id starting with dc_ and status queued or training. 4. **Wait for ready and read the expected accuracy** — GET https://cymetica.com/api/v1/decide/classifiers/ until status is ready. expected_accuracy is measured on examples held back from training, so it is an honest preview. If status is failed, error says why. *Done when:* Status is ready and they have seen expected_accuracy. 5. **Ask it for decisions** — POST https://cymetica.com/api/v1/decide/classifiers//predict with {"texts": [...]} (up to 256 per call). Each result has the label, its confidence, every label's probability, and unsure: true when the confidence is under the threshold (0.5 by default). Texts under 0.7 confidence first get a second opinion from an open decision model among the top 5 labels (second_opinion: true, about half a second more; send "second_opinion": false to skip it). Send unsure ones to a person or to their own general-model key (step 6). *Done when:* They have real answers back for their own texts. 6. **Tune it (optional)** — Move the unsure line with PATCH https://cymetica.com/api/v1/decide/classifiers/ {"threshold": 0.7} (0 to 1). Add examples with POST https://cymetica.com/api/v1/decide/classifiers//examples: it retrains and keeps answering with the previous version until the new one is ready. To have unsure texts answered by a general model, send their OWN TypeSafe System One key as the X-Fallback-Key header; it is used for that call only and never stored. Already calling Jev? Send the same request to POST https://cymetica.com/api/v1/decide/systemone with model set to tuatara-decide/. *Done when:* The unsure rate and accuracy suit their use. 7. **Watch usage and savings** — Decisions count against the plan's weekly allowance shown at https://cymetica.com/usage. GET https://cymetica.com/api/v1/decide/classifiers//savings estimates what the same decisions would have cost as general-model calls. *Done when:* They know where to see usage and what it saves. ## Endpoints | Method | Path | What | |---|---|---| | GET | /api/v1/decide | plans, limits, evidence — no key | | POST | /api/v1/decide/classifiers | train from JSON `{name, examples: [{text, label}], threshold?, instructions?}` → 202 | | POST | /api/v1/decide/classifiers/upload | train from a CSV with `text,label` columns (multipart `name`, `file`) → 202 | | GET | /api/v1/decide/classifiers | your classifiers, plan and limit | | GET | /api/v1/decide/classifiers/{id} | status (`queued`, `training`, `ready`, `failed`), `expected_accuracy`, labels | | PATCH | /api/v1/decide/classifiers/{id} | `name`, `threshold` (0–1), `learn_from_fallback`, `instructions` | | POST | /api/v1/decide/classifiers/{id}/examples | add examples and retrain; the previous version keeps answering | | POST | /api/v1/decide/classifiers/{id}/predict | `{texts: [...]}` or `{text}` | | GET | /api/v1/decide/classifiers/{id}/savings | decisions and a general-model cost estimate | | DELETE | /api/v1/decide/classifiers/{id} | deletes the classifier, its examples and its model files | | POST | /api/v1/decide/systemone | TypeSafe System One request shape with `model: "tuatara-decide/"` | | POST | /api/v1/decide/auto | Decide Auto: `{state, questions}`, nothing to train first; it learns your `choice` questions from its confident answers | For Decide Auto, give each option a one-line description, `"criteria": {"card_arrival": "The customer's new card has not arrived yet."}`, rather than a plain list of names. Measured on three public intent benchmarks, descriptions raise its first-day accuracy from 62–72% to 77–86% and let it learn from more of your texts. MCP tools at https://cymetica.com/mcp/v1 (for the agent's linked account): `get_decide_info`, `list_decide_classifiers`, `get_decide_classifier`, `decide_create_classifier`, `decide_predict`. Errors are `{"detail": {"code", "message"}}`: 401 no key, 403 `CLASSIFIER_LIMIT`, 404 not yours or not found, 422 bad input, 429 weekly allowance used. ## Plans (every NEXUS plan includes Decide) | Plan | USDC a month | Classifiers | Decisions a week | |---|---|---|---| | Free | $0 | 1 | 400,000 | | Pro | $20 | 3 | 2,000,000 | | Max 5x | $100 | 15 | 10,000,000 | | Max 20x | $200 | 60 | 40,000,000 | Training a classifier counts as 5,000 decisions. Limits: 255 labels, 200,000 examples, 2,000 characters a text (longer is cut), 256 texts a call. Plans and usage: https://cymetica.com/usage ## Evidence On BANKING77 (77 intents, 3,080 test messages) the Tuatara blend scored 91.79% against Jev's 92.40%, a statistical tie, at about a thousandth of the running cost. With the embedding head (an open sentence-embedding model on our own hardware plus a classifier trained on the same messages) Decide scored 94.09%, ahead of Jev (117 right where Jev was wrong, 65 the other way, p = 0.00014), at about $5.70 of CPU per million messages against about $142 for Jev. Jev still leads with no training examples: https://cymetica.com/blog/matching-jev-on-banking77-at-a-thousandth-of-the-cost Embedding head answers: https://cymetica.com/static/research/jev-banking77/head_predictions.csv | Dataset | Labels | Test texts | Decide | Word model alone | |---|---|---|---|---| | CLINC150 (in-scope) | 150 | 4,500 | 92.56% | 92.56% | | HWU64 | 64 | 1,076 | 87.73% | 87.17% | | AG News | 4 | 7,600 | 91.13% | 90.99% | | SST-2 | 2 | 1,821 | 84.40% | 82.59% | Per-example predictions and scoring scripts: https://cymetica.com/static/research/decide-benchmarks/summary.json. Your own `expected_accuracy` after training is the number to trust for your data. ### With no training: Decide Zero Questions Decide Auto has not learned are answered by Decide Zero (choice, noul, score), our own model with no training on your data. Every answer the served model gave: | Question | Dataset | Asked | Test texts | Right | Calibration error | |---|---|---|---|---|---| | noul | SST-2 (short reviews) | Is this review positive? with true/false criteria | 1,821 | 84.9% | 0.031 | | noul | IMDB (long reviews) | Is this review positive? with true/false criteria | 1,000 | 90.9% | 0.037 | | noul | AG News | Is this article about ? (half true) | 2,000 | 63.1% | 0.081 | | noul | SST-2 | the same question with no criteria | 1,821 | 51.2% | 0.058 | | score | SST-5 | five levels, very negative to very positive | 2,210 | 33.6% (85.2% within one level) | 0.080 | | score | Yelp | five levels, very negative to very positive | 1,000 | 45.4% (89.7% within one level) | 0.091 | | choice | BANKING77, 77 options | 1 example per option in the request | 3,080 | 82.1% | 0.017 | | choice | BANKING77, 77 options | 3 examples per option in the request | 3,080 | 85.1% | 0.013 | | choice | BANKING77, 77 options | 5 examples per option in the request | 3,080 | 85.7% | 0.015 | A yes/no question needs criteria that say what true and false mean; with the question alone it reads the topic, not the verdict. It reads the first 480 tokens of the text, and takes at most 512 examples per request. Answers and scorer: https://cymetica.com/static/research/decide-zero/score.py Human walkthrough: ask NEXUS (`POST https://cymetica.com/api/v1/support/ai-agent` with `{"message": "Walk me through Tuatara Decide"}`).