Evo-LLM Converter Specification

Version: 1.0 Scope: EvoSpikeNet-Core (evospikenet/ namespace) Purpose: Define the design of "Evo-LLM Converter", a CLI/library tool that converts and optimizes existing Transformer-based Large Language Models (LLMs) into EvoSpikeNet's Spiking Neural Network (SNN) LLM (SpikingEvoTextLM).

This document prioritizes "correct operation" above all else, assuming only existing modules, classes, and APIs in EvoSpikeNet-Core. Unimplemented features (e.g., INT16 operations) are not used. Instead, the Converter is newly implemented as an orchestration layer that combines already implemented assets (SpikingEvoTextLM, ChronoSpikeAttention, TASEncoderDecoder, OptimizationPipeline, QPFCAdaptiveController, MetaSTDP, SNNRAGHybrid, etc.).

---

1. Scope and Prerequisites

1.1 Goals

1. Convert an input LLM (torch.nn.Module or HuggingFace checkpoint) into a SpikingEvoTextLM-compatible SNN-LLM via knowledge distillation.
2. Spike-encode token inputs via TAS-Encoding and replace Softmax attention with ChronoSpikeAttention (causal exponential decay).
3. Perform quantization, pruning, and fusion using OptimizationPipeline and export for Jetson / Edge TPU / CPU.
4. Optionally connect Q-PFC self-modulating inference, Meta-STDP continual learning, and SNN-RAG memory retrieval.
5. Verify numerical values, performance, and accuracy at each stage to determine pass/fail.

1.2 Non-Goals

• Full scratch retraining of LLMs is out of scope. Only distillation and light-weight tuning.
• INT16 integer operations are not adopted because they do not exist in the codebase (quantization is based on INT8 dynamic quantization).

1.3 Pre-existing Components (Verified)

Feature	Entity (File / Class)	Status
SNN-LLM Body	evospikenet/models.py SpikingEvoTextLM	Implemented
Causal Attention	evospikenet/attention.py ChronoSpikeAttention	Implemented（特許 MT25-EV001）
TAS Encoding	evospikenet/encoding.py TASEncoderDecoder	Implemented（特許 MT25-EV002）
Optimization Pipeline	evospikenet/optimization_pipeline.py OptimizationPipeline	Implemented
Quantization / Pruning / Fusion	evospikenet/plugins/builtin/optimization_backends/{quantization,pruning,fusion}_plugin.py	Implemented（INT8）
Knowledge Distillation	examples/distill_ann_to_snn.py、evospikenet/api_modules/training_api.py（/api/train/distillation）	Implemented
Q-PFC Self-Modulation	evospikenet/q_pfc_adaptive_control.py QPFCAdaptiveController	Implemented（特許 MT25-EV008）
Continual Learning	evospikenet/plasticity.py MetaSTDP	Implemented（特許 MT25-EV016）
SNN-RAG / Memory	evospikenet/snn_rag.py SNNRAGHybrid、evospikenet/rag_memory_integrator.py RAGMemoryIntegrator	Implemented
Plugin Base	evospikenet/plugin_factory.py, evospikenet/plugins/__init__.py	Implemented
Device Deployment	device_backends/{jetson,edgetpu,cpu}_plugin.py, universal_integration.py JetsonAdapter	Implemented（一部 stub）

---

2. Architecture Overview

Evo-LLM Converter is an orchestrator that serializes existing assets as a 5-stage pipeline.

flowchart TD
    A[Input LLM<br/>torch.nn.Module / HF ckpt] --> B[Stage 1<br/>Ingestion & Teacher Modeling]
    B --> C[Stage 2<br/>SNN-LLM Config Gen<br/>SpikingEvoTextLM]
    C --> D[Stage 3<br/>ANN→SNN Knowledge Distillation]
    D --> E[Stage 4<br/>Optimization Pipeline<br/>量子化/剪定/融合]
    E --> F[Stage 5<br/>Optional Integration +<br/>Device Export]
    F --> G[Artifact<br/>EvoLLMArtifact]

    subgraph Optional Integration
      O1[Q-PFC Self-Modulation]
      O2[Meta-STDP Continual Learning]
      O3[SNN-RAG Memory Retrieval]
    end
    F -.-> O1
    F -.-> O2
    F -.-> O3

    subgraph Validation
      V1[Distill Convergence / Perplexity]
      V2[Sparsity / Latency]
      V3[Accuracy Degradation]
    end
    D -.-> V1
    E -.-> V2
    F -.-> V3

2.1 Newly Implemented Module Structure

evospikenet/converters/llm/
├── __init__.py
├── pipeline.py          # EvoLLMConverter (Orchestrator core)
├── config.py            # EvoLLMConverterConfig (dataclass + YAML loader)
├── stages/
│   ├── ingest.py        # Stage 1: Ingestion of teacher model & tokenizer alignment
│   ├── build_snn.py     # Stage 2: SpikingEvoTextLM student model configuration
│   ├── distill.py       # Stage 3: ANN→SNN Knowledge Distillation
│   ├── optimize.py      # Stage 4: OptimizationPipeline integration
│   └── integrate.py     # Stage 5: Q-PFC/MetaSTDP/SNN-RAG + Export
├── artifact.py          # EvoLLMArtifact (Artifact + Save/Load)
├── validation.py        # 各ステージの数値・性能Validation
└── cli.py               # `evo-llm-convert` entrypoint

---

3. Detailed Stage Design

3.1 Stage 1: Ingestion & Teacher Modeling (stages/ingest.py)

Purpose: Normalize the input LLM as the "teacher" for distillation, and extract the tokenizer, vocabulary size, and dimension sizes.

• Input: torch.nn.Module or HF checkpoint path.
• Processing:
• model.eval(), requires_grad_(False) (teacher is fixed).
• Retrieve vocab_size / d_model / n_heads / layers count (from HF config or manual config.teacher_meta).
• Normalize tokenizer for sharing with the student (explicit error on mismatch, no guessing).
• Output: TeacherSpec(model, tokenizer, vocab_size, d_model, n_heads, num_layers).

3.2 Stage 2: SNN-LLM Student Configuration (stages/build_snn.py)

Purpose: Create the SNN-LLM target for distillation using existing classes.

Existing APIs:

from evospikenet.models import SpikingEvoTextLM

student = SpikingEvoTextLM(
    vocab_size=teacher.vocab_size,
    d_model=config.d_model,                 # Can be smaller than teacher (distillation)
    n_heads=config.n_heads,
    num_transformer_blocks=config.num_blocks,
    time_steps=config.time_steps,           # e.g., 10
    dropout=0.1,
    neuron_type="EvoLIF",
)

• SpikingEvoTextLM internally implements TASEncoderDecoder (input spike encoding) and SpikingTransformerBlock (attention_axis="sequence"). Therefore, TAS-Encoding injection and replacement with ChronoSpike attention are automatically achieved by instantiating this class (no manual replacement needed).
• If attention axis or tau control is required, ChronoSpikeAttention(input_dim, hidden_dim, n_heads, time_steps, learnable_tau=...) can be directly instantiated and swapped.
• Output: Untrained SpikingEvoTextLM student model.

3.3 Stage 3: ANN→SNN Knowledge Distillation（stages/distill.py）

Purpose: Transfer output probability distributions of the teacher LLM to the student SNN-LLM.

• Utilize existing assets: Reference implementation examples/distill_ann_to_snn.py and job start API POST /api/train/distillation (training_api.py, teacher_source=local|huggingface).
• Distillation Loss: Weighted sum of soft-target KL divergence (temperature T) and language modeling CE.

  loss = alpha * KL(student_logits / T, teacher_logits / T) * T**2 \
       + (1 - alpha) * CE(student_logits, labels)
  

• Input: config.distill_dataset (text corpus), teacher = TeacherSpec.model, student = SpikingEvoTextLM from Stage 2.
• Validation: 蒸留中の perplexity / KL 収束を validation.py で記録。発散時は早期停止。
• Note: Marketing values such as "50-90% reduction" or "under 1uJ" are not hard-coded; validation.py records actual measured energy, latency, and perplexity in the artifact.

3.4 Stage 4: Optimization Pipeline（stages/optimize.py）

Purpose: Apply quantization, pruning, and layer fusion for edge deployment.

Existing APIs:

from evospikenet.optimization_pipeline import OptimizationPipeline

pipeline = OptimizationPipeline.from_yaml(config.optimization_yaml)
result = pipeline.run(student, continue_on_error=False)
optimized_model = result.model

最適化 YAML（既定テンプレート）:

optimization_pipeline:
  steps:
    - type: "quantization"   # QuantizationPlugin（INT8 動的量子化, backend=fbgemm）
      config: { backend: "fbgemm" }
    - type: "pruning"        # PruningPlugin（構造的剪定）
      config: { amount: 0.3, method: "l1_unstructured" }
    - type: "fusion"         # FusionPlugin（モジュール融合）
      config: { fuse_groups: [["linear", "act"]] }

• 量子化は INT8 のみ（torch.quantization.quantize_dynamic、対象 nn.Linear）。INT16 は非対応のため設定不可。
• continue_on_error=False を既定とし、ステップ失敗時はパイプライン全体を失敗とする（部分成果物の暗黙採用を防ぐ）。

3.5 Stage 5: Option統合 + デバイスエクスポート（stages/integrate.py）

目的: 任意Featureを接続し、ターゲットデバイス向け成果物を生成する。

デバイスエクスポート（plugin_factory 経由）:

from evospikenet.plugin_factory import PluginFactory
from evospikenet.plugins import PluginType

factory = PluginFactory()
device_plugin = factory.get_plugin(PluginType.DEVICE, config.target_device)  # jetson|edgetpu|cpu
device_plugin.optimize_model(optimized_model)
device_plugin.convert_format(optimized_model, output_path)

- Jetson は JetsonAdapter（universal_integration.py）の ONNX→TensorRT 経路も選択可（一部 stub のため未対応箇所は明示警告し対応経路へフォールバック）。

---

4. 任意Feature（オプトイン）

Feature	実体	既定
Q-PFC Self-Modulation推論	QPFCAdaptiveController（q_pfc_adaptive_control.py）	無効
Continual Learning（破滅的忘却回避）	MetaSTDP（plasticity.py）	無効
オンデバイス知識参照	SNNRAGHybrid / RAGMemoryIntegrator	無効

4.1 Q-PFC Self-Modulation推論

モデル出力の認知エントロピー（不確実性）に応じて推論の深さを自律調整する。Existing APIs:

from evospikenet.q_pfc_adaptive_control import QPFCAdaptiveController

controller = QPFCAdaptiveController(device="cpu", risk_tolerance=0.5, enable_learning=True)
ctrl = controller.forward(predictions=logits, entropy=entropy, alpha_t=alpha_t)

- 推論ランタイムで出力ロジットからエントロピーを算出し、forward() の制御出力で推論ステップ数／閾値を変調する。簡単な入力は低コスト、複雑な入力は深い推論へ。

4.2 Meta-STDP Continual Learning

from evospikenet.plasticity import MetaSTDP, STDP

meta = MetaSTDP(base_stdp=STDP(...), meta_learning_rate=0.001, energy_budget=1.0)
meta.compute_weight_updates(spike_history, synapse_matrix)
meta.adapt_to_feedback(performance_feedback=..., energy_feedback=...)

- 配備後、新規ドメイン知識を追加学習しても過去知識を保持。

4.3 SNN-RAG Memory Retrieval

from evospikenet.snn_rag import SNNRAGHybrid
from evospikenet.rag_memory_integrator import RAGMemoryIntegrator

rag = RAGMemoryIntegrator.from_config(config.rag_yaml)
context = rag.enrich_query_context(query, entities=[...])

- LLM 内部知識をセマンティック／エピソード記憶へ分離し、外部参照可能な RAG としてコンパイル。

いずれも既定無効。config.options で明示有効化した場合のみ適用する（過剰な自動付与をしない）。

---

5. 設定スキーマ（config.py）

@dataclass
class EvoLLMConverterConfig:
    model_path: str
    distill_dataset: str
    output_dir: str
    # Stage 1
    teacher_meta: dict | None = None         # 自動抽出失敗時の手動指定
    # Stage 2（生徒モデル）
    d_model: int = 512
    n_heads: int = 8
    num_blocks: int = 6
    time_steps: int = 10
    # Stage 3（蒸留）
    distill_temperature: float = 2.0
    distill_alpha: float = 0.5               # KL と CE の加重
    max_steps: int = 10000
    # Stage 4
    optimization_yaml: str = "config/llm_optimization.yaml"
    # Stage 5
    target_device: str = "jetson"            # 'jetson' | 'edgetpu' | 'cpu'
    export_format: str = "onnx"              # 'onnx' | 'pt'
    # options
    enable_qpfc: bool = False
    enable_meta_stdp: bool = False
    enable_snn_rag: bool = False
    rag_yaml: str | None = None

YAML から EvoLLMConverterConfig.from_yaml(path) で読み込む。

---

6. 成果物（artifact.py）

@dataclass
class EvoLLMArtifact:
    optimized_model_path: str          # デバイス向け変換済 SNN-LLM
    student_config: dict               # SpikingEvoTextLM 構成
    distillation_report: dict          # perplexity, KL 収束, ステップ数
    options_manifest: dict             # 有効化した Q-PFC/MetaSTDP/SNN-RAG 設定
    metrics: dict                      # 実測: Sparsity, 遅延, エネルギー, Accuracy Degradation
    provenance: dict                   # 教師モデルハッシュ, ステージログ, ツールバージョン

provenance に教師モデルのハッシュと各ステージのログを記録し、再現可能性・監査性を担保する。

---

7. Validationと受け入れ基準（validation.py）

Validation項目	方法	既定しきい値
蒸留収束	Validationセット perplexity / KL の単調改善	発散 0 件
生徒前方推論	SpikingEvoTextLM.forward がコーパスで成功	例外 0 件
量子化健全性	量子化後にキャリブレーションセットで推論成功	例外 0 件
Sparsity	剪定後の非ゼロ重み比率	設定 amount ±5%
Accuracy Degradation	教師 vs 生徒のタスク指標差	≤ 設定許容（既定 5%）
Option整合	有効化Featureのフック接続が成功	接続失敗 0 件

すべての必須Validationを満たした場合のみ EvoLLMArtifact を「合格」とマークする。1 つでも失敗した場合は成果物を保存しつつ非合格として明示する（暗黙の成功扱いをしない）。

---

8. CLI（cli.py）

evo-llm-convert \
  --config config/evo_llm_convert.yaml \
  --model-path ./checkpoints/my_llm \
  --target-device jetson \
  --output-dir ./out/evo_llm

主要サブコマンド: - convert: フルパイプライン実行。 - validate: 既存成果物に対して validation.py のValidationのみ再実行。 - inspect: 教師モデルのメタ情報（語彙・次元・層数）を出力し、teacher_meta 作成を支援。

---

9. 実装フェーズ計画

フェーズ	内容	主要成果
P1	骨組み + Stage 1/2（取り込み・生徒構成）+ CLI 雛形	SpikingEvoTextLM 生徒の生成
P2	Stage 3（Knowledge Distillation）+ 収束Validation	蒸留済 SNN-LLM
P3	Stage 4/5（最適化・デバイスエクスポート）	Jetson/EdgeTPU 出力
P4	Option統合（Q-PFC / MetaSTDP / SNN-RAG）	自己変調・Continual Learning・RAG 接続
P5	E2E Validation・受け入れ基準・ドキュメント整備	合否判定付き成果物生成

---

10. リスクと対策

リスク	対策
教師トークナイザと生徒の不一致	Stage 1 で整合Validationし、不一致は明示エラー（推測で続行しない）。
INT16 等の非実在Featureへの依存	量子化は INT8 のみに限定し、設定スキーマで INT16 を受け付けない。
Jetson/EdgeTPU 変換の一部が stub	未対応経路は実行時に明示警告し、対応済経路（INT8 / ONNX）へフォールバック。
蒸留のAccuracy Degradation	受け入れ基準（Accuracy Degradation ≤ 5%）で自動ゲート。未達時は非合格マーク。
蒸留の発散	perplexity/KL を監視し早期停止、ハイパラ調整を促す。
snntorch 不在環境	models.py / attention.py の identity フォールバックを活用し最小Featureで動作継続。

---

付録 A: 参照実装マップ（実在 API）

用途	import
SNN-LLM	from evospikenet.models import SpikingEvoTextLM
Causal Attention	from evospikenet.attention import ChronoSpikeAttention
TAS	from evospikenet.encoding import TASEncoderDecoder
最適化	from evospikenet.optimization_pipeline import OptimizationPipeline
蒸留	examples/distill_ann_to_snn.py、POST /api/train/distillation（training_api.py）
Q-PFC	from evospikenet.q_pfc_adaptive_control import QPFCAdaptiveController
Continual Learning	from evospikenet.plasticity import MetaSTDP, STDP
RAG / 記憶	from evospikenet.snn_rag import SNNRAGHybrid; from evospikenet.rag_memory_integrator import RAGMemoryIntegrator
プラグイン	from evospikenet.plugin_factory import PluginFactory; from evospikenet.plugins import PluginType