⚡ Bolt: Offload blocking API calls to worker threads

[anchapin]

💡 What: Offloaded blocking operations (like PDF compilation, template generation, and AI generation) in FastAPI endpoints (render_pdf, generate_cover_letter, render_resume_pdf) to worker threads using anyio.to_thread.run_sync.

🎯 Why: In FastAPI (which is async), performing heavy CPU-bound or blocking I/O tasks directly inside an async def route handler blocks the single thread running the ASGI event loop. This leads to severe concurrent request starvation, where other lightweight requests (like /health) are blocked until the heavy operation finishes.

📊 Impact: Significantly improves the API's concurrency. The main event loop is no longer blocked by slow operations (like LaTeX compilation), allowing the application to seamlessly handle background or interleaved requests while generating PDFs.

🔬 Measurement: I ran a time test against the API. Before the change, sending requests to the API while a heavy blocking operation was running would timeout or stall. After this optimization, endpoints remain highly responsive to concurrent requests even under heavy load.

---

PR created automatically by Jules for task 8138516599051557082 started by @anchapin

Summary by Sourcery

Offload blocking resume and cover letter PDF and content generation work from FastAPI route handlers to worker threads to avoid event loop blocking and improve concurrency.

Bug Fixes:

• Improve reliability of PDF generation endpoints by handling missing output files as explicit server errors after threaded execution.

Enhancements:

• Run PDF rendering for resumes in a worker thread, including JSON-to-YAML conversion, YAML writing, and TemplateGenerator PDF creation and reading.
• Execute cover letter AI generation and optional LaTeX-to-PDF compilation in worker threads, including file I/O and base64 encoding of the resulting PDF.
• Move resume PDF generation in the generic render endpoint to a worker thread, encapsulating generator calls and file reading.

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[sourcery-ai]

Reviewer's Guide

Offloads several blocking PDF generation, AI cover letter generation, and JSON→YAML/PDF rendering operations in FastAPI endpoints onto worker threads using anyio.to_thread.run_sync, so the async event loop remains responsive while preserving existing behavior and error handling semantics.

Sequence diagram for offloading blocking PDF generation to worker threads

sequenceDiagram
    actor Client
    participant FastAPI as render_pdf
    participant AnyIO as anyio.to_thread.run_sync
    participant Worker as WorkerThread
    participant Generator as TemplateGenerator
    participant FS as FileSystem

    Client->>FastAPI: HTTP POST /render_pdf
    FastAPI->>AnyIO: to_thread.run_sync(_generate_pdf)
    AnyIO->>Worker: execute _generate_pdf
    Worker->>Generator: generate(variant, output_format, output_path)
    Generator->>FS: write output.pdf
    Worker->>FS: output_pdf.exists()
    Worker->>FS: output_pdf.read_bytes()
    Worker-->>AnyIO: content
    AnyIO-->>FastAPI: content
    FastAPI-->>Client: HTTP 200 PDF bytes

Loading

File-Level Changes

Change	Details	Files
Offload blocking PDF generation and file I/O in render_pdf endpoint to a worker thread and adjust error handling accordingly.	Wrap TemplateGenerator.generate and subsequent output file existence check and read_bytes logic in a nested synchronous _generate_pdf function. Use anyio.to_thread.run_sync to execute _generate_pdf without blocking the event loop. Return bytes directly from _generate_pdf, using None as a sentinel when the PDF file is missing, and translate that to an HTTP 500 in the async route handler.	api/main.py
Offload AI-based cover letter generation and optional PDF compilation + base64 encoding to worker threads.	Introduce a synchronous _generate helper that calls generator.generate_non_interactive and run it via anyio.to_thread.run_sync to avoid blocking the event loop. Refactor LaTeX-to-PDF compilation and subsequent file read + base64 encoding into a synchronous _compile_and_read helper executed via anyio.to_thread.run_sync. Return pre-encoded base64 content from _compile_and_read, using None to signal compile failure, and keep the response shape consistent with the previous implementation.	api/main.py
Offload resume JSON→YAML conversion, YAML writing, template PDF generation, and file I/O in render_resume_pdf endpoint to a worker thread.	Move JSONResumeConverter usage, YAML dumping, TemplateGenerator construction, PDF generation, and file read into a synchronous _process_and_generate helper. Run _process_and_generate via anyio.to_thread.run_sync to prevent event loop starvation from CPU-bound and blocking I/O operations. Return PDF bytes from _process_and_generate, using None as a sentinel for generation failure and mapping it to an HTTP 500 in the async route handler.	api/main.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• Consider extracting the repeated anyio.to_thread.run_sync patterns into shared helper utilities (e.g., a generic run_blocking_pdf_generation/run_blocking_io function) instead of defining small nested functions in each route, to reduce duplication and make the threading behavior easier to reason about and maintain.
• The base64 import inside _compile_and_read will execute on every call; moving it to module scope would avoid the repeated import and make the helper function purely about compilation and I/O.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider extracting the repeated `anyio.to_thread.run_sync` patterns into shared helper utilities (e.g., a generic `run_blocking_pdf_generation`/`run_blocking_io` function) instead of defining small nested functions in each route, to reduce duplication and make the threading behavior easier to reason about and maintain.
- The `base64` import inside `_compile_and_read` will execute on every call; moving it to module scope would avoid the repeated import and make the helper function purely about compilation and I/O.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}