diff --git a/LICENSE b/LICENSE index a34b9f9..c61b663 100644 --- a/LICENSE +++ b/LICENSE @@ -1,21 +1,201 @@ -MIT License - -Copyright (c) 2022 Replicate - -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. + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/README.md b/README.md index 4641a36..7b35854 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,352 @@ -# replicate-js -A JavaScript / Node.js client for Replicate's API +This is a design document for figuring out the design of the future JavaScript client for Replicate’s HTTP API. Let’s design the API here, before we write any code. README-driven development! + +# `replicate` + +> SDK for [Replicate’s REST API](https://replicate.com/docs/reference/http) + +## Usage + +Install with `npm install replicate` + +```jsx +import Replicate from "@replicate/client"; + +const replicate = new Replicate({ + // get your token from https://replicate.com/account + auth: "", + userAgent: "my-app/1.2.3", +}); + +const prediction = await replicate.createAndAwaitPrediction({ + version: "", + input: { + // your model inputs need to be set here + prompt: "painting of a cat by andy warhol", + }, +}); + +// { +// id: "ufawqhfynnddngldkgtslldrkq", +// version: "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", +// urls: { +// get: "https://api.replicate.com/v1/predictions/ufawqhfynnddngldkgtslldrkq", +// cancel: "https://api.replicate.com/v1/predictions/ufawqhfynnddngldkgtslldrkq/cancel" +// }, +// created_at: "2020-02-02T00:00:00.00000Z", +// started_at: "2022-02-02T00:01:00.00000Z", +// completed_at: "2022-02-02T00:02:00.00000Z", +// status: "starting", +// input: { +// text: "Alice" +// }, +// output: [ +// "https://replicate.com/api/models/stability-ai/stable-diffusion/files/9c3b6fe4-2d37-4571-a17a-83951b1cb120/out-0.png" +// ], +// error: null, +// metrics: {} +// } +``` + +## Features + +- Implements best practices such as throttling requests +- Pagination +- Fully typed + +## API + +### Constructor + +```jsx +const replicate = new Replicate(options); +``` + +| name | type | description | +| ----------------- | ------ | ---------------------------------------- | +| options.auth | string | Required. API access token | +| options.userAgent | string | Required. Identifier of your app | +| options.baseUrl | string | Defaults to https://api.replicate.com/v1 | + +### `replicate.models.get` + +```jsx +const response = await replicate.models.get(options); +``` + +| name | type | description | +| ------------------- | ------ | ------------------------------------------------------------------- | +| options.model_owner | string | Required. The name of the user or organization that owns the model. | +| options.model_name | string | Required. The name of the model. | + +Example for `response.data` + +```jsx +{ + url: "https://replicate.com/replicate/hello-world", + owner: "replicate", + name: "hello-world", + description: "A tiny model that says hello", + visibility: "public", + github_url: "https://github.com/replicate/cog-examples", + paper_url: null, + license_url: null, + latest_version: { /* ... */ } +} +``` + +### `replicate.models.listVersions` + +```jsx +const response = await replicate.models.listVersions(options); +``` + +| name | type | description | +| ------------------- | ------ | ------------------------------------------------------------------- | +| options.model_owner | string | Required. The name of the user or organization that owns the model. | +| options.model_name | string | Required. The name of the model. | + +Example for `response.data` + +```jsx +{ + previous: null, + next: null, + results: [ + { + id: "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", + created_at: "2022-04-26T19:29:04.418669Z", + cog_version: "0.3.0", + openapi_schema: { /* ... */ } + }, + { + id: "e2e8c39e0f77177381177ba8c4025421ec2d7e7d3c389a9b3d364f8de560024f", + created_at: "2022-03-21T13:01:04.418669Z", + cog_version: "0.3.0", + openapi_schema: { /* ... */ } + } + ] +} +``` + +### `replicate.models.getVersion` + +```jsx +const response = await replicate.models.getVersion(options); +``` + +| name | type | description | +| ------------------- | ------ | ------------------------------------------------------------------- | +| options.model_owner | string | Required. The name of the user or organization that owns the model. | +| options.model_name | string | Required. The name of the model. | +| options.id | string | Required. The model version | + +Example for `response.data` + +```jsx +{ + id: "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", + created_at: "2022-04-26T19:29:04.418669Z", + cog_version: "0.3.0", + openapi_schema: { /* ... */ } +} +``` + +### `replicate.models.getCollection` + +```jsx +const response = await replicate.models.getCollection(options); +``` + +| name | type | description | +| ----------------------- | ------ | -------------------------------------------------------------------------- | +| options.collection_slug | string | Required. The slug of the collection. See http://replicate.com/collections | + +### `replicate.predictions.create` + +```jsx +const response = await replicate.predictions.create(options); +``` + +| name | type | description | +| ------------------------- | ------ | ------------------------------------------------------------------------- | +| options.version | string | Required. The model version | +| options.input | object | Required. An object with the models inputs | +| options.webhook_completed | string | A URL which will receive a POST request upon completion of the prediction | + +Example for `response.data` + +```jsx +{ + id: "ufawqhfynnddngldkgtslldrkq", + version: "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", + urls: { + get: "https://api.replicate.com/v1/predictions/ufawqhfynnddngldkgtslldrkq", + cancel: "https://api.replicate.com/v1/predictions/ufawqhfynnddngldkgtslldrkq/cancel" + }, + created_at: "2022-04-26T22:13:06.224088Z", + started_at: null, + completed_at: null, + status: "succeeded", + input: { + text: "Alice" + }, + output: null, + error: null, + logs: null, + metrics: {} +} +``` + +### `replicate.predictions.get` + +```jsx +const response = await replicate.predictions.get(options); +``` + +| name | type | description | +| -------------------- | ------ | ----------- | +| options.predictionId | string | Required. | + +Example for `response.data` + +```jsx +{ + id: "ufawqhfynnddngldkgtslldrkq", + version: "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", + urls: { + get: "https://api.replicate.com/v1/predictions/ufawqhfynnddngldkgtslldrkq", + cancel: "https://api.replicate.com/v1/predictions/ufawqhfynnddngldkgtslldrkq/cancel" + }, + created_at: "2022-04-26T22:13:06.224088Z", + started_at: null, + completed_at: null, + status: "starting", + input: { + text: "Alice" + }, + output: null, + error: null, + logs: null, + metrics: {} +} +``` + +### `replicate.predictions.list` + +```jsx +const response = await replicate.predictions.list(); +``` + +`replicate.predictions.list()` has no options. + +Example for `response.data` + +```jsx +{ + previous: null, + next: "https://api.replicate.com/v1/predictions?cursor=cD0yMDIyLTAxLTIxKzIzJTNBMTglM0EyNC41MzAzNTclMkIwMCUzQTAw", + results: [ + { + id: "jpzd7hm5gfcapbfyt4mqytarku", + version: "b21cbe271e65c1718f2999b038c18b45e21e4fba961181fbfae9342fc53b9e05", + urls: { + get: "https://api.replicate.com/v1/predictions/jpzd7hm5gfcapbfyt4mqytarku", + cancel: "https://api.replicate.com/v1/predictions/jpzd7hm5gfcapbfyt4mqytarku/cancel" + }, + created_at: "2022-04-26T20:00:40.658234Z", + started_at: "2022-04-26T20:00:84.583803Z", + completed_at: "2022-04-26T20:02:27.648305Z", + source: "web", + status: "succeeded" + }, + /* ... */ + ] +} +``` + +### `replicate.paginate` + +```jsx +const result = await replicate.paginate(replicate.predictions.list); +``` + +Auto-paginates the passed in endpoint and resolves with an array of all results + +### `replicate.paginate.iterator` + +```jsx +const asyncIterator = replicate.paginate.iterator(replicate.predictions.list); +``` + +Same as `replicate.paginate` but can be used as async iterator, e.g. + +```jsx +for await (const response of replicate.paginate.iterator( + replicate.predictions.list +)) { + /* do something with response */ +} +``` + +### `replicate.request` + +```jsx +const response = await replicate.request(route, parameters); +``` + +| name | type | description | +| ------------------ | ------ | ------------------------------------------------------------ | +| options.route | string | Required. REST API endpoint path. | +| options.parameters | object | URL, query, and request body parameters for the given route. | + +The `replicate.request()` method is used under the hood of the other request methods and can be utilized to try out experimental endpoints that have not been documented yet. + +## TypeScript + +The `Replicate` constructor and all `replicate.*` methods are fully typed. + +In order to get types for prediction inputs which depend on model versions, you can extend the `Replicate.ModelInputsByVersion` interface in one of two ways + +### 1. Install type packages from URLs + +Import types for JS/TS usage is to make dynamic type packages installable from the API. For example + +```bash +npm install --save-dev https://api.replicate.com/v1/models/{model_owner}/{model_name}/{version}.tar.gz +``` + +Because the package name begins with `@types/` the typescript language server in VS Code recognizes it automatically. Packages can be installed for multiple models/versions. + +### 2. Define types manually + +The types for each model version can be defined manually in a `replicate-models.d.ts` file that is located in your projects’ root path + +```bash +import { Replicate } from "replicate"; + +declare module "replicate-testing" { + namespace Replicate { + interface ModelInputsByVersion { + affe44672e418f636f9a5cf2e6f9632404a83d692e42ecfa3f3010e467b80659: { + prompt: string; + }; + } + } +} +``` + +The types can be imported in JS files with a triple slash directives (must be the first line in the file) + +```bash +/// +``` + +In TS files the types will be imported automatically when the file lives in the project root. + +## Contributing + +See [CONTRIBUTING.md](https://example.com) + +## License + +[Apache 2.0](LICENSE)