Building Tools that Generate Structured Data

While Large Language Models (LLMs) are adept at generating human-readable text, they can sometimes struggle to consistently produce data in strictly defined, machine-readable formats like JSON, XML, or CSV. This precision is often necessary when an LLM agent needs to interact with other software systems, APIs, or databases, or when the output needs to be stored and processed programmatically. Building tools that assist LLMs in generating well-formed structured data is therefore a significant step in expanding an agent's capabilities, enabling more reliable and complex interactions with its environment.

These tools don't replace the LLM's generative abilities; instead, they guide and constrain the LLM to ensure its output adheres to a predefined schema. This typically involves a combination of clear instructions to the LLM, schema definitions, and validation mechanisms.

Defining the Target: Specifying Schemas

The first step in building a structured data generation tool is to clearly define the structure of the data you want the LLM to produce. This definition, or schema, serves as the blueprint for the LLM and the basis for validation.

For JSON data, which is a common requirement, Python libraries like Pydantic are exceptionally useful. Pydantic allows you to define data schemas using standard Python type hints.

from pydantic import BaseModel, EmailStr, PositiveInt, field_validator
from typing import Optional, List

class UserProfile(BaseModel):
    username: str
    email: EmailStr
    age: Optional[PositiveInt] = None
    is_active: bool = True
    tags: List[str] = []
    score: float

    @field_validator('username')
    @classmethod
    def username_must_be_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError('Username must be alphanumeric and contain no spaces.')
        return v

    @field_validator('score')
    @classmethod
    def score_must_be_between_zero_and_one(cls, v: float) -> float:
        if not (0.0 <= v <= 1.0):
            raise ValueError('Score must be between 0.0 and 1.0.')
        return v

In this UserProfile model:

• Standard types like str, PositiveInt, bool, and float define expected data types.
• EmailStr is a Pydantic-provided type that validates email formats.
• Optional indicates fields that are not strictly required.
• List[str] defines a list of strings.
• Custom validators (@field_validator) can enforce more specific rules, like the format of a username or the range of a score.

For CSV data, the schema might be as simple as a list of header names and an indication of their expected data types, if necessary. For XML, you might use DTDs or XSDs, although guiding LLMs to produce valid complex XML can be more challenging and often requires more detailed prompting or post-processing.

Guiding the LLM: Prompting Strategies

Once you have a schema, the tool needs to instruct the LLM to generate data that conforms to it. Effective prompting is important here. Your prompt to the LLM should include:

1. A clear description of the task: "Generate a JSON object representing a user profile."
2. The schema definition (or a summary): You can serialize the Pydantic model structure (or JSON schema representation) into the prompt or provide a concise textual description of the fields, their types, and any constraints. For example: "The JSON object should include: username (string, alphanumeric), email (string, valid email format), age (integer, positive, optional), is_active (boolean, defaults to true), tags (list of strings, optional), and score (float, between 0.0 and 1.0)."
3. The input data (if any): If the LLM is generating structured data based on some natural language input, provide that input clearly. "Generate a user profile for 'testuser123', email '[email protected]', with a score of 0.75 and tags ['beta', 'tester']."
4. Examples (Few-Shot Prompting): Including one or two examples of valid output JSON objects can significantly improve the LLM's performance and adherence to the format.

The goal is to give the LLM enough context to understand both the content required and the structural constraints.

Validation and Refinement: Ensuring Correctness

Even with careful prompting, an LLM might occasionally produce output that doesn't perfectly match the schema. Therefore, a critical component of a structured data generation tool is a validation step.

Using our Pydantic example, after the LLM generates a JSON string, the tool would attempt to parse and validate it:

import json

# Assume 'llm_generated_json_string' is the output from the LLM
# llm_generated_json_string = '{"username": "test_user", "email": "[email protected]", "score": 0.5}' # Invalid username
# llm_generated_json_string = '{"username": "testuser", "email": "invalid-email", "score": 1.5}' # Invalid email and score

def parse_and_validate_profile(json_string: str) -> (Optional[UserProfile], Optional[str]):
    try:
        # Pydantic can parse a JSON string directly using model_validate_json
        profile = UserProfile.model_validate_json(json_string)
        return profile, None
    except ValueError as e:
        # Construct a helpful error message.
        # In a real tool, this error message can be fed back to the LLM for another attempt.
        error_details = json.loads(e.json()) if hasattr(e, 'json') else str(e)
        return None, f"Validation Error: {error_details}"

# Example usage:
# profile_instance, error = parse_and_validate_profile(llm_generated_json_string)
# if error:
#     print(f"Failed to create profile: {error}")
#     # Here, the tool could re-prompt the LLM with the error message for correction.
# else:
#     print("Successfully created profile:")
#     print(profile_instance.model_dump_json(indent=2))

If validation fails, the tool can implement a refinement loop:

1. Provide the error message from the validator back to the LLM.
2. Ask the LLM to correct its previous output based on the error.
3. Re-validate the new output. This iterative process can significantly increase the success rate of generating valid structured data.

The following diagram illustrates a common workflow for a tool that generates structured data using an LLM:

This diagram shows an agent requesting structured data. The tool uses an LLM to generate it, then validates the output. If invalid, feedback is provided to the LLM for refinement.

Format-Specific Notes

While JSON is widely used, your tools might need to generate other formats:

• CSV (Comma-Separated Values): For tabular data, LLMs can often generate CSV content quite well if given clear headers and a few examples. Validation might involve checking the number of columns per row and basic data types.
• XML (Extensible Markup Language): Generating well-formed and valid XML can be more complex due to its syntax (tags, attributes, nesting). Providing a template or a very detailed description of the expected XML structure is often necessary. Validation against an XSD or DTD is important.
• YAML (YAML Ain't Markup Language): Similar to JSON in its data modeling capabilities but with a more human-readable syntax. LLMs can generate YAML, but careful attention to indentation and syntax is required in prompts and validation.

Benefits and Design Choices

Tools for structured data generation offer several benefits:

• Reliability: They increase the likelihood of getting correctly formatted data that can be consumed by other systems.
• Interoperability: They enable LLM agents to integrate more smoothly with existing APIs and data processing pipelines.
• Reduced Post-processing: By getting the structure right at the generation stage, you reduce the need for complex and potentially fragile parsing and correction logic later.

When designing such tools, consider:

• Complexity of the Schema: Start with simpler schemas. Very complex or deeply nested structures can be challenging for LLMs to generate correctly in one go.
• Clarity of LLM Instructions: The description of the tool itself, provided to the agent framework, should clearly state what kind of structured data it generates (e.g., "Generates a JSON object representing a user profile based on input details") and what inputs it requires from the agent or user.
• Error Handling: After validation errors, consider what happens if the LLM repeatedly fails to produce valid output. Implement retry limits or fallback mechanisms.

By incorporating tools that assist in structured data generation, you equip your LLM agents to perform a wider array of tasks that depend on precise, machine-readable data formats, making them more versatile and effective.