changex-api 0.1.0__py3-none-any.whl

changex_api/__init__.py

@@ -0,0 +1,29 @@
+"""ChangeX HTTP/REST API: the changex-core spine, re-exposed over plain HTTP.
+
+This package wraps :mod:`changex_core` (reusing the MCP tool semantics from
+:mod:`changex_mcp.tools`) in a FastAPI app so ANY caller can drive tracked
+editing over HTTP — a local/offline model with no function-calling, a ``curl``
+script, or a ChatGPT custom GPT whose Action imports the auto-generated
+``/openapi.json``.
+
+Public surface (used by the entry point and tests):
+
+App
+    ``app.app`` — the configured :class:`fastapi.FastAPI` instance;
+    ``app.create_app()`` — a factory that builds a fresh app with its own
+    in-process session store.
+
+Runner
+    ``__main__.main`` — the ``changex-api`` console script / ``python -m
+    changex_api`` entry point (launches uvicorn, 127.0.0.1 by default).
+
+Models
+    ``models`` — the Pydantic request/response models that shape the OpenAPI
+    schema consumed by ChatGPT Actions and other clients.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

changex_api/__main__.py

@@ -0,0 +1,77 @@
+"""Run the ChangeX API with uvicorn: ``changex-api`` / ``python -m changex_api``.
+
+Binds ``127.0.0.1`` by default (the local, trustworthy path that needs no token).
+A non-local bind (any host other than ``127.0.0.1`` / ``localhost`` / ``::1``) is
+*refused* unless ``CHANGEX_API_TOKEN`` is set, so the surface is never exposed to
+a network without bearer-token auth — a fail-closed default rather than a footgun.
+
+Flags / env:
+
+* ``--host`` / ``CHANGEX_API_HOST`` (default ``127.0.0.1``)
+* ``--port`` / ``CHANGEX_API_PORT`` (default ``8000``)
+* ``--reload`` for development auto-reload
+* ``CHANGEX_API_TOKEN`` — when set, every non-health route requires
+  ``Authorization: Bearer <token>``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import uvicorn
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+_LOCAL_HOSTS = {"127.0.0.1", "localhost", "::1"}
+_TOKEN_ENV = "CHANGEX_API_TOKEN"
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="changex-api",
+        description="Serve the ChangeX HTTP/REST API (FastAPI + uvicorn).",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("CHANGEX_API_HOST", DEFAULT_HOST),
+        help="Bind host (default 127.0.0.1). Non-local hosts require CHANGEX_API_TOKEN.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("CHANGEX_API_PORT", DEFAULT_PORT)),
+        help="Bind port (default 8000).",
+    )
+    parser.add_argument(
+        "--reload", action="store_true", help="Enable uvicorn auto-reload (development)."
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Console-script / ``python -m changex_api`` entry point.
+
+    Returns a process exit code (``0`` on a clean shutdown, ``2`` if a non-local
+    bind was requested without a token).
+    """
+    args = _parse_args(argv)
+    host = str(args.host)
+    if host not in _LOCAL_HOSTS and not os.environ.get(_TOKEN_ENV):
+        sys.stderr.write(
+            f"refusing to bind non-local host {host!r} without {_TOKEN_ENV}; "
+            f"set {_TOKEN_ENV}=<secret> to enable bearer-token auth, or bind 127.0.0.1.\n"
+        )
+        return 2
+    uvicorn.run(
+        "changex_api.app:app",
+        host=host,
+        port=int(args.port),
+        reload=bool(args.reload),
+    )
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

changex_api/app.py

@@ -0,0 +1,405 @@
+"""The ChangeX HTTP/REST API — a thin FastAPI wrapper over ``changex_core``.
+
+Why this exists: ChangeX already exposes its tracked-editing spine over MCP
+(:mod:`changex_mcp`). This package re-exposes the *same* semantics over plain
+HTTP so ANY caller can use it — a local/offline model with no function-calling, a
+shell script with ``curl``, or a ChatGPT custom GPT whose Action consumes the
+auto-generated ``/openapi.json``. The endpoint set mirrors the MCP tools 1:1.
+
+Design notes:
+
+* **Reuse, not reimplementation.** The tracked-editing tools delegate to
+  :mod:`changex_mcp.tools` against an in-process :class:`SessionStore`, so the
+  boundary enforcement (before-substring validation, oversized-op rejection) and
+  the structured error codes are byte-for-byte the same as MCP. The passive
+  ``/open`` + ``/seal`` and ``/report`` endpoints call the core directly.
+* **Path-sanitized.** Every caller-supplied path goes through
+  :func:`changex_core.paths.safe_path` (the same guard the core uses) before any
+  I/O, rejecting directory traversal / NUL bytes / wrong suffixes.
+* **Local by default.** ``create_app`` binds nothing itself; the runner
+  (:mod:`changex_api.__main__`) defaults to ``127.0.0.1``. When a token is set via
+  ``CHANGEX_API_TOKEN`` (required for any non-local bind), every route except the
+  liveness probe demands a matching ``Authorization: Bearer <token>`` header.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from fastapi import Depends, FastAPI, Header, HTTPException, Query, status
+from fastapi.responses import HTMLResponse
+
+from changex_core import __version__ as _CORE_VERSION
+from changex_core.journal.journal import Journal
+from changex_core.paths import UnsafePathError, safe_path
+from changex_core.passive import open_passive, seal_passive
+from changex_core.render.html import render_html, render_markdown
+
+from changex_mcp import tools
+from changex_mcp.session import SessionError, SessionStore
+
+from changex_api import __version__ as _API_VERSION
+from changex_api.models import (
+    ChangesResponse,
+    EditRequest,
+    EditResponse,
+    HealthResponse,
+    OpenTrackedRequest,
+    OpenTrackedResponse,
+    OutlineResponse,
+    PassiveOpenRequest,
+    PassiveOpenResponse,
+    PassiveSealRequest,
+    PassiveSealResponse,
+    ReportResponse,
+    SaveRequest,
+    SaveResponse,
+)
+
+#: Environment variable holding the bearer token. When set, all non-health routes
+#: require ``Authorization: Bearer <CHANGEX_API_TOKEN>``. Leave unset only for a
+#: trusted local (127.0.0.1) bind.
+TOKEN_ENV = "CHANGEX_API_TOKEN"
+
+# Starlette renamed 422 to *_CONTENT; prefer the new name, fall back for older
+# pins so the package works across the supported FastAPI/Starlette range. (The
+# deprecated alias is only touched when the new constant is absent, so newer
+# Starlette never triggers its DeprecationWarning.)
+if hasattr(status, "HTTP_422_UNPROCESSABLE_CONTENT"):
+    HTTP_422 = status.HTTP_422_UNPROCESSABLE_CONTENT
+else:  # pragma: no cover - depends on the installed Starlette version
+    HTTP_422 = status.HTTP_422_UNPROCESSABLE_ENTITY
+
+API_TITLE = "ChangeX API"
+API_DESCRIPTION = (
+    "Provenance-first tracked editing for Word documents, over HTTP. Open a .docx "
+    "for tracked editing, discover node ids via the outline, make the SMALLEST "
+    "possible intent-named edit per call (always passing the exact existing text in "
+    "`before` — blind overwrites are refused), then save a native Word "
+    "accept/reject revisions file plus a hash-chained .changex provenance journal. "
+    "A passive (no-tool-calling) /open + /seal path serves offline models. This "
+    "schema is consumable directly as a ChatGPT custom GPT Action."
+)
+
+
+def _require_token(authorization: str | None = Header(default=None)) -> None:
+    """Enforce bearer-token auth iff ``CHANGEX_API_TOKEN`` is set.
+
+    When the env var is unset (the local-only default) this is a no-op so the
+    127.0.0.1 developer flow needs no header. When it is set, every guarded route
+    requires ``Authorization: Bearer <token>`` and rejects anything else with 401.
+    """
+    expected = os.environ.get(TOKEN_ENV)
+    if not expected:
+        return
+    if not authorization or not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="missing bearer token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    presented = authorization[len("Bearer ") :].strip()
+    if presented != expected:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="invalid bearer token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+def _tool_error_http(exc: tools.ToolError) -> HTTPException:
+    """Map an MCP ToolError to an HTTP 4xx carrying its structured payload.
+
+    ``already_open`` is a conflict (409); ``open_failed`` is a bad request (400);
+    everything else (split_required, before_mismatch, node_not_found, …) is a 422
+    unprocessable entity — the model should read the detail and adjust the op.
+    """
+    if exc.code == "already_open":
+        code = status.HTTP_409_CONFLICT
+    elif exc.code in ("open_failed", "bad_format"):
+        code = status.HTTP_400_BAD_REQUEST
+    else:
+        code = HTTP_422
+    return HTTPException(status_code=code, detail=exc.to_dict())
+
+
+def _value_error_http(exc: Exception) -> HTTPException:
+    """Map a validation / unsafe-path error to a 400 with a structured payload."""
+    code = "unsafe_path" if isinstance(exc, UnsafePathError) else "invalid_argument"
+    return HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail={"error": code, "detail": str(exc)},
+    )
+
+
+def create_app() -> FastAPI:
+    """Build and return the configured FastAPI application.
+
+    A single in-process :class:`SessionStore` backs the tracked-editing routes
+    (one process, single-session-per-handle — same model as the MCP server). The
+    returned app auto-serves its OpenAPI schema at ``/openapi.json``; that schema
+    is exactly what a ChatGPT custom GPT Action imports.
+    """
+    store = SessionStore()
+    app = FastAPI(
+        title=API_TITLE,
+        description=API_DESCRIPTION,
+        version=_API_VERSION,
+    )
+
+    guard = [Depends(_require_token)]
+
+    # -- liveness (unauthenticated) -------------------------------------------
+
+    @app.get("/healthz", response_model=HealthResponse, tags=["meta"], operation_id="healthz")
+    def healthz() -> HealthResponse:
+        """Liveness probe; never requires auth."""
+        return HealthResponse(version=_API_VERSION)
+
+    # -- tracked editing (mirrors the MCP tools) ------------------------------
+
+    @app.post(
+        "/sessions",
+        response_model=OpenTrackedResponse,
+        tags=["tracked"],
+        dependencies=guard,
+        operation_id="openTracked",
+    )
+    def open_session(body: OpenTrackedRequest) -> Any:
+        """Open a .docx for tracked editing and return a session handle + summary."""
+        agent_ctx = body.agent_context.model_dump() if body.agent_context else None
+        try:
+            return tools.open_tracked(
+                store, path=body.path, agent_context=agent_ctx, author=body.author
+            )
+        except tools.ToolError as exc:
+            raise _tool_error_http(exc) from exc
+
+    @app.get(
+        "/sessions/{handle}/outline",
+        response_model=OutlineResponse,
+        tags=["tracked"],
+        dependencies=guard,
+        operation_id="getOutline",
+    )
+    def get_outline(
+        handle: str,
+        cursor: str | None = Query(default=None, description="Opaque pagination cursor."),
+        limit: int = Query(default=100, ge=1, le=500, description="Max entries per page."),
+    ) -> Any:
+        """Return a bounded, paginated outline of the document's paragraphs."""
+        try:
+            return tools.get_outline(store, handle=handle, cursor=cursor, limit=limit)
+        except tools.ToolError as exc:
+            raise _tool_error_http(exc) from exc
+        except SessionError as exc:
+            raise _unknown_handle_http(exc) from exc
+        except (ValueError, KeyError) as exc:
+            raise _value_error_http(exc) from exc
+
+    @app.post(
+        "/sessions/{handle}/edit",
+        response_model=EditResponse,
+        tags=["tracked"],
+        dependencies=guard,
+        operation_id="editSession",
+    )
+    def edit(handle: str, body: EditRequest) -> Any:
+        """Apply ONE small, intent-named tracked edit to a node and journal it."""
+        try:
+            return tools.edit(
+                store,
+                handle=handle,
+                op=body.op,
+                node_id=body.node_id,
+                before=body.before,
+                after=body.after,
+                anchor=body.anchor,
+                text=body.text,
+                style=body.style,
+                rationale=body.rationale,
+                prompt=body.prompt,
+                turn_id=body.turn_id,
+            )
+        except tools.ToolError as exc:
+            raise _tool_error_http(exc) from exc
+        except SessionError as exc:
+            raise _unknown_handle_http(exc) from exc
+        except (ValueError, KeyError) as exc:
+            raise _value_error_http(exc) from exc
+
+    @app.post(
+        "/sessions/{handle}/save",
+        response_model=SaveResponse,
+        tags=["tracked"],
+        dependencies=guard,
+        operation_id="saveSession",
+    )
+    def save(handle: str, body: SaveRequest) -> Any:
+        """Save the native-revisions .docx and report the tracked + .changex paths."""
+        try:
+            return tools.save_tracked(store, handle=handle, out=body.out)
+        except tools.ToolError as exc:
+            raise _tool_error_http(exc) from exc
+        except SessionError as exc:
+            raise _unknown_handle_http(exc) from exc
+        except (ValueError, KeyError) as exc:
+            raise _value_error_http(exc) from exc
+
+    @app.get(
+        "/sessions/{handle}/changes",
+        response_model=ChangesResponse,
+        tags=["tracked"],
+        dependencies=guard,
+        operation_id="getChanges",
+    )
+    def get_changes(handle: str) -> Any:
+        """Return the structured provenance journal (active, non-reverted events)."""
+        try:
+            return tools.get_changes(store, handle=handle)
+        except tools.ToolError as exc:
+            raise _tool_error_http(exc) from exc
+        except SessionError as exc:
+            raise _unknown_handle_http(exc) from exc
+        except (ValueError, KeyError) as exc:
+            raise _value_error_http(exc) from exc
+
+    # -- passive ("native to any model") open / seal --------------------------
+
+    @app.post(
+        "/open",
+        response_model=PassiveOpenResponse,
+        tags=["passive"],
+        dependencies=guard,
+        operation_id="passiveOpen",
+    )
+    def passive_open(body: PassiveOpenRequest) -> PassiveOpenResponse:
+        """Snapshot a docx and write a pending passive journal (no tool calls).
+
+        Any tool may then edit the docx freely; call /seal to capture the delta.
+        """
+        try:
+            result = open_passive(body.docx, body.changex)
+        except (UnsafePathError, ValueError, OSError) as exc:
+            raise _value_error_http(exc) from exc
+        return PassiveOpenResponse(
+            changex_path=str(result.changex_path),
+            session_id=result.session_id,
+            baseline_sha256=result.baseline.sha256,
+            paragraphs=result.paragraphs,
+        )
+
+    @app.post(
+        "/seal",
+        response_model=PassiveSealResponse,
+        tags=["passive"],
+        dependencies=guard,
+        operation_id="passiveSeal",
+    )
+    def passive_seal(body: PassiveSealRequest) -> PassiveSealResponse:
+        """Diff the edited docx vs the stored baseline and append passive ops.
+
+        Returns honest, *degraded* counts: passive ops are observed net textual
+        deltas, not true provenance (agent/vendor/prompt are null).
+        """
+        try:
+            result = seal_passive(body.docx, body.changex)
+        except (UnsafePathError, ValueError, OSError) as exc:
+            raise _value_error_http(exc) from exc
+        return PassiveSealResponse(
+            changex_path=str(result.changex_path),
+            appended=result.appended,
+            replaced=result.replaced,
+            inserted=result.inserted,
+            deleted=result.deleted,
+            style_changed=result.style_changed,
+            baseline_unchanged=result.baseline_unchanged,
+            degraded=result.degraded,
+        )
+
+    # -- report (HTML/markdown redline) ---------------------------------------
+
+    @app.post(
+        "/report",
+        tags=["review"],
+        dependencies=guard,
+        operation_id="renderReport",
+        responses={200: {"content": {"text/html": {}, "application/json": {}}}},
+    )
+    def report(
+        handle: str | None = Query(
+            default=None,
+            description="An open tracked-session handle to render from.",
+        ),
+        changex: str | None = Query(
+            default=None,
+            description="OR a path to a .changex journal to render from (passive flow).",
+        ),
+        fmt: str = Query(default="html", description="'html' (default) or 'markdown'."),
+        raw: bool = Query(
+            default=False,
+            description="If true, return the report as text/html instead of JSON.",
+        ),
+    ) -> Any:
+        """Render an HTML/markdown redline of a session's or journal's changes.
+
+        Supply either an open ``handle`` (tracked flow) or a ``changex`` journal
+        path (passive flow). With ``raw=true`` and ``fmt=html`` the response is a
+        ready-to-display ``text/html`` page; otherwise a JSON ``{format, report}``.
+        """
+        fmt_norm = (fmt or "html").lower()
+        if fmt_norm not in ("html", "markdown"):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail={"error": "bad_format", "detail": "fmt must be 'html' or 'markdown'."},
+            )
+        if handle:
+            try:
+                payload = tools.render_review(store, handle=handle, fmt=fmt_norm)
+            except tools.ToolError as exc:
+                raise _tool_error_http(exc) from exc
+            except SessionError as exc:
+                raise _unknown_handle_http(exc) from exc
+            except (ValueError, KeyError) as exc:
+                raise _value_error_http(exc) from exc
+            rendered = str(payload["report"])
+        elif changex:
+            rendered = _render_from_journal(changex, fmt_norm)
+        else:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail={"error": "missing_argument", "detail": "pass either handle or changex."},
+            )
+        if raw and fmt_norm == "html":
+            return HTMLResponse(content=rendered)
+        return ReportResponse(format=fmt_norm, report=rendered)
+
+    return app
+
+
+def _render_from_journal(changex: str, fmt: str) -> str:
+    """Render a redline directly from a ``.changex`` journal path (passive flow)."""
+    try:
+        path = safe_path(changex, must_exist=True, allow_suffixes=(".changex", ".jsonl"))
+        journal = Journal.open(str(path))
+    except (UnsafePathError, ValueError, OSError) as exc:
+        raise _value_error_http(exc) from exc
+    events = journal.active_events()
+    return render_markdown(events) if fmt == "markdown" else render_html(events)
+
+
+def _unknown_handle_http(exc: SessionError) -> HTTPException:
+    """Map an unknown-handle error to a 404 so 'bad handle' != 'bad input'.
+
+    ``SessionStore.get`` raises :class:`SessionError` for an unknown handle; we
+    surface that as 404 with a structured payload distinct from a 400 input error.
+    """
+    return HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail={"error": "unknown_handle", "detail": str(exc)},
+    )
+
+
+#: Module-level app for ``uvicorn changex_api.app:app`` and the TestClient.
+app = create_app()

changex_api/models.py

@@ -0,0 +1,235 @@
+"""Pydantic request/response models for the ChangeX REST API.
+
+These are deliberately explicit (typed fields + descriptions + examples) because
+they ARE the OpenAPI schema that a ChatGPT custom GPT Action consumes at
+``/openapi.json``. Good field descriptions here become good tool affordances for
+any model calling the API. The semantics mirror the MCP tools 1:1
+(:mod:`changex_mcp.tools`): an ``op`` discriminator selects one small intent and
+its required payload, the exact ``before`` substring is always carried so the
+adapter can refuse blind overwrites, and an oversized op is rejected so the model
+splits the change.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+# The intent discriminators accepted by POST /sessions/{id}/edit, mirroring
+# ``changex_mcp.tools.EDIT_OPS``.
+EditOp = Literal["replace_text", "insert_text_after", "delete_text", "set_paragraph_style"]
+
+
+class AgentContext(BaseModel):
+    """Once-per-session declared identity (captured at open, never per-edit)."""
+
+    model: Optional[str] = Field(
+        default=None,
+        description="Your model id, e.g. 'claude-opus-4-8' or 'gpt-4o'. Recorded "
+        "once for the whole session and used as the Word revision author.",
+    )
+    vendor: Optional[str] = Field(
+        default=None, description="Your vendor, e.g. 'anthropic', 'openai', 'google'."
+    )
+
+
+# -- open / sessions ----------------------------------------------------------
+
+
+class OpenTrackedRequest(BaseModel):
+    """Body for POST /sessions — open a .docx for tracked editing."""
+
+    path: str = Field(
+        ...,
+        description="Absolute server-side path to the .docx to open for tracked editing.",
+        examples=["/data/contract.docx"],
+    )
+    agent_context: Optional[AgentContext] = Field(
+        default=None,
+        description="Optional once-per-session declared identity {model, vendor}.",
+    )
+    author: Optional[str] = Field(
+        default=None,
+        description="Override the Word revision author (defaults to the model id).",
+    )
+
+
+class OpenTrackedResponse(BaseModel):
+    """Session handle + summary returned by POST /sessions."""
+
+    handle: str = Field(..., description="Opaque session handle; pass it to every other call.")
+    session_id: str = Field(..., description="Stable journal session id (provenance identity).")
+    baseline_sha256: str = Field(..., description="SHA-256 of the opened baseline bytes.")
+    summary: dict[str, Any] = Field(
+        ..., description="{filename, paragraphs, agent, vendor, changex_path}."
+    )
+
+
+# -- outline ------------------------------------------------------------------
+
+
+class OutlineEntry(BaseModel):
+    """One paragraph node in a paginated outline page."""
+
+    node_id: str = Field(..., description="Durable node id; use it as an edit target.")
+    kind: str = Field(..., description="Node kind, e.g. 'paragraph'.")
+    preview: str = Field(..., description="Truncated text preview for discovery.")
+    style: Optional[str] = Field(default=None, description="Paragraph style name, if any.")
+
+
+class OutlineResponse(BaseModel):
+    """A bounded outline page plus the cursor to fetch the next one."""
+
+    nodes: list[OutlineEntry]
+    next_cursor: Optional[str] = Field(
+        default=None, description="Pass back as ?cursor= to page forward; null when done."
+    )
+    total: int = Field(..., description="Total paragraph count in the document.")
+
+
+# -- edit ---------------------------------------------------------------------
+
+
+class EditRequest(BaseModel):
+    """Body for POST /sessions/{id}/edit — apply ONE small intent-named edit.
+
+    ``op`` selects the intent and its required payload:
+
+    * ``replace_text``        — node_id, before (exact current text), after
+    * ``insert_text_after``   — node_id, anchor (exact text to insert after), text
+    * ``delete_text``         — node_id, before (exact text to delete)
+    * ``set_paragraph_style`` — node_id, style (new), before (current style name)
+    """
+
+    op: EditOp = Field(..., description="The edit intent.")
+    node_id: str = Field(..., description="Target node id (from the outline).")
+    before: Optional[str] = Field(
+        default=None,
+        description="Exact CURRENT text/style to match; the server refuses blind overwrites.",
+    )
+    after: Optional[str] = Field(default=None, description="Replacement text for replace_text.")
+    anchor: Optional[str] = Field(
+        default=None, description="Exact text to insert after (insert_text_after)."
+    )
+    text: Optional[str] = Field(default=None, description="Text to insert (insert_text_after).")
+    style: Optional[str] = Field(
+        default=None, description="New paragraph style (set_paragraph_style)."
+    )
+    rationale: Optional[str] = Field(default=None, description="Optional declared 'why'.")
+    prompt: Optional[str] = Field(
+        default=None, description="Optional prompt; hashed to prompt_sha256, never stored verbatim."
+    )
+    turn_id: Optional[str] = Field(default=None, description="Optional declared turn id.")
+
+
+class EditResponse(BaseModel):
+    """Result of one journaled edit."""
+
+    op_id: str = Field(..., description="Stable id of the journaled op.")
+    seq: int = Field(..., description="Server-assigned monotonic sequence number.")
+    node_id: str = Field(..., description="Resolved target node id.")
+    provenance_source: str = Field(..., description="'declared' or 'observed'.")
+
+
+# -- save / changes -----------------------------------------------------------
+
+
+class SaveRequest(BaseModel):
+    """Body for POST /sessions/{id}/save — render the tracked .docx."""
+
+    out: str = Field(
+        ...,
+        description="Absolute server-side .docx path to write the native-revisions file to.",
+        examples=["/data/contract.tracked.docx"],
+    )
+
+
+class SaveResponse(BaseModel):
+    """Paths + verification result after a save."""
+
+    tracked_path: str
+    changex_path: str
+    ops: int = Field(..., description="Number of active (non-reverted) ops written.")
+    verified: bool = Field(..., description="Whether the journal hash-chain verified.")
+
+
+class ChangesResponse(BaseModel):
+    """The structured provenance journal (active, non-reverted events)."""
+
+    session_id: str
+    events: list[dict[str, Any]]
+    count: int
+    verified: bool
+
+
+# -- passive open / seal ------------------------------------------------------
+
+
+class PassiveOpenRequest(BaseModel):
+    """Body for POST /open — start a passive (no-tool-calling) capture session."""
+
+    docx: str = Field(..., description="Absolute path to the .docx to snapshot.")
+    changex: Optional[str] = Field(
+        default=None, description="Optional sidecar journal path (.changex/.jsonl)."
+    )
+
+
+class PassiveOpenResponse(BaseModel):
+    """Outcome of POST /open."""
+
+    changex_path: str
+    session_id: str
+    baseline_sha256: str
+    paragraphs: int
+
+
+class PassiveSealRequest(BaseModel):
+    """Body for POST /seal — diff the edited docx vs the stored baseline."""
+
+    docx: str = Field(..., description="Absolute path to the (now edited) .docx.")
+    changex: Optional[str] = Field(default=None, description="Optional sidecar journal path.")
+
+
+class PassiveSealResponse(BaseModel):
+    """Honest, degraded capture counts from a passive seal."""
+
+    changex_path: str
+    appended: int
+    replaced: int
+    inserted: int
+    deleted: int
+    style_changed: int
+    baseline_unchanged: bool
+    degraded: bool = Field(
+        default=True,
+        description="Always true: passive ops are observed net deltas, not true provenance.",
+    )
+
+
+# -- report -------------------------------------------------------------------
+
+
+class ReportResponse(BaseModel):
+    """A rendered HTML/markdown redline of a session's journal."""
+
+    format: str = Field(..., description="'html' or 'markdown'.")
+    report: str = Field(..., description="The rendered redline.")
+
+
+# -- shared -------------------------------------------------------------------
+
+
+class HealthResponse(BaseModel):
+    """Liveness probe payload."""
+
+    status: Literal["ok"] = "ok"
+    service: str = "changex-api"
+    version: str
+
+
+class ErrorResponse(BaseModel):
+    """Structured boundary error mirroring the MCP ToolError shape."""
+
+    error: str = Field(..., description="Stable machine-readable code, e.g. 'split_required'.")
+    detail: str = Field(..., description="Human/agent-facing instruction.")

changex_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: changex-api
+Version: 0.1.0
+Summary: ChangeX HTTP/REST API: a thin FastAPI wrapper over the changex-core spine so any app or model — local/offline LLMs, or a ChatGPT custom GPT Action consuming /openapi.json — can open, edit, save, and review tracked Word documents over HTTP.
+Author: ChangeX
+License: MIT
+License-File: LICENSE
+Keywords: actions,ai,docx,fastapi,llm,openapi,provenance,rest,track-changes
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.11
+Requires-Dist: changex-core>=0.1.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.27
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# changex-api
+
+A thin HTTP/REST API over the [ChangeX](https://github.com/ArioMoniri/changex)
+core spine, so **any** app or model can drive provenance-first tracked editing of
+Word documents over plain HTTP — a local/offline LLM with no function-calling, a
+`curl` script, or a **ChatGPT custom GPT Action** that imports the
+auto-generated OpenAPI schema.
+
+It wraps `changex-core` and reuses the exact MCP tool semantics
+(`changex-mcp`): an `op` discriminator selects one small intent, the exact
+`before` substring is always carried so blind overwrites are refused, and an
+oversized op is rejected so the model splits the change.
+
+## Run
+
+```bash
+# install (workspace) and launch on 127.0.0.1:8000
+uv sync
+changex-api                     # or: python -m changex_api
+# custom bind / port:
+changex-api --host 0.0.0.0 --port 9000   # non-local host REQUIRES a token:
+CHANGEX_API_TOKEN=secret changex-api --host 0.0.0.0
+```
+
+Bind is `127.0.0.1` by default. A non-local host is **refused** unless
+`CHANGEX_API_TOKEN` is set; when it is, every non-`/healthz` route requires
+`Authorization: Bearer <token>`.
+
+## Endpoints
+
+| Method & path | Purpose |
+|---|---|
+| `POST /sessions` | Open a `.docx` for tracked editing (returns a `handle`). |
+| `GET  /sessions/{handle}/outline` | Bounded, paginated paragraph outline (discover `node_id`s). |
+| `POST /sessions/{handle}/edit` | One small, intent-named tracked edit. |
+| `POST /sessions/{handle}/save` | Write the native-revisions `.docx` + `.changex` journal. |
+| `GET  /sessions/{handle}/changes` | The structured provenance journal. |
+| `POST /open` | Passive (no-tool-calling) capture: snapshot a docx. |
+| `POST /seal` | Diff the edited docx vs the baseline; append passive ops. |
+| `POST /report` | Render an HTML/markdown redline (by `handle` or `.changex` path). |
+| `GET  /healthz` | Liveness probe (never requires auth). |
+
+## OpenAPI / function-calling schemas
+
+FastAPI serves the schema at **`/openapi.json`** — that file IS the ChatGPT
+custom GPT Action schema; point a GPT's Action import at it. Static copies plus
+OpenAI/Gemini function-calling schemas live in the repo's `integrations/`:
+
+- `integrations/openapi.json` — the dumped OpenAPI 3.1 schema (ChatGPT Actions).
+- `integrations/openai-functions.json` — OpenAI `tools` format.
+- `integrations/gemini-functions.json` — Gemini `functionDeclarations` format.

changex_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+changex_api/__init__.py,sha256=2nNxP7Q1mZISpiNnCRvw_Wz9riodAwx9V8xcdfvfLvk,1026
+changex_api/__main__.py,sha256=Vnm08OzIjxoAsQjzGcKJ4K8CurqIFr-2X1ktovNd3A8,2489
+changex_api/app.py,sha256=ho0MUDaZa6p0u99c00Em905r3gefgr1G7ALWvmP9Dzk,16117
+changex_api/models.py,sha256=HwpUEIIiOm-iKx0q7BtNg1B0xTig2sarDnI7-WmxoIU,8474
+changex_api-0.1.0.dist-info/METADATA,sha256=YRS9U7UlqUVtAsNPidSPXRJ0KSPqSioKuOyLR0VW9XM,3425
+changex_api-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+changex_api-0.1.0.dist-info/entry_points.txt,sha256=LdyIM_hFucRbamN3wGvF_U7WBzUD3mMAbfrJm22dCa8,58
+changex_api-0.1.0.dist-info/licenses/LICENSE,sha256=5qBe8VP3umqM2WMYBYJ4B9tznqeKkjmIhXZ62pJ0038,1068
+changex_api-0.1.0.dist-info/RECORD,,

changex_api-0.1.0.dist-info/WHEEL

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

changex_api-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+changex-api = changex_api.__main__:main

changex_api-0.1.0.dist-info/licenses/LICENSE

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