Structured Data

Get model responses that adhere to a JSON schema for reliable data extraction and structured outputs.

ASI1 supports structured output through the response_format parameter, ensuring responses conform to your specified JSON schema. This is essential for building reliable applications that parse model outputs programmatically.

Quick Start with OpenAI SDK

The simplest way to get structured output is using the OpenAI SDK with response_format:

1import os
2import json
3from openai import OpenAI
4
5client = OpenAI(
6 api_key=os.getenv("ASI_ONE_API_KEY"),
7 base_url="https://api.asi1.ai/v1"
8)
9
10response = client.chat.completions.create(
11 model="asi1",
12 messages=[
13 {"role": "system", "content": "Extract the requested information as JSON."},
14 {"role": "user", "content": "Extract: John Smith is a 32 year old software engineer from San Francisco."}
15 ],
16 response_format={
17 "type": "json_schema",
18 "json_schema": {
19 "name": "person_info",
20 "strict": True,
21 "schema": {
22 "type": "object",
23 "properties": {
24 "name": {"type": "string"},
25 "age": {"type": "integer"},
26 "occupation": {"type": "string"},
27 "city": {"type": "string"}
28 },
29 "required": ["name", "age", "occupation", "city"],
30 "additionalProperties": False
31 }
32 }
33 }
34)
35
36result = json.loads(response.choices[0].message.content)
37print(f"Name: {result['name']}")
38print(f"Age: {result['age']}")
39print(f"Occupation: {result['occupation']}")
40print(f"City: {result['city']}")

LangChain with Pydantic Models

For Python developers, LangChain’s with_structured_output provides a cleaner, type-safe approach:

1import os
2from langchain_openai import ChatOpenAI
3from pydantic import BaseModel, Field
4from typing import List
5
6# Define your schema as a Pydantic model
7class Product(BaseModel):
8 """A product extracted from text."""
9 name: str = Field(description="Product name")
10 price: float = Field(description="Price in USD")
11 category: str = Field(description="Product category")
12
13class ProductList(BaseModel):
14 """A list of products."""
15 products: List[Product] = Field(description="List of extracted products")
16
17llm = ChatOpenAI(
18 model="asi1",
19 base_url="https://api.asi1.ai/v1",
20 api_key=os.getenv("ASI_ONE_API_KEY"),
21)
22
23# Create a structured output chain
24structured_llm = llm.with_structured_output(ProductList)
25
26text = """
27Our store has the following items:
28- Wireless Mouse ($29.99) - Electronics
29- Organic Coffee Beans ($14.50) - Groceries
30- Running Shoes ($89.00) - Sports
31"""
32
33result = structured_llm.invoke(f"Extract all products from this text:\n{text}")
34
35for product in result.products:
36 print(f"- {product.name}: ${product.price} ({product.category})")

Complex Schema Example

Here’s a more comprehensive example with nested objects and arrays:

1import os
2import json
3from openai import OpenAI
4
5client = OpenAI(
6 api_key=os.getenv("ASI_ONE_API_KEY"),
7 base_url="https://api.asi1.ai/v1"
8)
9
10# Complex schema with nested objects
11response_format = {
12 "type": "json_schema",
13 "json_schema": {
14 "name": "order_summary",
15 "strict": True,
16 "schema": {
17 "type": "object",
18 "additionalProperties": False,
19 "properties": {
20 "order_id": {"type": "string"},
21 "customer": {
22 "type": "object",
23 "additionalProperties": False,
24 "properties": {
25 "name": {"type": "string"},
26 "email": {"type": "string"}
27 },
28 "required": ["name", "email"]
29 },
30 "items": {
31 "type": "array",
32 "items": {
33 "type": "object",
34 "additionalProperties": False,
35 "properties": {
36 "sku": {"type": "string"},
37 "name": {"type": "string"},
38 "quantity": {"type": "integer"},
39 "unit_price": {"type": "number"}
40 },
41 "required": ["sku", "name", "quantity", "unit_price"]
42 }
43 },
44 "total": {"type": "number"},
45 "currency": {"type": "string"}
46 },
47 "required": ["order_id", "customer", "items", "total", "currency"]
48 }
49 }
50}
51
52response = client.chat.completions.create(
53 model="asi1",
54 messages=[
55 {"role": "system", "content": "Generate order data matching the schema."},
56 {"role": "user", "content": "Create a sample order for customer Jane Doe (jane@example.com) with 2 items totaling $150."}
57 ],
58 response_format=response_format
59)
60
61order = json.loads(response.choices[0].message.content)
62print(json.dumps(order, indent=2))

Raw Requests Example

For direct API integration without SDKs:

Python

1import os
2import json
3import requests
4from typing import List
5from openai import OpenAI
6
7
8# ---- Config from environment ----
9LLM_API_ENDPOINT = os.getenv("LLM_API_ENDPOINT", "https://api.asi1.ai/v1")
10LLM_API_KEY = os.getenv("LLM_API_KEY", "your-api-key")
11LLM_MODEL = os.getenv("LLM_MODEL", "asi1")
12
13# Initialize OpenAI client with ASI1 API
14client = OpenAI(
15 api_key=LLM_API_KEY,
16 base_url=LLM_API_ENDPOINT
17)
18
19headers = {
20 "Authorization": f"Bearer {LLM_API_KEY}",
21 "Content-Type": "application/json",
22}
23
24# ---- Target JSON schema (order summary) ----
25response_format = {
26 "type": "json_schema",
27 "json_schema": {
28 "name": "order_summary",
29 "strict": True,
30 "schema": {
31 "type": "object",
32 "additionalProperties": False,
33 "properties": {
34 "order_id": {"type": "string"},
35 "total": {"type": "number"},
36 "currency": {"type": "string"},
37 "items": {
38 "type": "array",
39 "minItems": 1,
40 "items": {
41 "type": "object",
42 "additionalProperties": False,
43 "properties": {
44 "sku": {"type": "string"},
45 "name": {"type": "string"},
46 "qty": {"type": "integer", "minimum": 1},
47 "unit_price": {"type": "number"}
48 },
49 "required": ["sku", "name", "qty", "unit_price"]
50 }
51 }
52 },
53 "required": ["order_id", "total", "currency", "items"]
54 }
55 }
56}
57
58prompt = (
59 "Generate a realistic example order summary with 2–3 items. "
60 "Use USD as ISO currency code. Fill every required field. "
61 "The order id is 1234567890. "
62 "The total is 100. "
63 "The currency is USD. "
64 "The items are 100. "
65 "The unit price is 1."
66)
67
68# ---- Chat Completions payload ----
69payload = {
70 "model": LLM_MODEL,
71 "messages": [
72 {"role": "system", "content": "Return ONLY valid JSON matching the provided schema."},
73 {"role": "user", "content": prompt},
74 ],
75 "response_format": response_format,
76}
77
78resp = requests.post(
79 f"{LLM_API_ENDPOINT}/chat/completions",
80 headers=headers,
81 json=payload,
82 timeout=60,
83)
84
85# Raw response
86if not resp.ok:
87 print(resp.status_code, resp.text)
88 resp.raise_for_status()
89
90data = resp.json()
91
92# Simple parse of final JSON content
93try:
94 content = (
95 (data.get("choices") or [{}])[0]
96 .get("message", {})
97 .get("content", "")
98 )
99 parsed = json.loads(content) if content else None
100except Exception:
101 parsed = None
102
103print("\n=== Output ===")
104print(json.dumps(parsed, indent=2) if parsed is not None else "None")

Example Output

$=== Output ===
${
> "currency": "USD",
> "items": [
> {
> "name": "Wireless Bluetooth Earbuds",
> "qty": 40,
> "sku": "WBE-001",
> "unit_price": 1.0
> },
> {
> "name": "USB-C Charging Cable (6ft)",
> "qty": 35,
> "sku": "UCC-002",
> "unit_price": 1.0
> },
> {
> "name": "Phone Stand - Adjustable",
> "qty": 25,
> "sku": "PSA-003",
> "unit_price": 1.0
> }
> ],
> "order_id": "1234567890",
> "total": 100.0
>}

Best Practices

Schema Design

PracticeDescription
Use strict: trueEnsures output exactly matches your schema
Set additionalProperties: falsePrevents extra fields in response
Include all fields in requiredGuarantees complete responses
Add description to propertiesHelps the model understand field purpose

Validation

1import json
2from pydantic import BaseModel, ValidationError
3
4class Person(BaseModel):
5 name: str
6 age: int
7 city: str
8
9# Always validate model output
10try:
11 content = response.choices[0].message.content
12 data = json.loads(content)
13 person = Person(**data) # Pydantic validation
14except json.JSONDecodeError:
15 print("Model returned invalid JSON")
16except ValidationError as e:
17 print(f"Schema validation failed: {e}")

Notes

  • Always validate and sanitize structured output before using in production
  • Use strict: true for reliable schema adherence
  • LangChain’s with_structured_output handles validation automatically
  • For complex extraction tasks, provide clear examples in your prompt