feat(resume): improve PDF and DOCX extraction

requirements.txt

@@ -1,6 +1,7 @@
 fastapi==0.115.0
 uvicorn==0.30.6
 pdfplumber==0.11.4
+python-docx==1.1.2
 python-multipart==0.0.9
 pydantic==2.8.2
 

routers/extraction.py

@@ -1,6 +1,6 @@
 import io
 from fastapi import APIRouter, HTTPException, File, UploadFile
-from services.pdf_extractor import extract_resume_from_stream
+from services.pdf_extractor import extract_docx_from_stream, extract_resume_from_stream
 
 router = APIRouter(prefix="/extract-resume", tags=["extraction"])
 
@@ -14,7 +14,15 @@ async def extract_resume(file: UploadFile = File(...)):
     try:
         content = await file.read()
         pdf_stream = io.BytesIO(content)
-        result = extract_resume_from_stream(pdf_stream)
+        file_name = (file.filename or '').lower()
+        if file_name.endswith('.docx'):
+            result = extract_docx_from_stream(pdf_stream)
+        elif file_name.endswith('.pdf'):
+            result = extract_resume_from_stream(pdf_stream)
+        else:
+            raise HTTPException(status_code=400, detail='Only PDF and DOCX files are supported.')
         return result
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Extraction failed: {str(e)}")

services/pdf_extractor.py

@@ -23,6 +23,9 @@ def extract_resume_from_stream(stream) -> dict:
     has_tables = False
     has_images = False
     page_count = 0
+    font_names = set()
+    font_sizes = []
+    has_multiple_columns = False
 
     with pdfplumber.open(stream) as pdf:
         page_count = len(pdf.pages)
@@ -36,6 +39,16 @@ def extract_resume_from_stream(stream) -> dict:
             if page.images:
                 has_images = True
 
+            has_multiple_columns = has_multiple_columns or _detect_multiple_columns(page)
+
+            for char in page.chars:
+                font_name = _normalize_font_name(str(char.get("fontname", "")))
+                if font_name:
+                    font_names.add(font_name)
+                size = char.get("size")
+                if isinstance(size, (int, float)) and size > 0:
+                    font_sizes.append(float(size))
+
             page_text = page.extract_text() or ""
             text_pages.append(page_text)
 
@@ -47,6 +60,12 @@ def extract_resume_from_stream(stream) -> dict:
     confidence = round(confidence, 2)
 
     sections = _detect_sections(full_text)
+    non_empty_lines = [line.strip() for line in full_text.splitlines() if line.strip()]
+    long_line_count = sum(len(line) > 120 for line in non_empty_lines)
+    bullet_count = sum(
+        bool(re.match(r"^[\u2022\u25e6\u25aa\u25cf\-\u2013\u2014*]\s+", line))
+        for line in non_empty_lines
+    )
 
     return {
         "text": full_text,
@@ -56,10 +75,116 @@ def extract_resume_from_stream(stream) -> dict:
             "hasImages":  has_images,
             "pageCount":  page_count,
             "confidence": confidence,
+            "hasMultipleColumns": has_multiple_columns,
+            "fontCount": len(font_names),
+            "minFontSize": round(min(font_sizes), 1) if font_sizes else None,
+            "averageFontSize": round(sum(font_sizes) / len(font_sizes), 1) if font_sizes else None,
+            "averageCharsPerPage": round(len(full_text) / max(page_count, 1)),
+            "longLineCount": long_line_count,
+            "bulletCount": bullet_count,
+        },
+    }
+
+
+def extract_docx_from_stream(stream) -> dict:
+    """Extract ordered text and layout signals from a DOCX document."""
+    from docx import Document
+    from docx.oxml.ns import qn
+
+    document = Document(stream)
+    text_lines = []
+    font_names = set()
+    font_sizes = []
+
+    for paragraph in document.paragraphs:
+        text = paragraph.text.strip()
+        if text:
+            text_lines.append(text)
+        for run in paragraph.runs:
+            if run.font.name:
+                font_names.add(_normalize_font_name(run.font.name))
+            if run.font.size:
+                font_sizes.append(float(run.font.size.pt))
+
+    for table in document.tables:
+        for row in table.rows:
+            cells = [cell.text.strip() for cell in row.cells if cell.text.strip()]
+            if cells:
+                text_lines.append(" | ".join(cells))
+
+    full_text = "\n".join(text_lines).strip()
+    estimated_pages = max(1, round(len(full_text) / 3500))
+    has_multiple_columns = False
+    for section in document.sections:
+        columns = section._sectPr.xpath('./w:cols')
+        if columns:
+            count = columns[0].get(qn('w:num'))
+            if count and int(count) > 1:
+                has_multiple_columns = True
+
+    long_line_count = sum(len(line) > 120 for line in text_lines)
+    bullet_count = sum(
+        bool(re.match(r"^[\u2022\u25e6\u25aa\u25cf\-\u2013\u2014*]\s+", line))
+        for line in text_lines
+    )
+    confidence = 1.0 if len(full_text) >= 100 else round(len(full_text) / 100, 2)
+
+    return {
+        "text": full_text,
+        "sections": _detect_sections(full_text),
+        "metadata": {
+            "hasTables": bool(document.tables),
+            "hasImages": bool(document.inline_shapes),
+            "pageCount": estimated_pages,
+            "confidence": confidence,
+            "hasMultipleColumns": has_multiple_columns,
+            "fontCount": len(font_names),
+            "minFontSize": round(min(font_sizes), 1) if font_sizes else None,
+            "averageFontSize": round(sum(font_sizes) / len(font_sizes), 1) if font_sizes else None,
+            "averageCharsPerPage": round(len(full_text) / estimated_pages),
+            "longLineCount": long_line_count,
+            "bulletCount": bullet_count,
         },
     }
 
 
+def _normalize_font_name(font_name: str) -> str:
+    """Collapse embedded font prefixes and style suffixes into a font family."""
+    family = font_name.split("+")[-1].lower()
+    family = re.sub(r"(bold|italic|oblique|regular|medium|light|semibold|mt)", "", family)
+    return re.sub(r"[^a-z0-9]", "", family)
+
+
+def _detect_multiple_columns(page) -> bool:
+    """Detect repeated, independently populated left/right text regions."""
+    words = page.extract_words(use_text_flow=False, keep_blank_chars=False)
+    if len(words) < 20 or not page.width:
+        return False
+
+    rows: dict[int, list[dict]] = {}
+    for word in words:
+        row_key = round(float(word.get("top", 0)) / 5)
+        rows.setdefault(row_key, []).append(word)
+
+    midpoint = float(page.width) / 2
+    split_rows = 0
+    for row_words in rows.values():
+        left = [w for w in row_words if float(w.get("x1", 0)) < midpoint]
+        right = [w for w in row_words if float(w.get("x0", 0)) > midpoint]
+        if not left or not right:
+            continue
+
+        left_text = " ".join(str(w.get("text", "")) for w in left)
+        right_text = " ".join(str(w.get("text", "")) for w in right)
+        gap = min(float(w.get("x0", 0)) for w in right) - max(
+            float(w.get("x1", 0)) for w in left
+        )
+        if len(left_text) >= 8 and len(right_text) >= 8 and gap > float(page.width) * 0.08:
+            split_rows += 1
+
+    return split_rows >= max(4, round(len(rows) * 0.15))
+
+
 def _detect_sections(text: str) -> dict:
     """
     Splits the resume text into named sections by detecting section headers.

tests/__init__.py

@@ -0,0 +1 @@
+

tests/test_pdf_extractor.py

@@ -0,0 +1,73 @@
+import unittest
+import sys
+import io
+from unittest.mock import Mock
+
+# The layout helper tests do not open PDFs, so keep them runnable before the
+# optional service dependencies are installed in a fresh clone.
+sys.modules.setdefault('pdfplumber', Mock())
+
+from services.pdf_extractor import (
+    _detect_multiple_columns,
+    _detect_sections,
+    _normalize_font_name,
+    extract_docx_from_stream,
+)
+
+
+class FakePage:
+    width = 600
+
+    def __init__(self, words):
+        self._words = words
+
+    def extract_words(self, **_kwargs):
+        return self._words
+
+
+class PdfExtractorTests(unittest.TestCase):
+    def test_normalizes_embedded_font_variants(self):
+        self.assertEqual(_normalize_font_name('ABCDEF+Arial-BoldMT'), 'arial')
+
+    def test_detects_repeated_left_and_right_regions(self):
+        words = []
+        for row in range(8):
+            top = row * 20
+            words.extend([
+                {'top': top, 'x0': 30, 'x1': 140, 'text': 'Left column content'},
+                {'top': top, 'x0': 390, 'x1': 550, 'text': 'Right column content'},
+            ])
+        # Ensure the fixture passes the minimum word-count guard.
+        words.extend({'top': 200 + i, 'x0': 30, 'x1': 60, 'text': 'word'} for i in range(5))
+        self.assertTrue(_detect_multiple_columns(FakePage(words)))
+
+    def test_extracts_named_sections(self):
+        sections = _detect_sections('Jane Doe\nSUMMARY\nEngineer\nSKILLS\nPython\nEDUCATION\nBS CS')
+        self.assertEqual(sections['summary'], ['Engineer'])
+        self.assertEqual(sections['skills'], ['Python'])
+        self.assertEqual(sections['education'], ['BS CS'])
+
+    def test_extracts_docx_text_and_layout_metadata(self):
+        from docx import Document
+        from docx.shared import Pt
+
+        document = Document()
+        heading = document.add_paragraph('Jane Doe')
+        heading.runs[0].font.name = 'Arial'
+        heading.runs[0].font.size = Pt(16)
+        document.add_paragraph('SUMMARY')
+        document.add_paragraph('Software engineer building reliable products.')
+        document.add_paragraph('SKILLS')
+        document.add_paragraph('Python, TypeScript')
+        stream = io.BytesIO()
+        document.save(stream)
+        stream.seek(0)
+
+        result = extract_docx_from_stream(stream)
+        self.assertIn('Software engineer', result['text'])
+        self.assertEqual(result['sections']['skills'], ['Python, TypeScript'])
+        self.assertIn('fontCount', result['metadata'])
+
+
+if __name__ == '__main__':
+    unittest.main()