railtracks.decisions

 1__all__ = [
 2    "Choice",
 3    "ChoiceAnswer",
 4    "DecisionAnswer",
 5    "DecisionAnswers",
 6    "DecisionInput",
 7    "DecisionProviderAuthenticationError",
 8    "DecisionProviderError",
 9    "DecisionProviderRateLimitError",
10    "DecisionProviderRefusalError",
11    "DecisionProviderTimeoutError",
12    "DecisionModel",
13    "DecisionResponse",
14    "DecisionSchema",
15    "OpenAIDecisions",
16    "OpenRouterDecisions",
17    "Predicate",
18    "PredicateAnswer",
19    "SchemaDefinitionError",
20    "Score",
21    "ScoreAnswer",
22    "TypeSafeDecisions",
23]
24
25
26from ._exceptions import (
27    DecisionProviderAuthenticationError,
28    DecisionProviderError,
29    DecisionProviderRateLimitError,
30    DecisionProviderRefusalError,
31    DecisionProviderTimeoutError,
32    SchemaDefinitionError,
33)
34from .model import DecisionModel
35from .providers import OpenAIDecisions, OpenRouterDecisions, TypeSafeDecisions
36from .response import DecisionResponse
37from .schema import (
38    Choice,
39    ChoiceAnswer,
40    DecisionAnswer,
41    DecisionAnswers,
42    DecisionSchema,
43    Predicate,
44    PredicateAnswer,
45    Score,
46    ScoreAnswer,
47)
48from .state import DecisionInput
Choice = <class 'railtracks.decisions.schema.ChoiceQuestion'>
class ChoiceAnswer(railtracks.decisions.DecisionAnswer):
50class ChoiceAnswer(DecisionAnswer):
51    """The most likely value and the probability of each value.
52
53    Attributes:
54        choice: The value with the highest probability.
55        confidence: How concentrated the probabilities are, from 0 to 1.
56        probabilities: The probability of each value.
57    """
58
59    choice: str
60    confidence: float
61    probabilities: dict[str, float]
62
63    def __str__(self) -> str:
64        probability = self.probabilities.get(self.choice, self.confidence)
65        return f"{self.choice} {probability:.2f}"

The most likely value and the probability of each value.

Attributes:
  • choice: The value with the highest probability.
  • confidence: How concentrated the probabilities are, from 0 to 1.
  • probabilities: The probability of each value.
choice: str
confidence: float
probabilities: dict[str, float]
model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class DecisionAnswer(pydantic.main.BaseModel):
31class DecisionAnswer(BaseModel):
32    """One question's answer. ``str()`` is the compact summary an agent reads."""
33
34    model_config = ConfigDict(frozen=True)

One question's answer. str() is the compact summary an agent reads.

model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class DecisionAnswers(collections.abc.Mapping[str, railtracks.decisions.schema.DecisionAnswer]):
315class DecisionAnswers(Mapping[str, DecisionAnswer]):
316    """One answer per question of a schema.
317
318    Index with a question to get its typed answer (``answers[is_urgent]`` is a
319    ``PredicateAnswer``), or with a name to get it untyped. Iterates over the question
320    names in schema order.
321    """
322
323    def __init__(
324        self, schema: DecisionSchema, answers: Mapping[str, DecisionAnswer]
325    ) -> None:
326        """Hold one answer per question.
327
328        Args:
329            schema: The schema the answers are for.
330            answers: The answers keyed by question name.
331
332        Raises:
333            ValueError: If an answer is missing, unexpected, or of the wrong type.
334        """
335        questions = schema.questions
336        unexpected = set(answers) - set(questions)
337        if unexpected:
338            raise ValueError(f"Unexpected answers: {sorted(unexpected)}")
339        for name, question in questions.items():
340            if name not in answers:
341                raise ValueError(f"Missing answer for question {name!r}")
342            if not isinstance(answers[name], question.answer_type):
343                raise ValueError(
344                    f"Answer for question {name!r} must be a {question.answer_type.__name__}, got {type(answers[name]).__name__}"
345                )
346        self._schema = schema
347        self._answers = {name: answers[name] for name in questions}
348
349    @property
350    def schema(self) -> DecisionSchema:
351        """The schema these answers are for."""
352        return self._schema
353
354    @overload
355    def __getitem__(self, key: DecisionQuestion[_TAnswer]) -> _TAnswer: ...
356
357    @overload
358    def __getitem__(self, key: str) -> DecisionAnswer: ...
359
360    def __getitem__(self, key: DecisionQuestion[Any] | str) -> DecisionAnswer:
361        if isinstance(key, DecisionQuestion):
362            # a same-named question from another schema is not this one
363            if self._schema.questions.get(key.name) is not key:
364                raise KeyError(key.name)
365            key = key.name
366        return self._answers[key]
367
368    def __iter__(self) -> Iterator[str]:
369        return iter(self._answers)
370
371    def __len__(self) -> int:
372        return len(self._answers)
373
374    def encode(self) -> dict[str, Any]:
375        """The answers as plain JSON values, in schema order."""
376        return {
377            name: answer.model_dump(mode="json")
378            for name, answer in self._answers.items()
379        }
380
381    def __repr__(self) -> str:
382        fields = ", ".join(f"{k}={v!r}" for k, v in self._answers.items())
383        return f"DecisionAnswers({fields})"

One answer per question of a schema.

Index with a question to get its typed answer (answers[is_urgent] is a PredicateAnswer), or with a name to get it untyped. Iterates over the question names in schema order.

DecisionAnswers( schema: DecisionSchema, answers: Mapping[str, DecisionAnswer])
323    def __init__(
324        self, schema: DecisionSchema, answers: Mapping[str, DecisionAnswer]
325    ) -> None:
326        """Hold one answer per question.
327
328        Args:
329            schema: The schema the answers are for.
330            answers: The answers keyed by question name.
331
332        Raises:
333            ValueError: If an answer is missing, unexpected, or of the wrong type.
334        """
335        questions = schema.questions
336        unexpected = set(answers) - set(questions)
337        if unexpected:
338            raise ValueError(f"Unexpected answers: {sorted(unexpected)}")
339        for name, question in questions.items():
340            if name not in answers:
341                raise ValueError(f"Missing answer for question {name!r}")
342            if not isinstance(answers[name], question.answer_type):
343                raise ValueError(
344                    f"Answer for question {name!r} must be a {question.answer_type.__name__}, got {type(answers[name]).__name__}"
345                )
346        self._schema = schema
347        self._answers = {name: answers[name] for name in questions}

Hold one answer per question.

Arguments:
  • schema: The schema the answers are for.
  • answers: The answers keyed by question name.
Raises:
  • ValueError: If an answer is missing, unexpected, or of the wrong type.
schema: DecisionSchema
349    @property
350    def schema(self) -> DecisionSchema:
351        """The schema these answers are for."""
352        return self._schema

The schema these answers are for.

def encode(self) -> dict[str, typing.Any]:
374    def encode(self) -> dict[str, Any]:
375        """The answers as plain JSON values, in schema order."""
376        return {
377            name: answer.model_dump(mode="json")
378            for name, answer in self._answers.items()
379        }

The answers as plain JSON values, in schema order.

DecisionInput = typing.Union[str, dict[str, typing.Any], list[typing.Any]]
class DecisionProviderAuthenticationError(railtracks.decisions.DecisionProviderError):
51class DecisionProviderAuthenticationError(DecisionProviderError):
52    """The API key is missing or was rejected. Retrying will not help."""

The API key is missing or was rejected. Retrying will not help.

class DecisionProviderError(railtracks.decisions._exceptions._NotedError):
35class DecisionProviderError(_NotedError):
36    """A call to a decision model failed. Raised only by direct model calls.
37
38    Raised as is for a failure no subclass covers: a dropped connection, a 5xx or
39    other 4xx status or a response that could not be parsed.
40    """

A call to a decision model failed. Raised only by direct model calls.

Raised as is for a failure no subclass covers: a dropped connection, a 5xx or other 4xx status or a response that could not be parsed.

class DecisionProviderRateLimitError(railtracks.decisions.DecisionProviderError):
47class DecisionProviderRateLimitError(DecisionProviderError):
48    """The host rejected the call for rate or quota reasons. Worth backing off."""

The host rejected the call for rate or quota reasons. Worth backing off.

class DecisionProviderRefusalError(railtracks.decisions.DecisionProviderError):
55class DecisionProviderRefusalError(DecisionProviderError):
56    """The model declined to answer one or more questions. Retrying will not help.
57
58    Attributes:
59        refused: The names of the questions the model declined.
60        answers: The answers it did give, keyed by question name.
61    """
62
63    def __init__(
64        self,
65        reason: str,
66        refused: list[str],
67        answers: Mapping[str, DecisionAnswer],
68        notes: list[str] | None = None,
69    ):
70        super().__init__(reason, notes=notes)
71        self.refused = list(refused)
72        self.answers = dict(answers)

The model declined to answer one or more questions. Retrying will not help.

Attributes:
  • refused: The names of the questions the model declined.
  • answers: The answers it did give, keyed by question name.
DecisionProviderRefusalError( reason: str, refused: list[str], answers: Mapping[str, DecisionAnswer], notes: list[str] | None = None)
63    def __init__(
64        self,
65        reason: str,
66        refused: list[str],
67        answers: Mapping[str, DecisionAnswer],
68        notes: list[str] | None = None,
69    ):
70        super().__init__(reason, notes=notes)
71        self.refused = list(refused)
72        self.answers = dict(answers)
refused
answers
class DecisionProviderTimeoutError(railtracks.decisions.DecisionProviderError):
43class DecisionProviderTimeoutError(DecisionProviderError):
44    """The model did not answer in time. Usually transient."""

The model did not answer in time. Usually transient.

class DecisionModel:
 78class DecisionModel:
 79    """A System One model client: answers any ``DecisionSchema`` through ``litellm.adecisions``.
 80
 81    Create a provider subclass (``TypeSafeDecisions``, ``OpenRouterDecisions``,
 82    ``OpenAIDecisions``), not this base class.
 83
 84    Attributes:
 85        provider_prefix: litellm's provider name, prefixed to the model name
 86            (``"typesafe/jev-latest"``).
 87        provider_name: Who serves the model: the response's ``provider``.
 88    """
 89
 90    provider_prefix: ClassVar[str]
 91    provider_name: ClassVar[str]
 92
 93    def __init__(
 94        self,
 95        model_name: str,
 96        *,
 97        api_key: str | None = None,
 98        api_base: str | None = None,
 99        timeout: float = 30.0,
100        retry_approach: RetryApproach | None = None,
101    ) -> None:
102        """Create a client. Nothing is sent, and no environment is read, until a call.
103
104        Args:
105            model_name: The model to ask, without the provider prefix.
106            api_key: The API key. Defaults to the provider's environment variable,
107                which litellm reads at call time.
108            api_base: The server's base URL, passed to litellm as is. Defaults to
109                litellm's own lookup (the provider's environment variable, then its
110                default URL).
111            timeout: Seconds to wait for each request.
112            retry_approach: Retry strategy for litellm's transient errors (rate
113                limits, timeouts, connection failures, 500 and 503). None (the
114                default) makes one attempt, as for LLM providers.
115
116        Raises:
117            TypeError: If the class sets no ``provider_prefix`` or ``provider_name``.
118        """
119        missing = [
120            name
121            for name in ("provider_prefix", "provider_name")
122            if not hasattr(self, name)
123        ]
124        if missing:
125            raise TypeError(
126                f"{type(self).__name__} sets no {' or '.join(missing)}; create a "
127                "provider class such as TypeSafeDecisions instead."
128            )
129        self.model_name = model_name
130        self.retry_approach = retry_approach
131        self._api_key = api_key
132        self._api_base = api_base
133        self._timeout = timeout
134
135    @property
136    def litellm_model(self) -> str:
137        """The model name litellm routes on: ``"<provider_prefix>/<model_name>"``."""
138        return f"{self.provider_prefix}/{self.model_name}"
139
140    async def aask(
141        self, state: DecisionInput, schema: DecisionSchema
142    ) -> DecisionResponse:
143        """Answer every question in ``schema`` about ``state`` in one request.
144
145        Args:
146            state: What to judge: text, or a JSON object or array (sent as JSON
147                text).
148            schema: The ``DecisionSchema`` holding the questions.
149
150        Returns:
151            The answers (``DecisionAnswers``), with model, token, latency and cost
152            metadata.
153
154        Raises:
155            DecisionProviderRefusalError: If the model declines any question.
156            DecisionProviderError: If the call fails otherwise; a subclass for a
157                timeout, rate limit or rejected key.
158        """
159        await close_client_on_loop_shutdown(self.provider_prefix)
160        start = time.perf_counter()
161        response = await self._adecisions(state, schema)
162        latency = time.perf_counter() - start
163
164        parsed = parse_response(
165            response,
166            schema,
167            requested_model_name=self.model_name,
168            provider=self.provider_name,
169            latency=latency,
170        )
171        return dataclasses.replace(
172            parsed, cost=self._cost(response, parsed.input_tokens)
173        )
174
175    def _cost(
176        self, response: LiteLLMDecisionResponse, input_tokens: int | None
177    ) -> float | None:
178        """The call's cost in USD: litellm's ``response_cost``, or None when litellm
179        could not price it. ``OpenAIDecisions`` overrides it to price input tokens only."""
180        hidden = getattr(response, "_hidden_params", None) or {}
181        return _optional_cost(hidden.get("response_cost"))
182
183    async def _adecisions(
184        self, state: DecisionInput, schema: DecisionSchema
185    ) -> LiteLLMDecisionResponse:
186        """One ``litellm.adecisions`` call, retried per ``retry_approach``."""
187
188        async def adecisions() -> LiteLLMDecisionResponse:
189            return await litellm.adecisions(
190                model=self.litellm_model,
191                input=to_input(state),
192                questions=questions_to_wire(schema),
193                api_key=self._api_key,
194                api_base=self._api_base,
195                timeout=self._timeout,
196            )
197
198        try:
199            if self.retry_approach is None:
200                return await adecisions()
201            return await self.retry_approach.acall_with_retry(adecisions)
202        except Exception as e:
203            # classify once, by the attempt the retries ended on
204            failure = e.exception_list[-1] if isinstance(e, RetryError) else e
205            error = self._provider_error(failure)
206            if error is None:
207                raise
208            if isinstance(e, RetryError):
209                error.notes.append(f"Gave up after {len(e.exception_list)} attempts.")
210            raise error from failure
211
212    def _provider_error(self, error: Exception) -> DecisionProviderError | None:
213        """The ``DecisionProviderError`` for a litellm exception; None for any other."""
214        for litellm_types, provider_type in _LITELLM_ERRORS:
215            if isinstance(error, litellm_types):
216                return provider_type(
217                    f"Decision request to {self.litellm_model} failed: {error!r}"
218                )
219        return None

A System One model client: answers any DecisionSchema through litellm.adecisions.

Create a provider subclass (TypeSafeDecisions, OpenRouterDecisions, OpenAIDecisions), not this base class.

Attributes:
  • provider_prefix: litellm's provider name, prefixed to the model name ("typesafe/jev-latest").
  • provider_name: Who serves the model: the response's provider.
DecisionModel( model_name: str, *, api_key: str | None = None, api_base: str | None = None, timeout: float = 30.0, retry_approach: railtracks.llm.retries.RetryApproach | None = None)
 93    def __init__(
 94        self,
 95        model_name: str,
 96        *,
 97        api_key: str | None = None,
 98        api_base: str | None = None,
 99        timeout: float = 30.0,
100        retry_approach: RetryApproach | None = None,
101    ) -> None:
102        """Create a client. Nothing is sent, and no environment is read, until a call.
103
104        Args:
105            model_name: The model to ask, without the provider prefix.
106            api_key: The API key. Defaults to the provider's environment variable,
107                which litellm reads at call time.
108            api_base: The server's base URL, passed to litellm as is. Defaults to
109                litellm's own lookup (the provider's environment variable, then its
110                default URL).
111            timeout: Seconds to wait for each request.
112            retry_approach: Retry strategy for litellm's transient errors (rate
113                limits, timeouts, connection failures, 500 and 503). None (the
114                default) makes one attempt, as for LLM providers.
115
116        Raises:
117            TypeError: If the class sets no ``provider_prefix`` or ``provider_name``.
118        """
119        missing = [
120            name
121            for name in ("provider_prefix", "provider_name")
122            if not hasattr(self, name)
123        ]
124        if missing:
125            raise TypeError(
126                f"{type(self).__name__} sets no {' or '.join(missing)}; create a "
127                "provider class such as TypeSafeDecisions instead."
128            )
129        self.model_name = model_name
130        self.retry_approach = retry_approach
131        self._api_key = api_key
132        self._api_base = api_base
133        self._timeout = timeout

Create a client. Nothing is sent, and no environment is read, until a call.

Arguments:
  • model_name: The model to ask, without the provider prefix.
  • api_key: The API key. Defaults to the provider's environment variable, which litellm reads at call time.
  • api_base: The server's base URL, passed to litellm as is. Defaults to litellm's own lookup (the provider's environment variable, then its default URL).
  • timeout: Seconds to wait for each request.
  • retry_approach: Retry strategy for litellm's transient errors (rate limits, timeouts, connection failures, 500 and 503). None (the default) makes one attempt, as for LLM providers.
Raises:
provider_prefix: ClassVar[str]
provider_name: ClassVar[str]
model_name
retry_approach
litellm_model: str
135    @property
136    def litellm_model(self) -> str:
137        """The model name litellm routes on: ``"<provider_prefix>/<model_name>"``."""
138        return f"{self.provider_prefix}/{self.model_name}"

The model name litellm routes on: "<provider_prefix>/<model_name>".

async def aask( self, state: Union[str, dict[str, Any], list[Any]], schema: DecisionSchema) -> DecisionResponse:
140    async def aask(
141        self, state: DecisionInput, schema: DecisionSchema
142    ) -> DecisionResponse:
143        """Answer every question in ``schema`` about ``state`` in one request.
144
145        Args:
146            state: What to judge: text, or a JSON object or array (sent as JSON
147                text).
148            schema: The ``DecisionSchema`` holding the questions.
149
150        Returns:
151            The answers (``DecisionAnswers``), with model, token, latency and cost
152            metadata.
153
154        Raises:
155            DecisionProviderRefusalError: If the model declines any question.
156            DecisionProviderError: If the call fails otherwise; a subclass for a
157                timeout, rate limit or rejected key.
158        """
159        await close_client_on_loop_shutdown(self.provider_prefix)
160        start = time.perf_counter()
161        response = await self._adecisions(state, schema)
162        latency = time.perf_counter() - start
163
164        parsed = parse_response(
165            response,
166            schema,
167            requested_model_name=self.model_name,
168            provider=self.provider_name,
169            latency=latency,
170        )
171        return dataclasses.replace(
172            parsed, cost=self._cost(response, parsed.input_tokens)
173        )

Answer every question in schema about state in one request.

Arguments:
  • state: What to judge: text, or a JSON object or array (sent as JSON text).
  • schema: The DecisionSchema holding the questions.
Returns:

The answers (DecisionAnswers), with model, token, latency and cost metadata.

Raises:
  • DecisionProviderRefusalError: If the model declines any question.
  • DecisionProviderError: If the call fails otherwise; a subclass for a timeout, rate limit or rejected key.
@dataclass(frozen=True)
class DecisionResponse:
11@dataclass(frozen=True)
12class DecisionResponse:
13    """The result of one decision request.
14
15    Attributes:
16        structured: One answer per question; index it with a question for its typed
17            answer, or with a question name.
18        model_name: The model that answered, as reported by the provider (falls back
19            to the requested name).
20        requested_model_name: The model name the client asked for.
21        provider: The provider that served the request, when reported.
22        input_tokens: Input tokens, when reported.
23        output_tokens: Output tokens, when reported.
24        latency: Seconds the call took, including retries.
25        cost: Cost in USD: litellm's ``response_cost`` for the call, except for
26            ``OpenAIDecisions``, where it is the input tokens at litellm's input price
27            (the Decisions API bills input only). None when litellm could not price
28            it.
29        raw: The response as plain JSON, for debugging.
30    """
31
32    structured: DecisionAnswers
33    model_name: str
34    requested_model_name: str
35    provider: str | None
36    input_tokens: int | None
37    output_tokens: int | None
38    latency: float
39    cost: float | None
40    raw: dict[str, Any]
41
42    def __str__(self) -> str:
43        """One ``name: answer`` segment per question, in definition order.
44
45        This is what an agent reads when the decision node is one of its tools.
46        """
47        return " | ".join(
48            f"{name}: {answer}" for name, answer in self.structured.items()
49        )
50
51    def encode(self) -> dict[str, Any]:
52        """Plain JSON for the session record; ``raw`` is left out as it repeats the answers."""
53        return {
54            "structured": self.structured.encode(),
55            "model_name": self.model_name,
56            "requested_model_name": self.requested_model_name,
57            "provider": self.provider,
58            "input_tokens": self.input_tokens,
59            "output_tokens": self.output_tokens,
60            "latency": self.latency,
61            "cost": self.cost,
62        }

The result of one decision request.

Attributes:
  • structured: One answer per question; index it with a question for its typed answer, or with a question name.
  • model_name: The model that answered, as reported by the provider (falls back to the requested name).
  • requested_model_name: The model name the client asked for.
  • provider: The provider that served the request, when reported.
  • input_tokens: Input tokens, when reported.
  • output_tokens: Output tokens, when reported.
  • latency: Seconds the call took, including retries.
  • cost: Cost in USD: litellm's response_cost for the call, except for OpenAIDecisions, where it is the input tokens at litellm's input price (the Decisions API bills input only). None when litellm could not price it.
  • raw: The response as plain JSON, for debugging.
DecisionResponse( structured: DecisionAnswers, model_name: str, requested_model_name: str, provider: str | None, input_tokens: int | None, output_tokens: int | None, latency: float, cost: float | None, raw: dict[str, typing.Any])
structured: DecisionAnswers
model_name: str
requested_model_name: str
provider: str | None
input_tokens: int | None
output_tokens: int | None
latency: float
cost: float | None
raw: dict[str, typing.Any]
def encode(self) -> dict[str, typing.Any]:
51    def encode(self) -> dict[str, Any]:
52        """Plain JSON for the session record; ``raw`` is left out as it repeats the answers."""
53        return {
54            "structured": self.structured.encode(),
55            "model_name": self.model_name,
56            "requested_model_name": self.requested_model_name,
57            "provider": self.provider,
58            "input_tokens": self.input_tokens,
59            "output_tokens": self.output_tokens,
60            "latency": self.latency,
61            "cost": self.cost,
62        }

Plain JSON for the session record; raw is left out as it repeats the answers.

class DecisionSchema:
235class DecisionSchema:
236    """The questions answered together in one decision request::
237
238        is_urgent = Predicate(name="is_urgent", instructions="The message is urgent")
239        team = Choice(
240            name="team",
241            instructions="Which team should handle this",
242            choices={"billing": "Payments and refunds", "technical": "Bugs"},
243        )
244        triage = DecisionSchema(predicate=[is_urgent], choice=[team])
245
246    Questions are ordered predicates first, then choices, then scores, each in list
247    order. A question object can be shared by several schemas.
248    """
249
250    _KINDS: ClassVar[tuple[tuple[str, type[DecisionQuestion[Any]]], ...]] = (
251        ("predicate", PredicateQuestion),
252        ("choice", ChoiceQuestion),
253        ("score", ScoreQuestion),
254    )
255
256    def __init__(
257        self,
258        *,
259        predicate: Sequence[PredicateQuestion] = (),
260        choice: Sequence[ChoiceQuestion] = (),
261        score: Sequence[ScoreQuestion] = (),
262    ) -> None:
263        """Group questions into a schema.
264
265        Args:
266            predicate: Yes/no questions (``Predicate``).
267            choice: ``Choice`` questions.
268            score: ``Score`` questions.
269
270        Raises:
271            SchemaDefinitionError: If a list holds a question of another kind, two
272                questions share a name, or there are no questions.
273        """
274        given = {"predicate": predicate, "choice": choice, "score": score}
275        questions: dict[str, DecisionQuestion[Any]] = {}
276        for kind, question_type in self._KINDS:
277            values = given[kind]
278            if not isinstance(values, (list, tuple)):
279                raise SchemaDefinitionError(
280                    f"{kind}= must be a list of {question_type.__name__}, "
281                    f"got {type(values).__name__}."
282                )
283            for question in values:
284                if not isinstance(question, question_type):
285                    raise SchemaDefinitionError(
286                        f"{kind}= holds a {type(question).__name__}, "
287                        f"not a {question_type.__name__}.",
288                    )
289                if question.name in questions:
290                    raise SchemaDefinitionError(
291                        f"Two questions are named {question.name!r}.",
292                        notes=["Question names must be unique within a schema."],
293                    )
294                questions[question.name] = question
295        if not questions:
296            raise SchemaDefinitionError(
297                "The schema has no questions.",
298                notes=["Pass at least one question in predicate=, choice= or score=."],
299            )
300        self._questions = MappingProxyType(questions)
301
302    @property
303    def questions(self) -> Mapping[str, DecisionQuestion[Any]]:
304        """Every question keyed by name, in schema order."""
305        return self._questions
306
307    def __repr__(self) -> str:
308        groups = ", ".join(
309            f"{kind}={[q.name for q in self._questions.values() if q.kind == kind]}"
310            for kind, _ in self._KINDS
311        )
312        return f"DecisionSchema({groups})"

The questions answered together in one decision request::

is_urgent = Predicate(name="is_urgent", instructions="The message is urgent")
team = Choice(
    name="team",
    instructions="Which team should handle this",
    choices={"billing": "Payments and refunds", "technical": "Bugs"},
)
triage = DecisionSchema(predicate=[is_urgent], choice=[team])

Questions are ordered predicates first, then choices, then scores, each in list order. A question object can be shared by several schemas.

DecisionSchema( *, predicate: Sequence[railtracks.decisions.schema.PredicateQuestion] = (), choice: Sequence[railtracks.decisions.schema.ChoiceQuestion] = (), score: Sequence[railtracks.decisions.schema.ScoreQuestion] = ())
256    def __init__(
257        self,
258        *,
259        predicate: Sequence[PredicateQuestion] = (),
260        choice: Sequence[ChoiceQuestion] = (),
261        score: Sequence[ScoreQuestion] = (),
262    ) -> None:
263        """Group questions into a schema.
264
265        Args:
266            predicate: Yes/no questions (``Predicate``).
267            choice: ``Choice`` questions.
268            score: ``Score`` questions.
269
270        Raises:
271            SchemaDefinitionError: If a list holds a question of another kind, two
272                questions share a name, or there are no questions.
273        """
274        given = {"predicate": predicate, "choice": choice, "score": score}
275        questions: dict[str, DecisionQuestion[Any]] = {}
276        for kind, question_type in self._KINDS:
277            values = given[kind]
278            if not isinstance(values, (list, tuple)):
279                raise SchemaDefinitionError(
280                    f"{kind}= must be a list of {question_type.__name__}, "
281                    f"got {type(values).__name__}."
282                )
283            for question in values:
284                if not isinstance(question, question_type):
285                    raise SchemaDefinitionError(
286                        f"{kind}= holds a {type(question).__name__}, "
287                        f"not a {question_type.__name__}.",
288                    )
289                if question.name in questions:
290                    raise SchemaDefinitionError(
291                        f"Two questions are named {question.name!r}.",
292                        notes=["Question names must be unique within a schema."],
293                    )
294                questions[question.name] = question
295        if not questions:
296            raise SchemaDefinitionError(
297                "The schema has no questions.",
298                notes=["Pass at least one question in predicate=, choice= or score=."],
299            )
300        self._questions = MappingProxyType(questions)

Group questions into a schema.

Arguments:
Raises:
  • SchemaDefinitionError: If a list holds a question of another kind, two questions share a name, or there are no questions.
questions: Mapping[str, railtracks.decisions.schema.DecisionQuestion[typing.Any]]
302    @property
303    def questions(self) -> Mapping[str, DecisionQuestion[Any]]:
304        """Every question keyed by name, in schema order."""
305        return self._questions

Every question keyed by name, in schema order.

class OpenAIDecisions(railtracks.decisions.DecisionModel):
 9class OpenAIDecisions(DecisionModel):
10    """OpenAI's Decisions API, e.g. ``gpt-6-luna`` (public beta since 2026-10-06).
11
12    Calls ``litellm.adecisions`` with ``openai/<model_name>``. litellm reads the key
13    from ``litellm.api_key``, then ``litellm.openai_key``, then ``OPENAI_API_KEY`` (one
14    is required), and the base URL from ``litellm.api_base``, then ``OPENAI_BASE_URL``,
15    then ``OPENAI_API_BASE``. Text and JSON input only. Guide:
16    https://developers.openai.com/api/docs/guides/decisions.
17
18    The cost counts input tokens only: the API bills input tokens alone, while
19    ``litellm.model_cost`` lists ``gpt-6-luna`` at chat prices.
20    """
21
22    provider_prefix = "openai"
23    provider_name = "openai"
24
25    def _cost(
26        self, response: LiteLLMDecisionResponse, input_tokens: int | None
27    ) -> float | None:
28        """``input_tokens`` at litellm's input price; None if litellm does not list the
29        model. Never raises."""
30        if input_tokens is None:
31            return None
32        try:
33            input_cost, _ = litellm.cost_per_token(
34                model=self.model_name, prompt_tokens=input_tokens, completion_tokens=0
35            )
36        except Exception:
37            return None
38        return float(input_cost)

OpenAI's Decisions API, e.g. gpt-6-luna (public beta since 2026-10-06).

Calls litellm.adecisions with openai/<model_name>. litellm reads the key from litellm.api_key, then litellm.openai_key, then OPENAI_API_KEY (one is required), and the base URL from litellm.api_base, then OPENAI_BASE_URL, then OPENAI_API_BASE. Text and JSON input only. Guide: https://developers.openai.com/api/docs/guides/decisions.

The cost counts input tokens only: the API bills input tokens alone, while litellm.model_cost lists gpt-6-luna at chat prices.

provider_prefix = 'openai'
provider_name = 'openai'
class OpenRouterDecisions(railtracks.decisions.DecisionModel):
 7class OpenRouterDecisions(DecisionModel):
 8    """System One models through OpenRouter's decisions endpoint.
 9
10    Model ids carry the vendor, e.g. ``typesafe/jev-1.13``; calls
11    ``litellm.adecisions`` with ``openrouter/<model_name>``. litellm reads
12    ``OPENROUTER_API_KEY`` (required) and, optionally, ``OPENROUTER_API_BASE``. Text and
13    JSON input only.
14    """
15
16    provider_prefix = "openrouter"
17    provider_name = "openrouter"

System One models through OpenRouter's decisions endpoint.

Model ids carry the vendor, e.g. typesafe/jev-1.13; calls litellm.adecisions with openrouter/<model_name>. litellm reads OPENROUTER_API_KEY (required) and, optionally, OPENROUTER_API_BASE. Text and JSON input only.

provider_prefix = 'openrouter'
provider_name = 'openrouter'
Predicate = <class 'railtracks.decisions.schema.PredicateQuestion'>
class PredicateAnswer(railtracks.decisions.DecisionAnswer):
37class PredicateAnswer(DecisionAnswer):
38    """The probability that a yes/no condition is true.
39
40    Attributes:
41        probability: The probability the condition is true, from 0 to 1.
42    """
43
44    probability: float
45
46    def __str__(self) -> str:
47        return f"{'yes' if self.probability >= 0.5 else 'no'} {self.probability:.2f}"

The probability that a yes/no condition is true.

Attributes:
  • probability: The probability the condition is true, from 0 to 1.
probability: float
model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SchemaDefinitionError(railtracks.decisions._exceptions._NotedError):
75class SchemaDefinitionError(_NotedError):
76    """A schema or question was defined wrongly. A bug in the caller's code."""

A schema or question was defined wrongly. A bug in the caller's code.

Score = <class 'railtracks.decisions.schema.ScoreQuestion'>
class ScoreAnswer(railtracks.decisions.DecisionAnswer):
68class ScoreAnswer(DecisionAnswer):
69    """An expected level on an ordered rubric.
70
71    Attributes:
72        score: The probability-weighted level; may fall between levels.
73        confidence: Confidence in the score, from 0 to 1.
74        probabilities: The probability of each level, keyed by level index.
75        legend: The rubric's level descriptions, keyed by level index.
76    """
77
78    score: float
79    confidence: float
80    probabilities: dict[int, float]
81    legend: dict[int, str]
82
83    def __str__(self) -> str:
84        return f"{self.score:.1f}/{max(self.legend)}"

An expected level on an ordered rubric.

Attributes:
  • score: The probability-weighted level; may fall between levels.
  • confidence: Confidence in the score, from 0 to 1.
  • probabilities: The probability of each level, keyed by level index.
  • legend: The rubric's level descriptions, keyed by level index.
score: float
confidence: float
probabilities: dict[int, float]
legend: dict[int, str]
model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class TypeSafeDecisions(railtracks.decisions.DecisionModel):
 7class TypeSafeDecisions(DecisionModel):
 8    """TypeSafe's hosted System One models, e.g. ``jev-latest``.
 9
10    Calls ``litellm.adecisions`` with ``typesafe/<model_name>``. litellm reads
11    ``TYPESAFE_API_KEY`` (required) and, optionally, ``TYPESAFE_API_BASE``. Text and
12    JSON input only. API: https://docs.typesafe.ai/api.
13    """
14
15    provider_prefix = "typesafe"
16    provider_name = "typesafe"

TypeSafe's hosted System One models, e.g. jev-latest.

Calls litellm.adecisions with typesafe/<model_name>. litellm reads TYPESAFE_API_KEY (required) and, optionally, TYPESAFE_API_BASE. Text and JSON input only. API: https://docs.typesafe.ai/api.

provider_prefix = 'typesafe'
provider_name = 'typesafe'