Skip to content

[RNE Rewrite] refactor!: add better model schema contract and validation logic - #1327

Open
barhanc wants to merge 22 commits into
rne-rewritefrom
@bh/schema-refactor
Open

[RNE Rewrite] refactor!: add better model schema contract and validation logic#1327
barhanc wants to merge 22 commits into
rne-rewritefrom
@bh/schema-refactor

Conversation

@barhanc

@barhanc barhanc commented Jul 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Description

Intoduces a new powerful and extensible mechanism for validating model contracts both during the runtime execution (mitigating e.g. internal error crashes when two input tensors should have the same dimension during runtime) and pipeline construction (matching model contract against a specified interface).

  • Introduces consistent, clean, simple and extensible contract for custom schema specification as an optional constant companion method get_model_schema returning string-encoded JSON. No need for constructing auxiliary tensors for specifying dynamic dimensions, multiple companions for different kinds, etc.
  • Introduces distinction between symbolic dims and concrete dims which represent dimension domains the model can require (includes constant, enumerated and range dims).
  • Adds extensible mechanism of specifying runtime constraints (such as dynamic dim equality, linearity) which is distinct from dim domain constraints.
  • Adds ergonomic helper functions which make the model spec specification in pipeline implementation concise yet clear.

Introduces a breaking change?

  • Yes
  • No

Type of change

  • Bug fix (change which fixes an issue)
  • New feature (change which adds functionality)
  • Documentation update (improves or adds clarity to existing documentation)
  • Other (chores, tests, code style improvements etc.)

Tested on

  • iOS (Simulator only, re-exported MLX and CoreML haven't been tested)
  • Android

Testing instructions

Models that use the companion method to get the JSON schema have not yet been updated on the SWM HF as they wait for the review of this PR. For testing you can use the models at https://huggingface.co/bhanc/scratch/tree/main/ptes.

  • Build all example apps on both Android and iOS and check that all models still work

Screenshots

Related issues

Closes #1323

Checklist

  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have updated the documentation accordingly
  • My changes generate no new warnings

Additional notes

  • The updated export scripts are on the internal gitlab on the @bh/schema-workflow branch.
  • @msluszniak I haven't been able to re-export the LFM2.5 embeddings from the @nk/universal-exporter branch. I would be grateful if you could take a look.
  • @benITo47 Please take a look if you can find some use-case which this mechanism cannot express.

@barhanc barhanc self-assigned this Jul 23, 2026
@barhanc barhanc changed the title @bh/schema refactor [RNE Rewrie] refactor: add better model schema contract and validation logic Jul 23, 2026
@barhanc barhanc linked an issue Jul 23, 2026 that may be closed by this pull request
[RNE Rewrite] Proper way to handle dynamic input shapes #1323
Open
@barhanc barhanc changed the title [RNE Rewrie] refactor: add better model schema contract and validation logic [RNE Rewrite] refactor: add better model schema contract and validation logic Jul 24, 2026
@barhanc
barhanc force-pushed the @bh/schema-refactor branch from 2f087c7 to b1d3391 Compare July 28, 2026 03:21
barhanc added 21 commits July 29, 2026 01:48
@barhanc
initial new schema implementation
4fbba60
@barhanc
wip
8cad6a5
@barhanc
ts side kinda finished
2bf12c4
@barhanc
small fix
63cf94c
@barhanc
refactor ts side
1833022
@barhanc
update
e064c9f
@barhanc
update
b1ae60a
@barhanc
update
98090af
@barhanc
refactor schema validation to use validateSpec across all tasks
d474509
@barhanc
rebase
0d7434f
@barhanc
small fix
dcab050
@barhanc
small fix
c0a2e5e
@barhanc
feat(schema): add helper methods for runtime constraints and update t…
a77bbad 
…ask specifications
@barhanc
refactor(schema): namespace schema exports and cleanup constraint hel…
42adafb 
…pers

- Re-export schema utilities under a namespaced 'schema' export in index.ts
- Re-export types flatly using 'export type *' from ./core/schema
- Group constraint helpers under 'constr' object and inline DimRef object literals in task pipelines
- Remove redundant static dimension constraint from Whisper task pipeline
@barhanc
docs(skills): update model-schema-validation skill to reflect constr …
6599e4e 
…helper and inline DimRef objects
@barhanc
docs(schema): document SpecMatch.dims and add dynamic dimension accessor
737c72f
@barhanc
docs(schema): expand JSDoc comments and clarify validation phases
ab1280a 
- Expand schema.h file-level docblock to detail the two-phase validation
  model (load-time validateSpec + runtime validateRuntimeConstraints),
  explain the two spec source paths (companion method vs MethodMeta
  fallback), and document output-dimension skipping behaviour pre-execution
- Improve individual function docstrings for parseModelSpecJson, validateSpec,
  and validateRuntimeConstraints to reflect actual behaviour more precisely
- Fix whisperSpeechToText decode method spec: replace named symbol strings
  for static constant dimensions with literal integers (1) to match schema
  semantics
@barhanc
small fix
b777dbb
@barhanc
fix attribute name
b7ccaf6
@barhanc
fix
43cc476
@barhanc
fix
cacfa78
@barhanc
barhanc force-pushed the @bh/schema-refactor branch from ef56a3f to cacfa78 Compare July 28, 2026 23:49
@barhanc
barhanc marked this pull request as ready for review July 29, 2026 00:41
@barhanc
barhanc requested review from benITo47 and msluszniak July 29, 2026 00:41
@barhanc barhanc added the feature PRs that implement a new feature label Jul 29, 2026
@barhanc barhanc changed the title [RNE Rewrite] refactor: add better model schema contract and validation logic [RNE Rewrite] refactor!: add better model schema contract and validation logic Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@msluszniak msluszniak Awaiting requested review from msluszniak
@benITo47 benITo47 Awaiting requested review from benITo47

At least 1 approving review is required to merge this pull request.

Assignees

@barhanc barhanc

Labels

feature PRs that implement a new feature refactoring

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[RNE Rewrite] Proper way to handle dynamic input shapes

1 participant

@barhanc