Skip to content

Dependency architecture improvement report

[!NOTE] For the latest implementation status, please refer to Functional Implementation Status (Remaining Functionality).

overview

We analyzed the dependencies of EvoSpikeNet and introduced an interface layer to improve maintainability and testability.

Implementation details

1. Visualization of dependencies

Tools

  • pydeps: Python package dependency visualization tool
  • Custom analysis script: scripts/analyze_dependencies.py

Analysis results```json

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

#### Modules with many dependencies (Top 10)
1. **evospikenet.models** - Depends on 9
   - Depends on: memory_manager, audio, transformer, vision, text, encoding, core, attention, tensor_cache

2. **evospikenet.services** - 6 dependent

3. **evospikenet.rag_milvus** - 5 dependent
   - Depends on: elasticsearch_client, rag_backends, encoding, models, insight

4. **evospikenet.model_selector** - 3 dependent

5. **evospikenet.plugins.builtin** - 3 dependencies

#### Key findings
- ✅ **No circular dependencies**: Current architecture is healthy
- ⚠️ **Highly coupled module**: `models.py` depends on 9 modules (refactoring recommended)
- ⚠️ **Implicit interface**: Missing Protocol or base class

### 2. Introduction of interface layer

Create a new `evospikenet/base/` package and define the following:

#### 2.1 Protocol definition (`base/protocols.py`)

Ensure type safety while supporting Duck Typing:

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

2.2 Abstract base classes (base/base_classes.py)

Base class that concrete classes should inherit from:

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

Each base class has: - Common initialization logic - Default implementation (optional) - State management methods (reset_state, etc.)

2.3 Type definition (base/types.py)

Type hints and aliases:

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

3. Detection and prevention of circular dependencies

Current situation

  • ✅ 0 circular dependencies detected
  • In the existing code, there are some parts that are avoided by lazy import (intra-function import)

Precautions

  1. Clarification of layer architectureevospikenet/ ├── base/ # Bottom layer (no dependencies) ├── core/ # Core functionality (depends only on base) ├── models/ # Model implementation (depends on base, core) └── services/ # High level service (can depend on everything)

  2. Dependency direction constraints

  3. Upper layer → Only lower layer allowed
  4. Prohibition of circular dependence within the same layer

  5. Loose coupling via interfaces

  6. Continuous Monitoring

  7. Recommended to add dependency check to CI pipeline
  8. Circular dependency detection with pre-commit hook

Benefits of improved architecture

1. Improved maintainability

  • Easy to change implementation due to clear interface definition
  • Decreased coupling between modules

2. Improved testability

  • Easy mock creation using Protocol
  • Dependency injection (DI) pattern can be applied

3. Improved scalability

  • Easy to add new neuron models and encoders
  • Highly compatible with plugin architecture

4. Improved type safety

  • Improved accuracy of static type checking with mypy
  • Improved IDE completion and refactoring assistance

Next steps

  1. Refactoring existing code
  2. Migrate core.py, models.py, etc. to base class inheritance

  3. Replace lazy imports with interface dependencies

  4. Integration into CI/CD```yaml # Add to .github/workflows/ci.yml

  5. name: Check circular dependencies run: python scripts/analyze_dependencies.py ```

  6. Document update

  7. Added architecture diagram
  8. Creation of interface usage guide

Mid-term

  1. Introducing dependency injection container

  2. Consideration of python-dependency-injector etc.

  3. Enhanced layer separation

  4. Subpackaging of evospikenet/core/, evospikenet/models/

  5. Interface compliance verification

  6. Create test helper for pytest

Long term

  1. Consideration of microservices

  2. Clarification of service boundaries

  3. Type system extension

  4. Utilization of Generics/TypeVar

Generated file

  • evospikenet/base/__init__.py - Package initialization
  • evospikenet/base/protocols.py - Protocol definition
  • evospikenet/base/base_classes.py - Abstract base classes
  • evospikenet/base/types.py - Type definition
  • scripts/analyze_dependencies.py - Dependency analysis script
  • artifacts/dependency_analysis.json - Analysis results (JSON)
  • artifacts/dependencies.dot - Dependency graph (Graphviz)

Execute command

Dependency analysis```bash

python scripts/analyze_dependencies.py 

### Graphviz visualization (requires graphviz installation)```bash
dot -Tpng artifacts/dependencies.dot -o artifacts/dependencies.png

Visualization with pydeps (requires graphviz installation)```bash

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

Creation date: January 10, 2026