acquivela 0.2.0__py3-none-any.whl

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/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/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/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/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)

acquivela/models.py

@@ -0,0 +1,49 @@
+"""AcquiVela request/response models — Frozen per ADR-0003."""
+
+from __future__ import annotations
+
+
+class AcquireRequest:
+    """Input to the Acquisition Pipeline — data model per ADR-0001.
+
+    Attributes:
+        file_path: Input file to process.
+        engine_hint: Optional specific plugin to use (ADR-0005 §3.1).
+        required_capability: Optional capability the plugin must provide (ADR-0014).
+            If set, validated against canonical vocabulary; plugins are filtered
+            to those declaring the capability. If None, no capability filter is applied.
+    """
+
+    def __init__(
+        self,
+        file_path: str,
+        engine_hint: str | None = None,
+        required_capability: str | None = None,
+    ):
+        if not isinstance(file_path, str):
+            raise TypeError("file_path must be a string")
+        if not file_path:
+            raise ValueError("file_path must not be empty")
+        if engine_hint is not None and not isinstance(engine_hint, str):
+            raise TypeError("engine_hint must be a string or None")
+        if required_capability is not None and not isinstance(required_capability, str):
+            raise TypeError("required_capability must be a string or None")
+        self.file_path = file_path
+        self.engine_hint = engine_hint
+        self.required_capability = required_capability
+
+    def __repr__(self) -> str:
+        return (
+            f"AcquireRequest(file_path={self.file_path!r}, "
+            f"engine_hint={self.engine_hint!r}, "
+            f"required_capability={self.required_capability!r})"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, AcquireRequest):
+            return NotImplemented
+        return (
+            self.file_path == other.file_path
+            and self.engine_hint == other.engine_hint
+            and self.required_capability == other.required_capability
+        )

acquivela/pipeline.py

@@ -0,0 +1,317 @@
+"""Pipeline — Internal orchestration component per ADR-0004, ADR-0005, ADR-0006.
+
+Pipeline orchestrates plugin selection, execution, and result construction.
+Pipeline is internal infrastructure, not a frozen public contract. Its API
+may change before a future stable interface decision.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from acquivela.capabilities import Capabilities
+from acquivela.plugin import Plugin
+from acquivela.models import AcquireRequest
+from acquivela.result import PluginResult
+from acquivela.public_result import AcquireResult, Diagnostics
+from acquivela.registry import Registry
+from acquivela.execution_context import ExecutionContext
+
+
+def _validate_capability(requested: str) -> None:
+    """Validate that requested capability is in the canonical vocabulary.
+
+    Raises ValueError if the capability is not a canonical constant.
+    Per ADR-0014 §6.7: vocabulary validation is the first selection step.
+    """
+    vocabulary = {
+        v for v in Capabilities.__dict__.values()
+        if isinstance(v, str)
+    }
+    if requested not in vocabulary:
+        raise ValueError(f"Unknown capability: {requested}")
+
+
+class Pipeline:
+    """Pipeline layer — converts PluginResult (internal) to AcquireResult (public).
+
+    Per ADR-0004: Pipeline is the exception boundary. All plugin exceptions
+    are caught and converted to AcquireResult(status="failure").
+
+    Per ADR-0006: Pipeline performs Selection; Registry supplies candidates.
+    """
+
+    def __init__(self, registry: Optional[Registry] = None):
+        if registry is not None and not isinstance(registry, Registry):
+            raise TypeError(f"registry must be a Registry or None, got {type(registry).__name__}")
+        self.registry = registry
+
+    def execute(
+        self,
+        plugin: Plugin,
+        request: AcquireRequest,
+        execution_context: Optional[ExecutionContext] = None,
+    ) -> AcquireResult:
+        """Execute a specific plugin (bypasses Registry selection).
+
+        Args:
+            plugin: The plugin to execute
+            request: The acquisition request
+            execution_context: Optional internal context for selection_reason
+
+        Returns:
+            AcquireResult with status, canonical_document, diagnostics, error
+        """
+        if not isinstance(plugin, Plugin):
+            raise TypeError(f"plugin must be a Plugin instance, got {type(plugin).__name__}")
+        if not isinstance(request, AcquireRequest):
+            raise TypeError(f"request must be an AcquireRequest, got {type(request).__name__}")
+        if execution_context is not None and not isinstance(execution_context, ExecutionContext):
+            raise TypeError(f"execution_context must be an ExecutionContext or None, got {type(execution_context).__name__}")
+
+        start_time = time.time()
+
+        try:
+            plugin_result = plugin.acquire(request)
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            meta = plugin.metadata()
+
+            # Populate selection_reason if execution_context provided
+            selection_reason = None
+            if execution_context is not None:
+                selection_reason = execution_context.selection_reason
+
+            diagnostics = Diagnostics(
+                plugin_id=meta["id"],
+                plugin_version=meta["version"],
+                engine_used=plugin_result.internal_diagnostics.get("engine", "unknown"),
+                duration_ms=duration_ms,
+                warning=None,
+                selection_reason=selection_reason,
+            )
+
+            return AcquireResult(
+                status="success",
+                canonical_document=plugin_result.canonical_document,
+                diagnostics=[diagnostics],
+                error=None,
+            )
+
+        except Exception as e:
+            duration_ms = int((time.time() - start_time) * 1000)
+            meta = plugin.metadata()
+
+            selection_reason = None
+            if execution_context is not None:
+                selection_reason = execution_context.selection_reason
+
+            diagnostics = Diagnostics(
+                plugin_id=meta["id"],
+                plugin_version=meta["version"],
+                engine_used="unknown",
+                duration_ms=duration_ms,
+                warning=str(e),
+                selection_reason=selection_reason,
+            )
+
+            return AcquireResult(
+                status="failure",
+                canonical_document=None,
+                diagnostics=[diagnostics],
+                error=str(e),
+            )
+
+    def execute_with_registry(
+        self,
+        request: AcquireRequest,
+        execution_context: Optional[ExecutionContext] = None,
+    ) -> AcquireResult:
+        """Execute with Registry-based plugin selection.
+
+        Selection logic per ADR-0004 §5.2 + ADR-0013 + ADR-0014:
+        0. If required_capability set → validate against canonical vocabulary; fail if unknown
+        1. If engine_hint provided → Registry.get_by_id(engine_hint) → strict, no fallback
+           - If required_capability set → fail if plugin doesn't provide capability
+        2. Else → derive extension → Registry.get_by_extension(ext)
+           - If required_capability set → filter candidates by capability
+        3. Health-ordered fallback (M13) on remaining candidates
+        4. No match → AcquireResult(status="failure")
+
+        Args:
+            request: The acquisition request
+            execution_context: Optional internal context for selection_reason
+
+        Returns:
+            AcquireResult
+        """
+        if not isinstance(request, AcquireRequest):
+            raise TypeError(f"request must be an AcquireRequest, got {type(request).__name__}")
+        if execution_context is not None and not isinstance(execution_context, ExecutionContext):
+            raise TypeError(f"execution_context must be an ExecutionContext or None, got {type(execution_context).__name__}")
+
+        if self.registry is None:
+            raise ValueError("Registry not configured")
+
+        # M14 §6.7: Validate capability against canonical vocabulary (first step)
+        if request.required_capability is not None:
+            try:
+                _validate_capability(request.required_capability)
+            except ValueError as e:
+                return AcquireResult(
+                    status="failure",
+                    canonical_document=None,
+                    diagnostics=[],
+                    error=str(e),
+                )
+
+        # engine_hint path — STRICT per ADR-0013 §8.3
+        if request.engine_hint:
+            plugin = self.registry.get_by_id(request.engine_hint)
+            if plugin is None:
+                return AcquireResult(
+                    status="failure",
+                    canonical_document=None,
+                    diagnostics=[],
+                    error=f"Plugin not found: {request.engine_hint}",
+                )
+
+            # M14: capability validation on engine_hint path (hard constraint)
+            if request.required_capability is not None:
+                if request.required_capability not in plugin.capabilities():
+                    return AcquireResult(
+                        status="failure",
+                        canonical_document=None,
+                        diagnostics=[],
+                        error=f"Plugin '{request.engine_hint}' does not provide capability: {request.required_capability}",
+                    )
+
+            if execution_context is not None:
+                execution_context.selection_method = "engine_hint"
+                execution_context.selected_plugin_id = request.engine_hint
+                execution_context.available_plugins = [request.engine_hint]
+                execution_context.selection_reason = (
+                    f"engine_hint: matched plugin id '{request.engine_hint}' from [{request.engine_hint}]"
+                )
+
+            return self.execute(plugin, request, execution_context)
+
+        # No engine_hint — extension-based selection with M13 fallback
+        ext = request.file_path.rsplit(".", 1)[-1] if "." in request.file_path else ""
+        candidates = self.registry.get_by_extension(ext)
+        if not candidates:
+            return AcquireResult(
+                status="failure",
+                canonical_document=None,
+                diagnostics=[],
+                error=f"No plugin supports extension: {ext}",
+            )
+
+        # M14 §9.1: Filter candidates by capability (hard constraint, after extension matching)
+        if request.required_capability is not None:
+            candidates = [
+                c for c in candidates
+                if request.required_capability in c.capabilities()
+            ]
+            if not candidates:
+                return AcquireResult(
+                    status="failure",
+                    canonical_document=None,
+                    diagnostics=[],
+                    error=f"No eligible plugin provides capability: {request.required_capability}",
+                )
+
+        # M13 §8.4: Evaluate health once per candidate; retain (candidate, health) pairs
+        evaluated = [(candidate, candidate.health_check()) for candidate in candidates]
+
+        # M13 §8.4: Partition — healthy first, unavailable after; registration order within groups
+        healthy_pairs = [(c, h) for c, h in evaluated if h.status == "healthy"]
+        unavailable_pairs = [(c, h) for c, h in evaluated if h.status != "healthy"]
+        ordered = healthy_pairs + unavailable_pairs
+
+        candidate_ids = [c.metadata()["id"] for c in candidates]
+
+        diagnostics_entries: list[Diagnostics] = []
+
+        # M13: Record skip entries for ALL unavailable candidates upfront,
+        # so they appear in diagnostics even if a healthy candidate succeeds early.
+        for candidate, health in ordered:
+            if health.status != "healthy":
+                diag = Diagnostics(
+                    plugin_id=candidate.metadata()["id"],
+                    plugin_version=candidate.metadata()["version"],
+                    engine_used="unknown",
+                    duration_ms=0,
+                    warning=f"Skipped: health={health.status} ({health.message})",
+                    selection_reason=None,
+                )
+                diagnostics_entries.append(diag)
+
+        last_result: Optional[AcquireResult] = None
+
+        for candidate, health in ordered:
+            plugin_id = candidate.metadata()["id"]
+
+            # Skip unavailable candidates (already recorded in diagnostics_entries above)
+            if health.status != "healthy":
+                continue
+
+            # M13 §10.1: Capture selection_reason before execute() overwrites execution_context
+            if execution_context is not None:
+                execution_context.selection_method = "extension"
+                execution_context.selected_plugin_id = plugin_id
+                execution_context.available_plugins = candidate_ids
+                execution_context.selection_reason = (
+                    f"extension: .{ext} matched plugin supports ['{ext}'] from {candidate_ids}"
+                )
+
+            # M13: Attempt acquisition via existing execute() (single-plugin, exception boundary)
+            result = self.execute(candidate, request, execution_context)
+
+            # extract singleton Diagnostics entry from execute()'s result
+            diagnostics_entries.append(result.diagnostics[0])
+
+            if result.status == "success":
+                # M13: Replace singleton diagnostics with accumulated multi-attempt list
+                result.diagnostics = diagnostics_entries
+                return result
+
+            # Acquisition failed — record and try next candidate
+            last_result = result
+            last_result.diagnostics = diagnostics_entries
+
+        # All candidates exhausted
+        if last_result is not None:
+            return last_result
+
+        # All candidates were unavailable — return failure with accumulated skip diagnostics
+        return AcquireResult(
+            status="failure",
+            canonical_document=None,
+            diagnostics=diagnostics_entries,
+            error=f"All {len(candidates)} candidate(s) unavailable",
+        )
+
+    def __repr__(self) -> str:
+        return f"Pipeline(registry={self.registry!r})"
+
+
+class SelectionContext:
+    """Internal execution context for selection reasoning.
+
+    Internal architectural component — NOT part of public contracts.
+    Per ADR-0006 §7.1: Pipeline carries this during selection.
+    """
+
+    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"SelectionContext(reason={self.selection_reason!r}, "
+            f"plugin={self.selected_plugin_id!r}, method={self.selection_method!r})"
+        )

acquivela/plugin.py

@@ -0,0 +1,68 @@
+"""Plugin SPI — Frozen per ADR-0003."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+@dataclass(frozen=True)
+class PluginHealth:
+    """Plugin-level health status per ADR-0012.
+
+    Two states only for M12:
+    - healthy: plugin minimum health probe succeeds (import-level)
+    - unavailable: plugin minimum health probe fails
+
+    ``healthy`` does NOT guarantee ``acquire()`` will succeed.
+    M12 health is plugin-level availability, not execution assurance.
+    """
+
+    status: Literal["healthy", "unavailable"]
+    message: str | None = None
+    last_checked: float | None = None
+
+
+class Plugin(ABC):
+    """Plugin SPI — contract between plugin and pipeline.
+
+    Plugins implement this interface. The pipeline interacts with plugins
+    only through this SPI. Per ADR-0004, plugins MUST NOT import:
+    - acquivela.pipeline
+    - acquivela.registry
+    - acquivela.public_result
+    - acquivela.planner
+    """
+
+    @abstractmethod
+    def metadata(self) -> dict[str, Any]:
+        """Return plugin metadata.
+
+        Required keys (per ADR-0003 frozen SPI):
+        - id: str — unique plugin identifier
+        - name: str — human-readable name
+        - version: str — plugin version
+        - supports: list[str] — file extensions/MIME types supported
+        - provides: list[str] — capability vocabulary (deferred)
+        - priority: int — placeholder only (deferred)
+        """
+        ...
+
+    @abstractmethod
+    def acquire(self, request: "AcquireRequest") -> "PluginResult":
+        """Process request and return PluginResult (internal SPI contract)."""
+        ...
+
+    def health_check(self, force: bool = False) -> PluginHealth:
+        """Return current plugin-level availability.
+
+        Default: returns healthy without probing.
+        Concrete implementations performing runtime probes SHOULD cache results.
+        ``force`` has effect only for implementations with cached runtime probing.
+        """
+        return PluginHealth(status="healthy")
+
+    def capabilities(self) -> list[str]:
+        """Return declared capabilities as a copy of metadata['provides']."""
+        return list(self.metadata().get("provides", []))

acquivela/plugins/__init__.py

@@ -0,0 +1,14 @@
+"""Plugin package — plugins must only import allowed modules.
+
+Allowed imports (per ADR-0004 §3.3):
+- acquivela.plugin (Plugin ABC)
+- acquivela.models (AcquireRequest)
+- acquivela.cdm (CanonicalDocument, Page, TextBlock)
+- acquivela.result (PluginResult)
+
+Forbidden imports (enforced by import-linter):
+- acquivela.pipeline
+- acquivela.registry
+- acquivela.public_result
+- acquivela.planner
+"""