Unstract: Turning PDFs and Scans into JSON with Prompt-Defined Schemas

The Problem: Unstructured Documents Are a Schema Nightmare

Finance, insurance, healthcare, and KYC teams all face the same wall: invoices, contracts, scans, and ID documents arrive in formats that shift per vendor and per layout. The traditional answer is to write regex patterns and build a separate template for each document type. That approach breaks when a new vendor appears or a form changes layout. Unstract takes a different route. Instead of hard-coding extraction rules, you describe the data you want in plain language, and the LLM does the mapping. The output is structured JSON, ready for a database. The README frames the difference sharply: schema definition without Unstract means writing regex and building templates per vendor, while with Unstract you write a prompt once and it handles variations. For teams that process a high volume of heterogeneous documents, that shift removes a large maintenance burden. It is not for hobbyists who want a one-off parser; it is for groups that need a repeatable pipeline from raw files to clean records.

Prompt Studio: Where the Extraction Schema Is Born

The core authoring surface is the Prompt Studio. The README describes it as a place to define document extraction schemas with natural language. You do not write JSON Schema or XML mappings. Instead, you tell the model what fields to pull, and it infers the structure from the document content. The tool includes a GIF in the repository, but the README text does not detail the exact UI controls or how you validate outputs during authoring. What is clear is that the prompt you write becomes the reusable extraction definition. That means the quality of your extraction depends on the quality of your prompt engineering, not on your regex skills. The documentation link points to a dedicated intro page, which would be the source for specifics like test modes or field-level tuning. Without that page, I cannot confirm whether the Studio supports versioning or A/B testing of prompts. The repository layout suggests a web frontend, but the README alone does not describe the editing workflow in depth.

Three Deployment Modes: API, ETL, and MCP

Unstract is not a single script. It offers three distinct ways to consume the extraction. The first is API deployment: you send a document over REST and receive JSON back. That suits request-response integrations like a mobile app that photographs a receipt or a web portal that ingests a PDF. The second is an ETL pipeline: pull documents from a folder, process them, and load the results to your warehouse. That fits batch workloads where files accumulate in a shared drive or object store. The third is an MCP server, which connects to AI agents like Claude via the Model Context Protocol. That is a newer pattern, letting an agent call the extraction tool as part of a larger reasoning loop. The README also mentions an n8n node, so you can drop extraction into existing automation workflows without writing custom glue code. Each mode targets a different integration surface, and the platform seems designed to cover both synchronous and asynchronous use cases. The ETL mode is the one that aligns with the 'pipeline' part of the project's tagline, and it is where the warehouse loading logic lives, though the README does not specify which warehouses are supported.

Running the Platform: Docker and a Single Script

The quickstart is deliberately short. You need Linux or macOS, Docker and Docker Compose, at least 8 GB of RAM, and Git. Then you clone the repository, change into the directory, and run ./run-platform.sh. That script handles the rest, pulling images and starting the platform. The README gives no manual docker-compose up command; the wrapper script is the intended entry point. It offers several flags: -v pins a version tag, -u upgrades an existing setup, -b builds images locally, -d runs in detached mode, -e only sets up environment files, and -p only pulls images. For example, ./run-platform.sh -u -v v0.2.0 upgrades to a specific release. After startup, you visit http://frontend.unstract.localhost and log in with username unstract and password unstract. That default credential is a security consideration: anyone with network access to that host can log in until you change it. The script also sets up environment files, and the README warns you to copy the ENCRYPTION_KEY value from backend/.env or platform-service/.env to a secure location, because that key encrypts adapter credentials.

The Encryption Key Is a Single Point of Failure

The README contains a stark warning about the ENCRYPTION_KEY. It encrypts adapter credentials, and losing it makes existing adapters inaccessible. That is a genuine operational risk. If you lose the key or the environment file is deleted, you cannot recover the stored credentials for your LLM providers or any external services. The platform offers no visible recovery mechanism in the README. This is a classic secret-management trap: the key sits in a .env file on the host, and if that host is not backed up properly, you are locked out. For production use, you must treat that key like a database password and store it in a vault or a secure backup. The README does not mention rotation procedures or integration with external secret managers, so you are on your own for that. This is a case where the convenience of a single script hides a critical dependency. Teams that are careless with environment files will learn this the hard way.

Licence and Maintenance Implications

Unstract is released under AGPL-3.0. That is a strong copyleft licence. If you modify the platform and offer it as a network service, you may need to release your modifications under the same licence. For internal use where you do not distribute the software, the obligations are lighter, but you should consult a lawyer for your specific situation. The project is actively maintained, with releases dated September 2026 and a version number at v0.188.0. That indicates a rapid release cadence, roughly one version every few days. The README shows badges for pre-commit, SonarCloud quality gate, and Docker pulls, but those do not tell you about long-term maintenance cost. The platform is composed of multiple services: frontend, backend, worker, and platform service, as shown in the architecture diagram. That means upgrades are not a single binary swap; you need to run the upgrade script and test across components. The repository uses uv for Python, Vite and Bun for the frontend, and Biome for linting, which points to a modern toolchain. The active release schedule is a double-edged sword: you get fixes, but you also need to track breaking changes between versions.

Where Unstract Is the Wrong Tool

Unstract is not a fit for every document problem. If your documents are already machine-readable text with a fixed, well-known schema, a simple parser or a few regex rules will be faster and cheaper than spinning up an LLM pipeline. The platform requires Docker and at least 8 GB of RAM, so it will not run on a small VM or a serverless function. The AGPL licence may be a blocker for companies that want to embed extraction in a proprietary product without opening their code. Also, the README does not mention offline or on-premise LLM support beyond Ollama as a provider, so if your data cannot leave your network, you must verify that your chosen provider works in that mode. The reliance on natural-language prompts means extraction accuracy is not deterministic; an LLM can produce different outputs for the same input if the model updates or the prompt changes. For regulated industries that need auditable, consistent extraction, that variability is a concern. The README does not describe any validation or confidence-scoring mechanism, so you may need to build your own checks on the output JSON.

Alternatives and the Real Difference in Approach

The main alternative to Unstract is building your own extraction pipeline with a library like PyMuPDF or Tesseract for OCR, then calling an LLM API directly with your own prompt and JSON schema. That approach gives you full control over the code and no AGPL obligations, but you must write the glue logic, handle retries, manage API keys, and build a UI for non-technical users to adjust prompts. Unstract wraps all of that into a platform with a Prompt Studio, so the difference is not the underlying LLM capability but the surrounding tooling. Another alternative is a commercial IDP product like Azure Document Intelligence or AWS Textract, which offer pre-trained models for common document types like invoices and IDs. Those services are easier to start with because they have built-in schemas, but they are less flexible for custom or niche document types, and they lock you into a specific cloud vendor. Unstract sits in between: it is cloud-agnostic in terms of LLM providers (OpenAI, Anthropic, Bedrock, Ollama), but it requires you to host the platform yourself. The trade-off is operational overhead versus flexibility. If you need a fully managed service, Unstract's enterprise offering exists, but the open-source path is self-hosted.

Editorial conclusion

Adopt Unstract if your team processes varied, unstructured documents like invoices, IDs, or medical records and wants to replace per-vendor regex templates with a single natural-language prompt that produces JSON for a database or warehouse. Do not adopt it if you need a lightweight library, cannot run Docker and Compose with at least 8 GB RAM, or are restricted from AGPL-3.0 obligations in a commercial product. Before committing, verify that your document types and LLM providers (OpenAI, Anthropic, Bedrock, Ollama) are supported by the current version, and back up the ENCRYPTION_KEY from backend/.env or platform-service/.env because losing it makes existing adapter credentials inaccessible. Test the Prompt Studio on your own sample set to confirm extraction accuracy and latency meet your SLA before wiring it into production ETL.

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. Zipstack/unstract on GitHub