Get Structured Output Generation

Enhance your applications with high-quality, structured output using our API’s dedicated parameters. This feature is key for creating or parsing structured data, ensuring it meets specific format and validation rules.

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-4.2",
    "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-4.2",
    "messages": [
        {
            "role": "user",
            "content": "Generate an example email address for Alan Turing, who works in Enigma. End in .com. Example result: [e-mail]\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 [e-mail] for instance.

Guided JSON

Data Integrity and Validation

JSON 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 Sequence

Always 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-4.2",
    "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-4.2",
    "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 Matching

Use 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 Matching

Verify 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.