Skip to content

Commit c530398

Browse files
caradoxicalcaradoxical
authored
Merge pull request #27 from modzy/readme-overhaul
Readme overhaul
2 parents 9d6312b + e63777c commit c530398

File tree

2 files changed

+115
-49
lines changed

2 files changed

+115
-49
lines changed

‎README.md

+115-49
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,129 @@
1-
# Modzy JavaScript SDK
1+
<div align="center">
22

3-
Modzy's Javascript SDK simplifies tasks such as querying models, submitting jobs, and returning results. It supports both Node.js and browser JavaScript applications using the output target of your build system to know which code to use.
3+
![javascript-sdk-github-banner.png](javascript-sdk-github-banner.png)
44

5-
## Visit [docs.modzy.com](https://docs.modzy.com/docs/javascript) for docs, guides, API and more.
5+
![GitHub contributors](https://img.shields.io/github/contributors/modzy/sdk-javascript?logo=GitHub&style=flat)
6+
![GitHub last commit](https://img.shields.io/github/last-commit/modzy/sdk-javascript?logo=GitHub&style=flat)
7+
![GitHub issues](https://img.shields.io/github/issues-raw/modzy/sdk-javascript?logo=github&style=flat)
8+
![GitHub](https://img.shields.io/github/license/modzy/sdk-javascript?logo=apache&style=flat)
69

7-
These instructions are for Modzy JavaScript SDK v2, which is substantially different from v1.
10+
![npm (scoped)](https://img.shields.io/npm/v/@modzy/modzy-sdk?logo=npm)
11+
![npm](https://img.shields.io/npm/dm/@modzy/modzy-sdk?logo=npm)
812

9-
---
13+
**[JavaScript SDK Documentation Page](https://docs.modzy.com/docs/javascript)**
1014

11-
## Installation
15+
</div>
1216

13-
From the command line in your project directory, run `yarn add @modzy/modzy-sdk` or `npm install @modzy/modzy-sdk`.
14-
Then import the ModzyClient class into your code:
17+
# Installation
18+
19+
Intall Modzy's JavaScript SDK with NPM
1520

1621
```bash
17-
yarn add @modzy/modzy-sdk
18-
# or
1922
npm install @modzy/modzy-sdk
2023
```
24+
or YARN
2125

22-
```javascript
23-
import { ModzyClient } from "@modzy/modzy-sdk";
26+
```bash
27+
yarn add @modzy/modzy-sdk
2428
```
2529

26-
---
30+
# Usage/Examples
2731

28-
## Initialize
29-
30-
To initialize `ModzyClient`, you need an [api key](https://docs.modzy.com/docs/getting-started#key-download-your-api-key). If using an installation of Modzy other than app.modzy.com, you'll also need to provide the url for your instance of Modzy. For debugging purposes, you can also turn on logging.
31-
32-
⚠️ _Warning: Keep your API key secret. Do not include it in a git repo or store it on GitHub_
32+
## Initializing the SDK
33+
Initialize your client by authenticating with an API key. You can [download an API Key](https://docs.modzy.com/docs/view-and-manage-api-keys#download-team-api-key) from your instance of Modzy.
3334

3435
```javascript
35-
// app.modzy.com
36-
const modzyClient = new ModzyClient({
37-
apiKey: "xxxxxxxxxxxxx.xxxxxxxxxxxxx",
38-
});
36+
import { ModzyClient } from "@modzy/modzy-sdk";
3937

40-
// or for private Modzy instances
4138
const modzyClient = new ModzyClient({
42-
apiKey: "xxxxxxxxxxxxx.xxxxxxxxxxxxx",
43-
url: "https://modzy.yourdomain.com",
39+
apiKey: "Valid Modzy API Key", //e.g., "JbFkWZMx4Ea3epIrxSgA.a2fR36fZi3sdFPoztAXT"
40+
url: "Valid Modzy URL", //e.g., "https://trial.app.modzy.com"
4441
});
4542
```
4643

47-
---
48-
49-
## Basic usage
50-
51-
Submit a job providing the model, version and input text:
44+
## Running Inferences
45+
### Raw Text Inputs
46+
Submit an inference job to a text-based model by providing the model ID, version, and raw input text.
5247

5348
```javascript
49+
//Submit text to v1.0.1 of a Sentiment Analysis model, and to make the job explainable, change explain=True
5450
const { jobIdentifier } = await modzyClient.submitJobText({
5551
modelId: "ed542963de",
5652
version: "1.0.1",
5753
sources: {
58-
yourInputKey: {
59-
"input.txt": "Sometimes I really hate ribs",
54+
firstPhoneCall: {
55+
"input.txt": "Mr Watson, come here. I want to see you.",
56+
},
57+
},
58+
});
59+
```
60+
61+
### File Inputs
62+
Pass a file from your local directory to a model by providing the model ID, version, and the filepath of your sample data:
63+
64+
```javascript
65+
// Submit a job to the Image-Based Geolocation model
66+
const { jobIdentifier } = await modzyClient.submitJobFile({
67+
modelId: "aevbu1h3yw",
68+
version: "1.0.1",
69+
sources: {
70+
nyc-skyline: {
71+
image: "./images/nyc-skyline.jpg",
6072
},
6173
},
6274
});
6375
```
6476

77+
### Embedded Inputs
78+
Convert images and other large inputs to base64 embedded data and submit to a model by providing a model ID, version number, and dictionary with one or more base64 encoded inputs:
79+
80+
```javascript
81+
const fs = require('fs');
82+
83+
//Embed input as a string in base64
84+
const imageBytes = fs.readFileSync('images/tower-bridge.jpg');
85+
//Prepare the source dictionary
86+
let sources = { "tower-bridge": { "image": imageBytes } };
87+
88+
//Submit the image to v1.0.1 of an Imaged-based Geolocation model
89+
const { jobIdentifier } = await modzyClient.submitJobEmbedded("aevbu1h3yw", "1.0.1", "application/octet-stream", sources);
90+
```
91+
92+
### Inputs from Databases
93+
Submit data from a SQL database to a model by providing a model ID, version, a SQL query, and database connection credentials:
94+
95+
```javascript
96+
//Add database connection and query information
97+
const dbUrl = "jdbc:postgresql://db.bit.io:5432/bitdotio"
98+
const dbUserName = DB_USER_NAME;
99+
const dbPassword = DB_PASSWORD;
100+
const dbDriver = "org.postgresql.Driver";
101+
//Select as "input.txt" becase that is the required input name for this model
102+
const dbQuery = "SELECT \"mailaddr\" as \"input.txt\" FROM \"user/demo_repo\".\"atl_parcel_attr\" LIMIT 10;";
103+
104+
//Submit the database query to v0.0.12 of a Named Entity Recognition model
105+
const { jobIdentifier } = await modzyClient.submitJobJDBC("a92fc413b5", "0.0.12", dbUrl, dbUserName, dbPassword, dbDriver, dbQuery)}
106+
```
107+
108+
### Inputs from Cloud Storage
109+
Submit data directly from your cloud storage bucket (Amazon S3 supported) by providing a model ID, version, and storage-blob-specific parameters.
110+
111+
#### AWS S3
112+
```javascript
113+
//Define sources dictionary with bucket and key that points to the correct file in your s3 bucket
114+
const bucketName = "s3-bucket-name";
115+
const fileKey = "key-to-file.txt";
116+
let sources = { "sampleText": { "input.txt": { 'bucket': bucketName, 'key': fileKey } } };
117+
118+
const accessKey = ACCESS_KEY_ID;
119+
const secretAccessKey = SECRET_KEY;
120+
const region = "us-east-1";
121+
122+
//Submit s3 input to v1.0.1 of a Sentiment Analysis model
123+
const { jobIdentifier } = await modzyClient.submitJobAWSS3("ed542963de", "1.0.1", accessKey, secretAccessKey, region, sources)
124+
```
125+
126+
## Getting Results
65127
Hold until the inference is complete:
66128

67129
```javascript
@@ -74,33 +136,37 @@ Get the output results:
74136
const result = await modzyClient.getResult(jobIdentifier);
75137
```
76138

77-
---
78-
79-
## Samples
139+
## SDK Code Examples
80140

81-
Check out our [samples](https://github.com/modzy/sdk-javascript/tree/main/samples) for details on specific use cases.
82-
Samples are intended to be run using Node.js, but most can also run in the browser. The `react examples` directory contains a couple of react components to show how you can use the browser to send files to, or retrieve files from Modzy. To run the samples using app.modzy.com, make sure to update the line `const API_KEY = process.env.MODZY_API_KEY;` to contain a real api key from your account.
141+
* [`samples`](https://github.com/modzy/sdk-javascript/tree/main/samples) provides details for specific use cases and are intended to be run using Node.js, but most can also run in the browser
142+
* [`react examples`](https://github.com/modzy/sdk-javascript/tree/main/samples/react%20examples) contains react components that can be used to the browser to send files to, or retrieve files from Modzy.
143+
144+
To run these examples, make sure to update `API_KEY` and `MODZY_URL` to valid values.
83145

84-
---
146+
## Running Tests
85147

86-
## Running tests
87-
88-
The Jest tests expect that there is a .env file at the root of the repo that contains a
89-
valid app.modzy.com api key like this:
148+
The Jest tests expect that there is a .env file at the root of the repo that contains a valid Modzy api key like this:
90149

91150
```
92151
API_KEY=xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx
93152
```
94153

95-
---
154+
# Documentation
155+
156+
Modzy's SDK is built on top of the [Modzy HTTP/REST API](https://docs.modzy.com/reference/introduction). For a full list of features and supported routes visit [JavaScript SDK on docs.modzy.com](https://docs.modzy.com/docs/javascript)
157+
158+
# Support
159+
160+
For support, email [email protected] or join our [Slack](https://www.modzy.com/slack).
161+
162+
# Contributing
96163

97-
## Contributing
164+
Contributions are always welcome!
98165

99-
We are happy to receive contributions from all of our users. Check out our [contributing file](https://github.com/modzy/sdk-javascript/tree/main/contributing.adoc) to learn more.
166+
See [`contributing.md`](https://github.com/modzy/sdk-javascript/tree/main/contributing.adoc) for ways to get started.
100167

101-
---
168+
Please adhere to this project's `code of conduct`.
102169

103-
## Code of conduct
170+
We are happy to receive contributions from all of our users. Check out our contributing file to learn more.
104171

105-
Please see our [code of conduct](https://github.com/modzy/sdk-javascript/tree/main//CODE_OF_CONDUCT.md) for any questions about the kind of community we are trying to build.
106-
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](https://github.com/modzy/sdk-javascript/tree/main//CODE_OF_CONDUCT.md)
172+
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](https://github.com/modzy/sdk-javascript/tree/main/CODE_OF_CONDUCT.md)

‎javascript-sdk-github-banner.png

143 KB
Loading

0 commit comments

Comments
 (0)