doc-agent / docagent /agent.py
Sanidhya Ravi
Turn the TrOCR demo into an agentic document pipeline
5eb40dc
Raw History Blame Contribute Delete
4.17 kB
"""Top-level orchestration: one document in, artifacts and a reply out.
The whole run -- perception, routing or planning, and export -- happens inside
a *single* ``@spaces.GPU`` session. One session per tool would multiply queue
waits and burn the visitor quota on scheduling rather than work.
"""
from __future__ import annotations
import logging
import os
import tempfile
import time
from typing import Any, Iterator, Sequence
from .export import build_bundle
from .ingest import load
from .models import estimate_duration, gpu_task
from .state import Document
from .tools import perceive
log = logging.getLogger("docagent.agent")
__all__ = ["run", "run_stream", "process"]
def _finalise(doc: Document, reply: str) -> str:
"""Always write the bundle, then add anything the user should check.
This is the chosen low-confidence policy: never block, never fail, always
hand back artifacts plus an explicit note about what was uncertain.
"""
build_bundle(doc, doc.workdir)
from .export.bundle import LOW_CONFIDENCE
concerns = [
"p%d read as %s (confidence %.2f)" % (p.page_no, p.kind.value, p.kind_confidence)
for p in doc.pages
if 0.0 < p.kind_confidence < LOW_CONFIDENCE
]
parts = [reply.strip()] if reply.strip() else []
if concerns:
parts.append("Worth checking: " + "; ".join(concerns) + ".")
if doc.warnings:
parts.append("Notes: " + "; ".join(doc.warnings) + ".")
return " ".join(parts)
def _agent_events(doc: Document) -> Iterator[dict]:
"""Perceive, then either route deterministically or hand off to the planner."""
from .planner import iter_plan
from .router import route
started = time.time()
perceive(doc)
yield {"type": "step", "tool": "perceive", "args": {},
"observation": doc.brief(preview_chars=80)}
reply = route(doc)
if reply is not None:
yield {"type": "step", "tool": "router", "args": {},
"observation": "deterministic plan (no planner tokens used)"}
yield {"type": "final", "message": reply}
else:
yield from iter_plan(doc)
log.info("agent run finished in %.1fs", time.time() - started)
@gpu_task(duration=estimate_duration)
def _gpu_phase(doc: Document) -> list[dict]:
"""Everything that may touch a model, and nothing else.
Returns a list rather than a generator because a ZeroGPU function has to
complete inside its session; the caller replays the events afterwards.
Export deliberately happens *outside* this function. Writing a workbook, a
Word file and two PDFs takes seconds of pure CPU, and inside the session
every one of those seconds would be billed against the visitor's GPU quota.
"""
return list(_agent_events(doc))
def _reply_from(events: list[dict]) -> str:
return next(
(e.get("message", "") for e in reversed(events) if e.get("type") == "final"), ""
)
def run(doc: Document) -> str:
"""Process an already-ingested document. Returns the user-facing reply."""
return _finalise(doc, _reply_from(_gpu_phase(doc)))
def run_stream(doc: Document) -> list[dict]:
"""Same as :func:`run`, but returns the full event list for the UI trace."""
events = _gpu_phase(doc)
events.append({"type": "result", "message": _finalise(doc, _reply_from(events))})
return events
def process(
sources: Any | Sequence[Any],
instruction: str = "",
*,
dpi: int = 200,
workdir: str | os.PathLike | None = None,
) -> Document:
"""Ingest and process in one call, returning the finished Document.
Artifacts are on ``doc.artifacts`` and the user-facing sentence is the last
``reply`` entry of ``doc.trace``. Callers that only want that sentence can
call :func:`load` and :func:`run` directly instead.
"""
work = workdir or tempfile.mkdtemp(prefix="docagent_")
doc = load(sources, instruction=instruction, dpi=dpi, workdir=work)
doc.workdir = str(work)
if not doc.pages:
doc.warnings.append("no readable pages were found in the input")
return doc
reply = run(doc)
doc.log("reply", {}, reply)
return doc