From fa3ca1d08a7adddd291feb697287604f9b4cd93e Mon Sep 17 00:00:00 2001 From: Deshraj Yadav Date: Fri, 3 Nov 2023 00:42:55 -0700 Subject: [PATCH] [REST API] Incorporate changes related to REST API docs (#900) --- README.md | 6 +- .../add-datasource-to-an-app.mdx | 3 - docs/api-reference/deploy-app.mdx | 3 - docs/api-reference/getting-started.mdx | 6 +- docs/mint.json | 5 +- docs/rest-api.json | 35 ++++---- docs/rest-api/add-data.mdx | 22 +++++ docs/rest-api/chat.mdx | 3 + docs/rest-api/check-status.mdx | 20 +++++ docs/rest-api/create.mdx | 21 +++++ docs/rest-api/delete.mdx | 21 +++++ docs/rest-api/deploy.mdx | 22 +++++ docs/rest-api/get-all-apps.mdx | 33 +++++++ docs/rest-api/get-data.mdx | 28 ++++++ docs/rest-api/getting-started.mdx | 87 +++++++++++++++++++ docs/rest-api/query.mdx | 21 +++++ examples/rest-api/Dockerfile | 4 +- examples/rest-api/README.md | 4 +- .../bruno/ec-rest-api/default_add.bru | 2 +- .../bruno/ec-rest-api/default_chat.bru | 2 +- .../bruno/ec-rest-api/default_query.bru | 2 +- examples/rest-api/bruno/ec-rest-api/ping.bru | 2 +- examples/rest-api/main.py | 20 ++--- 23 files changed, 323 insertions(+), 49 deletions(-) delete mode 100644 docs/api-reference/add-datasource-to-an-app.mdx delete mode 100644 docs/api-reference/deploy-app.mdx create mode 100644 docs/rest-api/add-data.mdx create mode 100644 docs/rest-api/chat.mdx create mode 100644 docs/rest-api/check-status.mdx create mode 100644 docs/rest-api/create.mdx create mode 100644 docs/rest-api/delete.mdx create mode 100644 docs/rest-api/deploy.mdx create mode 100644 docs/rest-api/get-all-apps.mdx create mode 100644 docs/rest-api/get-data.mdx create mode 100644 docs/rest-api/getting-started.mdx create mode 100644 docs/rest-api/query.mdx diff --git a/README.md b/README.md index d40b378a..c2f60c1d 100644 --- a/README.md +++ b/README.md @@ -26,13 +26,13 @@ Book a [1-on-1 Session](https://cal.com/taranjeetio/ec) with Taranjeet, the foun pip install --upgrade embedchain ``` -To run Embedchain as a REST API server use, +To run Embedchain as a REST API server run the following command: ```bash -docker run -d --name embedchain -p 8000:8000 embedchain/app:rest-api-latest +docker run -d --name embedchain -p 8080:8080 embedchain/app:rest-api-latest ``` -Navigate to http://0.0.0.0:8000/docs to interact with the API. +Navigate to http://0.0.0.0:8080/docs to interact with the API. ## 🔍 Demo diff --git a/docs/api-reference/add-datasource-to-an-app.mdx b/docs/api-reference/add-datasource-to-an-app.mdx deleted file mode 100644 index 28f845ea..00000000 --- a/docs/api-reference/add-datasource-to-an-app.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: post /{app_id}/add ---- \ No newline at end of file diff --git a/docs/api-reference/deploy-app.mdx b/docs/api-reference/deploy-app.mdx deleted file mode 100644 index 830b804e..00000000 --- a/docs/api-reference/deploy-app.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: post /{app_id}/deploy ---- \ No newline at end of file diff --git a/docs/api-reference/getting-started.mdx b/docs/api-reference/getting-started.mdx index 88917a37..b2e651ab 100644 --- a/docs/api-reference/getting-started.mdx +++ b/docs/api-reference/getting-started.mdx @@ -7,10 +7,10 @@ title: "🌍 Getting Started" To run Embedchain as a REST API server use, ```bash -docker run -d --name embedchain -p 8000:8000 embedchain/app:rest-api-latest +docker run -d --name embedchain -p 8080:8080 embedchain/app:rest-api-latest ``` -Open up your browser and navigate to http://0.0.0.0:8000/docs to interact with the API. There is a full-fledged Swagger docs playground with all the information +Open up your browser and navigate to http://0.0.0.0:8080/docs to interact with the API. There is a full-fledged Swagger docs playground with all the information about the API endpoints. ![Swagger Docs Screenshot](https://github.com/embedchain/embedchain/assets/73601258/299d81e5-a0df-407c-afc2-6fa2c4286844) @@ -83,7 +83,7 @@ To provide them, you can simply run the docker command with the `-e` flag. For example, ```bash -docker run -d --name embedchain -p 8000:8000 -e OPENAI_API_KEY=YOUR_API_KEY embedchain/app:rest-api-latest +docker run -d --name embedchain -p 8080:8080 -e OPENAI_API_KEY=YOUR_API_KEY embedchain/app:rest-api-latest ``` Cool! This will create a new Embedchain App with the given `app_id`. diff --git a/docs/mint.json b/docs/mint.json index 00cd777e..3ccd4bd0 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -92,7 +92,7 @@ "pages": ["advanced/configuration"] }, { - "group": "Rest API", + "group": "REST API", "pages": [ "api-reference/getting-started", "api-reference/check-status", @@ -161,5 +161,8 @@ }, "search": { "prompt": "✨ Search embedchain docs..." + }, + "api": { + "baseUrl": "http://localhost:8080" } } diff --git a/docs/rest-api.json b/docs/rest-api.json index e35529fb..ecb40f86 100644 --- a/docs/rest-api.json +++ b/docs/rest-api.json @@ -13,8 +13,8 @@ "/ping": { "get": { "tags": ["Utility"], - "summary": "Check Status", - "description": "Endpoint to check the status of the API.", + "summary": "Check status", + "description": "Endpoint to check the status of the API", "operationId": "check_status_ping_get", "responses": { "200": { @@ -27,8 +27,8 @@ "/apps": { "get": { "tags": ["Apps"], - "summary": "Get All Apps", - "description": "Get all apps.", + "summary": "Get all apps", + "description": "Get all applications", "operationId": "get_all_apps_apps_get", "responses": { "200": { @@ -41,8 +41,8 @@ "/create": { "post": { "tags": ["Apps"], - "summary": "Create App", - "description": "Create a new app using App ID.", + "summary": "Create app", + "description": "Create a new app using App ID", "operationId": "create_app_using_default_config_create_post", "parameters": [ { @@ -89,8 +89,8 @@ "/{app_id}/data": { "get": { "tags": ["Apps"], - "summary": "Get Datasources Associated With App Id", - "description": "Get all datasources for an app.", + "summary": "Get data", + "description": "Get all data sources for an app", "operationId": "get_datasources_associated_with_app_id__app_id__data_get", "parameters": [ { @@ -119,8 +119,8 @@ "/{app_id}/add": { "post": { "tags": ["Apps"], - "summary": "Add Datasource To An App", - "description": "Add a source to an existing app.", + "summary": "Add data", + "description": "Add a data source to an app.", "operationId": "add_datasource_to_an_app__app_id__add_post", "parameters": [ { @@ -161,8 +161,8 @@ "/{app_id}/query": { "post": { "tags": ["Apps"], - "summary": "Query An App", - "description": "Query an existing app.", + "summary": "Query app", + "description": "Query an app", "operationId": "query_an_app__app_id__query_post", "parameters": [ { @@ -203,8 +203,8 @@ "/{app_id}/chat": { "post": { "tags": ["Apps"], - "summary": "Chat With An App", - "description": "Query an existing app.\n\napp_id: The ID of the app. Use \"default\" for the default app.\n\nmessage: The message that you want to send to the App.", + "summary": "Chat", + "description": "Chat with an app.\n\napp_id: The ID of the app. Use \"default\" for the default app.\n\nmessage: The message that you want to send to the app.", "operationId": "chat_with_an_app__app_id__chat_post", "parameters": [ { @@ -287,8 +287,8 @@ "/{app_id}/delete": { "delete": { "tags": ["Apps"], - "summary": "Delete App", - "description": "Delete an existing app.", + "summary": "Delete app", + "description": "Delete an existing app", "operationId": "delete_app__app_id__delete_delete", "parameters": [ { @@ -339,7 +339,7 @@ "api_key": { "type": "string", "title": "Api Key", - "description": "The Embedchain API key for App deployments.", + "description": "The Embedchain API key for app deployments. You get the api key on the Embedchain platform by visiting [https://app.embedchain.ai](https://app.embedchain.ai)", "default": "" } }, @@ -425,4 +425,3 @@ } } } - \ No newline at end of file diff --git a/docs/rest-api/add-data.mdx b/docs/rest-api/add-data.mdx new file mode 100644 index 00000000..05ed3796 --- /dev/null +++ b/docs/rest-api/add-data.mdx @@ -0,0 +1,22 @@ +--- +openapi: post /{app_id}/add +--- + + + +```bash Request +curl --request POST \ + --url http://localhost:8080/{app_id}/add \ + -d "source=https://www.forbes.com/profile/elon-musk" \ + -d "data_type=web_page" +``` + + + + + +```json Response +{ "response": "fec7fe91e6b2d732938a2ec2e32bfe3f" } +``` + + diff --git a/docs/rest-api/chat.mdx b/docs/rest-api/chat.mdx new file mode 100644 index 00000000..2571bf71 --- /dev/null +++ b/docs/rest-api/chat.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /{app_id}/chat +--- \ No newline at end of file diff --git a/docs/rest-api/check-status.mdx b/docs/rest-api/check-status.mdx new file mode 100644 index 00000000..0893cba4 --- /dev/null +++ b/docs/rest-api/check-status.mdx @@ -0,0 +1,20 @@ +--- +openapi: get /ping +--- + + + +```bash Request + curl --request GET \ + --url http://localhost:8080/ping +``` + + + + + +```json Response +{ "ping": "pong" } +``` + + diff --git a/docs/rest-api/create.mdx b/docs/rest-api/create.mdx new file mode 100644 index 00000000..113b7678 --- /dev/null +++ b/docs/rest-api/create.mdx @@ -0,0 +1,21 @@ +--- +openapi: post /create +--- + + + +```bash Request +curl --request POST \ + --url http://localhost:8080/create \ + -F "config=@/path/to/config.yaml" +``` + + + + + +```json Response +{ "response": "App created successfully. App ID: {app_id}" } +``` + + diff --git a/docs/rest-api/delete.mdx b/docs/rest-api/delete.mdx new file mode 100644 index 00000000..3aada339 --- /dev/null +++ b/docs/rest-api/delete.mdx @@ -0,0 +1,21 @@ +--- +openapi: delete /{app_id}/delete +--- + + + + +```bash Request + curl --request DELETE \ + --url http://localhost:8080/{app_id}/delete +``` + + + + + +```json Response +{ "response": "App with id {app_id} deleted successfully." } +``` + + diff --git a/docs/rest-api/deploy.mdx b/docs/rest-api/deploy.mdx new file mode 100644 index 00000000..b72f91da --- /dev/null +++ b/docs/rest-api/deploy.mdx @@ -0,0 +1,22 @@ +--- +openapi: post /{app_id}/deploy +--- + + + + +```bash Request +curl --request POST \ + --url http://localhost:8080/{app_id}/deploy \ + -d "api_key=ec-xxxx" +``` + + + + + +```json Response +{ "response": "App deployed successfully." } +``` + + diff --git a/docs/rest-api/get-all-apps.mdx b/docs/rest-api/get-all-apps.mdx new file mode 100644 index 00000000..6f603f9a --- /dev/null +++ b/docs/rest-api/get-all-apps.mdx @@ -0,0 +1,33 @@ +--- +openapi: get /apps +--- + + + +```bash Request +curl --request GET \ + --url http://localhost:8080/apps +``` + + + + + +```json Response +{ + "results": [ + { + "config": "config1.yaml", + "id": 1, + "app_id": "app1" + }, + { + "config": "config2.yaml", + "id": 2, + "app_id": "app2" + } + ] +} +``` + + diff --git a/docs/rest-api/get-data.mdx b/docs/rest-api/get-data.mdx new file mode 100644 index 00000000..0c960e6c --- /dev/null +++ b/docs/rest-api/get-data.mdx @@ -0,0 +1,28 @@ +--- +openapi: get /{app_id}/data +--- + + + +```bash Request +curl --request GET \ + --url http://localhost:8080/{app_id}/data +``` + + + + + +```json Response +{ + "results": [ + { + "data_type": "web_page", + "data_value": "https://www.forbes.com/profile/elon-musk/", + "metadata": "null" + } + ] +} +``` + + diff --git a/docs/rest-api/getting-started.mdx b/docs/rest-api/getting-started.mdx new file mode 100644 index 00000000..bdeda749 --- /dev/null +++ b/docs/rest-api/getting-started.mdx @@ -0,0 +1,87 @@ +--- +title: "🌍 Getting Started" +--- + +## Quickstart + +To use Embedchain as a REST API service, run the following command: + +```bash +docker run --name embedchain -p 8080:8080 embedchain/app:rest-api-latest +``` + +Navigate to [http://localhost:8080/docs](http://localhost:8080/docs) to interact with the API. There is a full-fledged Swagger docs playground with all the information about the API endpoints. + +![Swagger Docs Screenshot](https://github.com/embedchain/embedchain/assets/73601258/299d81e5-a0df-407c-afc2-6fa2c4286844) + +## Creating your first App + +App requires an `app_id` to be created. The `app_id` is a unique identifier for your app. By default we will use the opensource **gpt4all** model to get started. You can also specify your own config by uploading a config YAML file. + +For example, create a `config.yaml` file (adjust according to your requirements): + +```yaml +app: + config: + id: "default-app" + +llm: + provider: openai + config: + model: "gpt-3.5-turbo" + temperature: 0.5 + max_tokens: 1000 + top_p: 1 + stream: false + template: | + Use the following pieces of context to answer the query at the end. + If you don't know the answer, just say that you don't know, don't try to make up an answer. + + $context + + Query: $query + + Helpful Answer: + +vectordb: + provider: chroma + config: + collection_name: "rest-api-app" + dir: db + allow_reset: true + +embedder: + provider: openai + config: + model: "text-embedding-ada-002" +``` + +To learn more about custom configurations, check out the [custom configurations docs](https://docs.embedchain.ai/advanced/configuration). To explore more examples of config yamls for embedchain, visit [embedchain/configs](https://github.com/embedchain/embedchain/tree/main/configs). + +Now, you can upload this config file in the request body. + +**Note:** To use custom models, an **API key** might be required. Refer to the table below to determine the necessary API key for your provider. + +| Keys | Providers | +| -------------------------- | ------------------------------ | +| `OPENAI_API_KEY ` | OpenAI, Azure OpenAI, Jina etc | +| `OPENAI_API_TYPE` | Azure OpenAI | +| `OPENAI_API_BASE` | Azure OpenAI | +| `OPENAI_API_VERSION` | Azure OpenAI | +| `COHERE_API_KEY` | Cohere | +| `ANTHROPIC_API_KEY` | Anthropic | +| `JINACHAT_API_KEY` | Jina | +| `HUGGINGFACE_ACCESS_TOKEN` | Huggingface | +| `REPLICATE_API_TOKEN` | LLAMA2 | + +To add env variables, you can simply run the docker command with the `-e` flag. + +For example, + +```bash +docker run --name embedchain -p 8080:8080 -e OPENAI_API_KEY= embedchain/app:rest-api-latest +``` + +If you run into issues, please feel free to contact us using below links: + + diff --git a/docs/rest-api/query.mdx b/docs/rest-api/query.mdx new file mode 100644 index 00000000..2d647e50 --- /dev/null +++ b/docs/rest-api/query.mdx @@ -0,0 +1,21 @@ +--- +openapi: post /{app_id}/query +--- + + + +```bash Request +curl --request POST \ + --url http://localhost:8080/{app_id}/query \ + -d "query=who is Elon Musk?" +``` + + + + + +```json Response +{ "response": "Net worth of Elon Musk is $218 Billion." } +``` + + diff --git a/examples/rest-api/Dockerfile b/examples/rest-api/Dockerfile index 9d9c58c6..fe36d4ad 100644 --- a/examples/rest-api/Dockerfile +++ b/examples/rest-api/Dockerfile @@ -8,8 +8,8 @@ RUN pip install --no-cache-dir -r requirements.txt COPY . /app -EXPOSE 8000 +EXPOSE 8080 ENV NAME embedchain -CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] +CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"] diff --git a/examples/rest-api/README.md b/examples/rest-api/README.md index 1e5b9571..9f34da8f 100644 --- a/examples/rest-api/README.md +++ b/examples/rest-api/README.md @@ -1,7 +1,7 @@ ## Single command to rule them all, ```bash -docker run -d --name embedchain -p 8000:8000 embedchain/app:rest-api-latest +docker run -d --name embedchain -p 8080:8080 embedchain/app:rest-api-latest ``` ### To run the app locally, @@ -15,7 +15,7 @@ Using docker (locally), ```bash docker build -t embedchain/app:rest-api-latest . -docker run -d --name embedchain -p 8000:8000 embedchain/app:rest-api-latest +docker run -d --name embedchain -p 8080:8080 embedchain/app:rest-api-latest docker image push embedchain/app:rest-api-latest ``` diff --git a/examples/rest-api/bruno/ec-rest-api/default_add.bru b/examples/rest-api/bruno/ec-rest-api/default_add.bru index 06d2e8ef..1cd0144b 100644 --- a/examples/rest-api/bruno/ec-rest-api/default_add.bru +++ b/examples/rest-api/bruno/ec-rest-api/default_add.bru @@ -5,7 +5,7 @@ meta { } post { - url: http://localhost:8000/add + url: http://localhost:8080/add body: json auth: none } diff --git a/examples/rest-api/bruno/ec-rest-api/default_chat.bru b/examples/rest-api/bruno/ec-rest-api/default_chat.bru index d0fde8d5..4c4cbced 100644 --- a/examples/rest-api/bruno/ec-rest-api/default_chat.bru +++ b/examples/rest-api/bruno/ec-rest-api/default_chat.bru @@ -5,7 +5,7 @@ meta { } post { - url: http://localhost:8000/chat + url: http://localhost:8080/chat body: json auth: none } diff --git a/examples/rest-api/bruno/ec-rest-api/default_query.bru b/examples/rest-api/bruno/ec-rest-api/default_query.bru index 95947583..61e55c6b 100644 --- a/examples/rest-api/bruno/ec-rest-api/default_query.bru +++ b/examples/rest-api/bruno/ec-rest-api/default_query.bru @@ -5,7 +5,7 @@ meta { } post { - url: http://localhost:8000/query + url: http://localhost:8080/query body: json auth: none } diff --git a/examples/rest-api/bruno/ec-rest-api/ping.bru b/examples/rest-api/bruno/ec-rest-api/ping.bru index 5deddbfe..22128827 100644 --- a/examples/rest-api/bruno/ec-rest-api/ping.bru +++ b/examples/rest-api/bruno/ec-rest-api/ping.bru @@ -5,7 +5,7 @@ meta { } get { - url: http://localhost:8000/ping + url: http://localhost:8080/ping body: json auth: none } diff --git a/examples/rest-api/main.py b/examples/rest-api/main.py index c871f707..a1f0d842 100644 --- a/examples/rest-api/main.py +++ b/examples/rest-api/main.py @@ -39,7 +39,7 @@ app = FastAPI( @app.get("/ping", tags=["Utility"]) def check_status(): """ - Endpoint to check the status of the API. + Endpoint to check the status of the API """ return {"ping": "pong"} @@ -85,7 +85,7 @@ async def create_app_using_default_config(app_id: str, config: UploadFile = None return DefaultResponse(response=f"App created successfully. App ID: {app_id}") except Exception as e: - raise HTTPException(detail=f"Error creating app: {e}", status_code=400) + raise HTTPException(detail=f"Error creating app: {str(e)}", status_code=400) @app.get( @@ -94,7 +94,7 @@ async def create_app_using_default_config(app_id: str, config: UploadFile = None ) async def get_datasources_associated_with_app_id(app_id: str, db: Session = Depends(get_db)): """ - Get all datasources for an app.\n + Get all data sources for an app.\n app_id: The ID of the app. Use "default" for the default app.\n """ try: @@ -120,7 +120,7 @@ async def get_datasources_associated_with_app_id(app_id: str, db: Session = Depe status_code=400, ) except Exception as e: - raise HTTPException(detail=f"Error occurred: {e}", status_code=400) + raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400) @app.post( @@ -158,7 +158,7 @@ async def add_datasource_to_an_app(body: SourceApp, app_id: str, db: Session = D status_code=400, ) except Exception as e: - raise HTTPException(detail=f"Error occurred: {e}", status_code=400) + raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400) @app.post( @@ -195,7 +195,7 @@ async def query_an_app(body: QueryApp, app_id: str, db: Session = Depends(get_db status_code=400, ) except Exception as e: - raise HTTPException(detail=f"Error occurred: {e}", status_code=400) + raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400) # FIXME: The chat implementation of Embedchain needs to be modified to work with the REST API. @@ -236,7 +236,7 @@ async def query_an_app(body: QueryApp, app_id: str, db: Session = Depends(get_db # status_code=400, # ) # except Exception as e: -# raise HTTPException(detail=f"Error occurred: {e}", status_code=400) +# raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400) @app.post( @@ -278,7 +278,7 @@ async def deploy_app(body: DeployAppRequest, app_id: str, db: Session = Depends( status_code=400, ) except Exception as e: - raise HTTPException(detail=f"Error occurred: {e}", status_code=400) + raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400) @app.delete( @@ -311,11 +311,11 @@ async def delete_app(app_id: str, db: Session = Depends(get_db)): remove_app(db, app_id) return DefaultResponse(response=f"App with id {app_id} deleted successfully.") except Exception as e: - raise HTTPException(detail=f"Error occurred: {e}", status_code=400) + raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400) if __name__ == "__main__": import uvicorn is_dev = os.getenv("DEVELOPMENT", "False") - uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=bool(is_dev)) + uvicorn.run("main:app", host="0.0.0.0", port=8080, reload=bool(is_dev))