Merge pull request #12 from modzy/readmeUpdates

readme updates

README.adoc

@@ -12,60 +12,33 @@
 <h1>Javascript SDK</h1>
 
 <div align="center">
-
 <br>
 <br>
-
-
 <img  src="https://www.modzy.com/wp-content/uploads/2019/10/modzy-logo-tm.svg" alt="Modzy" width="350" height="auto">
-
 <br>
 <br>
 <br>
 <br>
-
-
-
-
 <p><b>Modzy's Javascript SDK queries models, submits inference jobs, and returns results directly to your editor.</b></p>
-
-
 <br>
-
-
 <img alt="GitHub contributors" src="https://img.shields.io/github/contributors/modzy/sdk-javascript">
-
 <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/modzy/sdk-javascript">
-
 <img alt="GitHub Release Date" src="https://img.shields.io/github/release-date/modzy/sdk-javascript">
-
 </div>
-
 <br>
 <br>
-
 <div align="center">
 <a href=https://models.modzy.com/docs/how-to-guides/job-lifecycle style="text-decoration:none">The job lifecycle</a> |
 <a href=https://models.modzy.com/docs/how-to-guides/api-keys style="text-decoration:none">API keys</a> |
 <a href=/samples style="text-decoration:none">Samples</a> |
 <a href=https://models.modzy.com/docs/home/home style="text-decoration:none">Documentation</a>
-
-
 <br>
 <br>
 <br>
 <br>
-
-
-
 <br>
-
 </div>
-
 <br>
-
-
-
 ++++
 
 
@@ -74,7 +47,7 @@
 
 ++++
 <br>
-<div align="center>
+<div align="center">
   <a href="https://asciinema.org/a/B1IkRkW4LjW7sufkjoMWoETH6"><img src="install.gif" style="max-width:100%"/></a>
 </div>
 <br>
@@ -84,71 +57,165 @@ Clone the repository:
 
 - `$ git clone https://github.com/modzy/sdk-javascript.git`
 
-++++
-<p>Use <a href=https://yarnpkg.com/ style="text-decoration:none">yarn</a> to package and install the SDK. </p>
-++++
+Use https://yarnpkg.com/[yarn] to package and install the SDK:
+
+Globally:
+
+- `$ yarn global add ./sdk-javascript`
+
+In an existing project (directly from github):
+
+- `$ yarn add modzy/sdk-javascript`
+
 
-- `$ yarn add ./sdk-javascript`
+Or you can use https://nodejs.org/[npm]:
 
-//no reference to node.js in here but it is in contributing.
+Globally
 
-== Usage
+- `$ npm install -g ./sdk-javascript`
 
+In an existing project (directly from github):
 
-=== Initialize
+- `$ npm install modzy/sdk-javascript`
 
-Once you have a `model` and `version` identified, authenticate to Modzy with your API key:
+== Initialize
+
+Once you have a `model` and `version` identified, get authenticated with your API key.
+
+API keys are security credentials required to perform API requests to Modzy. Our API keys are composed of an ID that is split by a dot into two parts: the prefix and the body. +
+The *prefix* is the API keys' visible part. It’s only used to identify the key and by itself, it’s unable to perform API requests.
+
+link:https://models.modzy.com/docs/users-keys/api-keys/retrieve-users-api-keys[List your API keys]:
+
+[source, js]
+----
+const keys = await modzyClient.getAccountingClient().getAPIKeys('[email protected]');
+keys.forEach(
+    key => {
+      console.log(JSON.stringify(key));
+    }
+);
+----
+
+The *body* is the prefix’s complement and it’s required to perform API requests. Since it’s not stored on Modzy’s servers, it cannot be recovered. Make sure to save it securely. If lost, you can link:https://models.modzy.com/docs/users-keys/api-keys/replace-API-key[replace the API key's body].
+
+link:https://models.modzy.com/docs/users-keys/api-keys/retrieve-full-API-key[Retrieve the API key's body]:
+
+[source, js]
+----
+
+const hash = await modzyClient.getAccountingClient().getKeyBody('yourKey');
+console.log("The hash is: "+hash);
+----
+
+Get authenticated with your API key:
 
 [source, js]
 ----
 const modzy = require('modzy-sdk');
-const modzyClient = new modzy.ModzyClient("http://url.to.modzy/api", "my_key.modzy");
+const modzyClient = new modzy.ModzyClient("http://url.to.modzy/api", "prefix.body");
 ----
 
-=== Basic usage
+== Basic usage
 
 ++++
 <br>
+<div align="center">
+<img src="js.gif" alt="basic usage" style="max-width:100%">
+</div>
+<br>
 ++++
 
-The code below is applicable for `text/plain` input type.
 
-++++
-<div align="center">
 
-<img src="js.gif" alt="basic usage" style="max-width:100%">
+=== Browse models
 
-</div>
+Modzy’s Marketplace includes pre-trained and re-trainable AI models from industry-leading machine learning companies, accelerating the process from data to value.
 
-<br>
-++++
+The Model service drives the Marketplace and can be integrated with other applications, scripts, and systems. It provides routes to list, search, and filter model and model-version details.
 
-Browse models:
+link:https://models.modzy.com/docs/marketplace/models/retrieve-models[List models]
 
 [source, js]
 ----
-try{
-    const models = await modzyClient.getAllModels();
-    models.forEach(
-        model => {
-          console.log(JSON.stringify(model));
-        }
-    );
-}
+const models = await modzyClient.getAllModels();
+models.forEach(
+    model => {
+      console.log(JSON.stringify(model));
+    }
+);
+----
+
+Tags help categorize and filter models. They make model browsing easier.
 
+link:https://models.modzy.com/docs/marketplace/tags/retrieve-tags[List tags]:
+
+[source, js]
+----
+const tags = await modzyClient.getAllTags();
+tags.forEach(
+    tag => {
+      console.log(JSON.stringify(tag));
+    }
+);
 ----
 
+link:https://models.modzy.com/docs/marketplace/tags/retrieve-models-by-tags[List models by tag]:
 
-Get a model's details:
+[source, js]
+----
+const tagsModels = await modzyClient.getTagsAndModels("language_and_text");
+tagsModels.models.forEach(
+    model => {
+        console.log(JSON.stringify(model));
+    }
+);
+----
+
+=== Get a model's details
+
+Models accept specific *input file link:https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types[MIME] types*. Some models may require multiple input file types to run data accordingly. In this sample, we use a model that requires `text/plain`.
+
+Models require inputs to have a specific *input name* declared in the job request. This name can be found in the model’s details. In this sample, we use a model that requires `input.txt`.
+
+Additionally, users can set their own input names. When multiple input items are processed in a job, these names are helpful to identify and get each input’s results. In this sample, we use a model that requires `input-1` and `input-2`.
+
+link:https://models.modzy.com/docs/marketplace/models/retrieve-model-details[Get a model's details]:
 
 [source, js]
 ----
 const saModel = await modzyClient.getModel("ed542963de");
 console.log(JSON.stringify(saModel));
 ----
 
+Model specific sample requests are available in the version details and in the Model Details page.
+
+link:https://models.modzy.com/docs/marketplace/versions/retrieve-version-details[Get version details]:
+
+[source, js]
+----
+let modelVersion = await modzyClient.getModelVersion("ed542963de", "0.0.27");
+console.log("inputs:");
+for(key in modelVersion.inputs){
+    let input = modelVersion.inputs[key];
+    console.log(`  key ${input.name}, type ${input.acceptedMediaTypes}, description: ${input.description}`);
+}
+console.log("outputs:");
+for(key in modelVersion.outputs){
+    let output = modelVersion.outputs[key];
+    console.log(`  key ${output.name}, type ${output.mediaType}, description: ${output.description}`);
+}
+----
+
+=== Submit a job and get results
+
+A *job* is the process that sends data to a model, sets the model to run the data, and returns results.
+
+Modzy supports several *input types* such as `text`, `embedded` for Base64 strings, `aws-s3` and `aws-s3-folder` for inputs hosted in buckets, and `jdbc` for inputs stored in databases. In this sample, we use `text`.
+
+link:https://github.com/modzy/sdk-javascript/blob/readmeUpdates/samples.adoc[Here] are samples to submit jobs with `embedded`, `aws-s3`, `aws-s3-folder`, and `jdbc` input types.
 
-Submit a job providing the model, version, and input file:
+link:https://models.modzy.com/docs/jobs/jobs/submit-job-text[Submit a job with the model, version, and input items]:
 
 [source, js]
 ----
@@ -162,15 +229,18 @@ let job = await modzyClient.submitJobText(
             );
 ----
 
-Hold until the inference is complete and results become available:
+link:https://models.modzy.com/docs/jobs/jobs/retrieve-job-details[Hold until the inference is complete and results become available]:
 
 [source, js]
 ----
 job = await modzyClient.blockUntilComplete(job);
-
 ----
 
-Get the output results:
+link:https://models.modzy.com/docs/jobs/results/retrieve-results[Get the results]:
+
+Results are available per input item and can be identified with the name provided for each input item upon job request. You can also add an input name to the route and limit the results to any given input item.
+
+Jobs requested for multiple input items may have partial results available prior to job completion.
 
 [source, js]
 ----
@@ -202,7 +272,11 @@ catch(error){
 
 == Features
 
-Currently we support the following api routes:
+Modzy supports link:https://models.modzy.com/docs/features/batch-processing[batch processing], link:https://models.modzy.com/docs/features/explainability[explainability], and link:https://models.modzy.com/docs/features/model-drift[model drift detection].
+
+== APIs
+
+Here is a list of Modzy APIs. To see all the APIs, check our link:https://models.modzy.com/docs/home/home[Documentation].
 
 :doc-pages: https://models.modzy.com/docs/
 [cols=3*, stripes=even]

contributing.adoc

@@ -86,7 +86,7 @@ Clone the repository:
 
 Install dependencies:
 
-- `$ yarn install`
+- `$ yarn install` or `$ npm install`
 
 Create a branch for your awesome new feature:
 
@@ -134,19 +134,23 @@ MODZY_API_KEY=my_key.modzy
 
 Run tests:
 
-- `$ yarn test`
+- `$ yarn test` or `$ npm test`
 
 Or specify the test that you want to run:
 
 - `$ yarn test -- model-client.test.js`
 
+With npm:
+
+- `$ npm test -- model-client.test.js`
+
 === 4. Document your changes
 
 Add supporting documentation for your code.
 
 === 5. Transpile the code
 
-- `$ yarn build`
+- `$ yarn build` or `$ npm run-script build`
 
 === 6. Send a pull request
 

package.json

@@ -1,24 +1,39 @@
 {
   "name": "modzy-sdk",
-  "version": "1.0.1",
+  "version": "1.0.2",
+  "description": "Javascript SDK for Modzy",
   "main": "dist/main.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modzy/sdk-javascript.git"
+  },
+  "keywords": [
+    "Modzy",
+    "SDK"
+  ],
+  "author": "Modzy",
+  "bugs": {
+    "url": "https://github.com/modzy/sdk-javascript/issues"
+  },
+  "homepage": "https://github.com/modzy/sdk-javascript#readme",
   "scripts": {
     "docs": "jsdoc -c jsdoc.json",
     "build": "babel src --out-dir=dist",
     "test": "jest --detectOpenHandles"
   },
   "dependencies": {
-    "axios": "^0.19.2",
+    "axios": "^0.21.1",
     "dotenv": "^8.2.0",
-    "log4js": "^6.1.2"
+    "log4js": "^6.1.2",
+    "string-similarity": "^4.0.4"
   },
   "devDependencies": {
     "@babel/cli": "^7.8.4",
     "@babel/core": "^7.8.7",
     "@babel/plugin-proposal-class-properties": "^7.8.3",
-    "@babel/preset-env": "^7.8.7",    
+    "@babel/preset-env": "^7.8.7",
     "babel-jest": "^25.1.0",
     "jest": "^25.1.0",
     "jsdoc": "^3.6.4"
   }
-}
+}