natsume-simpleは日本語の係り受け関係を検索できるシステム
本プロジェクトには以下の3つの開発環境のセットアップ方法があります：
VSCodeとDev Containersの拡張機能をインストールした後：
- このリポジトリをクローン：
git clone https://github.com/borh/natsume-simple.git- VSCodeでフォルダを開く
- 右下に表示される通知から、もしくはコマンドパレット（F1）から「Dev Containers: Reopen in Container」を選択（natsume-simple）
- コンテナのビルドが完了すると、必要な開発環境が自動的に設定されます
上記はローカルですが、Codespacesで作り、Githubクラウド上の仮想マシンで入ることもできます。 その場合は、Github上の「Code」ボタンから「Codespaces」を選択し、「Create codespace on main」でブラウザ経由でDev Containerに入れます。 また、同じことはVSCode内のGitHub Codespaces拡張機能でもできます。
- Determinate Nix InstallerでNixをインストール：
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | \
sh -s -- install- プロジェクトのセットアップ：
git clone https://github.com/borh/natsume-simple.git
cd natsume-simple
nix develop以下のツールを個別にインストールする必要があります：
- git
- Python 3.12以上
- uv
- Node.js
- pandoc
その後：
git clone https://github.com/borh/natsume-simple.git
cd natsume-simple
uv sync --extra backend
cd natsume-frontend && npm install && npm run build && cd ..このプロジェクトはNixフレークを使用して開発環境とビルドを管理しています。以下のコマンドが利用可能です：
# 開発環境に入る
nix develop
# または direnvを使用している場合（推奨）
direnv allow# テストを実行
nix run .#test
# リンター実行
nix run .#lint
# 開発サーバー起動（ホットリロード有効）
nix run .#dev-server
# プロダクションサーバー起動
nix run .#server# フォーマット
nix fmt
# ビルド
nix build
# 開発環境のシェル情報を表示
nix develop --print-build-logs注意：
- 各コマンドは自動的に必要な依存関係をインストールします
nix developで入る開発環境には以下が含まれています：- Python 3.12
- Node.js
- uv（Pythonパッケージマネージャー）
- pandoc
- その他開発に必要なツール
データの準備から検索システムの利用まで、以下の順序で処理を行う必要があります：
- データの準備（JNLPコーパスとTEDコーパスのダウンロードと前処理）
- パターン抽出（各コーパスからのNPVパターンの抽出）
- サーバーの起動（検索インターフェースの提供）
python src/natsume_simple/data.py --prepareオプション：
--data-dir PATH- データを保存するディレクトリ（デフォルト: ./data）--seed INT- 乱数シードの設定（デフォルト: 42）
この処理で以下が実行されます：
- JNLPコーパスのダウンロードと変換
- TEDコーパスのダウンロードと前処理
- 前処理済みデータの保存
準備済みデータを読み込む場合：
python src/natsume_simple/data.py --load \
--jnlp-sample-size 3000 \
--ted-sample-size 30000オプション：
--jnlp-sample-size INT- JNLPコーパスからのサンプルサイズ（デフォルト: 3000）--ted-sample-size INT- TEDコーパスからのサンプルサイズ（デフォルト: 30000）--data-dir PATH- データディレクトリの指定（デフォルト: ./data）--seed INT- 乱数シードの設定（デフォルト: 42）
この処理で以下が実行されます：
- 準備済みコーパスの読み込み
- 指定されたサイズでのサンプリング
- サンプリングされたコーパスの保存（{コーパス名}-corpus.txt形式）
注意：
- 各コマンドは必要な依存関係がインストールされていることを前提としています
- エラーが発生した場合は、依存関係のインストール状態を確認してください
- コーパスファイルは標準的な命名規則（{コーパス名}-corpus.txt）で保存されます
# JNLPコーパス用
python src/natsume_simple/pattern_extraction.py \
--model ja_ginza_bert_large \
--corpus-name "JNLP" \
data/jnlp-corpus.txt \
data/jnlp_npvs_ja_ginza_bert_large.csv
# TEDコーパス用
python src/natsume_simple/pattern_extraction.py \
--model ja_ginza_bert_large \
--corpus-name "TED" \
data/ted-corpus.txt \
data/ted_npvs_ja_ginza_bert_large.csvオプション：
--model NAME- 使用するspaCyモデル（オプション、デフォルト:ja_ginza_bert_large）--corpus-name NAME- コーパス名の指定（デフォルト: "Unknown"）--seed INT- 乱数シードの設定（デフォルト: 42）
この処理で以下が実行されます：
- コーパスの読み込み
- NPVパターンの抽出
- 結果のCSVファイルへの保存
uv run fastapi dev src/natsume_simple/server.pyこのコマンドでは，server.pyをFastAPIでウエブサーバで起動し，ブラウザからアクセス可能にする。
オプション：
--reload- コード変更時の自動リロード（開発時のみ）--host HOST- ホストの指定（デフォルト: 127.0.0.1）--port PORT- ポートの指定（デフォルト: 8000）
注意：
server.pyでは，モデルの指定があるのでご注意。- サーバを起動後は，出力される手順に従い，http://127.0.0.1:8000/にアクセスする。
- FastAPIによるドキュメンテーションはhttp://127.0.0.1:8000/docsにある。
- 環境によってはhttp://0.0.0.0:8000がhttp://127.0.0.1:8000と同様ではない
- 特定の係り受け関係（名詞ー格助詞ー動詞，名詞ー格助詞ー形容詞など）における格助詞の左右にある語から検索できる
- 検索がブラウザを通して行われる
- 特定共起関係のジャンル間出現割合
- 特定共起関係のコーパスにおける例文表示
このプロジェクトはNixフレークを使用して開発環境とビルドを管理しています。
開発環境では以下のコマンドが利用できます：
# データ準備
prepare-data # JNLPコーパスとTEDコーパスのダウンロードと前処理
extract-patterns # 準備されたコーパスからパターンを抽出
# 開発用
dev-server # 開発サーバーの起動（ホットリロード有効）
server # プロダクションサーバーの起動
build-frontend # フロントエンドのビルド
watch-frontend # フロントエンド開発サーバーの起動
# テストとリント
run-tests # テストスイートの実行
lint # リンターとフォーマッターの実行
# 一括実行
run-all # 完全なパイプラインの実行（prepare-data, extract-patterns, server）各コマンドは nix run .#コマンド名 の形式で実行できます。例：
nix run .#prepare-data
nix run .#dev-serverまた、開発環境に入るには：
# 開発環境に入る
nix develop
# または direnvを使用している場合（推奨）
direnv allow注意：
- 各コマンドは自動的に必要な依存関係をインストールします
nix developで入る開発環境には以下が含まれています：- Python 3.12
- Node.js
- uv（Pythonパッケージマネージャー）
- pandoc
- その他開発に必要なツール
このプロジェクトは以下のファイルを含む：
.
├── data/ # コーパスとパターン抽出結果
│ ├── ted_corpus.txt # TEDコーパス
│ ├── jnlp_npvs_*.csv # 自然言語処理コーパスのパターン抽出結果
│ └── ted_npvs_*.csv # TEDコーパスのパターン抽出結果
│
├── notebooks/ # 分析・可視化用Jupyterノートブック
│ ├── pattern_extraction.ipynb # パターン抽出処理の開発用
│ └── visualization.ipynb # データ可視化用
│
├── natsume-frontend/ # Svelteベースのフロントエンド
│ ├── src/ # アプリケーションソース
│ │ ├── routes/ # ページルーティング
│ │ └── tailwind.css # スタイル定義
│ ├── static/ # 静的アセット
│ └── tests/ # フロントエンドテスト
│
├── src/natsume_simple/ # バックエンドPythonパッケージ
│ ├── server.py # FastAPIサーバー
│ ├── data.py # データ処理
│ ├── pattern_extraction.py # パターン抽出ロジック
│ └── utils.py # ユーティリティ関数
│
├── scripts/ # データ準備スクリプト
│ ├── get-jnlp-corpus.py # コーパス取得
│ └── convert-jnlp-corpus.py # コーパス変換
│
├── tests/ # バックエンドテスト
│ └── test_models.py # モデルテスト
│
├── pyproject.toml # Python依存関係定義
├── flake.nix # Nix開発環境定義
└── README.md # プロジェクトドキュメント
各種のデータはdataに保存する。 特にscriptsやnotebooks下で行われる処理は，最終的にdataに書き込むようにする。
特に動的なプログラミングをするときや，データの性質を確認したいときに活用する。 ここでは，係り受け関係の抽出はすべてノートブック上で行う。
VSCodeなどでは，使用したいPythonの環境を選択の上，実行してください。
Google Colabで使用する場合は，リンクから開くか，pattern_extraction_colab.ipynbのファイルをColabにアップロードして利用する。
Jupyter Notebook/JupyterLabでは使用したPythonの環境をインストールの上，Jupterを立ち上げてください。
jupyter lab右上のメニューに選択できない場合は環境に入った上で下記コマンドを実行するとインストールされる：
python -m ipykernel install --user --name=$(basename $VIRTUAL_ENV)Svelte 5で書かれた検索インターフェース。
Svelteのインターフェース（html, css, jsファイル）は以下のコマンドで生成できる：
（natsume-frontend/フォルダから実行）
npm install
npm run buildSvelteの使用にはnodejsの環境整備が必要になる。
サーバ読む静的ファイルを含むファルダ。
上記のnpm run buildコマンド実行でstatic/下にフロントエンドのファイルが作成される。
ここに置かれるものは基本的にAPIのstatic/URL下で同一ファイル名でアクセス可能。
係り受け解析に使用されるモデルを利用するために以下のようにloadする必要がある。 環境設定が正常かどうかも以下のコードで検証できる。
import spacy
nlp = spacy.load('ja_ginza_bert_large')あるいは
import spacy
nlp = spacy.load('ja_ginza')notebooksにあるノートブックでは，優先的にja_ginza_bert_largeを使用するが，インストールされていない場合はja_ginzaを使用する。
プロジェクト環境内でノートブックを作れば，from natsume_simple.pattern_extraction import normalize_verb_spanなど個別に関数をインポートし，動的にテストすることができる。