feat(agent): 手持ち PDF 経歴書の構造化抽出エンドポイント（ADR-0024 / #527）

[yusuke0610]

概要

ADR-0024 に従い、手持ち PDF 経歴書を構造化抽出する同期エンドポイント POST /api/agent/resume-import/pdf を追加する（#527 / 3 PR 構成の 2 本目）。テキスト埋め込み PDF を pypdf で抽出 → Claude Haiku で Resume 互換 payload に構造化 → DB 非更新で返す。フォーム注入（#528/#524）の前段まで。

ADR は #526（PR #537・docs のみ）。本 PR は backend のみ・base=main（ADR とは独立）。

変更内容

• 依存: pypdf==6.14.2（純 Python・MIT・native 依存なし。flake.nix 変更不要）を追加、uv lock 再生成
• services/agent/resume_import/（新規）:
  • text_extract.py: pypdf 抽出 + スキャン PDF 判定 + 正規化（決定論・TDD。mutmut only_mutate に追加）
  • output_schema.py: v1 スコープ（full_name / career_summary / self_pr + フラット experiences）の構造化出力スキーマ
  • import_service.py: LLM 1 コール → パース（リトライ 1 回）→ payload（chat/draft と同一の失敗契約）
• prompts/agent_resume_import.md: 抽出プロンプト（転記重視・捏造禁止・読み取れないフィールドは空）
• schemas/agent.py: ResumeImportResponse（フォーム注入用の緩い payload。保存契約とは分離）
• routers/agent.py: エンドポイント（multipart / magic bytes・10MB 上限検証 / 日次レート制限 [Agent 整理 2/4] ユーザ単位レート制限の導入（課金撤去の前提） #521 / DB 非更新）
• エラー契約（旧設計の空文字握りつぶしの再発防止 / ADR-0004→0008→0024）: 非対応 PDF=422 / スキャン PDF=422 / LLM 失敗=502 AGENT_LLM_ERROR / パース失敗=502 AGENT_PARSE_ERROR
• messages.json: import_invalid_pdf / import_scanned_pdf / import_too_large

v1 スコープ（ADR-0024）

抽出は 見出し 3 フィールド + フラット職歴（company / business_description / start_date / end_date / description）。深いネスト（clients/projects/periods/technology_stacks）は v1 では抽出せず、ユーザーがフォームで追記する。

テスト

• text_extract 単体 11 件（TDD: 正規化・十分性判定・PDF 判定・抽出・スキャン検出・破損）
• endpoint 統合 7 件（正常 / 非 PDF / スキャン / LLM 失敗 / パース失敗 / レート制限 / 未認証）
• make ci green（backend lint+typecheck+test / web 323 / build-web）、make codegen-types 再生成済み
• 実 PDF は WeasyPrint で生成（テスト環境のフォントに日本語グリフが無いため抽出検証は ASCII 本文）

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added PDF resume import to extract profile details, career summaries, self-promotion, and work history into the resume form.
  • Added validation for file type, text availability, and a 10MB file-size limit.
  • Added clear error handling for invalid, scanned, oversized, and unreadable PDFs.

• Bug Fixes

  • Added handling for extraction service and parsing failures with appropriate error responses.

• Tests

  • Added coverage for successful imports, validation, authentication, rate limits, and error scenarios.

[coderabbitai]

Warning

Review limit reached

@yusuke0610, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 4 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f8631e5f-8568-44df-b2b0-11fbc7fbfe9a

📥 Commits

Reviewing files that changed from the base of the PR and between 77a9582 and b6184ae.

📒 Files selected for processing (2)

• backend/app/services/agent/resume_import/text_extract.py
• backend/tests/test_resume_import_text_extract.py

📝 Walkthrough

Walkthrough

Adds an authenticated PDF resume import endpoint that validates and extracts embedded text, uses Claude Haiku to produce a structured resume payload, returns explicit validation and upstream errors, and exposes generated frontend API types with backend and integration tests.

Changes

Resume import flow

Layer / File(s)	Summary
Import output contract backend/app/schemas/agent.py, backend/app/services/agent/resume_import/output_schema.py, backend/app/prompts/agent_resume_import.md, backend/app/messages.json	Defines flat resume fields, experience limits, Japanese extraction rules, structured output validation, and PDF import error messages.
PDF text extraction backend/app/services/agent/resume_import/text_extract.py, backend/pyproject.toml, backend/tests/test_resume_import_text_extract.py	Validates PDF headers, extracts and normalizes page text with pypdf, rejects unreadable or scan-like PDFs, and tests these behaviors.
LLM orchestration and API backend/app/services/agent/resume_import/import_service.py, backend/app/routers/agent.py, web/src/api/generated.ts, backend/tests/test_resume_import_api.py	Adds Haiku extraction with one parse retry, usage tracking, authenticated and rate-limited PDF upload handling, error mapping, generated API contracts, and endpoint integration tests.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

• #527 — Directly covers the PDF resume extraction and structured-output endpoint implemented here.
• #526 — Covers the PDF resume import design, text-only extraction, explicit errors, rate limiting, and no-DB form injection flow.
• #524 — Covers the form-injection API payload consumed by this resume import endpoint.

Suggested labels: documentation, feature, backend, test, agent

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PR title clearly and accurately summarizes the main change: a new agent endpoint for structured PDF resume extraction under ADR-0024.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/pdf-import-backend

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

backend/app/schemas/agent.py (1)

171-199: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Resume-import output shape is defined twice (public schema vs. internal validation model) with no single source of truth. ResumeImportExperience/ResumeImportResponse in schemas/agent.py and _ImportExperience/_ImportOutput in import_service.py describe the identical field set, but only the latter carries the max_length constraints (MAX_COMPANY_LENGTH, MAX_DATE_LENGTH, etc.). This means the public OpenAPI schema/generated FE types don't reflect the real length limits, and the two definitions can silently drift on future changes.

• backend/app/schemas/agent.py#L171-L199: keep this as the single public contract; have import_service.py import and reuse these classes (adding the max_length Field(...) constraints here) instead of maintaining a second private copy.
• backend/app/services/agent/resume_import/import_service.py#L55-L73: drop _ImportExperience/_ImportOutput and validate directly against ResumeImportExperience/ResumeImportResponse (imported from schemas.agent) once the length constraints are moved there.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@backend/app/schemas/agent.py` around lines 171 - 199, The resume-import
output models are duplicated and their length constraints are only present in
the internal validation models. In backend/app/schemas/agent.py lines 171-199,
add the existing max-length constraints to ResumeImportExperience and
ResumeImportResponse so they define the complete public contract; in
backend/app/services/agent/resume_import/import_service.py lines 55-73, remove
_ImportExperience and _ImportOutput, import the public models, and validate
directly with ResumeImportExperience/ResumeImportResponse.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/app/services/agent/resume_import/text_extract.py`:
- Around line 73-79: Update the PDF parsing exception handler around PdfReader
and page.extract_text to catch the broader PyPdfError type, while retaining a
narrow fallback for malformed-input parser errors such as KeyError and
RecursionError. Preserve the existing type-only warning and PdfExtractionError
wrapping behavior.

---

Nitpick comments:
In `@backend/app/schemas/agent.py`:
- Around line 171-199: The resume-import output models are duplicated and their
length constraints are only present in the internal validation models. In
backend/app/schemas/agent.py lines 171-199, add the existing max-length
constraints to ResumeImportExperience and ResumeImportResponse so they define
the complete public contract; in
backend/app/services/agent/resume_import/import_service.py lines 55-73, remove
_ImportExperience and _ImportOutput, import the public models, and validate
directly with ResumeImportExperience/ResumeImportResponse.

🪄 Autofix (Beta)

❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9a0a9d0f-ad86-4652-86cc-3a26a59171c0

📥 Commits

Reviewing files that changed from the base of the PR and between 1749be5 and 77a9582.

⛔ Files ignored due to path filters (1)

• backend/uv.lock is excluded by !**/*.lock

📒 Files selected for processing (12)

• backend/app/messages.json
• backend/app/prompts/agent_resume_import.md
• backend/app/routers/agent.py
• backend/app/schemas/agent.py
• backend/app/services/agent/resume_import/__init__.py
• backend/app/services/agent/resume_import/import_service.py
• backend/app/services/agent/resume_import/output_schema.py
• backend/app/services/agent/resume_import/text_extract.py
• backend/pyproject.toml
• backend/tests/test_resume_import_api.py
• backend/tests/test_resume_import_text_extract.py
• web/src/api/generated.ts

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Autofix skipped. No unresolved CodeRabbit review comments with fix instructions found.