feat: add structured LLM output support (response_format)

[Ridwannurudeen]

Summary

Adds response_format parameter to chat() and completion() methods, enabling JSON schema enforcement for predictable, machine-readable LLM output. Follows the OpenAI structured outputs specification.

• Add ResponseFormat dataclass to types.py with to_dict() serialization
• Thread response_format through all 5 LLM methods (2 public + 3 internal)
• Add --response-format and --response-format-file CLI options for both chat and completion commands
• Export ResponseFormat from the opengradient package
• Add examples/llm_structured_output.py demonstrating sentiment analysis with schema enforcement
• Add 6 unit tests covering serialization, passthrough, and all 3 LLM paths (completion, chat, streaming)

Usage

import opengradient as og

result = client.llm.chat(
    model=og.TEE_LLM.GPT_4O,
    messages=[{"role": "user", "content": "Analyze: 'Great product!'"}],
    max_tokens=200,
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "sentiment",
            "schema": {
                "type": "object",
                "properties": {
                    "label": {"type": "string", "enum": ["positive", "negative", "neutral"]},
                    "score": {"type": "number"},
                },
                "required": ["label", "score"],
            },
        },
    },
)

# Or using the typed helper:
fmt = og.ResponseFormat(type="json_schema", json_schema={...})
result = client.llm.chat(..., response_format=fmt)

CLI

opengradient chat --model openai/gpt-4o \
  --messages '[{"role":"user","content":"Classify this text"}]' \
  --response-format '{"type":"json_schema","json_schema":{...}}'

# Or from file:
opengradient chat --model openai/gpt-4o \
  --messages-file msgs.json \
  --response-format-file schema.json

Test plan

• Verify ResponseFormat.to_dict() serializes correctly (json_object and json_schema)
• Verify json_schema key is omitted when not provided
• Test completion() forwards response_format to internal method
• Test chat() non-streaming forwards response_format to internal method
• Test chat() streaming forwards response_format to internal method
• Verify dict passthrough works (no wrapping)
• Verify no breaking changes (all 21 tests pass)

Closes #155

[Ridwannurudeen]

Hi team! Just following up on this PR. It adds response_format support for structured LLM output (JSON schema enforcement), which unblocks use cases that need deterministic response shapes. CI is passing. Happy to address any feedback when you get a chance.

[adambalogh]

Thanks for contributing this! We'll also need backend changes for this to work, currently working on that

[Ridwannurudeen]

Thanks for the update @adambalogh! I see you've got a structured output implementation on aba/structured as well — yours uses TypedDict with structural validation, which is a cleaner fit for the current codebase after the recent refactors.

Given how much main has changed since this PR (Client class removal, LLM refactor, etc.), rebasing this would essentially be a rewrite. Happy to close this once yours lands.

One thing my PR has that yours doesn't yet: CLI support — --response-format and --response-format-file flags for both chat and completion commands. Happy to open a follow-up PR adding that on top of your implementation once it merges, if that'd be useful.

Let me know if there's anything else I can help with on the backend side or elsewhere.