DeepSpec: a full-stack codebase for training and evaluating speculative decoding algorithms
This report summarizes scanner evidence for deepseek-ai/DeepSpec, a Python project with 7,204 GitHub stars. SynthScan examined 11,816 lines of code across 76 source files, recording 185 pattern matches distributed across 9 syntactic categories. The legacy adjusted pattern signal is 16.0 (Elevated pattern signal); it is not an authorship estimate.
Use the findings to ask whether maintainers can explain intent, verify dependencies, simplify unnecessary scaffolding, and focus review effort. Risk Payload v1 adds ownership, supply-chain, over-engineering, and review-effort vectors when available. These are prompts for human verification, not probabilities, security findings, or measured maintenance costs.
Use each vector to guide manual verification of the underlying findings.
Can maintainers explain intent, assumptions, and trade-offs? 71 finding(s).
Are imports declared and package/API names verified? 78 finding(s).
Are wrappers, guards, and repeated structures necessary? 95 finding(s).
Which changes need focused human review? 185 finding(s).
This chart tracks the legacy adjusted pattern score across scan runs. Changes can reflect source changes, scan coverage, or detector/scoring versions; they do not measure AI adoption or prove that a team refactored code. Compare runs only when their scoring versions are compatible. The dashed line tracks the raw pattern-hit count.
Groups findings by configured severity weight. Severity is not a confidence estimate, security rating, or proof that a package is missing. Verify imports against the project's manifests and inspect each finding in its local design context.
This horizontal bar chart shows where configured pattern scores accumulate across directories. Treat the bars as locations to inspect, not as evidence of authorship or code quality. Use the file-level findings to decide whether a directory needs a focused ownership, dependency, complexity, or review check.
The scanner identified 185 distinct pattern matches across 9 syntactic categories. Each entry below represents a discrete location in the source code where the engine recorded a detector match to inspect in context. Expand any category row to inspect the individual file paths, line numbers, code snippets, and the lexical context (CODE, COMMENT, or STRING) in which each match was detected.
Reading the findings table: The Severity column indicates the configured finding weight (CRITICAL / HIGH / MEDIUM / LOW). The Context column identifies whether the match occurred inside executable code, an inline comment, or a string literal — legacy comment-context matches receive a ×1.5 score weight. The ⚡ bolt icon marks clustered matches: three or more patterns within a 10-line window, each receiving an additional ×1.5 density multiplier under the legacy scoring model.
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| LOW | eval.py | 1 | CODE | |
| LOW | deepspec/utils/__init__.py | 6 | CODE | |
| LOW | deepspec/utils/__init__.py | 6 | CODE | |
| LOW | deepspec/utils/__init__.py | 6 | CODE | |
| LOW | deepspec/utils/__init__.py | 6 | CODE | |
| LOW | deepspec/utils/__init__.py | 7 | CODE | |
| LOW | deepspec/utils/__init__.py | 7 | CODE | |
| LOW | deepspec/utils/__init__.py | 7 | CODE | |
| LOW | deepspec/utils/__init__.py | 7 | CODE | |
| LOW | deepspec/utils/__init__.py | 7 | CODE | |
| LOW | deepspec/utils/__init__.py | 7 | CODE | |
| LOW | deepspec/utils/__init__.py | 7 | CODE | |
| LOW | deepspec/utils/__init__.py | 16 | CODE | |
| LOW | deepspec/utils/__init__.py | 16 | CODE | |
| LOW | deepspec/utils/__init__.py | 17 | CODE | |
| LOW | deepspec/utils/__init__.py | 17 | CODE | |
| LOW | deepspec/utils/__init__.py | 17 | CODE | |
| LOW | deepspec/utils/__init__.py | 18 | CODE | |
| LOW | deepspec/utils/sampling.py | 1 | CODE | |
| LOW | deepspec/utils/constant/__init__.py | 2 | CODE | |
| LOW | deepspec/utils/constant/__init__.py | 3 | CODE | |
| LOW | deepspec/utils/constant/__init__.py | 5 | CODE | |
| LOW | deepspec/modeling/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/__init__.py | 6 | CODE | |
| LOW | deepspec/modeling/__init__.py | 6 | CODE | |
| LOW | deepspec/modeling/eagle3/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/eagle3/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/eagle3/__init__.py | 2 | CODE | |
| LOW | deepspec/modeling/eagle3/__init__.py | 3 | CODE | |
| LOW | deepspec/modeling/eagle3/common.py | 1 | CODE | |
| LOW | deepspec/modeling/eagle3/gemma4/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/eagle3/gemma4/__init__.py | 2 | CODE | |
| LOW | deepspec/modeling/eagle3/gemma4/modeling.py | 1 | CODE | |
| LOW | deepspec/modeling/eagle3/qwen3/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/eagle3/qwen3/__init__.py | 2 | CODE | |
| LOW | deepspec/modeling/eagle3/qwen3/modeling.py | 1 | CODE | |
| LOW | deepspec/modeling/dspark/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/dspark/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/dspark/__init__.py | 2 | CODE | |
| LOW | deepspec/modeling/dspark/__init__.py | 3 | CODE | |
| LOW | deepspec/modeling/dspark/gemma4/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/dspark/gemma4/__init__.py | 2 | CODE | |
| LOW | deepspec/modeling/dspark/qwen3/__init__.py | 1 | CODE | |
| LOW | deepspec/modeling/dspark/qwen3/__init__.py | 2 | CODE | |
| LOW | deepspec/eval/base_evaluator.py | 1 | CODE | |
| LOW | deepspec/eval/__init__.py | 1 | CODE | |
| LOW | deepspec/eval/__init__.py | 1 | CODE | |
| LOW | deepspec/eval/__init__.py | 1 | CODE | |
| LOW | deepspec/eval/__init__.py | 2 | CODE | |
| LOW | deepspec/eval/__init__.py | 2 | CODE | |
| LOW | deepspec/eval/__init__.py | 3 | CODE | |
| LOW | deepspec/eval/__init__.py | 3 | CODE | |
| LOW | deepspec/eval/eagle3/__init__.py | 1 | CODE | |
| LOW | deepspec/eval/eagle3/__init__.py | 1 | CODE | |
| LOW | deepspec/eval/eagle3/evaluator.py | 1 | CODE | |
| LOW | deepspec/eval/dspark/__init__.py | 1 | CODE | |
| LOW | deepspec/eval/dspark/__init__.py | 1 | CODE | |
| LOW | deepspec/eval/dspark/__init__.py | 2 | CODE | |
| 18 more matches not shown… | ||||
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| LOW | deepspec/utils/metrics.py | 72 | def _assert_schema_consistent(): | CODE |
| LOW | deepspec/modeling/eagle3/loss.py | 57 | def _compute_loss_normalizers( | CODE |
| LOW | deepspec/modeling/eagle3/loss.py | 77 | def _build_next_token_position_mask( | CODE |
| LOW | deepspec/modeling/eagle3/loss.py | 92 | def _build_padded_next_token_target_probs( | CODE |
| LOW | deepspec/modeling/eagle3/loss.py | 162 | def _log_softmax_forward_kernel( | CODE |
| LOW | deepspec/modeling/eagle3/loss.py | 225 | def _log_softmax_backward_kernel( | CODE |
| LOW | deepspec/modeling/eagle3/common.py | 56 | def get_compiled_flex_attention(): | CODE |
| LOW | deepspec/modeling/eagle3/common.py | 64 | def compile_friendly_flex_attention( | CODE |
| LOW | deepspec/modeling/eagle3/common.py | 77 | def get_compiled_create_block_mask(): | CODE |
| LOW | deepspec/modeling/eagle3/common.py | 87 | def compile_friendly_create_block_mask( | CODE |
| LOW | deepspec/modeling/eagle3/gemma4/config.py | 22 | def _validate_required_text_fields(text_config) -> None: | CODE |
| LOW | deepspec/modeling/eagle3/gemma4/modeling.py | 307 | def initialize_embeddings_and_head( | CODE |
| LOW | deepspec/modeling/eagle3/gemma4/modeling.py | 322 | def set_embedding_head_trainable(self, trainable: bool): | CODE |
| LOW | deepspec/modeling/eagle3/qwen3/modeling.py | 245 | def initialize_embeddings_and_head( | CODE |
| LOW | deepspec/modeling/eagle3/qwen3/modeling.py | 260 | def set_embedding_head_trainable(self, trainable: bool): | CODE |
| LOW | deepspec/modeling/dspark/loss.py | 11 | def _all_reduce_loss_denominators( | CODE |
| LOW | deepspec/modeling/dspark/loss.py | 40 | def _compute_local_probabilistic_stats( | CODE |
| LOW | deepspec/modeling/dspark/common.py | 59 | def validate_target_layer_ids(layer_ids, num_target_layers: int): | CODE |
| LOW | deepspec/modeling/dspark/common.py | 78 | def create_dspark_attention_mask( | CODE |
| LOW | deepspec/modeling/dspark/common.py | 109 | def build_anchor_candidate_mask( | CODE |
| LOW | deepspec/modeling/dspark/gemma4/config.py | 22 | def _validate_required_text_fields(text_config) -> None: | CODE |
| LOW | deepspec/modeling/dspark/gemma4/modeling.py | 320 | def initialize_embeddings_and_head( | CODE |
| LOW | deepspec/modeling/dspark/gemma4/modeling.py | 335 | def set_embedding_head_trainable(self, trainable: bool): | CODE |
| LOW | deepspec/modeling/dspark/qwen3/modeling.py | 270 | def initialize_embeddings_and_head( | CODE |
| LOW | deepspec/modeling/dspark/qwen3/modeling.py | 285 | def set_embedding_head_trainable(self, trainable: bool): | CODE |
| LOW | deepspec/eval/base_evaluator.py | 100 | def assert_no_final_target_layer(target_model, target_layer_ids) -> None: | CODE |
| LOW | deepspec/eval/base_evaluator.py | 550 | def allreduce_response_metrics( | CODE |
| LOW | deepspec/eval/dspark/draft_ops.py | 22 | def forward_dspark_draft_block( | CODE |
| LOW | deepspec/eval/dspark/draft_ops.py | 57 | def _predict_confidence_logits( | CODE |
| LOW | deepspec/eval/dspark/evaluator.py | 44 | def _build_confidence_head_recorder(self) -> ConfidenceHeadRecorder | None: | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 38 | def build_target_cache_shard_path(cache_dir: str, file_name: str) -> str: | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 42 | def expected_target_cache_tensor_numel( | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 57 | def expected_target_cache_tensor_nbytes( | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 123 | def load_target_cache_manifest(cache_dir: str): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 132 | def validate_target_cache_manifest(*, cache_dir: str, manifest): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 231 | def compute_local_sample_range(*, num_samples: int, rank: int, world_size: int): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 239 | def prepare_target_cache_output_dir(output_dir: str): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 283 | def build_target_cache_sample_bytes( | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 505 | def load_local_cache_write_summary(rank_dir: str): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 510 | def build_global_target_cache_shard_map(summaries): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 532 | def rename_local_target_cache_shards(*, output_dir: str, rank_dir: str, summary, shard_map): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 540 | def finalize_target_cache_index(*, output_dir: str, summaries, shard_map): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 580 | def build_target_cache_manifest( | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 605 | def write_target_cache_manifest(*, output_dir: str, manifest): | CODE |
| LOW | deepspec/data/target_cache_dataset.py | 609 | def cleanup_target_cache_tmp_dir(output_dir: str): | CODE |
| LOW | deepspec/trainer/base_trainer.py | 77 | def _compute_gradient_accumulation_steps( | CODE |
| LOW | deepspec/trainer/base_trainer.py | 89 | def _compute_samples_per_epoch(*, dataset_size: int, global_batch_size: int) -> int: | CODE |
| LOW | deepspec/trainer/base_trainer.py | 98 | def _compute_training_schedule( | CODE |
| LOW | deepspec/trainer/ckpt_manager.py | 25 | def discover_latest_checkpoint(checkpoint_dir): | CODE |
| LOW | deepspec/trainer/ckpt_manager.py | 188 | def _rank_training_state_path(checkpoint_dir: str, global_rank: int) -> str: | CODE |
| LOW | deepspec/trainer/ckpt_manager.py | 195 | def _serialize_training_state( | CODE |
| LOW | scripts/data/generate_train_data.py | 53 | def get_random_reasoning_effort(): | CODE |
| LOW | scripts/data/prepare_target_cache.py | 83 | def run_target_forward_with_hooks( | CODE |
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| LOW | deepspec/__init__.py | 1 | __all__ = [] | CODE |
| LOW | deepspec/utils/metrics.py | 173 | __all__ = ["add_metric", "flush", "reset"] | CODE |
| LOW | deepspec/utils/__init__.py | 66 | __all__ = [ | CODE |
| LOW | deepspec/utils/sampling.py | 47 | __all__ = [ | CODE |
| LOW | deepspec/modeling/__init__.py | 8 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/__init__.py | 5 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/loss.py | 455 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/common.py | 193 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/gemma4/config.py | 91 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/gemma4/__init__.py | 4 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/gemma4/modeling.py | 491 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/qwen3/config.py | 42 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/qwen3/__init__.py | 4 | __all__ = [ | CODE |
| LOW | deepspec/modeling/eagle3/qwen3/modeling.py | 410 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/__init__.py | 5 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/loss.py | 332 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/common.py | 297 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/markov_head.py | 314 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/gemma4/config.py | 105 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/gemma4/__init__.py | 4 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/gemma4/modeling.py | 600 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/qwen3/config.py | 59 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/qwen3/__init__.py | 4 | __all__ = [ | CODE |
| LOW | deepspec/modeling/dspark/qwen3/modeling.py | 528 | __all__ = [ | CODE |
| LOW | deepspec/eval/__init__.py | 5 | __all__ = [ | CODE |
| LOW | deepspec/eval/eagle3/__init__.py | 3 | __all__ = ["Gemma4Eagle3Evaluator", "Qwen3Eagle3Evaluator"] | CODE |
| LOW | deepspec/eval/eagle3/evaluator.py | 195 | __all__ = ["Gemma4Eagle3Evaluator", "Qwen3Eagle3Evaluator"] | CODE |
| LOW | deepspec/eval/dspark/__init__.py | 9 | __all__ = [ | CODE |
| LOW | deepspec/data/__init__.py | 9 | __all__ = [ | CODE |
| LOW | deepspec/trainer/__init__.py | 5 | __all__ = [ | CODE |
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| MEDIUM | deepspec/utils/__init__.py | 29 | def run_git_text(cmd): | CODE |
| LOW | deepspec/utils/__init__.py | 36 | except Exception: | CODE |
| LOW | deepspec/utils/__init__.py | 62 | except Exception: | CODE |
| LOW | scripts/data/generate_train_data.py | 131 | except Exception as exc: | CODE |
| LOW | scripts/data/generate_train_data.py | 165 | except Exception as exc: | CODE |
| LOW | scripts/data/generate_train_data.py | 192 | except Exception as exc: | CODE |
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| LOW | deepspec/modeling/eagle3/gemma4/modeling.py | 221 | CODE | |
| LOW | deepspec/modeling/eagle3/gemma4/modeling.py | 398 | CODE | |
| LOW | deepspec/modeling/eagle3/qwen3/modeling.py | 169 | CODE | |
| LOW | deepspec/modeling/eagle3/qwen3/modeling.py | 324 | CODE | |
| LOW | deepspec/modeling/dspark/gemma4/modeling.py | 201 | CODE | |
| LOW | deepspec/modeling/dspark/qwen3/modeling.py | 165 | CODE |
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| LOW | deepspec/eval/base_evaluator.py | 550 | CODE | |
| LOW | deepspec/data/target_cache_dataset.py | 438 | CODE | |
| LOW | eval_datasets/convert_eval_datasets_to_jsonl.py | 251 | CODE | |
| LOW | scripts/data/generate_train_data.py | 57 | CODE | |
| LOW | scripts/data/generate_train_data.py | 272 | CODE | |
| LOW | scripts/data/prepare_target_cache.py | 209 | CODE |
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| LOW | scripts/data/README.md | 27 | ## Step 1: Download And Split Data | COMMENT |
| LOW | scripts/data/README.md | 47 | ## Step 2: Regenerate Answers With Qwen3-4B | COMMENT |
| LOW | scripts/data/README.md | 103 | ## Step 3: Prepare Target Cache | COMMENT |
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| MEDIUM | scripts/train/train.sh | 34 | # local_batch_size is the per-GPU micro-batch size. Raise it to better utilize GPUs | COMMENT |
| Severity | File | Line | Snippet | Context |
|---|---|---|---|---|
| LOW | scripts/train/train.sh | 1 | #!/usr/bin/env bash | COMMENT |
| LOW | scripts/train/train.sh | 21 | # config/eagle3/eagle3_qwen3_4b.py | COMMENT |