diff --git a/.env.example b/.env.example index c1cf024..c1828af 100644 --- a/.env.example +++ b/.env.example @@ -30,15 +30,15 @@ VERTEX_PROJECT_ID=example-123456 ### VERTEX_LOCATION OPTIONS: https://cloud.google.com/vertex-ai/docs/general/locations VERTEX_LOCATION=us-central1 VERTEX_GAC_PATH=/path/to/vertex-key.json -## OPENAIAPI -OPENAI_API_KEY=sk-1234567890 -### OPENAI_MODEL OPTIONS: https://platform.openai.com/docs/models -OPENAI_MODEL=gpt-3.5-turbo # OCR_ENGINE CONFIG OPTIONS ## TESSERACT TESSERACT_PATH=/path/to/tesseract.exe # LANG_ENGINE CONFIG OPTIONS +## OPENAIAPI +OPENAI_API_KEY=sk-1234567890 +### OPENAI_MODEL OPTIONS: https://platform.openai.com/docs/models +OPENAI_MODEL=gpt-3.5-turbo ## PRIVATEGPT PRIVATEGPT_HOST=http://localhost:8001 \ No newline at end of file diff --git a/README.md b/README.md index a35c1c4..e457df5 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,127 @@ # Alt-Text Backend -## ROUTES +A [OpenAPI documented](https://learn.openapis.org/) REST API for the [Alt-Text Project](https://github.com/EbookFoundation/alt-text). -### /books +Developed as a Computer Science Senior Design Project at [Stevens Institute of Technology](https://www.stevens.edu/) in collaboration with the [Free Ebook Foundation](https://ebookfoundation.org/). -#### GET +[Learn more about the developers](#the-deveolpers). -##### FUNCTION +## Getting Started -Gets a list of books from database +### Installation -##### PARAMS +#### Alt-Text PyPi Package -- query (string) | ensures book titles must have ‘query’ as a substring -- skip (int) | skips ‘skip’ amount of books from the result -- limit (int) | limits the amount of books returned to ‘limit’ +You'll first need to install the PyPi package for the [Alt-Text Project](https://github.com/EbookFoundation/alt-text). -##### RETURNS +You can find the PyPi package [here](https://pypi.org/project/alt-text/). To install the package via, you can execute the following in a terminal for your respective system... -``` -[ - { - uuid: string, - title: string, - description: string, - cover: string, - }, - ... -] +Windows
+`py -m pip install alt-text` + +Unix/MacOS
+`python3 -m pip install alt-text` + +#### Postgres + +The Alt-Text Backend needs an instance of [Postgres](https://www.postgresql.org/) to operate. You can use one hosted elsewhere or [download Postgres](https://www.postgresql.org/download/). + +#### Backend Dependencies + +Make sure to install all the required PyPi dependencies for the backend using the following... + +Windows
+`py -m pip install -r requirements.txt` + +Unix/MacOS
+`python3 -m pip install -r requirements.txt` + +### Configuration + +Before running the server, you'll need to start by configuring the settings of the server. + +To start, rename the `.env.example` file to just `.env`. + +#### Postgres Configuration + +You'll need to change the database configuration settings to your appropriate credentials... + +```bash +# DATABASE OPTIONS +DATABASE_NAME=postgres +DATABASE_HOST=127.0.0.1 +DATABASE_USER=postgres +DATABASE_PASSWORD=testpassword +DATABASE_PORT=5432 ``` -#### POST +#### General Analyzation Options -##### FUNCTION +You can change the analyzation options to your liking... -Adds a book to the database and starts initial processing - -##### FIELDS - -- title (string) | desired title for new book -- description (string) | desired description for new book -- cover (image_file) | desired cover image for new book -- file (file[.zip]) | book file (html and images bundled) - -##### RETURNS - -``` -{ - uuid: string, - title: string, - description: string, - cover: string, -} +```bash +## GENERAL OPTIONS +ALT_WITH_CONTEXT=1 +ALT_WITH_HASH=1 +ALT_MULTITHREADED=0 +### ALT_VERSION OPTIONS: 1, 2 +ALT_VERSION=2 ``` -### /books/:bookid +#### Engine Options -#### GET +The Alt-Text Backend requires that you have a Description, OCR, and Language Engine (info can be found at [Alt-Text Project README](https://github.com/EbookFoundation/alt-text)). -#### PATCH +##### Selecting Engine Types -#### DELETE +You must declare which engines you are using. -### /books/:bookid/export +```bash +## DESC_ENGINE OPTIONS: replicateapi, bliplocal, googlevertexapi +DESC_ENGINE=replicateapi +## OCR_ENGINE OPTIONS: tesseract +OCR_ENGINE=tesseract +## LANG_ENGINE OPTIONS: privategpt, openaiapi +LANG_ENGINE=openaiapi +``` -#### GET +##### Configuring Engine Options -### /books/:bookid/analyze +You must fulfill the options for the engines you're using. -#### GET +```bash +# DESC_ENGINE CONFIG OPTIONS +## REPLICATEAPI +REPLICATE_KEY=r8_somekey +## BLIPLOCAL +BLIPLOCAL_DIR=/path/to/image-captioning +## GOOGLEVERTEXAPI +VERTEX_PROJECT_ID=example-123456 +### VERTEX_LOCATION OPTIONS: https://cloud.google.com/vertex-ai/docs/general/locations +VERTEX_LOCATION=us-central1 +VERTEX_GAC_PATH=/path/to/vertex-key.json -### /books/:bookid/images +# OCR_ENGINE CONFIG OPTIONS +## TESSERACT +TESSERACT_PATH=/path/to/tesseract.exe -#### GET +# LANG_ENGINE CONFIG OPTIONS +## OPENAIAPI +OPENAI_API_KEY=sk-1234567890 +### OPENAI_MODEL OPTIONS: https://platform.openai.com/docs/models +OPENAI_MODEL=gpt-3.5-turbo +## PRIVATEGPT +PRIVATEGPT_HOST=http://localhost:8001 +``` -#### PATCH +### Starting the Server -### /books/:bookid/images/:imagesrc +You can start the server with the following... -#### GET +`py manage.py runserver` -#### PATCH +### Usage + +You can see the all routes/features in the `openapi.yaml` file. + +We'd recommend to use a visuallizer for it, such as [Swagger](https://editor.swagger.io/).