Skip to content

fahiiim/Right-Route-App-OCR-Module

BranchesTags

Repository files navigation

Right Route App - OCR Module

Python Version License Code Quality Last Updated

AWS Amazon Textract OpenAI PyPDF2 Pillow

Boto3 Python Dotenv Requests

OCR AI NLP PDF Processing

Document Processing Route Extraction Structured Data REST API Ready

Professional-grade OCR solution for automated route extraction from permit documents and images

Overview

The Right Route App OCR Module is a robust, enterprise-ready solution that leverages advanced Optical Character Recognition (OCR) and Artificial Intelligence to automatically extract route information from permit documents. Built with AWS Textract and OpenAI's GPT-3.5, this module provides accurate, structured data extraction with minimal human intervention.

Key Capabilities

  • 🎯 Intelligent Text Extraction - AWS Textract with PyPDF2 fallback for multi-format document support
  • 🤖 AI-Powered Information Parsing - OpenAI GPT-3.5 for contextual route intelligence
  • 📄 Multi-Format Support - PDF, JPG, PNG, GIF, WebP documents
  • 🔍 Structured Output - JSON-formatted route data with geographic coordinates
  • ⚡ High Accuracy - Optimized for permit documents and travel documents

System Architecture

image

Prerequisites

System Requirements

  • Python: 3.8 or higher
  • OS: Windows, macOS, or Linux
  • RAM: Minimum 2GB recommended
  • Disk Space: 500MB for dependencies

External Services

  1. AWS Account with:

    • AWS Textract service access
    • S3 bucket (optional, for document storage)
    • Proper IAM credentials configured

  2. OpenAI API Key:

    • OpenAI account with API access
    • Sufficient API credits/quota

Quick Start

1. Clone Repository

git clone https://github.com/fahiiim/Right-Route-App-OCR-Module.git
cd Right-Route-App-OCR-Module

2. Install Dependencies

pip install -r requirements.txt

This installs:

  • boto3 - AWS SDK
  • openai - OpenAI API client
  • fastapi and uvicorn - REST API server
  • python-dotenv - Environment variable management
  • python-multipart - File upload handling
  • pymupdf - PDF processing and text extraction
  • Pillow - Image processing
  • requests - HTTP client

3. Configure Environment Variables

Create a .env file in the project root:

# AWS Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key

# Optional: AWS S3 Configuration
AWS_S3_BUCKET=your_s3_bucket_name

⚠️ Security Note: Never commit .env file to version control. Use environment variables in production.

4. Run the Module

python main.py path/to/document.pdf

Example Output:

🌐 OCR Module - Route Information Extractor
============================================================

📄 Processing document: permit.pdf
============================================================
🔍 Extracting text from document using AWS Textract...
  ✅ PDF text extracted with PyPDF2
✅ Text extraction successful

📝 Extracted Text Preview:
------------------------------------------------------------
[Extracted text content...]
------------------------------------------------------------

🤖 Extracting route information using OpenAI...
✅ Route extraction successful

🗺️  Route Information:
------------------------------------------------------------
{
  "start_location": "Main St & 5th Ave, New York, NY",
  "end_location": "Broadway & 42nd St, New York, NY",
  "route_segments": [
    "Main St northbound",
    "Turn left on 5th Ave",
    "Turn right on Broadway",
    "Destination on right"
  ]
}
------------------------------------------------------------

5. Run the REST API (Local)

uvicorn api:app --host 0.0.0.0 --port 8001

Once running:

  • API root: http://localhost:8001/
  • Interactive docs: http://localhost:8001/docs
  • OCR endpoint: POST http://localhost:8001/api/ocr/extract

Docker Quick Start

1. Prepare environment variables

# Windows PowerShell
Copy-Item .env.example .env

# macOS/Linux
cp .env.example .env

Update .env with your real AWS and OpenAI credentials.

2. Build and run with Docker Compose

docker compose up --build -d

3. Test the containerized API

curl http://localhost:8001/

Swagger docs will be available at http://localhost:8001/docs.

4. Stop the container

docker compose down

Live Link From Docker (No Cloud Deployment)

If your container is already running on port 8001, you can create a temporary public link directly from your machine.

1. Keep Docker container running

docker compose up -d

2. Start temporary public tunnel

ssh -o StrictHostKeyChecking=no -R 80:localhost:8001 nokey@localhost.run

The terminal will print a public HTTPS URL (example: https://abc123.localhost.run).

3. Share this link with backend engineer

  • GET https://<your-tunnel-domain>/
  • GET https://<your-tunnel-domain>/docs
  • POST https://<your-tunnel-domain>/api/ocr/extract

4. Stop live link when done

Close the tunnel terminal with Ctrl + C.

Note: this tunnel link is temporary and changes when restarted.

Usage Guide

Command Line Usage

# Process a single document
python main.py document.pdf

# Process an image
python main.py permit.jpg

# Process multiple documents (in a loop)
for file in uploads/*.pdf; do
    python main.py "$file"
done

Supported File Formats

Format Extension Support
PDF .pdf ✅ Full
JPEG .jpg, .jpeg ✅ Full
PNG .png ✅ Full
GIF .gif ✅ Full
WebP .webp ✅ Full

Output Format

The module returns structured JSON data:

{
  "filename": "permit.pdf",
  "extracted_text": "Full text content extracted...",
  "route_information": {
    "start_location": "Main St & 5th Ave, New York, NY",
    "end_location": "Broadway & 42nd St, New York, NY",
    "route_segments": [
      "Main St northbound",
      "Turn right on 5th Ave",
      "Destination on right"
    ]
  }
}

API Reference

Function: process_document(file_path)

Processes a document and extracts route information.

Parameters:

  • file_path (str): Full path to the document

Returns:

  • dict: Structured output with extraction results
  • None: If processing fails

Example:

from main import process_document

result = process_document("permits/document.pdf")
if result:
    print(result["route_information"]["start_location"])

Function: extract_text_from_document(file_path, document_name)

Extracts raw text using AWS Textract or PyPDF2.

Parameters:

  • file_path (str): Path to document
  • document_name (str): Document identifier

Returns:

  • tuple: (extracted_text, job_id)

Function: extract_route_information(extracted_text)

Parses extracted text using OpenAI GPT-3.5.

Parameters:

  • extracted_text (str): Raw text to process

Returns:

  • dict: Structured route information

Performance Metrics

Metric Value
Average Processing Time 2-5 seconds per document
Text Extraction Accuracy 95%+ (AWS Textract)
Route Parsing Accuracy 92%+ (GPT-3.5)
Supported Concurrent Requests 10+ (with proper scaling)
File Size Limit Up to 50MB (AWS limit)

Troubleshooting

Common Issues

1. AWS Textract Service Error

❌ Error: Error extracting text from document: An error occurred (InvalidSignatureException)

Solution: Verify AWS credentials in .env file

aws sts get-caller-identity  # Test AWS credentials

2. OpenAI API Rate Limit

❌ Error: Error extracting route information: RateLimitError

Solution:

  • Wait before retrying
  • Check API quota limits in OpenAI dashboard
  • Upgrade account tier if needed

3. PDF Extraction Failures

⚠️  PyPDF2 extraction failed

Solution:

  • Try updating PyPDF2: pip install --upgrade PyPDF2
  • Module automatically falls back to AWS Textract
  • Some encrypted PDFs may require decryption

4. File Not Found

❌ Error: File not found

Solution: Use absolute file path:

python main.py C:\Full\Path\To\document.pdf  # Windows
python main.py /full/path/to/document.pdf    # macOS/Linux

Configuration Guide

AWS Textract Setup

  1. Go to AWS IAM Console
  2. Create user with TextractFullAccess policy
  3. Generate Access Keys
  4. Add to .env file

OpenAI API Setup

  1. Visit OpenAI Platform
  2. Create/login to account
  3. Generate API key in dashboard
  4. Set OPENAI_API_KEY in .env

Code Structure

Social-wifi OCR Module/
├── api.py                     # FastAPI application and endpoints
├── main.py                    # OCR extraction and AI parsing logic
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Container build definition
├── docker-compose.yml         # Local container orchestration
├── .env.example               # Environment variable template
├── .env                       # Local secrets (git-ignored)
├── uploads/                   # Optional local document directory
└── README.md                  # Documentation

Dependencies

Package Version Purpose
boto3 ≥1.28.0 AWS SDK
botocore ≥1.31.0 AWS SDK core configuration
fastapi ≥0.104.0 REST API framework
uvicorn ≥0.24.0 ASGI server
openai ≥1.5.0 OpenAI API
python-dotenv ≥1.0.0 Environment variables
python-multipart ≥0.0.6 Multipart file uploads
pymupdf ≥1.24.0 PDF text extraction
Pillow ≥11.0.0 Image processing
requests ≥2.31.0 HTTP requests

For detailed versions, see requirements.txt

Best Practices

Document Preparation

  • PDF Quality: Ensure documents are clear and readable
  • Language: English documents supported (others may have lower accuracy)
  • Resolution: Scanned documents should be 200+ DPI
  • Color: Color documents process faster than B&W

API Usage Optimization

  • Batch Processing: Process documents sequentially to avoid rate limits
  • Cost Control: Monitor OpenAI API usage in dashboard
  • Error Handling: Implement retry logic with exponential backoff
  • Caching: Cache extraction results when possible

Security Considerations

  • ✅ Store credentials in environment variables
  • ✅ Use IAM roles instead of access keys in production
  • ✅ Implement request logging (exclude sensitive data)
  • ✅ Rotate API keys regularly
  • ❌ Never commit .env to version control
  • ❌ Never log API keys or sensitive data
  • ❌ Never expose environment variables in error messages

License

MIT License - See LICENSE for details

Support & Contribution

Getting Help

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. Create a Pull Request

Changelog

Version 1.0.0 (December 2025)

  • ✨ Initial release
  • 🎯 AWS Textract integration
  • 🤖 OpenAI GPT-3.5 processing
  • 📄 Multi-format document support
  • 🔐 Environment-based configuration

Technology Stack

┌──────────────────────────────────────┐
│   Right Route OCR Module v1.0        │
├──────────────────────────────────────┤
│                                      │
│  Application Layer                   │
│  ├─ Python 3.8+                      │
│  └─ FastAPI + Uvicorn                │
│                                      │
│  Processing Layer                    │
│  ├─ AWS Textract (OCR)              │
│  ├─ PyMuPDF (PDF handling)          │
│  └─ Pillow (Image processing)       │
│                                      │
│  Intelligence Layer                  │
│  └─ OpenAI GPT models (NLP)         │
│                                      │
│  Infrastructure                      │
│  ├─ Docker / Docker Compose          │
│  ├─ Localhost.run tunnel             │
│  └─ AWS + OpenAI APIs                │
│                                      │
└──────────────────────────────────────┘

Roadmap

  • Batch processing API endpoint
  • Multi-language support
  • Confidence score metrics
  • Result caching layer
  • REST API wrapper
  • Docker containerization
  • Unit test suite
  • Performance optimization

Disclaimer

This module processes documents through external services (AWS, OpenAI). Ensure compliance with:

  • Data protection regulations (GDPR, CCPA)
  • Service terms and conditions
  • Document confidentiality requirements
  • API usage policies

Last Updated: March 2026
Repository: GitHub
Maintained By: SparkTech Agency AI Engineer: Md Fahim Sarker Mridul

About

Here the client’s requirement was: “There will be a OCR module through which truck drivers will upload the Permit document or take image of the US permit document, and the AI will capture only the starting point, ending point, and intermediate route information, then plot these points on the map.”

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages