コンテンツにスキップ

依存関係アーキテクチャ改善レポート

[!NOTE] 最新の実装状況は 機能実装ステータス (Remaining Functionality) を参照してください。

概要

EvoSpikeNetの依存関係を分析し、インターフェース層を導入して保守性とテスタビリティを向上させました。

実施内容

1. 依存関係の可視化

ツール

  • pydeps: Pythonパッケージの依存関係可視化ツール
  • カスタム分析スクリプト: scripts/analyze_dependencies.py

分析結果

{
  "total_modules": 53,
  "total_dependencies": 80,
  "average_dependencies_per_module": 1.51,
  "circular_dependencies_count": 0
}

依存関係が多いモジュール（Top 10）

  1. evospikenet.models - 9依存

  2. 依存先: memory_manager, audio, transformer, vision, text, encoding, core, attention, tensor_cache

  3. evospikenet.services - 6依存

  4. evospikenet.rag_milvus - 5依存

  5. 依存先: elasticsearch_client, rag_backends, encoding, models, insight

  6. evospikenet.model_selector - 3依存

  7. evospikenet.plugins.builtin - 3依存

主要な発見

  • ✅ 循環依存なし: 現在のアーキテクチャは健全
  • ⚠️ 高結合モジュール: models.pyが9つのモジュールに依存（リファクタリング推奨）
  • ⚠️ 暗黙的インターフェース: Protocolやベースクラスが不足

2. インターフェース層の導入

新しいevospikenet/base/パッケージを作成し、以下を定義：

2.1 Protocolの定義 (base/protocols.py)

Duck Typingをサポートしつつ型安全性を確保：

- NeuronLayerProtocol: ニューロン層の基本インターフェース
- EncoderProtocol: エンコーダーのインターフェース
- PlasticityProtocol: 可塑性メカニズムのインターフェース
- AttentionProtocol: アテンション機構のインターフェース
- TransformerProtocol: Transformerブロックのインターフェース
- ModelProtocol: モデル全体のインターフェース
- CommunicatorProtocol: 分散通信のインターフェース
- MemoryManagerProtocol: メモリ管理のインターフェース

2.2 抽象基底クラス (base/base_classes.py)

具象クラスが継承すべきベースクラス：

- BaseNeuronLayer: ニューロン層の抽象基底クラス
- BaseEncoder: エンコーダーの抽象基底クラス
- BasePlasticity: 可塑性メカニズムの抽象基底クラス
- BaseAttention: アテンション機構の抽象基底クラス
- BaseTransformer: Transformerブロックの抽象基底クラス
- BaseModel: モデル全体の抽象基底クラス
- BaseCommunicator: 分散通信の抽象基底クラス
- BaseMemoryManager: メモリ管理の抽象基底クラス

各ベースクラスには： - 共通の初期化ロジック - デフォルト実装（オプション） - 状態管理メソッド（reset_state等）

2.3 型定義 (base/types.py)

型ヒントとエイリアス：

- SpikeTensor: スパイク列テンソル
- WeightTensor: 重み行列テンソル
- ConfigDict: 設定辞書
- MetricsDict: メトリクス辞書
- NodeID: ノード識別子（NewType）
- TaskID: タスク識別子（NewType）
- ModelID: モデル識別子（NewType）

3. 循環依存の検出と予防

現状

  • ✅ 循環依存は0件検出
  • 既存コードでは遅延インポート（関数内import）で回避している箇所あり

予防策

  1. レイヤーアーキテクチャの明確化 

    evospikenet/
├── base/          # 最下層（依存なし）
├── core/          # コア機能（baseのみに依存）
├── models/        # モデル実装（base, coreに依存）
└── services/      # 高レベルサービス（全てに依存可）

  2. 依存方向の制約

  3. 上位層 → 下位層のみ許可
  4. 同一層内の循環依存禁止

  5. インターフェース経由の疎結合

  6. 継続的監視

  7. CIパイプラインに依存関係チェックを追加推奨
  8. pre-commitフックで循環依存検出

アーキテクチャ改善の利点

1. 保守性の向上

  • 明確なインターフェース定義により、実装の変更が容易
  • モジュール間の結合度が低下

2. テスタビリティの向上

  • Protocolを使用したモック作成が容易
  • 依存性注入（DI）パターンの適用が可能

3. 拡張性の向上

  • 新しいニューロンモデルやエンコーダーの追加が容易
  • プラグインアーキテクチャとの親和性が高い

4. 型安全性の向上

  • mypyによる静的型チェックの精度向上
  • IDEの補完とリファクタリング支援の改善

次のステップ

短期（推奨）

  1. 既存コードのリファクタリング
  2. core.py, models.py等をベースクラス継承に移行

  3. 遅延インポートをインターフェース依存に置き換え

  4. CI/CDへの統合 

    # .github/workflows/ci.yml に追加
- name: Check circular dependencies
  run: python scripts/analyze_dependencies.py

  5. ドキュメント更新

  6. アーキテクチャ図の追加
  7. インターフェース使用ガイドの作成

中期

  1. 依存性注入コンテナの導入

  2. python-dependency-injector等の検討

  3. レイヤー分離の強化

  4. evospikenet/core/, evospikenet/models/のサブパッケージ化

  5. インターフェース準拠の検証

  6. pytest用のテストヘルパー作成

長期

  1. マイクロサービス化の検討

  2. サービス境界の明確化

  3. 型システムの拡張

  4. Generics/TypeVarの活用

生成ファイル

  • evospikenet/base/__init__.py - パッケージ初期化
  • evospikenet/base/protocols.py - Protocol定義
  • evospikenet/base/base_classes.py - 抽象基底クラス
  • evospikenet/base/types.py - 型定義
  • scripts/analyze_dependencies.py - 依存関係分析スクリプト
  • artifacts/dependency_analysis.json - 分析結果（JSON）
  • artifacts/dependencies.dot - 依存関係グラフ（Graphviz）

実行コマンド

依存関係分析

python scripts/analyze_dependencies.py

Graphviz可視化（要graphvizインストール）

dot -Tpng artifacts/dependencies.dot -o artifacts/dependencies.png

pydepsによる可視化（要graphvizインストール）

pydeps evospikenet --max-bacon=2 --cluster --noshow -o artifacts/pydeps_graph.png

作成日: 2026年1月10日