11 ms·
Show HN: Kreuzberg – Modern async Python library for document text extraction
I'm excited to showcase Kreuzberg!
Kreuzberg is a modern Python library built from the ground up with async/await, type hints, and optimized I/O handling.
It provides a unified interface for extracting text from documents (PDFs, images, office files) without external API dependencies.
Key technical features:
- Built with modern Python best practices (async/await, type hints, functional-first)
- Optimized async I/O with anyio for multi-loop compatibility
- Smart worker process pool for CPU-bound tasks (OCR, doc conversion)
- Efficient batch processing with concurrent extractions
- Clean error handling with context-rich exceptions
I built this after struggling with existing solutions that were either synchronous-only, required complex deployments, or had poor async support. The goal was to create something that works well in modern async Python applications, can be easily dockerized or used in serverless contexts, and relies only on permissive OSS.
Key advantages over alternatives:
- True async support with optimized I/O
- Minimal dependencies (much smaller than alternatives)
- Perfect for serverless and async web apps
- Local processing without API calls
- Built for modern Python codebases with rigorous typing and testing
I Would love feedback!
The library is MIT licensed and open to contributions.
Here is the repo: https://github.com/Goldziher/kreuzberg https://github.com/Goldziher/kreuzberg
Staring is caring
- deleted 2y ago[deleted]
- pseudony 2y agoInteresting, thanks for sharing :) Can you speak to how this differs in PDF extraction from, say, pymupdf, pdfplumber, unsloth and so on ? I know the async part is probably a thing, but when building a RAG I would be brutally focused on the quality of text extraction. Have you noticed an ability to do better than others ?
- nhirschfeld 2y agoSo, for PDF we need to distinguish between two types of text extraction- 1. Text extraction from a searchable PDF. 2. OCR. For 1. Kreuzberg uses pypdfium2, which is a python binding for pdfium - the chromium PDF engine. In this regard Kreuzberg has top notch performance. Much faster than miner.six, PDFplumber etc. Note PyMuPDF has top notch performance but also an AGPL license, and is almost unusable because of this without paying. For 2. Kreuzberg uses Tesseract, which is very solid. Performance is good, and Kreuzberg utilizes async worker processes to optimize concurrency. OCR though is a complex world. If what you need is to extract text from standard text documents (broadly speaking), Tesseract and hence Kreuzberg are a good choice. If what you need is things like layout extraction, hand writing recognition, complete bonding box metadata etc. than you need to use an alternative - commercial one probably.
- dleeftink 2y agoAn oldy but goody for layout extraction is Cermine by Dominika Tkaczyk and colleagues[0]. Java required. [0]: http://cermine.ceon.pl/about.html http://cermine.ceon.pl/about.html
- nhirschfeld 2y agodidnt know this!
- mdaniel 2y agoAlso AGPLv3 https://github.com/CeON/CERMINE/blob/cermine-parent-1.13/LICENSE https://github.com/CeON/CERMINE/blob/cermine-parent-1.13/LIC...
- ilaksh 2y agoPaddleOCR layout works, and so do some open source large language vision models
- tomcam 2y agoWhat is a RAG?
- nhirschfeld 2y agoRetrieval Augmented Generation. Its a class of techniques for generating content using LLMs. I'd recommend Googling this.
- richrichardsson 2y agoWhat led to the name choice?
- nhirschfeld 2y agoThat's my neighborhood in Berlin, which I love
- richrichardsson 2y agoAh, cool. I have a friend who lives there, so knew the name from that.
- jacomoRodriguez 2y agoamazing that half of the comments revolve around the name and the Neighbourhood. But I also clicked the topic because of the name, hello neighbour :) jokes aside, really cool library. I'm currently working in a bigger project where we build a data lake with a wide variety of input sources and formats - this could be quite interesting for us.
- nhirschfeld 2y agoAmazing, would be interested in reading your experience
- lippihom 2y agoBerlin SO 36!
- thecuntdaniel 2y ago[dead]
- eamag 2y agoLove the name! OCR was discussed here lately several times (https://news.ycombinator.com/item?id=42952605 https://news.ycombinator.com/item?id=42952605 and https://news.ycombinator.com/item?id=42871143 https://news.ycombinator.com/item?id=42871143), and some cool projects like https://github.com/Future-House/paper-qa?tab=readme-ov-file#what-is-paperqa2 https://github.com/Future-House/paper-qa?tab=readme-ov-file#... are using PyMuPDF. My experience with Tesseract is pretty sad, it's usually not good enough and modern LLMs are better.
- nhirschfeld 2y agoThanks, I'll check these links. In my tests I found tesseract quite good for regular text documents. For other kinds of texts it's not great. As for using models - there are some good small language models as well, and of course LLMs. I sorta feel though that if one needs complex OCR, or a vision model for layout, one should opt for either a commercial solution that abstracts the deployment and GPU management, or bake ones own system. For most use cases involving text documents though, my subjective opinion is that tesseract is sufficient.
- FlyingSnake 2y agoCan’t wait for non-Germans to butcher that name.
- leif_lundberg 2y agoVery cool, we've been using https://github.com/DS4SD/docling https://github.com/DS4SD/docling in our project, but will give this a try :)
- kachau 2y agocan you please share some details how are you using docling? This looks very promising but I am not sure how to use this one basically we have built document parser for all type of documents to extract texts and then feed these texts to llms to further find out semantics of these texts? do you think docling will help here with efficiency and latency?
- rapjul 2y agoDocling works quite well for me to convert a scanned book PDF to Markdown text. On the command line, first install `uv` from https://github.com/astral-sh/uv?tab=readme-ov-file#installation https://github.com/astral-sh/uv?tab=readme-ov-file#installat..., then run `uv tool install -U "docling[tesserocr,ocrmac,vlm]"` (first includes the tesserocr, ocrmac (macOS only), and vlm (for running a small Image-to-Text model to get descriptions of images). You go here https://github.com/DS4SD/docling/blob/main/pyproject.toml#L124 https://github.com/DS4SD/docling/blob/main/pyproject.toml#L1... to see all the extra installation options. For cached/offline use, run `docling-tools models download` to download their models.
- odiroot 2y agoDo you have to watch your pockets when using this library?
- nhirschfeld 2y agolol ;). But seriously, in 13 years living here, only one guy tried to pick pocket me.
- tymm 2y agoI live in 36 since 15 years or so. Wasn't as lucky as you :)
- nhirschfeld 2y agoSorry to hear...
- madisonmay 2y agopypdfium2 is a great choice and a solid piece of software! You might want to look into https://github.com/VikParuchuri/surya https://github.com/VikParuchuri/surya as an alternative to tesseract. Yes, it's associated with a commercial company, but as you long as you aren't a company with 5M in ARR or $5M in funding it's free to use.
- nhirschfeld 2y agointeresting!
- pzo 2y agothis still seems GPL. another OCR worth considering is easyOCR [0] (apache license). AFAIK there is not layout detection but they do provide bounding boxes and support many languages also detecting text on many different world objects from images (signpost, etc) [0] https://github.com/JaidedAI/EasyOCR https://github.com/JaidedAI/EasyOCR
- nhirschfeld 2y agoYup, easy OCR is good. My reasons for using Tesseract - easy OCR is larger, and it has a significant cold start. It benchmarks better for many OCR tasks though, so I'm thinking of adding it as an alternative backend.
- alex_suzuki 2y agoAny experience with Paddle OCR? https://github.com/PaddlePaddle/PaddleOCR https://github.com/PaddlePaddle/PaddleOCR Personally I‘ve used Tesseract before but the results were underwhelming, so I‘m curious how Paddle OCR performs in comparison.
- nhirschfeld 2y agoI haven't, testing it out is on my todo list for sure
- 2y ago
- rednafi 2y agoGotta write something named Wedding, Schoneberg, or Pankow. Kewt names.
- a012 2y agoDon’t forget Neukölln
- martin_balsam 2y agoGarbage collect module (cfr. Neuköllner for the past 12 years)
- nhirschfeld 2y agoI'm actually considering another library with optional API called `Kreuzköln` - probably without the Umlaut!
- guender 2y ago[dead]
- mohsen1 2y agocan you import it in python with ö in the name?
- madduci 2y agoWhat about Mitte, Steglitz or Charlottenburg?
- 2y ago
- diarrhea 2y agoI’m curious about the async aspect of this. I was under the impression PDF processing like OCR is purely CPU bound. OS file I/O interfaces are sync, so async does not help. With GIL, so single threaded Python, I can’t see how async improves performance for the PDF use case. Only parallelism helps, and concurrency doesn’t. When would it yield back to the event loop when it’s busy number crunching?
- nurettin 2y agoIt just litters perfectly reasonable python code with async/await. Maybe they are preparing for something we don't know, like a parallel async executor which can be set up to use native threads without changing code and somehow protects you if it detects shared state.
- diarrhea 2y ago> It just litters perfectly reasonable python code with async/await Yeah. As an API consumer I would not expect a PDF API do IO, hence be async. Have the library be sans-io, the interfaces sync and callers from async code handle IO on their end, offloading to IO threads. Async is also referred to as “best practice”, but it’s just a tool, for specific use cases. And I say that as an “async fan”! That said, perhaps it’s easier nowadays to just do async by default, as you say. The real world is async anyway, so why not program closer to that reality.
- nhirschfeld 2y agothats why Kreuzberg also exposes a sync API for you to consume.
- PDFBolt 2y agoAsync is great when you truly need it, but it can overcomplicate things when misused. Having both sync and async options, seems like the best approach. Lets devs choose based on their needs rather than forcing one paradigm.
- hermitdev 2y ago
- v3ss0n 2y agoWe are building something similar and waiting my partners/clients approval for opensourcing it. Looks like we should join forces.
- ideashower 2y agoIs there something like this for handwritten documents? I know newer models have been really good at handwriting transcription.
- nhirschfeld 2y agoYou'll need to use a different OCR engine. Look at easy ocr
- m00dy 2y agogood naming, it feels so warm that I feel like home :)
- taosx 2y agoI know this is contrary to popular opinion but I wish people would slowly move away from python. I've wasted so much time in understanding, integrating or just making python projects work that at this point I'm just avoiding anything python. The best python projects that I can confidently say are high quality are the ones where a lot of the code is c,c++ or rust and python is just a high level wrapper.
- d0mine 2y ago"python is a high level wrapper" is a python usage as intended. Being executable pseudo-code, glue language is its selling point. When has it ever been any different. I'm not sure C++/Rust projects are easier to understand though.
- RNCTX 2y agoAwesome. I modified a library card software (Blacklight) into a searchable PDF industrial manual system awhile back on a one-off basis. It couldn't go any further than a contract project that delivered the source code because it's hard to do anything programmatically (at the time) to a PDF without Ghostscript. I've often thought of rewriting it with Python (and Postgres, to get rid of Solr or Elastic as the search backend), maybe now's the time... I trust you long enough for a second look because I ctrl-f'd the readme and found "pdfium" so I know I don't have to retread old ground in your github issues about how there's really only a couple of ways to parse a PDF with a semblance of reliability, lol... (for anyone else reading this getting started with documents.. Adobe and Chrome are really the only PDF rendering libraries that work. PDF.js aka Firefox has always been broken, and Apple's is problematic as well, in both cases rearing their heads in terms of incorrect word / letter spacing).
- coderstartup 2y agoThat's Great.
- maleldil 2y agoThe API is pretty nice and easy to get started, but I couldn't get good results with parsing scientific paper PDFs, unfortunately (including OCR). Are there plans to use other backends? Docling works alright, and LLMs like Gemini Flash are interesting too.
- nhirschfeld 2y agoYes, there have already been several suggestions here for other backend etc. You should try using a different PSM to see if you get better results. If it's scientific texts specifically, look at grobid
- ulrischa 2y agoA really impressive feature list but a pretty heavy system level dependencies. On windows chocolatey is needed for them.
- umitkaanusta 2y agoSay I have a regular job that parses thousands of PDFs in bulk each day, how would kreuzberg help me? btw, liked the name as a turk with a few relatives who lived in germany :D