hemant-1010/automated-invoice-data-extractor

1. This repository is a single-process Python batch pipeline, centered on invoice_extractor.py. There is no web server, database, or background worker architecture; the whole system runs locally from the command line and processes invoice PDFs one by one.

2. The input boundary is the invoices/ folder. The script expects PDF files there, reads them from disk, and treats each PDF as one extraction unit. The sample PDFs at the repo root (1.pdf, 2.pdf, 3.pdf) appear to be test artifacts or examples, but the documented workflow is folder-based.

3. The first subsystem is PDF text acquisition. It uses pdfplumber to open each invoice and extract text across pages. This is the lowest-level dependency in the pipeline and is important because everything downstream depends on whether the PDF contains machine-readable text rather than scanned images.

4. The second subsystem is text normalization. After extraction, the raw text is cleaned by removing empty lines and extra whitespace. This preprocessing step creates a more stable input for the language model and reduces noise from multi-page invoice formatting.

5. The third subsystem is prompt construction. The script builds a tightly scoped extraction prompt that defines the 13 required invoice fields, date formatting rules, and null-handling behavior. This prompt is the main control boundary between unstructured document text and structured output.

6. The fourth subsystem is the OpenAI integration. The pipeline calls the OpenAI API using gpt-4o-mini with temperature=0, making the extraction deterministic and reducing hallucinated values. The model is used strictly as a structured information extractor, not as a conversational assistant.

7. The fifth subsystem is response parsing and validation. The model output is expected to be JSON, and the script parses it with json.loads(). The repository explicitly anticipates malformed responses, such as markdown code fences or non-JSON text, so parsing is a critical failure point in the architecture.

8. The sixth subsystem is presentation and persistence. Extracted data is printed in a human-readable console format and also written to JSON files in an outputs/ directory. That output folder is generated as part of the pipeline and serves as the final artifact boundary for downstream use.

9. Operationally, the system is driven by environment configuration. The OpenAI API key is loaded from a .env file using python-dotenv, keeping credentials out of source code. This is the only meaningful external secret management concern in the repo.

10. The dependency stack is intentionally small: pdfplumber for PDF parsing, openai for LLM access, and python-dotenv for configuration loading. The repository’s architecture is therefore a thin orchestration layer around these libraries rather than a multi-service application.

11. Error handling is part of the pipeline boundary design. The README describes graceful handling for missing files, API failures, and JSON parsing issues, which means the script is expected to continue or fail cleanly at each stage instead of crashing silently.

12. From an architecture-diagram perspective, the data flow is linear: local PDF files in invoices/ → text extraction and cleanup → prompt assembly → OpenAI model call → JSON parsing → console display and outputs/ JSON files. The only external network dependency is the OpenAI API; everything else is local filesystem and Python runtime.