Sweepy 開発者リファレンス
Sweepy は、平坦な構成のエンジンを持つ小さな Python プロジェクトとして動作します。このページは各パイプライン段階を実行するモジュールに対応づけるため、どこを変更すべきかが分かります。
対象読者
Sweepy のコードを変更する場合や、求人ソースを追加する場合にこのページを読んでください。レビュー担当者はプルリクエストの全体像をつかむのに使えます。扱うのは内部の構造だけです。モジュール、依存パッケージ、Python のバージョンです。
ヒント
スイープを実行したいだけなら、このページは飛ばしてください。インストールから始めてください。
パイプラインの段階とモジュール
swee.py は 5 つの段階を順に実行します。ターミナルは各段階を [1/5] から [5/5] として表示します。
| 段階 | モジュール | 動作 |
|---|---|---|
| 1. プロファイルの読み込み | engine/config.py | YAML プロファイルを読み込んで検証します。同じモジュールのウィザードがプロファイルを書き出します。 |
| 2. 求人の検出 | engine/discovery.py | python-jobspy 経由でアグリゲーターフィードに問い合わせ、各プラットフォームを分類します。 |
| 2. 求人の検出 | engine/sources/ | 公開エンドポイントから Greenhouse、Ashby、Lever、Workable、Built In NYC のサイトを取得します。 |
| 2. 重複の排除 | swee.py | アグリゲーターとソースの結果を、求人リンクごとに 1 枚のカードに統合します。 |
| 3. URL の検証 | engine/validator.py | HTTP の HEAD リクエストと GET の代替で各リンクを確認します。無効な求人を除外します。 |
| 4. 履歴書との照合採点 | engine/scorer.py | 求人と履歴書の用語を抽出し、要件とキーワードの重複を採点します。記述回答を求める求人に印を付けます。 |
| 5. 履歴書トラックの振り分け | engine/enrich.py | 用語の重複が最も多いトラックを選び、対応するバッジの色を割り当てます。 |
| 5. カードの強化 | engine/enrich.py | カードの要約、給与の行、調整済みのヒント文を作ります。 |
| 5. 既定のカード PDF | engine/report.py | カードのレイアウトを描画します。既定では 1 ページ 6 枚で、ページ数を返します。 |
| 5. 従来の表形式 PDF | engine/pdf_builder.py | プロファイルが report.style: legacy のときに表のレイアウトを描画します。 |
| 5. データのエクスポート | engine/exporter.py | CSV と JSON ファイルを書き出します。要求に応じて PNG のページ画像を生成します。 |
| 5. 求人管理 | engine/tracking.py | 管理用の列を追加し、以前のエクスポートを読んで入力した値を引き継ぎます。 |
engine/session.py は、状態を持つ Model Context Protocol（MCP）の流れに向けたカードストアを保持します。カードは、各求人リンクの安定したハッシュをキーにしたスレッドセーフなマップに保たれます。
変更する場所
| 変更したいもの | 着手する場所 |
|---|---|
| 求人ソースやそのエンドポイント | engine/sources/、および data/sources/ のシードリスト |
| マッチの採点方法 | engine/scorer.py |
| カードに表示する内容 | engine/enrich.py、続いて engine/report.py |
| リンクの確認方法 | engine/validator.py |
| コマンドラインのフラグ | swee.py |
| MCP ツール | server.py |
ヒント
server.py はコマンドラインツールと同じエンジンのモジュールを import します。エンジンを変更した後は MCP の経路もテストしてください。1 つの修正が両方のエントリポイントに影響します。
モジュールリファレンス
エントリポイント
| モジュール | 目的 |
|---|---|
swee.py | 5 段階のパイプラインの主要なオーケストレーターであり、argparse のコマンドラインエントリポイントです。 |
server.py | エンジンのツールを AI アシスタントに公開する Model Context Protocol（stdio）サーバーです。 |
エンジンのモジュール
| モジュール | 目的 |
|---|---|
engine/config.py | 対話形式のウィザードと、YAML の読み込みおよび検証です。 |
engine/discovery.py | python-jobspy と決定的なソースの取得処理の統括、応募者追跡システム（ATS）の判定、重複の排除です。 |
engine/validator.py | ソフト 404 の検出を伴うリンクの稼働確認です。検証できないリンクは実行に残ります。 |
engine/scorer.py | 履歴書の用語抽出、割合の照合、印付け、トラックごとの採点です。 |
engine/enrich.py | 要約、給与、トラックの振り分け、調整済みのヒントのためのカード強化です。 |
engine/session.py | 状態を持つ MCP の流れに向けた、安定した ID を持つスレッドセーフなカードストアです。 |
engine/report.py | 既定のカードレイアウトの PDF です。 |
engine/pdf_builder.py | report.style: legacy 用の従来の表レイアウトの PDF です。 |
engine/exporter.py | CSV と JSON のエクスポート、およびレポート PDF の PNG 化です。 |
engine/tracking.py | 管理用の列と、以前のエクスポートの読み取りによる引き継ぎです。 |
engine/docx.py | python-docx と reportlab による DOCX から PDF への変換、および Microsoft Word への切り替えです。 |
engine/documents.py | --convert と MCP の変換処理の振り分けです。DOCX、DOC、テキスト、Markdown、PDF を扱います。 |
engine/logging.py | logs/ 配下の任意で有効にするデバッグログです。 |
engine/cache.py | クエリとエンジンの組をキーにした SQLite の取得キャッシュで、有効期間は 1 時間です。 |
engine/circuit_breaker.py | ソースの連続エラーを数え、クールダウンの間は呼び出しを止めます。 |
engine/engine_defaults.py | 共有の既定サイトリストとエンジン設定です。循環を避けるため import を持ちません。 |
engine/engines.py | 任意の hirehunt、openroles、apify、jobdrop エンジンのアダプター登録とインストーラーです。 |
engine/history.py | 報告済みの求人の永続的な記録です。日次のスイープは新しい求人だけを報告します。 |
engine/normalize.py | エンジンの生の行を共有の求人列に正規化します。 |
engine/salary.py | サイトが構造化された給与を省略したときに、求人本文から給与を抽出します。 |
engine/sweep_config.py | 共有のエンジン既定値をプロファイル設定に適用します。 |
engine/updater.py | チェックアウト向けの、Git ベースの更新確認と依存パッケージの再インストールです。 |
決定的なソース
| モジュール | 目的 |
|---|---|
engine/sources/__init__.py | フェッチャーの公開と、data/sources/ からのシードリストの読み込みです。 |
engine/sources/_common.py | HTTP ヘッダー、職種名の事前フィルター、HTML からテキストへの変換の共通ヘルパーです。 |
engine/sources/greenhouse.py | Greenhouse の求人サイトのフェッチャーです。 |
engine/sources/ashby.py | Ashby の求人サイトのフェッチャーです。 |
engine/sources/lever.py | Lever の求人のフェッチャーです。 |
engine/sources/workable.py | Workable のウィジェット API のフェッチャーです。 |
engine/sources/builtinnyc.py | Built In NYC のカテゴリの取得処理です。 |
エンジンのアダプター
| モジュール | 目的 |
|---|---|
engine/adapters/__init__.py | 各エンジン名をアダプターに対応づけるレジストリです。 |
engine/adapters/base.py | ScraperAdapter の基底クラス、共有の User-Agent ヘッダー、結果の形を扱うヘルパーです。 |
engine/adapters/jobspy_adapter.py | LinkedIn、Indeed、Glassdoor、ZipRecruiter 向けの python-jobspy アグリゲーターのアダプターです。 |
engine/adapters/ats_adapter.py | engine/sources/ の決定的な ATS フェッチャーを包むアダプターです。 |
engine/adapters/hirehunt_adapter.py | 任意の hirehunt エンジンのアダプターです。 |
engine/adapters/openroles_adapter.py | 任意の openroles エンジンのアダプターです。 |
engine/adapters/apify_adapter.py | 任意の Apify アクターのアダプターです。 |
engine/adapters/jobdrop_adapter.py | 任意の jobdrop エンジンのアダプターです。 |
データ、スクリプト、テスト
| パス | 目的 |
|---|---|
data/sources/*.txt | サイト、企業、組織、カテゴリのシードリストです。 |
scripts/make_sample.py | docs/ に保存するサンプルレポートのビルダーです。 |
tests/ | 領域ごとにファイルを分けた pytest スイートです。adapters、config、documents、docx、engines、enrich、history、logging、report があります。さらに salary、scorer、server、session、sources、swee、tracking、updater、validator のファイルがあります。 |
注記
discovery.py、exporter.py、pdf_builder.py を変更したときは、専用のテストファイルを追加してください。ファイルは tests/ に置きます。
依存パッケージ
実行時のパッケージは requirements.txt から取得します。次のバージョンはそのファイルと一致します。
| パッケージ | バージョン | Sweepy での役割 |
|---|---|---|
reportlab | 5.0.1 | クリックできるリンク付きの整形された PDF レポートを組み立てます。 |
pymupdf | 1.28.2 | 履歴書 PDF からテキストを抽出し、PNG のエクスポートを画像化します。 |
python-docx | 1.2.0 | .docx の履歴書を読み取り、Word なしで DOCX のテキストを PDF として組み直します。 |
requests | 2.32.5 | ATS のエンドポイントに到達し、各求人リンクが応答するかを確認します。 |
beautifulsoup4 | 4.15.0 | Greenhouse、Lever、Workable、Built In NYC の各ソースから HTML を解析します。 |
pyyaml | 6.0.3 | YAML プロファイルを読み書きします。 |
questionary | 2.1.1 | 対話形式のウィザードの質問を動かします。 |
prompt-toolkit | 3.0.53 | ウィザードの対話形式のテキスト入力を動かします。 |
python-jobspy | 1.2.0 | API の認証情報なしで LinkedIn、Indeed、Glassdoor、ZipRecruiter からデータを取得します。 |
pandas | 2.2.3 | 求人を構造化し、CSV と JSON のエクスポートを組み立てます。 |
mcp | 1.30.0 | Model Context Protocol サーバーを実行します。 |
anyio | 4.12.1 | 非同期の MCP トランスポートを実行します。 |
requirements.txt には任意のパッケージも 1 つ載っています。Word で PDF を組み立てたいときに docx2pdf のコメントを外します。
docx2pdf（0.5.2、任意）は、Windows で Microsoft Word 経由で DOCX を PDF に描画します。Sweepy は、マシンに Microsoft Word があるときは常にこれを呼び出します。
注記
mcp は意図的に 1.x に据え置いています。2.x の SDK は 2026-07-28 のプロトコル世代だけを扱います。server/discover を試してから initialize ハンドシェイクに切り替えるクライアントは -32022 エラーを受け取ります。VS Code Copilot はその切り替えの経路をたどります。
ヒント
pandas は意図的に 2.x に据え置いています。Pandas 3.x は Python 3.11 以上を必要としますが、CI の組み合わせは Python 3.10 もテストします。
開発用パッケージ（requirements-dev.txt）
| パッケージ | バージョン | 動作 |
|---|---|---|
pytest | 9.1.1 | tests/ のテストスイートを実行します。 |
pytest-cov | 7.1.0 | swee.py、server.py、engine/scorer.py のカバレッジを報告します。 |
ruff | 0.17.0 | コードを静的解析し、import を整えます。 |
tomli | 2.2.1 | Python 3.10 のテスト実行に tomllib を提供します。 |
ターミナル
pip install -r requirements.txt
pip install -r requirements-dev.txt
ruff check .
pytest -q
必要な環境と対応する Python のバージョン
| 項目 | 詳細 |
|---|---|
| Python の下限 | Sweepy は Python 3.10 以上を必要とし、すべてのモジュールで 3.10 の構文を対象にします。 |
| テスト対象の範囲 | .github/workflows/ci.yml の CI ワークフローは、Ubuntu 上で Python 3.10、3.11、3.12 を実行します。 |
| 静的解析の対象 | pyproject.toml は ruff の target-version = "py310" を設定します。新しい版だけの構文は静的解析のジョブを失敗させます。 |
| 行の長さ | Ruff は 100 文字の行長制限を適用し、E501 は無視します。 |
| CI の手順 | ジョブは両方の requirements ファイルをインストールし、pytest の前に ruff check . を実行します。 |
注記
pyproject.toml は requires-python = ">=3.10" を宣言しているため、pip はインストール時に古いインタープリターを拒否します。テスト対象の範囲を定めるのは CI の組み合わせと ruff の対象です。Python 3.13 は実際には動作しますが、その範囲の外です。
Python 3.13
ビルド済みの wheel がない場合、pymupdf パッケージはソースからコンパイルされることがあります。依存パッケージをインストールする前に、Microsoft C++ Build Tools をインストールし、"Desktop development with C++" ワークロードを選んでください。
リポジトリの構成
リポジトリ構成
swee.py CLI エントリポイントとスイープのオーケストレーター
server.py stdio 経由の MCP サーバー
engine/ パイプラインモジュール
engine/sources/ 決定的な ATS 取得処理
engine/adapters/ アグリゲーターと任意エンジンのアダプター
data/sources/ 各取得処理のシードリスト
profiles/ YAML 検索プロファイル
results/ 生成された PDF、CSV、JSON、PNG ファイル
logs/ 任意で有効にするデバッグログ
styles/ ドキュメント用の Vale スタイルルール
tests/ pytest スイート
server.py のツールのシグネチャを変更したときは、同じコミットで MCP ツールリファレンスも更新してください。