EvoSpikeNet Python SDK

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

EvoSpikeNet Python SDK は、EvoSpikeNet分散脳シミュレーションシステムと対話するための高レベルAPIクライアントです。テキスト生成、分散脳シミュレーション、空間認知処理（Feature 13）、アーティファクト管理などの機能を、シンプルなPythonコードで利用できます。

最終更新日: 2026-02-19 🎯 Feature 13 + ゲノム管理SDK追加

🚀 クイックスタート

インストール

pip install -e .

基本的な使用例

<!-- from evospikenet.sdk import EvoSpikeNetAPIClient -->

# クライアント初期化
client = EvoSpikeNetAPIClient()

# テキスト生成
result = client.generate("人工知能とは何ですか？")
print(result['generated_text'])

# 分散脳シミュレーション
response = client.submit_prompt(prompt="脳の学習メカニズムを説明してください")
result = client.poll_for_result(timeout=60)
if result:
    print(result.get('response', 'No response'))

✨ 特徴

コア機能

🔄 テキスト生成: 高品質なテキスト生成
🧠 分散脳シミュレーション: マルチモーダルクエリ処理
📦 アーティファクト管理: モデル・ログ・設定の管理
📊 監視: リアルタイム統計とヘルスチェック
🧬 進化/ゲノム管理: ゲノム一覧・編集・適用（/api/evolution/genomes）

高度な機能

💾 スナップショット管理: システム状態の保存・復元
📈 スケーラビリティテスト: パフォーマンス評価
🌐 Zenoh通信: 非同期分散通信
🎯 AEG-Comm通信最適化: インテリジェント通信ゲーティング（85-93%削減）
⚖️ コンセンサス: 分散決定システム
分散coordinator: Zenoh DDS + Raftコンセンサスによる分散処理（組み込みタスク: federated_learning=平均集約, distributed_inference=即時完了, model_aggregation=weights平均。ノード発見はZenoh経由で古いハートビートをクリーンアップ）
�🛡️ 高可用性: 自動フェイルオーバーと監視
🔧 ハードウェア最適化: モデル最適化とベンチマーク

開発者体験

🔒 型安全: 完全な型ヒント
⚡ 非同期対応: async/awaitサポート
📚 Jupyter統合: ノートブック環境でのリッチ表示
🧪 包括的なテスト: 95%以上のカバレッジ
📖 詳細ドキュメント: チュートリアルとAPIリファレンス

📦 インストール

システム要件

Python 3.8+
4GB RAM（推奨8GB+）
インターネット接続（APIサーバーアクセス用）

基本インストール

# プロジェクトルートから
pip install -e .

オプション機能のインストール

# Jupyter Notebook統合
pip install -e ".[jupyter]"

# 非同期処理
pip install -e ".[async]"

# WebSocket通信
pip install -e ".[websocket]"

# 全てのオプション
pip install -e ".[all]"

Dockerを使用したインストール

# Dockerイメージビルド
docker build -t evospikenet-sdk .

# コンテナ実行
docker run -it evospikenet-sdk

🎯 使用方法

初期化

<!-- TODO: update or remove - import faileNetAPIClient -->

# 基本設定
client = EvoSpikeNetAPIClient()

# カスタム設定
client = EvoSpikeNetAPIClient(
    base_url="http://localhost:8000",
    api_key="your-api-key",
    timeout=120
)

テキスト生成

# シンプル生成
result = client.generate("機械学習について説明してください")
print(result['generated_text'])

# バッチ生成
prompts = ["AIの未来", "量子コンピューティング", "脳科学"]
results = client.batch_generate(prompts, max_length=100)

分散脳シミュレーション

# テキストクエリ
response = client.submit_prompt(prompt="記憶のメカニズムを説明してください")
result = client.poll_for_result(timeout=120)

# マルチモーダル（画像+テキスト）
response = client.submit_prompt(
    prompt="この画像を分析してください",
    image_path="./brain_scan.jpg"
)

# シミュレーション状態監視
status = client.get_simulation_status()
print(f"Active nodes: {status['active_nodes']}")

### ゲノム管理（保存・適用）

```python
genomes = client.list_genomes()
target = genomes[0]["name"]
genome = client.get_genome(target)
genome.setdefault("metadata", {})["note"] = "edited via SDK"
client.save_genome(target, genome, make_active=True)
client.apply_genome(target)

サンプル: examples/genome_management_sdk.py

### アーティファクト管理

```python
# セッション作成
session = client.create_log_session("実験セッション")

# モデルアップロード
with open('model.pkl', 'rb') as f:
    client.upload_artifact(
        session_id=session['session_id'],
        artifact_type="model",
        name="trained_model",
        file=io.BytesIO(f.read())
    )

# アーティファクト一覧
artifacts = client.list_artifacts(artifact_type="model")

# ダウンロード
client.download_artifact(artifact_id, "downloaded_model.pkl")

高度な機能

# スナップショット作成
snapshot = client.create_snapshot("backup_2026", include_models=True)

# スケーラビリティテスト
test_result = client.run_scalability_test(max_nodes=50)

# Zenoh通信
client.connect_zenoh(node_id="my_client")
client.publish_zenoh_message("topic/test", {"data": "hello"})

# コンセンサス
proposal = client.propose_consensus_decision(
    "resource_allocation",
    {"gpu": 2, "hours": 1}
)

📚 APIリファレンス

詳細なAPI仕様については、以下のドキュメントを参照してください：

APIリファレンス: 完全なメソッド仕様
チュートリアル: ステップバイステップガイド
インストールガイド: 詳細なセットアップ手順
開発者ガイド: 拡張と開発情報

主要クラス

クラス	説明
`EvoSpikeNetAPIClient`	メインAPIクライアント
`JupyterAPIClient`	Jupyter Notebook統合クライアント
`WebSocketClient`	リアルタイム通信クライアント

主要メソッド

基本操作

generate(prompt, max_length) - テキスト生成
submit_prompt(prompt, image_path, audio_path) - マルチモーダルクエリ
get_simulation_status() - シミュレーション状態取得
poll_for_result(timeout) - 結果ポーリング

アーティファクト管理

upload_artifact(session_id, artifact_type, name, file) - アップロード
list_artifacts(artifact_type) - 一覧取得
download_artifact(artifact_id, path) - ダウンロード

高度な機能

create_snapshot(name, include_models) - スナップショット作成
run_scalability_test(max_nodes) - スケーラビリティテスト
connect_zenoh(node_id) - Zenoh接続
propose_consensus_decision(type, payload) - コンセンサス提案

💡 サンプルコード

SDKには豊富なサンプルコードが含まれています：

基本サンプル

sdk_quickstart.py - クイックスタート
simple_generation.py - 基本的なテキスト生成
multimodal_generation.py - マルチモーダル処理
run_simulation_query.py - シミュレーション実行

🎯 Feature 13 - 空間認知処理サンプル

空間認知システムの実装例（Rank 12-15 空間処理ノード）

spatial_processing_example.py ⭐ NEW
特徴: テキスト、マルチモーダル、バッチ処理、状態監視
実装例:
- テキストプロンプト→ 空間分析（位置、深度、物体認識）
- 画像分析→ Rank 12-15 活性化
- バッチ生成→ 複数クエリの並列処理
- ヘルスチェック→ システム状態確認
実行方法: python examples/spatial_processing_example.py
async_spatial_processing_example.py ⭐ NEW
特徴: 非同期処理、並行実行、レート制限、エラーハンドリング
実装例:
- 同時実行タスク（複数プロンプト同時処理）
- レート制限付き送信（スループット管理）
- 非同期ヘルスチェック
- エラーシナリオ処理
実行方法: python examples/async_spatial_processing_example.py
メリット:
- 高スループット処理（複数リクエスト同時実行）
- リソース効率的（I/O待機中に処理継続）
- 分散システム向け（スケーリング対応）

高度なサンプル

advanced_features_demo.py - 高度な機能デモ
aeg_comm_demo.py - AEG-Comm通信最適化デモ
async_operations_demo.py - 非同期処理
batch_generation.py - バッチ処理
error_handling_example.py - エラーハンドリング

Jupyterサンプル

<!-- モジュール 'evospikenet' が見つかりません。パッケージ内の移動/名前変更を確認してください -->
<!-IClient()
client.set_display_mode("html")

# リッチ表示で結果確認
client.show_server_info()
client.show_stats()

🛠️ 開発者ガイド

SDKの拡張や開発については、開発者ガイドを参照してください。

開発環境セットアップ

# 開発依存関係インストール
pip install -e ".[dev]"

# テスト実行
pytest

# カバレッジレポート
pytest --cov=evospikenet --cov-report=html

# コード品質チェック
black evospikenet/
isort evospikenet/
mypy evospikenet/
flake8 evospikenet/

貢献の流れ

リポジトリをフォーク
機能ブランチを作成 (git checkout -b feature/amazing-feature)
変更を実装
テストを追加
コミット (git commit -m 'Add amazing feature')
プッシュ (git push origin feature/amazing-feature)
プルリクエストを作成

🧪 テスト

# 全テスト実行
pytest

# 特定のテスト実行
pytest tests/unit/test_sdk.py

# カバレッジ付き実行
pytest --cov=evospikenet --cov-report=term-missing

# 統合テスト実行
pytest tests/integration/

📊 パフォーマンス

ベンチマーク結果

応答時間: < 500ms（平均）
可用性: 99.9%+
スケーラビリティ: 1000ノード以上対応
並行処理: 同時100リクエスト対応

システム要件

最小: 4GB RAM, 2GHz CPU
推奨: 8GB RAM, 3GHz CPU
最適: 16GB RAM, マルチコアCPU

🔒 セキュリティ

APIキーによる認証
SSL/TLS暗号化
タイムアウトとリトライ制限
入力検証とサニタイズ

🤝 貢献

貢献を歓迎します！詳細は貢献ガイドを参照してください。

コーディング標準

スタイル: Black + isort
型チェック: mypy
リント: flake8
テスト: pytest（カバレッジ80%+）
ドキュメント: Googleスタイルdocstring

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルを参照してください。

📞 サポート

ドキュメント: docs/
イシュー: GitHub Issues
ディスカッション: GitHub Discussions

🙏 謝辞

EvoSpikeNetチームの皆様
オープンソースコミュニティ
貢献者の皆様

EvoSpikeNet SDK - 分散脳シミュレーションのパワーを、あなたの手元に。 /Users/maoki/Documents/GitHub/EvoSpikeNet/docs/SDK_README.md