Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

6.3 KB
Raw Blame
"""WebUI 会话任务、完整状态快照和同步输出工作的取消边界。"""

from __future__ import annotations

import asyncio
import json
from collections.abc import Callable
from dataclasses import dataclass, field
from pathlib import Path
from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar

from .status import STATUS_COMPLETED, STATUS_PREPARING_REQUEST, ParseStatusUpdate, StatusPanelState

if TYPE_CHECKING:
    from .artifacts import RunArtifacts

P = ParamSpec("P")
T = TypeVar("T")


@dataclass(frozen=True)
class ConversionInput:
    """描述一次转换输入,不依赖 Gradio 请求或组件。"""

    file_path: str | None
    tier_position: int | float
    page_range: str
    force_ocr: bool = False
    session_id: str = ""
    source_id: str = ""


@dataclass(frozen=True)
class PreviewPlan:
    """描述结果预览所需路径与占位状态,由界面层决定组件更新方式。"""

    preserve_source: bool
    pdf_path: Path | None = None
    image_path: Path | None = None
    show_ready_placeholder: bool = False


@dataclass(frozen=True)
class ConversionOutput:
    """保存已物化的转换输出,不保留解析语义树。"""

    artifacts: RunArtifacts
    html: str
    structured_json: str
    preview: PreviewPlan


@dataclass(frozen=True)
class ConversionSuccess:
    """表示解析及所有输出准备均已完成。"""

    output: ConversionOutput


@dataclass(frozen=True)
class ConversionFailure:
    """记录最终错误,由界面层保持既有失败响应格式。"""

    message: str


@dataclass(frozen=True)
class ConversionCancelled:
    """表示任务已失效且同步工作已退出,不再应用界面结果。"""


ConversionOutcome = ConversionSuccess | ConversionFailure | ConversionCancelled


@dataclass
class ConversionRun:
    """只保留当前任务的状态和素材路径,不在会话缓存中持有解析结果。"""

    run_id: str
    state: StatusPanelState = field(init=False)
    snapshot: str = ""
    cancelled: bool = False
    terminal: bool = False
    task: asyncio.Task[ConversionOutput] | None = None
    artifacts: dict[str, Any] | None = None

    def __post_init__(self) -> None:
        """使用浏览器或 API 分配的唯一标识初始化准备阶段。"""
        self.state = StatusPanelState(run_id=self.run_id)
        self.publish(STATUS_PREPARING_REQUEST)

    def publish(self, message: str | ParseStatusUpdate, *, at: float | None = None, final_failure: bool = False) -> None:
        """最终错误可补全已有失败快照,成功、取消和迟到通知仍受终态保护。"""
        text = message.message if isinstance(message, ParseStatusUpdate) else message
        replace_failure = final_failure and self.state.message.startswith("Failed:") and text.startswith("Failed:")
        if self.cancelled or (self.terminal and not replace_failure) or not self.state.append(message, at=at):
            return
        self.terminal = self.state.message == STATUS_COMPLETED or self.state.message.startswith("Failed:")
        self.snapshot = json.dumps(
            {
                "run_id": self.run_id,
                "sequence": self.state.sequence,
                "terminal": self.terminal,
                "html": self.state.render(),
            },
            ensure_ascii=False,
        )

    def cancel(self) -> asyncio.Task[ConversionOutput] | None:
        """立即失效界面回执,实际任务在同步工作退出后释放执行槽。"""
        self.cancelled = True
        self.artifacts = None
        if self.task is not None and not self.task.done():
            self.task.cancel()
        return self.task


class SessionConversions:
    """按 Gradio 会话隔离任务,并让所有实际解析共享一个执行槽。"""

    def __init__(self) -> None:
        """在构建 WebUI 时创建注册表,不在模块导入期间分配运行资源。"""
        self.runs: dict[str, ConversionRun] = {}
        self.revisions: dict[str, int] = {}
        self.slot = asyncio.Semaphore(1)

    def start(self, session: str, run_id: str, *, revision: int | None = None) -> ConversionRun | None:
        """拒绝晚到的旧提交,替换会话任务时先取消其后台工作。"""
        if revision is not None:
            if revision <= self.revisions.get(session, 0):
                return None
            self.revisions[session] = revision
        previous = self.runs.get(session)
        if previous is not None:
            previous.cancel()
        run = ConversionRun(run_id)
        self.runs[session] = run
        return run

    def current(self, session: str, run_id: str) -> ConversionRun | None:
        """只能读取当前会话仍有效的指定任务,避免跨任务状态混入。"""
        run = self.runs.get(session)
        return run if run is not None and run.run_id == run_id and not run.cancelled else None

    def cancel(self, session: str, run_id: str | None = None) -> asyncio.Task[ConversionOutput] | None:
        """按回执身份取消任务,迟到的文件切换请求不能取消新任务。"""
        run = self.runs.get(session)
        if run is None or (run_id is not None and run.run_id != run_id):
            return None
        self.runs.pop(session, None)
        return run.cancel()


async def await_task_completion(task: asyncio.Task[T]) -> T:
    """收到取消后仍等待实际工作退出,再传播取消以保持资源和槽位有效。"""
    cancelled = False
    while not task.done():
        try:
            await asyncio.shield(task)
        except asyncio.CancelledError:
            cancelled = True
        except Exception:
            break
    if cancelled:
        if not task.cancelled():
            task.exception()
        raise asyncio.CancelledError
    return task.result()


async def run_sync_output(function: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
    """同步输出线程不可强制取消,必须等它退出后才能释放外层执行槽。"""
    return await await_task_completion(asyncio.create_task(asyncio.to_thread(function, *args, **kwargs)))


__all__ = [
    "ConversionCancelled",
    "ConversionFailure",
    "ConversionInput",
    "ConversionOutcome",
    "ConversionOutput",
    "ConversionRun",
    "ConversionSuccess",
    "PreviewPlan",
    "SessionConversions",
    "await_task_completion",
    "run_sync_output",
]