Developer docs / AI Fabric tutorials
OCR job queue (bladekit.Queue)
- Image DSL
When work arrives faster than you can process it (uploads, documents, jobs), you don't want producers waiting on consumers. The fix is a queue: one side drops jobs in, the other side pulls them out and works through the backlog at its own pace. The two sides are decoupled, so each can scale and fail independently.
In this tutorial you'll build an OCR pipeline on bladekit.Queue. A producer renders sample invoice images and enqueues them, a worker drains the queue and runs Tesseract OCR on each one, and a second queue carries the extracted text back. No web framework, no message broker to run: bladekit.Queue is a managed, distributed queue you call directly.
Before you start
Make sure the AI Fabric CLI is installed and authenticated (blade setup). No GPU is needed; OCR runs happily on CPU. We build a small debian_slim image and apt_install the Tesseract binary, so there's nothing for you to install locally.
Build the image
Create ocr_queue.py. Tesseract is a system package, so we start from debian_slim and use apt_install for the OCR engine and pip_install for the Python bindings plus Pillow:
import bladekit
app = bladekit.app("ocr-queue")
image = (
bladekit.Image.debian_slim(python_version="3.12")
.apt_install("tesseract-ocr", "libtesseract-dev")
.pip_install("pytesseract", "Pillow", "numpy")
)Create the queues
You need two named queues: one for jobs waiting to be processed, and one for finished results. from_name(..., create_if_missing=True) gives you a handle, creating the queue the first time and reusing it afterwards. Because they're referenced by name, the producer and the worker share the same queues even though they run in different containers:
ocr_queue = bladekit.Queue.from_name("ocr-jobs", create_if_missing=True)
results_queue = bladekit.Queue.from_name("ocr-results", create_if_missing=True)Write the producer
The producer is an ordinary AI Fabric function that fills the jobs queue. To keep the tutorial self-contained it renders sample invoice images in memory rather than reading local files, base64-encodes each one, and calls ocr_queue.put(...) with a small job dict. Each put is one job the worker will later pick up:
@app.function(image=image, timeout=300)
def seed_jobs(n: int = 5) -> int:
"""Render sample documents and enqueue them (no local files needed)."""
import base64, io
from PIL import Image as PILImage, ImageDraw
for i in range(n):
img = PILImage.new("RGB", (480, 120), "white")
d = ImageDraw.Draw(img)
d.text((10, 40), f"Invoice number {1000 + i} Total 42.{i}0 USD", fill="black")
buf = io.BytesIO()
img.save(buf, format="PNG")
ocr_queue.put({"job_id": f"doc-{i}", "image_b64": base64.b64encode(buf.getvalue()).decode()})
return nWrite the worker
The worker drains the queue in a loop. ocr_queue.get(timeout=5) blocks for up to five seconds waiting for a job; when the queue is empty it returns None, which is the signal to stop. For each job it decodes the image, runs Tesseract via pytesseract.image_to_string, and pushes the extracted text onto the results queue:
@app.function(image=image, timeout=300)
def ocr_worker() -> None:
"""Drain the queue and OCR each document."""
import base64, io
import pytesseract
from PIL import Image as PILImage
processed = 0
while True:
job = ocr_queue.get(timeout=5)
if job is None:
break # queue empty
img_bytes = base64.b64decode(job["image_b64"])
img = PILImage.open(io.BytesIO(img_bytes))
text = pytesseract.image_to_string(img)
results_queue.put({"job_id": job["job_id"], "text": text[:500]})
processed += 1
print(f"OCR worker processed {processed} documents.")Reading until get returns None is the standard drain pattern: the worker keeps pulling until there's nothing left, then exits cleanly. Because the worker is another function, you could launch several of them to chew through a big backlog in parallel.
Wire up producer, worker, and results
The local_entrypoint orchestrates the three pieces from your laptop. It enqueues the jobs with seed_jobs.remote(...), launches the worker with ocr_worker.remote(), then drains the results queue the same way the worker drains jobs, reading until get returns None:
@app.local_entrypoint()
def main():
# Producer: render + enqueue jobs remotely (no local files needed)
n = seed_jobs.remote(5)
print(f"Enqueued {n} documents.")
# Launch the worker
ocr_worker.remote()
# Drain results
while True:
res = results_queue.get(timeout=10)
if res is None:
break
print(f"{res['job_id']}: {res['text'].strip()!r}")Run it
Run the program with the AI Fabric CLI:
blade run ocr_queue.pyThe producer enqueues five rendered invoices, the worker picks them up one by one and OCRs each, and the results stream back as the worker finishes them. You'll see one line per document with the text Tesseract extracted:
Enqueued 5 documents.
doc-0: 'Invoice number 1000 Total 42.00 USD'
doc-1: 'Invoice number 1001 Total 42.10 USD'That's a working job queue with no broker to operate. Because producers and consumers are decoupled through bladekit.Queue, you can swap the renderer for real document uploads, run many workers at once, and let the queue absorb bursts of work.
Take it for a spin
Everything above in one file, ready to run.
import bladekit
app = bladekit.app("ocr-queue")
image = (
bladekit.Image.debian_slim(python_version="3.12")
.apt_install("tesseract-ocr", "libtesseract-dev")
.pip_install("pytesseract", "Pillow", "numpy")
)
ocr_queue = bladekit.Queue.from_name("ocr-jobs", create_if_missing=True)
results_queue = bladekit.Queue.from_name("ocr-results", create_if_missing=True)
@app.function(image=image, timeout=300)
def seed_jobs(n: int = 5) -> int:
"""Render sample documents and enqueue them (no local files needed)."""
import base64, io
from PIL import Image as PILImage, ImageDraw
for i in range(n):
img = PILImage.new("RGB", (480, 120), "white")
d = ImageDraw.Draw(img)
d.text((10, 40), f"Invoice number {1000 + i} Total 42.{i}0 USD", fill="black")
buf = io.BytesIO()
img.save(buf, format="PNG")
ocr_queue.put({"job_id": f"doc-{i}", "image_b64": base64.b64encode(buf.getvalue()).decode()})
return n
@app.function(image=image, timeout=300)
def ocr_worker() -> None:
"""Drain the queue and OCR each document."""
import base64, io
import pytesseract
from PIL import Image as PILImage
processed = 0
while True:
job = ocr_queue.get(timeout=5)
if job is None:
break # queue empty
img_bytes = base64.b64decode(job["image_b64"])
img = PILImage.open(io.BytesIO(img_bytes))
text = pytesseract.image_to_string(img)
results_queue.put({"job_id": job["job_id"], "text": text[:500]})
processed += 1
print(f"OCR worker processed {processed} documents.")
@app.local_entrypoint()
def main():
# Producer: render + enqueue jobs remotely (no local files needed)
n = seed_jobs.remote(5)
print(f"Enqueued {n} documents.")
# Launch the worker
ocr_worker.remote()
# Drain results
while True:
res = results_queue.get(timeout=10)
if res is None:
break
print(f"{res['job_id']}: {res['text'].strip()!r}")Concepts used: Run, Cold start