Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
This page provides detailed technical instructions and architectural overviews for installing and setting up the Rosy Tax Processor. The system is an AI-powered prototype designed to automate tax document processing, featuring a Flask backend, a vanilla JavaScript frontend, and a modular processing pipeline for document classification, extraction, and tax calculation.
Sources: README.md:1-5, SETUP.md:1-5
System Prerequisites
Before installation, the environment must meet specific software requirements to ensure the execution of the Python-based backend and the associated AI models.
Core Requirements
- Python 3.12+: The primary runtime environment for the application.
- Git: Required for repository cloning and version control.
- Internet Access: Required during the first run to download AI models (approximately 500MB).
Sources: SETUP.md:8-11, SETUP.md:65-67
Dependency Overview
The project relies on several core and optional libraries managed via pip.
| Dependency | Purpose | Requirement Level |
|---|---|---|
flask | API Server and web routing | Mandatory |
pytest | Test suite execution | Recommended |
reportlab | PDF generation for draft 1040s | Mandatory |
pdfrw | PDF form manipulation and filling | Mandatory |
sentence-transformers | Semantic similarity for field mapping | Mandatory (AI features) |
pytesseract / Pillow | OCR capabilities for image files | Optional |
PyMuPDF / pdfminer.six | PDF text extraction | Mandatory (PDF parsing) |
Sources: requirements.txt:1-15, README.md:112-118
Installation Procedure
The installation involves cloning the source code and configuring the Python virtual environment with necessary dependencies.
# Step 1: Clone the repository
git clone https://github.com/sabs-27/Tax-Processor.git
cd Tax-Processor
# Step 2: Install dependencies
pip install -r requirements.txt
# Step 3: Verify installation
python -m pytest
Sources: SETUP.md:14-20, README.md:61-69
OCR Setup (Optional)
If processing images (PNG, JPG) is required, Tesseract OCR must be installed on the host system. If Tesseract is unavailable, the system defaults to processing digital PDF and text files which do not require OCR.
Sources: SETUP.md:33-36, SETUP.md:52-57
Architecture and Execution Flow
The Rosy Tax Processor follows a client-server architecture. The backend is powered by Flask, which orchestrates the data flow between the user interface and the processing pipeline.
Application Startup
The server is initiated via backend.py, which by default listens on http://localhost:5000.
The diagram shows the standard startup sequence and the workaround for port conflicts.
Sources: SETUP.md:23-26, SETUP.md:38-42, backend.py:15-18
Initialization Sequence
Upon the first execution, the system performs a one-time model initialization.
The sequence diagram illustrates the initial heavy load of AI models during the first run.
Sources: SETUP.md:65-67, pipeline.py:10-15, backend.py:125-126
Configuration and Deployment
Environment Configuration
The application is designed for local processing to ensure data privacy. Key security configurations include:
- MAX_UPLOAD_BYTES: Limits file upload size to prevent resource exhaustion.
- Temporary Storage: Files are stored in temporary directories with
rosy_upload_orrosy_final_prefixes and are cleaned up after processing. - PII Masking: SSNs and other sensitive data are masked in API responses.
Sources: backend.py:65-72, backend.py:91-96, SETUP.md:70-73
Docker Deployment
For containerized environments, a Dockerfile is provided to standardize the setup.
# Build the Docker image
docker build -t rosy-tax-processor .
# Run the container
docker run -p 5000:5000 rosy-tax-processor
Sources: README.md:131-137
Validation of Setup
To ensure the installation was successful, the project includes a comprehensive test suite. Users can run python -m pytest to execute 14 integration and unit tests covering parsing, tax calculation, and security features.
Test Categories
| Test File | Focus Area |
|---|---|
test_pipeline.py | Core document parsing and orchestration |
test_taxcalc.py | Accuracy of federal tax logic |
test_backend.py | API endpoint availability and response formats |
test_security.py | Sanitization and PII masking |
Sources: README.md:81-94, README_old.md:15-20
Conclusion
Setting up the Rosy Tax Processor requires a Python 3.12 environment and a specific set of dependencies for PDF manipulation and AI-driven mapping. While the initial setup involves a significant model download, subsequent runs are optimized for speed, performing local processing for enhanced data security.
Sources: SETUP.md:65-75, README.md:143-150