Skip to content

ontocast.tool.chunk.segment

Mutable text segments during chunk preparation (before sizing).

Attributes

logger = logging.getLogger(__name__) module-attribute

Classes

PrepareSegment dataclass

One logical segment prior to min/max sizing.

evidence holds every tier's vote; the label, its source and its strength are decided from it (:func:ontocast.tool.chunk.assignment.assign). With no evidence, a source of OUTLINE_UNRESOLVED marks a section the outline saw but could not name.

Source code in ontocast/tool/chunk/segment.py
@dataclass
class PrepareSegment:
    """One logical segment prior to min/max sizing.

    ``evidence`` holds every tier's vote; the label, its source and its
    strength are decided from it (:func:`ontocast.tool.chunk.assignment.assign`).
    With no evidence, a source of ``OUTLINE_UNRESOLVED`` marks a section the
    outline saw but could not name.
    """

    text: str
    headings: list[str] | None = None
    section_label: str | None = None
    section_label_source: SectionLabelSource | None = None
    section_label_strength: LabelStrength | None = None
    evidence: list[LabelEvidence] = field(default_factory=list)
    region: SectionRegion | None = None

Attributes

evidence = field(default_factory=list) class-attribute instance-attribute
headings = None class-attribute instance-attribute
region = None class-attribute instance-attribute
section_label = None class-attribute instance-attribute
section_label_source = None class-attribute instance-attribute
section_label_strength = None class-attribute instance-attribute
text instance-attribute

Methods:

__init__(text, headings=None, section_label=None, section_label_source=None, section_label_strength=None, evidence=list(), region=None)

SectionRegion dataclass

The headed section a segment belongs to, as the model is shown it.

Every segment of one headed section shares one region and so one model vote. Unheaded text has no region: each such segment is shown on its own.

Attributes:

Name Type Description
index int

Position of the section in the document's section blocks.

excerpt str

The heading line and the opening of the section's text.

Source code in ontocast/tool/chunk/segment.py
@dataclass(frozen=True)
class SectionRegion:
    """The headed section a segment belongs to, as the model is shown it.

    Every segment of one headed section shares one region and so one model
    vote. Unheaded text has no region: each such segment is shown on its own.

    Attributes:
        index: Position of the section in the document's section blocks.
        excerpt: The heading line and the opening of the section's text.
    """

    index: int
    excerpt: str

Attributes

excerpt instance-attribute
index instance-attribute

Methods:

__init__(index, excerpt)

Functions:

coalesce_small_segments_right(segments, min_chars, schema)

Merge undersized segments into the right neighbor; otherwise into the left.

Source code in ontocast/tool/chunk/segment.py
def coalesce_small_segments_right(
    segments: list[PrepareSegment],
    min_chars: int,
    schema: SectionLabelSchema,
) -> list[PrepareSegment]:
    """Merge undersized segments into the right neighbor; otherwise into the left."""
    if min_chars <= 0 or len(segments) <= 1:
        return segments

    merge_count = 0
    index = 0
    while index < len(segments):
        if (
            is_abstract_exempt(segments[index], schema)
            or _effective_length(segments[index], schema) >= min_chars
        ):
            index += 1
            continue
        merged = False
        if index + 1 < len(segments) and not segments_differ_in_structure(
            segments[index], segments[index + 1], schema
        ):
            segments[index + 1] = merge_into_right(segments[index], segments[index + 1])
            del segments[index]
            merge_count += 1
            merged = True
        elif _can_merge_small_into_left(segments, index, schema):
            segments[index - 1] = merge_into_left(segments[index - 1], segments[index])
            del segments[index]
            merge_count += 1
            index -= 1
            merged = True
        if not merged:
            index += 1

    if merge_count:
        logger.debug(
            "Coalesced %s undersized segment(s) (min_chars=%s)",
            merge_count,
            min_chars,
        )
    return segments

is_abstract_exempt(segment, schema)

Preserve short abstract segments instead of merging them into neighbors.

Source code in ontocast/tool/chunk/segment.py
def is_abstract_exempt(segment: PrepareSegment, schema: SectionLabelSchema) -> bool:
    """Preserve short abstract segments instead of merging them into neighbors."""
    first_line = _first_non_empty_line(segment.text)
    if first_line and match_heading_line(first_line, schema) == "abstract":
        return True
    if segment.headings:
        for heading in segment.headings:
            if match_heading_line(heading, schema) == "abstract":
                return True
    return False

merge_into_left(left, right)

Source code in ontocast/tool/chunk/segment.py
def merge_into_left(left: PrepareSegment, right: PrepareSegment) -> PrepareSegment:
    left_text = left.text.strip()
    right_text = right.text.strip()
    combined_text = (
        f"{left_text}{DEFAULT_PART_SEPARATOR}{right_text}"
        if left_text and right_text
        else left_text or right_text
    )
    winner = left if left.section_label is not None else right
    return PrepareSegment(
        text=combined_text,
        headings=left.headings or right.headings,
        section_label=winner.section_label,
        section_label_source=winner.section_label_source,
        section_label_strength=winner.section_label_strength,
        evidence=list(winner.evidence),
        region=winner.region,
    )

merge_into_right(left, right)

Source code in ontocast/tool/chunk/segment.py
def merge_into_right(left: PrepareSegment, right: PrepareSegment) -> PrepareSegment:
    left_text = left.text.strip()
    right_text = right.text.strip()
    combined_text = (
        f"{left_text}{DEFAULT_PART_SEPARATOR}{right_text}"
        if left_text and right_text
        else left_text or right_text
    )
    winner = right if right.section_label is not None else left
    return PrepareSegment(
        text=combined_text,
        headings=right.headings or left.headings,
        section_label=winner.section_label,
        section_label_source=winner.section_label_source,
        section_label_strength=winner.section_label_strength,
        evidence=list(winner.evidence),
        region=winner.region,
    )

segments_differ_in_structure(left, right, schema)

True when merging would join distinct document sections.

Source code in ontocast/tool/chunk/segment.py
def segments_differ_in_structure(
    left: PrepareSegment,
    right: PrepareSegment,
    schema: SectionLabelSchema,
) -> bool:
    """True when merging would join distinct document sections."""
    if starts_with_section_heading(right, schema):
        return True
    if left.headings and right.headings and left.headings != right.headings:
        return True
    return False

starts_with_section_heading(segment, schema)

True when the segment opens with a recognised section heading line.

Source code in ontocast/tool/chunk/segment.py
def starts_with_section_heading(
    segment: PrepareSegment, schema: SectionLabelSchema
) -> bool:
    """True when the segment opens with a recognised section heading line."""
    first_line = _first_non_empty_line(segment.text)
    return bool(first_line and match_heading_line(first_line, schema) is not None)