meta-sam-parser 0.0.2__tar.gz → 0.0.4__tar.gz

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-sam-parser
-Version: 0.0.2
+Version: 0.0.4
 Summary: Native Python parsing primitives for the SAM 3 segmentation protocol
 Project-URL: Homepage, https://github.com/meta-models/meta-sam
 Project-URL: Repository, https://github.com/meta-models/meta-sam
@@ -106,24 +106,35 @@ python -m pip install .
 
 Import supported APIs only from the package root. Deep imports are unsupported;
 underscore-prefixed modules are implementation details and may change without notice.
-Format factories are zero-argument and create isolated parser state:
+Format factories are zero-argument and create isolated parser state. The example
+feeds the parser one frame of SAM 3.1 output exactly as the API emits it - one line
+per frame, `<Nf>` then comma-separated `id<|box;...|><|mask;...|>` records:
 
 ```python
 from meta_sam_parser import CompletedOutcome, video_segmentation_format
 
+output_text = (
+    "<0f>0<|box;x1=211;y1=228;x2=270;y2=254;w=320;h=334|>"
+    "<|mask;x=0;y=0;data=27,60,~!!!!M!0c[0o91w?q1!pIH4pPRVp2B3'7`e.ioeAf6-k/#Xd8%dX9x(|>"
+    ",1<|box;x1=155;y1=228;x2=202;y2=254;w=320;h=334|>"
+    "<|mask;x=0;y=0;data=27,48,~!!!!J!0c[q=Pj_zs=*4C4(/./x#:/`S_GnD`=o3?X{emCgO$y@|>\n"
+)
+
 format_ = video_segmentation_format()
 parser = format_.create_parser()
 
-for snapshot in parser.push(
-    "[frame=7] object=bus box=(10,20,110,80)\n"
-    "[frame=7] object=bus mask=one_bit;size=5x5;data=!!!!!(QO(0lu8?\n"
-):
+# Chunks may split anywhere, including inside a mask payload.
+split = output_text.index(",1<|box")
+for snapshot in parser.push(output_text[:split]):
     print(snapshot.revision, len(snapshot.records))
+for snapshot in parser.push(output_text[split:]):
+    print(snapshot.revision, len(snapshot.records))  # 1 4
 
 finished = parser.finish(CompletedOutcome())
 for snapshot in finished.events:
     print(snapshot.revision, len(snapshot.records))
 result = finished.result
+# Two box records and two mask records, object IDs "0" and "1", frame 0.
 ```
 
 `push()` accepts arbitrarily split text chunks and returns zero or one cumulative
@@ -140,7 +151,11 @@ can own lane validation, source cleanup, and terminal outcomes.
 `parse_responses_stream(source, format)` accepts an async iterable of official
 OpenAI Python SDK event objects, mappings with the same wire fields, or a mixture
 of both. It has no runtime dependency on the OpenAI SDK. Field names stay in the
-SDK/wire snake-case form (`item_id`, `output_index`, and `content_index`).
+SDK/wire snake-case form (`item_id`, `output_index`, and `content_index`). An
+output-text lane is finalized by either `response.output_text.done` or a
+`response.content_part.done` event whose part type is `output_text`. The live SAM
+Model API emits only the latter. If a stream emits both finalizers, their text
+must match.
 
 ### Iterator-first
 
@@ -228,10 +243,10 @@ All public values are frozen, slotted dataclasses. Observable collections are
 tuples. The package root exports:
 
 - Geometry, masks, and aliases: `FrameReference`, `SegmentationMaskBounds`,
-  `SegmentationMask`, `SegmentationMaskIdentity`, `SegmentationMedia`,
+  `SegmentationMask`, `SegmentationMaskEncoding`, `SegmentationMaskIdentity`, `SegmentationMedia`,
   `DiagnosticSeverity`, and `IncompleteReason`.
-- Records: `SegmentationTextRecord`, `SegmentationPointRecord`,
-  `SegmentationBoxRecord`, `SegmentationMaskRecord`, and `SegmentationRecord`.
+- Records: `SegmentationTextRecord`, `SegmentationBoxRecord`,
+  `SegmentationMaskRecord`, and `SegmentationRecord`.
 - Views: `SegmentationDiagnostic`, `ImageSegmentationSnapshot`,
   `VideoSegmentationSnapshot`, `SegmentationSnapshot`,
   `ImageSegmentationResult`, `VideoSegmentationResult`, and
@@ -258,15 +273,31 @@ the next revision.
 
 ## Parsing behavior
 
-The documented package grammar is the line form in the
+SAM 3.1 returns segmentation as special-token text in one `output_text` lane, one
+line per frame:
+
+```text
+<Nf>id<|box;x1=..;y1=..;x2=..;y2=..;w=<frameW>;h=<frameH>|><|mask;x=0;y=0;data=<H>,<W>,<enc>payload|>,id<|box;...|><|mask;...|>
+```
+
+`<Nf>` is the zero-based frame index; frames without a visible object emit no
+line, so indices can skip. Each comma-separated record is a bare integer object
+id - stable for an object across the frames of one response and not a dense
+sequence - followed by one box and one mask. The parser retains the id as a string
+in `object_id`. Box corners and the `w`/`h` frame size are source pixels; the
+inclusive wire `x2`/`y2` become half-open `right`/`bottom`. The mask tuple is
+`height,width,payload`, where the payload's first character selects the encoding:
+`~` for `lossless` (the API default) or `!` for `one_bit`. The payload is base85,
+not base64: after the marker its digits are printable ASCII `!` through `{` minus
+the wire delimiters `" \ , ; < > |`, so it contains `*`, `$`, brackets, and
+backticks, a base64 regex will not match it, and only the first character after
+`H,W,` is the marker (`!` is also digit zero). Pass it through unchanged. Each record becomes one `SegmentationBoxRecord` followed by
+one `SegmentationMaskRecord` whose `bounds` is the same half-open box. Image streams require frame zero and omit the frame from
+normalized records; video records retain `frame.frame_index`. Every mask is
+strictly decoded before insertion; an empty lane is a valid completed response
+with no records.
+The grammar is specified in the
 [SAM 3 protocol](https://github.com/meta-models/meta-sam/blob/main/protocol/sam3.md).
-The parser separately accepts compact box-first SAM API output as production
-compatibility input and normalizes it to the same records. Its object token is an
-ASCII-decimal ID retained as a string, and IDs may be multi-digit or non-contiguous.
-The compact input's inclusive `x2`/`y2` coordinates become half-open `right`/`bottom`
-bounds. Image API
-records require frame zero and omit it from normalized records; video records retain
-frame indices. Every mask is strictly decoded before insertion.
 
 Plain text remains an ordered text record. Malformed structured-looking lines
 produce diagnostics and parsing continues. `raw_output` preserves every input
@@ -359,8 +390,11 @@ by the `release PyPI distribution` workflow
 1. Bump `version` in `pyproject.toml`, run `node scripts/sync-compatibility` from
    the repository root so the compatibility matrix records the new version, and
    merge that change to `main`.
-2. Push the tag `meta-sam-parser@<version>` at that commit. The workflow refuses a
-   tag that does not match the manifest version.
+2. Push the tag `meta-sam-parser@<version>` at that merge commit on `main`. The
+   workflow refuses a tag that does not match the manifest version, a tag whose
+   commit is not on `main`, and a tag older than the latest `main` commit touching
+   `python/`, `conformance/`, or `protocol/`, so a tag created before later fixes
+   merged cannot publish stale source.
 3. The workflow builds the reproducible wheel and sdist, runs the artifact and
    clean-consumer audits and the cross-language conformance suite, and then waits
    for approval in the `pypi` GitHub environment before uploading through PyPI

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.4}/README.md

@@ -17,24 +17,35 @@ python -m pip install .
 
 Import supported APIs only from the package root. Deep imports are unsupported;
 underscore-prefixed modules are implementation details and may change without notice.
-Format factories are zero-argument and create isolated parser state:
+Format factories are zero-argument and create isolated parser state. The example
+feeds the parser one frame of SAM 3.1 output exactly as the API emits it - one line
+per frame, `<Nf>` then comma-separated `id<|box;...|><|mask;...|>` records:
 
 ```python
 from meta_sam_parser import CompletedOutcome, video_segmentation_format
 
+output_text = (
+    "<0f>0<|box;x1=211;y1=228;x2=270;y2=254;w=320;h=334|>"
+    "<|mask;x=0;y=0;data=27,60,~!!!!M!0c[0o91w?q1!pIH4pPRVp2B3'7`e.ioeAf6-k/#Xd8%dX9x(|>"
+    ",1<|box;x1=155;y1=228;x2=202;y2=254;w=320;h=334|>"
+    "<|mask;x=0;y=0;data=27,48,~!!!!J!0c[q=Pj_zs=*4C4(/./x#:/`S_GnD`=o3?X{emCgO$y@|>\n"
+)
+
 format_ = video_segmentation_format()
 parser = format_.create_parser()
 
-for snapshot in parser.push(
-    "[frame=7] object=bus box=(10,20,110,80)\n"
-    "[frame=7] object=bus mask=one_bit;size=5x5;data=!!!!!(QO(0lu8?\n"
-):
+# Chunks may split anywhere, including inside a mask payload.
+split = output_text.index(",1<|box")
+for snapshot in parser.push(output_text[:split]):
     print(snapshot.revision, len(snapshot.records))
+for snapshot in parser.push(output_text[split:]):
+    print(snapshot.revision, len(snapshot.records))  # 1 4
 
 finished = parser.finish(CompletedOutcome())
 for snapshot in finished.events:
     print(snapshot.revision, len(snapshot.records))
 result = finished.result
+# Two box records and two mask records, object IDs "0" and "1", frame 0.
 ```
 
 `push()` accepts arbitrarily split text chunks and returns zero or one cumulative
@@ -51,7 +62,11 @@ can own lane validation, source cleanup, and terminal outcomes.
 `parse_responses_stream(source, format)` accepts an async iterable of official
 OpenAI Python SDK event objects, mappings with the same wire fields, or a mixture
 of both. It has no runtime dependency on the OpenAI SDK. Field names stay in the
-SDK/wire snake-case form (`item_id`, `output_index`, and `content_index`).
+SDK/wire snake-case form (`item_id`, `output_index`, and `content_index`). An
+output-text lane is finalized by either `response.output_text.done` or a
+`response.content_part.done` event whose part type is `output_text`. The live SAM
+Model API emits only the latter. If a stream emits both finalizers, their text
+must match.
 
 ### Iterator-first
 
@@ -139,10 +154,10 @@ All public values are frozen, slotted dataclasses. Observable collections are
 tuples. The package root exports:
 
 - Geometry, masks, and aliases: `FrameReference`, `SegmentationMaskBounds`,
-  `SegmentationMask`, `SegmentationMaskIdentity`, `SegmentationMedia`,
+  `SegmentationMask`, `SegmentationMaskEncoding`, `SegmentationMaskIdentity`, `SegmentationMedia`,
   `DiagnosticSeverity`, and `IncompleteReason`.
-- Records: `SegmentationTextRecord`, `SegmentationPointRecord`,
-  `SegmentationBoxRecord`, `SegmentationMaskRecord`, and `SegmentationRecord`.
+- Records: `SegmentationTextRecord`, `SegmentationBoxRecord`,
+  `SegmentationMaskRecord`, and `SegmentationRecord`.
 - Views: `SegmentationDiagnostic`, `ImageSegmentationSnapshot`,
   `VideoSegmentationSnapshot`, `SegmentationSnapshot`,
   `ImageSegmentationResult`, `VideoSegmentationResult`, and
@@ -169,15 +184,31 @@ the next revision.
 
 ## Parsing behavior
 
-The documented package grammar is the line form in the
+SAM 3.1 returns segmentation as special-token text in one `output_text` lane, one
+line per frame:
+
+```text
+<Nf>id<|box;x1=..;y1=..;x2=..;y2=..;w=<frameW>;h=<frameH>|><|mask;x=0;y=0;data=<H>,<W>,<enc>payload|>,id<|box;...|><|mask;...|>
+```
+
+`<Nf>` is the zero-based frame index; frames without a visible object emit no
+line, so indices can skip. Each comma-separated record is a bare integer object
+id - stable for an object across the frames of one response and not a dense
+sequence - followed by one box and one mask. The parser retains the id as a string
+in `object_id`. Box corners and the `w`/`h` frame size are source pixels; the
+inclusive wire `x2`/`y2` become half-open `right`/`bottom`. The mask tuple is
+`height,width,payload`, where the payload's first character selects the encoding:
+`~` for `lossless` (the API default) or `!` for `one_bit`. The payload is base85,
+not base64: after the marker its digits are printable ASCII `!` through `{` minus
+the wire delimiters `" \ , ; < > |`, so it contains `*`, `$`, brackets, and
+backticks, a base64 regex will not match it, and only the first character after
+`H,W,` is the marker (`!` is also digit zero). Pass it through unchanged. Each record becomes one `SegmentationBoxRecord` followed by
+one `SegmentationMaskRecord` whose `bounds` is the same half-open box. Image streams require frame zero and omit the frame from
+normalized records; video records retain `frame.frame_index`. Every mask is
+strictly decoded before insertion; an empty lane is a valid completed response
+with no records.
+The grammar is specified in the
 [SAM 3 protocol](https://github.com/meta-models/meta-sam/blob/main/protocol/sam3.md).
-The parser separately accepts compact box-first SAM API output as production
-compatibility input and normalizes it to the same records. Its object token is an
-ASCII-decimal ID retained as a string, and IDs may be multi-digit or non-contiguous.
-The compact input's inclusive `x2`/`y2` coordinates become half-open `right`/`bottom`
-bounds. Image API
-records require frame zero and omit it from normalized records; video records retain
-frame indices. Every mask is strictly decoded before insertion.
 
 Plain text remains an ordered text record. Malformed structured-looking lines
 produce diagnostics and parsing continues. `raw_output` preserves every input
@@ -270,8 +301,11 @@ by the `release PyPI distribution` workflow
 1. Bump `version` in `pyproject.toml`, run `node scripts/sync-compatibility` from
    the repository root so the compatibility matrix records the new version, and
    merge that change to `main`.
-2. Push the tag `meta-sam-parser@<version>` at that commit. The workflow refuses a
-   tag that does not match the manifest version.
+2. Push the tag `meta-sam-parser@<version>` at that merge commit on `main`. The
+   workflow refuses a tag that does not match the manifest version, a tag whose
+   commit is not on `main`, and a tag older than the latest `main` commit touching
+   `python/`, `conformance/`, or `protocol/`, so a tag created before later fixes
+   merged cannot publish stale source.
 3. The workflow builds the reproducible wheel and sdist, runs the artifact and
    clean-consumer audits and the cross-language conformance suite, and then waits
    for approval in the `pypi` GitHub environment before uploading through PyPI

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.4}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meta-sam-parser"
-version = "0.0.2"
+version = "0.0.4"
 description = "Native Python parsing primitives for the SAM 3 segmentation protocol"
 readme = "README.md"
 requires-python = ">=3.10"

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.4}/src/meta_sam_parser/__init__.py

@@ -36,10 +36,10 @@ from ._types import (
     SegmentationDiagnostic,
     SegmentationMask,
     SegmentationMaskBounds,
+    SegmentationMaskEncoding,
     SegmentationMaskIdentity,
     SegmentationMaskRecord,
     SegmentationMedia,
-    SegmentationPointRecord,
     SegmentationRecord,
     SegmentationResult,
     SegmentationSnapshot,
@@ -80,10 +80,10 @@ __all__ = [
     "SegmentationDiagnostic",
     "SegmentationMask",
     "SegmentationMaskBounds",
+    "SegmentationMaskEncoding",
     "SegmentationMaskIdentity",
     "SegmentationMaskRecord",
     "SegmentationMedia",
-    "SegmentationPointRecord",
     "SegmentationRecord",
     "SegmentationResult",
     "SegmentationSnapshot",

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.4}/src/meta_sam_parser/_segmentation.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import math
 import re
 from dataclasses import dataclass
 from typing import cast
@@ -23,7 +22,6 @@ from ._types import (
     SegmentationMaskIdentity,
     SegmentationMaskRecord,
     SegmentationMedia,
-    SegmentationPointRecord,
     SegmentationRecord,
     SegmentationResult,
     SegmentationSnapshot,
@@ -40,65 +38,28 @@ _JS_WHITESPACE = (
 _JS_WHITESPACE_CLASS = (
     r"\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
 )
-_JS_WHITESPACE_PATTERN = rf"[{_JS_WHITESPACE_CLASS}]"
-_JS_NON_WHITESPACE_PATTERN = rf"[^{_JS_WHITESPACE_CLASS}]"
 _JS_DOT_PATTERN = r"[^\n\r\u2028\u2029]"
-_RECORD_PATTERN = re.compile(
-    rf"^(?:\[frame=([0-9]+)\]{_JS_WHITESPACE_PATTERN}+)?"
-    rf"object=([A-Za-z0-9._-]+){_JS_WHITESPACE_PATTERN}+"
-    rf"(point|box|mask)=({_JS_DOT_PATTERN}+)$"
-)
-_COMPACT_API_HEADER_PATTERN = re.compile(rf"^<([0-9]+)f>({_JS_DOT_PATTERN}*)$")
-_COMPACT_API_OBJECT_PATTERN = re.compile(
+_API_HEADER_PATTERN = re.compile(rf"^<([0-9]+)f>({_JS_DOT_PATTERN}*)$")
+_API_RECORD_PATTERN = re.compile(
     r"^(?:,)?([0-9]+)"
     r"<\|box;x1=(-?[0-9]+);y1=(-?[0-9]+);x2=(-?[0-9]+);"
     r"y2=(-?[0-9]+);w=([0-9]+);h=([0-9]+)\|>"
     r"<\|mask;x=0;y=0;data=([0-9]+),([0-9]+),([!~][^|]+)\|>"
 )
-_POINT_PATTERN = re.compile(r"^\(([^,]+),([^,]+)\)$")
-_BOX_PATTERN = re.compile(r"^\(([^,]+),([^,]+),([^,]+),([^,]+)\)$")
-_MASK_PATTERN = re.compile(
-    rf"^([^;{_JS_WHITESPACE_CLASS}]+);"
-    rf"size=([0-9]+)x([0-9]+);data=({_JS_NON_WHITESPACE_PATTERN}+)$"
-)
-_DECIMAL_NUMBER_PATTERN = re.compile(
-    r"^[+-]?(?:(?:[0-9]+(?:\.[0-9]*)?)|(?:\.[0-9]+))"
-    r"(?:[eE][+-]?[0-9]+)?$"
-)
-_HEXADECIMAL_NUMBER_PATTERN = re.compile(r"^0[xX][0-9A-Fa-f]+$")
-_BINARY_NUMBER_PATTERN = re.compile(r"^0[bB][01]+$")
-_OCTAL_NUMBER_PATTERN = re.compile(r"^0[oO][0-7]+$")
 
 
 def _trim(value: str) -> str:
     return value.strip(_JS_WHITESPACE)
 
 
-def _javascript_number(value: str) -> float | None:
-    normalized = _trim(value)
-    if not normalized:
-        return None
-    try:
-        if _HEXADECIMAL_NUMBER_PATTERN.fullmatch(normalized):
-            parsed = float(int(normalized[2:], 16))
-        elif _BINARY_NUMBER_PATTERN.fullmatch(normalized):
-            parsed = float(int(normalized[2:], 2))
-        elif _OCTAL_NUMBER_PATTERN.fullmatch(normalized):
-            parsed = float(int(normalized[2:], 8))
-        elif _DECIMAL_NUMBER_PATTERN.fullmatch(normalized):
-            parsed = float(normalized)
-        else:
-            return None
-    except (OverflowError, ValueError):
-        return None
-    return parsed if math.isfinite(parsed) else None
-
-
 def _integer_text(value: str) -> int | None:
-    parsed = _javascript_number(value)
-    if parsed is None or not parsed.is_integer() or abs(parsed) > _MAXIMUM_SAFE_INTEGER:
-        return None
-    return int(parsed)
+    """Parse a decimal integer token the way JavaScript's ``Number`` observes it.
+
+    Callers only pass regex captures of ``-?[0-9]+``; values beyond the
+    JavaScript safe-integer range are rejected so both parsers agree.
+    """
+    parsed = int(value)
+    return parsed if abs(parsed) <= _MAXIMUM_SAFE_INTEGER else None
 
 
 class _SegmentationParser:
@@ -180,50 +141,15 @@ class _SegmentationParser:
             return False
 
         if line.startswith("<"):
-            accepted = self._accept_compact_api_line(line, raw)
+            accepted = self._accept_api_line(line, raw)
             if accepted is not None:
                 return accepted
 
-        match = _RECORD_PATTERN.fullmatch(line)
-        if match is None:
-            if line.startswith("[frame=") or line.startswith("object="):
-                self._diagnose("malformed_record", "Malformed structured record.", raw)
-            else:
-                self._add_record(
-                    SegmentationTextRecord(order=len(self._records), text=raw)
-                )
-            return True
-
-        frame_index = None if match.group(1) is None else _integer_text(match.group(1))
-        if match.group(1) is not None and (frame_index is None or frame_index < 0):
-            self._diagnose(
-                "invalid_frame",
-                "Frame references must be non-negative safe integers.",
-                raw,
-            )
-            return True
-        if self._media == "image" and frame_index is not None:
-            self._diagnose(
-                "unexpected_frame",
-                "Image segmentation records cannot include a frame reference.",
-                raw,
-            )
-            return True
-
-        object_id = match.group(2)
-        kind = match.group(3)
-        value = match.group(4)
-        frame = None if frame_index is None else FrameReference(frame_index)
-        if kind == "point":
-            self._accept_point(object_id, frame, value, raw)
-        elif kind == "box":
-            self._accept_box(object_id, frame, value, raw)
-        else:
-            self._accept_mask(object_id, frame, value, raw)
+        self._add_record(SegmentationTextRecord(order=len(self._records), text=raw))
         return True
 
-    def _accept_compact_api_line(self, line: str, raw: str) -> bool | None:
-        header = _COMPACT_API_HEADER_PATTERN.fullmatch(line)
+    def _accept_api_line(self, line: str, raw: str) -> bool | None:
+        header = _API_HEADER_PATTERN.fullmatch(line)
         if header is None:
             return None
         frame_index = _integer_text(header.group(1))
@@ -247,17 +173,17 @@ class _SegmentationParser:
         if not remainder:
             self._diagnose(
                 "malformed_record",
-                "Malformed compact SAM API object record.",
+                "Malformed SAM API object record.",
                 raw,
             )
             return True
         accepted = False
         while remainder:
-            match = _COMPACT_API_OBJECT_PATTERN.match(remainder)
+            match = _API_RECORD_PATTERN.match(remainder)
             if match is None:
                 self._diagnose(
                     "malformed_record",
-                    "Malformed compact SAM API object record.",
+                    "Malformed SAM API object record.",
                     raw,
                 )
                 return True
@@ -267,7 +193,7 @@ class _SegmentationParser:
             )
             if any(value is None for value in coordinate_values):
                 self._diagnose(
-                    "invalid_box", "Canonical SAM box coordinates are invalid.", raw
+                    "invalid_box", "SAM API box coordinates are invalid.", raw
                 )
                 return True
             (
@@ -289,7 +215,7 @@ class _SegmentationParser:
                 or inclusive_bottom >= source_height
             ):
                 self._diagnose(
-                    "invalid_box", "Canonical SAM box coordinates are invalid.", raw
+                    "invalid_box", "SAM API box coordinates are invalid.", raw
                 )
                 return True
             bounds = SegmentationMaskBounds(
@@ -309,14 +235,16 @@ class _SegmentationParser:
                     bottom=inclusive_bottom + 1,
                 )
             )
-            mask_height = match.group(8)
-            mask_width = match.group(9)
             payload = match.group(10)
-            encoding = "lossless" if payload.startswith("~") else "one_bit"
             self._accept_mask(
                 object_id,
                 frame,
-                f"{encoding};size={mask_width}x{mask_height};data={payload}",
+                SegmentationMask(
+                    encoding="lossless" if payload.startswith("~") else "one_bit",
+                    payload=payload,
+                    width=int(match.group(9)),
+                    height=int(match.group(8)),
+                ),
                 raw,
                 bounds,
             )
@@ -324,109 +252,20 @@ class _SegmentationParser:
             remainder = remainder[match.end() :]
         return accepted
 
-    def _accept_point(
-        self,
-        object_id: str,
-        frame: FrameReference | None,
-        value: str,
-        raw: str,
-    ) -> None:
-        match = _POINT_PATTERN.fullmatch(_trim(value))
-        x = None if match is None else _javascript_number(match.group(1))
-        y = None if match is None else _javascript_number(match.group(2))
-        if x is None or y is None:
-            self._diagnose(
-                "malformed_point", "Point coordinates must be finite numbers.", raw
-            )
-            return
-        self._add_record(
-            SegmentationPointRecord(
-                order=len(self._records),
-                object_id=object_id,
-                frame=frame,
-                x=x,
-                y=y,
-            )
-        )
-
-    def _accept_box(
-        self,
-        object_id: str,
-        frame: FrameReference | None,
-        value: str,
-        raw: str,
-    ) -> None:
-        match = _BOX_PATTERN.fullmatch(_trim(value))
-        coordinates = (
-            None
-            if match is None
-            else tuple(_javascript_number(item) for item in match.group(1, 2, 3, 4))
-        )
-        if coordinates is None or any(item is None for item in coordinates):
-            self._diagnose(
-                "malformed_box", "Box coordinates must be finite numbers.", raw
-            )
-            return
-        left, top, right, bottom = cast(tuple[float, float, float, float], coordinates)
-        if right < left or bottom < top:
-            self._diagnose("invalid_box", "Box coordinates must be ordered.", raw)
-            return
-        self._add_record(
-            SegmentationBoxRecord(
-                order=len(self._records),
-                object_id=object_id,
-                frame=frame,
-                left=left,
-                top=top,
-                right=right,
-                bottom=bottom,
-            )
-        )
-
     def _accept_mask(
         self,
         object_id: str,
         frame: FrameReference | None,
-        value: str,
+        mask: SegmentationMask,
         raw: str,
-        bounds: SegmentationMaskBounds | None = None,
+        bounds: SegmentationMaskBounds,
     ) -> None:
-        match = _MASK_PATTERN.fullmatch(_trim(value))
-        if match is None:
-            self._diagnose(
-                "malformed_mask",
-                "Mask records require encoding, size, and one complete payload.",
-                raw,
-            )
-            return
-        encoding = match.group(1)
-        width_number = _javascript_number(match.group(2))
-        height_number = _javascript_number(match.group(3))
-        width = int(width_number) if width_number is not None else 0
-        height = int(height_number) if height_number is not None else 0
-        payload = match.group(4)
-        if encoding not in ("one_bit", "lossless"):
-            self._diagnose(
-                "unsupported_mask_encoding",
-                f"Unsupported complete mask encoding: {encoding}.",
-                raw,
-            )
-            return
-        area = float(width) * float(height)
-        if (
-            width <= 0
-            or height <= 0
-            or not math.isfinite(area)
-            or not area.is_integer()
-            or abs(area) > _MAXIMUM_SAFE_INTEGER
-        ):
+        area = mask.width * mask.height
+        if mask.width <= 0 or mask.height <= 0 or area > _MAXIMUM_SAFE_INTEGER:
             self._diagnose(
                 "invalid_mask_size", "Mask dimensions must be positive.", raw
             )
             return
-        mask = SegmentationMask(
-            encoding=encoding, payload=payload, width=width, height=height
-        )
         try:
             decode_mask_to_raster(mask)
         except InvalidSegmentationMaskError as error:

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.4}/src/meta_sam_parser/_stream.py

@@ -107,6 +107,7 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
         self._error: BaseException | None = None
         self._lane: OutputTextLane | None = None
         self._lane_done = False
+        self._lane_finalizers: set[str] = set()
         self._text = ""
         self._saw_delta = False
 
@@ -169,6 +170,9 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
         if self._consumption == "idle":
             self._consumption = "final"
         failure = self._start_failure(ResponsesStreamAbortedError())
+        if current is self._active_read:
+            # A source finalizer cannot join the read that is running it.
+            return
         try:
             await asyncio.shield(failure)
         except asyncio.CancelledError:
@@ -274,30 +278,19 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
             self._push_parser(delta, emit=emit)
             return None
         if event_type == "response.output_text.done":
-            lane = self._accept_lane(event)
-            if self._lane_done:
-                raise ResponsesStreamLaneError(
-                    "The response finalized its output text lane more than once.",
-                    self._lane,
-                    lane,
-                )
-            text = _field(event, "text")
-            if not isinstance(text, str):
-                raise ResponsesStreamLaneError(
-                    "The completed output text is missing its text.",
-                    self._lane,
-                    lane,
-                )
-            if self._saw_delta and text != self._text:
-                raise ResponsesStreamLaneError(
-                    "The finalized output text conflicts with its accumulated deltas.",
-                    self._lane,
-                    lane,
+            self._finalize_output_text(event, _field(event, "text"), emit=emit)
+            return None
+        if event_type == "response.content_part.done":
+            part = _field(event, "part")
+            part_type = _field(part, "type")
+            if part_type == "output_text":
+                self._finalize_output_text(event, _field(part, "text"), emit=emit)
+            elif part_type == "refusal":
+                refusal = _field(part, "refusal")
+                message = (
+                    refusal if isinstance(refusal, str) else "The response was refused."
                 )
-            if not self._saw_delta:
-                self._text = text
-                self._push_parser(text, emit=emit)
-            self._lane_done = True
+                raise ResponsesStreamRefusalError(message, event)
             return None
         if event_type in ("response.refusal.delta", "response.refusal.done"):
             refusal = _field(event, "refusal")
@@ -342,6 +335,46 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
             raise ResponsesStreamEventError(event_message, event)
         return None
 
+    def _finalize_output_text(
+        self, event: ResponsesEventLike, text: object, *, emit: bool
+    ) -> None:
+        lane = self._accept_lane(event)
+        event_type = _field(event, "type")
+        assert isinstance(event_type, str)
+        if self._lane_done and event_type in self._lane_finalizers:
+            raise ResponsesStreamLaneError(
+                "The response finalized its output text lane more than once.",
+                self._lane,
+                lane,
+            )
+        if not isinstance(text, str):
+            raise ResponsesStreamLaneError(
+                "The completed output text is missing its text.",
+                self._lane,
+                lane,
+            )
+        if self._lane_done:
+            if text != self._text:
+                raise ResponsesStreamLaneError(
+                    "The response finalized its output text lane twice with "
+                    "conflicting text.",
+                    self._lane,
+                    lane,
+                )
+            self._lane_finalizers.add(event_type)
+            return
+        if self._saw_delta and text != self._text:
+            raise ResponsesStreamLaneError(
+                "The finalized output text conflicts with its accumulated deltas.",
+                self._lane,
+                lane,
+            )
+        if not self._saw_delta:
+            self._text = text
+            self._push_parser(text, emit=emit)
+        self._lane_done = True
+        self._lane_finalizers.add(event_type)
+
     def _accept_lane(self, event: ResponsesEventLike) -> OutputTextLane:
         item_id = _field(event, "item_id")
         output_index = _safe_nonnegative_integer(_field(event, "output_index"))
@@ -437,19 +470,41 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
             if isinstance(error, ResponsesStreamError)
             else ResponsesStreamParserError(error)
         )
+        # Stop admitting reads before yielding, and hand the current read to
+        # the one cleanup task. Consumer cancellation must not cancel it again.
+        self._interrupt_reads(failure)
+        active = self._active_read
         self._failure_task = self._ensure_loop().create_task(
-            self._fail_and_close(failure)
+            self._fail_and_close(
+                failure, active, cancel_read=active is not asyncio.current_task()
+            )
         )
         self._observe(self._failure_task)
         return self._failure_task
 
-    async def _fail_and_close(self, failure: ResponsesStreamError) -> None:
-        self._interrupt_reads(failure)
-        active = self._active_read
-        if active is not None and not active.done():
-            active.cancel()
-            with suppress(BaseException):
+    async def _fail_and_close(
+        self,
+        failure: ResponsesStreamError,
+        active: asyncio.Future[ResponsesEventLike] | None,
+        *,
+        cancel_read: bool,
+    ) -> None:
+        if active is not None:
+            # A read initiating its own close must unwind itself: cancellation
+            # could interrupt the finalizer that requested cleanup.
+            if cancel_read and not active.done():
+                active.cancel()
+            try:
                 await active
+            except (asyncio.CancelledError, StopAsyncIteration):
+                pass
+            except BaseException as error:
+                failure = ResponsesStreamSourceError(
+                    "return", error, prior_error=failure
+                )
+            finally:
+                if self._active_read is active:
+                    self._active_read = None
         if (
             isinstance(failure, ResponsesStreamSourceError)
             and failure.operation == "return"
@@ -486,7 +541,8 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
         failure = self._start_failure(ResponsesStreamAbortedError())
         with suppress(asyncio.CancelledError):
             await asyncio.shield(failure)
-        self._consumer_done = True
+        if failure.done():
+            self._consumer_done = True
 
     def _ensure_source_iterator(self) -> AsyncIterator[ResponsesEventLike]:
         if self._source_iterator is not None:
@@ -500,6 +556,9 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
         return self._source_iterator
 
     async def _read_source(self) -> tuple[bool, ResponsesEventLike | None]:
+        interrupted = self._ensure_read_interruption()
+        if interrupted.done():
+            raise interrupted.result()
         iterator = self._ensure_source_iterator()
         try:
             awaitable = iterator.__anext__()
@@ -512,15 +571,12 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
             raise ResponsesStreamSourceError("next", error) from error
         self._active_read = reading
         self._observe(reading)
-        interrupted = self._ensure_read_interruption()
         try:
             completed, _pending = await asyncio.wait(
                 (reading, interrupted), return_when=asyncio.FIRST_COMPLETED
             )
             if interrupted in completed:
-                interrupted_error = interrupted.result()
-                reading.cancel()
-                raise interrupted_error
+                raise interrupted.result()
             try:
                 event = reading.result()
             except StopAsyncIteration:
@@ -540,16 +596,17 @@ class ParsedResponsesStream(AsyncIterator[EventT], Generic[EventT, ResultT]):
                 raise ResponsesStreamSourceError("next", shape_error) from shape_error
             return False, event
         except asyncio.CancelledError:
-            reading.cancel()
-            with suppress(BaseException):
-                await reading
+            self._start_failure(ResponsesStreamAbortedError())
             raise
         finally:
-            if self._active_read is reading:
+            if self._active_read is reading and self._failure_task is None:
                 self._active_read = None
 
     async def _close_source(self) -> None:
         current = asyncio.current_task()
+        if current is self._active_read:
+            self._start_failure(ResponsesStreamAbortedError())
+            return
         if current is self._close_task:
             return
         if self._close_task is None:

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.4}/src/meta_sam_parser/_types.py

@@ -48,11 +48,20 @@ class SegmentationMaskBounds:
     bottom: float
 
 
+SegmentationMaskEncoding: TypeAlias = Literal["lossless", "one_bit"]
+"""The wire encodings of a mask payload: ``~`` selects lossless, ``!`` one_bit."""
+
+
 @dataclass(frozen=True, slots=True)
 class SegmentationMask:
-    """One complete encoded SAM 3 segmentation mask."""
+    """One complete mask exactly as the SAM API emitted it.
+
+    ``payload`` is the base85 text after the encoding marker and is never
+    partial; ``width`` and ``height`` are the raster's own dimensions, not the
+    frame's.
+    """
 
-    encoding: str
+    encoding: SegmentationMaskEncoding
     payload: str
     width: int
     height: int
@@ -76,18 +85,6 @@ class SegmentationTextRecord:
     text: str
 
 
-@dataclass(frozen=True, slots=True)
-class SegmentationPointRecord:
-    """A point associated with one object and optional frame."""
-
-    kind: Literal["point"] = field(default="point", init=False)
-    order: int
-    object_id: str
-    x: float
-    y: float
-    frame: FrameReference | None = None
-
-
 @dataclass(frozen=True, slots=True)
 class SegmentationBoxRecord:
     """A half-open or explicitly supplied box in source-media coordinates."""
@@ -112,15 +109,12 @@ class SegmentationMaskRecord:
     identity: SegmentationMaskIdentity
     revision: int
     mask: SegmentationMask
+    bounds: SegmentationMaskBounds
     frame: FrameReference | None = None
-    bounds: SegmentationMaskBounds | None = None
 
 
 SegmentationRecord: TypeAlias = (
-    SegmentationTextRecord
-    | SegmentationPointRecord
-    | SegmentationBoxRecord
-    | SegmentationMaskRecord
+    SegmentationTextRecord | SegmentationBoxRecord | SegmentationMaskRecord
 )