Get Structured Output Generation

Starting from the Victorious Vicuna release (January 2026) and later, using the Agent API is the preferred way of achieving this task, please refer to the Requesting structured output section of that page instead.

Supported parameters

Several parameters are avaible to better fit your needs, which must be added in your request payload:

guided_choice: the output will be exactly one of the choices.
guided_regex: the output will follow the regex pattern.
guided_json: the output will follow the JSON schema.

The following sections will give you example on how to use each of those parameters.

Guided Choices

Use the guided_choice parameter to force a model to choose one of the choices you define.
Here is an example below.

Guided Choices Example

import requests
import os

paradigm_api_key = os.environ.get("PARADIGM_API_KEY", None)

url = "https://paradigm.lighton.ai/api/v2/chat/completions"
headers = {
    "Authorization": f"Bearer {paradigm_api_key}",
    "Content-Type": "application/json",
}
payload = {
    "model": "alfred-ft5",
    "messages": [
        {"role": "user", "content": "Classify this sentiment: Alfred is wonderful!"}
    ],
    "guided_choice": ["positive", "negative"]
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(data["choices"][0]["message"]["content"])

For this example, the output should show the text positive.

Guided Regex

Use the guided_regex parameter to generate text following a regex pattern.
Here is an example below.

Guided Regex Example

import requests
import os

paradigm_api_key = os.environ.get("PARADIGM_API_KEY", None)

url = "https://paradigm.lighton.ai/api/v2/chat/completions"
headers = {
    "Authorization": f"Bearer {paradigm_api_key}",
    "Content-Type": "application/json",
}
payload = {
    "model": "alfred-ft5",
    "messages": [
        {
            "role": "user",
            "content": "Generate an example email address for Alan Turing, who works in Enigma. End in .com. Example result: alan.turing@enigma.com\n"
        }
    ],
    "guided_regex": r"\w+@\w+\.com",
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(data["choices"][0]["message"]["content"])

The output should then suggest an email address following the regex pattern as alan_turing@enigma.com for instance.

Data Integrity and ValidationJSON Schema maintains high data quality by enforcing a predefined structure and validation rules, minimizing the need for additional checks.

Create your JSON Schema

You have 2 possibilities to create your JSON schema:

Manually create a JSON schema: you can find a step-by-step guide here.
Define a Pydantic model and extract the JSON schema from it.

The Role of Stop Sequences

Stop sequences are critical in structured data tasks, marking the end of model responses to keep outputs within your schema’s structure.

Mandatory Stop SequenceAlways use an appropriate stop sequence of a model (default for mistral is stop=["</s>"]) to ensure precise model output termination, aligning with your JSON Schema.

Code example

The next examples shows how to use the guided_json parameter with an exmplicit JSON Schema as well as with a Pydantic model.

Guided JSON: Explicit Schema

import requests
import json
import os

# Get the Paradigm API key from the environment
paradigm_api_key = os.environ.get("PARADIGM_API_KEY", None)

# Define the JSON Schema for data generation
json_schema = """{
  "$defs": {
    "CarType": {
      "enum": [
        "sedan",
        "SUV",
        "Truck",
        "Coupe"
      ],
      "title": "CarType",
      "type": "string"
    }
  },
  "properties": {
    "brand": {
      "title": "Brand",
      "type": "string"
    },
    "model": {
      "title": "Model",
      "type": "string"
    },
    "car_type": {
      "$ref": "#/$defs/CarType"
    }
  },
  "required": [
    "brand",
    "model",
    "car_type"
  ],
  "title": "CarDescription",
  "type": "object"
}"""

url = "https://paradigm.lighton.ai/api/v2/chat/completions"
headers = {
    "Authorization": f"Bearer {paradigm_api_key}",
    "Content-Type": "application/json",
}
payload = {
    "model": "alfred-ft5",
    "messages": [
        {
            "role": "user",
            "content": "Generate a JSON with the brand, model and car_type of the most iconic car from the 80's",
        }
    ],
    "guided_json": json_schema
}
response = requests.post(url, json=payload, headers=headers)
response_data = response.json()

print(json.dumps(json.loads(response_data["choices"][0]["message"]["content"]), indent=2))

Guided JSON: Pydantic Model

from pydantic import BaseModel
from enum import Enum
import requests
import json
import os

paradigm_api_key = os.environ.get("PARADIGM_API_KEY", None)

class CarType(str, Enum):
    sedan = "sedan"
    suv = "SUV"
    truck = "Truck"
    coupe = "Coupe"

class CarDescription(BaseModel):
    brand: str
    model: str
    car_type: CarType

json_schema = CarDescription.model_json_schema()

url = "https://paradigm.lighton.ai/api/v2/chat/completions"
headers = {
    "Authorization": f"Bearer {paradigm_api_key}",
    "Content-Type": "application/json",
}
payload = {
    "model": "alfred-ft5",
    "messages": [
        {
            "role": "user",
            "content": "Generate a JSON with the brand, model and car_type of the most iconic car from the 80's",
        }
    ],
    "guided_json": json_schema
}
response = requests.post(url, json=payload, headers=headers)
response_data = response.json()

print(json.dumps(json.loads(response_data["choices"][0]["message"]["content"]), indent=2))

Here is an output example you can get:

{
  "brand": "Delorean",
  "model": "DMC-12",
  "car_type": "sedan"
}

Harnessing Pattern MatchingUse the pattern attribute in JSON Schema to define regular expressions (regex) for matching specific text formats. The (.+) regex is especially useful for capturing varied text segments, enabling precise extraction of desired information from texts. This feature is key for parsing specific data points from unstructured or semi-structured text.

Using Extracted Data

Leverage the structured data from your extractions to enhance databases, CRM systems, or automate workflows, boosting operational efficiency.

Accurate Pattern MatchingVerify that your JSON Schema’s regex patterns align with your text’s expected formats. Mismatches can lead to data extraction errors or inaccuracies.By employing JSON Schema, you can efficiently transform unstructured text into structured, actionable data, offering a scalable solution for data processing needs.

Conclusion

Structured outputs enrich the user experience with detailed content and ensuring application-wide data consistency. It’s crucial for applications reliant on structured data integrity.

Common Pitfalls

Excluding necessary schema properties might result in partial data outputs.
Imposing too strict constraints can restrict the AI’s ability to produce relevant content.
Neglecting to include stop sequences in API calls may cause processing issues.

API Fundamentals

Agents & Threads

Chat & AI Models

LightOn models

Document Management

Supported parameters

Guided Choices

Guided Regex

Create your JSON Schema

The Role of Stop Sequences

Code example

Using Extracted Data

Conclusion

​Supported parameters

​Guided Choices

​Guided Regex

​Guided JSON

​Create your JSON Schema

​The Role of Stop Sequences

​Code example

​Using Extracted Data

​Conclusion

Supported parameters

Guided Choices

Guided Regex

Create your JSON Schema

The Role of Stop Sequences

Code example

Using Extracted Data

Conclusion