Skip to content

ontocast.tool.chunk.section_llm

LLM section tier: one call labels the document's outline, as weak votes.

The model is shown the document as an ordered list of regions: each headed section once (its heading line and the opening of its text), and each segment of unheaded text on its own. It returns one label per region, chosen from the schema's labels and their descriptions. Every segment of a region receives that label as weak evidence, so the model decides only where no other tier spoke; where it disagrees with another tier, the disagreement is kept in the evidence. A long outline is sent in consecutive windows. A failed call costs the votes of its window and nothing else.

Attributes

EXCERPT_MAX_CHARS = 300 module-attribute

__all__ = ['EXCERPT_MAX_CHARS', 'OutlineLabels', 'OutlineRegion', 'RegionLabel', 'llm_label_outline', 'outline_regions', 'text_excerpt'] module-attribute

logger = logging.getLogger(__name__) module-attribute

Classes

OutlineLabels

Bases: BasePydanticModel

The model's labels for the numbered regions of one outline window.

Source code in ontocast/tool/chunk/section_llm.py
class OutlineLabels(BasePydanticModel):
    """The model's labels for the numbered regions of one outline window."""

    labels: list[RegionLabel] = Field(default_factory=list)

Attributes

labels = Field(default_factory=list) class-attribute instance-attribute

OutlineRegion dataclass

One region shown to the model and the segments its label applies to.

Source code in ontocast/tool/chunk/section_llm.py
@dataclass(frozen=True)
class OutlineRegion:
    """One region shown to the model and the segments its label applies to."""

    excerpt: str
    segments: tuple[int, ...]

Attributes

excerpt instance-attribute
segments instance-attribute

Methods:

__init__(excerpt, segments)

RegionLabel

Bases: BasePydanticModel

The section label the model gives one numbered region.

Source code in ontocast/tool/chunk/section_llm.py
class RegionLabel(BasePydanticModel):
    """The section label the model gives one numbered region."""

    index: int = Field(description="Number of the region, as given in the prompt")
    label: str | None = Field(
        default=None,
        description="One of the listed section labels, or null if none fits",
    )

Attributes

index = Field(description='Number of the region, as given in the prompt') class-attribute instance-attribute
label = Field(default=None, description='One of the listed section labels, or null if none fits') class-attribute instance-attribute

Functions:

llm_label_outline(segments, tools, schema, *, document_type_hint=None, window=40) async

Add the model's vote to every segment and decide again (mutates in place).

Parameters:

Name Type Description Default
segments list[PrepareSegment]

Prepare segments, in document order.

required
tools ToolBox

ToolBox providing the LLM.

required
schema SectionLabelSchema

The schema the document is typed against; labels outside it are discarded.

required
document_type_hint str | None

Free-text document type, passed to the prompt.

None
window int

Regions per call.

40

Returns:

Type Description
OutlineLabelReport

How many windows were sent and which failed.

Source code in ontocast/tool/chunk/section_llm.py
async def llm_label_outline(
    segments: list[PrepareSegment],
    tools: ToolBox,
    schema: SectionLabelSchema,
    *,
    document_type_hint: str | None = None,
    window: int = 40,
) -> OutlineLabelReport:
    """Add the model's vote to every segment and decide again (mutates in place).

    Args:
        segments: Prepare segments, in document order.
        tools: ToolBox providing the LLM.
        schema: The schema the document is typed against; labels outside it
            are discarded.
        document_type_hint: Free-text document type, passed to the prompt.
        window: Regions per call.

    Returns:
        How many windows were sent and which failed.
    """
    regions = outline_regions(segments)
    size = max(1, window)
    voted = 0
    report = OutlineLabelReport()
    for start in range(0, len(regions), size):
        chunk = regions[start : start + size]
        report.windows += 1
        labels = await _label_window(chunk, tools, schema, document_type_hint)
        if isinstance(labels, Exception):
            report.windows_failed += 1
            name = type(labels).__name__
            report.errors[name] = report.errors.get(name, 0) + 1
            continue
        for position, label in labels.items():
            for index in chunk[position].segments:
                segment = segments[index]
                segment.evidence.append(
                    LabelEvidence(
                        label=label,
                        source=SectionLabelSource.LLM,
                        strength=LabelStrength.WEAK,
                    )
                )
                assign(segment)
                voted += 1
    if voted:
        logger.debug(
            "Outline labeling voted on %s segment(s) in %s region(s)",
            voted,
            len(regions),
        )
    return report

outline_regions(segments)

The document's regions in order: each headed section once, unheaded segments each.

Source code in ontocast/tool/chunk/section_llm.py
def outline_regions(segments: list[PrepareSegment]) -> list[OutlineRegion]:
    """The document's regions in order: each headed section once, unheaded segments each."""
    regions: list[OutlineRegion] = []
    position: dict[int, int] = {}
    for index, segment in enumerate(segments):
        if segment.region is None:
            excerpt = text_excerpt(segment.text)
            if excerpt:
                regions.append(OutlineRegion(excerpt=excerpt, segments=(index,)))
            continue
        at = position.get(segment.region.index)
        if at is None:
            position[segment.region.index] = len(regions)
            regions.append(
                OutlineRegion(excerpt=segment.region.excerpt, segments=(index,))
            )
            continue
        region = regions[at]
        regions[at] = OutlineRegion(
            excerpt=region.excerpt, segments=(*region.segments, index)
        )
    return regions

text_excerpt(text, limit=EXCERPT_MAX_CHARS)

The opening of text: its first line kept, the rest on one line.

A heading keeps its own line, so the model sees what names the region and what follows it as distinct.

Source code in ontocast/tool/chunk/section_llm.py
def text_excerpt(text: str, limit: int = EXCERPT_MAX_CHARS) -> str:
    """The opening of ``text``: its first line kept, the rest on one line.

    A heading keeps its own line, so the model sees what names the region and
    what follows it as distinct.
    """
    stripped = text.strip()
    if not stripped:
        return ""
    first, _, rest = stripped.partition("\n")
    body = " ".join(rest.split())
    excerpt = f"{first.strip()}\n{body}" if body else first.strip()
    return excerpt[:limit].rstrip()