fuseji 0.1.0__tar.gz

fuseji-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: バグ報告
+about: 不具合を報告する
+title: ""
+labels: bug
+assignees: ""
+---
+
+## 現象
+
+<!-- 何が起きたかを簡潔に記述してください -->
+
+## 再現手順
+
+1.
+2.
+3.
+
+## 期待する動作
+
+<!-- 本来どうなるべきかを記述してください -->
+
+## 実際の動作
+
+<!-- 実際に起きたことを記述してください -->
+
+## 再現コード
+
+```python
+from fuseji import Masker
+
+masker = Masker()
+# ここに再現コードを記述
+```
+
+## 環境
+
+- fuseji バージョン:
+- Python バージョン:
+- OS:
+- extras（ginza, server 等）:

fuseji-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: true
+contact_links: []

fuseji-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: 機能要望
+about: 新しい機能やエンティティタイプの追加を提案する
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## 概要
+
+<!-- どのような機能が欲しいかを簡潔に記述してください -->
+
+## 背景・動機
+
+<!-- なぜこの機能が必要かを記述してください -->
+
+## 想定する利用イメージ
+
+```python
+# この機能をどのように使いたいかを記述
+```
+
+## 備考
+
+<!-- 参考情報、代替案などがあれば記述してください -->

fuseji-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## 関連 Issue
+
+<!-- closes #123 -->
+
+## 変更内容
+
+<!-- 何をどう変更したかを簡潔に記述してください -->
+
+## テスト
+
+- [ ] 既存テストが通ること（`uv run pytest`）
+- [ ] 新規テストを追加した（該当する場合）
+- [ ] リントが通ること（`uv run ruff check src/ tests/`）
+- [ ] 型チェックが通ること（`uv run mypy src/`）

fuseji-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint / type-check (Python 3.13)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.13
+      - name: Install dependencies (all extras for mypy stubs)
+        run: uv sync --all-extras
+      - name: ruff check
+        run: uv run ruff check src/ tests/
+      - name: ruff format check
+        run: uv run ruff format --check src/ tests/
+      - name: mypy
+        run: uv run mypy src/
+
+  test-core:
+    name: test (core, ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Python 3.14 まで含める。test-extras（ginza）は spaCy 3.8 の wheel 制約で
+        # 3.13 までしか試せないため、本マトリクスは core のみ。
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python }}
+        run: uv python install ${{ matrix.python }}
+      - name: Install dependencies (core only — extras なし)
+        run: uv sync --python ${{ matrix.python }}
+      - name: pytest (extras なし — ginza/server テストは skip)
+        run: uv run pytest -q
+
+  test-extras:
+    name: test (all extras, Python 3.13)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.13
+      - name: Install all extras (ginza + server)
+        run: uv sync --all-extras
+      - name: pytest (all extras)
+        run: uv run pytest -q
+
+  bench:
+    name: bench (informational)
+    runs-on: ubuntu-latest
+    # 情報表示のみ。回帰検知 assertion 化は別 Issue で対応。
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.13
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: pytest-benchmark (情報表示)
+        run: |
+          uv run pytest tests/bench/ --benchmark-enable \
+            --benchmark-columns=min,mean,max,stddev,median \
+            --benchmark-group-by=group \
+            --benchmark-warmup=on

fuseji-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,96 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: '公開先 (testpypi で検証 → pypi で本番公開)'
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+  push:
+    tags:
+      # vX.Y.Z 形式のタグ push 時に PyPI 本番へ自動公開
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      - 'v[0-9]+.[0-9]+.[0-9]+rc[0-9]+'
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # version 推定や changelog 生成のため履歴フル取得
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Install dependencies (all extras for mypy stubs)
+        run: uv sync --all-extras
+      - name: ruff check
+        run: uv run ruff check src/ tests/
+      - name: ruff format check
+        run: uv run ruff format --check src/ tests/
+      - name: mypy
+        run: uv run mypy src/
+      - name: pytest
+        run: uv run pytest -q
+      - name: Build distributions
+        run: uv build
+      - name: Verify built artifacts
+        run: |
+          ls -la dist/
+          uv run python -m zipfile -l dist/*.whl | head -20
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/fuseji
+    permissions:
+      id-token: write  # OIDC token for trusted publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: >-
+      github.event_name == 'push' ||
+      (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fuseji
+    permissions:
+      id-token: write  # OIDC token for trusted publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fuseji-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# 仮想環境
+.venv/
+venv/
+env/
+
+# テスト・カバレッジ
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# 環境変数
+.env
+.env.local

fuseji-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

fuseji-0.1.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# 変更履歴 / Changelog
+
+本ファイルは [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) に従い、
+バージョニングは [Semantic Versioning](https://semver.org/spec/v2.0.0.html) に従います。
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-12
+
+初回 PyPI リリース。日本語特化の PII 検出・マスキングミドルウェア。
+
+### Added
+
+#### コア機能
+
+- **コア型**: `Entity`、`MaskResult`（frozen dataclass、バリデーション付き）
+- **マスキング戦略**: `MaskStrategy` プロトコル + `Placeholder` / `Redact` / `Hash` / `VaultStrategy` の 4 実装
+- **仮名化バウルト**: `Vault` プロトコル + `InMemoryVault` 実装。同一 (type, surface) → 同一 placeholder、`MY_NUMBER` をデフォルト除外（番号法対応）
+  - `restore()` は placeholder regex マッチで silent corruption を構造的に防ぐ
+  - `clear()` で全マッピングを破棄可能（`excluded_types` 設定は維持）
+  - `size` プロパティで登録済み placeholder 数を取得
+  - `assign()` は `threading.Lock` で保護（並行採番衝突なし）
+  - `__repr__` で状態を可視化
+- **PII 認識器（v0.1 セット）**:
+  - `EMAIL`（RFC-lite）
+  - `CREDIT_CARD`（Luhn 検証）
+  - `MY_NUMBER`（12 桁、総務省公開仕様のチェックディジット、recall 優先）
+  - `JP_PHONE_NUMBER`（携帯 070/080/090、フリーダイヤル 0120、ナビダイヤル 0570、固定電話）
+  - `JP_POSTAL_CODE`（〒、コンテキストブースト）
+  - すべて全角数字・全角ハイフン対応、共通ヘルパ（`SEPARATOR_PATTERN`, `has_digit_boundary`）
+- **NER バックエンド**: `NerBackend` プロトコル + GiNZA 実装（`[ginza]` extra）で PERSON 検出
+- **Masker エンジン**:
+  - `Masker.mask` / `Masker.mask_json` / `Masker.detect`
+  - オーバーラップ解決はスコア優先 → 長 span 優先 → 開始位置順
+  - `max_json_depth`（既定 100）で `mask_json` の再帰深度を制限、超過時は fail-closed
+  - `Masker(vault=..., strategy=...)` 同時指定で `UserWarning`（vault 優先）
+
+#### 統合
+
+- **Langfuse SDK アダプタ**: `make_mask_fn()`。fail-closed 設計
+  - 例外時は固定 placeholder `"[fuseji: masking failed]"` を返し原データを露出しない
+  - デフォルトログは例外型名のみ（traceback 内 PII 漏洩防止）、`FUSEJI_LANGFUSE_LOG_TRACEBACK=1` で詳細出力
+- **FastAPI サーバー**（`[server]` extra）:
+  - `POST /mask` / `POST /detect` / `GET /healthz` / OpenAPI 自動生成
+  - `create_app(masker=..., max_body_bytes=...)` factory で DI
+  - `BodySizeLimitMiddleware` で 1MB 超リクエストを 413 で拒否（環境変数で上書き可）
+
+#### API ユーティリティ
+
+- **`fuseji.entity_types` 定数モジュール**: `EMAIL` / `CREDIT_CARD` / `MY_NUMBER` / `JP_PHONE_NUMBER` / `JP_POSTAL_CODE` / `PERSON` を str 定数として提供
+- **`FusejiError` 例外階層**: `FusejiError`（基底）/ `InvalidEntityError` / `InvalidConfigError`。多重継承で `ValueError` も継承（後方互換）
+- **公開 API の docstring に Example セクション**（doctest として実行可能）
+
+#### 品質・運用
+
+- **CI**: GitHub Actions で ruff / mypy / pytest を Python 3.10–3.14 マトリクス + 全 extras ジョブ + 情報的 bench ジョブ
+- **fuseji-bench**: `pytest-benchmark` 基盤と 23 ベンチケース
+- **レイテンシ回帰検知テスト**: O(n²) バグ等を通常 pytest で即時 fail（Masker 1KB/4KB、Vault.restore m=1000）
+- **PyPI 公開**: Trusted Publishing (OIDC) workflow
+
+### Performance
+
+- `_replace_spans` を list-of-segments の 1 パスに変更し O(n²) → O(n+k)
+- `normalize()` の translate テーブルを統合し 2 パスから 1 パスに
+
+### Security
+
+- マイナンバーは Vault のデフォルト除外集合に含み復元不可
+- `InMemoryVault.restore()` を placeholder regex マッチに変更し silent corruption を構造的に排除
+- `InMemoryVault.assign` を `threading.Lock` で保護
+- Langfuse adapter のデフォルトログから traceback 除去
+- `Masker(max_json_depth=...)` で DoS 対策
+- `BodySizeLimitMiddleware` で巨大ペイロードを拒否
+
+### Documentation
+
+- README（日本語メイン + 英語ミラー）
+- SECURITY.md（番号法対応・脆弱性報告窓口・設計上の安全保証）
+- docs/design.md / docs/api.md
+- examples/（Langfuse SDK / ingestion callback / OTel / GiNZA）
+- CONTRIBUTING.md
+
+[Unreleased]: https://github.com/sserada/fuseji/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sserada/fuseji/releases/tag/v0.1.0

fuseji-0.1.0/CLAUDE.md

@@ -0,0 +1,47 @@
+# fuseji 開発ガイド
+
+## プロジェクト概要
+
+fuseji (伏せ字) — 日本語特化のPII検出・マスキングミドルウェア（LLMオブザーバビリティ向け）。
+Python 3.10+、`uv` でパッケージ管理。
+
+## 開発フロー
+
+1. GitHub Issue を作成し、タスクを記述する
+2. `main` からブランチを作成する: `feat/<issue番号>-<短い説明>`, `fix/<issue番号>-<短い説明>`, `chore/<issue番号>-<短い説明>`
+3. 開発・コミット
+4. Issue を参照する PR を `main` に対して作成する
+5. レビュー後にマージ
+
+`main` への直接 push は禁止。必ず PR を経由すること。
+
+## コマンド
+
+```bash
+uv sync                          # 依存関係のインストール
+uv run ruff check src/ tests/    # リント
+uv run ruff format src/ tests/   # フォーマット
+uv run mypy src/                 # 型チェック
+uv run pytest                    # テスト実行
+```
+
+## コード規約
+
+- ソースレイアウト: `src/fuseji/`
+- 公開APIには型アノテーション必須
+- docstring・コメントは日本語
+- Issue・PR・コミットメッセージは日本語
+
+## ディレクトリ構成
+
+```
+src/fuseji/
+├── engine.py          # Maskerエンジン
+├── types.py           # Entity, MaskResult
+├── strategies.py      # Placeholder / Redact / Hash
+├── vault.py           # 仮名化バウルト
+├── recognizers/       # PII認識器
+├── ner/               # NERバックエンド
+├── integrations/      # 外部サービス連携
+└── server/            # FastAPIサーバー
+```

fuseji-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# コントリビューションガイド
+
+fuseji への貢献に感謝します。
+
+## 開発環境のセットアップ
+
+```bash
+# リポジトリをクローン
+git clone https://github.com/sserada/fuseji.git
+cd fuseji
+
+# 依存関係をインストール（uv が必要）
+uv sync --all-extras
+```
+
+## 開発フロー
+
+1. Issue を作成し、やることを記述する
+2. `main` からブランチを作成する
+   - 機能追加: `feat/<issue番号>-<短い説明>`
+   - バグ修正: `fix/<issue番号>-<短い説明>`
+   - その他: `chore/<issue番号>-<短い説明>`
+3. 開発・コミット
+4. PR を作成し、関連 Issue を参照する
+
+## コマンド
+
+```bash
+uv run ruff check src/ tests/    # リント
+uv run ruff format src/ tests/   # フォーマット
+uv run mypy src/                 # 型チェック
+uv run pytest                    # テスト
+```
+
+## コード規約
+
+- docstring・コメントは日本語
+- 公開 API には型アノテーション必須
+- PR 前にリント・型チェック・テストをすべて通すこと
+
+## 認識器の追加
+
+新しい PII 認識器の追加は歓迎します。`Recognizer` プロトコルを実装してください：
+
+```python
+class Recognizer(Protocol):
+    entity_type: str
+    def analyze(self, text: str) -> Iterable[Entity]: ...
+```
+
+テストには全角/半角バリエーション、コンテキスト語の有無、偽陽性ケースを含めてください。
+
+## ライセンス
+
+コントリビューションは Apache-2.0 ライセンスの下で提供されます。