> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawa-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Output

> Pawa AI structured output capabilities gives a way to define, request, and get JSON structured outputs directly from models for more reliable and machine-readable responses.

When utilizing language models within a lengthy process, chain, or pipeline, it is often necessary for the outputs to adhere to a specific structured format.
Structured output allows you to enforce predictable formats in model responses.

Instead of free-form text, you can guide the model to return **JSON objects, schemas, or other structured data** that is easy to parse and integrate into applications.

We offer a reliable method to obtain structured output in your desired format.
Our system includes a built-in mode for JSON output. It lets you define schemas using tools like `Pydantic` or `Zod` to enforce data types, constraints, and structure.

> **Structured Output Example**

<img src="https://mintcdn.com/sartifycoltd/h3QvoufTX15l3Mnz/images/structured%20output.png?fit=max&auto=format&n=h3QvoufTX15l3Mnz&q=85&s=9110d7ce9559c2bde9264ee414c983ba" alt="Document Parsing Example" className="w-full" width="1932" height="1216" data-path="images/structured output.png" />

## Use Cases of Structured Output

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
  <div className="rounded-xl border border-neutral-800 bg-neutral-900 p-4">
    <div className="text-lg">📄 <strong>Document Parsing</strong></div>
    <p className="text-neutral-300 text-sm mt-1">Extract and organize content from PDFs, Word files, and other unstructured documents into usable data.</p>
  </div>

  <div className="rounded-xl border border-neutral-800 bg-neutral-900 p-4">
    <div className="text-lg">🔎 <strong>Entity Extraction</strong></div>
    <p className="text-neutral-300 text-sm mt-1">Identify and capture names, dates, amounts, and other key entities from raw text with precision.</p>
  </div>

  <div className="rounded-xl border border-neutral-800 bg-neutral-900 p-4">
    <div className="text-lg">📊 <strong>Report Generation</strong></div>
    <p className="text-neutral-300 text-sm mt-1">Automatically generate structured reports from language model outputs for analytics and insights.</p>
  </div>

  <div className="rounded-xl border border-neutral-800 bg-neutral-900 p-4">
    <div className="text-lg">📝 <strong>Resume Creation</strong></div>
    <p className="text-neutral-300 text-sm mt-1">Transform plain text into professional resumes or structured job application documents.</p>
  </div>
</div>

<Note>
  **For JSON mode, it is essential to explicitly instruct the model in your prompt to output JSON and specify the desired format.**

  Custom structured outputs are more reliable and are recommended whenever possible. However, it is still advisable to iterate on your prompts.
  Use JSON mode when more flexibility in the output is required while maintaining a JSON structure, and customize it if you want to enforce a clearer format to improve reliability.
</Note>

## Why Use Structured Output?

* Ensure consistent responses
* Prevent parsing errors from free-form text
* Enable integrations with APIs, databases, or other systems
* Make automation workflows more reliable

***

## Sending Structured Output Request in Pawa AI.

> Sending request in Pawa AI you simply state your desired output format, for now the default is in JSON mode. You request the model to return the request in the specific JSON format you described in `response_format` parameter.

#### JSON Output

You can specify a `response_format` when calling the model to enforce a JSON schema.

#### Supported Schemas

For structured output, the following schema types are supported:

* **string**
* **number**
* **integer**
* **float**
* **object**
* **array**
* **boolean**
* **enum**
* **anyOf**

#### Example: Resume Information Extraction with Structured Outputs

A common use case for Structured Outputs is parsing resumes.

Resumes contain structured data such as a candidate’s name, contact details, education, and work history — but extracting this data from raw text can be error-prone. Structured Outputs ensure that the extracted data always matches a predefined schema.

***

### Step 1: Defining the Schema

```python theme={null}
from typing import List
from datetime import date
from pydantic import BaseModel, Field

class Education(BaseModel):
    institution: str = Field(description="Name of the institution")
    degree: str = Field(description="Degree obtained")
    graduation_year: int = Field(description="Year of graduation")

class Experience(BaseModel):
    company: str = Field(description="Company name")
    role: str = Field(description="Job title or role")
    start_date: date = Field(description="Job start date")
    end_date: date = Field(description="Job end date")
    responsibilities: List[str] = Field(description="List of key responsibilities")

class Resume(BaseModel):
    full_name: str = Field(description="Candidate's full name")
    email: str = Field(description="Candidate's email address")
    phone: str = Field(description="Candidate's phone number")
    education: List[Education] = Field(description="List of education records")
    experience: List[Experience] = Field(description="List of professional experiences")
    skills: List[str] = Field(description="List of candidate's skills")
```

***

### Step 2: System Prompt

The system prompt instructs the model to extract structured resume data.

```text theme={null}
Given a raw resume, carefully analyze the text and extract the relevant data into JSON format.
```

**Example Resume Text**

```
Name: Jane Doe
Email: jane.doe@example.com
Phone: +255 688067709

Education:
- B.Sc. Computer Science, UDSM, 2020

Experience:
- Software Engineer at TechCorp (Jan 2021 – Dec 2023)
  Responsibilities: Built APIs, Managed cloud infrastructure

Skills:
Python, JavaScript, AWS, Docker
```

***

### Step 3: Example API Request to Pawa AI

```json theme={null}
POST https://api.pawa-ai.com/v1/chat/request
Content-Type: application/json

{
  "model": "pawa-v1-ember-20240924",
  "messages": [
    {
      "role": "system",
      "content": [
        { "type": "text", "text": "You are an AI assistant that extracts resume information into structured JSON." }
      ]
    },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Here is a resume: Name: Jane Doe, Email: jane.doe@example.com, Phone: +1 555-123-4567, Education: B.Sc. Computer Science, MIT, 2020, Experience: Software Engineer at TechCorp (Jan 2021 – Dec 2023), Skills: Python, JavaScript, AWS, Docker" }
      ]
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "resume_schema",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "full_name": { "type": "string" },
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "education": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "institution": { "type": "string" },
                "degree": { "type": "string" },
                "graduation_year": { "type": "integer" }
              },
              "required": ["institution", "degree", "graduation_year"]
            }
          },
          "experience": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "company": { "type": "string" },
                "role": { "type": "string" },
                "start_date": { "type": "string", "format": "date" },
                "end_date": { "type": "string", "format": "date" },
                "responsibilities": {
                  "type": "array",
                  "items": { "type": "string" }
                }
              },
              "required": ["company", "role", "start_date", "end_date"]
            }
          },
          "skills": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["full_name", "email", "phone", "education", "experience", "skills"],
        "additionalProperties": false
      }
    }
  }
}
```

***

### Step 4: Example Type-Safe Output

```json theme={null}
{
  "full_name": "Jane Doe",
  "email": "jane.doe@example.com",
  "phone": "+255 768067709",
  "education": [
    {
      "institution": "UDSM",
      "degree": "B.Sc. Computer Science",
      "graduation_year": 2020
    }
  ],
  "experience": [
    {
      "company": "TechCorp",
      "role": "Software Engineer",
      "start_date": "2021-01-01",
      "end_date": "2023-12-31",
      "responsibilities": ["Built APIs", "Managed cloud infrastructure"]
    }
  ],
  "skills": ["Python", "JavaScript", "AWS", "Docker"]
}
```

***

This shows how **Pawa AI** can enforce schemas to reliably extract structured resume data.