Release v0.5.0

[lchoquel]

Release v0.5.0

Bumps version from 0.4.0 to 0.5.0.

Changelog

Added

• Input preparation: upload_file and prepare_inputs (hosted upload capability). The Python counterpart of @pipelex/sdk's uploadFile / prepareInputs, in parity. client.upload_file(source, *, filename=None, content_type=None) uploads one local asset — a filesystem path (str/Path) or raw bytes — and returns an UploadRecord (uri, content_type, size, filename) assembled client-side. client.prepare_inputs(*, files, pipe_ref=None, inputs) resolves the target pipe's declared signature from the explicit inputs template, interprets the caller's compact inputs top-down against it (the file signal is the canonical Image/Document content shape — a {"url": …} dict — mirroring the runtime's input_normalizer), uploads the file-bearing values, and returns PreparedInputs: a copy-on-write rewrite of inputs with each asset reference replaced by canonical content carrying pipelex-storage:// in url, plus one UploadRecord per prepared asset. HTTP(S) URLs and existing pipelex-storage:// URIs pass through unchanged; data URLs and local/byte sources are uploaded; the same source referenced twice uploads once (dedup by source identity); all failures are raised before any run is created. Failures are typed per category: InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError (all extend InputPreparationError). prepare_inputs takes the method closure as inline files; catalog method_id resolution and opt-in http(s) ingest are deferred and additive. See docs/input-preparation.md.

• build_inputs route (POST /v1/build/inputs). Closes the /v1/build/* parity gap the Python SDK had — client.build_inputs(BuildInputsRequest) projects a pipe's declared inputs as a fill-in template, returning a 200 verdict discriminated on is_valid (BuildInputsValidReport | CrateInvalidReport); a no-verdict condition throws ApiResponseError. It is the signature source prepare_inputs reads (with explicit=True). Models live in pipelex_sdk/build_models.py.

• Typed run usage: RunResults.tokens_usages + RunResults.usage_assembly_error. The per-call usage records a run produces — token counts by category, the server-computed cost in USD, model name and id, the pipe that made the call, job-kind fields and timing, for LLM and img-gen/extract/search calls alike — are now first-class typed fields instead of riding model_extra. Records validate into a new TokensUsageRecord model (pipelex_sdk/runs.py) mirroring the wire contract specified in the MTHDS protocol spec. Both paths populate the pair: the hosted durable path reads it off GET /v1/runs/{id}/results (which unpacks the runner's tokens_usages.json artifact), and the blocking fallback lifts the same pair out of the execute response's extension-open pipe_output — so result.tokens_usages reads the same regardless of which path ran.

  Note that the rate table (unit_costs) no longer crosses the wire: a record now carries the computed cost for the call instead, which is None when the model has no rate table at all (own-GPU, mock, dry run) and 0 when a rate table priced it at zero. There is no run-level aggregate — sum the records.

  tokens_usages is None whenever usage assembly produced no list (it was off, it broke, or the run was delivered before the artifact existed) and [] when assembly ran and no inference happened; usage_assembly_error is the only field separating a broken assembly from an off one. TokensUsageRecord keeps every field optional and is extension-open, so durable artifacts written before the contract shipped — relayed verbatim, never migrated — still parse: cost and pipe_code come back None, and the legacy job_metadata / unit_costs survive in model_extra. Enum-ish fields (model_type, job_category, unit_job_id) are open sets typed as plain str, so runtime enum churn stays non-breaking.

Changed

• RunResults.pipe_output is now DictPipeOutputAbstract | None, was dict[str, Any] | None (breaking). The blocking path already parsed the protocol model and then threw the types away with a .model_dump() round-trip; it now carries the parsed model straight through. Read the working memory as attributes — result.pipe_output.working_memory.root["out"].content — rather than nested dict keys. The durable path still leaves it None.

🤖 Generated with Claude Code

---

Summary by cubic

Release v0.5.0 adds hosted input preparation (upload_file, prepare_inputs), introduces build_inputs for signature templates, and exposes typed run-usage records on results. It also changes RunResults.pipe_output to a typed model. Adds a WIP doc with deferred review findings (no code changes).

• New Features

  • Input preparation: client.upload_file(source, filename?, content_type?) and client.prepare_inputs(files, pipe_ref?, inputs) rewrite file inputs to pipelex-storage:// URLs, pass through http(s)/existing URIs, dedup repeated sources, and raise clear typed errors. Mirrors @pipelex/sdk.
  • build_inputs support: client.build_inputs(BuildInputsRequest) returns the explicit inputs template with an is_valid verdict; used by prepare_inputs.
  • Typed run usage: RunResults.tokens_usages and usage_assembly_error validate into TokensUsageRecord and are available on both hosted and blocking paths; each record includes per-call token counts and computed USD cost.

• Migration

  • RunResults.pipe_output is now DictPipeOutputAbstract | None (was dict). Access working memory via attributes, e.g. result.pipe_output.working_memory.root["out"].content.

^{Written for commit 4ef1d1e. Summary will update on new commits.}

[greptile-apps]

Greptile Summary

This PR releases v0.5.0 with hosted input preparation and typed run usage. The main changes are:

• Adds file upload and signature-driven input preparation.
• Adds the /v1/build/inputs client route and models.
• Adds typed per-call usage records to run results.
• Preserves the protocol model for blocking-run pipe output.
• Updates documentation, tests, and package versions.

Confidence Score: 4/5

The upload rejection mapping needs a fix before merging; empty list templates can also bypass file preparation.

Some valid asset rejections are exposed as transport failures. Empty list templates can leave raw file values in prepared inputs. The main build-input and run-usage paths otherwise preserve their documented shapes.

pipelex_sdk/upload.py and pipelex_sdk/prepare_inputs.py

T-Rex Logs

What T-Rex did

• The focused pytest run reproduced asset rejections surfacing as transport errors when uploading assets through the public upload_file path, with HTTP 400 and 422 cases triggering UploadTransportError rather than RejectedAssetError, and it surfaced the originating ApiResponseError with full traces.
• After the implementation revisions (9ca1147 and then bba5074), the test harness shows the prepare_inputs path is available, captures the expected requests and a successful rewritten upload, and the resulting upload record includes URI, filename, application/octet-stream content type, and a 16-byte size.
• Artifacts from both proofs include the repro harness, the stack traces, and related logs that enable inspection of the observed upload behavior and the rewritten upload result.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
pipelex_sdk/prepare_inputs.py	Adds template-guided asset discovery, upload deduplication, data URL decoding, and copy-on-write input rewriting.
pipelex_sdk/upload.py	Adds path and byte upload normalization plus semantic error mapping.
pipelex_sdk/build_models.py	Adds discriminated request and response models for explicit input templates.
pipelex_sdk/client.py	Exposes the new build, upload, and preparation APIs and maps blocking usage data into run results.
pipelex_sdk/runs.py	Adds extension-open usage records and types blocking pipe output with the protocol model.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
pipelex_sdk/upload.py:101-103
**Asset Rejections Become Transport Errors**

When the upload endpoint rejects an asset with a client-error status other than 401, 403, 404, or 413, this fallback raises `UploadTransportError`. A validation rejection such as 400 or 422 is therefore reported as a network or server failure instead of the documented `RejectedAssetError`, so callers cannot handle rejected assets by category.

### Issue 2 of 2
pipelex_sdk/prepare_inputs.py:155-160
**Empty List Template Skips Uploads**

If an explicit template represents a multiple file input with an empty list, the truthiness check skips the element walk. Caller values such as a list of raw bytes then remain unprepared, and the later run receives bytes instead of canonical `{"url": ...}` content.

_{Reviews (1): Last reviewed commit: "Release v0.5.0" | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bba5074a29

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".