fastdocparse 0.2.0__tar.gz → 0.3.0__tar.gz

fastdocparse-0.3.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: fastdocparse
+Version: 0.3.0
+Summary: Extract structured data from semi-structured documents using any OpenAI-compatible LLM, with per-field grounding and confidence.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pranjalparmar/fastdocparse
+Project-URL: Repository, https://github.com/pranjalparmar/fastdocparse
+Project-URL: Issues, https://github.com/pranjalparmar/fastdocparse/issues
+Project-URL: Documentation, https://github.com/pranjalparmar/fastdocparse/tree/main/docs
+Keywords: document-extraction,llm,pdf,ocr,invoice-extraction,structured-data,openai,ollama,grounding
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: openai>=1.0
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: rapidocr-onnxruntime>=1.3
+Requires-Dist: typer>=0.12
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# fastdocparse
+
+[![PyPI](https://img.shields.io/pypi/v/fastdocparse.svg)](https://pypi.org/project/fastdocparse/)
+[![CI](https://github.com/pranjalparmar/fastdocparse/actions/workflows/ci.yml/badge.svg)](https://github.com/pranjalparmar/fastdocparse/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Extract structured data from semi-structured documents (invoices, bills, tax forms, resumes, bank statements, shipment manifests) using any OpenAI-compatible LLM (OpenAI, Ollama, vLLM, Groq, etc.), with **per-field grounding and confidence**, not just raw extraction.
+
+## Why this, not just another parser
+
+Most extractors give you a value and no way to know if it's real. This one tells you:
+
+- **`grounded`**: the value was found verbatim (or near-verbatim) in the source document text.
+- **`ungrounded`**: the value doesn't appear in the source, likely a hallucination. Flag for human review.
+- **`missing_required`**: a field you marked required came back empty.
+- **`invalid_format`**: the value doesn't match a pattern/enum constraint you declared (e.g. a shipment status outside the allowed list).
+- **`failed_check`**: a custom cross-field rule failed (e.g. line items don't sum to the stated total).
+
+No extra LLM call for any of this: it's deterministic, string/rule-based validation against text you already extracted.
+
+**Where it fits:** semi-structured documents with recurring fields (invoices, bills, tax forms, resumes, statements), and prose documents where *proving* a value came from the source matters (contracts, legal clauses, insurance claims). It is not a vision-LLM pipeline. It works from extracted text (digital PDF text layer, or local OCR for scans/images), which is what keeps it fast, cheap, and usable with small local models. Messy handwritten forms or complex multi-column layouts are a known weaker spot (see [document-extractor-spec.md](document-extractor-spec.md)).
+
+## How this compares
+
+| Project | Approach | Where it beats fastdocparse | Where fastdocparse can beat it |
+|---|---|---|---|
+| **[Sparrow](https://github.com/katanaml/sparrow)** (katanaml) | Vision-LLM first (MLX/vLLM/Ollama/Mistral OCR), multi-service platform, API-first | Layout-aware (sees the page), mature, table templates for complex tables | No GPU required, single `pip install`, Pydantic-schema devex vs. raw JSON-string CLI args |
+| **[LangExtract](https://github.com/google/langextract)** (Google) | Text-first, source-grounding (character-offset mapping), few-shot examples required | Real grounding/traceability, brand trust | Purpose-built for documents (OCR routing) vs. text-in/text-out |
+
+**The honest edge:** *fast, cheap, local-model-friendly extraction for clean-to-moderate documents*, not "better than Sparrow at everything." This has not yet been validated with a real head-to-head benchmark ([tracking issue](https://github.com/pranjalparmar/fastdocparse/issues/19)). Treat it as a design goal, not a proven claim, until that lands.
+
+## Two ways to use it
+
+| | Who it's for | How |
+|---|---|---|
+| **CLI** | No coding needed | `fastdocparse extract <file> <schema.json>` / `fastdocparse --version` |
+| **Python API** | Building it into your own app | `DocumentParser(client).extract(document_bytes, schema)` |
+
+Defining *what* to extract also has two paths: hand-write a JSON/YAML schema file, or describe it in plain English and let the LLM draft the schema for you.
+
+## Install
+
+```bash
+pip install fastdocparse
+```
+
+For local development instead:
+
+```bash
+git clone https://github.com/pranjalparmar/fastdocparse
+cd fastdocparse
+python -m venv venv
+source venv/bin/activate        # Windows: venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+You also need access to an LLM. Either:
+- An OpenAI API key (`export OPENAI_API_KEY=...` or pass `--api-key`), or
+- A local model via [Ollama](https://ollama.com/): no API key, no cloud, documents never leave your machine.
+
+## Quickstart: CLI (no coding)
+
+```bash
+# 1. Extract using one of the bundled example schemas
+fastdocparse extract sample_invoice.png src/fastdocparse/schemas/invoice.json \
+  --model gpt-4o-mini --api-key sk-...
+
+# Or with a local model via Ollama (no API key needed):
+fastdocparse extract sample_invoice.png src/fastdocparse/schemas/invoice.json \
+  --model llama3.2 --base-url http://localhost:11434/v1 --api-key ollama
+```
+
+Output is JSON, printed to stdout (or saved with `--output result.json`):
+
+```json
+{
+  "_meta": { "truncated": false, "truncation_reason": null },
+  "invoice_number": { "value": "INV-9011", "confidence": "high", "flags": ["grounded"] },
+  "total_price": { "value": 100.0, "confidence": "high", "flags": ["grounded"] }
+}
+```
+
+Don't want to write JSON at all? Describe the fields in plain English instead:
+
+```bash
+fastdocparse schema-from-text \
+  "I want the invoice number, total price, and vendor name. Invoice number and total are required." \
+  --output my_invoice_schema.json
+
+# review my_invoice_schema.json, then:
+fastdocparse extract my_invoice.pdf my_invoice_schema.json
+```
+
+## Quickstart: Python API
+
+```python
+from fastdocparse import Schema, Field, LLMClient, DocumentParser
+
+schema = Schema(
+    name="Invoice",
+    fields=[
+        Field(name="invoice_number", description="The invoice number", required=True),
+        Field(name="total_price", description="Total amount due", type="number", required=True),
+    ],
+)
+
+client = LLMClient(model="gpt-4o-mini", api_key="sk-...")
+# or: LLMClient(base_url="http://localhost:11434/v1", api_key="ollama", model="llama3.2")
+
+parser = DocumentParser(client=client)
+
+with open("invoice.pdf", "rb") as f:
+    result = parser.extract(f.read(), schema)
+
+print(result["invoice_number"])  # {'value': 'INV-9011', 'confidence': 'high', 'flags': ['grounded']}
+```
+
+## Full documentation
+
+- [Getting Started](docs/getting-started.md): step-by-step install, CLI, and API walkthroughs
+- [Schema Guide](docs/schema-guide.md): every field option (`type`, `required`, `pattern`, `enum`, `sub_fields`, few-shot `examples`), for JSON, YAML, and plain-English authoring
+- [Output & Validation](docs/output-format.md): the full result shape, what each confidence flag means, and how to write custom cross-check rules
+- [Architecture](docs/architecture.md): diagrams of the pipeline, the module dependency graph, and where to plug in a contribution
+- [Project spec](document-extractor-spec.md): architecture, phased roadmap, honest competitive positioning
+
+Want to contribute? Start with [docs/architecture.md](docs/architecture.md) for the map, then [CONTRIBUTING.md](CONTRIBUTING.md) for the process.
+
+## Status
+
+Core extraction, grounding, chunking, both CLI/API paths, and real packaging are implemented and tested (75 tests, `pytest -v`). Published on PyPI as [`fastdocparse`](https://pypi.org/project/fastdocparse/). `pip install fastdocparse` installs a working `fastdocparse` command and a proper `fastdocparse.*` import namespace, verified end to end with a clean-virtualenv install straight from the real public index. Not yet done: a hosted API. See [document-extractor-spec.md](document-extractor-spec.md) for the roadmap.

fastdocparse-0.3.0/README.md

@@ -0,0 +1,130 @@
+# fastdocparse
+
+[![PyPI](https://img.shields.io/pypi/v/fastdocparse.svg)](https://pypi.org/project/fastdocparse/)
+[![CI](https://github.com/pranjalparmar/fastdocparse/actions/workflows/ci.yml/badge.svg)](https://github.com/pranjalparmar/fastdocparse/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Extract structured data from semi-structured documents (invoices, bills, tax forms, resumes, bank statements, shipment manifests) using any OpenAI-compatible LLM (OpenAI, Ollama, vLLM, Groq, etc.), with **per-field grounding and confidence**, not just raw extraction.
+
+## Why this, not just another parser
+
+Most extractors give you a value and no way to know if it's real. This one tells you:
+
+- **`grounded`**: the value was found verbatim (or near-verbatim) in the source document text.
+- **`ungrounded`**: the value doesn't appear in the source, likely a hallucination. Flag for human review.
+- **`missing_required`**: a field you marked required came back empty.
+- **`invalid_format`**: the value doesn't match a pattern/enum constraint you declared (e.g. a shipment status outside the allowed list).
+- **`failed_check`**: a custom cross-field rule failed (e.g. line items don't sum to the stated total).
+
+No extra LLM call for any of this: it's deterministic, string/rule-based validation against text you already extracted.
+
+**Where it fits:** semi-structured documents with recurring fields (invoices, bills, tax forms, resumes, statements), and prose documents where *proving* a value came from the source matters (contracts, legal clauses, insurance claims). It is not a vision-LLM pipeline. It works from extracted text (digital PDF text layer, or local OCR for scans/images), which is what keeps it fast, cheap, and usable with small local models. Messy handwritten forms or complex multi-column layouts are a known weaker spot (see [document-extractor-spec.md](document-extractor-spec.md)).
+
+## How this compares
+
+| Project | Approach | Where it beats fastdocparse | Where fastdocparse can beat it |
+|---|---|---|---|
+| **[Sparrow](https://github.com/katanaml/sparrow)** (katanaml) | Vision-LLM first (MLX/vLLM/Ollama/Mistral OCR), multi-service platform, API-first | Layout-aware (sees the page), mature, table templates for complex tables | No GPU required, single `pip install`, Pydantic-schema devex vs. raw JSON-string CLI args |
+| **[LangExtract](https://github.com/google/langextract)** (Google) | Text-first, source-grounding (character-offset mapping), few-shot examples required | Real grounding/traceability, brand trust | Purpose-built for documents (OCR routing) vs. text-in/text-out |
+
+**The honest edge:** *fast, cheap, local-model-friendly extraction for clean-to-moderate documents*, not "better than Sparrow at everything." This has not yet been validated with a real head-to-head benchmark ([tracking issue](https://github.com/pranjalparmar/fastdocparse/issues/19)). Treat it as a design goal, not a proven claim, until that lands.
+
+## Two ways to use it
+
+| | Who it's for | How |
+|---|---|---|
+| **CLI** | No coding needed | `fastdocparse extract <file> <schema.json>` / `fastdocparse --version` |
+| **Python API** | Building it into your own app | `DocumentParser(client).extract(document_bytes, schema)` |
+
+Defining *what* to extract also has two paths: hand-write a JSON/YAML schema file, or describe it in plain English and let the LLM draft the schema for you.
+
+## Install
+
+```bash
+pip install fastdocparse
+```
+
+For local development instead:
+
+```bash
+git clone https://github.com/pranjalparmar/fastdocparse
+cd fastdocparse
+python -m venv venv
+source venv/bin/activate        # Windows: venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+You also need access to an LLM. Either:
+- An OpenAI API key (`export OPENAI_API_KEY=...` or pass `--api-key`), or
+- A local model via [Ollama](https://ollama.com/): no API key, no cloud, documents never leave your machine.
+
+## Quickstart: CLI (no coding)
+
+```bash
+# 1. Extract using one of the bundled example schemas
+fastdocparse extract sample_invoice.png src/fastdocparse/schemas/invoice.json \
+  --model gpt-4o-mini --api-key sk-...
+
+# Or with a local model via Ollama (no API key needed):
+fastdocparse extract sample_invoice.png src/fastdocparse/schemas/invoice.json \
+  --model llama3.2 --base-url http://localhost:11434/v1 --api-key ollama
+```
+
+Output is JSON, printed to stdout (or saved with `--output result.json`):
+
+```json
+{
+  "_meta": { "truncated": false, "truncation_reason": null },
+  "invoice_number": { "value": "INV-9011", "confidence": "high", "flags": ["grounded"] },
+  "total_price": { "value": 100.0, "confidence": "high", "flags": ["grounded"] }
+}
+```
+
+Don't want to write JSON at all? Describe the fields in plain English instead:
+
+```bash
+fastdocparse schema-from-text \
+  "I want the invoice number, total price, and vendor name. Invoice number and total are required." \
+  --output my_invoice_schema.json
+
+# review my_invoice_schema.json, then:
+fastdocparse extract my_invoice.pdf my_invoice_schema.json
+```
+
+## Quickstart: Python API
+
+```python
+from fastdocparse import Schema, Field, LLMClient, DocumentParser
+
+schema = Schema(
+    name="Invoice",
+    fields=[
+        Field(name="invoice_number", description="The invoice number", required=True),
+        Field(name="total_price", description="Total amount due", type="number", required=True),
+    ],
+)
+
+client = LLMClient(model="gpt-4o-mini", api_key="sk-...")
+# or: LLMClient(base_url="http://localhost:11434/v1", api_key="ollama", model="llama3.2")
+
+parser = DocumentParser(client=client)
+
+with open("invoice.pdf", "rb") as f:
+    result = parser.extract(f.read(), schema)
+
+print(result["invoice_number"])  # {'value': 'INV-9011', 'confidence': 'high', 'flags': ['grounded']}
+```
+
+## Full documentation
+
+- [Getting Started](docs/getting-started.md): step-by-step install, CLI, and API walkthroughs
+- [Schema Guide](docs/schema-guide.md): every field option (`type`, `required`, `pattern`, `enum`, `sub_fields`, few-shot `examples`), for JSON, YAML, and plain-English authoring
+- [Output & Validation](docs/output-format.md): the full result shape, what each confidence flag means, and how to write custom cross-check rules
+- [Architecture](docs/architecture.md): diagrams of the pipeline, the module dependency graph, and where to plug in a contribution
+- [Project spec](document-extractor-spec.md): architecture, phased roadmap, honest competitive positioning
+
+Want to contribute? Start with [docs/architecture.md](docs/architecture.md) for the map, then [CONTRIBUTING.md](CONTRIBUTING.md) for the process.
+
+## Status
+
+Core extraction, grounding, chunking, both CLI/API paths, and real packaging are implemented and tested (75 tests, `pytest -v`). Published on PyPI as [`fastdocparse`](https://pypi.org/project/fastdocparse/). `pip install fastdocparse` installs a working `fastdocparse` command and a proper `fastdocparse.*` import namespace, verified end to end with a clean-virtualenv install straight from the real public index. Not yet done: a hosted API. See [document-extractor-spec.md](document-extractor-spec.md) for the roadmap.

fastdocparse-0.3.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "fastdocparse"
+version = "0.3.0"
+description = "Extract structured data from semi-structured documents using any OpenAI-compatible LLM, with per-field grounding and confidence."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9,<3.13"  # capped by rapidocr-onnxruntime's own upper bound (checked live against PyPI)
+keywords = [
+    "document-extraction",
+    "llm",
+    "pdf",
+    "ocr",
+    "invoice-extraction",
+    "structured-data",
+    "openai",
+    "ollama",
+    "grounding",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Text Processing :: Linguistic",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "openai>=1.0",
+    "pymupdf>=1.24",
+    "pillow>=10.0",
+    "rapidocr-onnxruntime>=1.3",
+    "typer>=0.12",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/pranjalparmar/fastdocparse"
+Repository = "https://github.com/pranjalparmar/fastdocparse"
+Issues = "https://github.com/pranjalparmar/fastdocparse/issues"
+Documentation = "https://github.com/pranjalparmar/fastdocparse/tree/main/docs"
+
+[project.scripts]
+fastdocparse = "fastdocparse.cli:app"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fastdocparse = ["schemas/*.json", "py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/fastdocparse/cli.py" = ["B008"]

{fastdocparse-0.2.0 → fastdocparse-0.3.0}/src/fastdocparse/__init__.py

@@ -10,41 +10,55 @@ OpenAI-compatible LLM, with per-field grounding and confidence.
 
 from .cache import Cache, InMemoryCache
 from .config import ExtractionConfig
-from .grounding import Issue, check_substring, cross_check, date_parseable_rule, numeric_sum_rule, validate_field_constraints
+from .grounding import (
+    Issue,
+    check_substring,
+    cross_check,
+    date_parseable_rule,
+    numeric_sum_rule,
+    validate_field_constraints,
+)
 from .llm_client import LLMClient, LLMClientError
-from .parser import DocumentParser, EmptyDocumentError, UnknownIngestionKindError, register_default_ingestion_handler
+from .parser import (
+    DocumentParser,
+    EmptyDocumentError,
+    UnknownIngestionKindError,
+    register_default_ingestion_handler,
+)
 from .result import ExtractionMeta, ExtractionResult, FieldResult
 from .schema import Field, Schema
 from .schema_compiler import compile_schema_from_description
 
 try:
+    from importlib.metadata import PackageNotFoundError
     from importlib.metadata import version as _pkg_version
+
     # Looks up by the PyPI *distribution* name (pyproject.toml's [project] name) — keep
     # this string in sync with that if the distribution is ever renamed again.
     __version__ = _pkg_version("fastdocparse")
-except Exception:
+except PackageNotFoundError:
     __version__ = "0.0.0+unknown"
 
 __all__ = [
-    "Schema",
-    "Field",
-    "LLMClient",
-    "LLMClientError",
+    "Cache",
     "DocumentParser",
     "EmptyDocumentError",
-    "UnknownIngestionKindError",
-    "register_default_ingestion_handler",
     "ExtractionConfig",
-    "Cache",
-    "InMemoryCache",
+    "ExtractionMeta",
     "ExtractionResult",
+    "Field",
     "FieldResult",
-    "ExtractionMeta",
+    "InMemoryCache",
     "Issue",
+    "LLMClient",
+    "LLMClientError",
+    "Schema",
+    "UnknownIngestionKindError",
     "check_substring",
+    "compile_schema_from_description",
     "cross_check",
-    "validate_field_constraints",
-    "numeric_sum_rule",
     "date_parseable_rule",
-    "compile_schema_from_description",
+    "numeric_sum_rule",
+    "register_default_ingestion_handler",
+    "validate_field_constraints",
 ]

{fastdocparse-0.2.0 → fastdocparse-0.3.0}/src/fastdocparse/cache.py

@@ -4,19 +4,20 @@ Caching is skipped whenever custom `rules` are passed to extract(), since a rule
 arbitrary callable that can't be safely fingerprinted — caching would risk returning a
 result validated under a different rule than the one just requested.
 """
+from __future__ import annotations
 
 import hashlib
 import json
 from collections import OrderedDict
-from typing import Any, Callable, Dict, Optional, Protocol
+from typing import Any, Callable, Protocol
 
 from .config import ExtractionConfig
 from .schema import Schema
 
 
 class Cache(Protocol):
-    def get(self, key: str) -> Optional[Dict[str, Any]]: ...
-    def set(self, key: str, value: Dict[str, Any]) -> None: ...
+    def get(self, key: str) -> dict[str, Any] | None: ...
+    def set(self, key: str, value: dict[str, Any]) -> None: ...
 
 
 class InMemoryCache:
@@ -27,19 +28,19 @@ class InMemoryCache:
     process exits before the cache could grow unbounded.
     """
 
-    def __init__(self, max_size: Optional[int] = None):
+    def __init__(self, max_size: int | None = None):
         if max_size is not None and max_size <= 0:
             raise ValueError(f"max_size must be positive, got {max_size}")
         self._max_size = max_size
-        self._store: "OrderedDict[str, Dict[str, Any]]" = OrderedDict()
+        self._store: OrderedDict[str, dict[str, Any]] = OrderedDict()
 
-    def get(self, key: str) -> Optional[Dict[str, Any]]:
+    def get(self, key: str) -> dict[str, Any] | None:
         if key not in self._store:
             return None
         self._store.move_to_end(key)
         return self._store[key]
 
-    def set(self, key: str, value: Dict[str, Any]) -> None:
+    def set(self, key: str, value: dict[str, Any]) -> None:
         self._store[key] = value
         self._store.move_to_end(key)
         if self._max_size is not None:

{fastdocparse-0.2.0 → fastdocparse-0.3.0}/src/fastdocparse/cli.py

@@ -4,16 +4,17 @@ Usage:
     fastdocparse extract document.pdf invoice_schema.json
     fastdocparse extract receipt.jpg shipment_schema.json --model llama3 --base-url http://localhost:11434/v1
 """
+from __future__ import annotations
 
 import importlib
 import json
 import os
 from pathlib import Path
-from typing import Optional
 
 import typer
 from pydantic import ValidationError
 
+from . import __version__
 from .llm_client import LLMClient, LLMClientError
 from .parser import DocumentParser, EmptyDocumentError, UnknownIngestionKindError
 from .schema import Schema
@@ -48,17 +49,82 @@ IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg"}
 SUPPORTED_EXTENSIONS = IMAGE_EXTENSIONS | {".pdf"}
 
 
+def _check_llm_credentials(base_url: str | None, api_key: str | None) -> None:
+    """Catch the common "nothing configured" case before making any network call, rather
+    than letting it surface as an OpenAI auth error after a request round-trip. A
+    `base_url` (local/self-hosted endpoint) needs no real key, so this only fires when
+    neither a base_url nor a key is present from any source (flag or env var). A blank
+    or whitespace-only value (e.g. an env var set to "") counts as absent, not present,
+    since otherwise it would silently reach LLMClient's own dummy-key fallback and
+    proceed to a doomed network call instead of failing here with a clear message."""
+    if (base_url and base_url.strip()) or (api_key and api_key.strip()):
+        return
+
+    typer.echo(
+        "Error: no LLM credentials configured.\n"
+        "\n"
+        "To use OpenAI, set an API key:\n"
+        "  export OPENAI_API_KEY=sk-...\n"
+        "  (or pass --api-key)\n"
+        "\n"
+        "To use a local model via Ollama instead, pass --base-url pointing at your\n"
+        "Ollama server. No real key is needed there; --api-key accepts any non-empty\n"
+        "value in that case.\n"
+        "\n"
+        "Run 'fastdocparse extract --help' for the full list of options.",
+        err=True,
+    )
+    raise typer.Exit(code=1)
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+
+    typer.echo(f"fastdocparse {__version__}")
+    raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    return None
+
+
 @app.command()
 def extract(
     file: Path = typer.Argument(..., exists=True, readable=True, help="Path to the PDF/PNG/JPG document."),
-    schema: Path = typer.Argument(..., exists=True, readable=True, help="Path to a .json or .yaml schema file listing the fields to extract."),
-    model: str = typer.Option("gpt-4o-mini", "--model", "-m", help="Model name, e.g. gpt-4o-mini, llama3."),
-    base_url: Optional[str] = typer.Option(None, "--base-url", help="OpenAI-compatible API base URL. Omit for OpenAI; use e.g. http://localhost:11434/v1 for Ollama."),
-    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="LLM_API_KEY", help="API key. Not needed for local Ollama."),
-    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Write the JSON result to this file instead of printing it."),
-    kind: Optional[str] = typer.Option(None, "--kind", help="Override ingestion routing (e.g. 'docx' for a custom handler loaded via FASTDOCPARSE_PLUGINS). Defaults to auto-detecting pdf/image from the file extension."),
+    schema: Path | None = typer.Argument(None, exists=True, readable=True, help="Path to a .json or .yaml schema file listing the fields to extract."),
+    model: str = typer.Option("gpt-4o-mini", "--model", "-m", envvar="FASTDOCPARSE_MODEL", help="Model name, e.g. gpt-4o-mini, llama3."),
+    base_url: str | None = typer.Option(None, "--base-url", envvar="FASTDOCPARSE_BASE_URL", help="OpenAI-compatible API base URL. Omit for OpenAI; use e.g. http://localhost:11434/v1 for Ollama."),
+    api_key: str | None = typer.Option(None, "--api-key", envvar=["LLM_API_KEY", "OPENAI_API_KEY"], help="API key. Not needed for local Ollama."),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Write the JSON result to this file instead of printing it."),
+    kind: str | None = typer.Option(None, "--kind", help="Override ingestion routing (e.g. 'docx' for a custom handler loaded via FASTDOCPARSE_PLUGINS). Defaults to auto-detecting pdf/image from the file extension."),
 ):
     """Extract the fields defined in SCHEMA from FILE and print the result as JSON."""
+    if schema is None:
+        typer.echo(
+            "Error: a schema file is required.\n"
+            "\n"
+            "Quickest way to create one — describe your fields in plain English:\n"
+            "  fastdocparse schema-from-text \"invoice number, total amount, and line items\" --output my_schema.json\n"
+            "\n"
+            "Or start from a bundled example schema:\n"
+            "  fastdocparse list-schemas\n"
+            "\n"
+            "Then extract with:\n"
+            "  fastdocparse extract " + str(file) + " my_schema.json",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
     if kind is None and file.suffix.lower() not in SUPPORTED_EXTENSIONS:
         typer.echo(f"Unsupported file type {file.suffix!r}. Supported: .pdf, .png, .jpg, .jpeg (or pass --kind).", err=True)
         raise typer.Exit(code=1)
@@ -69,6 +135,8 @@ def extract(
         typer.echo(f"Could not load schema from {schema}: {e}", err=True)
         raise typer.Exit(code=1)
 
+    _check_llm_credentials(base_url, api_key)
+
     client = LLMClient(base_url=base_url, api_key=api_key, model=model)
     document_parser = DocumentParser(client=client)
 
@@ -108,9 +176,9 @@ def extract(
 def schema_from_text(
     description: str = typer.Argument(..., help="Plain-English description of the fields you want extracted, e.g. \"invoice number, total price, and a list of line items with product name and quantity\"."),
     output: Path = typer.Option(..., "--output", "-o", help="Where to save the generated schema (.json)."),
-    model: str = typer.Option("gpt-4o-mini", "--model", "-m", help="Model name, e.g. gpt-4o-mini, llama3."),
-    base_url: Optional[str] = typer.Option(None, "--base-url", help="OpenAI-compatible API base URL. Omit for OpenAI; use e.g. http://localhost:11434/v1 for Ollama."),
-    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="LLM_API_KEY", help="API key. Not needed for local Ollama."),
+    model: str = typer.Option("gpt-4o-mini", "--model", "-m", envvar="FASTDOCPARSE_MODEL", help="Model name, e.g. gpt-4o-mini, llama3."),
+    base_url: str | None = typer.Option(None, "--base-url", envvar="FASTDOCPARSE_BASE_URL", help="OpenAI-compatible API base URL. Omit for OpenAI; use e.g. http://localhost:11434/v1 for Ollama."),
+    api_key: str | None = typer.Option(None, "--api-key", envvar=["LLM_API_KEY", "OPENAI_API_KEY"], help="API key. Not needed for local Ollama."),
 ):
     """Turn a plain-English description of the fields you want into a schema file.
 
@@ -118,6 +186,8 @@ def schema_from_text(
     names and types from your description, and a wrong guess here affects every
     document you later run against this schema.
     """
+    _check_llm_credentials(base_url, api_key)
+
     client = LLMClient(base_url=base_url, api_key=api_key, model=model)
     try:
         doc_schema = compile_schema_from_description(description, client)
@@ -136,5 +206,27 @@ def schema_from_text(
     typer.echo("Review it, then run: fastdocparse extract <your_document> " + str(output))
 
 
+@app.command(name="list-schemas")
+def list_schemas():
+    """List the bundled example schemas you can copy as a starting point.
+
+    Copy any of the listed files into your project and pass the copy to `extract`.
+    This is the fastest way to get started without an LLM-generated schema.
+    """
+    schemas_dir = Path(__file__).parent / "schemas"
+    schema_files = sorted(schemas_dir.glob("*.json"))
+    if not schema_files:
+        typer.echo("No bundled schemas found.", err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo("Bundled example schemas (copy one as your starting point):\n")
+    for path in schema_files:
+        typer.echo(f"  {path}")
+    typer.echo(
+        "\nTo use one directly:\n"
+        "  fastdocparse extract document.pdf " + str(schema_files[0])
+    )
+
+
 if __name__ == "__main__":
     app()