Add frame_format parameter to VideoScene for PNG support by vinay553 · Pull Request #451 · scaleapi/nucleus-python-client · GitHub

Add FRAME_FORMAT_KEY constant
Add frame_format parameter to VideoScene dataclass
Update to_payload() to include frame_format when set
Supports 'jpeg' (default) or 'png' for lossless frame extraction
Bump version to 0.17.12
Remove broken test

Greptile Summary

This PR adds an optional frame_format parameter to VideoScene to support PNG (lossless) frame extraction when uploading videos via video_location, defaulting to JPEG. It also bumps the version to 0.17.12 and removes a broken integration test.

Bug: VideoScene.from_json() was not updated to deserialize the new frame_format field, so round-tripping through to_payload() → from_json() will silently drop it.
The validate() method does not enforce that frame_format is one of the documented valid values ("jpeg" or "png").
No unit tests were added for the new frame_format parameter (e.g., verifying serialization/deserialization or validation of invalid values).
The removed test (test_job_listing_and_retrieval) is unrelated to the feature being added.

Confidence Score: 2/5

This PR has a deserialization bug in from_json() that will cause data loss when round-tripping VideoScenes with frame_format set.
The from_json() method was not updated alongside to_payload(), creating an asymmetry where frame_format is serialized but never deserialized. This is a functional bug that will affect any code path that reconstructs a VideoScene from JSON (e.g., the existing test fixtures use from_json). Additionally, there are no new tests for the feature.
nucleus/scene.py — the from_json() method needs to be updated to include frame_format, and validate() should enforce valid values.

Important Files Changed

Filename	Overview
nucleus/scene.py	Adds frame_format field and serialization in to_payload(), but from_json() does not deserialize it, breaking round-trip consistency. Also lacks input validation for the new parameter.
nucleus/constants.py	Adds FRAME_FORMAT_KEY constant in alphabetical order. Clean, no issues.
CHANGELOG.md	Documents the new frame_format parameter with a usage example. Well-formatted.
pyproject.toml	Version bump from 0.17.11 to 0.17.12. Straightforward change.
tests/test_jobs.py	Removes test_job_listing_and_retrieval integration test described as broken. No replacement test added for the new frame_format feature.

Sequence Diagram

sequenceDiagram
    participant User
    participant VideoScene
    participant Payload as JSON Payload
    participant API as Nucleus API

    User->>VideoScene: Create with frame_format="png"
    VideoScene->>VideoScene: validate()
    VideoScene->>Payload: to_payload()
    Note over Payload: Includes frame_format: "png"
    Payload->>API: Upload scene

    API-->>Payload: Return scene JSON
    Payload->>VideoScene: from_json(payload)
    Note over VideoScene: ⚠️ frame_format is lost<br/>(not extracted from payload)

Last reviewed commit: 6341865

- Add FRAME_FORMAT_KEY constant - Add frame_format parameter to VideoScene dataclass - Update to_payload() to include frame_format when set - Supports 'jpeg' (default) or 'png' for lossless frame extraction - Bump version to 0.17.12

To be merged after https://github.com/scaleapi/scaleapi/pull/132674.

Looks good.
Since I was the only one who has redeployed a new SDK version in a while, lmk if help is needed for that part once this is merged.

Worth to take a look at greptile's comment as well

Why is this considered broken?

CLIENT.get_job(fetch_id)

Throws a 401 error. Honestly no one uses Nucleus jobs anymore though perhaps you'll use it for deduping.

I changed/fixed this job as part of this pr, so prob best to just undo this change from this pr

@greptileai review this PR

5 files reviewed, 1 comment

Edit Code Review Agent Settings | Greptile

Additional Comments (1)

nucleus/scene.py
from_json doesn't restore frame_format

to_payload() correctly serializes frame_format into the payload (line 703-704), but from_json() does not extract it when deserializing. This means a round-trip through to_payload() → from_json() will silently drop the frame_format field. The existing test fixture video_scenes in tests/test_video_scene.py uses from_json to reconstruct scenes, so any scene with a frame_format set will lose that value.

        return cls(
            reference_id=payload[REFERENCE_ID_KEY],
            frame_rate=payload.get(FRAME_RATE_KEY, None),
            items=items,
            metadata=payload.get(METADATA_KEY, {}),
            video_location=payload.get(VIDEO_URL_KEY, None),
            tracks=tracks,
            frame_format=payload.get(FRAME_FORMAT_KEY, None),
        )

Prompt To Fix With AI

This is a comment left during a code review.
Path: nucleus/scene.py
Line: 672-679

Comment:
**`from_json` doesn't restore `frame_format`**

`to_payload()` correctly serializes `frame_format` into the payload (line 703-704), but `from_json()` does not extract it when deserializing. This means a round-trip through `to_payload()` → `from_json()` will silently drop the `frame_format` field. The existing test fixture `video_scenes` in `tests/test_video_scene.py` uses `from_json` to reconstruct scenes, so any scene with a `frame_format` set will lose that value.

```suggestion
        return cls(
            reference_id=payload[REFERENCE_ID_KEY],
            frame_rate=payload.get(FRAME_RATE_KEY, None),
            items=items,
            metadata=payload.get(METADATA_KEY, {}),
            video_location=payload.get(VIDEO_URL_KEY, None),
            tracks=tracks,
            frame_format=payload.get(FRAME_FORMAT_KEY, None),
        )
```

How can I resolve this? If you propose a fix, please make it concise.

vinay553 force-pushed the add-png-frame-format branch 2 times, most recently from 7278cf5 to 5066528 Compare January 28, 2026 17:02

Add frame_format parameter to VideoScene for PNG support

6341865

- Add FRAME_FORMAT_KEY constant - Add frame_format parameter to VideoScene dataclass - Update to_payload() to include frame_format when set - Supports 'jpeg' (default) or 'png' for lossless frame extraction - Bump version to 0.17.12

vinay553 force-pushed the add-png-frame-format branch from 5066528 to 6341865 Compare January 28, 2026 18:10

vinay553 requested review from a team and edwinpav January 28, 2026 18:19

edwinpav approved these changes Jan 28, 2026

View reviewed changes

greptile-apps Bot reviewed Feb 23, 2026

View reviewed changes

-              def test_job_listing_and_retrieval(CLIENT):
-                  jobs = CLIENT.list_jobs()
-                  assert len(jobs) > 0, "No jobs found"
-                  fetch_id = jobs[0].job_id
-                  fetched_job = CLIENT.get_job(fetch_id)
-                  # job_last_known_status can change
-                  fetched_job.job_last_known_status = jobs[0].job_last_known_status
-                  assert fetched_job == jobs[0]

Add frame_format parameter to VideoScene for PNG support by vinay553 · Pull Request #451 · scaleapi/nucleus-python-client · GitHub

Uh oh!

Add frame_format parameter to VideoScene for PNG support - #451

Add frame_format parameter to VideoScene for PNG support#451
vinay553 wants to merge 1 commit into
masterfrom
add-png-frame-format

vinay553 commented Jan 28, 2026 •
edited by greptile-apps Bot
Loading

Uh oh!

Uh oh!

vinay553 commented Jan 28, 2026

Uh oh!

edwinpav left a comment •
edited
Loading

Uh oh!

Uh oh!

edwinpav Jan 28, 2026

Uh oh!

vinay553 Jan 29, 2026

Uh oh!

edwinpav Mar 2, 2026

Uh oh!

edwinpav commented Feb 23, 2026

Uh oh!

greptile-apps Bot left a comment

Uh oh!

greptile-apps Bot commented Feb 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add frame_format parameter to VideoScene for PNG support by vinay553 · Pull Request #451 · scaleapi/nucleus-python-client · GitHub

Uh oh!

Add frame_format parameter to VideoScene for PNG support - #451

Add frame_format parameter to VideoScene for PNG support#451vinay553 wants to merge 1 commit intomasterscaleapi/nucleus-python-client:masterfrom add-png-frame-formatscaleapi/nucleus-python-client:add-png-frame-formatCopy head branch name to clipboard

Conversation

vinay553 commented Jan 28, 2026 • edited by greptile-apps Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 2/5

Important Files Changed

Sequence Diagram

Uh oh!

vinay553 commented Jan 28, 2026

Uh oh!

edwinpav left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edwinpav Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

vinay553 Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

edwinpav Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

edwinpav commented Feb 23, 2026

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Feb 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add frame_format parameter to VideoScene for PNG support#451
vinay553 wants to merge 1 commit into
masterfrom
add-png-frame-format

vinay553 commented Jan 28, 2026 •
edited by greptile-apps Bot
Loading

edwinpav left a comment •
edited
Loading