CR-NEXUS-051 Implementation Plan

Spec: docs/spec/CR-NEXUS-051_ERROR_CLASSIFICATION_SPECIFICATION.md (v1.1.1) Status: Phase 3 Approve（実装フェーズ移行可能） Created: 2025-01-06

1. 実装対象ファイルの責務

1.1 src/nexuscore/core/errors.py

責務:

  • 例外階層の定義（NexusCoreError とそのサブクラス）
  • classify_error() 関数の実装（エラー分類ロジック）
  • convert_http_error_to_nexus_error() 関数の実装（例外変換）
  • 分類不能エラー時のフォールバック処理（3.4.2 Step 1-4）

依存関係:

  • retry_utils.py に依存しない（循環禁止）
  • 標準ライブラリのみ使用（logging, typing）

実装要件:

  • 分類処理中の例外を捕捉し、"unexpected" として扱う（3.4.3）
  • すべての入力に対して少なくとも "unexpected" を返すことを保証（3.4.3）
  • 分類結果をログに記録（5.3 AU-1）

1.2 src/nexuscore/core/retry_utils.py

責務:

  • リトライ可否の判定（3.3.1）
  • リトライの有限性保証（3.3.2 SHALL要件）
  • Backoff 戦略の適用（3.3.3 意味論レベル）
  • Unexpected エラーのリトライ禁止（3.3.4）
  • 分類不能エラー時のフォールバックフック（3.4.2）

依存関係:

  • errors.py の classify_error() を使用（一方向依存）
  • 設定値は外部から注入可能にする（固定値禁止）

実装要件:

  • 最大リトライ回数の上限を設定可能にする
  • Backoff 戦略は意味論レベルで実装（増加型/一定/待機なし）
  • unexpected カテゴリのエラーはリトライしない
  • 設定値（最大回数、待機時間、指数係数等）は外部注入を前提

2. 依存方向 

errors.py
  ↓ (classify_error を使用)
retry_utils.py

循環依存の禁止:

  • errors.py は retry_utils.py を import しない
  • retry_utils.py は errors.py の classify_error() のみ使用

3. 設定値の置き場所

3.1 設定値の分類

エラー分類関連（errors.py）:

  • ログレベル設定（INFO/WARNING）
  • 分類不能エラー時のログ設定

リトライ関連（retry_utils.py）:

  • 最大リトライ回数（エラー種別ごと）
  • Backoff 戦略のパラメータ（増加型の係数、一定間隔の値等）
  • エラー種別ごとの推奨戦略マッピング

3.2 設定値の注入方法

方針: 設定値は関数/クラスのパラメータとして注入可能にする

errors.py:

  • classify_error() は設定不要（純粋関数）
  • ログ設定はモジュールレベルの logger を使用（既存の仕組みを利用）

retry_utils.py:

  • retry_with_context() 関数のパラメータとして設定値を注入
  • デフォルト値は提供するが、外部から上書き可能
  • エラー種別ごとの設定は RetryConfig クラスまたは dict で管理

3.3 設定値のデフォルト

注意: Spec では具体的な数値は定義されていないため、実装時に適切なデフォルト値を設定する。

推奨デフォルト（実装時の参考）:

  • 最大リトライ回数: 3回（エラー種別ごとに設定可能）
  • 増加型待機戦略の初期待機時間: 1.0秒（エラー種別ごとに設定可能）
  • 増加型待機戦略の係数: 2.0（指数バックオフの底、設定可能）

重要: これらのデフォルト値は Spec の一部ではなく、実装詳細である。

4. 実装差分分析

4.1 errors.py の既存実装との差分

既存実装の状態:

  • ✅ 例外階層は定義済み
  • ✅ classify_error() は基本的に実装済み
  • ✅ convert_http_error_to_nexus_error() は実装済み

追加・修正が必要な箇所:

  1. 分類不能エラー時のフォールバック処理（3.4.2）:
    • Step 1: 安全な分類結果の返却（既に "unexpected" を返しているが、明示的に処理を追加）
    • Step 2: エラーログの記録（warning レベル、分類失敗の理由を含める）
    • Step 3: 上位へのエラー伝播（UnexpectedSystemError として伝播、既に実装済み）
    • Step 4: 監視・アラート（ログに記録、監視機構へのフック）
  2. 分類処理中の例外捕捉（3.4.3）:
    • classify_error() 内で例外が発生した場合、"unexpected" を返す
    • 入力検証（None チェック等）
  3. ログ記録の強化（5.3 AU-1）:
    • 分類結果を logger.info() で記録
    • 誤分類の疑いがある場合は logger.warning() で警告

4.2 retry_utils.py の既存実装との差分

既存実装の状態:

  • ✅ retry_with_context() は実装済み
  • ✅ 指数バックオフは実装済み（固定実装）
  • ⚠️ リトライ可否の判定は部分的に実装（invalid_output が含まれていない）
  • ⚠️ unexpected エラーのリトライ禁止が明示されていない
  • ⚠️ Backoff 戦略が固定実装（意味論レベルでの抽象化が必要）

追加・修正が必要な箇所:

  1. リトライ可否の判定ルール（3.3.1）:
    • invalid_output をリトライ可能に追加
    • unexpected をリトライ不可として明示的に禁止
  2. リトライの有限性保証（3.3.2）:
    • 既に max_retries で制御されているが、SHALL 要件として明示
    • 無限リトライループの可能性を完全に排除
  3. Backoff 戦略の抽象化（3.3.3）:
    • 増加型待機戦略（長/中/短）
    • 一定待機戦略
    • 待機なし再試行
    • エラー種別ごとの戦略マッピングを設定可能にする
  4. Unexpected エラーのリトライ禁止（3.3.4）:
    • unexpected カテゴリのエラーは即座にリトライを停止
  5. 分類不能エラー時のフォールバックフック（3.4.2）:
    • 分類不能エラーが発生した場合の処理フローを追加

5. テスト設計

5.1 テストファイル構成

ファイル: tests/core/test_errors.py

テストカテゴリ:

  1. カスタム例外の分類（8テスト）
  2. メッセージベースの分類（13テスト）
  3. 型名ベースの分類（2テスト）
  4. フォールバック（3テスト）
  5. 変換関数テスト（9テスト）
  6. 例外階層テスト（3テスト）
  7. エッジケーステスト（6テスト）
  8. 新規: 分類不能エラー時のフォールバック（3テスト）
  9. 新規: リトライ可否判定（7テスト）
  10. 新規: Backoff 戦略（6テスト）
  11. 新規: Unexpected エラーのリトライ禁止（3テスト）

合計: 45テスト（Spec 要件）+ 新規19テスト = 64テスト

5.2 テスト設計のポイント

分類不能エラーのテスト:

  • classify_error() が例外を発生させた場合
  • エラーオブジェクトが None の場合
  • 不正な形式のエラーオブジェクトの場合

リトライ可否判定のテスト:

  • 各エラー種別のリトライ可否を確認
  • unexpected は必ずリトライ不可

Backoff 戦略のテスト:

  • 増加型待機戦略（長/中/短）の動作確認
  • 一定待機戦略の動作確認
  • 待機なし再試行の動作確認
  • エラー種別ごとの戦略マッピング確認

6. 実装手順

Step 1: errors.py の拡張

  1. 分類不能エラー時のフォールバック処理を追加（3.4.2）
  2. 分類処理中の例外捕捉を追加（3.4.3）
  3. ログ記録の強化（5.3 AU-1）

Step 2: retry_utils.py の拡張

  1. リトライ可否判定ルールの修正（3.3.1）
  2. Backoff 戦略の抽象化（3.3.3）
  3. Unexpected エラーのリトライ禁止（3.3.4）
  4. 設定値の注入可能化

Step 3: テストの実装

  1. 既存テストの確認・修正
  2. 新規テストの追加（分類不能、リトライ可否、Backoff 戦略）

Step 4: 統合テスト

  1. LLM API呼び出し → エラー発生 → 分類 → リトライのワークフロー確認

7. 実装時の注意事項

7.1 後方互換性

  • 既存の retry_with_context() のシグネチャは維持
  • 既存の呼び出し元が動作することを確認

7.2 パフォーマンス要件

  • 分類処理は1ms以内（5.1 PR-1）
  • 文字列マッチングは in 演算子を使用（5.1 PR-2）

7.3 拡張性

  • 新しいエラーカテゴリの追加は10行以内（5.2 EX-1）
  • 設定値の注入により、将来の拡張に対応

8. 完了条件

  • errors.py が Spec v1.1.1 の要件を満たす
  • retry_utils.py が Spec v1.1.1 の要件を満たす
  • テストが45ケース以上（Spec 要件）+ 新規テストを実装
  • テストカバレッジが98%以上
  • 後方互換性が維持されている
  • パフォーマンス要件を満たす
  • 設定値が外部注入可能になっている

9. 関連ドキュメント

  • Spec: docs/spec/CR-NEXUS-051_ERROR_CLASSIFICATION_SPECIFICATION.md (v1.1.1)
  • Phase 3 Review: ガバナンス/review_packets/RP-NEXUS-051_PHASE25_INDEPENDENT_REVIEW_v2.md
  • Decision Log: 判断ログ/判断ログ.md
This site uses Just the Docs, a documentation theme for Jekyll.