extractfold 0.1.1__tar.gz

extractfold-0.1.1/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

extractfold-0.1.1/AGENTS.md

@@ -0,0 +1,9 @@
+@/Users/m/.codex/RTK.md
+
+# extractfold Agent Notes
+
+- Preserve the public API in `src/extractfold/engines/base.py`.
+- Follow the proposal -> failing test -> implementation -> verification loop.
+- Unit tests must not require model weights, network, or cloud credentials.
+- Optional engines must import heavy dependencies lazily inside methods.
+- Base package dependencies must remain empty.

extractfold-0.1.1/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-08-20
+
+### Fixed
+- Publish releases through a dedicated OIDC PyPI workflow so release tags do
+  not depend on the general test workflow.
+
+## [0.1.0] - 2026-08-19
+
+### Added
+- `fenic` engine adapter for typedef-ai's fenic `semantic.extract`, behind the
+  `extractfold[fenic]` extra.
+- Initial extractfold package scaffold with schema-first engine contract.
+- Router, CLI, evaluation runner, benchmark harness, docs, packaging, and CI.
+- Engine adapters for Lift, NuExtract, LLM structured outputs, Instructor,
+  LlamaExtract, Azure Document Intelligence, Google Document AI, AWS Textract,
+  and docfold plus LLM extraction.
+- Dependency-free `provider_router` engine for injected model gateways over
+  prepared text.
+- Opt-in resilient chunk execution for `extract_rows_chunked(..., continue_on_error=True)`.
+
+### Fixed
+- Exclude `.claude` from the sdist; its out-of-tree symlinks broke building a
+  wheel from the sdist.

extractfold-0.1.1/CLAUDE.md

@@ -0,0 +1,23 @@
+# CLAUDE.md
+
+## Project
+
+extractfold turns documents plus JSON Schema into schema-conformant dictionaries.
+It is the structured-extraction sibling of docfold.
+
+## Workflow
+
+- Use TDD for every feature and engine.
+- Write or update `docs/tasks/<name>.md` from `docs/tasks/_TEMPLATE.md`.
+- Confirm the new test fails for the expected reason before implementing.
+- Keep the public contract in `src/extractfold/engines/base.py` backward compatible.
+- Keep core imports dependency-free.
+- Put heavy SDK/model imports inside methods.
+
+## Gates
+
+```bash
+ruff check src/ tests/
+mypy src/
+pytest tests/ -m "not integration"
+```

extractfold-0.1.1/CODEX.md

@@ -0,0 +1,12 @@
+# CODEX.md
+
+## Commands
+
+```bash
+rtk ruff check src/ tests/
+rtk mypy src/
+rtk pytest tests/ -m "not integration"
+```
+
+Use `rtk` for shell commands in this workspace. Keep changes scoped and do not
+revert user work.

extractfold-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+## Development Setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Adding An Engine
+
+1. Add `docs/tasks/<engine>.md` from `docs/tasks/_TEMPLATE.md`.
+2. Write stubbed unit tests and a skipped `integration` test.
+3. Confirm the unit test fails before writing adapter code.
+4. Implement the adapter behind `ExtractionEngine`.
+5. Add an optional extra in `pyproject.toml`.
+6. Register the engine in the CLI router and priority order.
+7. Run the quality gates.
+
+## Quality Gates
+
+```bash
+ruff check src/ tests/
+mypy src/
+pytest tests/ -m "not integration"
+```

extractfold-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Sadofyev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

extractfold-0.1.1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: extractfold
+Version: 0.1.1
+Summary: Schema-guided structured data extraction from documents.
+Project-URL: Homepage, https://github.com/mihailorama/extractfold
+Project-URL: Documentation, https://github.com/mihailorama/extractfold/tree/main/docs
+Project-URL: Repository, https://github.com/mihailorama/extractfold
+Project-URL: Issues, https://github.com/mihailorama/extractfold/issues
+Project-URL: Changelog, https://github.com/mihailorama/extractfold/blob/main/CHANGELOG.md
+Author-email: Mihailorama <mihailorama@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: document-extraction,json-schema,llm,ocr,structured-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: azure-ai-documentintelligence>=1.0; extra == 'all'
+Requires-Dist: boto3>=1.28; extra == 'all'
+Requires-Dist: docfold>=0.6; extra == 'all'
+Requires-Dist: fenic>=0.13; extra == 'all'
+Requires-Dist: google-cloud-documentai>=3.0; extra == 'all'
+Requires-Dist: google-genai>=1.0; extra == 'all'
+Requires-Dist: instructor>=1.6; extra == 'all'
+Requires-Dist: llama-cloud-services>=0.6; extra == 'all'
+Requires-Dist: openai>=1.50; extra == 'all'
+Requires-Dist: requests>=2.31; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Requires-Dist: transformers>=4.40; extra == 'all'
+Provides-Extra: azure-docint
+Requires-Dist: azure-ai-documentintelligence>=1.0; extra == 'azure-docint'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: docfold-llm
+Requires-Dist: anthropic>=0.40; extra == 'docfold-llm'
+Requires-Dist: docfold>=0.6; extra == 'docfold-llm'
+Requires-Dist: google-genai>=1.0; extra == 'docfold-llm'
+Requires-Dist: openai>=1.50; extra == 'docfold-llm'
+Provides-Extra: evaluation
+Provides-Extra: fenic
+Requires-Dist: fenic>=0.13; extra == 'fenic'
+Provides-Extra: google-docai
+Requires-Dist: google-cloud-documentai>=3.0; extra == 'google-docai'
+Provides-Extra: instructor
+Requires-Dist: instructor>=1.6; extra == 'instructor'
+Requires-Dist: openai>=1.50; extra == 'instructor'
+Provides-Extra: lift
+Requires-Dist: requests>=2.31; extra == 'lift'
+Provides-Extra: llamaextract
+Requires-Dist: llama-cloud-services>=0.6; extra == 'llamaextract'
+Provides-Extra: llm-structured
+Requires-Dist: anthropic>=0.40; extra == 'llm-structured'
+Requires-Dist: google-genai>=1.0; extra == 'llm-structured'
+Requires-Dist: openai>=1.50; extra == 'llm-structured'
+Provides-Extra: nuextract
+Requires-Dist: torch>=2.0; extra == 'nuextract'
+Requires-Dist: transformers>=4.40; extra == 'nuextract'
+Provides-Extra: nuextract-vllm
+Requires-Dist: vllm>=0.5; extra == 'nuextract-vllm'
+Provides-Extra: provider-router
+Provides-Extra: test
+Requires-Dist: mypy>=1.8; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: ruff>=0.4; extra == 'test'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'test'
+Provides-Extra: textract
+Requires-Dist: boto3>=1.28; extra == 'textract'
+Description-Content-Type: text/markdown
+
+# extractfold
+
+`extractfold` is the structured-data sibling of `docfold`.
+
+- `docfold`: document -> representation, such as Markdown, HTML, text, or layout.
+- `extractfold`: document + JSON Schema -> schema-conformant Python `dict`.
+
+The core package has no required third-party dependencies. Engines that need model
+weights, cloud SDKs, or provider SDKs live behind optional extras and import those
+dependencies lazily.
+
+## Install
+
+```bash
+pip install extractfold
+pip install "extractfold[provider_router]"
+pip install "extractfold[llm_structured]"
+pip install "extractfold[all]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+from extractfold.engines import LLMStructuredEngine
+
+schema = {
+    "type": "object",
+    "required": ["invoice_id", "total"],
+    "properties": {
+        "invoice_id": {"type": "string"},
+        "vendor": {"type": "string"},
+        "total": {"type": "number"},
+    },
+}
+
+async def main() -> None:
+    result = await LLMStructuredEngine().extract("invoice.pdf", schema)
+    print(result.data)
+
+asyncio.run(main())
+```
+
+## CLI
+
+```bash
+extractfold extract invoice.pdf --schema invoice --engine llm_structured
+extractfold extract invoice.pdf --schema schema.json --out result.json
+extractfold compare invoice.pdf --schema schema.json --engines llm_structured,lift
+extractfold list-engines
+extractfold benchmark ./dataset --engines llm_structured,lift --out results.json
+```
+
+## Engine Comparison
+
+| Engine | Type | License | Schema | Nested | Confidence | Provenance | Local/Remote | Speed | Cost |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `lift` | Datalab Lift adapter | SaaS | Native | Yes | Yes | Yes | Remote | Fast | Paid API |
+| `nuextract` | Open model | Model license | Prompt JSON | Yes | No | No | Local | Medium | Hardware |
+| `provider_router` | Injected model gateway | App-defined | Prompt JSON | Yes | No | No | Remote | App-defined | App-defined |
+| `llm_structured` | LLM structured outputs | Provider terms | Tool/JSON mode | Yes | No | No | Remote | Medium | Paid tokens |
+| `instructor` | Pydantic/JSON extraction | MIT library + provider terms | Pydantic/JSON Schema | Yes | No | No | Remote by default | Medium | Paid tokens |
+| `fenic` | typedef-ai fenic `semantic.extract` | Apache-2.0 library + provider terms | Pydantic (converted from JSON Schema) | Yes | No | No | Remote by default | Medium | Paid tokens |
+| `llamaextract` | LlamaCloud Extract | SaaS | Native | Yes | No | No | Remote | Fast | Paid API |
+| `azure_docint` | Azure Document Intelligence | SaaS | Query fields | Limited | Yes | Yes | Remote | Fast | Paid API |
+| `google_docai` | Google Document AI | SaaS | Custom extractor/entities | Yes | Yes | Yes | Remote | Fast | Paid API |
+| `textract` | AWS Textract | SaaS | QUERIES/FORMS | Limited | Yes | Yes | Remote | Fast | Paid API |
+| `docfold_llm` | Composite | Mixed | LLM structured | Yes | Depends on LLM | Depends on LLM | Remote by default | Medium | Parse + token cost |
+
+## How To Choose
+
+| Need | Use |
+| --- | --- |
+| Existing model gateway, retries, and telemetry | `provider_router` |
+| Best practical default for arbitrary schemas | `llm_structured` |
+| First-party Datalab Lift workflow | `lift` |
+| Local/open-model extraction | `nuextract` |
+| Existing `instructor` stack | `instructor` |
+| Existing fenic dataframe pipelines | `fenic` |
+| Managed extraction SaaS | `llamaextract` |
+| Enterprise cloud OCR/forms/query fields | `azure_docint`, `google_docai`, or `textract` |
+| Clean Markdown/text before extraction | `docfold_llm` |
+
+## Engine Examples
+
+```python
+from extractfold.engines import (
+    AzureDocIntEngine,
+    DocfoldLLMEngine,
+    FenicEngine,
+    GoogleDocAIEngine,
+    InstructorEngine,
+    LiftEngine,
+    LLMStructuredEngine,
+    LlamaExtractEngine,
+    NuExtractEngine,
+    ProviderRouterEngine,
+    TextractEngine,
+)
+```
+
+```python
+async def provider_call(**kwargs):
+    # Call an application-owned gateway and return JSON-compatible data.
+    return {"invoice_id": "INV-001", "total": 125.5}
+
+result = await ProviderRouterEngine(provider_call=provider_call).extract("invoice.txt", "invoice")
+result = await LiftEngine().extract("invoice.pdf", "invoice")
+result = await NuExtractEngine(backend="hf").extract("invoice.txt", "invoice")
+result = await LLMStructuredEngine(provider="anthropic").extract("invoice.pdf", "invoice")
+result = await LLMStructuredEngine(provider="openai").extract("invoice.pdf", "invoice")
+result = await LLMStructuredEngine(provider="gemini").extract("invoice.pdf", "invoice")
+result = await InstructorEngine().extract("invoice.pdf", "invoice")
+result = await FenicEngine().extract("invoice.txt", "invoice")
+result = await LlamaExtractEngine().extract("invoice.pdf", "invoice")
+result = await AzureDocIntEngine().extract("invoice.pdf", "invoice")
+result = await GoogleDocAIEngine().extract("invoice.pdf", "invoice")
+result = await TextractEngine().extract("invoice.pdf", "invoice")
+result = await DocfoldLLMEngine().extract("invoice.pdf", "invoice")
+```
+
+## Evaluation
+
+`extractfold.evaluation` scores prediction folders shaped like this:
+
+```text
+dataset/
+  gold/invoice.json
+  predictions/llm_structured/invoice.json
+  predictions/lift/invoice.json
+```
+
+Metrics include field accuracy, schema compliance, precision/recall/F1,
+hallucination rate, type correctness, normalized value matching, and nested array
+alignment.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src/ tests/
+mypy src/
+pytest tests/ -m "not integration"
+```