quillwork-server 0.0.3__py3-none-any.whl

quillwork_server/__init__.py

@@ -0,0 +1,9 @@
+"""Quillwork's reference service: a document service library, an MCP server and an HTTP API.
+
+The library is :mod:`quillwork_server.core` (embed it in your application) and
+:mod:`quillwork_server.tools` (the agent tool layer). The front ends are
+:mod:`quillwork_server.mcp_server` (``quillwork-mcp``) and :mod:`quillwork_server.http_app`
+(``quillwork-server``).
+"""
+
+__version__ = "0.0.3"

quillwork_server/config.py

@@ -0,0 +1,86 @@
+"""Settings shared by the two front ends (``quillwork-mcp``, ``quillwork-server``).
+
+Every setting has an environment variable (``QUILLWORK_*``) and a command-line flag; the flag
+wins. Library users skip this module and build a :class:`~.core.DocumentService` themselves.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+
+from .core import (
+    DocumentService,
+    Engine,
+    FakeEngine,
+    FileStore,
+    MemoryStore,
+    QuillworkEngine,
+    ServiceConfig,
+    Store,
+)
+
+_DEFAULTS = ServiceConfig()
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    #: Directory for :class:`~.core.FileStore`; empty keeps documents in memory.
+    store: str = ""
+    #: ``quillwork`` (the real binding) or ``fake`` (plain text; for demos and tests).
+    engine: str = "quillwork"
+    #: Author on every transaction an agent makes through these front ends.
+    author: str = "AI"
+    #: HTTP: required ``Authorization: Bearer <key>`` (or ``X-API-Key``); empty disables auth.
+    api_key: str = ""
+    max_upload_bytes: int = _DEFAULTS.max_upload_bytes
+    max_ops_per_transaction: int = _DEFAULTS.max_ops_per_transaction
+    host: str = "127.0.0.1"
+    port: int = 8765
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> Settings:
+        env = os.environ if env is None else env
+        base = cls()
+        return cls(
+            store=env.get("QUILLWORK_STORE", base.store),
+            engine=env.get("QUILLWORK_ENGINE", base.engine),
+            author=env.get("QUILLWORK_AUTHOR", base.author),
+            api_key=env.get("QUILLWORK_API_KEY", base.api_key),
+            max_upload_bytes=int(env.get("QUILLWORK_MAX_UPLOAD_BYTES", base.max_upload_bytes)),
+            max_ops_per_transaction=int(env.get("QUILLWORK_MAX_OPS", base.max_ops_per_transaction)),
+            host=env.get("QUILLWORK_HOST", base.host),
+            port=int(env.get("QUILLWORK_PORT", base.port)),
+        )
+
+    def service(self) -> DocumentService:
+        engine: Engine = (
+            FakeEngine(author=self.author) if self.engine == "fake" else QuillworkEngine()
+        )
+        store: Store = FileStore(self.store) if self.store else MemoryStore()
+        config = ServiceConfig(
+            max_upload_bytes=self.max_upload_bytes,
+            max_ops_per_transaction=self.max_ops_per_transaction,
+            default_author=self.author,
+        )
+        return DocumentService(engine, store, config=config)
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--store", help="directory to keep documents in (default: memory)")
+    parser.add_argument("--engine", choices=("quillwork", "fake"))
+    parser.add_argument("--author", help="author name on agent edits (default: AI)")
+    parser.add_argument("--host")
+    parser.add_argument("--port", type=int)
+
+
+def from_args(args: argparse.Namespace, base: Settings | None = None) -> Settings:
+    settings = base or Settings.from_env()
+    changes = {
+        key: getattr(args, key)
+        for key in ("store", "engine", "author", "host", "port")
+        if getattr(args, key, None) is not None
+    }
+    return replace(settings, **changes)

quillwork_server/core/__init__.py

@@ -0,0 +1,61 @@
+"""The library core: store, locks, engine seam and the document service.
+
+Import from here; the submodules are an implementation detail.
+"""
+
+from .engine import Engine, EngineDocument, QuillworkEngine, asset_id, sniff_image
+from .errors import SPEC_VERSION, document_not_found, envelope, error_object, make_error
+from .fake import FakeDocument, FakeEngine, fake_bytes
+from .locks import LocalLocks, LocalNotifier, LockProvider, LockTimeout, Notifier
+from .service import DocumentService, ExportVariant, ServiceConfig, Session
+from .store import (
+    DocumentExists,
+    DocumentNotFound,
+    FileStore,
+    HeadMoved,
+    MemoryStore,
+    Store,
+    StoreError,
+    VersionNotFound,
+)
+from .types import JSON, Asset, DocumentInfo, PatchFeed, StoredVersion, VersionKind, VersionRecord
+
+__all__ = [
+    "JSON",
+    "SPEC_VERSION",
+    "Asset",
+    "DocumentExists",
+    "DocumentInfo",
+    "DocumentNotFound",
+    "DocumentService",
+    "Engine",
+    "EngineDocument",
+    "ExportVariant",
+    "FakeDocument",
+    "FakeEngine",
+    "FileStore",
+    "HeadMoved",
+    "LocalLocks",
+    "LocalNotifier",
+    "LockProvider",
+    "LockTimeout",
+    "MemoryStore",
+    "Notifier",
+    "PatchFeed",
+    "QuillworkEngine",
+    "ServiceConfig",
+    "Session",
+    "Store",
+    "StoreError",
+    "StoredVersion",
+    "VersionKind",
+    "VersionNotFound",
+    "VersionRecord",
+    "asset_id",
+    "document_not_found",
+    "envelope",
+    "error_object",
+    "fake_bytes",
+    "make_error",
+    "sniff_image",
+]

quillwork_server/core/engine.py

@@ -0,0 +1,149 @@
+"""The engine seam: what the service needs from a document engine.
+
+:class:`QuillworkEngine` adapts the real binding (``quillwork.Document``); ``fake.FakeEngine``
+implements the same protocol on plain text for tests. Both speak the spec's JSON shapes: a
+Transaction in, an OpResult out; a ReadOp in, a ReadResult out; errors as
+:class:`quillwork.errors.QuillworkError`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Protocol, runtime_checkable
+
+from .types import JSON, Asset
+
+
+@runtime_checkable
+class EngineDocument(Protocol):
+    """One open document. Not thread-safe: the service serialises calls on it."""
+
+    @property
+    def version(self) -> int: ...
+
+    def apply(self, transaction: JSON) -> JSON:
+        """Apply a Transaction atomically; return the OpResult. Raises QuillworkError."""
+        ...
+
+    def read_op(self, request: JSON) -> JSON:
+        """Run a ReadOp; return the ReadResult. Raises QuillworkError."""
+        ...
+
+    def view_model(self) -> JSON: ...
+
+    def save(self) -> bytes: ...
+
+    def sidecar(self) -> JSON | None:
+        """Engine state that is not in the .docx (anchor map, change sets), versioned with it."""
+        ...
+
+
+@runtime_checkable
+class Engine(Protocol):
+    name: str
+
+    def open(self, data: bytes, *, version: int = 1, sidecar: JSON | None = None) -> EngineDocument:
+        """Open ``data`` as ``version``, restoring ``sidecar`` when given.
+
+        Raises QuillworkError (BAD_PACKAGE, PROTECTED, LIMIT) for unusable input.
+        """
+        ...
+
+    def asset(self, data: bytes, asset_id: str) -> Asset | None:
+        """The bytes of an image the document at ``data`` holds, by asset id (``a_<16 hex>``)."""
+        ...
+
+
+def asset_id(data: bytes) -> str:
+    """Asset ids are the first 16 hex digits of sha256(bytes) (spec/anchors.md)."""
+    return "a_" + hashlib.sha256(data).hexdigest()[:16]
+
+
+_MAGIC: tuple[tuple[bytes, str], ...] = (
+    (b"\x89PNG\r\n\x1a\n", "image/png"),
+    (b"\xff\xd8\xff", "image/jpeg"),
+    (b"GIF87a", "image/gif"),
+    (b"GIF89a", "image/gif"),
+)
+
+
+def sniff_image(data: bytes) -> str | None:
+    """The image MIME type from magic bytes, or ``None``. Never trusts a declared type."""
+    for magic, mime in _MAGIC:
+        if data.startswith(magic):
+            return mime
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    head = data[:512].lstrip().lower()
+    if head.startswith(b"<svg") or (head.startswith(b"<?xml") and b"<svg" in head):
+        return "image/svg+xml"
+    return None
+
+
+# -- the real binding ------------------------------------------------------------------------
+
+
+class QuillworkEngine:
+    """:class:`Engine` over :class:`quillwork.Document`.
+
+    Versions and sidecars pass straight through: ``Document.open(data, sidecar=..., version=...)``
+    opens at ``max(version, the sidecar's)``, which is how the service reopens an import or a
+    restore at ``head + 1`` with an older sidecar.
+    """
+
+    name = "quillwork"
+
+    def __init__(self, limits: Any | None = None) -> None:
+        import quillwork
+
+        self._quillwork = quillwork
+        self._limits = limits
+
+    def open(self, data: bytes, *, version: int = 1, sidecar: JSON | None = None) -> EngineDocument:
+        doc = self._quillwork.Document.open(data, self._limits, sidecar=sidecar, version=version)
+        return _QuillworkDocument(doc)
+
+    def asset(self, data: bytes, asset_id_: str) -> Asset | None:
+        package = self._quillwork.Package.open(data)
+        for name in package.names():
+            if not name.startswith("word/media/"):
+                continue
+            part = bytes(package.part(name))
+            if asset_id(part) == asset_id_:
+                mime = (
+                    sniff_image(part) or package.content_type_of(name) or "application/octet-stream"
+                )
+                return Asset(part, mime)
+        return None
+
+
+class _QuillworkDocument:
+    """:class:`EngineDocument` over an open :class:`quillwork.Document`."""
+
+    def __init__(self, doc: Any) -> None:
+        self._doc = doc
+
+    @property
+    def version(self) -> int:
+        return int(self._doc.version)
+
+    def apply(self, transaction: JSON) -> JSON:
+        result: JSON = self._doc.apply(transaction)
+        return result
+
+    def read_op(self, request: JSON) -> JSON:
+        result: JSON = self._doc.read_op(request)
+        return result
+
+    def view_model(self) -> JSON:
+        result: JSON = self._doc.view_model()
+        return result
+
+    def save(self) -> bytes:
+        return bytes(self._doc.save())
+
+    def sidecar(self) -> JSON | None:
+        """The sidecar as a JSON object (the binding caches it from the last save)."""
+        result: JSON = json.loads(self._doc.sidecar())
+        return result

quillwork_server/core/errors.py

@@ -0,0 +1,110 @@
+"""Spec error objects (``spec/schema/error.schema.json``) built and rendered on the service side.
+
+The service raises the binding's own exception classes (:mod:`quillwork.errors`), so a host sees
+one error type whether the engine or the service refused a call. :func:`make_error` builds one
+with a complete spec ``error`` object; :func:`envelope` turns any exception into the
+``{spec_version, ok: false, error}`` response the front ends return.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from quillwork.errors import QuillworkError, error_from_dict
+
+from .types import JSON
+
+SPEC_VERSION: Final = "0.1.0"
+
+#: retryable per code (spec/errors.md). UNSUPPORTED depends on the reason; see make_error.
+RETRYABLE: Final[dict[str, bool]] = {
+    "STALE_ANCHOR": True,
+    "AMBIGUOUS": True,
+    "NOT_FOUND": True,
+    "IN_FIELD": True,
+    "INVALID_OP": True,
+    "UNSUPPORTED": False,
+    "CONFIRM_REQUIRED": True,
+    "PROTECTED": False,
+    "LIMIT": True,
+    "BAD_VERSION": True,
+    "CONFLICT": True,
+    "BAD_PACKAGE": False,
+    "INVARIANT": False,
+    "INTERNAL": True,
+}
+
+#: UNSUPPORTED reasons a retry with other arguments can get past.
+_RETRYABLE_UNSUPPORTED: Final = frozenset({"direct_only", "track_only"})
+
+
+def make_error(
+    code: str,
+    message: str,
+    *,
+    version: int,
+    op_index: int | None = None,
+    retryable: bool | None = None,
+    **fields: Any,
+) -> QuillworkError:
+    """The binding exception for ``code`` carrying a full spec error object.
+
+    ``fields`` are the per-code members (``anchor``, ``current``, ``what``, ``reason``, ``limit``,
+    ``path``, ``usage``, ``candidates``...); ``None`` values are left out.
+    """
+    if retryable is None:
+        retryable = RETRYABLE.get(code, False)
+        if code == "UNSUPPORTED":
+            retryable = fields.get("reason") in _RETRYABLE_UNSUPPORTED
+    error: JSON = {
+        "code": code,
+        "message": message,
+        "retryable": retryable,
+        "version": max(1, int(version)),
+        "op_index": op_index,
+    }
+    for key, value in fields.items():
+        if value is not None:
+            error[key] = value
+    return error_from_dict(error)
+
+
+def error_object(exc: BaseException, *, version: int | None = None) -> JSON:
+    """The spec ``error`` object for any exception.
+
+    ``version`` fills in a missing current version (the binding leaves it ``None`` for errors raised
+    before a document exists, e.g. BAD_PACKAGE on upload).
+    """
+    if isinstance(exc, QuillworkError):
+        error = dict(exc.error)
+        error.setdefault("code", exc.code)
+        error.setdefault("message", exc.message or str(exc))
+        error.setdefault("retryable", exc.retryable)
+        error.setdefault("op_index", exc.op_index)
+        if not isinstance(error.get("version"), int) or error["version"] < 1:
+            error["version"] = max(1, version or exc.version or 1)
+        if error["code"] in ("CONFLICT", "INTERNAL"):
+            error["retryable"] = True
+        if error["code"] in ("INVARIANT", "BAD_PACKAGE", "PROTECTED"):
+            error["retryable"] = False
+        return error
+    return {
+        "code": "INTERNAL",
+        "message": "The engine failed unexpectedly; retry once, then report it.",
+        "retryable": True,
+        "version": max(1, version or 1),
+        "op_index": None,
+    }
+
+
+def envelope(exc: BaseException, *, version: int | None = None) -> JSON:
+    """``{spec_version, ok: false, error}`` for ``exc``."""
+    return {"spec_version": SPEC_VERSION, "ok": False, "error": error_object(exc, version=version)}
+
+
+def document_not_found(document_id: str) -> QuillworkError:
+    # `what: "document"` is not in the 0.1.0 enum yet (proposed in docs/SERVER.md). `version` is
+    # required (minimum 1) even though no document exists, so it is 1.
+    return make_error(
+        "NOT_FOUND", f"There is no document {document_id!r}.", version=1, what="document"
+    )