openpond-sdk 0.0.18 → 0.1.0

package/LEARNING.md

@@ -0,0 +1,44 @@
+# Submit task evidence
+
+Install `openpond-sdk` and use `OpenPondLearningClient` from
+`openpond-sdk/learning`. Task definitions, reusable Rewards, grading, review,
+batching and HTTP schemas are owned by `@openpond/evals/learning`; see that
+package's `LEARNING.md` for the full contract and host responsibilities.
+
+The runnable examples in `examples/learning` submit one JSON record through an
+existing source. Create a task format and source in Models → Tasksets → Task
+formats first. The sample uses an input object with `question` and an output
+object with `answer`; adapt the record to your published format. The scripts read
+the source's exact task-definition reference from the server.
+
+Set `OPENPOND_API_KEY`, `OPENPOND_API_URL` and `OPENPOND_LEARNING_SCOPE` in your
+shell, then run one of:
+
+```sh
+node --experimental-strip-types submit.ts SOURCE_ID example.json
+python3 submit.py SOURCE_ID example.json
+```
+
+Use the URL of the execution owner: a local OpenPond server or the hosted API
+where the learning service is deployed. The server authorizes the requested
+profile/team scope. The SDK and Python example send the selected scope in
+`X-OpenPond-Team-Id` so hosted requests select that team before authorization;
+the local server uses the profile scope in the request body. These variables are example configuration, not arguments
+that should be committed with credentials.
+
+Assign stable example/attempt identities and preserve `idempotencyKey`, timestamp
+and content on retries. A different record must use a different key. Submission
+records evidence; it does not approve the task or observed response for training.
+The failed observed answer in the sample is intentional. Grade it, propose the
+correct target, grade that target separately, and approve it in Example review.
+
+For feedback, call `client.submitFeedback` with a
+`openpond.taskFeedback.v1` envelope. Preserve source/example/attempt identity,
+use a separate stable idempotency key, and set `expectedEvidenceHash` to the
+evidence hash when targeting a specific revision. Feedback may arrive before
+the example and stays pending until review. Corrections do not mutate sealed
+historical batches.
+
+All client requests support an optional `AbortSignal`. Aborting a request does
+not cancel remote compute; use `cancel_grade` and read the authoritative terminal
+job state. Page through list responses with `nextCursor` as `afterId`.

package/README.md

@@ -1,5 +1,7 @@
 # `openpond-sdk`
 
+See [task evidence and learning](./LEARNING.md) for reusable Rewards, task-format publication, SDK/HTTP intake, grading, review and approved batches.
+
 The OpenPond SDK is the server-side TypeScript client for running agentic work in OpenPond sandboxes. It gives Node.js applications, Next.js route handlers, workers, and backend services a small API for creating sandboxes, executing commands, managing files and runtimes, and running a model/tool loop in an isolated workspace.
 
 OpenPond is an open-source agent orchestration system for doing durable work with any model, provider, or subscription. The desktop app, CLI/TUI, and this SDK live in the same repository and share the sandbox client implementation. Desktop builds use the workspace source directly; installing this package from npm is only for external applications.