paces 0.0.18__tar.gz → 0.0.20__tar.gz

{paces-0.0.18 → paces-0.0.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.18
+Version: 0.0.20
 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.18 → paces-0.0.20}/paces/ask.py

@@ -49,7 +49,7 @@ from paces.corrections import (
     time_str,
 )
 from paces.model import seconds_per_unit
-from paces.segmenters import Segmentation
+from paces.segmentation import Segmentation
 
 PROPOSAL_KIND = "PacesAskProposal"
 ANSWERS_KIND = "PacesAskAnswers"

{paces-0.0.18 → paces-0.0.20}/paces/corrections.py

@@ -42,7 +42,7 @@ from dataclasses import dataclass
 from typing import Literal, get_args
 
 from paces.model import decimal_str
-from paces.segmenters import (
+from paces.segmentation import (
     DFLT_EXPLICIT_CONFIDENCE,
     SegStep,
     Segmentation,

{paces-0.0.18 → paces-0.0.20}/paces/evidence.py

@@ -144,7 +144,7 @@ from paces.model import (
     StepDocument,
 )
 from paces.projection import to_document
-from paces.segmenters import Segmentation
+from paces.segmentation import Segmentation
 
 #: The namespace every paces annotation id is derived under. Derived from the
 #: repository URL rather than typed as a literal, so it is reproducible from
@@ -454,7 +454,7 @@ def to_store(
     *seg* is the analysis result; the projection arguments (*doc_id*,
     *title*, *source*, *domain*, *lang*) are :func:`paces.to_document`'s,
     unchanged. Everything else is evidence a segmenter does not carry on
-    :class:`~paces.segmenters.Segmentation` but a pipeline may have:
+    :class:`~paces.segmentation.Segmentation` but a pipeline may have:
 
     Args:
         store: Any ``lacing.IntervalAnnotationStore`` — ``MemoryStore()`` for

{paces-0.0.18 → paces-0.0.20}/paces/measure.py

@@ -45,7 +45,7 @@ from paces.model import MetricGrid, decimal_str, seconds_per_unit
 from paces.segmenters import (
     Capability,
     Segmentation,
-    _segment_grid_placed,
+    place_on_grid,
     register,
 )
 
@@ -318,7 +318,7 @@ def _segment_grid_measured(inputs: Mapping[str, Any]) -> Segmentation:
     grid = measurement.grid
     if grid.tempo_bpm is None or grid.origin is None:
         return Segmentation(grid=grid, confidence=measurement.confidence, flags=flags)
-    placed = _segment_grid_placed({**inputs, "grid": grid})
+    placed = place_on_grid(inputs["steps"], grid)
     return Segmentation(
         steps=placed.steps,
         boundaries=placed.boundaries,

{paces-0.0.18 → paces-0.0.20}/paces/projection.py

@@ -21,7 +21,7 @@ from paces.model import (
     StepDocument,
     seconds_per_unit,
 )
-from paces.segmenters import SegStep, Segmentation
+from paces.segmentation import SegStep, Segmentation
 
 #: Decimal places kept when converting computed seconds to wire decimals —
 #: matches the POC's 0.1 s working resolution with headroom.

paces-0.0.20/paces/segmentation.py

@@ -0,0 +1,74 @@
+"""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

{paces-0.0.18 → paces-0.0.20}/paces/segmenters.py

@@ -44,55 +44,18 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Callable
 
+from paces import corrections as corrections_module
 from paces.model import MetricGrid, seconds_per_unit
+from paces.segmentation import (  # noqa: F401 — re-exported; their home is there
+    DFLT_CHAPTERS_CONFIDENCE,
+    DFLT_EXPLICIT_CONFIDENCE,
+    DFLT_GRID_CONFIDENCE,
+    SegStep,
+    Segmentation,
+    Span,
+)
 from paces.timed_text import normalize_timed_text
 
-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
-
 
 @dataclass(frozen=True, slots=True, kw_only=True)
 class Capability:
@@ -354,13 +317,6 @@ def _facts(
     return frozenset(facts)
 
 
-def _corrections_api():
-    """:mod:`paces.corrections`, imported lazily: it imports this module."""
-    from paces import corrections
-
-    return corrections
-
-
 def _apply_corrections(
     result: Segmentation, log: tuple, capability: Capability | None
 ) -> Segmentation:
@@ -370,7 +326,7 @@ def _apply_corrections(
     unmatched — rather than dropped."""
     if not log or (capability is not None and "corrections" in capability.reads):
         return result
-    return _corrections_api().replay(result, log)
+    return corrections_module.replay(result, log)
 
 
 # ── the facade ──────────────────────────────────────────────────────────────
@@ -418,7 +374,7 @@ def segment(
     transcript_cues = normalize_timed_text(transcript)
     # fail fast: a malformed log raises before any segmenter runs
     correction_log = (
-        _corrections_api().normalize_corrections(corrections)
+        corrections_module.normalize_corrections(corrections)
         if corrections is not None
         else ()
     )
@@ -543,42 +499,77 @@ def segment(
 # ── the two v1 segmenters ───────────────────────────────────────────────────
 
 
-def _segment_grid_placed(inputs: Mapping[str, Any]) -> Segmentation:
+def place_on_grid(steps: Sequence, grid: MetricGrid | Mapping) -> Segmentation:
     """Place an ordered step list on the timeline using a metric grid.
 
     The que-calor shape: cumulative domain durations from the grid's origin,
     ``span = origin + cumulative_units * seconds_per_unit``. Children subdivide
-    their parent's span the same way.
+    their parent's span the same way. ``steps`` takes any form
+    :func:`segment` takes (``(name, duration)`` pairs, mappings with
+    ``children``); every step needs a positive duration, and the grid a tempo
+    and an origin — anything missing or invalid is a ``ValueError`` naming it.
+
+    >>> seg = place_on_grid([("a", 1), ("b", 2)],
+    ...                     {"unit": "eight", "subdivisions": 8,
+    ...                      "tempoBpm": "120", "origin": "1"})
+    >>> [s.spans for s in seg.steps], seg.boundaries
+    ([((1.0, 5.0),), ((5.0, 13.0),)], (1.0, 5.0, 13.0))
     """
-    grid: MetricGrid = inputs["grid"]
+
+    def _all_rows(rows: list[dict]):
+        for row in rows:
+            yield row
+            yield from _all_rows(row["children"])
+
+    grid = _normalize_grid(grid)
+    rows = _normalize_steps(steps)
+    if grid is None:
+        raise ValueError("place_on_grid needs a grid; got None")
+    missing = [
+        name
+        for name, value in (("tempoBpm", grid.tempo_bpm), ("origin", grid.origin))
+        if value is None
+    ]
+    if missing:
+        raise ValueError(f"place_on_grid needs a grid with {' and '.join(missing)}")
+    if not rows:
+        raise ValueError("place_on_grid needs at least one step")
+    undated = [row["id"] for row in _all_rows(rows) if row["duration"] is None]
+    if undated:
+        raise ValueError(f"place_on_grid needs a duration for every step: {undated}")
+    bad = [
+        row["id"]
+        for row in _all_rows(rows)
+        if not (math.isfinite(row["duration"]) and row["duration"] > 0)
+    ]
+    if bad:
+        raise ValueError(f"place_on_grid needs positive, finite durations: {bad}")
     spu = seconds_per_unit(grid)
-    origin = float(grid.origin)  # guaranteed by the 'grid' fact
+    origin = float(grid.origin)
 
-    def _place(rows: list[dict], at_units: float) -> tuple[list[SegStep], float]:
+    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
-            children, _ = _place(row["children"], at_units)
             placed.append(
                 SegStep(
                     id=row["id"],
                     name=row["name"],
                     spans=((start, end),),
                     confidence=DFLT_GRID_CONFIDENCE,
-                    children=tuple(children),
+                    children=tuple(_place(row["children"], at_units)),
                     source="grid-placed",
                     evidence={"duration_units": duration, "offset_units": at_units},
                 )
             )
             at_units += duration
-        return placed, at_units
+        return placed
 
-    steps, total_units = _place(inputs["steps"], 0.0)
-    boundaries = tuple(origin + units * spu for units in _cumulative(inputs["steps"]))
+    boundaries = tuple(origin + units * spu for units in _cumulative(rows))
     return Segmentation(
-        steps=tuple(steps),
+        steps=tuple(_place(rows, 0.0)),
         boundaries=boundaries,
         unit=grid.unit,
         grid=grid,
@@ -586,6 +577,11 @@ def _segment_grid_placed(inputs: Mapping[str, Any]) -> Segmentation:
     )
 
 
+def _segment_grid_placed(inputs: Mapping[str, Any]) -> Segmentation:
+    """The ``grid-placed`` capability: :func:`place_on_grid` over the facade's inputs."""
+    return place_on_grid(inputs["steps"], inputs["grid"])
+
+
 def _cumulative(rows: list[dict]) -> list[float]:
     offsets, at = [0.0], 0.0
     for row in rows:

{paces-0.0.18 → paces-0.0.20}/pyproject.toml

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

{paces-0.0.18 → paces-0.0.20}/tests/test_segment.py

@@ -170,3 +170,32 @@ def test_decimal_str_refuses_non_finite_values(value):
 
     with pytest.raises(ValueError, match="non-finite"):
         decimal_str(value)
+
+
+def test_place_on_grid_is_the_public_placement():
+    from paces.segmenters import place_on_grid
+
+    seg = place_on_grid(ROUTINE_STEPS, GRID)
+    assert [s.spans for s in seg.steps] == [
+        s.spans for s in segment(steps=ROUTINE_STEPS, grid=GRID).steps
+    ]
+
+
+@pytest.mark.parametrize(
+    "steps, grid, match",
+    [
+        (ROUTINE_STEPS, {"unit": "eight", "subdivisions": 8}, "tempoBpm and origin"),
+        (ROUTINE_STEPS, {**GRID, "origin": None}, "with origin$"),
+        ([], GRID, "at least one step"),
+        ([("back", -1)], GRID, r"positive, finite durations: \['back'\]"),
+        ([("nan", float("nan"))], GRID, "positive, finite"),
+        ([("zero", 0)], GRID, "positive, finite"),
+        (["no duration"], GRID, "duration for every step"),
+        ([{"name": "p", "duration": 2, "children": ["c"]}], GRID, r"\['c'\]"),
+    ],
+)
+def test_place_on_grid_names_what_is_missing(steps, grid, match):
+    from paces.segmenters import place_on_grid
+
+    with pytest.raises(ValueError, match=match):
+        place_on_grid(steps, grid)