feat(decisions): add Parallel AI web-grounded decisions

This commit is contained in:
devin-gupta 2026-10-30 05:10:11 +00:00
parent ccc56d27ad
commit 16805dbb14
19 changed files with 392 additions and 9 deletions

View file

@ -1755,6 +1755,9 @@ if TYPE_CHECKING:
from .llms.typesafe.decisions.transformation import (
TypeSafeDecisionsConfig as TypeSafeDecisionsConfig,
)
from .llms.parallel_ai.decisions.transformation import (
ParallelAIDecisionsConfig as ParallelAIDecisionsConfig,
)
from .llms.openrouter.decisions.transformation import (
OpenRouterDecisionsConfig as OpenRouterDecisionsConfig,
)

View file

@ -162,6 +162,7 @@ LLM_CONFIG_NAMES: Final = (
"HostedVLLMRerankConfig",
"PerplexityDecisionsConfig",
"TypeSafeDecisionsConfig",
"ParallelAIDecisionsConfig",
"NaceDecisionsConfig",
"OpenRouterDecisionsConfig",
"FireworksAIDecisionsConfig",
@ -738,6 +739,7 @@ _LLM_CONFIGS_IMPORT_MAP: Final = {
"PerplexityDecisionsConfig": (".llms.perplexity.decisions.transformation", "PerplexityDecisionsConfig"),
"NaceDecisionsConfig": (".llms.nace.decisions.transformation", "NaceDecisionsConfig"),
"TypeSafeDecisionsConfig": (".llms.typesafe.decisions.transformation", "TypeSafeDecisionsConfig"),
"ParallelAIDecisionsConfig": (".llms.parallel_ai.decisions.transformation", "ParallelAIDecisionsConfig"),
"OpenRouterDecisionsConfig": (".llms.openrouter.decisions.transformation", "OpenRouterDecisionsConfig"),
"FireworksAIDecisionsConfig": (".llms.fireworks_ai.decisions.transformation", "FireworksAIDecisionsConfig"),
"CloudflareDecisionsConfig": (".llms.cloudflare.decisions.transformation", "CloudflareDecisionsConfig"),

View file

@ -604,6 +604,12 @@ def cost_per_token(
decisions_overrides: Final = decisions_pricing_fields(
litellm.model_cost.get(decisions_model_info["key"], {}) # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType] # model cost map is dynamically loaded
)
request_price: Final = decisions_overrides.get(
"input_cost_per_query", decisions_model_info.get("input_cost_per_query")
)
if isinstance(request_price, (int, float)):
# One Decisions request can answer many questions for the same flat fee.
return float(request_price), 0.0
if decisions_overrides:
return generic_cost_per_token(
model=model,

View file

@ -310,7 +310,7 @@ def ir_to_openai_response(
response: DecisionsIRResponse, request: DecisionsIRRequest, requested_model: str
) -> OpenAIDecisionResponse:
usage: Final = response.usage or DecisionsIRUsage()
return OpenAIDecisionResponse(
formatted: Final = OpenAIDecisionResponse(
model=response.model or requested_model,
answers=tuple(
_openai_answer(question, answer)
@ -327,6 +327,8 @@ def ir_to_openai_response(
total_tokens=usage.input_tokens + usage.output_tokens,
),
)
# Keep provider evidence without letting extras replace normalized fields.
return OpenAIDecisionResponse.model_validate({**response.extra, **formatted.model_dump()})
class OpenAIDecisionsConfig(BaseDecisionsConfig):

View file

@ -0,0 +1,73 @@
"""Parallel's web-grounded Decisions use System One questions with mode-based routing.
Both LiteLLM Decisions routes share this adapter. Citations describe the whole
request, so they stay on the response rather than being assigned to answers.
Contract: https://docs.parallel.ai/api-reference/decisions/make-web-grounded-typed-decisions
"""
from collections.abc import Mapping
from typing import Final
from pydantic import BaseModel, ConfigDict
from litellm.llms.base_llm.decisions.transformation import BaseDecisionsConfig, ir_to_systemone_request
from litellm.types.decisions import (
DecisionsIRRequest,
DecisionsIRResponse,
UnsupportedDecisionsRequest,
)
class _ParallelResponse(BaseModel):
model_config = ConfigDict(extra="allow", frozen=True)
mode: str
answers: Mapping[str, Mapping[str, object]]
class ParallelAIDecisionsConfig(BaseDecisionsConfig):
path = "/v1/decisions"
api_key_env = ("PARALLEL_AI_API_KEY", "PARALLEL_API_KEY")
api_base_env = ("PARALLEL_AI_API_BASE",)
def get_default_api_base(self) -> str:
return "https://api.parallel.ai"
def validate_environment(
self,
headers: Mapping[str, str],
model: str,
api_key: str | None,
litellm_params: Mapping[str, object],
) -> Mapping[str, str]:
return {
**{
name: value
for name, value in headers.items()
if name.lower() not in {"authorization", "x-api-key", "content-type"}
},
**({"x-api-key": api_key} if api_key is not None else {}),
"Content-Type": "application/json",
}
def transform_decisions_request(
self, model: str, request: DecisionsIRRequest, custom_llm_provider: str
) -> Mapping[str, object] | UnsupportedDecisionsRequest:
if len(request.questions) > 100:
return UnsupportedDecisionsRequest(reason="Parallel Decisions supports at most 100 questions")
body: Final = ir_to_systemone_request(model, request)
if isinstance(body, UnsupportedDecisionsRequest):
return body
return {"mode": model, **{key: value for key, value in body.items() if key != "model"}}
def parse_response(self, payload: object, request: DecisionsIRRequest) -> DecisionsIRResponse:
response: Final = _ParallelResponse.model_validate(payload)
# Missing answers become IR refusals in the shared System One parser.
return super().parse_response(
{
**response.model_dump(),
"model": response.mode,
"answers": {key: answer for key, answer in response.answers.items() if answer.get("type") != "refusal"},
},
request,
)

View file

@ -46248,6 +46248,15 @@
"supports_response_schema": true,
"supports_tool_choice": false
},
"parallel_ai/fast": {
"input_cost_per_query": 0.001,
"input_cost_per_token": 0.0,
"output_cost_per_token": 0.0,
"litellm_provider": "parallel_ai",
"max_input_tokens": 32000,
"mode": "evaluation",
"source": "https://docs.parallel.ai/getting-started/pricing#decisions-api"
},
"parallel_ai/search": {
"input_cost_per_query": 0.005,
"litellm_provider": "parallel_ai",

View file

@ -2613,6 +2613,34 @@
],
"default_model_placeholder": "nace/drex-latest"
},
{
"provider": "ParallelAI",
"provider_display_name": "Parallel AI",
"litellm_provider": "parallel_ai",
"credential_fields": [
{
"key": "api_base",
"label": "API Base",
"placeholder": "https://api.parallel.ai",
"tooltip": null,
"required": false,
"field_type": "text",
"options": null,
"default_value": null
},
{
"key": "api_key",
"label": "API Key",
"placeholder": null,
"tooltip": null,
"required": true,
"field_type": "password",
"options": null,
"default_value": null
}
],
"default_model_placeholder": "parallel_ai/fast"
},
{
"provider": "NEBIUS",
"provider_display_name": "Nebius",

View file

@ -210,7 +210,7 @@ class NoulAnswer(LiteLLMPydanticObjectBase):
class ChoiceAnswer(LiteLLMPydanticObjectBase):
type: Literal["choice"]
choice: str
confidence: float
confidence: float | None = None
probabilities: Mapping[str, float]
model_config = ConfigDict(extra="allow", frozen=True)
@ -219,7 +219,7 @@ class ChoiceAnswer(LiteLLMPydanticObjectBase):
class ScoreAnswer(LiteLLMPydanticObjectBase):
type: Literal["score"]
score: float
confidence: float
confidence: float | None = None
legend: Mapping[str, DecisionsJSON]
probabilities: Mapping[str, float]
@ -431,7 +431,7 @@ class OpenAIChoiceAnswer(LiteLLMPydanticObjectBase):
name: str | None
choice: str | bool
probabilities: tuple[OpenAIChoiceProbability, ...]
confidence: float
confidence: float | None = None
model_config = ConfigDict(frozen=True)
@ -449,7 +449,7 @@ class OpenAIScoreAnswer(LiteLLMPydanticObjectBase):
name: str | None
score: float
probabilities: tuple[OpenAIScoreProbability, ...]
confidence: float
confidence: float | None = None
model_config = ConfigDict(frozen=True)
@ -595,7 +595,7 @@ class DecisionsIRChoiceProbability:
@dataclass(frozen=True, slots=True)
class DecisionsIRChoiceAnswer:
choice: str | bool
confidence: float
confidence: float | None
probabilities: tuple[DecisionsIRChoiceProbability, ...]
extra: Mapping[str, object] = field(default_factory=lambda: _NO_EXTRA)
@ -610,7 +610,7 @@ class DecisionsIRScoreProbability:
@dataclass(frozen=True, slots=True)
class DecisionsIRScoreAnswer:
score: float
confidence: float
confidence: float | None
probabilities: tuple[DecisionsIRScoreProbability, ...]
extra: Mapping[str, object] = field(default_factory=lambda: _NO_EXTRA)

View file

@ -4488,6 +4488,7 @@ class LlmProviders(str, Enum):
CLF_AI_GATEWAY = "clf_ai_gateway"
PERPLEXITY = "perplexity"
TYPESAFE = "typesafe"
PARALLEL_AI = "parallel_ai"
NACE = "nace"
STRANDS_DECIDER = "strands_decider"
LAYA = "laya"

View file

@ -9991,12 +9991,19 @@ class ProviderConfigManager:
return litellm.LayaDecisionsConfig()
if provider == LlmProviders.BESPOKE:
return litellm.BespokeDecisionsConfig()
if provider in (LlmProviders.OPENAI, LlmProviders.AZURE, LlmProviders.AZURE_AI, LlmProviders.EU_JEV):
if provider in (
LlmProviders.OPENAI,
LlmProviders.AZURE,
LlmProviders.AZURE_AI,
LlmProviders.EU_JEV,
LlmProviders.PARALLEL_AI,
):
configs: Final = {
LlmProviders.OPENAI: litellm.OpenAIDecisionsConfig,
LlmProviders.AZURE: litellm.AzureDecisionsConfig,
LlmProviders.AZURE_AI: litellm.AzureAIDecisionsConfig,
LlmProviders.EU_JEV: litellm.EuJevDecisionsConfig,
LlmProviders.PARALLEL_AI: litellm.ParallelAIDecisionsConfig,
}
return configs[provider]()
return None

View file

@ -46248,6 +46248,15 @@
"supports_response_schema": true,
"supports_tool_choice": false
},
"parallel_ai/fast": {
"input_cost_per_query": 0.001,
"input_cost_per_token": 0.0,
"output_cost_per_token": 0.0,
"litellm_provider": "parallel_ai",
"max_input_tokens": 32000,
"mode": "evaluation",
"source": "https://docs.parallel.ai/getting-started/pricing#decisions-api"
},
"parallel_ai/search": {
"input_cost_per_query": 0.005,
"litellm_provider": "parallel_ai",

View file

@ -3132,7 +3132,7 @@
"batches": false,
"messages": false,
"interactions": false,
"systemone": false,
"systemone": true,
"a2a": false,
"generateContent": false
}

View file

@ -62,6 +62,21 @@ def test_apply_decisions_pricing_leaves_rows_without_decisions_fields_unchanged(
assert apply_decisions_pricing(plain_row) == plain_row
@pytest.mark.parametrize("rate", [0.0, 0.002])
def test_flat_decisions_rate_overrides_catalog_without_changing_chat(
monkeypatch: pytest.MonkeyPatch, rate: float
) -> None:
monkeypatch.setitem(
litellm.model_cost,
"gpt-6-luna",
{**litellm.model_cost["gpt-6-luna"], **_ROW, "input_cost_per_query_decisions": rate},
)
assert cost_calculator.cost_per_token(model="gpt-6-luna", prompt_tokens=100, call_type="decisions") == (rate, 0.0)
assert cost_calculator.cost_per_token(
model="gpt-6-luna", prompt_tokens=100, call_type="completion"
) == pytest.approx((100 * 1e-07, 0.0))
_LUNA_USAGE: Final = Usage(
prompt_tokens=100,
completion_tokens=10,

View file

@ -0,0 +1,213 @@
import json
from collections.abc import Mapping
from dataclasses import replace
from typing import Final
import httpx
import pytest
import respx
import litellm
from litellm.litellm_core_utils.logging_worker import GLOBAL_LOGGING_WORKER
from litellm.llms.base_llm.decisions.transformation import (
DecisionsResponseValidationError,
ir_to_systemone_response,
systemone_request_to_ir,
)
from litellm.llms.openai.decisions.transformation import ir_to_openai_response, openai_request_to_ir
from litellm.llms.parallel_ai.decisions.transformation import ParallelAIDecisionsConfig
from litellm.types.decisions import (
DecisionsIRRefusal,
DecisionsRequestBody,
OpenAIDecisionRequestBody,
UnsupportedDecisionsRequest,
)
from litellm.types.utils import LlmProviders
from litellm.utils import ProviderConfigManager
QUESTIONS: Final = {
"available": {"type": "noul", "instructions": "Is this product available?"},
"tier": {"type": "choice", "instructions": "Which tier is offered?", "criteria": {"free": "Free", "paid": "Paid"}},
"fit": {"type": "score", "instructions": "How well does it fit?", "criteria": ["Poor", "Good", "Excellent"]},
"unknown": {"type": "noul", "instructions": "Is there enough evidence?"},
}
REQUEST: Final = systemone_request_to_ir(
DecisionsRequestBody.model_validate({"state": {"product": "Example"}, "questions": QUESTIONS})
)
PAYLOAD: Final = {
"mode": "fast",
"answers": {
"available": {"type": "noul", "noul": 0.9},
"tier": {"type": "choice", "choice": "paid", "probabilities": {"free": 0.2, "paid": 0.8}},
"fit": {
"type": "score",
"score": 1.7,
"legend": {"0": "Poor", "1": "Good", "2": "Excellent"},
"probabilities": {"0": 0.1, "1": 0.1, "2": 0.8},
},
"unknown": {"type": "refusal"},
},
"usage": {"input_tokens": 4212, "output_tokens": 0},
"citations": [{"url": "https://example.com/product", "title": "Product", "excerpts": ["Available now"]}],
"decision_id": "decisions_example",
}
@pytest.mark.asyncio
@pytest.mark.parametrize("use_async", [False, True])
@pytest.mark.parametrize("surface", ["decisions", "systemone"])
async def test_sdk_sends_parallel_wire_format_and_preserves_evidence(
use_async: bool, surface: str, respx_mock: respx.MockRouter, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(litellm, "disable_aiohttp_transport", True)
litellm.in_memory_llm_clients_cache.flush_cache()
route: Final = respx_mock.post("https://api.parallel.ai/v1/decisions").respond(json=PAYLOAD)
connection: Final = {"model": "parallel_ai/fast", "api_key": "test-key", "timeout": 5, "num_retries": 0}
fields: Final = (
{"state": "Example", "questions": QUESTIONS}
if surface == "systemone"
else {
"input": "Example",
"questions": [{"type": "predicate", "name": "available", "instructions": "Available?"}],
}
)
sync_call: Final = litellm.systemone if surface == "systemone" else litellm.decisions
async_call: Final = litellm.asystemone if surface == "systemone" else litellm.adecisions
response: Final = await async_call(**connection, **fields) if use_async else sync_call(**connection, **fields)
sent: Final = route.calls.last.request
body: Final = json.loads(sent.content)
assert body["mode"] == "fast"
assert "model" not in body
assert body["state"] == "Example"
assert sent.headers["x-api-key"] == "test-key"
assert "authorization" not in sent.headers
assert response.model_dump()["citations"] == PAYLOAD["citations"]
assert response.model_dump()["decision_id"] == PAYLOAD["decision_id"]
await GLOBAL_LOGGING_WORKER.clear_queue()
def test_provider_routes_systemone_questions_to_parallel_without_a_model_field() -> None:
config: Final = ProviderConfigManager.get_provider_decisions_config("fast", LlmProviders.PARALLEL_AI)
assert config is not None
assert config.transform_decisions_request("fast", REQUEST, "parallel_ai") == {
"mode": "fast",
"state": {"product": "Example"},
"questions": QUESTIONS,
}
assert config.get_complete_url("https://gateway.example/v1/", "fast") == "https://gateway.example/v1/decisions"
def test_auth_replaces_conflicting_headers_without_forwarding_bearer_credentials() -> None:
headers: Final = ParallelAIDecisionsConfig().validate_environment(
{"Authorization": "Bearer old", "X-API-Key": "old", "CONTENT-TYPE": "text/plain", "X-Trace": "test"},
"fast",
"test-key",
{},
)
assert headers == {"x-api-key": "test-key", "Content-Type": "application/json", "X-Trace": "test"}
def test_openai_predicate_is_translated_to_a_named_noul_question() -> None:
request: Final = openai_request_to_ir(
OpenAIDecisionRequestBody.model_validate(
{
"input": "Example product",
"questions": [{"type": "predicate", "name": "available", "instructions": "Available?"}],
}
)
)
assert ParallelAIDecisionsConfig().transform_decisions_request("fast", request, "parallel_ai") == {
"mode": "fast",
"state": "Example product",
"questions": {"available": {"type": "noul", "instructions": "Available?"}},
}
@pytest.mark.parametrize("surface", ["systemone", "decisions"])
def test_all_answers_usage_and_evidence_survive_response_translation(surface: str) -> None:
response: Final = ParallelAIDecisionsConfig().parse_response(PAYLOAD, REQUEST)
assert isinstance(response.answers[3], DecisionsIRRefusal)
formatted: Final = (
ir_to_systemone_response(response, REQUEST)
if surface == "systemone"
else ir_to_openai_response(response, REQUEST, "parallel_ai/fast")
)
result: Final = formatted.model_dump(mode="json")
assert result["citations"] == PAYLOAD["citations"]
assert result["decision_id"] == PAYLOAD["decision_id"]
assert result["mode"] == "fast"
assert result["usage"]["input_tokens"] == 4212
assert result["usage"]["output_tokens"] == 0
if surface == "systemone":
assert result["answers"]["available"]["noul"] == 0.9
assert result["answers"]["tier"]["choice"] == "paid"
assert result["answers"]["fit"]["score"] == 1.7
assert "unknown" not in result["answers"]
else:
assert result["answers"][3]["type"] == "refusal"
def test_rejects_more_than_one_hundred_questions() -> None:
request: Final = systemone_request_to_ir(
DecisionsRequestBody.model_validate(
{
"state": "Example",
"questions": {str(index): QUESTIONS["available"] for index in range(101)},
}
)
)
assert isinstance(
ParallelAIDecisionsConfig().transform_decisions_request("fast", request, "parallel_ai"),
UnsupportedDecisionsRequest,
)
@pytest.mark.parametrize("confidence", [None, 0.8])
@pytest.mark.parametrize("surface", ["systemone", "decisions"])
def test_optional_confidence_is_preserved_without_inventing_a_value(confidence: float | None, surface: str) -> None:
payload: Final = {
**PAYLOAD,
"answers": {name: {**answer, "confidence": confidence} for name, answer in PAYLOAD["answers"].items()},
}
response: Final = ParallelAIDecisionsConfig().parse_response(payload, REQUEST)
formatted: Final = (
ir_to_systemone_response(response, REQUEST)
if surface == "systemone"
else ir_to_openai_response(response, REQUEST, "parallel_ai/fast")
)
answers: Final = formatted.model_dump(mode="json")["answers"]
values: Final = answers.values() if isinstance(answers, dict) else answers
assert [answer["confidence"] for answer in values if answer["type"] in {"choice", "score"}] == [confidence] * 2
def test_provider_extras_cannot_replace_normalized_response_fields() -> None:
response: Final = ParallelAIDecisionsConfig().parse_response(PAYLOAD, REQUEST)
with_collision: Final = replace(response, extra={**response.extra, "model": "wrong", "answers": [], "usage": {}})
formatted: Final = ir_to_openai_response(with_collision, REQUEST, "parallel_ai/fast")
assert formatted.model == "fast"
assert len(formatted.answers) == 4
assert formatted.usage.input_tokens == 4212
assert formatted.model_dump()["citations"] == PAYLOAD["citations"]
@pytest.mark.parametrize("tokens", [0, 100, 32000])
@pytest.mark.parametrize("call_type", ["decisions", "adecisions", "systemone", "asystemone"])
def test_request_pricing_is_independent_of_token_count(tokens: int, call_type: str) -> None:
rate: Final = litellm.model_cost["parallel_ai/fast"]["input_cost_per_query"]
cost: Final = litellm.cost_per_token(
model="parallel_ai/fast",
prompt_tokens=tokens,
completion_tokens=0,
call_type=call_type,
)
assert cost == (rate, 0.0)
@pytest.mark.parametrize(
"payload", [{"answers": {}}, {"mode": "fast", "answers": {"available": {"type": "noul", "noul": "invalid"}}}]
)
def test_malformed_provider_responses_raise_a_provider_error(payload: Mapping[str, object]) -> None:
with pytest.raises(DecisionsResponseValidationError):
ParallelAIDecisionsConfig().transform_decisions_response(
"fast", "parallel_ai", httpx.Response(200, json=payload), REQUEST
)

View file

@ -486,6 +486,7 @@ def _decisions_provider_entry(provider: str) -> ProviderCreateInfo:
(
("TypeSafe", "TypeSafe", LlmProviders.TYPESAFE),
("Nace", "Nace", LlmProviders.NACE),
("ParallelAI", "Parallel AI", LlmProviders.PARALLEL_AI),
("EU_JEV", "eu/jev", LlmProviders.EU_JEV),
),
)

View file

@ -230,6 +230,7 @@ describe("provider_info_helpers", () => {
Providers.NLP_CLOUD,
Providers.NSCALE,
Providers.OVHCLOUD,
Providers.ParallelAI,
Providers.PETALS,
Providers.PG_VECTOR,
Providers.PREDIBASE,
@ -549,6 +550,16 @@ describe("provider_info_helpers", () => {
expect(getProviderModels("Sail" as Providers, modelMap)).toEqual(["sail/openai/gpt-oss-120b"]);
});
it("lists Parallel decision models with their provider and model placeholder", () => {
const modelMap = {
"parallel_ai/fast": { litellm_provider: "parallel_ai", mode: "evaluation" },
};
expect(getProviderModels("ParallelAI", modelMap)).toEqual(["parallel_ai/fast"]);
expect(getProviderLogoAndName("parallel_ai").displayName).toBe("Parallel AI");
expect(getPlaceholder("ParallelAI")).toBe("parallel_ai/fast");
});
it("lists Nace decision models and resolves the provider name and model placeholder", () => {
const modelMap = {
"nace/drex-latest": { litellm_provider: "nace", mode: "evaluation" },

View file

@ -186,6 +186,7 @@ export enum Providers {
Triton = "Triton",
TypeSafe = "TypeSafe",
Nace = "Nace",
ParallelAI = "Parallel AI",
V0 = "V0",
VERCEL_AI_GATEWAY = "Vercel Ai Gateway",
Vertex_AI = "Vertex AI (Anthropic, Gemini, etc.)",
@ -317,6 +318,7 @@ export const provider_map: Record<string, string> = {
Triton: "triton",
TypeSafe: "typesafe",
Nace: "nace",
ParallelAI: "parallel_ai",
V0: "v0",
VERCEL_AI_GATEWAY: "vercel_ai_gateway",
Vertex_AI: "vertex_ai",
@ -500,6 +502,7 @@ const providerPlaceholderMap: Partial<Record<Providers, string>> = {
[Providers.Tencent]: "tencent/deepseek-v4-pro",
[Providers.TypeSafe]: "typesafe/jev-latest",
[Providers.Nace]: "nace/drex-latest",
[Providers.ParallelAI]: "parallel_ai/fast",
[Providers.StreamLake]: "streamlake/<model-or-endpoint>",
[Providers.Vertex_AI]: "gemini-pro",
[Providers.VolcEngine]: "volcengine/<any-model-on-volcengine>",