SAIDEX — Documentation¶

Structured AI Data EXtraction: validated Pydantic models from LLM responses — with automatic retry, fallback, and an agentic tool loop.

Documentation map¶

Document	What it covers
Quickstart	Installation, core API, first working example
Extraction	`extract_data_from_text` and `extract_data` in depth
Batch Extraction	`extract_data_list` / `extract_data_list_from_text` — return `list[ModelT]` from one call
Extraction Modes	Tool calling vs. raw JSON (no tool-calling required)
Agent Loop	`extract_data_with_tools` / `run_extractor_agent` — let the LLM call your tools before the final answer
Retry & Fallback	Validation retries, network retries, fallback models, error handling
Schema Design	Which types to use, field descriptions, types to avoid
Built-in Field Types & Validators	Reusable types the library ships (`IsoDateStr`, `IbanStr`, `IsinStr`, …)
Pydantic Validators	Pre/post/model validators, computed fields, patterns, pitfalls
External Validators	Pass your own `validator` callable for cross-field, stateful, or reference-data checks that re-enter the retry loop
Source Grounding	Mark fields with `Grounded` / `GroundedField` so extracted values are verified against the source text (anti-hallucination)
Image Extraction	Multimodal messages, OpenAI Vision, local vLLM
Observability	Callbacks, Langfuse, LangSmith, logging, async/sync
LangGraph: SaidexToolNode	Drop-in `ToolNode` replacement that repairs, validates and corrects agentic tool calls

All examples are runnable Python files in the examples/ directory.

File	Demonstrates
`01_extract_from_text.py`	Basic text → Pydantic model
`02_chat_history.py`	Multi-turn LangChain messages → model
`03_with_fallback.py`	Primary + fallback model
`04_custom_retry_config.py`	Custom `RetryConfig` + `create_instance_safe` standalone
`05_image_analysis.py`	Image URL, local file, vLLM, multiple images
`06_pydantic_validators.py`	All four validator types + computed fields
`07_json_mode.py`	Extraction without tool calling (raw JSON)
`08_agent_tools.py`	Agentic tool loop: `Tool`, `extract_data_with_tools`, `run_extractor_agent`
`10_batch_extraction.py`	Batch extraction → `list[ModelT]`: `extract_data_list_from_text`
`11_quality_analytics.py`	Aggregate field issues across runs: `summarize_field_issues`
`12_external_validator.py`	External `validator` callable: cross-field rule that re-enters the retry loop
`13_source_grounding.py`	Source grounding: `Grounded` / `GroundedField` verify values against the text
`15_openai_compatible_gateway.py`	`ToolCallConfig`: tool calling against gateways that reject OpenAI-only flags
`16_langgraph_toolnode.py`	`SaidexToolNode`: validated tool calling in a LangGraph agent
`17_salvage_partial_results.py`	`on_exhausted`: keep the valid items when every retry fails

I want to…

…run my first extraction → Quickstart
…use a model that does not support tool calling → Extraction Modes — JSON
…pass a chat history instead of plain text → Extraction
…extract many repeated records (line items, attendees) as a list → Batch Extraction
…let the LLM look things up with my own tools first → Agent Loop
…make extraction more reliable with retries → Retry & Fallback
…understand which Pydantic types to use → Schema Design
…validate a date/IBAN/country code field with one annotation → Built-in Types
…clean messy LLM output (currency symbols, date formats) → Validators — mode='before'
…add cross-field rules (end > start, total = sum) → Validators — mode='after'
…validate against a database, business rule, or running total → External Validators
…make sure the model only returns values present in the document → Source Grounding
…extract data from images → Image Extraction
…add tracing with Langfuse or LangSmith → Observability
…call the library from synchronous code → Observability — Sync usage
…validate and correct tool calls in a LangGraph agent → LangGraph: SaidexToolNode