Output format

jtbd-span-v1

Jobs, pains and gains as verbatim spans. Produced by scout-large 0.1.0, scout-large 0.1.1, scout-large 0.1.2.

Input

A text in German or English, as one string. Any length; long texts are read in overlapping 512-token windows and the results are merged.
Other languages and texts outside mobility are untested; the model still returns a valid output.
The offsets in the output count characters (Unicode code points) of exactly the string you passed in.

Guarantees

Every quote is a verbatim span of the input: text[start:end] == quote.
Items are sorted by start and never overlap.
Every item has exactly the attribute keys listed in dimensions.
relevant: false always comes with items: [].

Fields

Fields of jtbd-span-v1
Field	Type	Allowed values	Meaning	Empty case
`output_format_version` required	string (constant)	`jtbd-span-v1`	The format of this output. Always `jtbd-span-v1` for this format.	–
`relevant` required	boolean	–	Whether the text contains jobs, pains or gains in mobility at all. scout-large sets it to true when its best item clears the relevance threshold.	`false` for empty texts, texts on other subjects and texts without items; then `items` is empty.
`relevance_probability` required	number (≥ 0, ≤ 1)	–	The mean probability of the model's relevance head over the windows of the text, from 0 to 1. Informational; `relevant` itself is decided from the item scores.	–
`dimensions` required	array of string	`actor_type` `evidence_type` `evidence_scope`	The attribute dimensions the model produces for every item, a subset of `actor_type`, `evidence_type` and `evidence_scope`.	–
`items` required	array of objects	–	The jobs, pains and gains found in the text, one object per item, sorted by `start`.	An empty list is a valid result. It means the model found no item, not that something failed.
`items[].kind` required	string	`job` `pain` `gain`	`job`: something an actor is trying to get done. `pain`: a problem, obstacle, risk, cost or frustration in getting it done. `gain`: a benefit or desired improvement the actor experiences or wants.	–
`items[].quote` required	string	–	The sentence or clause the item was found in, copied verbatim from the input. Items are whole sentences or clauses; a job that spans several sentences is split.	–
`items[].start` required	integer (≥ 0)	–	Character offset where the quote starts in the input (inclusive, from 0).	–
`items[].end` required	integer (≥ 1)	–	Character offset where the quote ends in the input (exclusive). `text[start:end] == quote`.	–
`items[].score` required	number (≥ 0, ≤ 1)	–	The model's score for this span and kind, from 0 to 1. Higher is more confident; it is not a calibrated probability.	–
`items[].actor_type`	string	`individual` `worker` `organization` `public_sector` `society`	Who has the job, pain or gain. `individual`: a private person or group of users. `worker`: a person acting in their job in the domain. `organization`: a company, operator or association. `public_sector`: a state body or authority. `society`: the public at large. The model gives the type only; it does not name the actor in free text.	–
`items[].evidence_type`	string	`opinion` `anecdote` `routine` `observation` `measurement`	How directly the text supports the item, from lowest to highest: `opinion` (a belief or wish), `anecdote` (a specific experience), `routine` (a recurring practice), `observation` (what was systematically observed or reported by several people), `measurement` (a quantified result of a defined measurement or survey). When the grade is uncertain, the lower grade is the correct one.	–
`items[].evidence_scope`	string	`single` `multiple` `quantified`	How far the evidence reaches: `single` (one actor, one occurrence), `multiple` (several actors or occurrences, or a general statement), `quantified` (the quote itself states a number, share, frequency or amount).	–

Edge cases

Input	What you get
Empty or whitespace-only text	A valid output with `relevant: false` and `items: []`.
A text on another subject, or without jobs, pains or gains	`relevant: false` and `items: []`. This is a correct result, not an error.
A very long text	Read in overlapping windows; offsets always refer to the whole text you passed in.
Another language	Untested. The output stays valid, but its quality is unknown.

Versioning

Every output carries output_format_version. A change that breaks a parser (a renamed or removed field, a new required field, a changed meaning) gets a new format version; the old version stays documented. Before 1.0.0, an experimental model may change its output format in a minor release.