folioiq 0.1.0__tar.gz

folioiq-0.1.0/.env.example

@@ -0,0 +1,12 @@
+# FolioIQ — copy to .env and fill in
+
+# Azure OpenAI (required for extract() without a custom llm=)
+AZURE_API_KEY=
+AZURE_API_BASE=
+AZURE_API_VERSION=
+# Deployment name (also accepts env var `model` for billing-app compatibility)
+FOLIOIQ_AZURE_MODEL=
+
+# Azure Document Intelligence (Phase 3)
+AZURE_DOC_INTELLIGENCE_ENDPOINT=
+AZURE_DOC_INTELLIGENCE_KEY=

folioiq-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+
+# Env / secrets
+.env
+.env.local
+
+# OS / IDE
+.DS_Store
+.idea/
+.vscode/
+
+# Test / local artifacts
+uploads/
+*.pdf
+!tests/fixtures/**/*.pdf
+!tests/fixtures/**/*.jpg
+!tests/fixtures/**/*.jpeg
+!tests/fixtures/**/*.png

folioiq-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FolioIQ contributors
+
+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.

folioiq-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: folioiq
+Version: 0.1.0
+Summary: Schema-driven document extraction with pluggable providers
+Project-URL: Homepage, https://github.com/auspicious123/folioiq-sdk
+Project-URL: Repository, https://github.com/auspicious123/folioiq-sdk
+Project-URL: Issues, https://github.com/auspicious123/folioiq-sdk/issues
+Author-email: auspicious123 <auspicious123@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: azure,document-extraction,llm,ocr,pdf,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pymupdf>=1.24.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: azure
+Requires-Dist: azure-ai-documentintelligence>=1.0.0; extra == 'azure'
+Requires-Dist: langchain-core>=0.3.0; extra == 'azure'
+Requires-Dist: langchain-openai>=0.2.0; extra == 'azure'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FolioIQ
+
+[![PyPI](https://img.shields.io/badge/pypi-folioiq-blue)](https://pypi.org/project/folioiq/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Schema-driven document extraction. YAML spec (+ optional MD) in → structured data out.
+
+```python
+from folioiq import DocumentExtractor
+
+extractor = DocumentExtractor.from_env()
+result = extractor.extract("invoice.pdf", spec="examples/invoice.yaml")
+
+if result.is_valid:
+    print(result.data)
+else:
+    print(result.validation_errors)
+```
+
+## Install
+
+```bash
+pip install folioiq
+pip install "folioiq[azure]"   # Azure OpenAI + Document Intelligence
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/auspicious123/folioiq-sdk.git
+cd folioiq-sdk
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[azure,dev]"
+cp .env.example .env   # fill Azure vars
+```
+
+## Spec only (no LLM)
+
+```python
+spec = extractor.load_spec("examples/invoice.yaml")
+Model = extractor.build_model(spec)
+```
+
+## Pipeline override (YAML)
+
+```yaml
+pipeline:
+  mode: explicit
+  parser: azure_di   # or pymupdf
+```
+
+## Eval
+
+```bash
+pip install -e ".[azure,dev]"
+folioiq-eval                         # all fixture packs
+folioiq-eval tests/fixtures/packs/po
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+See [PLAN.md](PLAN.md) for design phases.

folioiq-0.1.0/PLAN.md

@@ -0,0 +1,91 @@
+# FolioIQ — Build Plan
+
+Provider-agnostic document extraction. Spec (YAML + optional MD) in → structured data out.
+
+**Package:** `folioiq`  
+**Promise:** consistent interface + providers + validation — not “always accurate.”
+
+Keep it simple. Ship one phase at a time.
+
+---
+
+## Public API (target)
+
+```python
+from folioiq import DocumentExtractor
+
+extractor = DocumentExtractor.from_env()
+result = extractor.extract("invoice.pdf", spec="specs/invoice.yaml")
+
+if result.is_valid:
+    process(result.data)
+```
+
+---
+
+## Phases
+
+### Phase 0 — Scaffold ✅ done
+- Repo layout, `pyproject.toml`, installable package
+- Stub `DocumentExtractor` + `ExtractionResult`
+- Config / env skeleton
+- Extras: `[azure]` declared (deps unused until later)
+
+**Done when:** `pip install -e .` and `from folioiq import DocumentExtractor` works.
+
+### Phase 1 — Spec + models ✅ done
+- Load YAML → field schema → Pydantic model (`load_spec`, `build_model`)
+- Optional sibling `.md` instructions
+- Example: `examples/invoice.yaml` + `invoice.md`
+- No LLM yet (`extract()` still Phase 2)
+
+### Phase 2 — Native parse + Azure OpenAI ✅ done
+- PyMuPDF → embedded PDF text
+- Prompt from YAML + MD
+- Azure OpenAI structured output (`folioiq[azure]`)
+- Digital PDF path only; inject `llm=` for tests / custom clients
+
+```python
+extractor = DocumentExtractor.from_env()
+result = extractor.extract("invoice.pdf", spec="examples/invoice.yaml")
+```
+
+### Phase 3 — Azure DI + simple router ✅ done
+- Auto: text PDF → `pymupdf`; scant/image → `azure_di`
+- Explicit: `pipeline.mode: explicit` + `parser: pymupdf|azure_di`
+- Inject `ocr=` for tests (same pattern as `llm=`)
+
+### Phase 4 — Validation + one fallback ✅ done
+- Required / type checks via `validate_extraction`
+- One retry with the alternate parser (`pymupdf` ↔ `azure_di`)
+- `is_valid`, `validation_errors`, `metadata.fallback_used`
+
+### Phase 5 — Fixtures / eval ✅ done
+- Packs under `tests/fixtures/packs/{po,so,contract,dr}`
+- `expected.json` ground truth (dr pack placeholder until labeled)
+- `python -m folioiq.eval [pack_dir]` or `folioiq-eval`
+- Field accuracy scoring (loose string / number match)
+
+### Later (only if needed)
+- OpenAI / Bedrock / Textract / Docling extras
+- Rich layout IR, business-rule engine, async API
+
+---
+
+## V1 providers (hard cut)
+
+| In | Out for now |
+|----|-------------|
+| PyMuPDF | Docling |
+| Azure DI | Textract |
+| Azure OpenAI | Other LLMs |
+
+---
+
+## Rules
+
+1. Don’t add providers until the previous phase works.
+2. One YAML dialect only (new nested `fields` style).
+3. Secrets in env only.
+4. Prefer small files and clear names over deep abstractions.
+5. Stop after each phase and review before the next.

folioiq-0.1.0/README.md

@@ -0,0 +1,64 @@
+# FolioIQ
+
+[![PyPI](https://img.shields.io/badge/pypi-folioiq-blue)](https://pypi.org/project/folioiq/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Schema-driven document extraction. YAML spec (+ optional MD) in → structured data out.
+
+```python
+from folioiq import DocumentExtractor
+
+extractor = DocumentExtractor.from_env()
+result = extractor.extract("invoice.pdf", spec="examples/invoice.yaml")
+
+if result.is_valid:
+    print(result.data)
+else:
+    print(result.validation_errors)
+```
+
+## Install
+
+```bash
+pip install folioiq
+pip install "folioiq[azure]"   # Azure OpenAI + Document Intelligence
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/auspicious123/folioiq-sdk.git
+cd folioiq-sdk
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[azure,dev]"
+cp .env.example .env   # fill Azure vars
+```
+
+## Spec only (no LLM)
+
+```python
+spec = extractor.load_spec("examples/invoice.yaml")
+Model = extractor.build_model(spec)
+```
+
+## Pipeline override (YAML)
+
+```yaml
+pipeline:
+  mode: explicit
+  parser: azure_di   # or pymupdf
+```
+
+## Eval
+
+```bash
+pip install -e ".[azure,dev]"
+folioiq-eval                         # all fixture packs
+folioiq-eval tests/fixtures/packs/po
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+See [PLAN.md](PLAN.md) for design phases.

folioiq-0.1.0/examples/invoice.md

@@ -0,0 +1,13 @@
+# Invoice Extraction Instructions
+
+Extract invoice information exactly as represented in the document.
+
+Rules:
+
+- Never invent missing values.
+- Use null when a field is not present.
+- Preserve invoice and PO numbers exactly (keep leading zeros).
+- Do not infer currency from the vendor's country.
+- Preserve decimal amounts.
+- Extract every visible line item.
+- Use the invoice total, not subtotal, as total_amount.

folioiq-0.1.0/examples/invoice.yaml

@@ -0,0 +1,64 @@
+name: invoice
+version: "1.0"
+
+document:
+  allowed_types:
+    - pdf
+    - png
+    - jpg
+
+pipeline:
+  mode: auto
+
+extraction:
+  fields:
+    invoice_number:
+      type: string
+      required: true
+      description: >
+        Unique invoice identifier assigned by the supplier.
+
+    invoice_date:
+      type: date
+      required: true
+      description: Date the invoice was issued.
+
+    vendor_name:
+      type: string
+      required: true
+      description: Legal or trading name of the supplier.
+
+    po_number:
+      type: string
+      required: false
+      description: Purchase order number referenced by the invoice, if any.
+
+    currency:
+      type: string
+      required: true
+      description: ISO currency code (e.g. USD, PHP, INR).
+
+    total_amount:
+      type: number
+      required: true
+      description: Invoice grand total (not subtotal).
+
+    line_items:
+      type: array
+      required: false
+      description: Line items on the invoice.
+      items:
+        type: object
+        fields:
+          description:
+            type: string
+            required: false
+          quantity:
+            type: number
+            required: false
+          unit_price:
+            type: number
+            required: false
+          amount:
+            type: number
+            required: false

folioiq-0.1.0/examples/invoice_explicit_di.yaml

@@ -0,0 +1,24 @@
+name: invoice
+version: "1.0"
+
+document:
+  allowed_types:
+    - pdf
+    - png
+    - jpg
+
+# Force Azure DI even for digital PDFs (optional)
+pipeline:
+  mode: explicit
+  parser: azure_di
+
+extraction:
+  fields:
+    invoice_number:
+      type: string
+      required: true
+      description: Invoice id
+    total_amount:
+      type: number
+      required: false
+      description: Grand total

folioiq-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "folioiq"
+version = "0.1.0"
+description = "Schema-driven document extraction with pluggable providers"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+    { name = "auspicious123", email = "auspicious123@users.noreply.github.com" },
+]
+keywords = [
+    "document-extraction",
+    "llm",
+    "ocr",
+    "pdf",
+    "azure",
+    "pydantic",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "pyyaml>=6.0",
+    "python-dotenv>=1.0",
+    "pymupdf>=1.24.0",
+]
+
+[project.optional-dependencies]
+azure = [
+    "langchain-openai>=0.2.0",
+    "langchain-core>=0.3.0",
+    "azure-ai-documentintelligence>=1.0.0",
+]
+dev = [
+    "pytest>=8.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+folioiq-eval = "folioiq.eval:main"
+
+[project.urls]
+Homepage = "https://github.com/auspicious123/folioiq-sdk"
+Repository = "https://github.com/auspicious123/folioiq-sdk"
+Issues = "https://github.com/auspicious123/folioiq-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/folioiq"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/folioiq" = "folioiq"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

folioiq-0.1.0/src/folioiq/__init__.py

@@ -0,0 +1,20 @@
+"""FolioIQ — schema-driven document extraction."""
+
+from folioiq.client import DocumentExtractor
+from folioiq.exceptions import FolioIQError, NotImplementedPhaseError, SpecError
+from folioiq.models import ExtractionResult
+from folioiq.specs import ExtractionSpec, FieldSpec, build_model, load_spec
+
+__all__ = [
+    "DocumentExtractor",
+    "ExtractionResult",
+    "ExtractionSpec",
+    "FieldSpec",
+    "FolioIQError",
+    "NotImplementedPhaseError",
+    "SpecError",
+    "build_model",
+    "load_spec",
+]
+
+__version__ = "0.1.0"

folioiq-0.1.0/src/folioiq/azure_di.py

@@ -0,0 +1,61 @@
+"""Azure Document Intelligence OCR (requires folioiq[azure])."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from folioiq.config import FolioIQSettings
+from folioiq.exceptions import FolioIQError
+from folioiq.io import DocumentInput, read_document_bytes
+
+
+class OCRClient(Protocol):
+    def extract_text(self, document: DocumentInput) -> str:
+        ...
+
+
+class AzureDIClient:
+    """OCR via Azure Document Intelligence prebuilt-read."""
+
+    def __init__(self, settings: FolioIQSettings, model_id: str = "prebuilt-read") -> None:
+        self.settings = settings
+        self.model_id = model_id
+        self._client = self._build_client()
+
+    def _build_client(self):
+        endpoint = self.settings.azure_doc_intelligence_endpoint
+        key = self.settings.azure_doc_intelligence_key
+        if not endpoint or not key:
+            raise FolioIQError(
+                "Azure Document Intelligence is not configured. "
+                "Set AZURE_DOC_INTELLIGENCE_ENDPOINT and AZURE_DOC_INTELLIGENCE_KEY."
+            )
+        try:
+            from azure.ai.documentintelligence import DocumentIntelligenceClient
+            from azure.core.credentials import AzureKeyCredential
+        except ImportError as exc:
+            raise FolioIQError(
+                "Azure DI requires: pip install 'folioiq[azure]'"
+            ) from exc
+
+        return DocumentIntelligenceClient(
+            endpoint=endpoint,
+            credential=AzureKeyCredential(key),
+        )
+
+    def extract_text(self, document: DocumentInput) -> str:
+        data, _ = read_document_bytes(document)
+        poller = self._client.begin_analyze_document(
+            self.model_id,
+            body=data,
+            content_type="application/octet-stream",
+        )
+        result = poller.result()
+        text = (result.content or "").strip()
+        if not text:
+            raise FolioIQError("Azure DI returned empty OCR text")
+        return text
+
+
+def get_default_ocr(settings: FolioIQSettings) -> OCRClient:
+    return AzureDIClient(settings)