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
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.
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.
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.
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.
349 @property 350 def schema(self) -> DecisionSchema: 351 """The schema these answers are for.""" 352 return self._schema
The schema these answers are for.
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.
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.
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.
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.
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.
43class DecisionProviderTimeoutError(DecisionProviderError): 44 """The model did not answer in time. Usually transient."""
The model did not answer in time. Usually transient.
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.
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:
- TypeError: If the class sets no
provider_prefixorprovider_name.
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>".
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
DecisionSchemaholding 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.
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_costfor the call, except forOpenAIDecisions, 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.
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.
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.
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)
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.
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.
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.
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.
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.
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.