Quantify issues

Recent GitHub Issues Activity

_{Like all software activity quantification, these numbers are imperfect but sometimes useful. Comments, Labels, and Milestones refer to those issues opened in the timespan in question.}

Rate pull requests

PR#95 - experimental: introduce img understand pipelineopen

3_/5

Michele Dolfi (dolfim-ibm)Created: 2024-09-22

The pull request introduces a new feature, the 'ImgUnderstand' pipeline, which is a moderately significant change. However, it lacks updated documentation, examples, and tests, which are crucial for understanding and verifying the new functionality. The code changes are substantial, with several new files added and modifications to existing ones. The commit messages follow conventional guidelines, but the absence of necessary documentation and testing reduces the overall quality and completeness of the PR. Therefore, it is rated as average with nontrivial flaws.

[+] Read More

PR#132 - feat: [WIP] Support Document Index as a layout classopen

3_/5

Christoph Auer (cau-git)Created: 2024-10-08

The pull request introduces a feature to support 'Document Index' as a layout class, which is a useful enhancement. However, it is still a work in progress (WIP) and lacks completion in several areas such as documentation, examples, tests, and commit message formatting. The changes are minimal with only 14 lines modified across five files, indicating a relatively minor update. The PR resolves an issue (#126), but without additional context on its significance, the impact remains unclear. Overall, the PR is average and unremarkable at this stage.

[+] Read More

PR#194 - reuse existing chunk/meta types, fix minor issues, lintopen

3_/5

Panos Vagenas (vagenas)Created: 2024-11-01

The pull request makes several improvements by reusing existing chunk/meta types, fixing minor issues, and applying linting to the code. These changes are beneficial for code maintainability and readability. However, the PR lacks significant new features or substantial enhancements, and it doesn't resolve any major issues or add critical functionality. The changes are mostly refactoring and minor fixes, which are important but not groundbreaking. Therefore, it is rated as average or unremarkable.

[+] Read More

PR#193 - Sample chunking notebook that includes merging, etc.open

3_/5

Bill Murdock (jwm4)Created: 2024-11-01

The pull request introduces a new chunking notebook with several enhancements over an existing one. It merges chunks with similar headings, splits on list items before generic text splitting, and uses a different text splitter. However, it also makes assumptions about document titles that may not hold in the future, and opts for list-based chunk handling instead of streaming, which could be less efficient. While it shows thoughtful improvements, the changes are not exceptionally significant or flawless, warranting an average rating.

[+] Read More

PR#203 - feat: pdf backend and table mode as optionsopen

3_/5

Michele Dolfi (dolfim-ibm)Created: 2024-11-02

This pull request introduces new CLI options for selecting PDF backends and table modes, which enhances the flexibility of the tool. The changes are well-structured and documented, with updates to both code and documentation. However, it lacks accompanying tests and examples, which are crucial for ensuring robustness and usability of the new features. The commit messages are formatted correctly, but the absence of tests and examples prevents this PR from being rated higher.

[+] Read More

PR#214 - Specify encoding when writing output file to avoid errors when defaul…open

3_/5

Johnny Salazar (cepera-ang)Created: 2024-11-03

The pull request addresses a specific issue by specifying UTF-8 encoding when writing output files, which is a necessary improvement to prevent encoding errors. The change is straightforward and affects multiple file export formats, ensuring consistency. However, the modification is relatively minor, involving only the addition of an encoding parameter in file operations. While it resolves a potential bug, it does not introduce new features or significant enhancements. The PR follows proper commit message guidelines and includes necessary documentation and tests, making it a solid but unremarkable contribution.

[+] Read More

Quantify commits

Quantified Commit Activity Over 14 Days

Developer	Avatar	Branches	PRs	Commits	Files	Changes
****		1	0/0/0	1	72	37873
Peter W. J. Staar		3	3/3/1	11	63	16483
Christoph Auer		2	2/2/0	3	69	9110
Bill Murdock (jwm4)		1	1/0/0	2	1	1182
Panos Vagenas		4	6/5/0	7	13	811
Maxim Lysak		1	3/3/1	3	7	626
Maksym Lysak		1	0/0/0	5	3	441
Michele Dolfi		2	7/6/0	8	12	412
Mohamed Ali		1	0/1/0	1	1	58
github-actions[bot]		1	0/0/0	4	2	51
Johnny Salazar (cepera-ang)		0	1/0/0	0	0	0

_{PRs: created by that dev and opened/merged/closed-unmerged during the period}

Quantify risks

Project Risk Ratings

Report On: Fetch issues

Recent Activity Analysis

Recent GitHub issue activity for the DS4SD/docling project shows a flurry of new issues created within the last few days, indicating active development and user engagement. The issues range from minor documentation errors to significant functionality requests and bug reports. Notably, there are several issues related to document conversion accuracy, particularly with mathematical expressions and table recognition, suggesting ongoing challenges in these areas. Additionally, there are requests for new features such as support for arxiv HTML parsing and exporting markdown with image references.

Anomalies and Themes

• Anomalies: Issue #213 highlights a critical import error that could hinder users trying to utilize specific functionalities. This is an urgent problem that needs addressing to prevent user frustration.
• Complications: Issues like #212 and #210 indicate persistent problems with the accuracy of document conversion, particularly with complex content like mathematical expressions and tables.
• Commonalities: A recurring theme is the enhancement of document parsing capabilities, such as better handling of images (#211), support for additional formats (#209), and improved OCR functionality (#208). These reflect a focus on broadening the tool's applicability and improving its core functionalities.
• Unaddressed Urgency: Despite the critical nature of some issues (e.g., import errors in #213), there is no immediate indication of resolution or prioritization, which could impact user confidence.

Issue Details

Most Recently Created Issues

1. #215: Typo in documentation (docs/usage.md).

   • Priority: Low
   • Status: Open
   • Created: 0 days ago

2. #213: Import error with 'PipelineOptions'.

   • Priority: High
   • Status: Open
   • Created: 0 days ago

3. #212: Poor extraction of mathematical expressions.

   • Priority: Medium
   • Status: Open
   • Created: 0 days ago

4. #211: Request to export markdown with image references.

   • Priority: Medium
   • Status: Open
   • Created: 0 days ago

5. #210: Incorrect table recognition results.

   • Priority: Medium
   • Status: Open
   • Created: 1 day ago

Most Recently Updated Issues

1. #181: AttributeError in HierarchalChunker with LlamaIndex integration.

   • Priority: High
   • Status: Closed
   • Updated: 8 days ago

2. #176: Error in export_to_document_tokens function call.

   • Priority: Medium
   • Status: Closed
   • Updated: 9 days ago

3. #174: Markdown export issue with underscores needing escape.

   • Priority: Low
   • Status: Closed
   • Updated: 5 days ago

4. #166: Unable to render as doc tags post-update.

   • Priority: Medium
   • Status: Closed
   • Updated: 12 days ago

5. #163: Input format discovery improvement suggestion.

   • Priority: Low
   • Status: Closed
   • Updated: 11 days ago

This analysis highlights the project's ongoing efforts to refine its document conversion capabilities while also addressing user-reported bugs and feature requests to enhance overall functionality and user experience.

Report On: Fetch pull requests

Analysis of Pull Requests for DS4SD/docling

Open Pull Requests

1. PR #214:

   • Summary: This PR addresses encoding issues when writing output files, proposing UTF-8 as a universal solution.
   • Notable Points:
   • Created very recently (0 days ago).
   • Important for preventing CLI failures due to encoding errors.
   • Well-documented with updated tests and examples.

2. PR #203:

   • Summary: Adds options in the CLI for selecting PDF backends and table models.
   • Notable Points:
   • Created 1 day ago.
   • Lacks necessary examples and tests, which could delay merging.

3. PR #194:

   • Summary: Reuses existing chunk/meta types and fixes minor issues.
   • Notable Points:
   • Created 2 days ago.
   • Missing documentation, examples, and tests, which are crucial for understanding the changes.

4. PR #193:

   • Summary: Introduces a sample chunking notebook with various enhancements over existing examples.
   • Notable Points:
   • Created 2 days ago.
   • Adds significant new content with 918 lines of code, but lacks a clear integration plan with the main project.

5. PR #132:

   • Summary: Work in Progress (WIP) to support Document Index as a layout class.
   • Notable Points:
   • Created 26 days ago and still in draft status.
   • No progress on checklist items, indicating potential stagnation.

6. PR #95:

   • Summary: Experimental feature introducing an image understanding pipeline using vision LLMs.
   • Notable Points:
   • Open for 42 days, indicating slow progress or low priority.
   • Draft status with unresolved review comments.

Recently Closed Pull Requests

1. PR #196:

   • Summary: Updated LlamaIndex documentation.
   • Significance: Merged quickly after creation, indicating straightforward changes or high priority.

2. PR #190, #189, and others:

   • These PRs involve various fixes and enhancements such as simplifying dependencies, allowing explicit pipeline initialization, and updating README documentation.
   • Notable for their quick turnaround from creation to merging, suggesting efficient project management and prioritization.

3. PR #186, #184, and others:

   • Focus on fixing document structure issues like duplicate titles and heading levels in DOCX & HTML outputs.
   • Highlight the project's ongoing efforts to improve document parsing accuracy.

4. PR #183:

   • Introduces pipeline timing profiling and debug visualization settings.
   • Significant enhancement for developers needing performance insights and debugging tools.

5. Closed without Merge (e.g., PR #159, #157):

   • Some PRs were closed without merging, often because they were superseded by other changes or merged manually into other branches (e.g., through squashed commits).

Observations

• The project is actively maintained with frequent updates addressing both minor fixes and major feature additions.
• There is a strong emphasis on improving document parsing capabilities across various formats, as seen in multiple PRs focusing on backend enhancements.
• The presence of long-standing open PRs suggests areas where development may be slower or more complex (e.g., experimental features).
• The project maintains a robust testing framework, although some open PRs lack necessary tests which could delay their integration.

Recommendations

• Prioritize closing older open PRs like #132 and #95 by either advancing them towards completion or deciding on their future within the project.
• Encourage contributors to complete checklists before requesting reviews to streamline the merging process.
• Consider increasing focus on documentation updates alongside code changes to ensure users can fully leverage new features immediately upon release.

Report On: Fetch Files For Assessment

Source Code Assessment

File: docling/document_converter.py

Structure and Quality Analysis

• Imports: The file imports a wide range of modules, indicating a complex functionality. It uses standard libraries, third-party packages (like pydantic), and project-specific modules.
• Class Definitions: Multiple classes are defined for different document formats, inheriting from a base FormatOption class. This is a good use of inheritance to manage different document types.
• Type Annotations: The code uses type annotations extensively, which enhances readability and helps with static type checking.
• Validation: The use of pydantic validators ensures that the data is validated before processing, which is a robust design choice.
• Logging: Logging is used throughout the file, which is essential for debugging and monitoring the application's behavior.
• Error Handling: There is some error handling, particularly in the conversion methods, but it could be more comprehensive.
• Complexity: The file has a high level of complexity due to multiple classes and methods. Consider breaking down some methods into smaller functions to improve readability.

Recommendations

• Error Handling: Enhance error handling to cover more edge cases and provide more informative error messages.
• Documentation: Add docstrings to all classes and methods for better understanding and maintainability.
• Method Complexity: Refactor complex methods into smaller, more manageable functions.

File: docling/backend/html_backend.py

Structure and Quality Analysis

• Imports: Uses BeautifulSoup for HTML parsing, which is appropriate for this task.
• Class Definition: The HTMLDocumentBackend class handles HTML document conversion. It initializes with an input document and manages parsing through BeautifulSoup.
• Error Handling: Exceptions are caught during initialization but could be expanded throughout other methods for robustness.
• Logging: Extensive use of logging provides insight into the processing steps and potential issues.
• Complexity: Methods like analyse_element are quite lengthy and handle many cases, which can be simplified.

Recommendations

• Refactor Methods: Break down large methods into smaller ones to improve clarity and maintainability.
• Error Handling: Implement more comprehensive error handling across all methods.
• Documentation: Ensure all methods have clear docstrings explaining their purpose and functionality.

File: docling/backend/md_backend.py

Structure and Quality Analysis

• Imports: Utilizes the marko library for Markdown parsing, which is suitable for this backend's needs.
• Class Definition: The MarkdownDocumentBackend class processes Markdown documents. It includes initialization, validation, unloading, and conversion methods.
• Error Handling: There is minimal error handling; exceptions are mainly raised during initialization failures.
• Logging: Logging statements are present but could be more descriptive in certain areas to aid debugging.
• Complexity: Similar to the HTML backend, some methods handle multiple responsibilities and could benefit from being split into simpler functions.

Recommendations

• Error Handling: Increase the scope of error handling to cover more potential failure points within the conversion process.
• Refactoring: Simplify complex methods by dividing them into smaller functions with single responsibilities.
• Documentation: Add comprehensive docstrings to all functions for better understanding.

File: pyproject.toml

Structure and Quality Analysis

• Project Metadata: Contains essential metadata about the project such as name, version, description, authors, etc., which are well-defined.
• Dependencies Management: Lists dependencies with specific versions using Poetry. This ensures consistent environments across different setups.
• Development Tools: Includes tools like Black, Mypy, Pytest for development purposes which indicates a focus on code quality and testing.

Recommendations

• Ensure that dependency versions are regularly updated to include security patches and improvements.

File: poetry.lock

Structure and Quality Analysis

• Dependency Locking: Provides exact versions of all dependencies ensuring reproducibility across environments. This file should not be manually edited.

Recommendations

• Regularly update this file by running poetry update to ensure dependencies are up-to-date with security patches.

File: CHANGELOG.md

Structure and Quality Analysis

• Version History: Clearly documents changes made in each version with links to issues and commits. This is crucial for tracking project evolution.

Recommendations

• Continue maintaining detailed entries for each release to aid users in understanding changes over time.

GitHub Workflows (ci.yml, cd.yml, cd-docs.yml, ci-docs.yml)

Structure and Quality Analysis

• CI/CD Setup: Configures continuous integration and deployment workflows using GitHub Actions. These workflows automate testing (ci.yml) and deployment (cd.yml, cd-docs.yml) processes.

Recommendations

• Ensure workflows cover all critical paths in the application lifecycle including testing, building, and deploying documentation updates (ci-docs.yml).

Report On: Fetch commits

Repo Commits Analysis

Development Team and Recent Activity

Team Members and Their Recent Activities:

1. Panos Vagenas (vagenas)

   • Worked on updating the LlamaIndex docs and added advanced chunking examples.
   • Made CLI JSON export more human-readable.
   • Involved in reusing existing chunk/meta types and fixing minor issues.

2. Michele Dolfi (dolfim-ibm)

   • Added more options to the CLI and updated CLI documentation.
   • Simplified torch dependencies and updated pinned docling dependencies.
   • Worked on explicitly initializing the pipeline.

3. Christoph Auer (cau-git)

   • Added pipeline timings, toggle visualization, and established debug settings.
   • Updated various models with profiling options.
   • Worked on supporting AsciiDoc and Markdown input formats.

4. Peter W. J. Staar (PeterStaar-IBM)

   • Added detection of h1 in HTML parser and worked on skip_furniture parameter.
   • Fixed duplicate title and heading issues, added e2e tests for HTML and DOCX.
   • Contributed to supporting AsciiDoc input format.

5. Maxim Lysak (maxmnemonic)

   • Fixed handling of long sequences of unescaped underscore chars in markdown.
   • Made improvements in MD backend parsing.

6. Bill Murdock (jwm4)

   • Added advanced chunking with merging example notebook.

7. Mohamed Ali (moli-debugger)

   • Fixed typo errors in CONTRIBUTING.md file.

Patterns, Themes, and Conclusions:

• Collaborative Efforts: There is a strong collaborative effort among team members, with multiple co-authored commits and shared responsibilities across features and fixes.

• Focus on Documentation and Usability: Several updates were made to documentation files, indicating an emphasis on improving user guidance and project usability.

• Continuous Improvement: The team is actively involved in refining existing features, such as improving the CLI, enhancing document parsing capabilities, and fixing bugs related to document formatting.

• Feature Expansion: New features like advanced chunking, profiling options, and support for additional document formats (AsciiDoc, Markdown) are being actively developed.

• Active Branch Management: Multiple branches are being used for feature development, bug fixes, and documentation updates, showing organized development practices.

Overall, the development team is actively engaged in enhancing the functionality of the Docling project while ensuring comprehensive documentation and robust testing frameworks are maintained.