MNT move api-inference-community to root of the repo

Author: adrinjalali

Diff for: api-inference-community/MANIFEST.in renamed to MANIFEST.in

@@ -1,149 +1,96 @@
-## `huggingface_hub`
 
-### Client library to download and publish models and other files on the huggingface.co hub
+This repositories enable third-party libraries integrated with [huggingface_hub](https://github.com/huggingface/huggingface_hub/) to create
+their own docker so that the widgets on the hub can work as the `transformers` one do.
 
-<p align="center">
-	<img alt="Build" src="https://github.com/huggingface/huggingface_hub/workflows/Python%20tests/badge.svg">
-	<a href="https://github.com/huggingface/huggingface_hub/blob/master/LICENSE">
-		<img alt="GitHub" src="https://img.shields.io/github/license/huggingface/huggingface_hub.svg?color=blue">
-	</a>
-	<a href="https://github.com/huggingface/huggingface_hub/releases">
-		<img alt="GitHub release" src="https://img.shields.io/github/release/huggingface/huggingface_hub.svg">
-	</a>
-</p>
+The hardware to run the API will be provided by Hugging Face for now.
 
-> **Do you have an open source ML library?**
-> We're looking to partner with a small number of other cool open source ML libraries to provide model hosting + versioning. 
-> https://twitter.com/julien_c/status/1336374565157679104 https://twitter.com/mnlpariente/status/1336277058062852096
->
-> Advantages are:
-> - versioning is built-in (as hosting is built around git and git-lfs), no lock-in, you can just `git clone` away.
-> - anyone can upload a new model for your library, just need to add the corresponding tag for the model to be discoverable – no more need for a hardcoded list in your code
-> - Fast downloads! We use Cloudfront (a CDN) to geo-replicate downloads so they're blazing fast from anywhere on the globe
-> - Usage stats and more features to come
->
-> Ping us if interested 😎
+The `docker_images/common` folder is intended to be a starter point for all new libs that 
+want to be integrated.
 
-<br>
+### Adding a new container from a new lib.
 
-### ♻️ Partial list of implementations in third party libraries:
 
-- http://github.com/asteroid-team/asteroid [[initial PR 👀](https://github.com/asteroid-team/asteroid/pull/377)]
-- https://github.com/pyannote/pyannote-audio [[initial PR 👀](https://github.com/pyannote/pyannote-audio/pull/549)]
-- https://github.com/flairNLP/flair [[work-in-progress, initial PR 👀](https://github.com/flairNLP/flair/pull/1974)]
-- https://github.com/espnet/espnet [[initial PR 👀](https://github.com/espnet/espnet/pull/2815)]
+1. Copy the `docker_images/common` folder into your library's name `docker_images/example`.
+2. Edit:
+    - `docker_images/example/requirements.txt`
+    - `docker_images/example/app/main.py`
+    - `docker_images/example/app/pipelines/{task_name}.py` 
+    to implement the desired functionnality. All required code is marked with `IMPLEMENT_THIS` markup.
+3. Feel free to customize anything required by your lib everywhere you want. The only real requirements, are to honor the HTTP endpoints, in the same fashion as the `common` folder for all your supported tasks.
+4. Edit `example/tests/test_api.py` to add TESTABLE_MODELS.
+5. Pass the test suite `pytest -sv --rootdir docker_images/example/ docker_images/example/`
+6. Submit your PR and enjoy !
 
-<br>
+### Going the full way
 
-## Download files from the huggingface.co hub
+Doing the first 6 steps is good enough to get started, however in the process 
+you can anticipate some problems corrections early on. Maintainers will help you
+along the way if you don't feel confident to follow those steps yourself
 
-Integration inside a library is super simple. We expose two functions, `hf_hub_url()` and `cached_download()`.
+1. Test your creation within a docker
 
-### `hf_hub_url`
-
-`hf_hub_url()` takes:
-- a repo id (e.g. a model id like `julien-c/EsperBERTo-small` i.e. a user or organization name and a repo name, separated by `/`),
-- a filename (like `pytorch_model.bin`),
-- and an optional git revision id (can be a branch name, a tag, or a commit hash)
-
-and returns the url we'll use to download the actual files: `https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin`
-
-If you check out this URL's headers with a `HEAD` http request (which you can do from the command line with `curl -I`) for a few different files, you'll see that:
-- small files are returned directly
-- large files (i.e. the ones stored through [git-lfs](https://git-lfs.github.com/)) are returned via a redirect to a Cloudfront URL. Cloudfront is a Content Delivery Network, or CDN, that ensures that downloads are as fast as possible from anywhere on the globe.
-
-### `cached_download`
-
-`cached_download()` takes the following parameters, downloads the remote file, stores it to disk (in a versioning-aware way) and returns its local file path.
-
-Parameters:
-- a remote `url`
-- your library's name and version (`library_name` and `library_version`), which will be added to the HTTP requests' user-agent so that we can provide some usage stats.
-- a `cache_dir` which you can specify if you want to control where on disk the files are cached.
-
-Check out the source code for all possible params (we'll create a real doc page in the future).
-
-### Bonus: `snapshot_download`
-
-`snapshot_download()` downloads all the files from the remote repository at the specified revision, 
-stores it to disk (in a versioning-aware way) and returns its local file path.
-
-Parameters:
-- a `repo_id` in the format `namespace/repository`
-- a `revision` on which the repository will be downloaded
-- a `cache_dir` which you can specify if you want to control where on disk the files are cached.
-
-<br>
-
-## Publish models to the huggingface.co hub
-
-Uploading a model to the hub is super simple too:
-- create a model repo directly from the website, at huggingface.co/new (models can be public or private, and are namespaced under either a user or an organization)
-- clone it with git
-- [download and install git lfs](https://git-lfs.github.com/) if you don't already have it on your machine (you can check by running a simple `git lfs`)
-- add, commit and push your files, from git, as you usually do.
-
-**We are intentionally not wrapping git too much, so that you can go on with the workflow you’re used to and the tools you already know.**
+```python
+./manage.py docker --model-id MY_MODEL
+```
 
-> 👀 To see an example of how we document the model sharing process in `transformers`, check out https://huggingface.co/transformers/model_sharing.html
+should work and responds on port 8000. `curl -X POST -d "test" http://localhost:8000` for instance if 
+the pipeline deals with simple text.
 
-Users add tags into their README.md model cards (e.g. your `library_name`, a domain tag like `audio`, etc.) to make sure their models are discoverable.
+If it doesn't work out of the box and/or docker is slow for some reason you
+can test locally (using your local python environment) with :
 
-**Documentation about the model hub itself is at https://huggingface.co/docs**
+`./manage.py start --model-id MY_MODEL`
 
-### API utilities in `hf_api.py`
 
-You don't need them for the standard publishing workflow, however, if you need a programmatic way of creating a repo, deleting it (`⚠️ caution`), pushing a single file to a repo or listing models from the hub, you'll find helpers in `hf_api.py`.
+2. Test your docker uses cache properly.
 
-We also have an API to query models by specific tags (e.g. if you want to list models compatible to your library)
+When doing subsequent docker launch with the same model_id, the docker should start up very fast and not redownload the whole model file. If you see the model/repo being downloaded over and over, it means the cache is not being used correctly.
+You can edit the `docker_images/{framework}/Dockerfile` and add an environement variable (by default it assumes `HUGGINGFACE_HUB_CACHE`), or your code directly to put
+the model files in the `/data` folder.
 
-### `huggingface-cli`
+3. Add a docker test.
 
-Those API utilities are also exposed through a CLI:
+Edit the `tests/test_dockers.py` file to add a new test with your new framework
+in it (`def test_{framework}(self):` for instance). As a basic you should have 1 line per task in this test function with a real working model on the hub. Those tests are relatively slow but will check automatically that correct errors are replied by your API and that the cache works properly. To run those tests your can simply do:
 
 ```bash
-huggingface-cli login
-huggingface-cli logout
-huggingface-cli whoami
-huggingface-cli repo create
-```
-
-### Need to upload large (>5GB) files?
 
-To upload large files (>5GB 🔥), you need to install the custom transfer agent for git-lfs, bundled in this package. 
-
-To install, just run:
-
-```bash
-$ huggingface-cli lfs-enable-largefiles
+RUN_DOCKER_TESTS=1 pytest -sv tests/test_dockers.py::DockerImageTests::test_{framework}
 ```
 
-This should be executed once for each model repo that contains a model file >5GB. If you just try to push a file bigger than 5GB without running that command, you will get an error with a message reminding you to run it.
-
-Finally, there's a `huggingface-cli lfs-multipart-upload` command but that one is internal (called by lfs directly) and is not meant to be called by the user.
-
-<br>
-
-## Visual integration into the huggingface.co hub
-
-Finally, we'll implement a few tweaks to improve the UX for your models on the website – let's use [Asteroid](https://github.com/asteroid-team/asteroid) as an example:
-
-![asteroid-model](https://cdn-media.huggingface.co/huggingface_hub/asteroid-model-optim.png)
-
-Model authors add an `asteroid` tag to their model card and they get the advantages of model versioning built-in
+### Modifying files within `api-inference-community/{routes,validation,..}.py`.
 
-![use-in-asteroid](https://cdn-media.huggingface.co/huggingface_hub/use-in-asteroid.png)
+If you ever come across a bug within `api-inference-community/` package or want to update it
+the developpement process is slightly more involved.
 
-We add a custom "Use in Asteroid" button.
+- First, make sure you need to change this package, each framework is very autonomous
+ so if your code can get away by being standalone go that way first as it's much simpler.
+- If you can make the change only in `api-inference-community` without depending on it
+that's also a great option. Make sure to add the proper tests to your PR.
+- Finally, the best way to go is to develop locally using `manage.py` command:
+- Do the necessary modifications within `api-inference-community` first.
+- Install it locally in your environment with `pip install -e .`
+- Install your package dependencies locally.
+- Run your webserver locally: `./manage.py start --framework example --task audio-source-separation --model-id MY_MODEL`
+- When everything is working, you will need to split your PR in two, 1 for the `api-inference-community` part.
+  The second one will be for your package specific modifications and will only land once the `api-inference-community`
+  tag has landed.
+- This workflow is still work in progress, don't hesitate to ask questions to maintainers.
 
-![asteroid-code-sample](https://cdn-media.huggingface.co/huggingface_hub/asteroid-code-sample.png)
+Another similar command `./manage.py docker --framework example --task audio-source-separation --model-id MY_MODEL`
+Will launch the server, but this time in a protected, controlled docker environment making sure the behavior
+will be exactly the one in the API.
 
-When clicked you get a library-specific code sample that you'll be able to specify. 🔥
 
-## Inference API integration into the huggingface.co hub
 
-In order to get a functional Inference API on the hub for your models (and thus, cool working widgets!) check out this [doc](https://github.com/huggingface/huggingface_hub/tree/master/api-inference-community)
+### Available tasks
 
-<br>
+- **Automatic speech recognition**: Input is a file, output is a dict of understood words being said within the file
+- **Text generation**: Input is a text, output is a dict of generated text
+- **Image recognition**: Input is an image, output is a dict of generated text
+- **Question answering**: Input is a question + some context, output is a dict containing necessary information to locate the answer to the `question` within the `context`.
+- **Audio source separation**: Input is some audio, and the output is n audio files that sum up to the original audio but contain individual soures of sound (either speakers or instruments for instant).
+- **Token classification**: Input is some text, and the output is a list of entities mentionned in the text. Entities can be anything remarquable like locations, organisations, persons, times etc...
+- **Text to speech**: Input is some text, and the output is an audio file saying the text...
+- **Sentence Similarity**: Input is some sentence and a list of reference sentences, and the list of similarity scores.
 
-## Feedback (feature requests, bugs, etc.) is super welcome 💙💚💛💜♥️🧡