paces 0.0.22__tar.gz → 0.0.24__tar.gz

{paces-0.0.22 → paces-0.0.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.22
+Version: 0.0.24
 Summary: Turn instructional media into structured, interactive learning material
 Project-URL: Homepage, https://github.com/thorwhalen/paces
 Project-URL: Repository, https://github.com/thorwhalen/paces

{paces-0.0.22 → paces-0.0.24}/paces/corrections.py

@@ -42,21 +42,20 @@ from dataclasses import dataclass
 from typing import Literal, get_args
 
 from paces.model import decimal_str
-from paces.segmentation import (
+from paces.segmentation import (  # noqa: F401 — TIME_PLACES/time_str re-exported
     DFLT_EXPLICIT_CONFIDENCE,
+    TIME_PLACES,
     SegStep,
     Segmentation,
     Span,
+    time_str,
 )
+from paces.segmentation import edges as _edges
+from paces.segmentation import overlaps as _overlaps
 
 Verb = Literal["pin", "forbid", "absent", "split", "merge"]
 VERBS: tuple[str, ...] = get_args(Verb)
 
-#: Decimal places a correction's times keep: milliseconds, the wire's
-#: resolution. Times are rounded to it at construction, so ``to_wire`` →
-#: ``from_wire`` is lossless (``decimal_str`` writes exactly this many).
-TIME_PLACES = 3
-
 #: How far a ``merge`` time may sit from the boundary it means. A human taps
 #: approximately; the machine finds the cut (``docs/alignment/07 §7.3`` step 3
 #: snaps taps within ±1.5 s).
@@ -69,6 +68,8 @@ DFLT_MIN_STEP_S = 0.25
 
 def _to_ms(value, *, what: str) -> float:
     """A finite time rounded to :data:`TIME_PLACES`, or a ``ValueError``."""
+    if isinstance(value, bool):  # True is 1.0 to float(); never a time
+        raise ValueError(f"{what} must be a time in seconds, got {value!r}")
     try:
         t = float(value)
     except (TypeError, ValueError):
@@ -102,6 +103,18 @@ class Correction:
     reason: str = ""
 
     def __post_init__(self):
+        for name in ("author", "at", "reason"):
+            if not isinstance(getattr(self, name), str):
+                raise ValueError(
+                    f"{name} must be a string, got {getattr(self, name)!r}"
+                )
+        for name in ("step_id", "media_key"):
+            if getattr(self, name) is not None and not isinstance(
+                getattr(self, name), str
+            ):
+                raise ValueError(
+                    f"{name} must be a string or None, got {getattr(self, name)!r}"
+                )
         if self.verb not in VERBS:
             raise ValueError(f"unknown verb {self.verb!r}; expected one of {VERBS}")
         object.__setattr__(self, "anchor_t", _to_ms(self.anchor_t, what="anchor_t"))
@@ -177,16 +190,6 @@ _WIRE_KEYS = {
 _REQUIRED_WIRE_KEYS = ("verb", "anchorT")
 
 
-def time_str(t: float) -> str:
-    """A time as paces' millisecond wire decimal — the one formatter every
-    corrections producer shares (the ask page's ``timeStr`` mirrors it).
-
-    >>> time_str(95.80000001), time_str(10.0625)  # exact binary ties round half-even
-    ('95.8', '10.062')
-    """
-    return decimal_str(t, places=TIME_PLACES)
-
-
 def to_wire(correction: Correction) -> dict:
     """A JSON-ready dict: camelCase keys, times as decimal strings, defaults omitted."""
     wire: dict = {"verb": correction.verb, "anchorT": time_str(correction.anchor_t)}
@@ -296,9 +299,11 @@ def replay(
     against the *final* placement: ``satisfied: forbid@<t>``, or
     ``correction-unenforced`` — moving a step elsewhere needs a solver, which
     replay is not. A pin that clips a child step out of existence says so
-    (``correction-clipped``). A last consistency pass flags
-    (``inconsistent:``) any empty span, any overlap between steps, and any
-    step edge missing from ``boundaries``.
+    (``correction-clipped``). Checking the result is not replay's job:
+    :func:`paces.segmenters.segment` runs
+    :func:`~paces.segmentation.inconsistencies` on every segmentation. A log
+    in which no correction edits the cut set leaves ``boundaries`` exactly as
+    given (duplicates included); once one does, they are rebuilt from it.
 
     >>> seg = Segmentation(steps=(SegStep(id="a", spans=((0.0, 10.0),)),),
     ...                    boundaries=(0.0, 10.0))
@@ -316,14 +321,18 @@ def replay(
         seen_ids=frozenset(step.id for step in seg.steps),
     )
     outcomes: list = []
+    cuts_touched = False  # once a correction edits the cut set, it is rebuilt
     for correction in normalize_corrections(corrections):
+        before = state.boundaries
         state, outcome = _APPLY[correction.verb](state, correction, options)
+        cuts_touched = cuts_touched or state.boundaries != before
         outcomes.append(outcome)
-    flags = tuple(_final_flags(state.steps, outcomes)) + _inconsistencies(state)
+    flags = tuple(_final_flags(state.steps, outcomes))
+    unchanged = not cuts_touched
     return dataclasses.replace(
         seg,
         steps=state.steps,
-        boundaries=tuple(sorted(state.boundaries)),
+        boundaries=seg.boundaries if unchanged else tuple(sorted(state.boundaries)),
         flags=seg.flags + flags,
     )
 
@@ -351,15 +360,6 @@ def _edges_at(steps: Sequence[SegStep], t: float, side: int) -> list[tuple[int,
     ]
 
 
-def _edges(steps: Iterable[SegStep]) -> set[float]:
-    return {t for step in steps for span in step.spans for t in span}
-
-
-def _overlaps(a: Span, b: Span) -> bool:
-    """True when the two spans share a positive length of time."""
-    return max(a[0], b[0]) < min(a[1], b[1])
-
-
 def _falls_in(child: SegStep, span: Span) -> bool:
     """A child belongs to the parent span its first span starts in."""
     return bool(child.spans) and span[0] <= child.spans[0][0] < span[1]
@@ -681,34 +681,3 @@ def _final_flags(steps: Sequence[SegStep], outcomes: Iterable) -> Iterable[str]:
             yield _forbid_flag(steps, outcome)
         else:
             yield from outcome
-
-
-def _inconsistencies(state: _State) -> tuple[str, ...]:
-    """What no segmentation may contain, flagged rather than repaired: empty
-    spans, spans of different steps that overlap, and step edges missing from
-    ``boundaries``."""
-    spans = sorted((span, step.id) for step in state.steps for span in step.spans)
-    flags = [
-        f"inconsistent: step {step_id!r} has an empty span at {time_str(span[0])}"
-        for span, step_id in spans
-        if span[0] >= span[1]
-    ]
-    flags += [
-        f"inconsistent: steps {a_id!r} and {b_id!r} overlap "
-        f"({time_str(max(a[0], b[0]))}–{time_str(min(a[1], b[1]))})"
-        for k, (a, a_id) in enumerate(spans)
-        for b, b_id in spans[k + 1 :]
-        if a_id != b_id and _overlaps(a, b)
-    ]
-    flags += [
-        f"inconsistent: child {child.id!r} of {step.id!r} lies outside its parent"
-        for step in state.steps
-        for child in step.children
-        for span in child.spans
-        if not any(p[0] <= span[0] and span[1] <= p[1] for p in step.spans)
-    ]
-    missing = sorted(_edges(state.steps) - state.boundaries)
-    if missing:
-        listed = ", ".join(time_str(t) for t in missing)
-        flags.append(f"inconsistent: step edges not in boundaries: {listed}")
-    return tuple(flags)

paces-0.0.24/paces/segmentation.py

@@ -0,0 +1,169 @@
+"""What a segmenter returns: :class:`Segmentation`, its :class:`SegStep` records and
+the ``Span`` they cover — the analysis-result types, with nothing else.
+
+They live apart from :mod:`paces.segmenters` (the registry and the
+``segment()`` facade) so a module that only consumes or reshapes a result —
+:mod:`paces.corrections`, :mod:`paces.projection`, :mod:`paces.ask`, the
+evidence layer — depends on the types and not on the facade, and the facade
+can import those modules without a cycle. :mod:`paces.segmenters` re-exports
+every name here, so ``from paces.segmenters import Segmentation`` keeps
+working.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from paces.model import MetricGrid, decimal_str
+
+__all__ = [
+    "DFLT_CHAPTERS_CONFIDENCE",
+    "DFLT_EXPLICIT_CONFIDENCE",
+    "DFLT_GRID_CONFIDENCE",
+    "SegStep",
+    "Segmentation",
+    "Span",
+    "TIME_PLACES",
+    "edges",
+    "inconsistencies",
+    "overlaps",
+    "time_str",
+]
+
+#: Decimal places every computed time keeps (spans, boundaries, corrections): milliseconds, the wire's
+#: resolution. Corrections round to it at construction, so their wire round trip
+#: is lossless (``decimal_str`` writes exactly this many).
+TIME_PLACES = 3
+
+
+Span = tuple[float, float]  # seconds, half-open
+
+# Confidence constants: placement from user-supplied inputs is arithmetic, so
+# what these grade is trust in the inputs, not in any inference.
+DFLT_EXPLICIT_CONFIDENCE = 0.95  # a human said so
+DFLT_GRID_CONFIDENCE = 0.9  # exact given the grid; the grid itself may drift
+DFLT_CHAPTERS_CONFIDENCE = 0.9  # the author said so, in metadata
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SegStep:
+    """One named piece of the media, as an analysis result.
+
+    ``name=''`` means "found, not named" — a VALID state, not an error.
+    ``spans`` is a tuple because a step legitimately appears in several places
+    (run-through AND breakdown).
+    """
+
+    id: str
+    name: str = ""
+    spans: tuple[Span, ...] = ()
+    confidence: float = 0.0
+    children: tuple["SegStep", ...] = ()
+    source: str = ""  # which capability produced it
+    evidence: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Segmentation:
+    """What every segmenter returns. Reviewable, re-runnable, arguable.
+
+    ``boundaries`` is separate from ``steps`` and populated even when naming
+    failed: nine excellent unnamed cuts are a useful, honest result. ``steps``
+    may be empty while ``boundaries`` is not.
+    """
+
+    steps: tuple[SegStep, ...] = ()  # ordered; MAY be empty while boundaries is not
+    boundaries: tuple[float, ...] = ()  # the raw cut set, always
+    unit: str = "seconds"  # "eight" | "rep" | "seconds"
+    grid: MetricGrid | None = None
+    confidence: float = 0.0
+    method: str = ""  # which capability ran (the ADR's "reported default")
+    flags: tuple[str, ...] = ()  # 'naming-abstained', 'no-signal', 'try: ...'
+    elapsed_s: float = 0.0
+    spent_usd: float = 0.0
+
+
+# ── consistency: what no segmentation may contain ───────────────────────────
+
+
+def edges(steps: Iterable[SegStep]) -> set[float]:
+    """Every span start and end of ``steps`` (top level)."""
+    return {t for step in steps for span in step.spans for t in span}
+
+
+def overlaps(a: Span, b: Span) -> bool:
+    """True when the two spans share a positive length of time."""
+    return max(a[0], b[0]) < min(a[1], b[1])
+
+
+#: Overlap flags listed one per pair before the rest are summarised: the
+#: check runs on every segmentation, and dense overlaps make pairs by the
+#: hundred thousand.
+DFLT_MAX_OVERLAP_FLAGS = 20
+
+
+def inconsistencies(
+    seg: Segmentation, *, max_overlap_flags: int = DFLT_MAX_OVERLAP_FLAGS
+) -> tuple[str, ...]:
+    """What no segmentation may contain, as ``inconsistent:`` flags — never
+    repaired, never raised: empty spans, spans of different steps that
+    overlap, children outside their parent, and step edges missing from
+    ``boundaries``. :func:`paces.segmenters.segment` runs it on every result,
+    whichever segmenter produced it and whether or not a correction log ran.
+
+    >>> inconsistencies(Segmentation(
+    ...     steps=(SegStep(id="a", spans=((0.0, 10.0),)),
+    ...            SegStep(id="b", spans=((8.0, 20.0),))),
+    ...     boundaries=(0.0, 10.0, 20.0)))
+    ("inconsistent: steps 'a' and 'b' overlap (8–10)", 'inconsistent: step edges not in boundaries: 8')
+    """
+
+    spans = sorted((span, step.id) for step in seg.steps for span in step.spans)
+    flags = [
+        f"inconsistent: step {step_id!r} has an empty span at {time_str(span[0])}"
+        for span, step_id in spans
+        if span[0] >= span[1]
+    ]
+    # A sweep, not all pairs: it runs on every segmentation, and subtitle
+    # cues can make thousands of steps. Only spans still open can overlap.
+    active: list[tuple[Span, str]] = []
+    overlap_flags: list[str] = []
+    for b, b_id in spans:
+        active = [(a, a_id) for a, a_id in active if a[1] > b[0]]
+        overlap_flags += [
+            f"inconsistent: steps {a_id!r} and {b_id!r} overlap "
+            f"({time_str(max(a[0], b[0]))}–{time_str(min(a[1], b[1]))})"
+            for a, a_id in active
+            if a_id != b_id and overlaps(a, b)
+        ]
+        active.append((b, b_id))
+    flags += overlap_flags[:max_overlap_flags]
+    if len(overlap_flags) > max_overlap_flags:
+        flags.append(
+            f"inconsistent: {len(overlap_flags) - max_overlap_flags} more "
+            "overlapping pairs not listed"
+        )
+    flags += [
+        f"inconsistent: child {child.id!r} of {step.id!r} lies outside its parent"
+        for step in seg.steps
+        for child in step.children
+        for span in child.spans
+        if not any(p[0] <= span[0] and span[1] <= p[1] for p in step.spans)
+    ]
+    missing = sorted(edges(seg.steps) - set(seg.boundaries))
+    if missing:
+        listed = ", ".join(time_str(t) for t in missing)
+        flags.append(f"inconsistent: step edges not in boundaries: {listed}")
+    return tuple(flags)
+
+
+def time_str(t: float) -> str:
+    """A time as paces' millisecond wire decimal — the one formatter every
+    time producer shares (the ask page's ``timeStr`` mirrors it).
+
+    >>> time_str(95.80000001), time_str(10.0625)  # exact binary ties round half-even
+    ('95.8', '10.062')
+    """
+    return decimal_str(t, places=TIME_PLACES)

{paces-0.0.22 → paces-0.0.24}/paces/segmenters.py

@@ -52,7 +52,9 @@ from paces.segmentation import (  # noqa: F401 — re-exported; their home is th
     DFLT_GRID_CONFIDENCE,
     SegStep,
     Segmentation,
+    TIME_PLACES,
     Span,
+    inconsistencies,
 )
 from paces.timed_text import normalize_timed_text
 
@@ -386,8 +388,8 @@ def _facts(
         facts.add("steps")
         if not _undated_ids(steps):
             facts.add("steps.durations")  # children too: placement needs them all
-        if any(row["spans"] for row in steps):
-            facts.add("steps.spans")
+        if any(row["spans"] for row in _walk_rows(steps)):
+            facts.add("steps.spans")  # like steps.durations: the whole tree
     if boundaries:
         facts.add("boundaries")
     if grid is not None and grid.tempo_bpm is not None and grid.origin is not None:
@@ -589,7 +591,7 @@ def segment(
         grid=out_grid,
         confidence=result.confidence,
         method=capability.name,
-        flags=result.flags + extra_flags,
+        flags=result.flags + extra_flags + inconsistencies(result),
         elapsed_s=time.perf_counter() - started,
         spent_usd=result.spent_usd,
     )
@@ -598,6 +600,11 @@ def segment(
 # ── the two v1 segmenters ───────────────────────────────────────────────────
 
 
+#: Places a unit offset (cumulative eights, reps…) is rounded to before it
+#: becomes seconds: far below any real duration, far above float noise.
+UNIT_PLACES = 9
+
+
 def place_on_grid(steps: Sequence, grid: MetricGrid | Mapping) -> Segmentation:
     """Place an ordered step list on the timeline using a metric grid.
 
@@ -632,12 +639,20 @@ def place_on_grid(steps: Sequence, grid: MetricGrid | Mapping) -> Segmentation:
     spu = seconds_per_unit(grid)
     origin = float(grid.origin)
 
+    def _seconds(units: float) -> float:
+        return round(origin + round(units, UNIT_PLACES) * spu, TIME_PLACES)
+
     def _place(rows: list[dict], at_units: float) -> list[SegStep]:
         placed = []
         for row in rows:
             duration = row["duration"]
-            start = origin + at_units * spu
-            end = origin + (at_units + duration) * spu
+            # Rounded to the millisecond, like boundaries below: a child's
+            # end summed piecewise ((a+0.1)+0.2) and its parent's (a+0.3) are
+            # the same time and must compare equal.
+            # Unit offsets are rounded first too, or a piecewise sum and the
+            # whole land on opposite sides of a half-millisecond tie.
+            start = _seconds(at_units)
+            end = _seconds(at_units + duration)
             placed.append(
                 SegStep(
                     id=row["id"],
@@ -652,7 +667,7 @@ def place_on_grid(steps: Sequence, grid: MetricGrid | Mapping) -> Segmentation:
             at_units += duration
         return placed
 
-    boundaries = tuple(origin + units * spu for units in _cumulative(rows))
+    boundaries = tuple(_seconds(units) for units in _cumulative(rows))
     return Segmentation(
         steps=tuple(_place(rows, 0.0)),
         boundaries=boundaries,

{paces-0.0.22 → paces-0.0.24}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paces"
-version = "0.0.22"
+version = "0.0.24"
 description = "Turn instructional media into structured, interactive learning material"
 readme = "README.md"
 license = "MIT"

{paces-0.0.22 → paces-0.0.24}/tests/test_corrections.py

@@ -19,6 +19,7 @@ from paces.corrections import (
     split,
     to_wire,
 )
+from paces.segmentation import inconsistencies
 from paces.segmenters import Capability, Segmentation, SegStep, segment
 
 CUTS = [0, 10, 20, 30]
@@ -241,9 +242,9 @@ def _flagged(seg, prefix):
 
 
 def test_times_are_kept_to_the_millisecond_so_the_wire_is_lossless():
-    """A grid-placed boundary is an ugly float; the wire writes 3 places."""
-    grid_placed = segment(steps=GRID_ROWS, grid=GRID)
-    b1, b2 = grid_placed.boundaries[1:3]
+    """Any computed time can be an ugly float; the wire writes 3 places.
+    (Grid-placed times are already rounded since #53; these are raw.)"""
+    b1, b2 = 0.37 + 3.8803 / 7, 4.1 + 0.1 + 0.2
     assert b1 != round(b1, 3)  # the premise: an unrounded time
     for c in [pin((b1, b2)), split(0.8550444), forbid(b1, (b1, b2)), split(0.1 + 0.2)]:
         assert from_wire(json.loads(json.dumps(to_wire(c)))) == c
@@ -336,7 +337,8 @@ def test_pin_moves_only_the_abutting_time_order_neighbours():
     out = replay(overlapping, [pin((5, 20), anchor_t=15)])
     assert [s.spans for s in out.steps] == [s.spans for s in overlapping.steps]
     assert _flagged(out, "correction-infeasible: pin@15 (would overlap step 'x')")
-    assert _flagged(out, "inconsistent: steps")  # the input itself overlapped
+    # the input itself overlapped: segment() says so, replay does not check
+    assert any(f.startswith("inconsistent: steps") for f in inconsistencies(out))
 
 
 def test_pin_clips_its_children_and_flags_any_it_drops():
@@ -468,15 +470,18 @@ def test_a_boundaries_only_segmentation_can_still_be_split_and_merged():
     assert out.flags == ("corrected: merge@10", "corrected: split@5")
 
 
-def test_the_consistency_pass_flags_what_replay_cannot_repair():
+def test_the_consistency_check_flags_what_replay_cannot_repair():
     seg = _seg(
         SegStep(id="a", spans=((0.0, 10.0),)),
         SegStep(id="b", spans=((8.0, 20.0),)),
         boundaries=(0.0, 10.0, 20.0),
     )
     out = replay(seg, [absent(25)])
-    assert "inconsistent: steps 'a' and 'b' overlap (8–10)" in out.flags
-    assert "inconsistent: step edges not in boundaries: 8" in out.flags
+    assert inconsistencies(out) == (
+        "inconsistent: steps 'a' and 'b' overlap (8–10)",
+        "inconsistent: step edges not in boundaries: 8",
+    )
+    assert not _flagged(out, "inconsistent")  # checking is segment()'s job
 
 
 def test_corrections_land_on_grid_placed_results():
@@ -563,7 +568,7 @@ def test_split_trims_a_child_that_straddles_the_cut():
     assert not _flagged(out, "inconsistent")
 
 
-def test_the_consistency_pass_flags_a_child_outside_its_parent():
+def test_the_consistency_check_flags_a_child_outside_its_parent():
     seg = _seg(
         SegStep(
             id="v",
@@ -572,7 +577,9 @@ def test_the_consistency_pass_flags_a_child_outside_its_parent():
         )
     )
     out = replay(seg, [absent(99)])
-    assert "inconsistent: child 'c' of 'v' lies outside its parent" in out.flags
+    assert "inconsistent: child 'c' of 'v' lies outside its parent" in (
+        inconsistencies(out)
+    )
 
 
 def test_merge_into_a_named_step_keeps_that_steps_record():
@@ -615,3 +622,63 @@ def test_merge_exactly_on_an_end_of_a_boundaries_only_segmentation_is_unmatched(
     assert out.flags == (
         "correction-unmatched: merge@11 (that is an end, not a cut between steps)",
     )
+
+
+# ── #36: a log that changes nothing leaves the output alone ─────────────────
+
+
+def test_a_no_op_log_leaves_the_output_exactly_as_without_one():
+    plain = segment(boundaries=[0, 10, 10, 20])  # a duplicate cut: an empty step
+    logged = segment(boundaries=[0, 10, 10, 20], corrections=[absent(99)])
+    assert logged.boundaries == plain.boundaries == (0.0, 10.0, 10.0, 20.0)
+    assert logged.steps == plain.steps
+    assert [f for f in logged.flags if not f.startswith("correction-")] == list(
+        plain.flags
+    )
+
+
+def test_every_segmentation_is_checked_log_or_not():
+    """The consistency check runs on every result, not only after a replay."""
+    plain = segment(boundaries=[0, 10, 10, 20])
+    assert "inconsistent: step 'seg-2' has an empty span at 10" in plain.flags
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        {"verb": "split", "anchor_t": True},
+        {"verb": "split", "anchor_t": 1.0, "author": 5},
+        {"verb": "split", "anchor_t": 1.0, "step_id": 3},
+    ],
+)
+def test_correction_fields_have_their_types(kwargs):
+    with pytest.raises(ValueError, match="must be"):
+        Correction(**kwargs)
+
+
+def test_the_overlap_check_scales_to_thousands_of_steps():
+    import time
+
+    n = 5000
+    steps = tuple(SegStep(id=f"s{i}", spans=((float(i), i + 1.0),)) for i in range(n))
+    seg = Segmentation(steps=steps, boundaries=tuple(float(i) for i in range(n + 1)))
+    started = time.perf_counter()
+    assert inconsistencies(seg) == ()
+    assert time.perf_counter() - started < 1.0  # all-pairs took ~seconds here
+
+
+def test_a_touched_cut_set_is_rebuilt_even_if_it_ends_where_it_started():
+    """The review's fuzz case: the duplicate 50 must not survive its step."""
+    seg = segment(
+        boundaries=[10, 40, 50, 50],
+        corrections=[pin((40, 42.5)), merge(42.5), merge(22.5)],
+    )
+    assert seg.boundaries == tuple(sorted(set(seg.boundaries)))
+
+
+def test_dense_overlaps_are_summarised_not_listed_by_the_hundred_thousand():
+    steps = tuple(SegStep(id=f"s{i}", spans=((0.0, 10.0),)) for i in range(30))
+    flags = inconsistencies(Segmentation(steps=steps, boundaries=(0.0, 10.0)))
+    overlap = [f for f in flags if " overlap " in f]
+    assert len(overlap) == 20
+    assert "inconsistent: 415 more overlapping pairs not listed" in flags

{paces-0.0.22 → paces-0.0.24}/tests/test_segment.py

@@ -8,7 +8,13 @@ import pytest
 
 from paces.model import MetricGrid
 from paces.projection import to_document
-from paces.segmenters import Capability, capabilities, register, segment
+from paces.segmenters import (
+    Capability,
+    Segmentation,
+    capabilities,
+    register,
+    segment,
+)
 
 GRID = {"unit": "eight", "subdivisions": 8, "tempoBpm": "129.2", "origin": "51.2"}
 #: The POC routine as (name, eights) pairs — kickoff's "common real case".
@@ -337,3 +343,46 @@ def test_grid_measured_rejects_bad_durations_before_measuring(
     steps = [("a", 1), {"name": "p", "duration": 2, "children": [("c", bad)]}]
     with pytest.raises(ValueError, match=r"positive, finite durations: \['c'\]"):
         segment(str(media), steps=steps, segmenter="grid-measured")
+
+
+def _spans_reader(inputs):
+    return Segmentation(boundaries=(0.0, 1.0))
+
+
+def test_the_spans_fact_reads_the_whole_step_tree():
+    """A span on a child counts, as a duration on a child does (#51): a
+    segmenter that needs ``steps.spans`` is selectable from a nested span."""
+    needs_spans = Capability(
+        name="needs-spans",
+        gives="segmentation",
+        summary="test double",
+        target=f"{__name__}:_spans_reader",
+        needs=frozenset({"steps", "steps.spans"}),
+    )
+    catalog = {"needs-spans": needs_spans}
+    nested = [
+        {"name": "p", "duration": 2, "children": [{"name": "c", "spans": [(1, 2)]}]}
+    ]
+    assert segment(steps=nested, catalog=catalog).method == "needs-spans"
+    refused = segment(steps=[("p", 2)], catalog=catalog)
+    assert refused.method == "" and "no-signal" in refused.flags
+
+
+def test_grid_placed_children_with_fractional_durations_are_consistent():
+    """(a+0.1)+0.2 and a+0.3 are the same time once placed (review of #53)."""
+    steps = [
+        ("a", 2),
+        {"name": "b", "duration": 0.3, "children": [("c1", 0.1), ("c2", 0.2)]},
+    ]
+    seg = segment(steps=steps, grid={**GRID, "tempoBpm": "120", "origin": "0"})
+    assert not [f for f in seg.flags if f.startswith("inconsistent")]
+
+
+@pytest.mark.parametrize("origin", ["1.2345", "0.0005", "0.0015"])
+def test_grid_placed_children_survive_half_millisecond_origins(origin):
+    steps = [
+        ("a", 2),
+        {"name": "b", "duration": 0.3, "children": [("c1", 0.1), ("c2", 0.2)]},
+    ]
+    seg = segment(steps=steps, grid={**GRID, "tempoBpm": "120", "origin": origin})
+    assert not [f for f in seg.flags if f.startswith("inconsistent")]

paces-0.0.22/paces/segmentation.py

@@ -1,74 +0,0 @@
-"""What a segmenter returns: :class:`Segmentation`, its :class:`SegStep` records and
-the ``Span`` they cover — the analysis-result types, with nothing else.
-
-They live apart from :mod:`paces.segmenters` (the registry and the
-``segment()`` facade) so a module that only consumes or reshapes a result —
-:mod:`paces.corrections`, :mod:`paces.projection`, :mod:`paces.ask`, the
-evidence layer — depends on the types and not on the facade, and the facade
-can import those modules without a cycle. :mod:`paces.segmenters` re-exports
-every name here, so ``from paces.segmenters import Segmentation`` keeps
-working.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Mapping
-from dataclasses import dataclass, field
-from typing import Any
-
-from paces.model import MetricGrid
-
-__all__ = [
-    "DFLT_CHAPTERS_CONFIDENCE",
-    "DFLT_EXPLICIT_CONFIDENCE",
-    "DFLT_GRID_CONFIDENCE",
-    "SegStep",
-    "Segmentation",
-    "Span",
-]
-
-Span = tuple[float, float]  # seconds, half-open
-
-# Confidence constants: placement from user-supplied inputs is arithmetic, so
-# what these grade is trust in the inputs, not in any inference.
-DFLT_EXPLICIT_CONFIDENCE = 0.95  # a human said so
-DFLT_GRID_CONFIDENCE = 0.9  # exact given the grid; the grid itself may drift
-DFLT_CHAPTERS_CONFIDENCE = 0.9  # the author said so, in metadata
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SegStep:
-    """One named piece of the media, as an analysis result.
-
-    ``name=''`` means "found, not named" — a VALID state, not an error.
-    ``spans`` is a tuple because a step legitimately appears in several places
-    (run-through AND breakdown).
-    """
-
-    id: str
-    name: str = ""
-    spans: tuple[Span, ...] = ()
-    confidence: float = 0.0
-    children: tuple["SegStep", ...] = ()
-    source: str = ""  # which capability produced it
-    evidence: Mapping[str, Any] = field(default_factory=dict)
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class Segmentation:
-    """What every segmenter returns. Reviewable, re-runnable, arguable.
-
-    ``boundaries`` is separate from ``steps`` and populated even when naming
-    failed: nine excellent unnamed cuts are a useful, honest result. ``steps``
-    may be empty while ``boundaries`` is not.
-    """
-
-    steps: tuple[SegStep, ...] = ()  # ordered; MAY be empty while boundaries is not
-    boundaries: tuple[float, ...] = ()  # the raw cut set, always
-    unit: str = "seconds"  # "eight" | "rep" | "seconds"
-    grid: MetricGrid | None = None
-    confidence: float = 0.0
-    method: str = ""  # which capability ran (the ADR's "reported default")
-    flags: tuple[str, ...] = ()  # 'naming-abstained', 'no-signal', 'try: ...'
-    elapsed_s: float = 0.0
-    spent_usd: float = 0.0