Skip to content

About

πŸ‘‰ A production-minded FastAPI backend for validating, uploading, and extracting structured content from PDF, DOCX, TXT, CSV, XLS, and XLSX documents.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

6 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ“„ AI File Analyzer

A production-minded FastAPI backend for uploading, validating, and extracting structured content from multiple document formats.

πŸ“€ Document Upload β€’ πŸ›‘οΈ File Validation β€’ πŸ“‘ Text Extraction β€’ πŸ“Š Structured Metadata β€’ πŸ§ͺ 142 Passing Tests

Python FastAPI PyMuPDF Tests Pydantic


1. πŸ“Œ Introduction

AI File Analyzer is a backend application built with Python and FastAPI that accepts document uploads, validates them, and extracts their readable content into a structured format.

The application supports six document formats: TXT, PDF, DOCX, CSV, XLS, and XLSX.

Each uploaded document passes through a dedicated validation service before being processed by the document extraction service. The extracted result includes normalized content, document metadata, and individual content sections.

The project focuses on building a reliable document-processing foundation with structured responses, sensible resource limits, and predictable error handling.

2. βš™οΈ Core Features & Technologies

Core Features

  • πŸ“€ Document Upload: Upload documents through a REST API.
  • πŸ›‘οΈ File Validation: Validate filenames, extensions, empty files, and upload sizes.
  • πŸ“‘ Multi-format Extraction: Extract content from TXT, PDF, DOCX, CSV, XLS, and XLSX files.
  • πŸ“Š Structured Output: Preserve useful information such as PDF page numbers, DOCX paragraph and table details, CSV rows, and Excel sheet metadata.
  • πŸ”’ Resource Limits: Apply configurable limits to document extraction and processing.
  • ⚠️ Error Handling: Handle invalid documents, malformed files, and extraction failures through predictable API responses.
  • πŸ§ͺ Automated Testing: Unit tests and upload endpoint integration tests.

Technologies Used

Technology Purpose
Python Backend programming language
FastAPI REST API framework
Pydantic Data validation and response schemas
Pydantic Settings Environment-based configuration
PyMuPDF PDF text extraction
python-docx DOCX document extraction
Pandas Tabular data processing
openpyxl XLSX workbook handling
xlrd XLS workbook handling
Pytest Automated testing

3. πŸ—οΈ Project Architecture

backend/
β”‚
β”œβ”€β”€ app/
β”‚   β”œβ”€β”€ api/
β”‚   β”‚   └── routes/
β”‚   β”‚       └── document.py
β”‚   β”‚
β”‚   β”œβ”€β”€ core/
β”‚   β”‚   β”œβ”€β”€ config.py
β”‚   β”‚   └── exceptions.py
β”‚   β”‚
β”‚   β”œβ”€β”€ exceptions/
β”‚   β”‚   └── handlers.py
β”‚   β”‚
β”‚   β”œβ”€β”€ schemas/
β”‚   β”‚   β”œβ”€β”€ document.py
β”‚   β”‚   └── extracted_document.py
β”‚   β”‚
β”‚   β”œβ”€β”€ services/
β”‚   β”‚   β”œβ”€β”€ document_validation_service.py
β”‚   β”‚   └── document_extraction_service.py
β”‚   β”‚
β”‚   └── main.py
β”‚
β”œβ”€β”€ tests/
β”‚   β”œβ”€β”€ unit/
β”‚   └── api/
β”‚
β”œβ”€β”€ .env.example
β”œβ”€β”€ .gitignore
β”œβ”€β”€ requirements.txt
└── README.md

Main Processing Flow

        Client
          β”‚
          β–Ό
    Upload Endpoint
          β”‚
          β–Ό
  Document Validation
       Service
          β”‚
          β–Ό
    Read File Bytes
          β”‚
          β–Ό
  Document Extraction
       Service
          β”‚
          β–Ό
   Extracted Document
          β”‚
          β–Ό
    Structured JSON
       Response

4. πŸš€ Getting Started

Follow these steps to clone, configure, run, and test the application locally.

Step 1. Clone the Repository

git clone <repository-url>

Navigate into the backend directory:

cd <repository-folder>/backend

Step 2. Create a Virtual Environment

python -m venv .venv

Activate it:

Linux / macOS:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

Step 3. Install Dependencies

python -m pip install --upgrade pip
pip install -r requirements.txt

Step 4. Configure Environment Variables

Create your local environment file:

cp .env.example .env

Open .env and configure the application settings as required.

Step 5. Start the Application

From the backend directory, run:

uvicorn app.main:app --reload

The application will start locally at:

http://127.0.0.1:8000

Step 6. Open Swagger Documentation

Navigate to:

http://127.0.0.1:8000/docs

Swagger UI provides an interactive interface for testing the available API endpoints.

Step 7. Upload a Document

  1. Open the /documents/upload endpoint.
  2. Click Try it out.
  3. Select a supported document.
  4. Click Execute.
  5. Inspect the response containing the extracted content, sections, and metadata.

You can also check the application health using:

http://127.0.0.1:8000/health

Step 8. Run the Tests

From the backend directory:

pytest -q

The current test suite contains 142 passing tests.

5. πŸ’‘ Final Note

AI File Analyzer is built around a simple principle: reliable AI applications begin with reliable data processing.

Clean inputs. Structured extraction. Predictable outputs.

About

πŸ‘‰ A production-minded FastAPI backend for validating, uploading, and extracting structured content from PDF, DOCX, TXT, CSV, XLS, and XLSX documents.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages