[TS/Python] Cross-SDK parity and Training-specs branch coordination

[aruniverse]

Context

The TypeScript and Python SDKs cover the same iTwin Platform APIs but have drifted on features, and — more urgently — the Training specs are in flux across three active branches in ways that will silently undo fixes if not coordinated.

Verified on main @ dafc2ce plus origin/feature/AnalyseV2, origin/feature/AnalyseRelease26.0.2, origin/feature/2_TrainingSpecs.

⚠️ Urgent: Training specs branch coordination

• main (TS): JobType.TRAINING_O2D + TRAINING_S3D exist; JobSchema literals are typo'd ("TraningO2D"/"TraningS3D", job.ts:238,243).
• feature/AnalyseV2 and feature/AnalyseRelease26.0.2 (June 2026, commit 27a25de "Updated training specs for release"): TrainingO2D deleted entirely (enum, create schema, union variant); TraningS3D still typo'd (line 236 there).
• Python main: no training specs at all.
• feature/2_TrainingSpecs (Python): specifications/training.py (+103), service/estimation.py (+59), service methods (+131), data_handler changes, tests — the "missing" Python features already exist here.

Implications:

1. Fixing the TS typo on main alone (tracked in the correctness sub-issue) will merge-conflict with the Analyse branches and the typo re-ships on the next Analysis release. The fix must land there too (S3D-only where O2D is deleted), or merge order must be agreed first.
2. Do not "fix" TS→Python TrainingO2D parity blindly — the newest release line deletes TrainingO2D in both SDKs. Resolve the product question (is TrainingO2D staying?) before parity work.

Tasks:

• Decide TrainingO2D's fate across both SDKs (owner: whoever owns the Analyse release line)
• Land the TraningS3D typo fix on feature/AnalyseV2 + feature/AnalyseRelease26.0.2 (or document merge order)
• Merge/reconcile feature/2_TrainingSpecs into Python main (training + estimation) — this is merge work, not greenfield

Parity gaps (verified on main)

Dimension	TypeScript	Python (reality_capture 2.5.0)	Action
Training specs	Present (typo'd in JobSchema)	Absent on main; exists on feature/2_TrainingSpecs	Resolve branch question above
Cost estimation	Present (estimation.ts, estimateCost at service.ts:130–138)	Absent on main; on the same feature branch	Merge branch
Blob I/O	Sequential + full in-memory buffering	Parallel (ThreadPool ≤32) + streaming, max_concurrency=16	TS side tracked in data-handler sub-issue
authoring lifecycle	Missing	Present (data_handler.py:182–207)	TS side tracked in data-handler sub-issue
Windows blob paths	path.join → \ corruption (data_handler.ts:28,116)	Same flaw (os.path.join, data_handler.py:113)	Fix both sides
Reality-data endpoints on service	Absent (delegated to reality-data-client)	Present (service.py:474–601 incl. /readaccess /writeaccess)	TS side tracked in data-handler sub-issue
point_cloud_conversion	No file; commented references (job.ts:18,54,120; barrels)	45-line file, 100% commented	Decide: implement or delete in both
Public API surface	Barrel exports (with gaps)	No __init__.py re-exports at all — deep module paths required (from reality_capture.service.service import …)	Add Python re-exports
User-Agent	Missing SDK version (service.ts:39 — trailing slash)	Includes __version__ (service.py:48)	Fix TS
Response model	Response<T> class	Response(tuple) — mirrored field-for-field	Keep aligned (predicate-union refactor preserves fields)
Unit tests	30 files, nyc 90% per-file, but data_handler.ts excluded and untested	14 files incl. 554-line test_data_handler.py + doc-example tests	TS data_handler tests tracked in data-handler sub-issue

Ongoing guard

• Add a parity checklist to the repo root (job types × features × SDKs) and require updates in PRs that touch specs or service methods — the training/estimation drift and the point_cloud_conversion limbo happened because no such artifact exists.

[dbiguenet]

Hi @aruniverse , TrainingO2D has been removed, at least for now. The typo has been fixed too. See #306
I'm taking a look at the other parity gaps

[dbiguenet]

@aruniverse I have created a pull request to address the parity gaps. It does not include the fixes for TS data-handler.
Instead of the parity checklist, Cyril added an agent, see https://github.com/iTwin/reality-capture/blob/main/.github/agents/sdk_alignment.agent.md is that ok for you?