学校連絡まとめる君 | Portfolio Case Study

作った理由

学校からの連絡は「届いている」のに、実際にはメール本文、リンク先、PDF、紙で持ち帰るプリント、カレンダー転記まで確認が分散し、家庭内での見落としや共有漏れが起きやすい状態でした。日々の小さな運用負荷を、要件定義から設計・実装・運用改善までひとつの業務アプリとして形にすることを目的に開発しました。

なぜローカルLLMか

学校連絡には、子ども、学校、予定、提出物など家庭に閉じたい情報が含まれます。そのためクラウドLLMへ本文やPDF抽出テキストを送る設計ではなく、ローカル環境上のLM StudioとGemma 4で解析を完結させる方針にしました。精度が必要な場面だけ大きいモデルへ切り替え、普段は軽量モデルを使うことで、プライバシーと実行コストの両立を狙っています。

runtime 4 containers

frontend / backend / db / worker

database 11 migrations

Alembicで段階的にスキーマ管理

backend 106 Python files

API、サービス、モデル、テストを分離

quality 124 tests

pytestで契約・リトライ・運用処理を検証

Problem

解いた課題

学校連絡はメール本文だけで完結せず、本文ページ、PDF、紙で配られるプリントまで確認しないと必要な情報に到達できないことがあります。その確認作業を、ローカル運用を前提に安全に自動化しました。

Before

通知メール、本文ページ、PDF、紙プリント、カレンダーが分散
予定・提出期限・持ち物を手作業で読み取る
紙のおたよりは写真を撮っても、家族内で元画像を探し直しやすい
家庭内共有やGoogleカレンダー登録で漏れが起きやすい
学校連絡データを外部AI APIへ安易に送れない

After

Gmail、key付きURL、PDF、Drive上の紙おたより画像を同一の学校連絡として保存
ローカルLLMでお知らせ、期限、対応区分、画像内の持ち物を候補化
通知メールと管理画面から元画像のDriveリンクを開ける
管理者確認後に通知メールとカレンダー候補へ展開
本文全文やトークンを通常ログ、公開サイト、Gitに出さない

Operation Results

運用実績（実測値）

家庭内で連続運用した約6週間分（2026-05-20〜07-03）の実測値です。成功数だけでなく失敗も計測・分解し、原因に応じた対策へつなげる方針で運用しています。

ingestion 学校連絡 82件

メール・PDF・紙おたより画像を自動処理

ai analysis 解析 106回

成功81 / 失敗25（失敗も分類して記録）

notification 通知メール 55通

スケジュール42+手動13、送信失敗は1通

calendar 候補 90件

登録・既存紐づけ23件、重複確認を経て判断

失敗を分解して直す

解析失敗25件の内訳は、LLM接続失敗14、JSON解釈不能8、スキーマ違反2、タイムアウト1。「AIの精度不足」に見えていた問題の過半は、実際にはローカルLLMサーバーへの接続というインフラ起因でした。この分解に基づき、接続系エラーの指数バックオフ付きリトライと、壊れたJSON応答をエラー内容付きで再生成させる自己修復リトライを実装しています。

モデル使い分けの実測根拠

通常解析のGemma 4 4B系は平均56秒、PDF・画像解析用のGemma 4 26B系は平均145秒。「普段は軽量モデル、難しい連絡だけ大きいモデル」という使い分けを、体感ではなく実測値に基づいて運用しています。運用の詳細はZennの運用記録にまとめています。

System Flow

処理フロー

01 Gmail取り込み
専用Gmailの通知メールをMIME解析し、message_idで重複防止。
02 本文取得
通知メール内のkey付きURLから本文ページを保存。
03 紙おたより取り込み
Drive共有フォルダのJPEG/PNG/HEIC/PDFを検出し、近接アップロードを1文書にまとめる。
04 PDF処理
添付PDF、本文内PDF、紙おたよりファイルを保存し、SHA256で重複判定。
05 ローカルLLM解析
本文、PDF抽出テキスト、紙おたより画像を構造化し、JSON契約で候補化。
06 管理者確認
AI結果を即上書きせず、修正履歴と差分確認を残す。
07 通知・カレンダー
日次/週次/月次メール、Googleカレンダー候補、運用ログへ展開。

Features

機能概要

取得、解析、確認、通知、運用までをMVPの一連の業務フローとして実装しています。

Gmail取り込み

専用Gmailから通知メールを取得し、本文、HTML、添付候補、URLを抽出。

Gmail API / MIME解析 / ラベル付与

PDF保存・抽出

本文ページ内PDFと添付PDFを保存し、抽出テキストと失敗理由を履歴化。

pypdf / PyMuPDF / pdfplumber / SHA256

紙おたよりDrive取り込み

共有フォルダに置いた写真やPDFを取得し、60秒以内の複数写真を1文書として扱う。

Google Drive API / JPEG / PNG / HEIC / PDF

AI解析

Gemma 4 4Bを通常解析、Gemma 4 26BをPDF/画像解析用プロファイルに使い分けて候補化。

LM Studio / Gemma 4 / JSON契約 / Pydantic検証

お知らせ管理

AI候補を管理者が確認し、編集、再解析、差分反映、破棄を選べる。

修正履歴 / 再解析差分 / 要確認フラグ

通知メール

日次、週次、月次の通知プレビューをHTMLメールとして確認し、Gmail APIで送信。

HTML preview / Gmail send / duplicate guard

Googleカレンダー

AI解析の予定候補を確認し、重複候補を見てから登録、紐づけ、更新。

Calendar API / 近似タイトル / 二重登録防止

AI解析改善

管理者修正から改善候補を作り、採用済みルールをプロンプトへ適用して次回解析へ反映。適用効果は検証ルールで実証済み。

改善キュー / ルールスナップショット / 効果検証

運用管理

処理エラー、バッチ履歴、監査ログ、手動バックアップ、OAuth状態を確認。

APScheduler / audit log / backup zip

LLM起動切り替え

解析用途に応じてモデルをロードし、不要になったモデルをアンロードしてローカル環境のメモリ使用量を抑制。

LM Studio lifecycle / model unload / memory saving

System Overview

一枚で見るシステム全体

メールと紙のおたよりを集め、ローカル環境で読み取り、管理者が確認してから家族への通知とカレンダー候補につなげます。学校連絡の本文や画像は外部AIへ送らず、ローカル環境内の処理で完結させる設計です。

情報源

学校から届くもの

さくら連絡網メール

通知メール、本文ページ、添付PDF、本文内PDF

紙のおたより

家族が撮影してGoogle Drive共有フォルダへアップロード

ローカル実行環境 / Docker Compose ── 本文・PDF・画像はこの枠の外に出さない 学校連絡まとめる君

Frontend Next.js管理画面

取り込み、確認、修正、通知送信を操作

Backend FastAPI

Gmail / Drive / Calendar連携と業務処理

Storage PostgreSQL + local files

お知らせ、処理済み状態、PDF、画像を保存

Worker 定期実行

メールとDriveを指定時刻に確認

AI LM Studio / local LLM

本文、PDF、紙おたより画像から予定・持ち物・提出物を候補化

家族へ

必要な形で届ける

通知メール

今日・今週・今月の提出物、持ち物、期限を整理

Googleカレンダー

行事や締切を重複確認して候補登録

元資料リンク

PDFや紙おたより画像をDriveリンクから確認

1集める
GmailとDriveから未処理の連絡を取得
2まとめる
メール、PDF、複数写真を1つの学校連絡へ整理
3読み取る
ローカルLLMが予定・持ち物・提出物を候補化
4確認する
管理者がAI結果を見て修正・採用
5届ける
通知メール、カレンダー候補、元資料リンクへ展開

Architecture

技術構成

家庭内のローカル運用を本線に、管理画面、API、DB、worker、ローカルLLM、外部Google APIを分離して構成しています。

専用Gmail
通知メール

Google Drive
紙おたより画像

取得

FastAPI
API / services

保存

PostgreSQL
Alembic

Local storage
PDF / backups

Worker
APScheduler

Local LLM
LM Studio

Google Calendar
候補登録

Next.js
管理コンソール

Stack

Frontend: Next.js, React, TypeScript
Backend: Python, FastAPI, SQLAlchemy, Pydantic
Database: PostgreSQL, Alembic
Worker: APScheduler, batch history
AI: LM Studio, Gemma 4 4B / 26B, PDF/画像解析用プロファイル, OpenAI互換API, Ollama形式対応
External APIs: Gmail API, Google Drive API, Google Calendar API
Runtime: Docker Compose, local-first

LLM運用方針

通常のお知らせ抽出は軽量なGemma 4 4Bを優先し、PDF量が多い連絡、紙おたより画像、判断が難しい連絡ではGemma 4 26Bへ切り替えます。学校連絡データをクラウドLLMへ送らず、LM Studioのモデルロード/アンロードを制御して、常時大きなモデルを載せ続けないことでプライバシーとメモリ使用量の両方に配慮しています。

設計・実装ハイライト

設計と実装の見どころ

面接で深掘りしやすい、要件に対する設計判断と実装上の工夫が出る領域です。

Notification

通知メールのプレビューと送信

日次、週次、月次の対象期間を選び、件名、送信先、対象のお知らせ、HTMLメール本文を確認してから送信します。同じ期間の再送は確認を挟み、家族への重複通知を避ける導線にしています。

AI workflow

AI再解析と差分反映

LLMの結果を即時上書きせず、現在値と再解析候補の差分を表示します。管理者が反映または破棄を選び、修正履歴を保存することで、AIを業務データの候補生成役として扱えるようにしました。

External integration

Googleカレンダー二重登録防止

同日または近い日付、近いタイトルの予定を重複候補として保存します。重複候補がある場合は新規登録を止め、既存予定への紐づけや更新を選べるようにしています。

Operation

AI解析改善ルールと「効いているか」の検証

管理者修正から改善候補を作成し、採用済みルールだけをプロンプトへ適用する改善ループです。運用中の計測で「ルールがLLMに渡っているのに、適用指示がなく効いていない」状態を発見し、プロンプト設計を修正。効果が疑いようのない検証ルールを使ったbefore/after比較で、ルールが実際に出力を変えることを確認しました。解析実行ごとに適用ルールとプロンプトバージョンをスナップショット保存する設計が、この検証を可能にしています。

Implementation Notes

実装で工夫した点

秘匿情報をログに出さない

key付きURL全文、メール本文全文、PDF内容、紙おたより画像の解析入力、AI入力全文は通常ログへ出さず、解析履歴には要約とハッシュを残す設計にしました。

クラウドLLMではなくローカルLLMを選択

学校連絡、PDF、紙おたより写真には家庭・子どもに関わる情報が含まれるため、外部AI APIへ送信せず、ローカル環境内で解析を完結させています。

OAuthトークンをDBに保存しない

Gmail、Google Drive、Google CalendarのOAuthトークンはGit管理外のcredentials配下に置き、DBには状態確認に必要なメタ情報だけを扱います。

AI応答を契約で検証

自由文ではなくJSON契約で受け取り、必須項目不足、壊れたJSON、空応答を処理エラーとして保存します。

Gemma 4を用途別に使い分ける

通常解析は4B、PDF/画像解析や複数日付を含む難しい連絡は26Bを使う方針にし、精度とローカル実行コストのバランスを取っています。

PDF/画像の重複と取得失敗を運用に残す

PDFや紙おたよりファイルはSHA256とDrive file IDで重複判定し、同一ファイルの再保存を避けます。抽出失敗や画像スキャン疑いは要確認として扱います。

iPhone写真運用をシステム側で吸収

写真名を変えられない前提で、1分以内の近接アップロードを同一文書候補にし、ページ順、使用/除外、手動回転をUIで調整できるようにしました。

通知メールに載せる情報を絞る

管理者メモ、本文全文、PDF抽出全文、画像解析内容の全文は載せず、通知用メモと必要な元資料リンクだけを家族向けメールに含めます。

MVP段階から運用を設計

処理エラー、バッチ履歴、操作履歴、バックアップ、OAuth再認可、AI改善キューを管理コンソールに含めています。

「動く」と「効く」を分けて検証する

UI・DB・履歴が正常でも、LLMの挙動が変わっているかは別問題です。解析ごとの適用ルール・プロンプトバージョンのスナップショットを使ったbefore/after比較と、プロンプト構築の配線テストで「効いていること」を検証しています。

LLMの常時起動を避ける

LM Studioのライフサイクル制御で必要なモデルを起動し、解析後にアンロードすることで、ローカル環境のメモリ占有を抑えています。

Screens

画面紹介

取得、解析、通知、カレンダー登録、運用改善までの主要な操作画面です。

ダッシュボード画面 — ダッシュボード: 取り込み、要確認、通知失敗、カレンダー候補を集約

通知メールプレビュー画面 — 通知プレビュー: 件名、送信先、対象のお知らせ、HTMLメール本文を確認して送信

カレンダー候補画面 — カレンダー候補: 重複確認後に新規登録、紐づけ、更新を選択

運用画面 — 運用: AI解析改善キュー、Drive/OAuth設定、処理エラー、バックアップを確認

Development Timeline

開発プロセス

機能を小さなPhaseに分け、設計、実装、検証、運用改善を段階的に進めました。

Phase 0-1基盤・認証・DB
Docker Compose、FastAPI、PostgreSQL、Googleログイン、初期スキーマ。
Phase 2管理コンソール
ダッシュボード、共通レイアウト、取り込み一覧の土台。
Phase 3Gmail取り込み
Gmail API、MIME解析、key付きURL取得、PDF保存。
Phase 4PDF抽出
PDFテキスト抽出、PDF確認画面、抽出失敗の要確認化。
Phase 5-6AI解析・再解析
ローカルLLM連携、JSON検証、お知らせ生成、差分確認。
Phase 7-8通知・カレンダー
通知メール生成、Gmail送信、Googleカレンダー候補と重複防止。
Phase 9+運用改善
処理エラー、監査ログ、バックアップ、OAuth再認可、AI解析改善キュー。
Phase 10紙おたよりDrive対応
Google Drive取り込み、画像Vision解析、複数写真グルーピング、元画像リンク通知。
Phase 11運用検証・信頼性改善
改善ルールの効果検証と修正、LLMリトライ/JSON自己修復、送信後の自動整理、OAuthトークン監視。

Gmail / Drive / PDF / Local LLM / Calendar 学校連絡の取得から 通知までを自動化 ローカル運用MVP