v0.50.0

@pipelex/sdk on npm

Added

• One file read, renamed and linked: getFile(fileId, query) reads GET /v1/files/{file_id}, a FileDetail holding the whole FileRecord (the row's fields with source_uri, original_name, sha256, role and state), the method_ids whose lists hold it and one page of its uses, paged by usesLimit and usesCursor; getFilesByUri(uri, { runId }) reads GET /v1/files/by-uri, every record holding an address, the one a surface shows first; renameFile(fileId, { name }) sends PATCH /v1/files/{file_id} and answers the record under the name the platform's rule saved; and linkFiles(files) sends POST /v1/files/links and answers one FileLink per file named by file_id or uri, in order, each a fifteen-minute link naming the file for its download or an error, a 200 either way, with every link hidden from the error of an answer the SDK cannot read (docs/files.md).
• A zip of files: requestFileArchive(request) asks POST /v1/files/archives for one zip of chosen file_ids, or of a run_id's inputs and outputs, under an optional name, and answers the FileArchive, queued; getFileArchive(archiveId) reads it until its state is ready, with a fresh link to the zip, or failed, with its failure. A request naming both or neither of file_ids and run_id is refused with RequestArgumentError before sending, and a selection past a cap is a 422 file_archive_too_large whose problemDocument.limit, typed FileArchiveLimit, names the cap and how far over the selection is.
• A run's files: listRunFiles(runId, query) reads GET /v1/runs/{run_id}/files, a RunFilesPage of what went in, what came out, what was made along the way and the inputs given as web links, each entry with its mark and the FileRecord a surface shows, its state listing until every file of the run is recorded and its next_cursor read as nextCursor.
• Adding a file to a method's draft: copyFileIntoDraft(methodId, { file_id, path, expected_updated_at }) sends POST /v1/methods/{method_id}/draft/files/from-file, which copies one of the organization's files into the draft at path without its bytes crossing the client, and answers a DraftFileFromFileResult discriminated on blob, copied or already_held, with the file as the tree names it and the method carrying the new draft token.
• The build assistant's save: saveAssistantMethodExample(methodId, { name, inputs, example_id, input_revision }) sends POST /v1/methods/{method_id}/examples/assistant-save, which writes the inputs into the named example only while it is still the assistant's at the revision read, and otherwise saves them as a new example flagged as the assistant's, never writing over a person's edit, and answers a MethodExampleAssistantSaveResult discriminated on outcome, kept or created, with the example (docs/method-examples.md).
• describeUpload, a file described for its upload grant: describeUpload(file, { filename?, maxBytes? }), on @pipelex/sdk/upload and the main entry, reads a File's or a Blob's name, type and size and computes the SHA-256 of its bytes with Web Crypto, the description requestUploadGrant takes as is. It leaves the hash out, and the grant works as it does without one, for a file larger than maxBytes, 50 MiB by default, which it never reads, so that the grant route's 413 refuses it where the deployment's limit is no larger and a deployment with a larger max_bytes grants it without a hash, under a fresh name and with no deduplication, the description's missing sha256 saying so, and where the runtime offers no Web Crypto digest, as on a page served over plain http from any host but the local one (docs/input-preparation.md).
• The file's record on the upload answer: UploadedFile, the answer of upload (POST /v1/upload), gains file_id, the record the platform wrote for the file, as a grant and uploadWithGrant now answer it; it is absent from a deployment that predates file records.
• The upload grant request takes the file's hash and its kind: UploadGrantInput gains sha256, with which the platform names the object after its bytes and holds the upload to them, and kind (uploaded or test) with method_id for a method's test file, as UploadInput takes them.

Changed

• An example carries kept_by_assistant (Breaking): MethodExample gains the required boolean kept_by_assistant, true on the example the build assistant keeps current and false from a person's first inputs edit, and every example the client hands back is checked to carry it, so an example answered without it, by a platform predating it, is an ApiResponseError of an answer the SDK cannot read, and code building a MethodExample by hand, such as a test fixture, adds the field.
• The upload grant answers whether the bytes are already stored (Breaking): UploadGrant gains file_id and stored, both absent from a deployment that predates them, and its url, headers and expires_at are null when stored is true, the organization already holding those bytes, so code reading grant.url branches on grant.stored first. uploadWithGrant sends nothing for a stored grant, and resolves to { uri, file_id } where it resolved to { uri }, file_id present whenever the grant carried one.
• uploadWithGrant reads a 412 as stored and sends a 409 again: for a grant that names the file by its bytes, told by the x-amz-checksum-sha256 it signs, storage's 412 means those bytes were stored there meanwhile, by another upload or by the platform's copy of a run's file, and resolves as stored with the grant's uri and file_id, while a grant asked for without a hash still meets grant_used; a 409 ConditionalRequestConflict is sent again after short pauses, within the call's time limit, before it fails with conflict; and a 400 BadDigest, bytes other than the hashed ones, is a store_refused that says so.

pipelex-sdk on PyPI

Added

• An organization's files, listed: list_files(...) reads GET /v1/files, one FilePage of FileSummary rows, newest first, filtered by method_id, run_id, created_by, kind, formats, media_types, created_from, created_to and q, the repeated filters sent as one format or media_type parameter per value, and iterate_files(...) follows the cursor through a filtered page that is empty and still carries one; an empty formats or media_types is refused with RequestArgumentError before any request, and a bare str raises TypeError (docs/files.md).
• One file read, renamed and linked: get_file(file_id, uses_limit=, uses_cursor=) reads GET /v1/files/{file_id}, a FileDetail holding the whole FileRecord (the row's fields with source_uri, original_name, sha256, role and state), the method_ids whose lists hold it and one page of its uses; get_files_by_uri(uri, run_id=) reads GET /v1/files/by-uri, every record holding an address, the one a surface shows first; rename_file(file_id, name) sends PATCH /v1/files/{file_id} and answers the record under the name the platform's rule saved; and link_files(files) takes FileLinkTargets, each naming exactly one of file_id and uri, sends POST /v1/files/links and answers one FileLinked or FileLinkRefused per file, in order, a 200 either way, with every link hidden from the error of an answer the SDK cannot read.
• A zip of files: request_file_archive(file_ids=, run_id=, name=) asks POST /v1/files/archives for one zip of chosen files, or of a run's inputs and outputs, and answers the FileArchive, queued; get_file_archive(archive_id) reads it until its state is ready, with a fresh link to the zip, or failed, with its failure. A request naming both or neither of file_ids and run_id is refused with RequestArgumentError before sending, and a selection past a cap is a 422 file_archive_too_large whose problem document's limit, read by FileArchiveLimit, names the cap and how far over the selection is.
• A run's files: list_run_files(run_id, limit=, cursor=) reads GET /v1/runs/{run_id}/files, a RunFilesPage of what went in, what came out, what was made along the way and the inputs given as web links, each entry with its mark and the FileRecord a surface shows, its state listing until every file of the run is recorded.
• Adding a file to a method's draft: copy_file_into_draft(method_id, file_id=, path=, expected_updated_at=) sends POST /v1/methods/{method_id}/draft/files/from-file, which copies one of the organization's files into the draft at path without its bytes crossing the client, and answers a DraftFileFromFileResult discriminated on blob, copied or already_held, with the file as the tree names it and the method carrying the new draft token.
• An upload recorded as a method's test file: UploadInput gains kind, an UploadKind (uploaded or test), and method_id, which upload sends to POST /v1/upload only when given; upload_file takes the same pair as keyword arguments and prepare_inputs as its upload argument, an UploadKindOptions, for every file it uploads, each checked before any file is read, kind="test" requiring a bare method_id and only a test file naming one. The upload route's refusals of a test file, a role that may not change methods, an unknown method or one being erased, are a TestFileRefusedError with a TestFileRefusalCode, rather than a refused credential or a deployment without upload (docs/files.md).
• The build assistant's save: save_assistant_method_example(method_id, name=, inputs=, example_id=, input_revision=) sends POST /v1/methods/{method_id}/examples/assistant-save, which writes the inputs into the named example only while it is still the assistant's at the revision read, and otherwise saves them as a new example flagged as the assistant's, never writing over a person's edit, and answers a MethodExampleAssistantSaveResult, MethodExampleAssistantKept or MethodExampleAssistantCreated, with the example (docs/method-examples.md).
• The file's record on the upload answer: UploadedFile, the answer of upload (POST /v1/upload), gains file_id, the record the platform wrote for the file, None from a deployment that predates file records.

Changed

• MethodExample carries kept_by_assistant (Breaking): MethodExample gains the required kept_by_assistant, a strict boolean, true on the example the build assistant keeps current and false from a person's first inputs edit, so an example answered without it, by a platform predating it, is an ApiResponseError of an answer the SDK cannot read, and code building a MethodExample by hand, such as a test fixture, adds the field.