terbium-parse 0.1.0__tar.gz

terbium_parse-0.1.0/LICENSE

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

terbium_parse-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: terbium-parse
+Version: 0.1.0
+Summary: A god-level algorithmic multi-file parser (PDF/PPTX/XLSX/CSV) that scores its own confidence and only reaches for AI when it is genuinely stuck.
+Author: anishfyi
+License: MIT
+Project-URL: Homepage, https://anishfyi.github.io/terbium
+Project-URL: Repository, https://github.com/anishfyi/terbium
+Keywords: parser,pdf,pptx,xlsx,csv,extraction,document,ai,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyMuPDF>=1.24
+Requires-Dist: python-pptx>=0.6.23
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pillow>=10.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.34; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.7; extra == "gemini"
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.34; extra == "ai"
+Requires-Dist: google-generativeai>=0.7; extra == "ai"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/anishfyi/terbium/main/assets/logo.png" width="150" alt="terbium: a periodic-table tile reading 65 Tb terbium">
+
+# terbium
+
+**A god-level algorithmic multi-file parser that knows when it is stuck.**
+It reconstructs a document's structure from geometry, scores its own confidence,
+and only reaches for an AI model when the algorithm cannot be sure.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-000000.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-000000.svg)](pyproject.toml)
+[![formats](https://img.shields.io/badge/PDF_PPTX_XLSX_CSV-000000.svg)](#what-it-parses)
+[![version](https://img.shields.io/badge/version-0.1.0-000000.svg)](pyproject.toml)
+
+[Website](https://anishfyi.github.io/terbium) · [Trove](https://github.com/anishfyi/trove)
+
+</div>
+
+---
+
+A vendor document carries most of its content as text but almost none of its
+structure. A furniture catalogue page is a 2-D matrix: rows are sizes, columns
+are finishes, and the cells are article numbers. Flatten it to text and the grid
+is gone, the columns collapse into a single line, and the numbers lose their
+meaning. terbium rebuilds that structure from the raw position of every word,
+and it is honest about how sure it is.
+
+Most parsers do one of two things: they fail silently on the hard pages, or they
+throw the whole document at an LLM and bill you for the easy pages too. terbium
+does neither. It solves what it can algorithmically, scores every record, and
+when a page is genuinely ambiguous it either routes just that page to the right
+model tier, or, if you gave it no key, tells you so in plain words.
+
+## The loop
+
+```
+FILE  ->  ADAPT  ->  RECONSTRUCT  ->  SCORE  ->  [ESCALATE]
+             |            |             |            |
+       pdf/pptx/     columns, rows,  confidence   hard pages only:
+       xlsx/csv      matrices from   per record   AI if key, else
+                     geometry                      "add a key" message
+```
+
+| Phase | What happens |
+|---|---|
+| **Adapt** | One adapter per format normalizes bytes into positioned words + images |
+| **Reconstruct** | Strip repeated headers, split two-page spreads, rebuild columns/rows/matrices from word geometry |
+| **Score** | Every table gets a 0-1 confidence from grid regularity, header presence, and fill |
+| **Escalate** | Below threshold: route the page to Haiku/Sonnet/Opus, or announce that a key would resolve it |
+
+## Quickstart
+
+```bash
+pip install terbium-parse
+```
+
+```python
+import terbium
+
+doc = terbium.parse("Furniture Catalogue.pdf")     # algorithmic only, no key needed
+print(doc.stats)                                    # Stats(total=725, confident=712, ambiguous=13)
+
+for r in doc.records:
+    print(r.sku, r.fields)
+
+# opt into AI only for the pages the engine could not resolve
+doc = terbium.parse("Furniture Catalogue.pdf",
+                    schema="furniture",
+                    ai=terbium.AI(anthropic_key="sk-..."))
+```
+
+Run it from the shell:
+
+```bash
+terbium "Furniture Catalogue.pdf" --schema furniture
+terbium report.xlsx --json out.json
+```
+
+## What it parses
+
+| Format | Engine | How |
+|---|---|---|
+| **PDF** | word-level geometry | rebuild columns/rows/matrices from the position of every word |
+| **PPTX** | python-pptx | native slides, tables and images, straight from the deck structure |
+| **XLSX** | openpyxl | cells, merged ranges propagated, wide/long layouts |
+| **CSV** | stdlib | delimiter, encoding and type inference |
+
+PDF gets the full geometry engine because a PDF throws its structure away. PPTX,
+XLSX and CSV already carry native structure, so terbium leans on it and parses
+them cleanly and cheaply.
+
+## Confidence and escalation
+
+terbium never pretends a shaky parse is solid. When it cannot be sure and no key
+is set, it prints exactly what it could not do:
+
+```
+terbium: 712/725 records parsed confidently.
+3 table(s) on page(s) 15, 26, 30 are ambiguous (no product title found above
+the table; sparse matrix: 5/9 cells filled; 2 row(s) do not line up).
+-> set ANTHROPIC_API_KEY or pass ai=terbium.AI(...)   recommended tier: Sonnet
+```
+
+Every record exposes its own `confidence` and the `reasons` behind it, so you can
+filter, sort, or route on it yourself.
+
+## The AI lane
+
+The AI lane is opt-in and only ever sees the hard pages.
+
+- **Routing.** Difficulty scales the tier: trivial to Haiku, moderate to Sonnet,
+  hard or low-confidence to Opus. Pin a tier with `terbium.AI(force_tier="opus")`.
+- **Arrange.** A hard table is handed to the routed model with the page's raw
+  text and, for PDFs, a rendered image, and rebuilt into a clean matrix.
+- **Vision.** Material icons (FSC, oiled, varnished) and finish swatches live only
+  in the pixels; `terbium.read_images(path, page, ai)` reads them with a vision
+  model. Note: Nano Banana (Gemini image) is for generation, not reading, so it is
+  not on the parse path.
+
+Keys come from `terbium.AI(...)` or the `ANTHROPIC_API_KEY` / `GEMINI_API_KEY`
+environment variables.
+
+## Schemas
+
+A schema turns reconstructed tables into typed records. Ships with two:
+
+- `generic` (default): one record per row for grids, one per cell for matrices.
+- `furniture`: product, size, finish, and metric + imperial dimensions per SKU.
+
+Add your own by subclassing `terbium.schema.Schema` and registering it.
+
+## Install from source
+
+```bash
+git clone https://github.com/anishfyi/terbium.git
+cd terbium
+pip install -e .
+```
+
+## License
+
+MIT. Built by [anishfyi](https://github.com/anishfyi).
+
+<div align="center"><sub>terbium · Tb · 65</sub></div>

terbium_parse-0.1.0/README.md

@@ -0,0 +1,145 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/anishfyi/terbium/main/assets/logo.png" width="150" alt="terbium: a periodic-table tile reading 65 Tb terbium">
+
+# terbium
+
+**A god-level algorithmic multi-file parser that knows when it is stuck.**
+It reconstructs a document's structure from geometry, scores its own confidence,
+and only reaches for an AI model when the algorithm cannot be sure.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-000000.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-000000.svg)](pyproject.toml)
+[![formats](https://img.shields.io/badge/PDF_PPTX_XLSX_CSV-000000.svg)](#what-it-parses)
+[![version](https://img.shields.io/badge/version-0.1.0-000000.svg)](pyproject.toml)
+
+[Website](https://anishfyi.github.io/terbium) · [Trove](https://github.com/anishfyi/trove)
+
+</div>
+
+---
+
+A vendor document carries most of its content as text but almost none of its
+structure. A furniture catalogue page is a 2-D matrix: rows are sizes, columns
+are finishes, and the cells are article numbers. Flatten it to text and the grid
+is gone, the columns collapse into a single line, and the numbers lose their
+meaning. terbium rebuilds that structure from the raw position of every word,
+and it is honest about how sure it is.
+
+Most parsers do one of two things: they fail silently on the hard pages, or they
+throw the whole document at an LLM and bill you for the easy pages too. terbium
+does neither. It solves what it can algorithmically, scores every record, and
+when a page is genuinely ambiguous it either routes just that page to the right
+model tier, or, if you gave it no key, tells you so in plain words.
+
+## The loop
+
+```
+FILE  ->  ADAPT  ->  RECONSTRUCT  ->  SCORE  ->  [ESCALATE]
+             |            |             |            |
+       pdf/pptx/     columns, rows,  confidence   hard pages only:
+       xlsx/csv      matrices from   per record   AI if key, else
+                     geometry                      "add a key" message
+```
+
+| Phase | What happens |
+|---|---|
+| **Adapt** | One adapter per format normalizes bytes into positioned words + images |
+| **Reconstruct** | Strip repeated headers, split two-page spreads, rebuild columns/rows/matrices from word geometry |
+| **Score** | Every table gets a 0-1 confidence from grid regularity, header presence, and fill |
+| **Escalate** | Below threshold: route the page to Haiku/Sonnet/Opus, or announce that a key would resolve it |
+
+## Quickstart
+
+```bash
+pip install terbium-parse
+```
+
+```python
+import terbium
+
+doc = terbium.parse("Furniture Catalogue.pdf")     # algorithmic only, no key needed
+print(doc.stats)                                    # Stats(total=725, confident=712, ambiguous=13)
+
+for r in doc.records:
+    print(r.sku, r.fields)
+
+# opt into AI only for the pages the engine could not resolve
+doc = terbium.parse("Furniture Catalogue.pdf",
+                    schema="furniture",
+                    ai=terbium.AI(anthropic_key="sk-..."))
+```
+
+Run it from the shell:
+
+```bash
+terbium "Furniture Catalogue.pdf" --schema furniture
+terbium report.xlsx --json out.json
+```
+
+## What it parses
+
+| Format | Engine | How |
+|---|---|---|
+| **PDF** | word-level geometry | rebuild columns/rows/matrices from the position of every word |
+| **PPTX** | python-pptx | native slides, tables and images, straight from the deck structure |
+| **XLSX** | openpyxl | cells, merged ranges propagated, wide/long layouts |
+| **CSV** | stdlib | delimiter, encoding and type inference |
+
+PDF gets the full geometry engine because a PDF throws its structure away. PPTX,
+XLSX and CSV already carry native structure, so terbium leans on it and parses
+them cleanly and cheaply.
+
+## Confidence and escalation
+
+terbium never pretends a shaky parse is solid. When it cannot be sure and no key
+is set, it prints exactly what it could not do:
+
+```
+terbium: 712/725 records parsed confidently.
+3 table(s) on page(s) 15, 26, 30 are ambiguous (no product title found above
+the table; sparse matrix: 5/9 cells filled; 2 row(s) do not line up).
+-> set ANTHROPIC_API_KEY or pass ai=terbium.AI(...)   recommended tier: Sonnet
+```
+
+Every record exposes its own `confidence` and the `reasons` behind it, so you can
+filter, sort, or route on it yourself.
+
+## The AI lane
+
+The AI lane is opt-in and only ever sees the hard pages.
+
+- **Routing.** Difficulty scales the tier: trivial to Haiku, moderate to Sonnet,
+  hard or low-confidence to Opus. Pin a tier with `terbium.AI(force_tier="opus")`.
+- **Arrange.** A hard table is handed to the routed model with the page's raw
+  text and, for PDFs, a rendered image, and rebuilt into a clean matrix.
+- **Vision.** Material icons (FSC, oiled, varnished) and finish swatches live only
+  in the pixels; `terbium.read_images(path, page, ai)` reads them with a vision
+  model. Note: Nano Banana (Gemini image) is for generation, not reading, so it is
+  not on the parse path.
+
+Keys come from `terbium.AI(...)` or the `ANTHROPIC_API_KEY` / `GEMINI_API_KEY`
+environment variables.
+
+## Schemas
+
+A schema turns reconstructed tables into typed records. Ships with two:
+
+- `generic` (default): one record per row for grids, one per cell for matrices.
+- `furniture`: product, size, finish, and metric + imperial dimensions per SKU.
+
+Add your own by subclassing `terbium.schema.Schema` and registering it.
+
+## Install from source
+
+```bash
+git clone https://github.com/anishfyi/terbium.git
+cd terbium
+pip install -e .
+```
+
+## License
+
+MIT. Built by [anishfyi](https://github.com/anishfyi).
+
+<div align="center"><sub>terbium · Tb · 65</sub></div>

terbium_parse-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "terbium-parse"
+version = "0.1.0"
+description = "A god-level algorithmic multi-file parser (PDF/PPTX/XLSX/CSV) that scores its own confidence and only reaches for AI when it is genuinely stuck."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "anishfyi" }]
+keywords = ["parser", "pdf", "pptx", "xlsx", "csv", "extraction", "document", "ai", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: General",
+]
+dependencies = [
+    "PyMuPDF>=1.24",
+    "python-pptx>=0.6.23",
+    "openpyxl>=3.1",
+    "pillow>=10.0",
+]
+
+[project.optional-dependencies]
+# The AI lane is opt-in. terbium runs fully without either of these.
+anthropic = ["anthropic>=0.34"]
+gemini = ["google-generativeai>=0.7"]
+ai = ["anthropic>=0.34", "google-generativeai>=0.7"]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://anishfyi.github.io/terbium"
+Repository = "https://github.com/anishfyi/terbium"
+
+[project.scripts]
+terbium = "terbium.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+terbium = ["py.typed"]

terbium_parse-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

terbium_parse-0.1.0/src/terbium/__init__.py

@@ -0,0 +1,31 @@
+"""terbium - a god-level algorithmic multi-file parser that scores its own
+confidence and only reaches for AI when it is genuinely stuck.
+
+    import terbium
+    doc = terbium.parse("catalogue.pdf")
+    print(doc.stats)
+    for r in doc.records:
+        print(r.sku, r.fields)
+"""
+from __future__ import annotations
+
+from .api import parse, supported_extensions, DEFAULT_THRESHOLD
+from .harness import AI
+from .harness.vision import read_page as read_images
+from .model.document import ParsedDocument, Stats
+from .model.record import Record
+from .model.table import ExtractedTable
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "parse",
+    "AI",
+    "read_images",
+    "supported_extensions",
+    "ParsedDocument",
+    "Record",
+    "ExtractedTable",
+    "Stats",
+    "__version__",
+]

terbium_parse-0.1.0/src/terbium/api.py

@@ -0,0 +1,106 @@
+"""``terbium.parse`` - the one function most users call.
+
+Flow: adapt -> assemble tables (native, or reconstructed from PDF geometry) ->
+score confidence -> (optionally) send only the hard tables to AI -> build typed
+records -> if anything is still shaky and no key was given, attach and announce
+an escalation message.
+"""
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+from .documents import get_adapter, supported_extensions
+from .layout import confidence as _confidence
+from .layout import dehead, grid
+from .layout.columns import split_columns
+from .layout.lines import cluster_lines
+from .model.document import ParsedDocument, Stats
+from .model.elements import Page
+from .model.table import ExtractedTable
+from .schema import get_schema
+from .harness import arrange_tables, build_message, resolve
+
+DEFAULT_THRESHOLD = 0.72
+
+
+def _assemble_tables(pages: List[Page]) -> List[ExtractedTable]:
+    tables: List[ExtractedTable] = []
+    pdf_pages = [p for p in pages if p.source_kind == "pdf" and p.words]
+    stripper = dehead.build_stripper(pdf_pages) if pdf_pages else None
+    for p in pages:
+        if p.native_tables:
+            tables.extend(p.native_tables)
+        elif p.source_kind == "pdf" and p.words:
+            for word_group in split_columns(p):
+                lines = cluster_lines(word_group)
+                if stripper:
+                    lines = [ln for ln in lines if not stripper(ln, p)]
+                tables.extend(grid.extract_tables(lines, p))
+    return tables
+
+
+def parse(
+    path: str,
+    schema=None,
+    ai=None,
+    threshold: float = DEFAULT_THRESHOLD,
+    announce: bool = True,
+) -> ParsedDocument:
+    """Parse a PDF/PPTX/XLSX/CSV file into structured, confidence-scored records.
+
+    ``schema``: "generic" (default) or "furniture", or a Schema instance.
+    ``ai``: a ``terbium.AI(...)``, ``True`` (use env keys), or ``None`` (off).
+    ``threshold``: confidence below which a record is "ambiguous".
+    ``announce``: print the escalation message to stderr when AI could help but
+    no key is set. This is terbium telling you it is stuck.
+    """
+    adapter = get_adapter(path)
+    pages = adapter.parse(path)
+    source_kind = pages[0].source_kind if pages else "unknown"
+
+    tables = _assemble_tables(pages)
+    for t in tables:
+        _confidence.score_table(t)
+
+    ai_cfg = resolve(ai)
+    hard = [t for t in tables if t.confidence < threshold]
+    used_ai = False
+    if hard and ai_cfg is not None:
+        fixed = arrange_tables(path, pages, hard, ai_cfg)
+        used_ai = fixed > 0
+        hard = [t for t in tables if t.confidence < threshold]
+
+    schema_obj = get_schema(schema)
+    records = []
+    for t in tables:
+        recs = schema_obj.build_records([t])
+        if t.origin == "ai":
+            for r in recs:
+                r.origin = "ai"
+        records.extend(recs)
+
+    stats = Stats(
+        total=len(records),
+        confident=sum(1 for r in records if r.confidence >= threshold),
+        ambiguous=sum(1 for r in records if r.confidence < threshold),
+        threshold=threshold,
+    )
+    doc = ParsedDocument(
+        path=path,
+        source_kind=source_kind,
+        pages=pages,
+        records=records,
+        stats=stats,
+        used_ai=used_ai,
+    )
+
+    if hard:
+        doc.escalation = build_message(records, hard, threshold)
+        if announce and ai_cfg is None:
+            print(doc.escalation, file=sys.stderr)
+
+    return doc
+
+
+__all__ = ["parse", "supported_extensions", "DEFAULT_THRESHOLD"]

terbium_parse-0.1.0/src/terbium/cli.py

@@ -0,0 +1,53 @@
+"""`terbium <file>` - parse from the command line."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .api import parse, supported_extensions
+from .harness import AI
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="terbium",
+        description="Algorithmic multi-file parser (PDF/PPTX/XLSX/CSV) that knows when it is stuck.",
+    )
+    ap.add_argument("file", help="path to a " + "/".join(supported_extensions()) + " file")
+    ap.add_argument("--schema", default="generic", help="generic (default) or furniture")
+    ap.add_argument("--json", metavar="OUT", help="write records as JSON to this path (or - for stdout)")
+    ap.add_argument("--ai", action="store_true", help="enable the AI lane using env keys")
+    ap.add_argument("--tier", choices=["haiku", "sonnet", "opus"], help="pin the AI model tier")
+    ap.add_argument("--limit", type=int, default=12, help="how many records to preview")
+    ap.add_argument("--version", action="version", version=f"terbium {__version__}")
+    args = ap.parse_args(argv)
+
+    ai = AI(force_tier=args.tier) if args.ai else None
+    doc = parse(args.file, schema=args.schema, ai=ai)
+
+    if args.json:
+        payload = doc.to_json()
+        if args.json == "-":
+            print(payload)
+        else:
+            with open(args.json, "w", encoding="utf-8") as f:
+                f.write(payload)
+            print(f"wrote {len(doc.records)} records -> {args.json}", file=sys.stderr)
+        return 0
+
+    print(f"terbium {__version__}  ·  {doc.source_kind}  ·  {len(doc.pages)} pages")
+    print(f"records: {doc.stats.total}  (confident {doc.stats.confident}, ambiguous {doc.stats.ambiguous})")
+    if doc.used_ai:
+        print("AI lane: engaged on hard tables")
+    print("-" * 60)
+    for r in doc.records[: args.limit]:
+        flag = "" if r.confidence >= doc.stats.threshold else "  [ambiguous]"
+        print(f"{r.sku or '-':>8}  {r.confidence:.2f}  {r.fields}{flag}")
+    if doc.stats.total > args.limit:
+        print(f"... and {doc.stats.total - args.limit} more")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

terbium_parse-0.1.0/src/terbium/documents/__init__.py

@@ -0,0 +1,8 @@
+"""Importing this package registers every adapter as a side effect."""
+from .base import DocumentAdapter, get_adapter, register, supported_extensions
+from . import pdf as _pdf
+from . import pptx_adapter as _pptx
+from . import xlsx_adapter as _xlsx
+from . import csv_adapter as _csv
+
+__all__ = ["DocumentAdapter", "get_adapter", "register", "supported_extensions"]

terbium_parse-0.1.0/src/terbium/documents/base.py

@@ -0,0 +1,46 @@
+"""Adapter interface + registry. One adapter per file format.
+
+Adapters do exactly one job: turn bytes on disk into normalized ``Page`` objects
+(words with positions, images, and - when the format exposes it natively - ready
+made tables). Everything smart happens after, on that uniform representation.
+"""
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from typing import List
+
+from ..model.elements import Page
+
+
+class DocumentAdapter(ABC):
+    extensions: tuple = ()
+
+    @abstractmethod
+    def parse(self, path: str) -> List[Page]:
+        ...
+
+
+_REGISTRY: dict = {}
+
+
+def register(adapter_cls):
+    """Class decorator: instantiate the adapter and index it by extension."""
+    instance = adapter_cls()
+    for ext in adapter_cls.extensions:
+        _REGISTRY[ext.lower()] = instance
+    return adapter_cls
+
+
+def get_adapter(path: str) -> DocumentAdapter:
+    ext = os.path.splitext(path)[1].lower().lstrip(".")
+    if ext not in _REGISTRY:
+        raise ValueError(
+            f"terbium has no adapter for '.{ext}'. Supported: "
+            + ", ".join(sorted(_REGISTRY)) + "."
+        )
+    return _REGISTRY[ext]
+
+
+def supported_extensions() -> List[str]:
+    return sorted(_REGISTRY)