{"ok":true,"model":"20261004T084408Z-r21-s42s7-soup-h42","docs":{"sdk":"import { Arthur } from \"@patina/arthur\"; const arthur = new Arthur({ apiKey }); await arthur.parse(text, schema, { context })","parse":{"method":"POST","path":"/v1/parse","auth":"Authorization: Bearer <api key>","body":"{ text, schema, context? }","schema":"entities (names, or name -> description), optional relations (names, or name -> {from?, to?}; use descriptive, Wikidata-style names such as 'headquarters location' or 'employer') and optional actions (name -> {args: {name: 'type' | 'type[]' (many) | 'type?' (optional)}, returns?, effect?})","context":"a list, oldest first, of {said}, {showed: [items]}, {selected: [ids]}, {focus: id} and {text}; an item is a string or {id?, title?, type?, ...fields}","result":"{confidence?, entities: [{id, text, start, end, type: Choice, refersTo?: Choice}], relations: [{from, to, type: Choice}], actions?: [{id: 'a1', action: Choice, args: {name: Value}}]}; Choice = {value, confidence, alternatives?}; Value = {entity} | {action: 'a1'} | {ref} | {text}; offsets are UTF-16 code units; words the app can't act on are entities of type 'unsupported'; no actions means a remark or nothing the schema serves; the serving model is in the X-Arthur-Model header","limits":"64 KB bodies, 2,000-character requests with actions, 4,000-character texts without, 30 requests a minute per key"},"examples_model":"20261004T084408Z-r21-s42s7-soup-h42","use_cases":[{"title":"Extract entities","features":"E","shows":"Typed spans, each with a confidence. Give each entity type a name, or a name and a description.","sdk":"await arthur.parse(\"Marie Curie won the Nobel Prize in Physics in 1903.\", {\"entities\":[\"person\",\"award\",\"field\",\"date\"]})","rest":"curl -s https://api.patinasystems.com/v1/parse -H \"Authorization: Bearer $ARTHUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"Marie Curie won the Nobel Prize in Physics in 1903.\",\"schema\":{\"entities\":[\"person\",\"award\",\"field\",\"date\"]}}'","request":{"text":"Marie Curie won the Nobel Prize in Physics in 1903.","schema":{"entities":["person","award","field","date"]}},"response":{"entities":[{"id":"e1","text":"Marie Curie","start":0,"end":11,"type":{"value":"person","confidence":0.9959}},{"id":"e2","text":"Nobel Prize","start":20,"end":31,"type":{"value":"award","confidence":0.5802}},{"id":"e3","text":"Physics","start":35,"end":42,"type":{"value":"field","confidence":0.7069}},{"id":"e4","text":"1903","start":46,"end":50,"type":{"value":"date","confidence":0.9424}}],"relations":[]}},{"title":"Extract relations","features":"ER","shows":"Links between entities, with optional `from` and `to` types. Name relations descriptively, in the style of Wikidata properties (\"headquarters location\", \"employer\", \"chief executive officer\"), not terse snake_case: the model reads the name.","sdk":"await arthur.parse(\"Tim Cook runs Apple from Cupertino.\", {\"entities\":[\"person\",\"company\",\"city\"],\"relations\":{\"chief executive officer\":{\"from\":\"company\",\"to\":\"person\"},\"headquarters location\":{\"from\":\"company\",\"to\":\"city\"}}})","rest":"curl -s https://api.patinasystems.com/v1/parse -H \"Authorization: Bearer $ARTHUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"Tim Cook runs Apple from Cupertino.\",\"schema\":{\"entities\":[\"person\",\"company\",\"city\"],\"relations\":{\"chief executive officer\":{\"from\":\"company\",\"to\":\"person\"},\"headquarters location\":{\"from\":\"company\",\"to\":\"city\"}}}}'","request":{"text":"Tim Cook runs Apple from Cupertino.","schema":{"entities":["person","company","city"],"relations":{"chief executive officer":{"from":"company","to":"person"},"headquarters location":{"from":"company","to":"city"}}}},"response":{"entities":[{"id":"e1","text":"Tim Cook","start":0,"end":8,"type":{"value":"person","confidence":0.947}},{"id":"e2","text":"Apple","start":14,"end":19,"type":{"value":"company","confidence":0.9979}},{"id":"e3","text":"Cupertino","start":25,"end":34,"type":{"value":"city","confidence":0.9939}}],"relations":[{"from":"e2","to":"e3","type":{"value":"headquarters location","confidence":0.7341}}]}},{"title":"Run actions","features":"EA","shows":"Each action word becomes an action, in order. \"the kitchen lights\" is an implied search (a1), and `turn off` takes its output as `{ action: \"a1\" }`; `lock` takes the front door entity directly.","sdk":"await arthur.parse(\"turn off the kitchen lights and lock the front door\", {\"entities\":{\"light\":\"a light or lamp\",\"door\":\"a door with a smart lock\",\"room\":\"a room in the house\"},\"actions\":{\"turn off\":{\"args\":{\"lights\":\"light[]\"}},\"lock\":{\"args\":{\"doors\":\"door[]\"}}}})","rest":"curl -s https://api.patinasystems.com/v1/parse -H \"Authorization: Bearer $ARTHUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"turn off the kitchen lights and lock the front door\",\"schema\":{\"entities\":{\"light\":\"a light or lamp\",\"door\":\"a door with a smart lock\",\"room\":\"a room in the house\"},\"actions\":{\"turn off\":{\"args\":{\"lights\":\"light[]\"}},\"lock\":{\"args\":{\"doors\":\"door[]\"}}}}}'","request":{"text":"turn off the kitchen lights and lock the front door","schema":{"entities":{"light":"a light or lamp","door":"a door with a smart lock","room":"a room in the house"},"actions":{"turn off":{"args":{"lights":"light[]"}},"lock":{"args":{"doors":"door[]"}}}}},"response":{"entities":[{"id":"e1","text":"turn off","start":0,"end":8,"type":{"value":"turn off","confidence":1}},{"id":"e2","text":"kitchen","start":13,"end":20,"type":{"value":"room","confidence":0.9991}},{"id":"e3","text":"lock","start":32,"end":36,"type":{"value":"lock","confidence":0.9996}},{"id":"e4","text":"front door","start":41,"end":51,"type":{"value":"door","confidence":0.9749}}],"relations":[{"from":"e1","to":"e2","type":{"value":"lights","confidence":1}},{"from":"e3","to":"e4","type":{"value":"doors","confidence":0.9598}}],"actions":[{"id":"a1","action":{"value":"search","confidence":1},"args":{"room":[{"entity":"e2"}]}},{"id":"a2","action":{"value":"turn off","confidence":0.9997},"args":{"lights":{"action":"a1"}}},{"id":"a3","action":{"value":"lock","confidence":0.9992},"args":{"doors":[{"entity":"e4"}]}}]}},{"title":"Photos: ask the user","features":"EA","shows":"Two photos titled \"beach\" are on screen. When the parser finds a reference tied between entries, `refersTo` comes back with equal confidences and `arthur.unsure` lists it, so the app asks.","sdk":"await arthur.parse(\"share the beach one with Mara\", {\"entities\":{\"photo\":\"a photo\",\"album\":\"a photo album\",\"place\":\"where it was taken\",\"date\":\"when it was taken\",\"person\":\"someone\"},\"actions\":{\"add to album\":{\"args\":{\"photos\":\"photo[]\",\"album\":\"album\"}},\"share\":{\"args\":{\"photos\":\"photo[]\",\"with\":\"person[]\"}},\"delete\":{\"args\":{\"photos\":\"photo[]\"},\"effect\":\"destructive\"}}}, { context: [{\"said\":\"show me the Lisbon photos\"},{\"showed\":[{\"id\":\"IMG_0412\",\"title\":\"beach\",\"type\":\"photo\"},{\"id\":\"IMG_0419\",\"title\":\"beach\",\"type\":\"photo\"},{\"id\":\"IMG_0433\",\"title\":\"tram\",\"type\":\"photo\"}]}] })","rest":"curl -s https://api.patinasystems.com/v1/parse -H \"Authorization: Bearer $ARTHUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"share the beach one with Mara\",\"schema\":{\"entities\":{\"photo\":\"a photo\",\"album\":\"a photo album\",\"place\":\"where it was taken\",\"date\":\"when it was taken\",\"person\":\"someone\"},\"actions\":{\"add to album\":{\"args\":{\"photos\":\"photo[]\",\"album\":\"album\"}},\"share\":{\"args\":{\"photos\":\"photo[]\",\"with\":\"person[]\"}},\"delete\":{\"args\":{\"photos\":\"photo[]\"},\"effect\":\"destructive\"}}},\"context\":[{\"said\":\"show me the Lisbon photos\"},{\"showed\":[{\"id\":\"IMG_0412\",\"title\":\"beach\",\"type\":\"photo\"},{\"id\":\"IMG_0419\",\"title\":\"beach\",\"type\":\"photo\"},{\"id\":\"IMG_0433\",\"title\":\"tram\",\"type\":\"photo\"}]}]}'","request":{"text":"share the beach one with Mara","schema":{"entities":{"photo":"a photo","album":"a photo album","place":"where it was taken","date":"when it was taken","person":"someone"},"actions":{"add to album":{"args":{"photos":"photo[]","album":"album"}},"share":{"args":{"photos":"photo[]","with":"person[]"}},"delete":{"args":{"photos":"photo[]"},"effect":"destructive"}}},"context":[{"said":"show me the Lisbon photos"},{"showed":[{"id":"IMG_0412","title":"beach","type":"photo"},{"id":"IMG_0419","title":"beach","type":"photo"},{"id":"IMG_0433","title":"tram","type":"photo"}]}]},"response":{"entities":[{"id":"e1","text":"share","start":0,"end":5,"type":{"value":"share","confidence":1}},{"id":"e2","text":"Mara","start":25,"end":29,"type":{"value":"person","confidence":1}}],"relations":[{"from":"e1","to":"e2","type":{"value":"with","confidence":1}}],"actions":[{"id":"a1","action":{"value":"share","confidence":1},"args":{"with":[{"entity":"e2"}]}}]},"note":"With the served model this request comes back without a reference: \"the beach one\" isn't marked, so the share action has no `photos` argument and nothing is close. The same request on the same checkpoint in float32 on a Mac returned all three photos tied at 0.33. The unit tests hold the tie shape (`tests/test_serve_api.py`)."},{"title":"Photos: a follow-up with an ordinal","features":"EA","shows":"\"the second one\" is pinned by the ordinal rule at confidence 1.0, so there is nothing to ask.","sdk":"await arthur.parse(\"share the second one with Mara\", {\"entities\":{\"photo\":\"a photo\",\"album\":\"a photo album\",\"place\":\"where it was taken\",\"date\":\"when it was taken\",\"person\":\"someone\"},\"actions\":{\"add to album\":{\"args\":{\"photos\":\"photo[]\",\"album\":\"album\"}},\"share\":{\"args\":{\"photos\":\"photo[]\",\"with\":\"person[]\"}},\"delete\":{\"args\":{\"photos\":\"photo[]\"},\"effect\":\"destructive\"}}}, { context: [{\"said\":\"show me the Lisbon photos\"},{\"showed\":[{\"id\":\"IMG_0412\",\"title\":\"Alfama at dusk\",\"type\":\"photo\"},{\"id\":\"IMG_0419\",\"title\":\"Tram 28\",\"type\":\"photo\"},{\"id\":\"IMG_0433\",\"title\":\"Belém tower\",\"type\":\"photo\"}]}] })","rest":"curl -s https://api.patinasystems.com/v1/parse -H \"Authorization: Bearer $ARTHUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"share the second one with Mara\",\"schema\":{\"entities\":{\"photo\":\"a photo\",\"album\":\"a photo album\",\"place\":\"where it was taken\",\"date\":\"when it was taken\",\"person\":\"someone\"},\"actions\":{\"add to album\":{\"args\":{\"photos\":\"photo[]\",\"album\":\"album\"}},\"share\":{\"args\":{\"photos\":\"photo[]\",\"with\":\"person[]\"}},\"delete\":{\"args\":{\"photos\":\"photo[]\"},\"effect\":\"destructive\"}}},\"context\":[{\"said\":\"show me the Lisbon photos\"},{\"showed\":[{\"id\":\"IMG_0412\",\"title\":\"Alfama at dusk\",\"type\":\"photo\"},{\"id\":\"IMG_0419\",\"title\":\"Tram 28\",\"type\":\"photo\"},{\"id\":\"IMG_0433\",\"title\":\"Belém tower\",\"type\":\"photo\"}]}]}'","request":{"text":"share the second one with Mara","schema":{"entities":{"photo":"a photo","album":"a photo album","place":"where it was taken","date":"when it was taken","person":"someone"},"actions":{"add to album":{"args":{"photos":"photo[]","album":"album"}},"share":{"args":{"photos":"photo[]","with":"person[]"}},"delete":{"args":{"photos":"photo[]"},"effect":"destructive"}}},"context":[{"said":"show me the Lisbon photos"},{"showed":[{"id":"IMG_0412","title":"Alfama at dusk","type":"photo"},{"id":"IMG_0419","title":"Tram 28","type":"photo"},{"id":"IMG_0433","title":"Belém tower","type":"photo"}]}]},"response":{"entities":[{"id":"e1","text":"share","start":0,"end":5,"type":{"value":"share","confidence":1}},{"id":"e2","text":"the second one","start":6,"end":20,"type":{"value":"context","confidence":1},"refersTo":{"value":{"ref":"IMG_0419"},"confidence":1}},{"id":"e3","text":"Mara","start":26,"end":30,"type":{"value":"person","confidence":1}}],"relations":[{"from":"e1","to":"e2","type":{"value":"photos","confidence":1}},{"from":"e1","to":"e3","type":{"value":"with","confidence":1}}],"actions":[{"id":"a1","action":{"value":"share","confidence":1},"args":{"photos":{"entity":"e2"},"with":[{"entity":"e3"}]}}]}},{"title":"Photos: confirm and hand off","features":"EA","shows":"The app knows `delete` is destructive and confirms it. \"blurry\" is a word the schema can't act on, so it comes back as an `unsupported` entity for the app to hand to a language model or drop.","sdk":"await arthur.parse(\"delete the blurry ones from yesterday\", {\"entities\":{\"photo\":\"a photo\",\"album\":\"a photo album\",\"place\":\"where it was taken\",\"date\":\"when it was taken\",\"person\":\"someone\"},\"actions\":{\"add to album\":{\"args\":{\"photos\":\"photo[]\",\"album\":\"album\"}},\"share\":{\"args\":{\"photos\":\"photo[]\",\"with\":\"person[]\"}},\"delete\":{\"args\":{\"photos\":\"photo[]\"},\"effect\":\"destructive\"}}})","rest":"curl -s https://api.patinasystems.com/v1/parse -H \"Authorization: Bearer $ARTHUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"delete the blurry ones from yesterday\",\"schema\":{\"entities\":{\"photo\":\"a photo\",\"album\":\"a photo album\",\"place\":\"where it was taken\",\"date\":\"when it was taken\",\"person\":\"someone\"},\"actions\":{\"add to album\":{\"args\":{\"photos\":\"photo[]\",\"album\":\"album\"}},\"share\":{\"args\":{\"photos\":\"photo[]\",\"with\":\"person[]\"}},\"delete\":{\"args\":{\"photos\":\"photo[]\"},\"effect\":\"destructive\"}}}}'","request":{"text":"delete the blurry ones from yesterday","schema":{"entities":{"photo":"a photo","album":"a photo album","place":"where it was taken","date":"when it was taken","person":"someone"},"actions":{"add to album":{"args":{"photos":"photo[]","album":"album"}},"share":{"args":{"photos":"photo[]","with":"person[]"}},"delete":{"args":{"photos":"photo[]"},"effect":"destructive"}}}},"response":{"entities":[{"id":"e1","text":"delete","start":0,"end":6,"type":{"value":"delete","confidence":1}},{"id":"e2","text":"blurry","start":11,"end":17,"type":{"value":"unsupported","confidence":0.9966}},{"id":"e3","text":"yesterday","start":28,"end":37,"type":{"value":"date","confidence":1}}],"relations":[{"from":"e1","to":"e3","type":{"value":"photos","confidence":0.6926}},{"from":"e3","to":"e2","type":{"value":"qualified by","confidence":0.9284}}],"actions":[{"id":"a1","action":{"value":"search","confidence":1},"args":{"date":[{"entity":"e3"}],"unsupported":[{"entity":"e2"}]}},{"id":"a2","action":{"value":"delete","confidence":0.9999},"args":{"photos":{"action":"a1"}}}]}},{"title":"CRM: log a call","features":"ERA","shows":"`log call` plus the declared `employer` relation, in one request. Declared relations are scored between the action's entities after the actions are parsed.","sdk":"await arthur.parse(\"log a call with Priya Shah from Northwind about the renewal\", {\"entities\":{\"person\":\"a contact\",\"company\":\"a business or organization\",\"date\":\"a day or time\"},\"actions\":{\"email\":{\"description\":\"send an email to people\",\"args\":{\"to\":\"person[]\",\"subject\":\"text?\"}},\"create deal\":{\"description\":\"open a sales deal with a company\",\"args\":{\"company\":\"company\",\"owner\":\"person?\",\"close date\":\"date?\"},\"returns\":\"deal\"},\"log call\":{\"description\":\"record a phone call with a contact\",\"args\":{\"with\":\"person\",\"subject\":\"text?\"}}},\"relations\":{\"employer\":{\"from\":\"person\",\"to\":\"company\"}}})","rest":"curl -s https://api.patinasystems.com/v1/parse -H \"Authorization: Bearer $ARTHUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"log a call with Priya Shah from Northwind about the renewal\",\"schema\":{\"entities\":{\"person\":\"a contact\",\"company\":\"a business or organization\",\"date\":\"a day or time\"},\"actions\":{\"email\":{\"description\":\"send an email to people\",\"args\":{\"to\":\"person[]\",\"subject\":\"text?\"}},\"create deal\":{\"description\":\"open a sales deal with a company\",\"args\":{\"company\":\"company\",\"owner\":\"person?\",\"close date\":\"date?\"},\"returns\":\"deal\"},\"log call\":{\"description\":\"record a phone call with a contact\",\"args\":{\"with\":\"person\",\"subject\":\"text?\"}}},\"relations\":{\"employer\":{\"from\":\"person\",\"to\":\"company\"}}}}'","request":{"text":"log a call with Priya Shah from Northwind about the renewal","schema":{"entities":{"person":"a contact","company":"a business or organization","date":"a day or time"},"actions":{"email":{"description":"send an email to people","args":{"to":"person[]","subject":"text?"}},"create deal":{"description":"open a sales deal with a company","args":{"company":"company","owner":"person?","close date":"date?"},"returns":"deal"},"log call":{"description":"record a phone call with a contact","args":{"with":"person","subject":"text?"}}},"relations":{"employer":{"from":"person","to":"company"}}}},"response":{"entities":[{"id":"e1","text":"log","start":0,"end":3,"type":{"value":"log call","confidence":0.9998}},{"id":"e2","text":"Priya Shah","start":16,"end":26,"type":{"value":"person","confidence":1}},{"id":"e3","text":"Northwind","start":32,"end":41,"type":{"value":"company","confidence":1}},{"id":"e4","text":"renewal","start":52,"end":59,"type":{"value":"text","confidence":0.9998}}],"relations":[{"from":"e1","to":"e2","type":{"value":"with","confidence":0.9973}},{"from":"e1","to":"e4","type":{"value":"subject","confidence":0.9399}}],"actions":[{"id":"a1","action":{"value":"log call","confidence":0.9984},"args":{"subject":{"entity":"e4"},"with":{"entity":"e2"}}},{"id":"a2","action":{"value":"search","confidence":1},"args":{"company":[{"entity":"e3"}]}}]},"note":"Here the action and its arguments are right, but `employer` between Priya Shah and Northwind stays under the 0.5 threshold, so no relation comes back. On \"email Dana from Acme about the renewal\" with the same schema, `employer` from Dana to Acme comes back at 0.5293."},{"title":"Calendar: out of scope","features":"EA","shows":"No actions means a remark, or nothing the schema serves: the app hands the text to a chat model.","sdk":"await arthur.parse(\"tell me a joke\", {\"entities\":{\"event\":\"a calendar event\",\"date\":\"a day or time\",\"person\":\"an attendee\",\"place\":\"where an event is\"},\"actions\":{\"create event\":{\"args\":{\"title\":\"text\",\"when\":\"date\",\"with\":\"person[]?\"},\"returns\":\"event\"},\"cancel event\":{\"args\":{\"events\":\"event[]\"}}}})","rest":"curl -s https://api.patinasystems.com/v1/parse -H \"Authorization: Bearer $ARTHUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"tell me a joke\",\"schema\":{\"entities\":{\"event\":\"a calendar event\",\"date\":\"a day or time\",\"person\":\"an attendee\",\"place\":\"where an event is\"},\"actions\":{\"create event\":{\"args\":{\"title\":\"text\",\"when\":\"date\",\"with\":\"person[]?\"},\"returns\":\"event\"},\"cancel event\":{\"args\":{\"events\":\"event[]\"}}}}}'","request":{"text":"tell me a joke","schema":{"entities":{"event":"a calendar event","date":"a day or time","person":"an attendee","place":"where an event is"},"actions":{"create event":{"args":{"title":"text","when":"date","with":"person[]?"},"returns":"event"},"cancel event":{"args":{"events":"event[]"}}}}},"response":{"entities":[{"id":"e1","text":"tell me a joke","start":0,"end":14,"type":{"value":"unsupported","confidence":0.9997}}],"relations":[]},"note":"\"what's the weather tomorrow in Seattle?\" (the contract's example) currently comes back as a search for tomorrow in Seattle, not as no actions: the route head misses it."}],"features":{"E":{"name":"Entities","returns":"typed spans of the text: `entities`, each with a `type` choice"},"R":{"name":"Relations","returns":"links between entities: `relations`, each with a `type` choice"},"A":{"name":"Actions","returns":"action words, their arguments as relations from the word, and `actions` ready to run, in order"}},"dropping":"Dropping a schema key turns that feature off. Without `actions`, the result has no action words, no `actions`, no `unsupported` words and no top-level `confidence`; without `relations` (and `actions`), it has no `relations`."}}