Skills & sessions

Skills

Save a question once, show Wity labelled examples of the answer you want, and it learns your definition. Use the skill anywhere you would write the question.

Every team has its own meaning for words like urgent, eligible or off-topic. Wity answers a question the way most people would read it. When yours differs, write the question as a skill and add examples: Wity learns from them in seconds and keeps learning as you add more. You don't tune prompts or train anything yourself.

Create a skill#

A skill is a name, a noul (yes or no) or choice question, and optional examples. An example is a state and the answer you want for it: yes or no, or an option id for a choice question.

curl https://api.wity.alphanimble.com/v1/skills \
  -H "Authorization: Bearer $WITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "urgent-ticket",
    "description": "Urgent = the customer cannot use the product, a security problem, or money taken wrongly.",
    "question": { "type": "noul", "instructions": "Does this support ticket need a reply within the hour?" },
    "examples": [
      { "state": "Hi team, no rush, but since 9am none of our staff can log in.", "answer": "yes" },
      { "state": "THIS IS UNACCEPTABLE. Your new logo is hideous. Fix it NOW.", "answer": "no" },
      { "state": "We were billed for 250 seats but only have 40 users.", "answer": "yes" },
      { "state": "Could you send me the invoices from last year as one PDF?", "answer": "no" }
    ]
  }'

Use it#

Wherever a request takes a question, write {"skill": "<name or id>"} instead. Mix skills and ordinary questions in one request.

curl https://api.wity.alphanimble.com/v1/systemone \
  -H "Authorization: Bearer $WITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Hello, no stress, but our payroll export has been failing since Monday and salaries go out tomorrow.",
    "questions": {
      "urgent": { "skill": "urgent-ticket" },
      "team": { "type": "choice", "instructions": "Which team owns this?",
                "criteria": { "billing": "Money and invoices", "product": "Something is broken", "other": "Anything else" } }
    }
  }'

Each skill answer is a normal answer of the skill's type, plus which skill version answered and how:

"urgent": {
  "type": "noul", "noul": 0.998, ...,
  "skill": { "id": "sk_4f1c…", "name": "urgent-ticket", "version": 3, "answered_by": "examples", "active": true }
}

Note

Skill questions are always answered in fast mode, the way the skill learned them, whatever reasoning the request sets for its other questions.

How a skill learns#

Until it has enough examples, a skill answers its question exactly as Wity would answer it written out. It starts learning once it has 8 examples, with at least 2 for each of two answers. Wity learns in the background, checks what it learned on examples it held back, and switches to it only if it beats its own answer on them. Add examples at any time; each change starts a new round of learning and, when it is better, a new version.

{
  "id": "sk_4f1c…", "object": "skill", "name": "urgent-ticket",
  "question": { "type": "noul", "instructions": "Does this support ticket need a reply within the hour?" },
  "examples": 72, "status": "ready", "answered_by": "examples", "active": true, "version": 3,
  "quality": { "accuracy": 0.94, "accuracy_without_skill": 0.67, "checked_on": 72 }
}

field	meaning
`status`	`needs_examples` (not enough yet), `learning`, or `ready`
`answered_by`	`question` (as asked), `examples` (what it learned), or for skills with parts `rule` or `parts`; see Parts
`active`	decisions use what the skill learned from its examples
`quality.accuracy`	how often the skill was right on its own examples, each judged by a version that never saw it
`quality.accuracy_without_skill`	Wity's answer to the question as asked, on the same examples
`version`	goes up each time the skill learns or changes; every answer names the version that gave it

How long it takes

step	typical time
Create a skill, add examples	well under a second: the call returns at once
Learn from 50 examples	about 4 to 5 seconds
Learn from 300 examples	10 to 15 seconds
Learn again after one new example	about 3 to 5 seconds
A decision with a skill	the same as the question asked plainly, plus a few milliseconds

While a skill is learning it keeps answering with the version before, so there is never a gap. Poll GET /v1/skills/{name} until status is ready if you want to wait for the new one.

Good examples#

Use real states, written the way your requests send them. A skill learns from the state and question together, so examples that look like production traffic teach the most.
Label the cases where your definition differs from the obvious reading: the angry ticket that isn't urgent, the calm one that is. Easy cases teach little.
Start with 30 to 100. A few dozen often help; with only a handful the skill may decide it can't yet beat the plain question, and stays as asked until it can. More examples keep helping up to a few hundred.
Watch quality. If accuracy is not above accuracy_without_skill, the skill is not active, and more or clearer examples are the fix. Check your labels too: one rule applied consistently beats many exceptions.
Correct it from production. In a session, feedback on a decision becomes an example with exactly what that decision read.

Change a skill#

PATCH /v1/skills/{name} renames it or changes its description, question, parts, rule or metadata. A new question, parts or rule makes the skill learn again from its examples; the name and description don't. Delete examples one by one with DELETE /v1/skills/{name}/examples/{id}. Every skill belongs to your account: other accounts can't see or use it.

Try it in the console#

The console's Skills & sessions page runs three demos on your account (a taught definition, a question split into parts, and a support thread as a session), shows each call it makes, and lets you manage your skills and sessions. The full list of endpoints is in the skills API reference.

← Forecast questions

Parts →