Python API

Python から利用する場合は、chilmai.generic.service.MatchingService を入口にします。このクラスは、ファイル読込、列名マッピング、バリデーション、マッチング、結果整形をまとめて実行します。

パッケージの導入と、リポジトリ同梱のサンプルデータで動かす手順は インストールと実行 を参照してください。

最小例

申込者データと保育所データのファイル内容をバイト列で渡し、マッチングを実行します。入力ファイルの形式は 入力データと設定 を参照してください。

from pathlib import Path

from chilmai.generic.config import DEFAULT_CONFIG
from chilmai.generic.service import MatchingService

service = MatchingService()
result = service.match(
    children_file_bytes=Path("申込者データ.csv").read_bytes(),
    children_file_format="csv",
    daycares_file_bytes=Path("保育所データ.csv").read_bytes(),
    daycares_file_format="csv",
    mapping=DEFAULT_CONFIG,
    solver_config={"max_time_seconds": 10},
)

きょうだい児童の入所パターンを細かく指定する組み合わせファイル（任意、入力データと設定を参照）を使う場合は、combination_file_bytes と combination_file_format も指定します。

戻り値

match() は、マッチング結果、施設名辞書、成立件数の集計、Excel 出力用の列・行データを含む辞書を返します。HTTP API や Web UI も、このコア処理を利用しています。

バリデーションだけを実行する

入力データに問題がないかを事前に確認する場合は、validate() を呼び出します。引数は match() から solver_config を除いたものと同じです。

validation = service.validate(
    children_file_bytes=Path("申込者データ.csv").read_bytes(),
    children_file_format="csv",
    daycares_file_bytes=Path("保育所データ.csv").read_bytes(),
    daycares_file_format="csv",
    mapping=DEFAULT_CONFIG,
)

戻り値の is_valid が False の場合、errors にバリデーションエラーが入ります。あわせて warnings（警告一覧）と summary（読み込んだ申込者・保育所の件数）も返されます。

主要モジュール

モジュール	役割
chilmai.generic.parser	CSV、Excel の読込と内部列名への変換
chilmai.generic.validator	必須列、ID、年齢、希望施設、募集人数などのバリデーション
chilmai.generic.config	列名マッピングとプロファイル管理
chilmai.generic.column_mapper	入力列名からのマッピング候補のサジェスト
chilmai.generic.service	高レベル API
chilmai.generic.matcher	CP-SAT マッチングの実行
chilmai.generic.preprocessor	自治体ごとの前処理拡張

API リファレンス

chilmai.generic.service.MatchingService

パース、検証、マッチング、結果整形をまとめて扱う。

FastAPI の HTTP レイヤーを経由せずに ChilmAI を実行したいアプリケーション向けの 推奨 Python API エントリポイント::

from chilmai.generic.config import DEFAULT_CONFIG
from chilmai.generic.service import MatchingService

service = MatchingService()
result = service.match(
    children_file_bytes=children_bytes,
    children_file_format="csv",
    daycares_file_bytes=daycares_bytes,
    daycares_file_format="csv",
    mapping=DEFAULT_CONFIG,
)

Parameters:

Name	Type	Description	Default
preprocessor	BasePreprocessor | None	自治体カスタム前処理。None の場合はすべてパススルーの BasePreprocessor を使う。前処理が呼ばれる順序は BasePreprocessor を参照。	None

validate(*, children_file_bytes, children_file_format, daycares_file_bytes, daycares_file_format, mapping, combination_file_bytes=None, combination_file_format=None)

アップロードされた申込者ファイルと保育所ファイルを検証する。

マッチングは実行せず、パース → 自治体カスタムバリデーション → ChilmAI 汎用バリデーションまでを行う。公開 /validate HTTP エンドポイントと 同じ構造を返す。すべてキーワード引数で渡す。

Parameters:

Name	Type	Description	Default
children_file_bytes	bytes	申込者ファイルの内容。	required
children_file_format	str	申込者ファイルの形式。"csv" または "xlsx"。	required
daycares_file_bytes	bytes	保育所ファイルの内容。	required
daycares_file_format	str	保育所ファイルの形式。"csv" または "xlsx"。	required
mapping	dict[str, dict[str, str]]	列名マッピング。"children"・"daycares"・"combination"・ "output" をキーに、{内部列名: 元ファイルの列名} の dict を持つ。 既定値は chilmai.generic.config.DEFAULT_CONFIG。	required
combination_file_bytes	bytes | None	組み合わせファイルの内容。任意。	None
combination_file_format	str | None	組み合わせファイルの形式。任意。 combination_file_bytes と両方指定したときのみ組み合わせを検証する。	None

Returns:

Type	Description
dict[str, Any]	以下のキーを持つ dict:
dict[str, Any]	is_valid（bool）: エラーがなければ True。
dict[str, Any]	errors（list[dict]）: エラーのリスト。各要素は {"message": str, "type": str, "code": int | None}。
dict[str, Any]	warnings（list[str]）: 警告メッセージのリスト。
dict[str, Any]	summary（dict）: children_count・daycares_count の件数集計。
dict[str, Any]	自治体カスタムバリデーションまたは組み合わせファイルの検証で
dict[str, Any]	エラーが出た場合は、その時点で is_valid=False を返し、
dict[str, Any]	ChilmAI 汎用バリデーションは実行しない。

Raises:

Type	Description
ChilmError	ファイルのパースに失敗した場合（形式不正、必要な列がないなど）。

match(*, children_file_bytes, children_file_format, daycares_file_bytes, daycares_file_format, mapping, solver_config=None, combination_file_bytes=None, combination_file_format=None)

アップロードされたファイルを検証し、CP-SAT マッチングを実行する。

公開 /match HTTP エンドポイントと同じ中核結果に加え、 Web UI の Excel 出力で使う出力列・行データを返す。すべてキーワード引数で渡す。

Parameters:

Name	Type	Description	Default
children_file_bytes	bytes	申込者ファイルの内容。	required
children_file_format	str	申込者ファイルの形式。"csv" または "xlsx"。	required
daycares_file_bytes	bytes	保育所ファイルの内容。	required
daycares_file_format	str	保育所ファイルの形式。"csv" または "xlsx"。	required
mapping	dict[str, dict[str, str]]	列名マッピング。"children"・"daycares"・"combination"・ "output" をキーに、{内部列名: 元ファイルの列名} の dict を持つ。 既定値は chilmai.generic.config.DEFAULT_CONFIG。	required
solver_config	dict[str, Any] | None	ソルバー設定。max_time_seconds（float、既定 10.0）で CP-SAT の打ち切り時間を指定する。省略時は既定値を使う。	None
combination_file_bytes	bytes | None	組み合わせファイルの内容。任意。	None
combination_file_format	str | None	組み合わせファイルの形式。任意。 combination_file_bytes と両方指定したときのみ組み合わせを使う。	None

Returns:

Type	Description
dict[str, Any]	以下のキーを持つ dict:
dict[str, Any]	matching_result_dict（dict[str, str | None]）: 申込者 ID → 内定した 保育所 ID。不成立の申込者は None。
dict[str, Any]	household_result_dict（dict）: 世帯 ID → その世帯の child_ids・assigned・selected_combo など。
dict[str, Any]	daycare_name_dict（dict[str, str]）: 保育所 ID → 保育所名。
dict[str, Any]	matched_children（dict）: 成立件数の集計。total・only_child・ siblings・applied_total・by_age（年齢別の内訳）。
dict[str, Any]	transfer_back_count（int）: 在籍中の保育所に再度内定した件数。 該当がある場合のみ含まれる。 mapping["output"]["exclude_transfer_back"] == "true" のときは 該当申込者の結果を空欄に落とし、matched_children からも差し引く。
dict[str, Any]	meta（dict）: algorithm・is_optimal などの実行情報。
dict[str, Any]	output_columns（list[str]）: 出力ファイルの列名リスト （元の申込ファイル全列 + 結果列）。
dict[str, Any]	output_rows（list[dict]）: 出力ファイルの行データ。 BasePreprocessor.transform_output の加工後の内容。

Raises:

Type	Description
ValueError	バリデーションエラーで中断した場合。第 2 引数に validate() と同じ構造の dict（is_valid・errors・ warnings・summary）が入る。
ChilmError	ファイルのパースに失敗した場合、申込者ファイルに 申請者 ID 列が見つからない場合、出力列名の設定が重複している場合、 出力列名が申込者ファイルの既存列と衝突する場合。

chilmai.generic.preprocessor.BasePreprocessor

自治体カスタム前処理の基底クラス。デフォルト実装はすべてパススルー。

MatchingService のコンストラクタに渡すことで前処理を有効にする::

from chilmai.generic import MatchingService
from mytown.preprocessor import MyTownPreprocessor

service = MatchingService(preprocessor=MyTownPreprocessor())
result = service.match(...)

パイプラインの順序:

1. parse — ファイル読込・列名マッピング
2. validate — 自治体固有バリデーション（ここでエラーがあれば以降はスキップ）
3. transform_children / transform_daycares — score_1〜N・sibling_pattern の計算
4. ValidationService.validate — ChilmAI 汎用バリデーション
5. matcher.match — マッチング実行
6. transform_output — 出力 DataFrame の列・行を加工

validate(children_df, daycares_df)

自治体固有の入力規則チェック。

列名マッピング適用後の DataFrame を受け取る。元ファイルの全列が残っている ため、自治体独自の列（指数合計、優先順位 N など）にアクセスできる。

Parameters:

Name	Type	Description	Default
children_df	DataFrame	申込者データ（列名マッピング適用済み）。	required
daycares_df	DataFrame	保育所データ（列名マッピング適用済み）。	required

Returns:

Type	Description
list[dict[str, Any]]	エラーがなければ空リスト。エラーがある場合は以下の形式の dict のリスト:: {"message": "エラー内容", "type": "data"|"config", "code": int|None}
list[dict[str, Any]]	形式は ValidationService のエラーと同じ。

transform_children(df)

申込者データを変換し、スコア列と sibling_pattern 列を追加する。

validate でエラーがなかった場合のみ呼ばれる。 元 DataFrame を変更せず、コピーを返すことを推奨する。

score_N はタイブレーカーまで含んだ完全な優先順位スコアでなければならない。 基礎点が同じ申込者が複数いる場合に同値だとマッチング内での優先順位が不定になる。 希望施設ごとの点数列が基礎点のみを表す場合は共通タイブレーク列と組み合わせて 一意なスコアを生成すること （examples/sample_preprocessor.py の PerPreferenceScorePreprocessor 参照）。

Parameters:

Name	Type	Description	Default
df	DataFrame	申込者データ（列名マッピング適用済み）。	required

Returns:

Type	Description
DataFrame	以下の列を追加した DataFrame:
DataFrame	score_1（整数）: 全保育所共通のベーススコア。score_N が存在しない 希望施設への点数として使われる。全施設で同じ点数ルールの場合は この列だけ返せばよい。
DataFrame	score_2, score_3, ...（整数・任意）: 第 N 希望施設への個別スコア。 元データに希望施設ごとの点数列がある場合（例: 第1希望は50点・ 兄弟在籍の第2希望は55点など）に設定する。pref_N 列に対応する 施設に適用され、score_N がない希望は score_1 にフォールバックする。
DataFrame	sibling_pattern（"1"〜"7" または空文字）: きょうだいパターン番号。

transform_daycares(df)

保育所データを変換する。通常は実装不要。

Parameters:

Name	Type	Description	Default
df	DataFrame	保育所データ（列名マッピング適用済み）。	required

Returns:

Type	Description
DataFrame	変換後の保育所 DataFrame。

transform_output(df, result)

出力ファイルの列・行を加工する。通常は実装不要。

マッチング結果列（入所選考結果保育所ID・名）が追加された後に呼ばれる。 列の並べ替え・追加・削除が可能。元 DataFrame を変更せず、コピーを返すことを推奨する。

Parameters:

Name	Type	Description	Default
df	DataFrame	出力 DataFrame（元の申込ファイル全列 + 結果列）。	required
result	dict[str, Any]	マッチング結果 dict。matching_result_dict・daycare_name_dict など MatchingService.match() が返すキーを含む。ただし output_columns・ output_rows はこのフック呼び出し後にセットされるため、まだ含まれない。	required

Returns:

Type	Description
DataFrame	加工後の出力 DataFrame。

rank_by(df, rules) staticmethod

複数列のソートルールから整数ランクを計算する。

transform_children 内で score_1 や score_N を計算する際に使う。 戻り値の整数は「高いほど優先度が高い」ため、そのままスコア列に代入できる。

Parameters:

Name	Type	Description	Default
df	DataFrame	申込者 DataFrame。	required
rules	list[tuple[str, str]]	ソートルールのリスト。各要素は (列名, "asc"|"desc") のタプル。 例: [("指数合計", "desc"), ("優先順位2", "asc")] 空リストを渡すと入力順のまま n, n-1, ..., 1 を返す。	required

Returns:

Type	Description
Series	df と同じインデックスを持つ pd.Series[int]。
Series	値は 1〜len(df) の整数で、高いほど優先度が高い。
Series	NaN 値は最低優先（リスト末尾）として扱われる。
Series	全キーが同値の行は入力順を維持する（安定ソート）。

Raises:

Type	Description
ValueError	direction が "asc" でも "desc" でもない場合。