feat(decisions): serve System One format at /v1/systemone and OpenAI format at /v1/decisions

[mateo-berri]

TLDR

Problem this solves:

• /v1/decisions only spoke the System One format
• OpenAI shipped a Decisions API with a different request and response shape
• Clients written against OpenAI's API could not use the proxy

How it solves it:

• System One format moves to /v1/systemone and /systemone
• /v1/decisions and /decisions now take OpenAI's Decisions API format
• OpenAI requests get translated into System One, run through the same pipeline, and translated back
• Playground System One tab now calls /v1/systemone
• OpenAI-format requests are capped at 128 questions, the System One limit, so a bigger request gets a 400 before any upstream call
• A body that is not JSON gets a 400 instead of a 500 when the proxy runs without auth
• OpenAI-format responses keep guardrail_information when the caller sets include_guardrail_response

Intentional product change: callers sending System One bodies to /v1/decisions must switch to /v1/systemone, since /v1/decisions now expects OpenAI's shape and returns 400 otherwise

User Flow

Before: a developer using OpenAI's Decisions API format gets a 400 from the proxy

1. They send POST http://localhost:4000/v1/decisions with input and a questions list (predicate, choice, score)
2. The proxy answers 400 Invalid Decisions request because it expects state and a questions map
3. POST http://localhost:4000/v1/systemone returns 404 Not Found

After: the same OpenAI-format request returns OpenAI-format answers, and System One callers use their own route

1. They send the same POST http://localhost:4000/v1/decisions body
2. They get 200 with an answers list of typed predicate, choice and score answers plus OpenAI-style usage
3. A System One client sends its usual body to POST http://localhost:4000/v1/systemone and gets the same answers map as before
4. Both responses carry a non-zero x-litellm-response-cost header

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/unit/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Proxy started with python litellm/proxy/proxy_cli.py --config decisions_config.yaml --port 4000, calling Perplexity for real

model_list:
  - model_name: decider
    litellm_params:
      model: perplexity/pplx-decider-v1-27b
      api_key: os.environ/PERPLEXITY_API_KEY

general_settings:
  master_key: os.environ/DECISIONS_PROOF_MASTER_KEY

systemone_body.json:

{
  "model": "decider",
  "state": "Customer wrote: I was charged twice for my order #4411 and want one of the charges refunded today.",
  "questions": {
    "is_refund_request": {"type": "noul", "instructions": "Is the customer asking for a refund?"},
    "urgency": {"type": "choice", "instructions": "How urgent is this?", "criteria": {"low": "can wait a week", "high": "needs action today"}},
    "frustration": {"type": "score", "instructions": "How frustrated is the customer?", "criteria": ["calm", "mildly annoyed", "angry"]}
  }
}

openai_body.json:

{
  "model": "decider",
  "input": [{"role": "user", "type": "message", "content": [{"type": "input_text", "text": "Customer wrote: I was charged twice for my order #4411 and want one of the charges refunded today."}]}],
  "questions": [
    {"type": "predicate", "name": "is_refund_request", "instructions": "Is the customer asking for a refund?"},
    {"type": "choice", "name": "needs_human", "instructions": "Should a human agent take over?", "choices": [{"value": true, "description": "billing dispute that needs a person"}, {"value": false}]},
    {"type": "score", "name": "frustration", "instructions": "How frustrated is the customer?", "levels": [{"label": "calm"}, {"label": "mildly annoyed"}, {"label": "angry", "description": "uses hostile language"}]}
  ]
}

Before (df23f11)

System One format at /v1/systemone

1. curl -sS -i localhost:4000/v1/systemone -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' -d @systemone_body.json
2. Output:

HTTP/1.1 404 Not Found
{"detail":"Not Found"}

OpenAI format at /v1/decisions

1. curl -sS -i localhost:4000/v1/decisions -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' -d @openai_body.json
2. Output:

HTTP/1.1 400 Bad Request
x-litellm-response-cost: 0
{"error":{"message":"litellm.BadRequestError: Invalid Decisions request: 2 validation errors for DecisionsRequestBody\nstate\n  Field required [type=missing, input_value={'model': 'decider', 'inp...s hostile language'}]}]}, input_type=dict]\n    For further information visit https://errors.pydantic.dev/2.13/v/missing\nquestions\n  Input should be a valid dictionary [type=dict_type, input_value=[{'type': 'predicate', 'n...es hostile language'}]}], input_type=list]\n    For further information visit https://errors.pydantic.dev/2.13/v/dict_type","type":"invalid_request_error","param":null,"code":"400"}}

After (77872f6)

System One format at /v1/systemone

1. curl -sS -i localhost:4000/v1/systemone -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' -d @systemone_body.json
2. Output:

HTTP/1.1 200 OK
x-litellm-response-cost: 1.336e-05
{"model":"pplx-decider-v1-27b","answers":{"is_refund_request":{"type":"noul","noul":0.999578470044738},"urgency":{"type":"choice","choice":"high","confidence":0.9956760234989415,"probabilities":{"low":0.0021619882505292073,"high":0.9978380117494707}},"frustration":{"type":"score","score":0.6902205412172965,"confidence":0.4426092958331813,"legend":{"0":"calm","1":"mildly annoyed","2":"angry"},"probabilities":{"0":0.3406866307802912,"1":0.6284061972221208,"2":0.03090717199758787}}},"usage":{"input_tokens":334,"output_tokens":3}}

OpenAI format at /v1/decisions

1. curl -sS -i localhost:4000/v1/decisions -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' -d @openai_body.json
2. Output:

HTTP/1.1 200 OK
x-litellm-response-cost: 1.3520000000000001e-05
{"model":"pplx-decider-v1-27b","answers":[{"type":"predicate","name":"is_refund_request","probability":0.999578470044738},{"type":"choice","name":"needs_human","choice":true,"probabilities":[{"value":true,"probability":0.9537056989243478},{"value":false,"probability":0.0462943010756523}],"confidence":0.9074113978486955},{"type":"score","name":"frustration","score":0.5402765434232424,"probabilities":[{"value":0,"label":"calm","probability":0.4628774338253685},{"value":1,"label":"mildly annoyed","probability":0.5339685889260208},{"value":2,"label":"angry","probability":0.0031539772486107467}],"confidence":0.30095288338903103}],"usage":{"input_tokens":338,"input_tokens_details":{"cached_tokens":0,"cache_write_tokens":0},"output_tokens":3,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":341}}

After, Jev direct from TypeSafe (77872f6)

Same proxy and request bodies with model set to jev, using this config so the calls go straight to TypeSafe's own API

model_list:
  - model_name: jev
    litellm_params:
      model: typesafe/jev-latest
      api_key: os.environ/TYPESAFE_API_KEY

general_settings:
  master_key: os.environ/DECISIONS_PROOF_MASTER_KEY

System One format at /v1/systemone

1. curl -sS -i localhost:4000/v1/systemone -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' -d @jev_systemone_body.json
2. Output:

HTTP/1.1 200 OK
x-litellm-response-cost: 1.6422e-05
{"model":"jev-1.13.0","answers":{"is_refund_request":{"type":"noul","noul":0.99},"urgency":{"type":"choice","choice":"high","confidence":1.0,"probabilities":{"low":0.0,"high":1.0}},"frustration":{"type":"score","score":0.96,"confidence":0.88,"legend":{"0":"calm","1":"mildly annoyed","2":"angry"},"probabilities":{"0":0.06,"1":0.92,"2":0.02}}},"usage":{"input_tokens":391,"output_tokens":67}}

OpenAI format at /v1/decisions

1. curl -sS -i localhost:4000/v1/decisions -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' -d @jev_openai_body.json
2. Output:

HTTP/1.1 200 OK
x-litellm-response-cost: 1.6422e-05
{"model":"jev-1.13.0","answers":[{"type":"predicate","name":"is_refund_request","probability":0.99},{"type":"choice","name":"needs_human","choice":true,"probabilities":[{"value":true,"probability":0.63},{"value":false,"probability":0.37}],"confidence":0.26},{"type":"score","name":"frustration","score":0.83,"probabilities":[{"value":0,"label":"calm","probability":0.17},{"value":1,"label":"mildly annoyed","probability":0.83},{"value":2,"label":"angry","probability":0.0}],"confidence":0.74}],"usage":{"input_tokens":391,"input_tokens_details":{"cached_tokens":0,"cache_write_tokens":0},"output_tokens":61,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":452}}

Type

New Feature

Caveats (if any)

Severe

• System One bodies sent to /v1/decisions now get a 400
  • Clients on v1.106.0-dev.1 must move to /v1/systemone

Low

• input_image parts return 400 since System One is text only
• safety_identifier is accepted but not forwarded upstream
• Missing or mismatched upstream answers come back as refusal answers
• Response model is the upstream model name, same as /v1/systemone
• A config pass-through mounted at /v1/decisions still takes precedence
• Greptile's note that the route ownership tests check structure is left as is, since they mirror feat(decisions): add unified /v1/decisions endpoint for Jev-compatible providers #44236 and every route also has functional tests
• Integration suites under tests/integration were not run locally because they need Postgres and Redis

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

---

Note

Medium Risk
Breaking route contract for /v1/decisions affects existing System One clients; translation and answer-mapping logic must stay correct for predicate/choice/score edge cases.

Overview
Splits decision APIs by wire format: System One (state + keyed questions) moves to /v1/systemone and /systemone, while /v1/decisions and /decisions now accept OpenAI’s Decisions shape (input, list questions, typed answers).

OpenAI requests are validated with new Pydantic types, translated to System One via openai_transformation (predicate→noul, choice/score mapping, text state from messages), run through the same adecisions proxy path, then mapped back to OpenAI answers (including refusal when upstream data is missing). include_guardrail_response is honored on the OpenAI response path. Invalid or non-JSON bodies return 400 before upstream calls; OpenAI question count is capped at 128.

Routing/auth/OpenAPI/allowlists and the playground System One tab are updated to the new paths. Breaking: clients sending System One JSON to /v1/decisions must switch to /v1/systemone.

^{Reviewed by Cursor Bugbot for commit f360214. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds new decision endpoint format alongside existing one.

The PR appears safe to merge with the documented client migration

What we checked:

• Frozen responses still return guardrail details: The shared helper creates a new model with model_copy. OpenAIDecisionResponse allows extra fields, so the helper can add guardrail_information without changing the frozen original

Summary

This PR separates the two request formats: System One uses /v1/systemone, while OpenAI-format clients use /v1/decisions. Both use the existing Decisions request pipeline

• The latest changes preserve requested guardrail_information after converting the response to OpenAI format
• The previous guardrail finding is fixed. No new actionable issues were found
• mateo-berri explicitly accepts the route-breaking change: existing System One clients must switch routes
• mateo-berri also documents intentional limits: images are rejected, safety_identifier is not forwarded, missing or mismatched answers become refusals, the upstream model name is returned, configured pass-through routes take precedence, and structural route tests remain unchanged

_{Reviews (5) · Last reviewed commit: "refactor(decisions): validate proxy requ..." · Reviewed by Greptile}

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_systemone_endpoint (f360214) with main (03ba79d)}

[codecov]

Codecov Report

❌ Patch coverage is 98.91892% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/decisions/openai_transformation.py	95.12%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[mateo-berri]

@greptileai please re-review: non-JSON bodies now return 400, OpenAI questions are capped at 128, and integration tests use /v1/systemone

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

Kerry's stack #45129 to #44969 lands the OpenAI schema through provider configs first. This PR then rebases onto it, keeping /v1/systemone and the Playground switch

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit f360214. Configure here.}