📝 Began restructuring Inference docs

packages/inference/README.md

@@ -31,20 +31,30 @@ import { HfInference } from "npm:@huggingface/inference"
 
 Your access token should be kept private. If you need to protect it in front-end applications, we suggest setting up a proxy server that stores the access token.
 
-### Basic examples
+### Getting started
 
 ```typescript
 import { HfInference } from '@huggingface/inference'
 
 const hf = new HfInference('your access token')
+```
+
+### Fill Mask
 
-// Natural Language
+Tries to fill in a hole with a missing word (token to be precise).
 
+```typescript
 await hf.fillMask({
   model: 'bert-base-uncased',
   inputs: '[MASK] world!'
 })
+```
 
+### Summarization
+
+Summarizes longer text into shorter text. Be careful, some models have a maximum length of input.
+
+```typescript
 await hf.summarization({
   model: 'facebook/bart-large-cnn',
   inputs:
@@ -53,15 +63,25 @@ await hf.summarization({
     max_length: 100
   }
 })
+```
+
+### Question Answering
 
+Answers questions based on the context you provide.
+
+```typescript
 await hf.questionAnswering({
   model: 'deepset/roberta-base-squad2',
   inputs: {
     question: 'What is the capital of France?',
     context: 'The capital of France is Paris.'
   }
 })
+```
+
+### Table Question Answering
 
+```typescript
 await hf.tableQuestionAnswering({
   model: 'google/tapas-base-finetuned-wtq',
   inputs: {
@@ -74,12 +94,24 @@ await hf.tableQuestionAnswering({
     }
   }
 })
+```
+
+### Text Classification
 
+Often used for sentiment analysis, this method will assign labels to the given text along with a probability score of that label.
+
+```typescript
 await hf.textClassification({
   model: 'distilbert-base-uncased-finetuned-sst-2-english',
   inputs: 'I like you. I love you.'
 })
+```
+
+### Text Generation
+
+Generates text from an input prompt.
 
+```typescript
 await hf.textGeneration({
   model: 'gpt2',
   inputs: 'The answer to the universe is'
@@ -92,25 +124,56 @@ for await (const output of hf.textGenerationStream({
 })) {
   console.log(output.token.text, output.generated_text);
 }
+```
+
+### Token Classification
 
+Used for sentence parsing, either grammatical, or Named Entity Recognition (NER) to understand keywords contained within text.
+
+```typescript
 await hf.tokenClassification({
   model: 'dbmdz/bert-large-cased-finetuned-conll03-english',
   inputs: 'My name is Sarah Jessica Parker but you can call me Jessica'
 })
+```
 
+### Translation
+
+```typescript
 await hf.translation({
   model: 't5-base',
   inputs: 'My name is Wolfgang and I live in Berlin'
 })
 
+await hf.translation({
+  model: 'facebook/mbart-large-50-many-to-many-mmt',
+  inputs: textToTranslate,
+  parameters: {
+		"src_lang": "en_XX",
+		"tgt_lang": "fr_XX"
+	}
+})
+```
+
+### Zero-Shot Classification
+
+Checks how well an input text fits into a set of labels you provide.
+
+```typescript
 await hf.zeroShotClassification({
   model: 'facebook/bart-large-mnli',
   inputs: [
     'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!'
   ],
   parameters: { candidate_labels: ['refund', 'legal', 'faq'] }
 })
+```
 
+### Conversational
+
+This task corresponds to any chatbot-like structure. Models tend to have shorter max_length, so please check with caution when using a given model if you need long-range dependency or not.
+
+```typescript
 await hf.conversational({
   model: 'microsoft/DialoGPT-large',
   inputs: {
@@ -119,7 +182,13 @@ await hf.conversational({
     text: 'Can you explain why ?'
   }
 })
+```
+
+### Sentence Similarity
 
+Calculate the semantic similarity between one text and a list of other sentences.
+
+```typescript
 await hf.sentenceSimilarity({
   model: 'sentence-transformers/paraphrase-xlm-r-multilingual-v1',
   inputs: {
@@ -131,72 +200,135 @@ await hf.sentenceSimilarity({
     ]
   }
 })
+```
+
+### Feature Extraction
+
+This task reads some text and outputs raw float values, that are usually consumed as part of a semantic database/semantic search.
 
+```typescript
 await hf.featureExtraction({
   model: "sentence-transformers/distilbert-base-nli-mean-tokens",
   inputs: "That is a happy person",
 });
+```
+
+### Automatic Speech Recognition
 
-// Audio
+Transcribes speech from an audio file.
 
+```typescript
 await hf.automaticSpeechRecognition({
   model: 'facebook/wav2vec2-large-960h-lv60-self',
   data: readFileSync('test/sample1.flac')
 })
+```
+
+### Audio Classification
 
+Assigns labels to the given audio along with a probability score of that label.
+
+```typescript
 await hf.audioClassification({
   model: 'superb/hubert-large-superb-er',
   data: readFileSync('test/sample1.flac')
 })
+```
+
+### Text To Speech
 
+```typescript
 await hf.textToSpeech({
   model: 'espnet/kan-bayashi_ljspeech_vits',
   inputs: 'Hello world!'
 })
+```
+
+### Audio To Audio
 
+```typescript
 await hf.audioToAudio({
   model: 'speechbrain/sepformer-wham',
   data: readFileSync('test/sample1.flac')
 })
+```
+
+### Image Classification
+
+Assigns labels to a given image along with a probability score of that label.
 
-// Computer Vision
 
+```typescript
 await hf.imageClassification({
   data: readFileSync('test/cheetah.png'),
   model: 'google/vit-base-patch16-224'
 })
+```
+
+### Object Detection
 
+Detects objects within an image and returns labels with corresponding bounding boxes and probability scores.
+
+```typescript
 await hf.objectDetection({
   data: readFileSync('test/cats.png'),
   model: 'facebook/detr-resnet-50'
 })
+```
+
+### Image Segmentation
 
+Detects segments within an image and returns labels with corresponding bounding boxes and probability scores.
+
+```typescript
 await hf.imageSegmentation({
   data: readFileSync('test/cats.png'),
   model: 'facebook/detr-resnet-50-panoptic'
 })
+```
 
+### Text To Image
+
+Creates an image from a text prompt.
+
+```typescript
 await hf.textToImage({
   inputs: 'award winning high resolution photo of a giant tortoise/((ladybird)) hybrid, [trending on artstation]',
   model: 'stabilityai/stable-diffusion-2',
   parameters: {
     negative_prompt: 'blurry',
   }
 })
+```
+
+### Image To Text
+
+Captions a given image.
 
+```typescript
 await hf.imageToText({
   data: readFileSync('test/cats.png'),
   model: 'nlpconnect/vit-gpt2-image-captioning'
 })
+```
 
+### Image To Image
+
+```typescript
 await hf.imageToImage({
   inputs: new Blob([readFileSync("test/stormtrooper_depth.png")]),
   parameters: {
     prompt: "elmo's lecture",
   },
   model: "lllyasviel/sd-controlnet-depth",
 });
+```
+
+### Zero Shot Image Classification
+
+Checks how well an input image fits into a set of labels you provide.
 
+```typescript
 await hf.zeroShotImageClassification({
   model: 'openai/clip-vit-large-patch14-336',
   inputs: {
@@ -206,27 +338,35 @@ await hf.zeroShotImageClassification({
     candidate_labels: ['cat', 'dog']
   }
 })
+```
 
-// Multimodal
+### Visual Question Answering
 
+```typescript
 await hf.visualQuestionAnswering({
   model: 'dandelin/vilt-b32-finetuned-vqa',
   inputs: {
     question: 'How many cats are lying down?',
     image: await (await fetch('https://placekitten.com/300/300')).blob()
   }
 })
+```
+
+### Document Question Answering
 
+```typescript
 await hf.documentQuestionAnswering({
   model: 'impira/layoutlm-document-qa',
   inputs: {
     question: 'Invoice number?',
     image: await (await fetch('https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png')).blob(),
   }
 })
+```
 
-// Tabular
+### Tabular Regression
 
+```typescript
 await hf.tabularRegression({
   model: "scikit-learn/Fish-Weight",
   inputs: {
@@ -240,7 +380,11 @@ await hf.tabularRegression({
     },
   },
 })
+```
+
+### Tabular Classification
 
+```typescript
 await hf.tabularClassification({
   model: "vvmnnnkv/wine-quality",
   inputs: {
@@ -259,8 +403,13 @@ await hf.tabularClassification({
     },
   },
 })
+```
+
+### Custom Call
 
-// Custom call, for models with custom parameters / outputs
+For models with custom parameters / outputs.
+
+```typescript
 await hf.request({
   model: 'my-custom-model',
   inputs: 'hello world',
@@ -279,8 +428,13 @@ for await (const output of hf.streamingRequest({
 })) {
   ...
 }
+```
 
-// Using your own inference endpoint: https://hf.co/docs/inference-endpoints/
+### Custom Inference Endpoints
+
+Learn more about using your own inference endpoints [here](https://hf.co/docs/inference-endpoints/)
+
+```typescript
 const gpt2 = hf.endpoint('https://xyz.eu-west-1.aws.endpoints.huggingface.cloud/gpt2');
 const { generated_text } = await gpt2.textGeneration({inputs: 'The answer to the universe is'});
 ```