Skip to content

Schemas

Questions

Noul

Bases: BaseSchema

A yes/no question.

Source code in system_one/schemas.py 
38
39
40
41
42
43
44
45
class Noul(BaseSchema):
    """A yes/no question."""

    model_config = ConfigDict(extra="forbid")

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

type class-attribute instance-attribute 

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

instructions class-attribute instance-attribute 

instructions: JSONValue | None = None

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 
31
32
33
34
35
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 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
class Choice(BaseSchema):
    """A pick-one question over labelled options."""

    model_config = ConfigDict(extra="forbid")

    type: Literal["choice"] = "choice"
    instructions: JSONValue | None = None
    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 class-attribute instance-attribute 

instructions: JSONValue | None = None

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 
65
66
67
68
69
70
71
72
class Score(BaseSchema):
    """An ordinal question whose criteria index is the score."""

    model_config = ConfigDict(extra="forbid")

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

type class-attribute instance-attribute 

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

instructions class-attribute instance-attribute 

instructions: JSONValue | None = None

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 
134
135
136
137
138
139
140
141
class NoulAnswer(ConfidentAnswer):
    """A yes/no answer, where `noul` is the probability the statement holds."""

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

    def _derive(self) -> float | None:
        return choice_confidence([1.0 - self.noul, self.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 
144
145
146
147
148
149
150
151
152
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

    def _derive(self) -> float | None:
        return confidence_over(self.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 
155
156
157
158
159
160
161
162
163
164
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

    def _derive(self) -> float | None:
        return confidence_over(self.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: BaseSchema

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 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
class ConfidentAnswer(BaseSchema):
    """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

    def _derive(self) -> float | None:
        """Confidence implied by the answer, or `None` if it cannot be derived."""
        raise NotImplementedError

    @model_validator(mode="after")
    def _fill_confidence(self) -> Self:
        if self.confidence is None:
            confidence = self._derive()
            if confidence is not None:
                self.confidence = round_confidence(confidence)
        return self

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 
181
182
183
184
185
186
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: BaseSchema

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

Source code in system_one/schemas.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
class SystemOneOutput(BaseSchema):
    """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: BaseSchema

Token counts, and cost where the provider reports one.

Source code in system_one/schemas.py 
173
174
175
176
177
178
class Usage(BaseSchema):
    """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

BaseSchema

Bases: BaseModel

Source code in system_one/schemas.py 
23
24
25
26
27
28
class BaseSchema(BaseModel):
    model_config = ConfigDict(
        use_enum_values=True,
        populate_by_name=True,
        from_attributes=True,
    )