ponder-sdk 0.1.0__tar.gz

ponder_sdk-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.pyc
+dist/

ponder_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPond contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ponder_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: ponder-sdk
+Version: 0.1.0
+Summary: Typed native Python access to OpenPond training and learning
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: jsonschema[format]<5,>=4.23
+Requires-Dist: rfc8785<1,>=0.1.4
+Requires-Dist: typing-extensions<5,>=4.12
+Description-Content-Type: text/markdown
+
+# Ponder Python SDK
+
+Native synchronous and asynchronous access to existing OpenPond training,
+evaluation, dataset and continual-learning APIs. Python3.10+; no Node subprocess,
+Desktop application, or uv installation is required to use the installed wheel.
+Distribution `ponder-sdk`, import `ponder_sdk`, candidate version0.1.0. Name and
+publisher ownership must be verified before publication; this source is not a
+claim that a registry release exists.
+
+```sh
+pip install ponder-sdk==0.1.0
+# or: uv add ponder-sdk==0.1.0
+```
+
+Use an existing workspace API credential and explicit API origin. Do not put
+credentials in source or request URLs. The SDK does not perform a second login.
+For the official CLI use the running app's configured OpenPond home as described
+in the repository configuration guide; the SDK accepts the credential explicitly.
+
+```python
+from ponder_sdk import Client, inputs
+
+with Client(base_url="https://staging-api.openpond.ai", api_key=api_key,
+            team_id=team_id) as client:
+    capabilities = client.training.capabilities()
+    # review is an existing reviewed batch and a pinned Model configuration.
+    request: inputs.TrainingPreparationRequest = {
+        "schemaVersion": "openpond.trainingPreparationRequest.v1",
+        "teamId": team_id, "operationId": operation_id, "projectId": project_id,
+        "configuration": configuration, "batch": reviewed_batch,
+        "name": "Reviewed training", "maximumSpendUsd": approved_spend,
+    }
+    prepared = client.training.prepare_run(request)
+    # Keep the receipt. Start is a separate explicit mutation after review.
+    # client.training.start_preparation(prepared["plan"]["id"], {
+    #     "teamId": team_id, "planHash": prepared["plan"]["contentHash"],
+    #     "expectedRevision": prepared["revision"],
+    # })
+```
+
+Every resource group has matching `AsyncClient` methods and owns the same native
+HTTP pool. Use `async with AsyncClient(...)` and await calls. Close a client when
+finished; cancellation of an async call propagates normally and closes its
+response stream. If cancellation or transport loss occurs during a write, its
+outcome may be unknown: retain the original operation/idempotency key and read the
+existing operation/preparation/job before deciding whether to explicitly replay.
+Writes are never automatically retried. GET reads retry at most3times for bounded
+transport/408/429/selected5xx failures, with250/500ms backoff. Set `read_attempts=1`
+when the caller owns retry policy.
+
+`timeout` bounds connect/read/write/pool inactivity and checks elapsed time in the
+streamed body loop. Synchronous calls do not promise an absolute wall-clock
+deadline: header trickling can continue while making progress, and a blocked
+body read can overshoot the elapsed check by one read timeout. Synchronous hard
+workflow cancellation is caller-owned. Async calls additionally enforce one
+`asyncio.wait_for` deadline across connection, headers, body and retries; caller
+cancellation propagates and closes the owned response. This is not a process-kill
+deadline. Async callers can also bound an entire multi-call workflow. Responses are streamed under explicit byte bounds; compression is not
+requested or accepted, and redirects are refused. Structured `PonderError`
+exposes only a safe code/status/outcome_unknown flag, never raw remote messages,
+request bodies, transport URLs or credentials.
+
+## API and authoring boundary
+
+`client.training`, `models`, `learning`, `post_training`, `evaluation_runs`,
+`datasets` and `dataset_preparations` cover the shared operation matrix bundled in
+`operation-matrix.json`. Public `inputs` and `models` are generated TypedDict and
+union types, including nested fields, from the TypeScript Zod wire schemas.
+Runtime JSON Schema validation preserves the same default/standard string
+normalization metadata. Additional immutable-reference, request/hash, revision,
+workspace and cursor checks protect the client boundary; server domain admission
+and authorization remain authoritative. Compact training-envelope hashes are independently recomputed. Harness/Learning
+resource seals use a different existing pretty-JSON/localeCompare algorithm;
+Python preserves their authenticated declarations and pinned references without
+claiming independent recomputation or ICU portability. This affects Harness
+source/agent/release, Learning resources, dataset workspace, post-training plan
+and evaluation-manifest seals. Raw Harness file SHA256/size/complete asset closure
+and private-policy visibility are independently checked. Existing sealed resources
+can be submitted/read, while their domain admission remains server-owned. Python
+custom Harness/Reward authoring and a universal Harness hashing bridge are not
+part of this package. Portable resource formats are accepted;
+this SDK does not execute Python-authored custom Rewards or environments.
+
+Learning methods accept the existing typed command/read envelopes, including
+explicit workspace `scope`, not a second workflow language. Generic `command`
+provides the current evidence/feedback/review/batch/policy/iteration controls.
+`submit_example` and `submit_feedback` wrap the existing typed submissions.
+See `examples/continual.py` for native API orchestration. Learning resource pages
+retain `nextCursor`; callers pass it as `afterId` in the next read. Training job
+pages use `cursor`, preparations use `afterId`, and evaluation pages use their
+numeric consecutive offset cursor. Never restart pagination from the beginning
+after a failed mutation. All page APIs expose the full retained cursor.
+
+The existing estimate client contract has no current hosted route and is not a
+prerequisite for preparation/start. Known unavailable routes raise
+`unsupported_hosted_operation` before dispatch; the matrix records local/hosted
+availability. Fresh GPU catalog and explicit approved spend remain subject to
+server admission.
+
+Current executable training is discovered through capabilities: GRPO and
+reward-model jobs in the deployed host's supported model/runtime envelope.
+Recipe schema enums do not establish SFT/DPO/PPO or gradient/session support.
+Candidate decisions do not activate serving. Training start, funding, evaluation
+start/retry, acceptance and serving are separate explicit controls. Ordinary
+hosted `prepare_run` compiles an existing reviewed batch on the server; Python
+never shells out to a Node authoring compiler. Advanced `stage_artifact` and
+`create_job` require already-authored portable artifacts, immutable hashes,
+capabilities and exact approval. Dataset source ingestion/large uploads remain
+subject to the existing public format and API limits.
+
+## Development and release
+
+```sh
+uv sync --project python/openpond-sdk --locked
+pnpm exec tsx python/openpond-sdk/tools/export-wire.ts
+uv run --project python/openpond-sdk python python/openpond-sdk/tools/generate_models.py
+uv run --project python/openpond-sdk python python/openpond-sdk/tools/generate_models.py --inputs
+uv run --project python/openpond-sdk python python/openpond-sdk/tools/generate_clients.py
+uv run --project python/openpond-sdk pytest python/openpond-sdk/tests
+uv build --project python/openpond-sdk --no-sources
+```
+
+The schema asset uses versioned, lossless structural interning. One bounded
+strict decoder expands it before validation or type generation; JSON Schema
+local references, parsing policies and annotations retain their original scope.
+The shared and packaged asset bytes match.
+
+The command is a development schema exporter only; installed consumers never
+need it. Shared canonical fixtures include omitted/null, Unicode, integer-key
+ordering and JavaScript number boundaries. The canonical JSON implementation
+matches the existing protocol, including JS array-index enumeration; plain JCS
+object sorting alone would give different hashes. Python integers must be exactly
+representable as a JavaScript binary64 value rather than silently rounded.
+
+`tools/prepare_release.py` builds source/wheel distributions and records exact
+hashes without publishing. `tools/check_consumer.py` verifies the exact wheel in
+isolated temporary pip and uv environments. The manual
+`.github/workflows/release-python-sdk.yml` workflow first builds, validates and
+uploads immutable candidate artifacts after successful CI on that source commit.
+It never publishes from the build lane. After reviewing that run's manifest,
+source bindings, wheel, source distribution and consumer receipt, publish the
+same artifacts with their exact source/run/version/manifest binding:
+
+```sh
+# Run from the reviewed source ref; these are operator commands, not yet run.
+gh workflow run release-python-sdk.yml --ref REVIEWED_REF -f mode=build -f version=0.1.0
+gh run download REVIEWED_BUILD_RUN -n ponder-python-candidate -D reviewed-python-candidate
+sha256sum reviewed-python-candidate/manifest.json
+gh workflow run release-python-sdk.yml --ref REVIEWED_REF -f mode=publish -f version=0.1.0 -f candidate_run_id=REVIEWED_BUILD_RUN -f candidate_sha=REVIEWED_40_CHARACTER_COMMIT -f manifest_sha256=REVIEWED_MANIFEST_SHA256
+```
+
+The publish lane requires the protected `pypi-production` environment and
+`PONDER_SDK_PYPI_OWNER_VERIFIED=true`, set only after independent project ownership
+and exact repository/workflow/environment trusted-publisher bootstrap. No token
+or first-publication authority is inferred from the package name or build. It
+downloads the reviewed build without rebuilding, checks all artifact digests,
+reconciles any already-published exact version and uses the pinned official PyPI
+OIDC action. A mismatching existing release refuses; an ambiguous upload requires
+read-only reconciliation of those same digests before retrying. A wheel hash is
+not publisher ownership. Actual hosted qualification
+requires retained API receipts and separately authorized compute; local consumer
+checks do not claim GPU execution, wrong-team deployed denial or live serving.

ponder_sdk-0.1.0/README.md

@@ -0,0 +1,162 @@
+# Ponder Python SDK
+
+Native synchronous and asynchronous access to existing OpenPond training,
+evaluation, dataset and continual-learning APIs. Python3.10+; no Node subprocess,
+Desktop application, or uv installation is required to use the installed wheel.
+Distribution `ponder-sdk`, import `ponder_sdk`, candidate version0.1.0. Name and
+publisher ownership must be verified before publication; this source is not a
+claim that a registry release exists.
+
+```sh
+pip install ponder-sdk==0.1.0
+# or: uv add ponder-sdk==0.1.0
+```
+
+Use an existing workspace API credential and explicit API origin. Do not put
+credentials in source or request URLs. The SDK does not perform a second login.
+For the official CLI use the running app's configured OpenPond home as described
+in the repository configuration guide; the SDK accepts the credential explicitly.
+
+```python
+from ponder_sdk import Client, inputs
+
+with Client(base_url="https://staging-api.openpond.ai", api_key=api_key,
+            team_id=team_id) as client:
+    capabilities = client.training.capabilities()
+    # review is an existing reviewed batch and a pinned Model configuration.
+    request: inputs.TrainingPreparationRequest = {
+        "schemaVersion": "openpond.trainingPreparationRequest.v1",
+        "teamId": team_id, "operationId": operation_id, "projectId": project_id,
+        "configuration": configuration, "batch": reviewed_batch,
+        "name": "Reviewed training", "maximumSpendUsd": approved_spend,
+    }
+    prepared = client.training.prepare_run(request)
+    # Keep the receipt. Start is a separate explicit mutation after review.
+    # client.training.start_preparation(prepared["plan"]["id"], {
+    #     "teamId": team_id, "planHash": prepared["plan"]["contentHash"],
+    #     "expectedRevision": prepared["revision"],
+    # })
+```
+
+Every resource group has matching `AsyncClient` methods and owns the same native
+HTTP pool. Use `async with AsyncClient(...)` and await calls. Close a client when
+finished; cancellation of an async call propagates normally and closes its
+response stream. If cancellation or transport loss occurs during a write, its
+outcome may be unknown: retain the original operation/idempotency key and read the
+existing operation/preparation/job before deciding whether to explicitly replay.
+Writes are never automatically retried. GET reads retry at most3times for bounded
+transport/408/429/selected5xx failures, with250/500ms backoff. Set `read_attempts=1`
+when the caller owns retry policy.
+
+`timeout` bounds connect/read/write/pool inactivity and checks elapsed time in the
+streamed body loop. Synchronous calls do not promise an absolute wall-clock
+deadline: header trickling can continue while making progress, and a blocked
+body read can overshoot the elapsed check by one read timeout. Synchronous hard
+workflow cancellation is caller-owned. Async calls additionally enforce one
+`asyncio.wait_for` deadline across connection, headers, body and retries; caller
+cancellation propagates and closes the owned response. This is not a process-kill
+deadline. Async callers can also bound an entire multi-call workflow. Responses are streamed under explicit byte bounds; compression is not
+requested or accepted, and redirects are refused. Structured `PonderError`
+exposes only a safe code/status/outcome_unknown flag, never raw remote messages,
+request bodies, transport URLs or credentials.
+
+## API and authoring boundary
+
+`client.training`, `models`, `learning`, `post_training`, `evaluation_runs`,
+`datasets` and `dataset_preparations` cover the shared operation matrix bundled in
+`operation-matrix.json`. Public `inputs` and `models` are generated TypedDict and
+union types, including nested fields, from the TypeScript Zod wire schemas.
+Runtime JSON Schema validation preserves the same default/standard string
+normalization metadata. Additional immutable-reference, request/hash, revision,
+workspace and cursor checks protect the client boundary; server domain admission
+and authorization remain authoritative. Compact training-envelope hashes are independently recomputed. Harness/Learning
+resource seals use a different existing pretty-JSON/localeCompare algorithm;
+Python preserves their authenticated declarations and pinned references without
+claiming independent recomputation or ICU portability. This affects Harness
+source/agent/release, Learning resources, dataset workspace, post-training plan
+and evaluation-manifest seals. Raw Harness file SHA256/size/complete asset closure
+and private-policy visibility are independently checked. Existing sealed resources
+can be submitted/read, while their domain admission remains server-owned. Python
+custom Harness/Reward authoring and a universal Harness hashing bridge are not
+part of this package. Portable resource formats are accepted;
+this SDK does not execute Python-authored custom Rewards or environments.
+
+Learning methods accept the existing typed command/read envelopes, including
+explicit workspace `scope`, not a second workflow language. Generic `command`
+provides the current evidence/feedback/review/batch/policy/iteration controls.
+`submit_example` and `submit_feedback` wrap the existing typed submissions.
+See `examples/continual.py` for native API orchestration. Learning resource pages
+retain `nextCursor`; callers pass it as `afterId` in the next read. Training job
+pages use `cursor`, preparations use `afterId`, and evaluation pages use their
+numeric consecutive offset cursor. Never restart pagination from the beginning
+after a failed mutation. All page APIs expose the full retained cursor.
+
+The existing estimate client contract has no current hosted route and is not a
+prerequisite for preparation/start. Known unavailable routes raise
+`unsupported_hosted_operation` before dispatch; the matrix records local/hosted
+availability. Fresh GPU catalog and explicit approved spend remain subject to
+server admission.
+
+Current executable training is discovered through capabilities: GRPO and
+reward-model jobs in the deployed host's supported model/runtime envelope.
+Recipe schema enums do not establish SFT/DPO/PPO or gradient/session support.
+Candidate decisions do not activate serving. Training start, funding, evaluation
+start/retry, acceptance and serving are separate explicit controls. Ordinary
+hosted `prepare_run` compiles an existing reviewed batch on the server; Python
+never shells out to a Node authoring compiler. Advanced `stage_artifact` and
+`create_job` require already-authored portable artifacts, immutable hashes,
+capabilities and exact approval. Dataset source ingestion/large uploads remain
+subject to the existing public format and API limits.
+
+## Development and release
+
+```sh
+uv sync --project python/openpond-sdk --locked
+pnpm exec tsx python/openpond-sdk/tools/export-wire.ts
+uv run --project python/openpond-sdk python python/openpond-sdk/tools/generate_models.py
+uv run --project python/openpond-sdk python python/openpond-sdk/tools/generate_models.py --inputs
+uv run --project python/openpond-sdk python python/openpond-sdk/tools/generate_clients.py
+uv run --project python/openpond-sdk pytest python/openpond-sdk/tests
+uv build --project python/openpond-sdk --no-sources
+```
+
+The schema asset uses versioned, lossless structural interning. One bounded
+strict decoder expands it before validation or type generation; JSON Schema
+local references, parsing policies and annotations retain their original scope.
+The shared and packaged asset bytes match.
+
+The command is a development schema exporter only; installed consumers never
+need it. Shared canonical fixtures include omitted/null, Unicode, integer-key
+ordering and JavaScript number boundaries. The canonical JSON implementation
+matches the existing protocol, including JS array-index enumeration; plain JCS
+object sorting alone would give different hashes. Python integers must be exactly
+representable as a JavaScript binary64 value rather than silently rounded.
+
+`tools/prepare_release.py` builds source/wheel distributions and records exact
+hashes without publishing. `tools/check_consumer.py` verifies the exact wheel in
+isolated temporary pip and uv environments. The manual
+`.github/workflows/release-python-sdk.yml` workflow first builds, validates and
+uploads immutable candidate artifacts after successful CI on that source commit.
+It never publishes from the build lane. After reviewing that run's manifest,
+source bindings, wheel, source distribution and consumer receipt, publish the
+same artifacts with their exact source/run/version/manifest binding:
+
+```sh
+# Run from the reviewed source ref; these are operator commands, not yet run.
+gh workflow run release-python-sdk.yml --ref REVIEWED_REF -f mode=build -f version=0.1.0
+gh run download REVIEWED_BUILD_RUN -n ponder-python-candidate -D reviewed-python-candidate
+sha256sum reviewed-python-candidate/manifest.json
+gh workflow run release-python-sdk.yml --ref REVIEWED_REF -f mode=publish -f version=0.1.0 -f candidate_run_id=REVIEWED_BUILD_RUN -f candidate_sha=REVIEWED_40_CHARACTER_COMMIT -f manifest_sha256=REVIEWED_MANIFEST_SHA256
+```
+
+The publish lane requires the protected `pypi-production` environment and
+`PONDER_SDK_PYPI_OWNER_VERIFIED=true`, set only after independent project ownership
+and exact repository/workflow/environment trusted-publisher bootstrap. No token
+or first-publication authority is inferred from the package name or build. It
+downloads the reviewed build without rebuilding, checks all artifact digests,
+reconciles any already-published exact version and uses the pinned official PyPI
+OIDC action. A mismatching existing release refuses; an ambiguous upload requires
+read-only reconciliation of those same digests before retrying. A wheel hash is
+not publisher ownership. Actual hosted qualification
+requires retained API receipts and separately authorized compute; local consumer
+checks do not claim GPU execution, wrong-team deployed denial or live serving.

ponder_sdk-0.1.0/examples/continual.py

@@ -0,0 +1,73 @@
+"""One explicit existing continual transition or finite retained snapshot.
+
+Reservation may trigger paid host dispatch. Never replay an uncertain mutation
+with a new operation ID; use read-only reconcile/status instead.
+"""
+import argparse,asyncio,json,os
+from pathlib import Path
+from ponder_sdk import AsyncClient,ProtocolError
+from ponder_sdk.wire import validate
+
+async def main():
+    parser=argparse.ArgumentParser();parser.add_argument('action',choices=['inspect','command','reserve','reconcile','status','results','cancel','retry']);parser.add_argument('input',type=Path);parser.add_argument('output',type=Path);args=parser.parse_args()
+    raw=args.input.read_bytes()
+    if len(raw)>16777216:raise ProtocolError('input_too_large')
+    value=json.loads(raw)
+    async with AsyncClient(base_url=os.environ['OPENPOND_API_URL'],api_key=os.environ['OPENPOND_API_KEY'],team_id=os.environ['OPENPOND_TEAM_ID']) as client:
+        scope=client.team_id
+        if args.action=='inspect':response=await client.learning.inspect_policy({'action':'inspect_policy','scope':scope,'policy':value})
+        elif args.action=='reconcile':
+            value=validate('LearningCommandSchema',value,request=True)
+            if value.get('action')!='reserve_iteration' or value['trigger']['kind']!='manual':raise ProtocolError('manual_reservation_command_required')
+            inspection=await client.learning.inspect_policy({'action':'inspect_policy','scope':scope,'policy':value['policy']})
+            if not inspection['chain']:raise ProtocolError('reservation_not_observed')
+            cursor=None;seen=set();response=None
+            for _ in range(10):
+                page=await client.learning.list({'action':'list','scope':scope,'kind':'reservation','parentId':inspection['chain']['id'],'limit':100,**({'afterId':cursor} if cursor else {})})
+                reservation=next((r for r in page['items'] if r['policy']==value['policy'] and r['trigger']==value['trigger']),None)
+                if reservation:
+                    iteration=await client.learning.get({'action':'get','scope':scope,'kind':'iteration','id':reservation['iterationId']})
+                    response={'reservation':reservation,'iteration':iteration};break
+                cursor=page['nextCursor']
+                if not cursor:break
+                if cursor in seen:raise ProtocolError('repeated_cursor')
+                seen.add(cursor)
+            if response is None:raise ProtocolError('reservation_not_observed_no_replay')
+        elif args.action in ('command','reserve'):
+            if (args.action=='reserve')!=(value.get('action')=='reserve_iteration'):raise ProtocolError('explicit_reserve_required')
+            if args.action=='reserve' and value['trigger']['kind']!='manual':raise ProtocolError('manual_trigger_required')
+            operation=await client.learning.command({'scope':scope,'command':value})
+            iteration=next((r for r in operation['resources'] if r['schemaVersion']=='openpond.learningIteration.v1'),None)
+            response={'operation':operation,**({'iteration':iteration} if iteration else {})}
+        else:
+            retained=value['iteration']
+            iteration=await client.learning.get({'action':'get','scope':scope,'kind':'iteration','id':retained['id']})
+            if iteration['policy']!=retained['policy'] or iteration['dispatchId']!=retained['dispatchId']:raise ProtocolError('iteration_binding_changed')
+            if args.action in ('cancel','retry'):
+                if args.action=='retry':
+                    dispatch=await client.learning.get({'action':'get','scope':scope,'kind':'dispatch','id':iteration['dispatchId']})
+                    if dispatch['iterationId']!=iteration['id'] or dispatch['state']!='blocked':raise ProtocolError('dispatch_not_blocked')
+                operation=await client.learning.command({'scope':scope,'command':{'action':'cancel_iteration' if args.action=='cancel' else 'retry_iteration_dispatch','operationId':value['operationId'],'iterationId':iteration['id'],'expectedRevision':iteration['revision']}})
+                response={'operation':operation,'iteration':next((r for r in operation['resources'] if r['schemaVersion']=='openpond.learningIteration.v1'),iteration)}
+            else:
+                page=await client.learning.list({'action':'list','scope':scope,'kind':'dispatch','parentId':iteration['id'],'limit':2})
+                if page['nextCursor'] or len(page['items'])>1 or any(d['id']!=iteration['dispatchId'] for d in page['items']):raise ProtocolError('ambiguous_dispatch_identity')
+                dispatch=page['items'][0] if page['items'] else None
+                # Worker commits iteration and dispatch together, but these HTTP
+                # reads are separate snapshots. Refresh once and refuse a race.
+                iteration=await client.learning.get({'action':'get','scope':scope,'kind':'iteration','id':retained['id']})
+                if iteration['policy']!=retained['policy'] or iteration['dispatchId']!=retained['dispatchId']:raise ProtocolError('iteration_binding_changed')
+                if dispatch and (dispatch['iterationId']!=iteration['id'] or dispatch['policy']!=iteration['policy'] or dispatch['execution']!=iteration['trainingJob']):raise ProtocolError('snapshot_changed_read_again')
+                if dispatch is None and iteration['trainingJob'] is not None:raise ProtocolError('snapshot_changed_read_again')
+                job=await client.training.get_job(iteration['trainingJob']['id']) if iteration['trainingJob'] else None
+                if job and (job['id']!=iteration['trainingJob']['id'] or job['submissionHash']!=iteration['trainingJob']['contentHash']):raise ProtocolError('training_execution_identity_mismatch')
+                if args.action=='results' and (not dispatch or dispatch['state']!='settled' or not dispatch['terminalReceipt']):raise ProtocolError('terminal_cleanup_receipt_not_observed')
+                if args.action=='results' and job is None and (iteration['status']!='cancelled' or dispatch['execution'] is not None):raise ProtocolError('terminal_job_not_observed')
+                response={'iteration':iteration,'dispatch':dispatch,'job':job}
+                if args.action=='results' and job:response['outputs']=await client.training.outputs(job['id'])
+        fd=os.open(args.output,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)
+        with os.fdopen(fd,'w',encoding='utf-8') as file:json.dump(response,file,ensure_ascii=True)
+    print('Saved one retained transition/snapshot. Local timeout does not cancel remote work.')
+
+# Total client workflow is bounded, including multiple sequential public reads.
+asyncio.run(asyncio.wait_for(main(),timeout=120))

ponder_sdk-0.1.0/examples/manual.py

@@ -0,0 +1,50 @@
+"""Native reviewed-batch orchestration; each mutation is selected explicitly.
+
+OPENPOND_API_URL / OPENPOND_API_KEY / OPENPOND_TEAM_ID are existing credentials,
+not a second login. Never execute this example as a test without approval.
+"""
+import argparse,asyncio,json,os
+from datetime import datetime,timezone
+from pathlib import Path
+from ponder_sdk import AsyncClient,ProtocolError
+
+async def main():
+    parser=argparse.ArgumentParser()
+    parser.add_argument('action',choices=['prepare','start','status','results','cancel'])
+    parser.add_argument('input',type=Path);parser.add_argument('output',type=Path)
+    args=parser.parse_args()
+    raw=args.input.read_bytes()
+    if len(raw)>1048576:raise ProtocolError('input_too_large')
+    value=json.loads(raw)
+    async with AsyncClient(base_url=os.environ['OPENPOND_API_URL'],api_key=os.environ['OPENPOND_API_KEY'],team_id=os.environ['OPENPOND_TEAM_ID']) as client:
+        if args.action=='prepare':
+            capabilities=await client.training.capabilities()
+            if 'grpo' not in capabilities['methods']:raise ProtocolError('grpo_not_available')
+            response=await client.training.prepare_run(value)
+        else:
+            retained=await client.training.get_preparation(value['plan']['id'])
+            if retained['plan']['contentHash']!=value['plan']['contentHash']:raise ProtocolError('preparation_identity_mismatch')
+            if args.action=='start':
+                if retained['state']!='prepared':raise ProtocolError('reconcile_existing_preparation')
+                # No estimate endpoint is invented. The retained request already
+                # binds explicit maximum spend; fresh offerings/server admission apply.
+                catalog=await client.training.gpu_catalog()
+                if datetime.fromisoformat(catalog['expiresAt'].replace('Z','+00:00'))<=datetime.now(timezone.utc):raise ProtocolError('gpu_catalog_expired')
+                catalog_fd=os.open(args.output.with_suffix(args.output.suffix+'.catalog.json'),os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)
+                with os.fdopen(catalog_fd,'w',encoding='utf-8') as file:json.dump(catalog,file)
+                response=await client.training.start_preparation(retained['plan']['id'],{'teamId':client.team_id,'planHash':retained['plan']['contentHash'],'expectedRevision':retained['revision']})
+            elif args.action=='cancel':
+                if retained['jobId']:
+                    job=await client.training.get_job(retained['jobId'])
+                    response=await client.training.cancel_job(job['id'],{'expectedVersion':job['version']})
+                else:response=await client.training.cancel_preparation(retained['plan']['id'],{'teamId':client.team_id,'planHash':retained['plan']['contentHash'],'expectedRevision':retained['revision']})
+            elif args.action=='status':response={'preparation':retained,'job':await client.training.get_job(retained['jobId']) if retained['jobId'] else None}
+            else:
+                if not retained['jobId']:raise ProtocolError('preparation_not_submitted')
+                response=await client.training.outputs(retained['jobId'])
+        # Receipts may contain private evidence. Do not print them to a shared log.
+        fd=os.open(args.output,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)
+        with os.fdopen(fd,'w',encoding='utf-8') as file:json.dump(response,file,ensure_ascii=True)
+    print('Saved the retained response. Execution/acceptance remain separate gates.')
+
+asyncio.run(asyncio.wait_for(main(),timeout=120))

ponder_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "ponder-sdk"
+version = "0.1.0"
+description = "Typed native Python access to OpenPond training and learning"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.28.1,<1", "jsonschema[format]>=4.23,<5", "rfc8785>=0.1.4,<1", "typing-extensions>=4.12,<5"]
+classifiers = ["Typing :: Typed", "Programming Language :: Python :: 3"]
+
+[dependency-groups]
+dev = ["pytest>=8.3,<10", "tomli>=2,<3; python_version < '3.11'"]
+
+[build-system]
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ponder_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "examples", "tools", "tests", "README.md", "LICENSE", "pyproject.toml", "uv.lock"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.uv]
+required-version = ">=0.9.11"

ponder_sdk-0.1.0/src/ponder_sdk/__init__.py

@@ -0,0 +1,7 @@
+"""Ponder Python SDK. Training execution remains capability-gated by the host."""
+from .client import Client,AsyncClient
+from .errors import PonderError,ProtocolError
+from .wire import canonical_json,canonical_sha256
+from . import models,inputs
+__version__='0.1.0'
+__all__=['Client','AsyncClient','PonderError','ProtocolError','canonical_json','canonical_sha256','models','inputs']

ponder_sdk-0.1.0/src/ponder_sdk/canonical-identities.json

@@ -0,0 +1,94 @@
+{
+  "schemaVersion": "openpond.canonicalIdentities.v1",
+  "vectors": [
+    {
+      "value": "😀",
+      "canonical": "\"😀\"",
+      "sha256": "7a0c50b92434b015545fe93ab723db2d4b2cdd14a441405624a9ce8be29f1d5a"
+    },
+    {
+      "value": "\ud800",
+      "canonical": "\"\\ud800\"",
+      "sha256": "8c0c59dd0d275aadcd462a5fe12eb352cbdfeaf961eae4f85a4660521df7d2f5"
+    },
+    {
+      "value": {
+        "__proto__": {
+          "retained": true
+        },
+        "ordinary": 1
+      },
+      "canonical": "{\"__proto__\":{\"retained\":true},\"ordinary\":1}",
+      "sha256": "8d52a329a7fb2167e4d72deefb9d41ed2c78233596ebff7b240d78eab348c1eb"
+    },
+    {
+      "value": {
+        "2": 2,
+        "10": 1,
+        "4294967294": 4,
+        "01": 3,
+        "4294967295": 5
+      },
+      "canonical": "{\"2\":2,\"10\":1,\"4294967294\":4,\"01\":3,\"4294967295\":5}",
+      "sha256": "7c26965db131091a44f39acaf6c3942dd756609639f983920dc6bdb0142cd42c"
+    },
+    {
+      "value": "\ud800",
+      "canonical": "\"\\ud800\"",
+      "sha256": "8c0c59dd0d275aadcd462a5fe12eb352cbdfeaf961eae4f85a4660521df7d2f5"
+    },
+    {
+      "value": null,
+      "canonical": "null",
+      "sha256": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b"
+    },
+    {
+      "value": {
+        "omitted": "kept",
+        "present": null
+      },
+      "canonical": "{\"omitted\":\"kept\",\"present\":null}",
+      "sha256": "d0da19ce46bbcb4461108e6f2c2f0516e3318cd7fd92bdff2c03ed22eee8ac83"
+    },
+    {
+      "value": {
+        "unicode": "雪😀é",
+        "keys": {
+          "😀": 1,
+          "": 2
+        }
+      },
+      "canonical": "{\"keys\":{\"😀\":1,\"\":2},\"unicode\":\"雪😀é\"}",
+      "sha256": "3423a9dd306cadadef53d0a5f3ed563011be1c5535aa070c1cf9241b036acdbe"
+    },
+    {
+      "value": [
+        0,
+        0,
+        1,
+        0.000001,
+        1e-7,
+        100000000000000000000,
+        1e+21,
+        9007199254740991,
+        1000000000000000100
+      ],
+      "canonical": "[0,0,1,0.000001,1e-7,100000000000000000000,1e+21,9007199254740991,1000000000000000100]",
+      "sha256": "273ae0fdf747be4c44e06422fb5b08eed98820708f932cc3cfc74f749a0978af"
+    },
+    {
+      "value": {
+        "nested": [
+          true,
+          false,
+          {
+            "b": 2,
+            "a": 1
+          }
+        ]
+      },
+      "canonical": "{\"nested\":[true,false,{\"a\":1,\"b\":2}]}",
+      "sha256": "421f4604e52b696d8eb084190e28030fe39187d8d5adced1fa8fadef2dd9ded0"
+    }
+  ]
+}