python-pdf2txt/README.md

# python-pdf2txt

`python-pdf2txt` is a Dockerized Python application designed to convert PDF files into editable Word documents. The application utilizes Flask to expose a web service that handles PDF file uploads through HTTP requests and returns the converted DOCX files using OCR technology.

## Features

- **PDF to Word Conversion**: Transforms PDF documents into DOCX format using advanced OCR capabilities.
- **Dockerized Application**: Facilitates easy deployment and consistent performance across various environments.
- **REST API**: Simple API for straightforward integration, supporting PDF uploads and DOCX retrievals.

## Getting Started

### Step 1: Clone the Repository

Clone the repository to your local machine to get started:

```bash
git clone https://github.com/your-username/python-pdf2txt.git
cd python-pdf2txt
```

### Step 2: Build and Run the Docker Container

Use Docker Compose to build and run your container:

```bash
docker-compose up --build -d
```

This command constructs the Docker image if it hasn't been built previously and runs the container in detached mode. The service will be available at localhost on port 4000.

### Step 3: Convert a PDF to Word

Convert a PDF to a Word document by executing the following curl command:

```bash
curl -X POST -F "file=@path_to_your_pdf_file.pdf" http://localhost:4000/upload-pdf --output converted.docx
```

Make sure to replace `path_to_your_pdf_file.pdf` with the actual path to the PDF you intend to convert. The output will be saved as `converted.docx`.

### Step 4: View Application Logs

To track the application's processes in real-time, you can view the logs:

```bash
tail -f ./logs/*
```

This command tails the log files, offering a live view into the application’s operational logs.

## New Features

### Callback URL Support

The application now includes the ability to process PDF to Word conversions asynchronously. Once the conversion process is complete, the converted `.docx` file is sent to a specified callback URL. This feature allows the processing to occur in the background, freeing up clients to perform other tasks rather than waiting for a synchronous response.

## Updated Usage Instructions

### Asynchronous Conversion with Callback URL

1. **Trigger the Conversion**:
   To request a PDF conversion and have the application send the resulting `.docx` file to a callback URL once processing is done, use the curl command as follows:

   ```bash
   curl -X POST -F "file=@path_to_your_pdf_file.pdf" \
        -F "callback_url=http://<your-callback-url>/callback" \
        http://localhost:4000/upload-pdf
   ```

   Replace `path_to_your_pdf_file.pdf` with the path to your actual PDF file, and `<your-callback-url>` with your service's callback URL.

2. **Callback Server Setup**:
   Prepare your callback server to handle incoming POST requests at the `/callback` endpoint. The server should process the incoming `.docx` file as per your application's logic.

### Example Callback Endpoint

Here's an example Flask route that could serve as your callback endpoint:

```python
@app.route('/callback', methods=['POST'])
def callback():
    file = request.files['file']
    # Implement file handling logic here
    return jsonify({'message': 'File received successfully'}), 200
```

This endpoint will be invoked with the converted .docx file after the PDF conversion is complete.

### Test Command for Callback Feature

To test the callback functionality, you can use the following curl command. This will send a PDF file to the /upload-pdf endpoint along with a callback_url. After the PDF is processed, the application will send the converted .docx file to the provided callback URL:

```bash
curl -X POST -F "file=@uploads/sample_input.pdf" \
     -F "callback_url=http://localhost:5000/callback" \
     http://localhost:4000/upload-pdf
```

Be sure to replace `http://localhost:5000/callback` with your actual callback endpoint that's ready to accept the file.

## Configuration Details

### Environment Variables

The application uses several environment variables to configure its behavior:

- `FLASK_ENV`: Sets the environment for the Flask application. In this case, `development` for enabling debug features.
- `FLASK_APP`: Points to the entry file of the Flask application. Here, it's set to `app.py`.
- `TESSDATA_PREFIX`: Specifies the directory where the Tesseract OCR data is stored, which is crucial for OCR functionality.

### Port Configuration

The Docker container is configured to expose the Flask application on port `4000` of the host machine, mapping it to port 5000 inside the container. This mapping is defined in the `docker-compose.yml` file, allowing the application to be accessible via `http://localhost:4000`.

### Volume Management

- **Uploads Folder**: The `./uploads` folder on the host is mapped to `/app/uploads` inside the Docker container. This is where uploaded PDF files are stored temporarily during processing.
- **Outputs Folder**: Similarly, the `./outputs` folder on the host is mapped to `/app/outputs` inside the container. This folder stores the converted Word documents, making them accessible outside the container.
- **Logs Folder**: The `./logs` folder is used to store log files generated by the application, providing insights into its operations and any errors.

This setup ensures that data persists across container restarts and is easily accessible for both inputs and outputs.