AskPageAssessment

Description

AskPageAssessment answers two independent questions about every page that is read: what kind of page it is, and whether it carries welding callouts. Each page gets one vision call, and both answers come from that one look.

Werk24 interprets component drawings and assembly drawings. The other page types (architectural drawings, P&IDs, wiring diagrams, and anything else) are recognised so that you learn early that the rest of your asks will come back empty, instead of receiving an empty result with no explanation.

When to use

Classify first, then decide whether to continue. Send AskPageAssessment on its own (or together with AskDocumentProfile) and request the extraction asks only for documents whose pages are COMPONENT_DRAWING or ASSEMBLY_DRAWING. Asked without any extraction ask, the request finishes once the pages have been assessed.
Explain an empty result. When a request for features comes back empty, page_type tells you whether the page was a wiring diagram or a cover sheet rather than a drawing Werk24 failed to read.
Route documents with welding. has_welding_symbols flags pages that carry welding callouts.

Kept apart from AskDocumentProfile on purpose

AskDocumentProfile is read off the file and arrives almost immediately. This ask waits on a model, so it arrives well after the profile and roughly alongside the extraction results. Asking for both gets you the profile straight away and this one later, rather than making the fast answer wait for the slow one.

How to read the response:

pages has one entry per page that was read, in reading order. A request that names particular pages gets those pages, and a page limit truncates the rest, so its length can differ from ResponseDocumentProfile.page_count, which counts the whole document.
A null entry means that page could not be assessed. That is not the same as a page assessed as MISCELLANEOUS without welding; do not read it as "no welding".
has_welding_symbols reports presence only, never which weld. It is answered false when unsure, so a true is worth more than a false.
description is one short sentence saying what the page shows. It is most useful when page_type is MISCELLANEOUS, which on its own only tells you the page is none of the named types.
New page types may be added as the classification improves. Treat a value you do not recognise as MISCELLANEOUS rather than as an error; the Python client already does.

Example Usage

from werk24 import AskPageAssessment, AskType, PageType, read_example_drawing

results = read_example_drawing([AskPageAssessment()])

assessment = results[AskType.PAGE_ASSESSMENT][0].payload_dict
for index, page in enumerate(assessment.pages):
    if page is None:
        print(index, "could not be assessed")
    elif page.page_type in (PageType.COMPONENT_DRAWING, PageType.ASSEMBLY_DRAWING):
        print(index, "will be interpreted:", page.description)
    else:
        print(index, "will come back empty:", page.page_type.value, page.description)

ResponsePageAssessment

Bases: Response

What each page of the document is, and whether it shows welding.

One entry per page we were asked to read, in the order we read them, which is not necessarily the order they appear in the file: a request that names particular pages gets those pages, and a page limit truncates the rest. ResponseDocumentProfile.page_count reports the length of the whole document, so the two legitimately disagree.

A None entry means that page could not be assessed, which is not the same as a page assessed as ordinary. Do not read it as "no welding".

This response waits on a model, so it arrives well after ResponseDocumentProfile and roughly alongside the extraction results.

PARAMETER	DESCRIPTION
`ask_version`	TYPE: `Literal['v2']` DEFAULT: `'v2'`
`ask_type`	TYPE: `Literal[<AskType.PAGE_ASSESSMENT: 'PAGE_ASSESSMENT'>]` DEFAULT: `<AskType.PAGE_ASSESSMENT: 'PAGE_ASSESSMENT'>`
`pages`	One entry per page read, in reading order. None where the page could not be assessed at all, which is distinct from a page assessed as MISCELLANEOUS with no welding. TYPE: `List[PageAssessment \| None]` DEFAULT: `<dynamic>`

Source code in werk24/models/v2/responses.py

class ResponsePageAssessment(Response):
    """
    What each page of the document is, and whether it shows welding.

    One entry per page **we were asked to read**, in the order we read them,
    which is not necessarily the order they appear in the file: a request that
    names particular pages gets those pages, and a page limit truncates the
    rest. `ResponseDocumentProfile.page_count` reports the length of the whole
    document, so the two legitimately disagree.

    A `None` entry means that page could not be assessed, which is not the
    same as a page assessed as ordinary. Do not read it as "no welding".

    This response waits on a model, so it arrives well after
    `ResponseDocumentProfile` and roughly alongside the extraction results.
    """

    ask_type: Literal[AskType.PAGE_ASSESSMENT] = AskType.PAGE_ASSESSMENT

    pages: List[Optional[PageAssessment]] = Field(
        default_factory=list,
        description=(
            "One entry per page read, in reading order. None where the page "
            "could not be assessed at all, which is distinct from a page "
            "assessed as MISCELLANEOUS with no welding."
        ),
    )

PageAssessment

Bases: BaseModel

What one page turned out to be, and whether it shows welding.

Two answers from a single look at the page, kept in one object because they were made together and kept as separate fields because they are independent: a page nobody could categorise may still plainly carry weld callouts, so an unhelpful page_type says nothing about has_welding_symbols.

PARAMETER	DESCRIPTION
`page_type`	What kind of page this is. COMPONENT_DRAWING and ASSEMBLY_DRAWING are interpreted; the others are recognised so you learn early that the rest of your asks will come back empty. MISCELLANEOUS also covers a page we looked at and could not place. TYPE: `PageType` DEFAULT: `<PageType.MISCELLANEOUS: 'MISCELLANEOUS'>`
`has_welding_symbols`	Whether the page carries welding callouts. Presence only, never which weld: the symbol's flag and its lettering are too small to read reliably at the resolution this is judged at, while the callout as a whole is not. Answered False when unsure, so a True is worth more than a False. TYPE: `bool` DEFAULT: `False`
`description`	One short sentence saying what this page shows, in plain language. Most useful when `page_type` is MISCELLANEOUS, which on its own tells you only that the page is not one of the categories: the sentence is what tells you whether you sent a cover sheet, a specification, a photograph or something we simply have no name for yet. Empty when no description was produced. Written from a downscaled image, so it describes what the page IS and never quotes a dimension or a tolerance off it. TYPE: `str` DEFAULT: `''`

Source code in werk24/models/v2/models.py

class PageAssessment(BaseModel):
    """What one page turned out to be, and whether it shows welding.

    Two answers from a single look at the page, kept in one object because
    they were made together and kept as separate fields because they are
    independent: a page nobody could categorise may still plainly carry weld
    callouts, so an unhelpful `page_type` says nothing about
    `has_welding_symbols`.
    """

    page_type: PageType = Field(
        PageType.MISCELLANEOUS,
        description=(
            "What kind of page this is. COMPONENT_DRAWING and "
            "ASSEMBLY_DRAWING are interpreted; the others are recognised so "
            "you learn early that the rest of your asks will come back empty. "
            "MISCELLANEOUS also covers a page we looked at and could not "
            "place."
        ),
    )
    has_welding_symbols: bool = Field(
        False,
        description=(
            "Whether the page carries welding callouts. Presence only, never "
            "which weld: the symbol's flag and its lettering are too small to "
            "read reliably at the resolution this is judged at, while the "
            "callout as a whole is not. Answered False when unsure, so a True "
            "is worth more than a False."
        ),
    )
    description: str = Field(
        "",
        description=(
            "One short sentence saying what this page shows, in plain "
            "language. Most useful when `page_type` is MISCELLANEOUS, which "
            "on its own tells you only that the page is not one of the "
            "categories: the sentence is what tells you whether you sent a "
            "cover sheet, a specification, a photograph or something we "
            "simply have no name for yet. Empty when no description was "
            "produced. Written from a downscaled image, so it describes what "
            "the page IS and never quotes a dimension or a tolerance off it."
        ),
        examples=[
            "A dimensioned drawing of a turned shaft with a keyway.",
            "A cover sheet listing the drawings in this package.",
            "A photograph of a printed drawing, taken at an angle.",
        ],
    )

Example Response

One response for the whole document, here a two-page document whose second page is a cover sheet:

{
    "ask_version": "v2",
    "ask_type": "PAGE_ASSESSMENT",
    "pages": [
        {
            "page_type": "COMPONENT_DRAWING",
            "has_welding_symbols": false,
            "description": "A dimensioned drawing of a turned shaft with a keyway."
        },
        {
            "page_type": "MISCELLANEOUS",
            "has_welding_symbols": false,
            "description": "A cover sheet listing the drawings in this package."
        }
    ]
}