--- 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 it is unsure about 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). 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/"` | 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) Decide scored 91.79% against Jev's 92.40%, a statistical tie, at about a thousandth of the running cost: https://cymetica.com/blog/matching-jev-on-banking77-at-a-thousandth-of-the-cost | 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. Human walkthrough: ask NEXUS (`POST https://cymetica.com/api/v1/support/ai-agent` with `{"message": "Walk me through Tuatara Decide"}`).