Skip to content

Schemas

Questions

Noul

Bases: BaseSchema

A yes/no question.

Source code in system_one/schemas.py 
100
101
102
103
104
105
class Noul(BaseSchema):
    """A yes/no question."""

    type: Literal["noul"] = "noul"
    instructions: str
    criteria: NoulCriteria | None = None

type class-attribute instance-attribute 

type: Literal['noul'] = 'noul'

instructions instance-attribute 

instructions: str

criteria class-attribute instance-attribute 

criteria: NoulCriteria | None = None

NoulCriteria

Bases: BaseSchema

Optional descriptions of the two noul outcomes.

Source code in system_one/schemas.py 
93
94
95
96
97
class NoulCriteria(BaseSchema):
    """Optional descriptions of the two `noul` outcomes."""

    true: JSONValue | None = None
    false: JSONValue | None = None

true class-attribute instance-attribute 

true: JSONValue | None = None

false class-attribute instance-attribute 

false: JSONValue | None = None

Choice

Bases: BaseSchema

A pick-one question over labelled options.

Source code in system_one/schemas.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
class Choice(BaseSchema):
    """A pick-one question over labelled options."""

    type: Literal["choice"] = "choice"
    instructions: str
    criteria: Mapping[str, JSONValue | None] = Field(min_length=1)

    @field_validator("criteria", mode="before")
    @classmethod
    def _labels_without_descriptions(cls, value: Any) -> Any:
        if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
            return dict.fromkeys(value)
        return value

type class-attribute instance-attribute 

type: Literal['choice'] = 'choice'

instructions instance-attribute 

instructions: str

criteria class-attribute instance-attribute 

criteria: Mapping[str, JSONValue | None] = Field(
    min_length=1
)

Score

Bases: BaseSchema

An ordinal question whose criteria index is the score.

Source code in system_one/schemas.py 
123
124
125
126
127
128
class Score(BaseSchema):
    """An ordinal question whose criteria index is the score."""

    type: Literal["score"] = "score"
    instructions: str
    criteria: Sequence[JSONValue] = Field(min_length=1)

type class-attribute instance-attribute 

type: Literal['score'] = 'score'

instructions instance-attribute 

instructions: str

criteria class-attribute instance-attribute 

criteria: Sequence[JSONValue] = Field(min_length=1)

Answers

NoulAnswer

Bases: ConfidentAnswer

A yes/no answer, where noul is the probability the statement holds.

Source code in system_one/schemas.py 
173
174
175
176
177
178
179
180
181
182
183
184
class NoulAnswer(ConfidentAnswer):
    """A yes/no answer, where `noul` is the probability the statement holds."""

    type: Literal["noul"] = "noul"
    noul: float

    @classmethod
    def _derive(cls, data: Mapping[str, Any]) -> float | None:
        noul = data.get("noul")
        if not isinstance(noul, (int, float)) or isinstance(noul, bool):
            return None
        return max(float(noul), 1.0 - float(noul))

type class-attribute instance-attribute 

type: Literal['noul'] = 'noul'

noul instance-attribute 

noul: float

ChoiceAnswer

Bases: ConfidentAnswer

The selected label and, when reported, the distribution it came from.

Source code in system_one/schemas.py 
187
188
189
190
191
192
193
194
195
196
class ChoiceAnswer(ConfidentAnswer):
    """The selected label and, when reported, the distribution it came from."""

    type: Literal["choice"] = "choice"
    choice: str
    probabilities: dict[str, float] | None = None

    @classmethod
    def _derive(cls, data: Mapping[str, Any]) -> float | None:
        return confidence_over(data.get("probabilities"), choice_confidence)

type class-attribute instance-attribute 

type: Literal['choice'] = 'choice'

choice instance-attribute 

choice: str

probabilities class-attribute instance-attribute 

probabilities: dict[str, float] | None = None

ScoreAnswer

Bases: ConfidentAnswer

A probability-weighted expected score, not an argmax.

Source code in system_one/schemas.py 
199
200
201
202
203
204
205
206
207
208
209
class ScoreAnswer(ConfidentAnswer):
    """A probability-weighted expected score, not an argmax."""

    type: Literal["score"] = "score"
    score: float
    legend: dict[int, JSONValue] | None = None
    probabilities: dict[int, float] | None = None

    @classmethod
    def _derive(cls, data: Mapping[str, Any]) -> float | None:
        return confidence_over(data.get("probabilities"), score_confidence)

type class-attribute instance-attribute 

type: Literal['score'] = 'score'

score instance-attribute 

score: float

legend class-attribute instance-attribute 

legend: dict[int, JSONValue] | None = None

probabilities class-attribute instance-attribute 

probabilities: dict[int, float] | None = None

ConfidentAnswer

Bases: BaseOutput

An answer that reports how much to trust itself on one scale for every type.

The hosted API always sends confidence; _derive fills it in for providers that do not. A payload it cannot trust leaves confidence unset, because an absent confidence is honest while a fabricated 1.0 is not.

Source code in system_one/schemas.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
class ConfidentAnswer(BaseOutput):
    """An answer that reports how much to trust itself on one scale for every type.

    The hosted API always sends `confidence`; `_derive` fills it in for providers that
    do not. A payload it cannot trust leaves `confidence` unset, because an absent
    confidence is honest while a fabricated `1.0` is not.
    """

    confidence: float | None = None

    @classmethod
    def _derive(cls, data: Mapping[str, Any]) -> float | None:
        """Confidence implied by the raw payload, or `None` if it cannot be derived."""
        raise NotImplementedError

    @model_validator(mode="before")
    @classmethod
    def _fill_confidence(cls, data: Any) -> Any:
        if not isinstance(data, Mapping) or data.get("confidence") is not None:
            return data
        confidence = cls._derive(data)
        if confidence is None:
            return data
        return {**data, "confidence": round(confidence, ROUNDING)}

confidence class-attribute instance-attribute 

confidence: float | None = None

Request and response

SystemOneInput

Bases: BaseSchema

The single normalized input shared by every backend.

Source code in system_one/schemas.py 
226
227
228
229
230
231
class SystemOneInput(BaseSchema):
    """The single normalized input shared by every backend."""

    state: State
    model: str
    questions: Mapping[str, Question] = Field(min_length=1)

state instance-attribute 

state: State

model instance-attribute 

model: str

questions class-attribute instance-attribute 

questions: Mapping[str, Question] = Field(min_length=1)

SystemOneOutput

Bases: BaseOutput

Answers keyed by question name, with model and usage metadata.

Source code in system_one/schemas.py 
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
class SystemOneOutput(BaseOutput):
    """Answers keyed by question name, with model and usage metadata."""

    model: str
    usage: Usage
    answers: dict[str, Answer] = Field(default_factory=dict)
    id: str | None = None

    def _of_type(self, kind: type[AnswerT]) -> dict[str, AnswerT]:
        return {
            name: answer
            for name, answer in self.answers.items()
            if isinstance(answer, kind)
        }

    @cached_property
    def nouls(self) -> dict[str, NoulAnswer]:
        return self._of_type(NoulAnswer)

    @cached_property
    def choices(self) -> dict[str, ChoiceAnswer]:
        return self._of_type(ChoiceAnswer)

    @cached_property
    def scores(self) -> dict[str, ScoreAnswer]:
        return self._of_type(ScoreAnswer)

model instance-attribute 

model: str

usage instance-attribute 

usage: Usage

answers class-attribute instance-attribute 

answers: dict[str, Answer] = Field(default_factory=dict)

id class-attribute instance-attribute 

id: str | None = None

nouls cached property 

nouls: dict[str, NoulAnswer]

choices cached property 

choices: dict[str, ChoiceAnswer]

scores cached property 

scores: dict[str, ScoreAnswer]

Usage

Bases: BaseOutput

Token counts, and cost where the provider reports one.

Source code in system_one/schemas.py 
218
219
220
221
222
223
class Usage(BaseOutput):
    """Token counts, and cost where the provider reports one."""

    input_tokens: int
    output_tokens: int
    cost: float | None = None

input_tokens instance-attribute 

input_tokens: int

output_tokens instance-attribute 

output_tokens: int

cost class-attribute instance-attribute 

cost: float | None = None

Helpers

distribution 

distribution(probabilities: Iterable[float]) -> list[float]

Read a probability vector, rejecting anything that is not one.

Confidence derived from logits, top-k remnants or any other unnormalized vector is meaningless, so callers get a ValueError instead of a plausible number.

Source code in system_one/schemas.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def distribution(probabilities: Iterable[float]) -> list[float]:
    """Read a probability vector, rejecting anything that is not one.

    Confidence derived from logits, top-k remnants or any other unnormalized vector
    is meaningless, so callers get a `ValueError` instead of a plausible number.
    """
    values = [float(probability) for probability in probabilities]
    if not values:
        raise ValueError(EMPTY_DISTRIBUTION)
    if any(not 0.0 <= value <= 1.0 for value in values):
        message = f"probabilities must lie in [0, 1], got {values}"
        raise ValueError(message)
    total = math.fsum(values)
    if abs(total - 1.0) > PROBABILITY_TOLERANCE:
        message = f"probabilities must sum to 1, got {total}"
        raise ValueError(message)
    return values

choice_confidence 

choice_confidence(probabilities: Iterable[float]) -> float

Confidence in the selected choice: the probability of the reported label.

Source code in system_one/schemas.py 
48
49
50
def choice_confidence(probabilities: Iterable[float]) -> float:
    """Confidence in the selected choice: the probability of the reported label."""
    return max(distribution(probabilities))

score_confidence 

score_confidence(probabilities: Iterable[float]) -> float

Confidence in the expected score: 1 - 2 * sd / (k - 1).

The score is an expectation over ordered levels, so its reliability is how tightly the mass sits around it. Entropy cannot see order and would rate a distribution split between the end levels — whose expectation lands in a valley no level claims — the same as one split between neighbours.

Source code in system_one/schemas.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def score_confidence(probabilities: Iterable[float]) -> float:
    """Confidence in the expected score: `1 - 2 * sd / (k - 1)`.

    The score is an expectation over ordered levels, so its reliability is how
    tightly the mass sits around it. Entropy cannot see order and would rate a
    distribution split between the end levels — whose expectation lands in a
    valley no level claims — the same as one split between neighbours.
    """
    values = distribution(probabilities)
    if len(values) == 1:
        return 1.0
    expected = math.fsum(level * value for level, value in enumerate(values))
    variance = math.fsum(
        value * (level - expected) ** 2 for level, value in enumerate(values)
    )
    return max(0.0, 1.0 - 2.0 * math.sqrt(variance) / (len(values) - 1))

BaseSchema

Bases: BaseModel

Frozen, strict-input model whose unset optional fields stay off the wire.

The wrap serializer drops only top-level None field values, so a user-supplied criteria={"calm": None} survives while an unset instructions does not; exclude_none would drop both and exclude_unset would drop the type discriminator.

Source code in system_one/schemas.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
class BaseSchema(BaseModel):
    """Frozen, strict-input model whose unset optional fields stay off the wire.

    The wrap serializer drops only top-level ``None`` field values, so a user-supplied
    ``criteria={"calm": None}`` survives while an unset ``instructions`` does not;
    ``exclude_none`` would drop both and ``exclude_unset`` would drop the ``type``
    discriminator.
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    @model_serializer(mode="wrap")
    def _omit_none(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
        return {key: value for key, value in handler(self).items() if value is not None}