How to Report Bugs or Suggest Features for Olmocr: A Complete Guide

Report bugs or suggest features for olmocr by filing structured GitHub Issues in the allenai/olmocr repository using the provided templates for bug reports and feature requests.

The allenai/olmocr repository uses GitHub's standard issue tracking system to manage community feedback. Whether you have encountered an error in the OCR pipeline or want to propose new functionality, the project provides specific templates and guidelines to ensure your report reaches the maintainers efficiently.

Where to Report Bugs and Suggest Features

All bug reports, feature requests, and documentation suggestions should be submitted as GitHub Issues in the main repository. The project maintains separate templates to streamline the triage process and ensure you provide the necessary context.

Filing Bug Reports

To report a bug, use the dedicated template at the bug report URL:

https://github.com/allenai/olmocr/issues/new?template=bug_report.yml

This template, defined in .github/ISSUE_TEMPLATE/bug_report.yml, automatically prompts you for environment details, reproduction steps, and expected versus actual behavior. Providing complete information allows the maintainers to reproduce and resolve issues faster.

Submitting Feature Requests

For new functionality or enhancements, use the feature request template:

https://github.com/allenai/olmocr/issues/new?template=feature_request.yml

The template in .github/ISSUE_TEMPLATE/feature_request.yml asks for a description of the proposed feature, use cases, and potential implementation approaches. This structure helps the team evaluate how the suggestion fits into the project's roadmap.

Contribution Guidelines and Templates

Before opening any issue, review the guidelines in .github/CONTRIBUTING.md (https://github.com/allenai/olmocr/blob/main/.github/CONTRIBUTING.md). This file outlines the project's standards for reporting issues, code style, testing requirements, and the pull request process.

Selecting the appropriate template automatically adds the required sections to your issue, making it easier for maintainers to categorize and prioritize your feedback. If you have quick questions or need clarification before filing a formal issue, you can start a discussion in the Discussions tab of the repository, though the Issues system remains the primary channel for bugs and feature proposals.

Programmatically Creating Issues

You can automate issue creation using the GitHub CLI or API when reporting bugs or suggesting features for olmocr at scale.

Using the GitHub CLI

Create a bug report from the command line using the gh CLI:

gh issue create \
  --repo allenai/olmocr \
  --title "OCR fails on multi‑column tables in PDF X" \
  --body "$(cat <<EOF
**Bug Description**
The OCR output merges columns in multi‑column tables for PDF X.

**Steps to Reproduce**
1. Run `olmocr pipeline --input path/to/pdf_x.pdf`
2. Observe the merged columns in the generated markdown.

**Environment**
- OS: Ubuntu 22.04
- Python: 3.11
- OLMOCR version: 0.4.2

**Expected Behavior**
Each column should be preserved separately.

**Actual Behavior**
Columns are concatenated into a single column.
EOF
)" \
  --label bug

Using the GitHub API

Submit a feature request via curl using the GitHub REST API:

curl -X POST \
  -H "Authorization: token <YOUR_PERSONAL_ACCESS_TOKEN>" \
  -d '{
    "title": "Add support for OCR of handwritten equations",
    "body": "**Feature Description**\nEnable detection and LaTeX rendering of handwritten mathematical expressions.\n\n**Use Cases**\n- Academic papers with handwritten notes\n- Scanned lecture slides\n\n**Potential Approach**\nLeverage a specialized handwriting model (e.g., MathPix) and integrate it as a post‑processing step.\n",
    "labels": ["enhancement"]
  }' \
  https://api.github.com/repos/allenai/olmocr/issues

Replace <YOUR_PERSONAL_ACCESS_TOKEN> with a token that has the repo scope.

Summary

• Use GitHub Issues as the primary channel to report bugs or suggest features for olmocr, located at https://github.com/allenai/olmocr/issues.
• Select appropriate templates via the bug report or feature request URLs to ensure your submission includes required context.
• Review .github/CONTRIBUTING.md before submitting to understand project standards and expectations.
• Automate submissions using the GitHub CLI or REST API when creating multiple issues programmatically.

Frequently Asked Questions

Where do I report bugs for olmocr?

Report bugs by creating a GitHub Issue in the allenai/olmocr repository using the bug report template at https://github.com/allenai/olmocr/issues/new?template=bug_report.yml. This template, stored in .github/ISSUE_TEMPLATE/bug_report.yml, ensures you provide environment details and reproduction steps necessary for the maintainers to investigate.

How do I suggest a new feature for olmocr?

Submit feature requests through the feature request template at https://github.com/allenai/olmocr/issues/new?template=feature_request.yml. The template defined in .github/ISSUE_TEMPLATE/feature_request.yml guides you to describe use cases and potential implementation approaches, helping the team evaluate your proposal against the project roadmap.

What information should I include in a bug report?

Include your operating system, Python version, olmocr version, a clear description of the bug, step-by-step reproduction instructions, expected behavior, and actual behavior. The bug report template automatically prompts for these details, following the guidelines established in .github/CONTRIBUTING.md.

Can I use the GitHub API to create issues programmatically?

Yes, you can create issues using the GitHub CLI (gh issue create) or the REST API (POST /repos/allenai/olmocr/issues) with a personal access token containing the repo scope. This approach is useful for automated reporting or when submitting multiple related issues, though you should still follow the template structure for consistency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}