rasgapdf 0.1.0__py3-none-any.whl

rasgapdf/__init__.py

@@ -0,0 +1,156 @@
+import os
+import sys
+import json
+import ctypes
+from typing import Dict, Any, List, Optional
+
+def _find_library() -> str:
+    lib_name = "librasgapdf.so" if sys.platform != "win32" else "rasgapdf.dll"
+    if sys.platform == "darwin":
+        lib_name = "librasgapdf.dylib"
+
+    search_paths = [
+        # Relative to installed package
+        os.path.join(os.path.dirname(__file__), lib_name),
+        os.path.join(os.path.dirname(__file__), "..", "..", "..", "target", "release", lib_name),
+        os.path.join(os.path.dirname(__file__), "..", "..", "target", "release", lib_name),
+        os.path.join(os.path.expanduser("~"), "rasgapdf", "target", "release", lib_name),
+        "/usr/local/lib/" + lib_name,
+        "/usr/lib/" + lib_name,
+    ]
+
+    for p in search_paths:
+        abs_p = os.path.abspath(p)
+        if os.path.exists(abs_p):
+            return abs_p
+
+    # Fallback to system loader
+    return lib_name
+
+_lib_path = _find_library()
+try:
+    _lib = ctypes.CDLL(_lib_path)
+except Exception as e:
+    _lib = None
+
+if _lib:
+    _lib.rasgapdf_parse_raw.argtypes = [ctypes.c_char_p]
+    _lib.rasgapdf_parse_raw.restype = ctypes.c_void_p
+
+    _lib.rasgapdf_parse_file.argtypes = [ctypes.c_char_p]
+    _lib.rasgapdf_parse_file.restype = ctypes.c_void_p
+
+    _lib.rasgapdf_parse_file_options.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+    _lib.rasgapdf_parse_file_options.restype = ctypes.c_void_p
+
+    _lib.rasgapdf_free_string.argtypes = [ctypes.c_void_p]
+    _lib.rasgapdf_free_string.restype = None
+
+    _lib.rasgapdf_version.argtypes = []
+    _lib.rasgapdf_version.restype = ctypes.c_char_p
+
+def version() -> str:
+    if not _lib:
+        return "0.1.0 (unlinked)"
+    return _lib.rasgapdf_version().decode("utf-8")
+
+def parse_raw(file_path: str) -> Dict[str, Any]:
+    """
+    ⚡ Modo 1 (Bruto): Retorna exclusivamente a lista plana de coordenadas X/Y
+    sem overhead de blocos hierárquicos ou detecção de tabelas.
+
+    Args:
+        file_path: Caminho do arquivo PDF.
+
+    Returns:
+        dict: {
+            "file_name": str,
+            "total_pages": int,
+            "total_spans": int,
+            "parse_time_ms": float,
+            "spans": [
+                {
+                    "page": int,
+                    "x0": float,
+                    "y0": float,
+                    "x1": float,
+                    "y1": float,
+                    "font_size": float,
+                    "font_name": str,
+                    "text": str
+                }, ...
+            ]
+        }
+    """
+    if not _lib:
+        raise RuntimeError(f"RasgaPDF native library ({_lib_path}) not loaded.")
+
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"PDF file not found: {file_path}")
+
+    path_bytes = os.path.abspath(file_path).encode("utf-8")
+    res_ptr = _lib.rasgapdf_parse_raw(path_bytes)
+    if not res_ptr:
+        raise RuntimeError("Null pointer returned from native rasgapdf library.")
+
+    try:
+        raw_json = ctypes.string_at(res_ptr).decode("utf-8")
+        parsed = json.loads(raw_json)
+        if isinstance(parsed, dict) and parsed.get("error"):
+            raise RuntimeError(f"RasgaPDF Error: {parsed.get('message')}")
+        return parsed
+    finally:
+        _lib.rasgapdf_free_string(res_ptr)
+
+def parse_pdf(
+    file_path: str,
+    detect_tables: bool = True,
+    min_table_cols: int = 3,
+    col_tolerance: float = 16.0,
+    row_tolerance: float = 6.0,
+) -> Dict[str, Any]:
+    """
+    🎯 Modo 2 (Estruturado): Processa o PDF e retorna o layout espacial hierárquico
+    com blocos de texto, linhas, spans e tabelas detectadas.
+    
+    Args:
+        file_path: Caminho do arquivo PDF.
+        detect_tables: Se deve detectar matrizes de tabelas automaticamente.
+        min_table_cols: Quantidade mínima de colunas para agrupar em tabela.
+        col_tolerance: Tolerância horizontal de alinhamento em pontos.
+        row_tolerance: Tolerância vertical de linha em pontos.
+
+    Returns:
+        dict: SpatialDocument contendo páginas, blocos, linhas e tabelas.
+    """
+    if not _lib:
+        raise RuntimeError(f"RasgaPDF native library ({_lib_path}) not loaded.")
+
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"PDF file not found: {file_path}")
+
+    opts = {
+        "mode": "structured",
+        "detect_tables": detect_tables,
+        "min_table_columns": min_table_cols,
+        "column_tolerance": col_tolerance,
+        "row_tolerance": row_tolerance,
+    }
+
+    path_bytes = os.path.abspath(file_path).encode("utf-8")
+    opts_bytes = json.dumps(opts).encode("utf-8")
+
+    res_ptr = _lib.rasgapdf_parse_file_options(path_bytes, opts_bytes)
+    if not res_ptr:
+        raise RuntimeError("Null pointer returned from native rasgapdf library.")
+
+    try:
+        raw_json = ctypes.string_at(res_ptr).decode("utf-8")
+        parsed = json.loads(raw_json)
+        if isinstance(parsed, dict) and parsed.get("error"):
+            raise RuntimeError(f"RasgaPDF Error: {parsed.get('message')}")
+        return parsed
+    finally:
+        _lib.rasgapdf_free_string(res_ptr)
+
+__all__ = ["parse_raw", "parse_pdf", "version"]

rasgapdf-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: rasgapdf
+Version: 0.1.0
+Summary: Ultra-fast 2D spatial PDF parser powered by Rust
+Author: Messias Martins
+Project-URL: Homepage, https://github.com/messiasmartins/rasgapdf
+Project-URL: Bug Tracker, https://github.com/messiasmartins/rasgapdf/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ⚡ RasgaPDF
+
+<div align="center">
+
+**The Blazing-Fast 2D Spatial PDF Parser powered by Pure Rust.**  
+*Extract exact physical coordinates (Raw X/Y) or structured blocks & tables at native hardware speeds.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Rust](https://img.shields.io/badge/Rust-2021%2B-orange?logo=rust)](Cargo.toml)
+[![Python](https://img.shields.io/badge/Python-3.8%2B-yellow?logo=python)](bindings/python)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?logo=node.js)](bindings/nodejs)
+[![Go](https://img.shields.io/badge/Go-1.20%2B-cyan?logo=go)](bindings/go)
+[![.NET](https://img.shields.io/badge/.NET-8.0%2B-purple?logo=dotnet)](bindings/csharp)
+[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-martinsmessias%2Frasgapdf-blue)](https://huggingface.co/martinsmessias/rasgapdf)
+
+[**Live Gradio Demo**](#-interactive-gradio-demo) • [**Quickstart**](#-quickstart) • [**Two Modes**](#-two-parsing-modes) • [**Architecture**](docs/ARCHITECTURE.md) • [**Spatial Schema**](docs/SCHEMA.md) • [**Contributing**](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## 🎯 The Philosophy: Pure Spatial Parsing
+
+Most PDF libraries make fragile guesses: they convert multi-column documents into flat, corrupted text streams, mangle tables, and strip away spatial geometry. 
+
+**RasgaPDF does one thing with uncompromising precision:**  
+It returns the **exact 2D physical spatial geometry** of the PDF.
+
+- **Bounding Boxes Everywhere:** Every character, word span, line, block, and table has exact coordinates `[x0, y0, x1, y1]`.
+- **Zero Lossy Guesswork:** No broken heuristics pretending to be Markdown. Your downstream LLMs, RAG pipelines, or OCR validators receive the true physical layout.
+- **Microsecond Rayon Parallelism:** Multi-threaded page processing in pure Rust utilizing AVX2/AVX-512 SIMD.
+- **Polyglot First:** Native C-ABI FFI bindings for **Python**, **Node.js**, **Go**, and **C# (.NET)**.
+
+---
+
+## ⚡ Two Parsing Modes
+
+RasgaPDF offers two distinct modes for different engineering needs:
+
+### ⚡ Modo 1: Coordenadas Brutas (Raw X/Y Puro)
+O retorno mais direto, bruto e rápido possível. Retorna exclusivamente a lista plana de coordenadas físicas de cada elemento desenhado na página, sem criar hierarquias de blocos ou overhead de tabelas:
+- **Latência:** ~3 a 8 ms por página
+- **Saídas suportadas:** JSON plano, Text formatado, TSV ou CSV
+- **Uso ideal:** RAG espacial, visualizadores 2D, indexação vetorial, pipelines Unix com `awk`/`grep`.
+
+```
+[Pág. 1] (X0:  50.00, Y0:  67.00, X1: 244.00, Y1:  83.00) [12.0pt] A Revolução da Inteligência Artificial
+[Pág. 1] (X0:  50.00, Y0: 103.00, X1: 478.00, Y1: 119.00) [12.0pt] A Inteligência Artificial (IA) tem transformado...
+```
+
+### 🎯 Modo 2: Estruturado Hierárquico
+Processa a geometria e agrupa elementos em parágrafos visuais (`blocks`), linhas (`lines`), spans de fonte e detecta matrizes de tabelas automaticamente via projeção horizontal de colunas:
+- **Latência:** ~8 a 15 ms por página
+- **Saída:** Árvore hierárquica `SpatialDocument` -> `pages` -> `text_blocks` -> `lines` -> `tables`.
+
+---
+
+## ⚡ Performance Benchmark
+
+Measured on Intel Core i7-1365U (10 Cores / 12 Threads, AVX2):
+
+| Library / Tool | Language | Single Page | 50 Pages | Memory Footprint | Output Type |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **⚡ RasgaPDF (Raw X/Y)** | **Rust (Native)** | **7.7 ms** | **95 ms** | **~14 MB** | **Flat Raw Coordinates** |
+| **🚀 RasgaPDF (Structured)**| **Rust (Native)** | **8.5 ms** | **142 ms** | **~18 MB** | **Spatial Blocks & Tables** |
+| PyMuPDF (`fitz`) | C / Python | 28.0 ms | 620 ms | ~45 MB | Text / Pixmap |
+| `pdfplumber` | Python | 410.0 ms | 9,800 ms | ~140 MB | Python dicts |
+| `pypdf` | Python | 95.0 ms | 2,100 ms | ~85 MB | Flat text string |
+| Apache Tika | Java | 650.0 ms | 12,400 ms | ~320 MB | XHTML |
+
+---
+
+## 💻 Standalone CLI Tool
+
+```bash
+cargo build --release
+./target/release/rasgapdf --help
+
+# ⚡ MODO 1: Coordenadas Brutas (Raw X/Y)
+./target/release/rasgapdf sample.pdf --raw
+./target/release/rasgapdf sample.pdf --raw --format text
+./target/release/rasgapdf sample.pdf --raw --format csv
+./target/release/rasgapdf sample.pdf --raw --format tsv
+
+# 🎯 MODO 2: Estruturado (Hierárquico com Blocos e Tabelas)
+./target/release/rasgapdf sample.pdf --pretty
+./target/release/rasgapdf sample.pdf -o output.json
+```
+
+---
+
+## 🚀 Polyglot Quickstart
+
+### 🐍 Python
+```python
+import rasgapdf
+
+# ⚡ Modo 1: Coordenadas Brutas (Raw X/Y)
+raw = rasgapdf.parse_raw("document.pdf")
+print(f"Extraídos {raw['total_spans']} spans em {raw['parse_time_ms']:.2f} ms")
+for s in raw["spans"]:
+    print(f"Pág {s['page']} | ({s['x0']}, {s['y0']}) -> {s['text']}")
+
+# 🎯 Modo 2: Estruturado (Hierárquico)
+doc = rasgapdf.parse_pdf("document.pdf", detect_tables=True)
+for page in doc["pages"]:
+    for table in page["tables"]:
+        print("Tabela detectada:", table["rows"])
+```
+
+### 🟢 Node.js
+```javascript
+const rasgapdf = require('rasgapdf');
+
+// ⚡ Modo 1: Coordenadas Brutas
+const raw = rasgapdf.parseRaw('document.pdf');
+console.log(`Raw: ${raw.total_spans} spans em ${raw.parse_time_ms} ms`);
+
+// 🎯 Modo 2: Estruturado
+const doc = rasgapdf.parsePdf('document.pdf');
+console.log(`Blocos de texto: ${doc.pages[0].text_blocks.length}`);
+```
+
+### 🔵 Go
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/messiasmartins/rasgapdf/bindings/go"
+)
+
+func main() {
+    // ⚡ Modo 1: Coordenadas Brutas
+    raw, _ := rasgapdf.ParseRaw("document.pdf")
+    fmt.Printf("Raw: %d spans em %.2f ms\n", raw.TotalSpans, raw.ParseTimeMs)
+
+    // 🎯 Modo 2: Estruturado
+    opts := rasgapdf.DefaultOptions()
+    doc, _ := rasgapdf.ParseFile("document.pdf", &opts)
+    fmt.Printf("Estruturado: %d páginas\n", doc.TotalPages)
+}
+```
+
+### 🟣 C# / .NET 8
+```csharp
+using RasgaPdf;
+
+// ⚡ Modo 1: Coordenadas Brutas
+var raw = SpatialPdf.ParseRaw("document.pdf");
+Console.WriteLine($"Raw: {raw.TotalSpans} spans em {raw.ParseTimeMs} ms");
+
+// 🎯 Modo 2: Estruturado
+var doc = SpatialPdf.Parse("document.pdf");
+Console.WriteLine($"Estruturado: {doc.TotalPages} páginas");
+```
+
+---
+
+## 🎨 Interactive Gradio Demo
+
+We provide an interactive **visual spatial explorer** built with Gradio:
+
+```bash
+cd demo_gradio
+pip install -r requirements.txt
+python app.py
+```
+Acesse `http://localhost:7860` para:
+- Inspecionar a **tabela interativa de Coordenadas Físicas (Raw X/Y)**.
+- Visualizar os **bounding boxes translúcidos** sobrepostos à página do PDF.
+- Analisar **tabelas detectadas** renderizadas em DataFrames.
+- Exportar JSONs brutos ou estruturados.
+
+---
+
+## 🤝 Contributing & Community
+
+Contributions are what make the open-source community thrive!
+- Read our [Contributing Guide](CONTRIBUTING.md) to get started.
+- Adhere to our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## 📄 License
+
+RasgaPDF is licensed under the [MIT License](LICENSE).  
+Copyright (c) 2026 Messias Martins.

rasgapdf-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+rasgapdf/__init__.py,sha256=1PCpr7JigOnNxYBR0d6L98_LM_whJQ358F56uy4ItJM,5132
+rasgapdf/librasgapdf.so,sha256=pKotSfi5thIU6kl3glawsJXvCuknsWueJtz-7B-8wbM,8745688
+rasgapdf-0.1.0.dist-info/METADATA,sha256=ZBYSPut-3clnJJ7BY8clLUovFlaEhBy28inak9x7K7k,7587
+rasgapdf-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rasgapdf-0.1.0.dist-info/top_level.txt,sha256=3DOdLinXRup1qeRyF1_qxtGgDWzf_LUMAw51ycM8qts,9
+rasgapdf-0.1.0.dist-info/RECORD,,

rasgapdf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rasgapdf-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rasgapdf