Fjc Case Outcomes

@pipeworx/fjc-case-outcomes

連邦裁判所の事件件数と事件結果に関する統計 — フリート #3271。court-listener パックを補完します。court-listener は個別の訴訟記録や判決文を検索して読み取りますが、このパックは court-listener にはない集計統計に関する質問（「FY2023 に SDNY で民権訴訟は何件提起され、どのような結果で終結したか」など）に回答し、訴訟記録と地区を直接指定した結果照会にも対応します。

Pipeworx の一部です。AI エージェントを 1879 以上の稼働中データソースに接続する MCP ゲートウェイです。これは独立した非公式の統合であり、上流プロバイダーとは提携、推奨、公開のいずれの関係もありません。

ステータス（2026-10-19）：昇格済み、データ読み込み中、ツール例は未対応

移行 264 は適用済みで、fjc-idb-refresh.yml も実際に実行されました（実行 ID 39288114956）：FY2023-24 のデータが読み込み済みです — 民事 690,312 行、刑事 435,234 行、控訴 80,722 行に加え、それぞれの集計テーブルも読み込み済みです。FY2020-22 は別途読み込み中です。このセッションでパックは _incubator から昇格されましたが、tool-examples.json、実環境でのスモークテスト用ペイロード、デプロイ後の再プローブはまだ完了していません。これらには、パックを通じて稼働中のバックアップテーブルに実際に問い合わせる必要があります。そのためには、バックアップデータベースの URL とサービスロール認証情報を環境変数として設定する必要があります（正確な名前は取り込みスクリプト冒頭を参照してください）。このセッションではどちらもありませんでした（.env、すべての .dev.vars、プロセス環境に設定されていないことを確認済みです）。node scripts/add-pack.mjs fjc-case-outcomes を実行したところ、ステップ 3/11（「バックアップストアの認証情報が設定されていません」）で正常に停止しました。認証情報を持つ方は、node scripts/add-pack.mjs fjc-case-outcomes --from 3 を実行すると、その地点から再開し、実際の呼び出し結果を使って tool-examples.json を作成できます。

規模と v1 の対象範囲（PM レビューに基づき 2026-10-19 に改訂）

FJC が公開しているのは、会計年度ごと、事件種別ごとに 1 つの SAS7BDAT ファイルです。クエリ API も複数年分の一括エクスポートもありません。年度別ファイルの命名規則は、FY2021-FY2023 の実データで確認済みです（cv23.sas7bdat、cr23_0.sas7bdat、 ap23.sas7bdat — 接尾辞に一貫性がなく、ドキュメントにも記載されていないため、ファイル名を確認するロジックについては scripts/ingest-fjc-idb.mjs の冒頭を参照してください）。

v1 の対象範囲：民事と刑事のみ、FY2020-FY2024（会計年度 5 年分）。 控訴は、低コストで対応できる範囲で含めます（下記の規模を参照）が、確約済みの対象範囲ではありません。破産は対象外です（下記を参照）。

推定ではなく、実測した規模です。 FY2023 の民事（293,677 行）と 刑事（218,853 行）を実際の SAS7BDAT ファイルから解析し、ローカルの Postgres 17 に読み込んでから（生テーブル、集計テーブル、インデックス、ANALYZE）、pg_total_relation_size で測定しました。

テーブル	テーブルサイズ	インデックス	合計
fjc_idb_civil	44 MB	21 MB	65 MB
fjc_idb_criminal	27 MB	14 MB	41 MB
fjc_idb_civil_summary	1.4 MB	1.6 MB	2.9 MB
fjc_idb_criminal_summary	0.7 MB	0.9 MB	1.6 MB
会計年度 1 年分の合計			110 MB

v1（会計年度 5 年分、民事＋刑事）に単純比例で外挿すると、約 550 MBとなり、ストアの再検討が必要になる約 1.5 GB の上限を十分に下回ります。注意点：この外挿は 1 年分（FY2023）のみを基にしています。事件数は年によって変動するため、実際の 5 年分のサイズにはある程度の差が出る可能性がありますが、結論が変わるほどの倍率にはなりません。検索クエリ（インデックス付きの district＋docket）と、絞り込みを行う集計テーブルの読み取りの両方で EXPLAIN ANALYZE を実行し、インデックススキャンのみでサブミリ秒、シーケンシャルスキャンなしであることを確認しました。正確な実行計画については、移行ファイルの冒頭を参照してください。

今回のビルドでは破産 IDB データを対象外とします。 FJC は 2008 年以降、破産事件データを公開していますが、今回のセッションでプローブした bk##／bq##／bankr## 形式のファイル名（通常形式および _0 付き）のいずれも HTTP 200 を返しませんでした。別の命名規則か別のポータルを使っている可能性があります。サイズを見積もるには別途調査が必要です。URL を推測してこのビルドの対象範囲を曖昧にしないため、ここではこれ以上調査していません。

ストア

Supabase（構造化されたリレーショナルデータ、集計を多用するクエリ）を使用します。R2/FTS5 ではありません。これは、テキスト検索ではなく、GROUP BY 形式の質問（地区／年／訴訟の種類／処分別の件数）を扱う表形式の事件統計です。想定ではなく、上記の実データ量で実用性を確認済みです。

3つの生データテーブル（fjc_idb_civil、fjc_idb_criminal、fjc_idb_appellate）には、ここで使用するツールが実際に必要とするフィールドだけを格納します。raw jsonb の汎用列はありません（以前の草案にはありましたが、レビューで削除しました。実際のPostgresテーブルでは、未使用でも格納するすべてのバイトにコストがかかるためです。この改訂では、そのコストを正直に扱う必要があります）。

集計データはビューではなく、事前計算済みのサマリーテーブルです。 この移行の最初の草案では、生データテーブルに対する単純な GROUP BY ビューは安価に見えました。しかし、PostgREST は約8秒の statement_timeout で実行されます。uspto-maintenance-fees パック（2,750万行）は、count=exact とフルスキャンを取り除くまで、この構成ではすべての呼び出しがタイムアウトしました。fjc_idb_*_summary は scripts/ingest-fjc-idb.mjs によって会計年度のデータ読み込みごとに一度だけ構築されます（このスクリプトには直接のSQL接続がなく、他のすべてのパックの取り込み処理で使われるものと同じPostgREST認証情報しかないため、GROUP BY はSQLではなく、すでに解析済みの行を使ってNode上で実行されます）。また、会計年度全体を再読み込みするたびに再挿入されます。集計ツールはこれらのサマリーテーブルのみを読み取り、ケースごとの生データテーブルは読み取りません。設計の根拠全体については、マイグレーション冒頭のコメントを参照してください。

更新

生データテーブルとサマリーテーブルの両方について、行単位のアップサートではなく、会計年度全体を置き換えます。 IDB独自の四半期更新モデルでは、報告対象としてまだ開いている会計年度内のレコードのみが更新されます（FJC Research Guide）。年度が終了すると、そのファイルは変更されなくなります。そのため、定期更新では現行（および念のため前年度）のファイルだけを再取得し、該当する (table, fiscal_year) の既存行をすべて削除（生データとサマリーの両方）してから再挿入すれば十分です。実行コマンドは scripts/ingest-fjc-idb.mjs --case-type all --years <current>,<current-1> です。FY2020〜FY2024を対象とするv1の全件バックフィルは、同じスクリプトにより、より広い --years リストを使って一度だけ実行する別の処理です。スクリプトから ANALYZE は実行しません（直接のSQLアクセスがないため）。会計年度全体の置き換えによってその年度の全行が更新された後、Postgresの自動バキュームによって分析が実行されます。一度限りの初回バックフィルでは、それを待つのではなく、最後に psql から手動で ANALYZE を実行してください。

fjc-idb-refresh.yml は .github/workflows/fjc-idb-refresh.yml に配置されており（.github/workflows/** はプッシュがブロックされるため、config-applierによって適用）、データ読み込みのためにすでに一度正常に実行されています（実行番号 39288114956）。smokeステップは、tool-examples.json が存在すれば通過します（上記の「ステータス」を参照）。

完全リリースまでに残っている作業

1. バックエンドデータベースのURLとservice-role認証情報を持つ人が、node scripts/add-pack.mjs fjc-case-outcomes --from 3 を実行します。これにより、読み込み済みデータに対して両方のツールの実動作を確認し、その呼び出し結果から tool-examples.json を作成して、add-packチェックリストの残り（npm-release-statusの確認、成果物のエントリー）も実施します。
2. 次回デプロイ後に、ライブゲートウェイ経由で両方のツールを再確認します。
3. タスクの受け入れチェックリストで必要とされる smoke_payloads／live_probes などの成果物を添えて、#3271 で fleet_close を実行します。

ツール

• fjc_case_outcome_lookup(case_type, district_or_circuit, docket, fiscal_year?, defendant_number?) — 事件番号と地区（控訴審の場合は巡回区）を指定して、1件の事件または被告の結果を取得します。
• fjc_case_outcomes_summary(case_type, fiscal_year?, district_or_circuit?, nature_of_suit_code?, offense_code?, disposition_code?, group_by?, limit?) — 集計件数を返します。合計を最初に示し、要求されたディメンション（訴訟の種類／犯罪コード／処分／年／地区または巡回区）ごとに内訳を表示します。

データソース

• Federal Judicial Center、Integrated Database — 連邦裁判所における民事事件、刑事被告人、破産事件、控訴事件の申立てと終結を収録。U.S. Courts の Administrative Office が四半期ごとに報告しています。米国連邦政府のデータで、パブリックドメインです。1970年（民事・刑事）、1971年（控訴）まで継続しています。クエリ API はなく、バルクファイルのみです。このパックでは、対象を絞った年範囲を Supabase に取り込みます。

注意点

年ごとのファイル名の接尾辞には一貫性がなく、文書化もされていません。 cv23.sas7bdat（民事）には接尾辞が不要ですが、cr23_0.sas7bdat（刑事）には必要です。ap23.sas7bdat（控訴）には不要です。取り込みスクリプトはパターンを一つに固定せず、年と事件種別ごとに両方の形式を確認します。

pandas.read_sas は欠損日付に対して NaT を返します。これは単純な isinstance(v, float) and math.isnan(v) チェックでは捕捉されず、 json.dumps で TypeError: Object of type NaTType is not JSON serializable が発生します。実際に民事ファイルの TRANSDAT 列で確認されました（別の地区に移送されたことのない大多数の事件では、すべて NaT でした）。最初に pd.isna(v) を確認するよう修正しました。これにより、None、浮動小数点の NaN、NaT を一度に処理できます。

刑事被告人の氏名は、FJC 自身によってすでに匿名化されています （実データで確認済み。2023会計年度の刑事事件218,853件すべてで、NAME 列が100％ null でした）。これは1995年および2003年の Judicial Conference の方針によるものです。保持する氏名データがないため、刑事テーブルには氏名フィールドがありません。民事当事者名（PLT／DEF）は入力され公開されているため、そのまま保存します。

会計年度の境界は1992年に変更されました。 統計年度 SY70～SY91 は7月から翌年6月までで、1993年度以降は連邦政府の10月から翌年9月までの会計年度です。1992年のファイルは、移行期の15か月間を対象としています。この点を考慮しない場合、「1991年」と「1993年」のデータを求める呼び出し元は、比較できない12か月の期間を指定することになります。この点はまだツールの応答に反映されておらず、プロモーション手順で対処する必要があることが文書化されています。

コードは、人が読める名称にまだ置き換えられていない FJC の生コードです（訴訟の性質、処分、犯罪、地区、巡回区）。 対応表を推測で作成しなかった理由については、マイグレーションのヘッダーを参照してください。今後の対応として、FJC が公開しているコードブック（例：https://www.fjc.gov/sites/default/files/idb/codebooks/）を基に、小規模な参照テーブルを作成する予定です。

(fiscal_year, district, office, docket) は一意ではありません。 実際の2023会計年度の民事ファイルを読み込んで判明したもので、推測ではありません。293,677行のうち、一意な組み合わせは290,139件のみです（約1.2％が重複）。調査した1組では、処分と訴訟の性質は同じでしたが、filedate が異なっていました（2017年と2023年）。手続きが再開されたか、番号が振り直された可能性があります。IDB には事件単位のバージョン列がないため、判別できません。刑事事件でも同じ形式の重複がありました（defendant_number も含めても重複）。そのため、生テーブルではこの組み合わせに一意制約ではなく通常のインデックスを設定しています。取り込みスクリプトは重複を排除せず、FJC が公開するすべての行を読み込み、fjc_case_outcome_lookup は対象の訴訟記録に一致するすべての行を返します。

fjc_case_outcomes_summary では fiscal_year および／または district_or_circuit の指定が必要です。 集計テーブルは事前集計済みですが、複数年にわたるフィルターなしのクエリでは、PostgREST の行数上限を超える数のグループが残る可能性があります。実際に2023会計年度のみを対象に測定したところ、民事のグループは26,067件ありました。ツールは集計テーブルの詳細な粒度で一致するデータ一式を取得し、呼び出し元が指定した、より粗い group_by に合わせてクライアント側で再集計します（PostgREST では通常の select= を使ってテーブルを再度 GROUP BY することはできません）。取得件数が安全上限に達した場合、誤った合計を黙って返すのではなく、応答に total_may_be_incomplete: true を含めます。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurf など）に追加します。

{
  "mcpServers": {
    "fjc-case-outcomes": {
      "url": "https://gateway.pipeworx.io/fjc-case-outcomes/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/fjc-case-outcomes/mcp の tools/list は、上の表にあるツールに加えて、共有 Pipeworx メタツール（ask_pipeworx、 discover_tools、search_within、remember／recall など、ゲートウェイ全体で使えるツール群）も返します。そのため、表示されるツール数はこの表より多くなります。現在、単一パックのエンドポイントには、そのパック専用のツールに加えて、約30個の共有ツールが一覧表示されます。接続の initialize レスポンスには正確な対象範囲が記載されており、その日の状況を知るための確かな情報源です。

これは意図的な仕様であり、意図せず多重化されているわけではありません。メタツールを使えば、このパックでは対応できない質問にも、カタログ全体を横断する ask_pipeworx を通じて回答できます。そのため、MCP サーバーをもう1つ追加する必要はありません。現時点では、メタツールなしでパックのエンドポイントを接続する方法はありません。追加のスキーマによるコンテキスト消費が、ルーティングのメリットを上回る場合は、複数のパックエンドポイントではなく、フルゲートウェイに一度だけ接続してください。

または、Pipeworx のフルゲートウェイに接続すると、このパックのツールだけでなく、すべてのパックのツールが直接一覧表示されます。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらの URL も同じゲートウェイと同じ1879以上のデータソースに接続します。違いは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも、ask_pipeworx を使ってすべてのツールにアクセスできます。

MCP クライアントがない場合：HTTP 経由で呼び出す

curl -X POST https://gateway.pipeworx.io/v1/tools/fjc_case_outcome_lookup \
  -H 'Content-Type: application/json' \
  -d '{"case_type":"civil","district_or_circuit":"90","docket":"1701877","fiscal_year":2023}'

最初の呼び出しにはアカウントは必要ありません。任意のツールを確認するには、GET https://gateway.pipeworx.io/v1/tools/fjc_case_outcome_lookup を実行します。ツールを検索するには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を実行します。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージは、ローカルの stdio MCP サーバーとしても実行できます。Pipeworx アカウントやゲートウェイへの往復通信は必要ありません。

{
  "mcpServers": {
    "fjc-case-outcomes": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-fjc-case-outcomes"]
    }
  }
}

または、直接実行して起動を確認します。

npx -y @pipeworx/mcp-fjc-case-outcomes

stdin／stdout 経由で MCP を使用し、initialize／tools/list／tools/call に応答します。対象となるのはこのパックのツールのみで、上記のゲートウェイ接続で追加される共有メタツールは含まれません。同じソース、同じツールで、ask_pipeworx によるルーティングはありません。

ask_pipeworx の使用

ツールを直接呼び出す代わりに、自然な英語で質問できます。これは、上記のパックエンドポイントでもフルゲートウェイでも利用できます。

ask_pipeworx({ question: "your question about Fjc Case Outcomes data" })

ゲートウェイが適切なツールを選び、引数を自動的に設定します。

詳細情報

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT