Turn messy AI text into clean data.

Large language models answer in free-form text. Wassitai takes that text and hands you back a validated object — the exact fields you asked for, with the right types — so your code can use it directly. No brittle string-parsing, no "sometimes it returns markdown." This guide assumes no prior experience.

The core idea

You give Wassitai two things:

1. A prompt — what you want, in plain English (e.g. "Extract the invoice from this email").
2. A schema — the shape of the answer you expect (e.g. a number and a total).

You get back an object that matches your schema, already checked for you. If the model's first answer is slightly malformed (extra markdown, a trailing comma, a number written as text), Wassitai repairs and validates it — and if it still doesn't fit, it asks the model to try again.

Two ways to use it

• The REST API — call it over HTTP from any language (JavaScript, Go, Ruby, a shell script…). Best when your app isn't in Python, or you want a hosted service.
• The Python library (wassitai) — import it and call it directly. Best inside a Python app; you get real typed objects back.

Both run the exact same engine. The playground you came from is itself built on the REST API.

Quickstart · REST

Send a POST to /v1/generate with your prompt and schema:

curl -X POST $WASSITAI_URL/v1/generate \
  -H "X-Provider-Key: $YOUR_PROVIDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "groq",
    "prompt": "Extract the invoice from: Invoice A-1, total $9.50 due April.",
    "schema": { "number": "str", "total": "float" }
  }'

Each piece:

• provider — which model service to use. Ask GET /v1/providers for the list.
• X-Provider-Key — your API key for that provider. It's sent with the request and never stored.
• prompt — the plain-English task.
• schema — the fields you want. Here, a text number and a decimal total.

To clean up text you already have (no model call, no key), POST to /v1/parse with text instead of prompt.

Quickstart · Python

pip install wassitai

from wassitai import Client
from pydantic import BaseModel

# 1. Describe the shape you want as a normal Python class.
class Invoice(BaseModel):
    number: str
    total: float

# 2. Point at a provider and ask.
client = Client.from_provider("groq", api_key="…")
invoice = client.generate("Extract the invoice: Invoice A-1, total $9.50", schema=Invoice)

print(invoice.number, invoice.total)   # A-1 9.5  — a real, typed object

Already have the text? Skip the model entirely:

from wassitai import parse

invoice = parse('{"number": "A-1", "total": 9.5}', Invoice)

Writing a schema

The schema is just "the fields I want back." You can write it three ways — pick whichever is easiest:

Field types in the simple map: str (text), int (whole number), float (decimal), bool (true/false). An unrecognised type name falls back to text — or is rejected when strict is on.

Reading the response

A successful response gives you more than just the data:

The options, explained

The four strategies, one by one

A strategy is how Wassitai coaxes structured output out of a model. Providers differ in what they support, so there are three real methods plus auto:

What the pipeline does

Every response runs through six small steps. You don't have to think about them — but this is what's happening under the hood:

If validation fails, Wassitai shows the model its own failed answer and asks it to correct it — up to a small retry limit — instead of giving up.

When things go wrong

The REST API maps failures to standard HTTP status codes, so you can handle them like any other request:

Every error body carries an error_type — with one exception, the unhandled 500 above, which is plain text and has no JSON to read at all, so check the status before you parse. That string — not the status code alone — is what to branch on. Several failures share 422: ParseError and its two narrower forms ExtractionError (the model answered prose) and RepairError (the JSON was past repairing), plus SchemaError, ValidationError, RenderError and ConfigurationError. Match on the names you handle and treat the rest as one fallback, rather than enumerating them exhaustively — the list grows.

In Python, a validation failure raises a ParseError. Its .diagnostics name the stage that failed and quote the validator's message, including which field didn't fit, and .raw_response holds what the model actually said. There is no .field_errors attribute on the exception; structured per-field entries are a REST-only convenience, at record.result.error.field_errors, when you send include_record.

Next steps

• Open the playground and run a real request — every option above is a control you can try.
• Browse the interactive API reference to see every endpoint and field.
• Click Integrate ↗ in the playground to copy a ready-to-paste cURL or Python snippet for your exact request.