acquivela 0.2.0__tar.gz

acquivela-0.2.0/LICENSE

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

acquivela-0.2.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: acquivela
+Version: 0.2.0
+Summary: AcquiVela — Document Acquisition Framework
+License: MIT
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: docling
+Requires-Dist: docling>=2.119.0; extra == "docling"
+Provides-Extra: mineru
+Requires-Dist: mineru>=3.4.4; extra == "mineru"
+Provides-Extra: all
+Requires-Dist: acquivela[docling,mineru]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: importlinter>=0.16; extra == "dev"
+Requires-Dist: acquivela[all]; extra == "dev"
+Dynamic: license-file
+
+# AcquiVela
+
+Document Acquisition Framework — Frozen Architecture v0.1
+
+> **Note:** AcquiVela v0.1.0 is a pre-1.0 release. Some internal orchestration APIs (`Pipeline`, `Registry`) are exposed for use but are **not frozen public contracts** and may change. See [Governance](#governance) below.
+
+## What is AcquiVela?
+
+AcquiVela is a capability-oriented document acquisition framework that orchestrates specialized acquisition engines (Docling, MinerU) through frozen public contracts and a versioned Canonical Document Model (CDM).
+
+**Scope:** Document acquisition only (PDF, DOCX, scanned images, and more).
+**Non-goals:** Embeddings, retrieval, vector DB, chunking, LLM reasoning, knowledge extraction.
+
+## Governed Public Contracts
+
+The following are frozen per ADR-0001 through ADR-0006 and carry semantic-versioning compatibility guarantees:
+
+| Contract | Module | Description |
+|----------|--------|-------------|
+| `AcquireRequest` | `models.py` | Input request (file path, engine hint, capability) |
+| `AcquireResult` | `public_result.py` | Public result wrapper (status, canonical document, error) |
+| `CanonicalDocument` | `cdm.py` | CDM root — pages + title |
+| `Page` | `cdm.py` | A document page — text blocks + page number |
+| `TextBlock` | `cdm.py` | A text block — text + type classification |
+| `Plugin` | `plugin.py` | Plugin SPI (ABC) — `metadata()`, `acquire()`, `capabilities()` |
+| `PluginHealth` | `plugin.py` | Plugin health status |
+| `Capabilities` | `capabilities.py` | Canonical capability vocabulary |
+| `Diagnostics` | `public_result.py` | Per-execution diagnostic metadata |
+
+## Internal Orchestration Infrastructure
+
+The following components are **internal** and not frozen public contracts:
+
+| Component | Module | Status |
+|-----------|--------|--------|
+| `Pipeline` | `pipeline.py` | Internal — may change before stable API decision |
+| `Registry` | `registry.py` | Internal — may change before stable API decision |
+| `PluginResult` | `result.py` | Internal SPI — not exported at package root |
+| `ExecutionContext` | `execution_context.py` | Internal |
+
+Plugins may NOT import `Pipeline`, `Registry`, or `public_result` — enforced via import-linter (ADR-0004 §3.2, ADR-0006 §3.3).
+
+## Installation
+
+```bash
+# Base installation (no acquisition engines)
+pip install acquivela
+
+# With Docling support (PDF, DOCX, images, and more)
+pip install acquivela[docling]
+
+# With MinerU support (high-accuracy PDF)
+pip install acquivela[mineru]
+
+# With both engines
+pip install acquivela[docling,mineru]
+```
+
+### System Dependencies
+
+Some formats require additional system-level tools:
+
+- **Legacy Office formats** (`.doc`, `.ppt`, `.xls`): Requires LibreOffice installed and on PATH
+- **OpenDocument formats** (`.odt`, `.ods`, `.odp`): Requires `odfdo` Python package (included with `docling` extras)
+
+## Quick Start
+```python
+# Recommended: use the M15 stable facade
+from acquivela import AcquireRequest, acquire
+
+result = acquire(
+    AcquireRequest(file_path="document.pdf")
+)
+
+if result.status == "success":
+    doc = result.canonical_document
+    for page in doc.pages:
+        for block in page.text_blocks:
+            print(block.text)
+```
+
+### Using the M15 facade (recommended normal path)
+```python
+from acquivela import AcquireRequest, acquire
+
+result = acquire(
+    AcquireRequest(file_path="document.pdf")
+)
+
+if result.status == "success":
+    doc = result.canonical_document
+    for page in doc.pages:
+        for block in page.text_blocks:
+            print(block.text)
+```
+
+### Using Engine Hints
+
+```python
+# Force a specific engine
+request = AcquireRequest(
+    file_path="document.pdf",
+    engine_hint="docling"
+)
+```
+
+### Using Capability Filtering
+
+```python
+from acquivela.capabilities import Capabilities
+
+# Require text extraction capability
+request = AcquireRequest(
+    file_path="document.pdf",
+    required_capability=Capabilities.DOCUMENT_TEXT
+)
+```
+
+## Known Limitations
+
+### MinerU
+
+MinerU has a known upstream issue (`PPDocLayoutV2Config` missing `reading_order_config`) that causes acquisition failures. AcquiVela correctly contains this failure — the pipeline returns `status="failure"` without exceptions escaping. The MinerU plugin reports `healthy` at the health-check level because it is importable, but actual acquisition will fail until the upstream issue is resolved.
+
+### Legacy Office Formats
+
+`.doc`, `.ppt`, and `.xls` files require LibreOffice to be installed and available on PATH. Without LibreOffice, Docling cannot convert these legacy formats to modern equivalents.
+
+### OpenDocument Formats
+
+`.odt`, `.ods`, and `.odp` files require the `odfdo` Python package. This is included when installing with `pip install acquivela[docling]`.
+
+### XML and JSON
+
+Generic XML files are not supported. Docling supports specific XML dialects only (USPTO, JATS, XBRL, DOCLANG). Similarly, only `json_docling` format is supported for JSON input.
+
+### CDM v0.2 Exclusions
+
+The Canonical Document Model (CDM) v0.2 captures text content only. Tables, images, equations, bounding boxes, and rich provenance are intentionally excluded from the current model.
+
+## Architecture
+
+### Package Structure
+
+```
+acquivela/
+├── __init__.py          # Public exports + internal orchestration (see Governance)
+├── cdm.py               # CanonicalDocument, Page, TextBlock (PUBLIC/STABLE)
+├── models.py            # AcquireRequest (PUBLIC/STABLE)
+├── plugin.py            # Plugin SPI, PluginHealth (PUBLIC/STABLE)
+├── result.py            # PluginResult (INTERNAL - not exported at root)
+├── public_result.py     # AcquireResult, Diagnostics (PUBLIC/STABLE)
+├── capabilities.py      # Capabilities (PUBLIC/STABLE)
+├── registry.py          # Registry (INTERNAL - may change)
+├── pipeline.py          # Pipeline (INTERNAL - may change)
+├── execution_context.py # ExecutionContext (INTERNAL)
+└── plugins/             # Plugin implementations (one class per module)
+```
+
+### Status
+
+- Charter: FROZEN
+- ADR-0001 Project Boundaries: FROZEN
+- ADR-0002 Execution Model: FROZEN
+- ADR-0003 Core Data Contracts: FROZEN
+- ADR-0004 Plugin & Execution Strategy: FROZEN
+- ADR-0005 Observability & Diagnostics: FROZEN
+- ADR-0006 Registry & Plugin Discovery: FROZEN
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e .[dev]
+
+# Run contract tests
+pytest tests/test_contracts.py
+
+# Run import-linter validation
+pytest tests/test_import_linter.py
+
+# Or run import-linter directly
+importlinter lint
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

acquivela-0.2.0/README.md

@@ -0,0 +1,188 @@
+# AcquiVela
+
+Document Acquisition Framework — Frozen Architecture v0.1
+
+> **Note:** AcquiVela v0.1.0 is a pre-1.0 release. Some internal orchestration APIs (`Pipeline`, `Registry`) are exposed for use but are **not frozen public contracts** and may change. See [Governance](#governance) below.
+
+## What is AcquiVela?
+
+AcquiVela is a capability-oriented document acquisition framework that orchestrates specialized acquisition engines (Docling, MinerU) through frozen public contracts and a versioned Canonical Document Model (CDM).
+
+**Scope:** Document acquisition only (PDF, DOCX, scanned images, and more).
+**Non-goals:** Embeddings, retrieval, vector DB, chunking, LLM reasoning, knowledge extraction.
+
+## Governed Public Contracts
+
+The following are frozen per ADR-0001 through ADR-0006 and carry semantic-versioning compatibility guarantees:
+
+| Contract | Module | Description |
+|----------|--------|-------------|
+| `AcquireRequest` | `models.py` | Input request (file path, engine hint, capability) |
+| `AcquireResult` | `public_result.py` | Public result wrapper (status, canonical document, error) |
+| `CanonicalDocument` | `cdm.py` | CDM root — pages + title |
+| `Page` | `cdm.py` | A document page — text blocks + page number |
+| `TextBlock` | `cdm.py` | A text block — text + type classification |
+| `Plugin` | `plugin.py` | Plugin SPI (ABC) — `metadata()`, `acquire()`, `capabilities()` |
+| `PluginHealth` | `plugin.py` | Plugin health status |
+| `Capabilities` | `capabilities.py` | Canonical capability vocabulary |
+| `Diagnostics` | `public_result.py` | Per-execution diagnostic metadata |
+
+## Internal Orchestration Infrastructure
+
+The following components are **internal** and not frozen public contracts:
+
+| Component | Module | Status |
+|-----------|--------|--------|
+| `Pipeline` | `pipeline.py` | Internal — may change before stable API decision |
+| `Registry` | `registry.py` | Internal — may change before stable API decision |
+| `PluginResult` | `result.py` | Internal SPI — not exported at package root |
+| `ExecutionContext` | `execution_context.py` | Internal |
+
+Plugins may NOT import `Pipeline`, `Registry`, or `public_result` — enforced via import-linter (ADR-0004 §3.2, ADR-0006 §3.3).
+
+## Installation
+
+```bash
+# Base installation (no acquisition engines)
+pip install acquivela
+
+# With Docling support (PDF, DOCX, images, and more)
+pip install acquivela[docling]
+
+# With MinerU support (high-accuracy PDF)
+pip install acquivela[mineru]
+
+# With both engines
+pip install acquivela[docling,mineru]
+```
+
+### System Dependencies
+
+Some formats require additional system-level tools:
+
+- **Legacy Office formats** (`.doc`, `.ppt`, `.xls`): Requires LibreOffice installed and on PATH
+- **OpenDocument formats** (`.odt`, `.ods`, `.odp`): Requires `odfdo` Python package (included with `docling` extras)
+
+## Quick Start
+```python
+# Recommended: use the M15 stable facade
+from acquivela import AcquireRequest, acquire
+
+result = acquire(
+    AcquireRequest(file_path="document.pdf")
+)
+
+if result.status == "success":
+    doc = result.canonical_document
+    for page in doc.pages:
+        for block in page.text_blocks:
+            print(block.text)
+```
+
+### Using the M15 facade (recommended normal path)
+```python
+from acquivela import AcquireRequest, acquire
+
+result = acquire(
+    AcquireRequest(file_path="document.pdf")
+)
+
+if result.status == "success":
+    doc = result.canonical_document
+    for page in doc.pages:
+        for block in page.text_blocks:
+            print(block.text)
+```
+
+### Using Engine Hints
+
+```python
+# Force a specific engine
+request = AcquireRequest(
+    file_path="document.pdf",
+    engine_hint="docling"
+)
+```
+
+### Using Capability Filtering
+
+```python
+from acquivela.capabilities import Capabilities
+
+# Require text extraction capability
+request = AcquireRequest(
+    file_path="document.pdf",
+    required_capability=Capabilities.DOCUMENT_TEXT
+)
+```
+
+## Known Limitations
+
+### MinerU
+
+MinerU has a known upstream issue (`PPDocLayoutV2Config` missing `reading_order_config`) that causes acquisition failures. AcquiVela correctly contains this failure — the pipeline returns `status="failure"` without exceptions escaping. The MinerU plugin reports `healthy` at the health-check level because it is importable, but actual acquisition will fail until the upstream issue is resolved.
+
+### Legacy Office Formats
+
+`.doc`, `.ppt`, and `.xls` files require LibreOffice to be installed and available on PATH. Without LibreOffice, Docling cannot convert these legacy formats to modern equivalents.
+
+### OpenDocument Formats
+
+`.odt`, `.ods`, and `.odp` files require the `odfdo` Python package. This is included when installing with `pip install acquivela[docling]`.
+
+### XML and JSON
+
+Generic XML files are not supported. Docling supports specific XML dialects only (USPTO, JATS, XBRL, DOCLANG). Similarly, only `json_docling` format is supported for JSON input.
+
+### CDM v0.2 Exclusions
+
+The Canonical Document Model (CDM) v0.2 captures text content only. Tables, images, equations, bounding boxes, and rich provenance are intentionally excluded from the current model.
+
+## Architecture
+
+### Package Structure
+
+```
+acquivela/
+├── __init__.py          # Public exports + internal orchestration (see Governance)
+├── cdm.py               # CanonicalDocument, Page, TextBlock (PUBLIC/STABLE)
+├── models.py            # AcquireRequest (PUBLIC/STABLE)
+├── plugin.py            # Plugin SPI, PluginHealth (PUBLIC/STABLE)
+├── result.py            # PluginResult (INTERNAL - not exported at root)
+├── public_result.py     # AcquireResult, Diagnostics (PUBLIC/STABLE)
+├── capabilities.py      # Capabilities (PUBLIC/STABLE)
+├── registry.py          # Registry (INTERNAL - may change)
+├── pipeline.py          # Pipeline (INTERNAL - may change)
+├── execution_context.py # ExecutionContext (INTERNAL)
+└── plugins/             # Plugin implementations (one class per module)
+```
+
+### Status
+
+- Charter: FROZEN
+- ADR-0001 Project Boundaries: FROZEN
+- ADR-0002 Execution Model: FROZEN
+- ADR-0003 Core Data Contracts: FROZEN
+- ADR-0004 Plugin & Execution Strategy: FROZEN
+- ADR-0005 Observability & Diagnostics: FROZEN
+- ADR-0006 Registry & Plugin Discovery: FROZEN
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e .[dev]
+
+# Run contract tests
+pytest tests/test_contracts.py
+
+# Run import-linter validation
+pytest tests/test_import_linter.py
+
+# Or run import-linter directly
+importlinter lint
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

acquivela-0.2.0/acquivela/__init__.py

@@ -0,0 +1,28 @@
+"""AcquiVela — Document Acquisition Framework.
+
+Public exports per frozen architecture (ADR-0001 through ADR-0006).
+"""
+
+from acquivela.cdm import CanonicalDocument, Page, TextBlock
+from acquivela.capabilities import Capabilities
+from acquivela.models import AcquireRequest
+from acquivela.plugin import Plugin
+from acquivela.public_result import AcquireResult, Diagnostics
+from acquivela.facade import acquire
+from acquivela.pipeline import Pipeline
+from acquivela.registry import Registry
+
+__version__ = "0.2.0"
+__all__ = [
+    "CanonicalDocument",
+    "Page",
+    "TextBlock",
+    "Capabilities",
+    "AcquireRequest",
+    "Plugin",
+    "AcquireResult",
+    "Diagnostics",
+    "Pipeline",
+    "Registry",
+    "acquire",
+]

acquivela-0.2.0/acquivela/capabilities.py

@@ -0,0 +1,19 @@
+"""Capability Vocabulary — Canonical capability constants for plugin selection.
+
+Per ADR-0014: Plugins declare capabilities; consumers request them via
+AcquireRequest.required_capability. Vocabulary is validated against this
+module's constants before plugin lookup.
+"""
+
+
+class Capabilities:
+    """Canonical capability constants.
+
+    Plugins declare capabilities as strings matching these constants.
+    Consumers request capabilities via AcquireRequest.required_capability.
+
+    Unknown plugin capabilities are tolerated at registration but inert
+    for selection — they cannot satisfy a required_capability request.
+    """
+
+    DOCUMENT_TEXT = "document.text"

acquivela-0.2.0/acquivela/cdm.py

@@ -0,0 +1,106 @@
+"""Canonical Document Model (CDM) v0.2 — Frozen per ADR-0003, extended per ADR-0011."""
+
+from __future__ import annotations
+
+from typing import List
+
+
+class CanonicalDocument:
+    """CanonicalDocument — frozen public contract.
+
+    Attributes:
+        cdm_version: Version string, e.g., "0.2"
+        pages: List of Page objects (at least one required)
+        title: Document title, or None if unavailable (ADR-0011)
+    """
+
+    def __init__(
+        self,
+        pages: List["Page"],
+        cdm_version: str = "0.2",
+        title: str | None = None,
+    ):
+        if not isinstance(pages, list):
+            raise TypeError(f"pages must be a list, got {type(pages).__name__}")
+        if len(pages) < 1:
+            raise ValueError("CanonicalDocument must contain at least one Page")
+        for i, page in enumerate(pages):
+            if not isinstance(page, Page):
+                raise TypeError(f"pages[{i}] must be a Page, got {type(page).__name__}")
+        self.cdm_version = cdm_version
+        self.pages = pages
+        self.title = title
+
+    def __repr__(self) -> str:
+        return (
+            f"CanonicalDocument(cdm_version={self.cdm_version!r}, "
+            f"pages={len(self.pages)}, title={self.title!r})"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, CanonicalDocument):
+            return NotImplemented
+        return (
+            self.cdm_version == other.cdm_version
+            and self.pages == other.pages
+            and self.title == other.title
+        )
+
+
+class Page:
+    """Page within CanonicalDocument — frozen public contract.
+
+    Attributes:
+        text_blocks: List of TextBlock objects (at least one required)
+        page_number: 1-based physical page number, or None if unknown (ADR-0011)
+    """
+
+    def __init__(
+        self,
+        text_blocks: List["TextBlock"],
+        page_number: int | None = None,
+    ):
+        if not isinstance(text_blocks, list):
+            raise TypeError(f"text_blocks must be a list, got {type(text_blocks).__name__}")
+        if len(text_blocks) < 1:
+            raise ValueError("Page must contain at least one TextBlock")
+        for i, block in enumerate(text_blocks):
+            if not isinstance(block, TextBlock):
+                raise TypeError(f"text_blocks[{i}] must be a TextBlock, got {type(block).__name__}")
+        self.text_blocks = text_blocks
+        self.page_number = page_number
+
+    def __repr__(self) -> str:
+        return f"Page(text_blocks={len(self.text_blocks)}, page_number={self.page_number!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Page):
+            return NotImplemented
+        return (
+            self.text_blocks == other.text_blocks
+            and self.page_number == other.page_number
+        )
+
+
+class TextBlock:
+    """TextBlock within Page — frozen public contract.
+
+    Attributes:
+        text: Text content string
+        text_type: Structural text classification, or None if unknown (ADR-0011).
+            Allowed values: "title", "paragraph", "list_item", "code", "caption"
+    """
+
+    def __init__(self, text: str, text_type: str | None = None):
+        if not isinstance(text, str):
+            raise TypeError(f"text must be a string, got {type(text).__name__}")
+        self.text = text
+        self.text_type = text_type
+
+    def __repr__(self) -> str:
+        return f"TextBlock(text={self.text!r}, text_type={self.text_type!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, TextBlock):
+            return NotImplemented
+        return self.text == other.text and self.text_type == other.text_type

acquivela-0.2.0/acquivela/execution_context.py

@@ -0,0 +1,27 @@
+"""ExecutionContext — Internal component per ADR-0005."""
+
+from __future__ import annotations
+
+
+class ExecutionContext:
+    """Internal execution context — NOT a frozen contract.
+
+    This is an internal mechanism for carrying execution metadata
+    that does not belong in the frozen public contracts.
+    It is internal to the pipeline and carries no compatibility guarantee.
+
+    Per ADR-0005: Pipeline propagates ExecutionContext.selection_reason
+    into Diagnostics.selection_reason.
+    """
+
+    def __init__(self):
+        self.selection_reason: str | None = None
+        self.selected_plugin_id: str | None = None
+        self.available_plugins: list[str] = []
+        self.selection_method: str | None = None
+
+    def __repr__(self) -> str:
+        return (
+            f"ExecutionContext(reason={self.selection_reason!r}, "
+            f"plugin={self.selected_plugin_id!r}, method={self.selection_method!r})"
+        )

acquivela-0.2.0/acquivela/facade.py

@@ -0,0 +1,47 @@
+"""AcquiVela high-level acquisition facade.
+
+Provides a governed public execution entry point that allows consumers to perform
+document acquisition using AcquiVela's stable public contracts without depending
+directly on INTERNAL Pipeline or Registry APIs.
+
+The facade delegates to existing internal orchestration (Pipeline/Registry/plugin
+selection/health/fallback) while hiding those components from the consumer.
+
+Do NOT promote Pipeline or Registry to PUBLIC/STABLE contracts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from acquivela import AcquireRequest
+from acquivela.public_result import AcquireResult
+from acquivela.pipeline import Pipeline
+from acquivela.registry import Registry
+from acquivela.plugins.docling import DoclingPlugin
+from acquivela.plugins.mineru import MinerUPlugin
+
+
+def acquire(request: AcquireRequest) -> AcquireResult:
+    """Acquire a document using stable public contracts.
+
+    Consumers do not need to import Pipeline or Registry.
+    Concrete plugin instantiation is hidden behind the facade.
+
+    Args:
+        request: Acquisition request specifying file path, engine hint,
+            and/or required capability.
+
+    Returns:
+        AcquireResult with status, canonical document, diagnostics, and error.
+
+    Normal consumer usage requires no direct Pipeline, Registry, or plugin
+    class construction.
+    """
+    # Internal bootstrap: create Registry, auto-register built-in plugins,
+    # then delegate to existing Pipeline orchestration.
+    registry = Registry()
+    registry.register(DoclingPlugin())
+    registry.register(MinerUPlugin())
+    pipeline = Pipeline(registry=registry)
+    return pipeline.execute_with_registry(request)