roborean-documents-base 0.1.2__py3-none-any.whl

roborean_documents_base/__init__.py

@@ -0,0 +1,24 @@
+"""Document driver protocols and session manager for Roborean."""
+
+from .artifact import hash_bytes, write_artifact
+from .capabilities import CapabilitySet, assert_op_allowed
+from .errors import DriverError, TemplateError, UnsupportedOperationError
+from .registry import DriverRegistry, load_entry_point_drivers
+from .session import DocumentSessionManager
+from .template_store import DocumentTemplateStore
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "CapabilitySet",
+    "DocumentSessionManager",
+    "DocumentTemplateStore",
+    "DriverError",
+    "DriverRegistry",
+    "TemplateError",
+    "UnsupportedOperationError",
+    "assert_op_allowed",
+    "hash_bytes",
+    "load_entry_point_drivers",
+    "write_artifact",
+]

roborean_documents_base/artifact.py

@@ -0,0 +1,15 @@
+"""Artifact hashing helpers."""
+
+import hashlib
+from pathlib import Path
+
+
+def hash_bytes(data: bytes) -> str:
+    """Return a lowercase SHA-256 hex digest."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def write_artifact(path: Path, data: bytes) -> None:
+    """Write artifact bytes, creating parent directories."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)

roborean_documents_base/capabilities.py

@@ -0,0 +1,30 @@
+"""Capability enforcement for document operations."""
+
+from collections.abc import Iterable
+
+from roborean_spec import DocumentDriverManifest, DocumentOperation
+
+from .errors import UnsupportedOperationError
+
+
+class CapabilitySet:
+    """Immutable set of operation capability identifiers."""
+
+    def __init__(self, capabilities: Iterable[str]) -> None:
+        """Store capabilities."""
+        self._items = frozenset(capabilities)
+
+    def allows(self, op_name: str) -> bool:
+        """Return whether ``op_name`` is advertised."""
+        return op_name in self._items
+
+
+def assert_op_allowed(
+    manifest: DocumentDriverManifest,
+    op: DocumentOperation,
+) -> None:
+    """Raise when an operation is outside the driver capability set."""
+    if op.op not in manifest.capabilities:
+        raise UnsupportedOperationError(
+            f"Driver {manifest.driver_id} does not support {op.op}"
+        )

roborean_documents_base/errors.py

@@ -0,0 +1,13 @@
+"""Document driver and template errors."""
+
+
+class DriverError(Exception):
+    """Base document driver failure."""
+
+
+class UnsupportedOperationError(DriverError):
+    """Operation not in the driver's capability set."""
+
+
+class TemplateError(DriverError):
+    """Template missing or invalid."""

roborean_documents_base/protocol.py

@@ -0,0 +1,64 @@
+"""Document driver and session protocols."""
+
+from typing import Any, Mapping, Protocol
+
+from roborean_spec import (
+    DocumentDriverManifest,
+    DocumentOperation,
+    DocumentPreview,
+    TemplateManifest,
+)
+
+from .template_store import DocumentTemplateStore
+
+
+class DocumentSession(Protocol):
+    """Mutable per-document generation state."""
+
+    document_id: str
+    driver_id: str
+    ops_applied: list[dict[str, Any]]
+
+
+class DocumentDriver(Protocol):
+    """Format-specific document engine.
+
+    Attributes:
+        driver_id: Stable id such as ``roborean.docx``.
+        manifest: Driver capability manifest.
+    """
+
+    driver_id: str
+    manifest: DocumentDriverManifest
+
+    def load_template(
+        self,
+        template_ref: str,
+        *,
+        store: DocumentTemplateStore,
+        manifest: TemplateManifest,
+    ) -> None:
+        """Load mandatory template bytes into driver-internal state."""
+
+    def begin_session(
+        self,
+        workspace: Any,
+        metadata: Mapping[str, Any],
+    ) -> DocumentSession:
+        """Open a session bound to current workspace snapshot."""
+
+    def apply_operation(
+        self,
+        session: DocumentSession,
+        op: DocumentOperation,
+    ) -> None:
+        """Apply one typed operation."""
+
+    def finalize(self, session: DocumentSession) -> None:
+        """Seal the session before serialization."""
+
+    def serialize(self, session: DocumentSession) -> bytes:
+        """Return artifact bytes."""
+
+    def preview(self, session: DocumentSession) -> DocumentPreview | None:
+        """Optional backend preview."""

roborean_documents_base/registry.py

@@ -0,0 +1,69 @@
+"""Discover installed document drivers."""
+
+import logging
+import os
+from importlib.metadata import entry_points
+from typing import Any
+
+from roborean_spec import DocumentDriverManifest
+
+logger = logging.getLogger(__name__)
+
+DOCUMENT_DRIVERS_GROUP = "roborean.document_drivers"
+
+
+class DriverRegistry:
+    """Maps driver ids to driver instances or factories."""
+
+    def __init__(self) -> None:
+        """Create an empty registry."""
+        self._drivers: dict[str, Any] = {}
+
+    def register(self, driver: Any) -> None:
+        """Register a driver instance exposing ``driver_id``."""
+        self._drivers[driver.driver_id] = driver
+
+    def get(self, driver_id: str) -> Any:
+        """Return a registered driver."""
+        return self._drivers[driver_id]
+
+    def list_ids(self) -> list[str]:
+        """Return registered driver ids."""
+        return sorted(self._drivers)
+
+    def manifests(self) -> dict[str, DocumentDriverManifest]:
+        """Return driver manifests keyed by id."""
+        return {
+            driver_id: driver.manifest
+            for driver_id, driver in self._drivers.items()
+        }
+
+
+def load_entry_point_drivers(
+    registry: DriverRegistry | None = None,
+) -> DriverRegistry:
+    """Load ``roborean.document_drivers`` entry points into a registry."""
+    registry = registry or DriverRegistry()
+    selected = entry_points().select(group=DOCUMENT_DRIVERS_GROUP)
+    allow_third = os.environ.get("ROBOREAN_ALLOW_THIRD_PARTY_PLUGINS", "") in {
+        "1",
+        "true",
+        "TRUE",
+    }
+    for item in selected:
+        try:
+            factory = item.load()
+            driver = factory() if callable(factory) else factory
+            # Built-in packages are always trusted; third-party optional.
+            trust = getattr(driver, "trust_tier", "core")
+            if trust == "third_party" and not allow_third:
+                logger.debug("Skipping third-party driver %s", item.name)
+                continue
+            registry.register(driver)
+        except Exception:
+            logger.debug(
+                "Failed loading document driver %s",
+                item.name,
+                exc_info=True,
+            )
+    return registry

roborean_documents_base/resolve_values.py

@@ -0,0 +1,27 @@
+"""Resolve workspace values for document ops."""
+
+from typing import Any
+
+from roborean_spec import PublicLiteral, SecretRefValue, WorkspaceValue
+
+from .errors import DriverError
+
+
+def public_literal_value(value: WorkspaceValue) -> Any:
+    """Extract a public literal payload; reject secrets for previews."""
+    if isinstance(value, PublicLiteral):
+        return value.value
+    if isinstance(value, SecretRefValue):
+        raise DriverError(
+            "secret_ref values cannot be rendered into document previews"
+        )
+    raise DriverError(f"Unsupported workspace value kind: {value.kind}")
+
+
+def display_value(value: WorkspaceValue) -> str:
+    """Return a redacted display string for previews."""
+    if isinstance(value, PublicLiteral):
+        return str(value.value)
+    if isinstance(value, SecretRefValue):
+        return value.display_hint or "***"
+    return "***"

roborean_documents_base/session.py

@@ -0,0 +1,161 @@
+"""Orchestrate document sessions for a compiled project run."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from roborean_spec import (
+    ArtifactRecord,
+    CompiledProject,
+    DocumentOperation,
+    DocumentPreview,
+    Project,
+)
+
+from .artifact import hash_bytes
+from .capabilities import assert_op_allowed
+from .errors import DriverError, TemplateError
+from .registry import DriverRegistry
+from .template_store import DocumentTemplateStore
+
+
+@dataclass
+class _OpenSession:
+    """Internal bookkeeping for one open document session."""
+
+    document_id: str
+    driver: Any
+    session: Any
+    template_id: str
+    template_version: str
+    output_target: str
+    media_type: str
+    payload: bytes | None = None
+    preview: DocumentPreview | None = None
+
+
+@dataclass
+class DocumentSessionManager:
+    """Open sessions, apply ops, and finalize artifacts."""
+
+    registry: DriverRegistry
+    store: DocumentTemplateStore
+    _sessions: dict[str, _OpenSession] = field(default_factory=dict)
+
+    def open_all(
+        self,
+        project: Project,
+        compiled: CompiledProject,
+        workspace: Any,
+    ) -> None:
+        """Load templates and begin sessions for every document definition."""
+        self._sessions.clear()
+        for definition in project.documents:
+            driver = self.registry.get(definition.driver)
+            manifest = self.store.load_manifest(
+                definition.template_ref,
+                manifest_ref=definition.template_manifest_ref,
+            )
+            if manifest.driver != definition.driver:
+                raise TemplateError(
+                    f"Manifest driver {manifest.driver} != {definition.driver}"
+                )
+            driver.load_template(
+                definition.template_ref,
+                store=self.store,
+                manifest=manifest,
+            )
+            session = driver.begin_session(
+                workspace,
+                {
+                    "documentId": definition.id,
+                    "projectId": project.id,
+                    "settings": definition.settings,
+                },
+            )
+            media = (
+                driver.manifest.template_media_types[0]
+                if driver.manifest.template_media_types
+                else "application/octet-stream"
+            )
+            self._sessions[definition.id] = _OpenSession(
+                document_id=definition.id,
+                driver=driver,
+                session=session,
+                template_id=manifest.template_id,
+                template_version=manifest.template_version,
+                output_target=definition.output_target
+                or f"{definition.id}.bin",
+                media_type=media,
+            )
+
+    def apply(self, op: DocumentOperation | dict[str, Any]) -> None:
+        """Route one operation to the correct session."""
+        if isinstance(op, dict):
+            operation = DocumentOperation.model_validate(op)
+        else:
+            operation = op
+        opened = self._sessions.get(operation.document_id)
+        if opened is None:
+            raise DriverError(
+                f"No open session for document {operation.document_id}"
+            )
+        assert_op_allowed(opened.driver.manifest, operation)
+        opened.driver.apply_operation(opened.session, operation)
+
+    def finalize_all(self) -> list[ArtifactRecord]:
+        """Finalize, serialize, hash, and return artifact records."""
+        records: list[ArtifactRecord] = []
+        for opened in self._sessions.values():
+            opened.driver.finalize(opened.session)
+            payload = opened.driver.serialize(opened.session)
+            opened.payload = payload
+            opened.preview = opened.driver.preview(opened.session)
+            records.append(
+                ArtifactRecord(
+                    documentId=opened.document_id,
+                    path=opened.output_target,
+                    mediaType=opened.media_type,
+                    digestSha256=hash_bytes(payload),
+                    byteLength=len(payload),
+                    templateId=opened.template_id,
+                    templateVersion=opened.template_version,
+                    driverId=opened.driver.driver_id,
+                    driverVersion=opened.driver.manifest.version,
+                )
+            )
+        return records
+
+    def payloads(self) -> dict[str, bytes]:
+        """Return serialized payloads keyed by document id."""
+        return {
+            item.document_id: item.payload
+            for item in self._sessions.values()
+            if item.payload is not None
+        }
+
+    def previews(self) -> dict[str, DocumentPreview]:
+        """Return previews keyed by document id."""
+        now = datetime.now(UTC).isoformat()
+        result: dict[str, DocumentPreview] = {}
+        for item in self._sessions.values():
+            if item.preview is not None:
+                result[item.document_id] = item.preview
+            elif item.payload is not None:
+                # Fallback text preview for UTF-8 payloads.
+                try:
+                    body = item.payload.decode("utf-8")
+                except UnicodeDecodeError:
+                    continue
+                result[item.document_id] = DocumentPreview(
+                    documentId=item.document_id,
+                    mode="text",
+                    body=body,
+                    warnings=[],
+                    generatedAt=now,
+                    renderer={
+                        "package": item.driver.driver_id,
+                        "version": item.driver.manifest.version,
+                    },
+                )
+        return result

roborean_documents_base/template_store.py

@@ -0,0 +1,56 @@
+"""Load template bytes and manifests from a project package directory."""
+
+import json
+from pathlib import Path
+
+from roborean_spec import Project, TemplateManifest
+
+from .errors import TemplateError
+
+
+class DocumentTemplateStore:
+    """Resolve templates by id from a project package root."""
+
+    def __init__(self, package_dir: Path, project: Project) -> None:
+        """Bind to a package directory and project template table."""
+        self.package_dir = package_dir
+        self.project = project
+        self._by_id = {item["id"]: item for item in project.templates}
+
+    def resolve_path(self, template_ref: str) -> Path:
+        """Return the absolute path for a template id."""
+        entry = self._by_id.get(template_ref)
+        if entry is None:
+            raise TemplateError(f"Unknown templateRef: {template_ref}")
+        path = self.package_dir / entry["path"]
+        if not path.is_file():
+            raise TemplateError(f"Missing template file: {path}")
+        return path
+
+    def load_bytes(self, template_ref: str) -> bytes:
+        """Read template bytes."""
+        return self.resolve_path(template_ref).read_bytes()
+
+    def load_manifest(
+        self,
+        template_ref: str,
+        *,
+        manifest_ref: str | None = None,
+    ) -> TemplateManifest:
+        """Load the sidecar template manifest."""
+        if manifest_ref:
+            path = self.package_dir / manifest_ref
+        else:
+            template_path = self.resolve_path(template_ref)
+            path = template_path.with_suffix(
+                template_path.suffix + ".manifest.json"
+            )
+            if not path.is_file():
+                # Also accept templates/<id>.manifest.json next to stem.
+                path = template_path.with_name(
+                    template_path.stem + ".manifest.json"
+                )
+        if not path.is_file():
+            raise TemplateError(f"Missing template manifest: {path}")
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return TemplateManifest.model_validate(data)

roborean_documents_base-0.1.2.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: roborean-documents-base
+Version: 0.1.2
+Summary: Document driver protocols and session manager for Roborean
+Project-URL: Homepage, https://github.com/TNick/roborean
+Project-URL: Repository, https://github.com/TNick/roborean
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: roborean-spec>=0.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# roborean-documents-base
+
+Protocols and session orchestration for Roborean document drivers.
+
+Bits emit typed document operations; drivers load templates and serialize
+artifacts. Format packages implement `DocumentDriver`.

roborean_documents_base-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+roborean_documents_base/__init__.py,sha256=dqT2QV8Y0FRrfXFaLMDm1TYpVfURDTuKn4UYHwrIt6A,716
+roborean_documents_base/artifact.py,sha256=kkemUA_vzn70rb1G5efUOL-XOBJxGpWHx7M98z66ChE,398
+roborean_documents_base/capabilities.py,sha256=sWAWo3zNjpCODgSFzCQdk4yc-7PgQGN7cNuF7enUzjE,908
+roborean_documents_base/errors.py,sha256=Nmqi3cO2Nei6pmBmfBLK1CxqcuRDS5yw2HjDk401-aM,294
+roborean_documents_base/protocol.py,sha256=cahDWWa7O3OEMcBb0jEXHB53aaZ-jWLqml3J722O80E,1600
+roborean_documents_base/registry.py,sha256=TioO4DfYhTCzzDflZgOLlDvTbML3Jy3xIh7mNlNomWs,2198
+roborean_documents_base/resolve_values.py,sha256=RgtitC-tSNl7S_6iVbmkg-S747GAkmvjslPuI-vcfYs,887
+roborean_documents_base/session.py,sha256=h1LeUhXBB1qsRr8BJTvG88SHgix9aMt080EqikLyir0,5735
+roborean_documents_base/template_store.py,sha256=YKlEgSyJ_9Dk6NSRNzu_epThrFVuQLc3EqwIuW6LGco,2054
+roborean_documents_base-0.1.2.dist-info/METADATA,sha256=KxgZm0Z5nhubskKtlp24qMXDVrU_u3SRHFkCuDA1i3c,663
+roborean_documents_base-0.1.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+roborean_documents_base-0.1.2.dist-info/RECORD,,

roborean_documents_base-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any