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:

ocr_queue.py
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:

Python
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:

Python
@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

Write 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:

Python
@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:

Python
@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:

Terminal
blade run ocr_queue.py

The 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:

Output
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.

ocr_queue.py
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

Contact the team

Loading the form…