From eece9c33086d52ef66f5bfb7fb9132b9985ee643 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:26:44 +0300 Subject: [PATCH 01/11] Extend architecture schema for evidenced manifests --- schemas/architecture.schema.json | 59 ++++++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 2 deletions(-) diff --git a/schemas/architecture.schema.json b/schemas/architecture.schema.json index efe5b50..beffd8e 100644 --- a/schemas/architecture.schema.json +++ b/schemas/architecture.schema.json @@ -3,11 +3,22 @@ "$id": "https://modelmap.dev/schemas/architecture.schema.json", "title": "ModelMap ArchitectureSpec", "type": "object", - "required": ["id", "type", "name", "topology"], + "$defs": { + "evidenceField": { + "type": "string", + "pattern": "^(?:blocks|(?:topology|dimensions|tokenization|context|components|attention|feed_forward|modalities)\\.[a-z][a-z0-9_]*)$" + } + }, + "required": ["id", "type", "name", "target", "status", "topology", "evidence"], "properties": { "id": {"type": "string", "pattern": "^arch:[a-z0-9][a-z0-9._-]*$"}, "type": {"const": "architecture_spec"}, "name": {"type": "string", "minLength": 1}, + "target": {"type": "string", "pattern": "^(?:release|variant):[a-z0-9][a-z0-9._-]*$"}, + "status": { + "type": "string", + "enum": ["draft", "reviewed", "canonical", "deprecated"] + }, "topology": { "type": "object", "required": ["type"], @@ -16,7 +27,8 @@ "type": "string", "enum": ["decoder_only", "encoder_decoder", "encoder_only", "hybrid", "multimodal_hybrid", "unknown"] }, - "pre_norm": {"type": ["boolean", "null"]} + "pre_norm": {"type": ["boolean", "null"]}, + "post_norm": {"type": ["boolean", "null"]} }, "additionalProperties": false }, @@ -63,6 +75,29 @@ }, "additionalProperties": false }, + "attention": { + "type": "object", + "properties": { + "query_heads": {"type": ["integer", "null"], "minimum": 1}, + "kv_heads": {"type": ["integer", "null"], "minimum": 1}, + "sliding_window": {"type": ["integer", "null"], "minimum": 1}, + "global_span": {"type": ["integer", "null"], "minimum": 1}, + "kv_compression_dim": {"type": ["integer", "null"], "minimum": 1}, + "query_compression_dim": {"type": ["integer", "null"], "minimum": 1} + }, + "additionalProperties": false + }, + "feed_forward": { + "type": "object", + "properties": { + "intermediate_dim": {"type": ["integer", "null"], "minimum": 1}, + "expert_intermediate_dim": {"type": ["integer", "null"], "minimum": 1}, + "shared_experts": {"type": ["integer", "null"], "minimum": 1}, + "routed_experts": {"type": ["integer", "null"], "minimum": 1}, + "active_routed_experts": {"type": ["integer", "null"], "minimum": 1} + }, + "additionalProperties": false + }, "blocks": { "type": "array", "items": { @@ -91,6 +126,26 @@ }, "additionalProperties": false }, + "evidence": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": ["source", "locator", "fields"], + "properties": { + "source": {"type": "string", "pattern": "^source:[a-z0-9][a-z0-9._-]*$"}, + "locator": {"type": "string", "minLength": 1}, + "fields": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": {"$ref": "#/$defs/evidenceField"} + }, + "note": {"type": ["string", "null"]} + }, + "additionalProperties": false + } + }, "notes": {"type": ["string", "null"]} }, "additionalProperties": false From 204adfd015a59525fdfb7c5a7ce8e08ba30ccbb1 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:27:21 +0300 Subject: [PATCH 02/11] Enforce architecture targets and field evidence --- tools/validate.py | 131 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 130 insertions(+), 1 deletion(-) diff --git a/tools/validate.py b/tools/validate.py index c9ecfb1..8df091a 100755 --- a/tools/validate.py +++ b/tools/validate.py @@ -30,6 +30,17 @@ "extends", } +ARCHITECTURE_FACT_SECTIONS = ( + "topology", + "dimensions", + "tokenization", + "context", + "components", + "attention", + "feed_forward", + "modalities", +) + def load_schema(name: str) -> dict[str, Any]: with (SCHEMAS / name).open("r", encoding="utf-8") as fh: @@ -63,6 +74,118 @@ def claim_supports_relationship(relationship: dict[str, Any], claim: dict[str, A ) +def architecture_fact_paths(record: dict[str, Any]) -> set[str]: + """Return populated architecture fact paths that require field-level evidence.""" + fields: set[str] = set() + for section in ARCHITECTURE_FACT_SECTIONS: + value = record.get(section) + if not isinstance(value, dict): + continue + for key, field_value in value.items(): + if field_value is not None: + fields.add(f"{section}.{key}") + + # A heterogeneous layer plan is evidenced as one atomic fact. Per-block notes + # and properties remain covered by the evidence attached to the full plan. + if record.get("blocks") is not None: + fields.add("blocks") + return fields + + +def architecture_record_errors( + record: dict[str, Any], + by_id: dict[str, tuple[Path, dict[str, Any]]], +) -> list[str]: + """Validate architecture targets, field evidence, and block-plan invariants.""" + messages: list[str] = [] + + target_ref = record.get("target") + target = by_id.get(target_ref) if isinstance(target_ref, str) else None + if target is None: + messages.append(f"unresolved architecture target {target_ref!r}") + elif target[1].get("type") not in {"model_release", "model_variant"}: + messages.append( + f"architecture target {target_ref!r} must reference a model_release " + f"or model_variant, found {target[1].get('type')!r}" + ) + + fact_paths = architecture_fact_paths(record) + covered_fields: set[str] = set() + for evidence in record.get("evidence", []): + if not isinstance(evidence, dict): + continue + + source_ref = evidence.get("source") + source = by_id.get(source_ref) if isinstance(source_ref, str) else None + source_is_valid = source is not None and source[1].get("type") == "source" + if source is None: + messages.append(f"unresolved architecture evidence source {source_ref!r}") + elif not source_is_valid: + messages.append( + f"architecture evidence {source_ref!r} must reference type 'source', " + f"found {source[1].get('type')!r}" + ) + + fields = evidence.get("fields", []) + if not isinstance(fields, list): + continue + for field in fields: + if not isinstance(field, str): + continue + if field not in fact_paths: + messages.append( + f"architecture evidence field {field!r} does not name a populated " + "architecture fact" + ) + elif source_is_valid: + covered_fields.add(field) + + for field in sorted(fact_paths - covered_fields): + messages.append(f"architecture field {field!r} is missing evidence") + + blocks = record.get("blocks") + dimensions = record.get("dimensions") + layer_count = None + if isinstance(dimensions, dict) and type(dimensions.get("layers")) is int: + layer_count = dimensions["layers"] + + valid_ranges: list[tuple[int, int, int]] = [] + if isinstance(blocks, list): + for index, block in enumerate(blocks): + if not isinstance(block, dict): + continue + block_range = block.get("range") + if not ( + isinstance(block_range, list) + and len(block_range) == 2 + and all(type(value) is int for value in block_range) + ): + continue + + start, end = block_range + if start > end: + messages.append( + f"blocks[{index}].range start {start} exceeds end {end}" + ) + continue + if layer_count is not None and end >= layer_count: + messages.append( + f"blocks[{index}].range end {end} is outside " + f"dimensions.layers={layer_count}" + ) + + for previous_index, previous_start, previous_end in valid_ranges: + if start <= previous_end and previous_start <= end: + messages.append( + f"blocks[{index}].range [{start}, {end}] overlaps " + f"blocks[{previous_index}].range " + f"[{previous_start}, {previous_end}]" + ) + valid_ranges.append((index, start, end)) + + return messages + + def main() -> int: errors: list[str] = [] try: @@ -80,7 +203,9 @@ def main() -> int: for path, record in records: rel = path.relative_to(ROOT) schema_name = SCHEMA_BY_TYPE.get(record.get("type"), "entity.schema.json") - validator = Draft202012Validator(schema_cache[schema_name], format_checker=FormatChecker()) + validator = Draft202012Validator( + schema_cache[schema_name], format_checker=FormatChecker() + ) for err in sorted(validator.iter_errors(record), key=lambda e: list(e.path)): location = ".".join(str(part) for part in err.path) or "" errors.append(f"{rel}: {location}: {err.message}") @@ -134,6 +259,10 @@ def require_id( f"predicate/endpoints {record.get('subject')!r} " f"-{record.get('predicate')}-> {record.get('object')!r}" ) + elif record_type == "architecture_spec": + rel = path.relative_to(ROOT) + for message in architecture_record_errors(record, by_id): + errors.append(f"{rel}: {message}") elif record_type == "event": require_id(path, record.get("subject")) for source_ref in record.get("evidence", []): From a709430c5a5a40a56096d27f03658cdd7ec0af94 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:27:55 +0300 Subject: [PATCH 03/11] Add architecture manifest validation tests --- tests/test_architecture_manifests.py | 182 +++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 tests/test_architecture_manifests.py diff --git a/tests/test_architecture_manifests.py b/tests/test_architecture_manifests.py new file mode 100644 index 0000000..96479f1 --- /dev/null +++ b/tests/test_architecture_manifests.py @@ -0,0 +1,182 @@ +from __future__ import annotations + +import json +import sys +import unittest +from pathlib import Path + +from jsonschema import Draft202012Validator, FormatChecker + +ROOT = Path(__file__).resolve().parents[1] +TOOLS = ROOT / "tools" +if str(TOOLS) not in sys.path: + sys.path.insert(0, str(TOOLS)) + +import records # noqa: E402 +import validate as corpus_validate # noqa: E402 + + +class ArchitectureManifestTests(unittest.TestCase): + def load_schema(self) -> dict: + return json.loads( + (ROOT / "schemas" / "architecture.schema.json").read_text(encoding="utf-8") + ) + + def assert_schema_invalid(self, instance: dict) -> None: + validator = Draft202012Validator( + self.load_schema(), format_checker=FormatChecker() + ) + self.assertTrue(list(validator.iter_errors(instance))) + + def record_index(self, *records_to_index: dict) -> dict: + return { + record["id"]: (Path(f"{index}.yaml"), record) + for index, record in enumerate(records_to_index) + } + + def minimal_architecture(self) -> dict: + return { + "id": "arch:example", + "type": "architecture_spec", + "name": "Example architecture", + "target": "release:example", + "status": "reviewed", + "topology": {"type": "decoder_only"}, + "evidence": [ + { + "source": "source:example", + "locator": "Architecture section", + "fields": ["topology.type"], + } + ], + } + + def test_schema_requires_target_status_and_evidence(self) -> None: + architecture = self.minimal_architecture() + for field in ("target", "status", "evidence"): + invalid = dict(architecture) + invalid.pop(field) + with self.subTest(field=field): + self.assert_schema_invalid(invalid) + + def test_schema_rejects_non_fact_evidence_path(self) -> None: + architecture = self.minimal_architecture() + architecture["evidence"][0]["fields"] = ["notes"] + self.assert_schema_invalid(architecture) + + def test_schema_supports_gemma_pre_and_post_norm(self) -> None: + architecture = self.minimal_architecture() + architecture["topology"] = { + "type": "decoder_only", + "pre_norm": True, + "post_norm": True, + } + architecture["evidence"][0]["fields"] = [ + "topology.type", + "topology.pre_norm", + "topology.post_norm", + ] + validator = Draft202012Validator( + self.load_schema(), format_checker=FormatChecker() + ) + self.assertEqual(list(validator.iter_errors(architecture)), []) + + def test_architecture_target_must_resolve_to_model(self) -> None: + architecture = self.minimal_architecture() + index = self.record_index( + {"id": "release:example", "type": "technique"}, + {"id": "source:example", "type": "source"}, + ) + errors = corpus_validate.architecture_record_errors(architecture, index) + self.assertTrue(any("must reference a model_release or model_variant" in e for e in errors)) + + def test_populated_fact_requires_evidence(self) -> None: + architecture = self.minimal_architecture() + architecture["dimensions"] = {"layers": 32} + index = self.record_index( + {"id": "release:example", "type": "model_release"}, + {"id": "source:example", "type": "source"}, + ) + errors = corpus_validate.architecture_record_errors(architecture, index) + self.assertIn("architecture field 'dimensions.layers' is missing evidence", errors) + + def test_evidence_cannot_name_an_absent_or_null_fact(self) -> None: + architecture = self.minimal_architecture() + architecture["attention"] = {"kv_heads": None} + architecture["evidence"][0]["fields"].append("attention.kv_heads") + index = self.record_index( + {"id": "release:example", "type": "model_release"}, + {"id": "source:example", "type": "source"}, + ) + errors = corpus_validate.architecture_record_errors(architecture, index) + self.assertTrue(any("does not name a populated architecture fact" in e for e in errors)) + + def test_invalid_source_does_not_satisfy_field_coverage(self) -> None: + architecture = self.minimal_architecture() + index = self.record_index( + {"id": "release:example", "type": "model_release"}, + {"id": "source:example", "type": "paper"}, + ) + errors = corpus_validate.architecture_record_errors(architecture, index) + self.assertTrue(any("must reference type 'source'" in e for e in errors)) + self.assertIn("architecture field 'topology.type' is missing evidence", errors) + + def test_packaging_dependent_kv_heads_can_be_omitted(self) -> None: + architecture = self.minimal_architecture() + architecture["attention"] = {"query_heads": 128} + architecture["evidence"][0]["fields"].append("attention.query_heads") + index = self.record_index( + {"id": "release:example", "type": "model_release"}, + {"id": "source:example", "type": "source"}, + ) + self.assertEqual( + corpus_validate.architecture_record_errors(architecture, index), [] + ) + + def test_block_ranges_must_be_ordered_non_overlapping_and_in_bounds(self) -> None: + architecture = self.minimal_architecture() + architecture["dimensions"] = {"layers": 4} + architecture["blocks"] = [ + {"range": [0, 2]}, + {"range": [2, 4]}, + {"range": [3, 1]}, + ] + architecture["evidence"][0]["fields"].extend( + ["dimensions.layers", "blocks"] + ) + index = self.record_index( + {"id": "release:example", "type": "model_release"}, + {"id": "source:example", "type": "source"}, + ) + errors = corpus_validate.architecture_record_errors(architecture, index) + self.assertTrue(any("overlaps" in e for e in errors)) + self.assertTrue(any("outside dimensions.layers=4" in e for e in errors)) + self.assertTrue(any("exceeds end" in e for e in errors)) + + def test_repository_architectures_have_complete_field_evidence(self) -> None: + loaded = list(records.iter_records(ROOT / "data")) + index = { + record["id"]: (path, record) + for path, record in loaded + if isinstance(record.get("id"), str) + } + architectures = [ + record for _, record in loaded if record.get("type") == "architecture_spec" + ] + self.assertGreaterEqual(len(architectures), 4) + for architecture in architectures: + with self.subTest(architecture=architecture["id"]): + self.assertEqual( + corpus_validate.architecture_record_errors(architecture, index), [] + ) + + def test_llama_405b_manifest_omits_packaging_dependent_kv_heads(self) -> None: + llama = records.load_document( + ROOT / "data" / "architectures" / "llama-3.1-405b.yaml" + ) + self.assertNotIn("kv_heads", llama.get("attention", {})) + self.assertIn("packaging-dependent", llama.get("notes", "")) + + +if __name__ == "__main__": + unittest.main() From 484a889f42ef8384558e8e8540617820a10fa98b Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:28:02 +0300 Subject: [PATCH 04/11] Add pinned Meta Llama SKU source --- data/sources/llama-models-sku-list.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 data/sources/llama-models-sku-list.yaml diff --git a/data/sources/llama-models-sku-list.yaml b/data/sources/llama-models-sku-list.yaml new file mode 100644 index 0000000..79e90e0 --- /dev/null +++ b/data/sources/llama-models-sku-list.yaml @@ -0,0 +1,9 @@ +id: source:llama-models-sku-list +type: source +title: Meta Llama model SKU registry +source_type: official_config +url: https://github.com/meta-llama/llama-models/blob/0e0b8c519242d5833d8c11bffc1232b77ad7f301/models/sku_list.py +publisher: Meta +version: 0e0b8c519242d5833d8c11bffc1232b77ad7f301 +retrieved_at: '2026-09-29T21:06:00Z' +notes: Pinned to the commit used to verify Llama 3.1 405B architecture arguments and packaging-dependent KV-head counts. From 389605f91ed81e5406a7a7a0dc293fb9676f5eb5 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:28:06 +0300 Subject: [PATCH 05/11] Add Llama 3.1 405B variant target --- data/variants/llama-3.1-405b.yaml | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 data/variants/llama-3.1-405b.yaml diff --git a/data/variants/llama-3.1-405b.yaml b/data/variants/llama-3.1-405b.yaml new file mode 100644 index 0000000..4ac161d --- /dev/null +++ b/data/variants/llama-3.1-405b.yaml @@ -0,0 +1,4 @@ +id: variant:llama-3.1-405b +type: model_variant +name: Llama 3.1 405B +status: reviewed From bcdd2b8e31309dec40ec0bccb86b8460c6142746 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:28:14 +0300 Subject: [PATCH 06/11] Add Mistral 7B architecture manifest --- data/architectures/mistral-7b.yaml | 41 ++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 data/architectures/mistral-7b.yaml diff --git a/data/architectures/mistral-7b.yaml b/data/architectures/mistral-7b.yaml new file mode 100644 index 0000000..c6a013f --- /dev/null +++ b/data/architectures/mistral-7b.yaml @@ -0,0 +1,41 @@ +id: arch:mistral-7b +type: architecture_spec +name: Mistral 7B architecture +target: release:mistral-7b +status: reviewed +topology: + type: decoder_only +dimensions: + layers: 32 + d_model: 4096 + head_dim: 128 +tokenization: + vocab_size: 32000 +context: + pretrained_length: 8192 +components: + attention: grouped_query_attention_with_sliding_window +attention: + query_heads: 32 + kv_heads: 8 + sliding_window: 4096 +feed_forward: + intermediate_dim: 14336 +evidence: + - source: source:mistral-7b-paper + locator: '§2 Architectural details, Table 1' + fields: + - dimensions.layers + - dimensions.d_model + - dimensions.head_dim + - tokenization.vocab_size + - context.pretrained_length + - attention.query_heads + - attention.kv_heads + - attention.sliding_window + - feed_forward.intermediate_dim + - source: source:mistral-7b-paper + locator: 'Abstract and §2 Architectural details (GQA/SWA; Figure 3 causal mask)' + fields: + - topology.type + - components.attention From 38fe1d008b1670038b511218d026fea1b55be8ca Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:28:24 +0300 Subject: [PATCH 07/11] Add Gemma 2 9B architecture manifest --- data/architectures/gemma-2-9b.yaml | 53 ++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 data/architectures/gemma-2-9b.yaml diff --git a/data/architectures/gemma-2-9b.yaml b/data/architectures/gemma-2-9b.yaml new file mode 100644 index 0000000..53a4539 --- /dev/null +++ b/data/architectures/gemma-2-9b.yaml @@ -0,0 +1,53 @@ +id: arch:gemma-2-9b +type: architecture_spec +name: Gemma 2 9B architecture +target: variant:gemma-2-9b +status: reviewed +topology: + type: decoder_only + pre_norm: true + post_norm: true +dimensions: + layers: 42 + d_model: 3584 + head_dim: 256 +tokenization: + vocab_size: 256128 +context: + pretrained_length: 8192 +components: + normalization: rmsnorm + position: rope + attention: alternating_local_global_grouped_query_attention + ffn: geglu +attention: + query_heads: 16 + kv_heads: 8 + sliding_window: 4096 + global_span: 8192 +feed_forward: + intermediate_dim: 28672 +evidence: + - source: source:gemma-2-report + locator: 'Table 1, Overview of the main model parameters and design choices' + fields: + - topology.pre_norm + - topology.post_norm + - dimensions.layers + - dimensions.d_model + - dimensions.head_dim + - tokenization.vocab_size + - attention.query_heads + - attention.kv_heads + - attention.sliding_window + - attention.global_span + - feed_forward.intermediate_dim + - source: source:gemma-2-report + locator: '§2 Model Architecture' + fields: + - topology.type + - context.pretrained_length + - components.normalization + - components.position + - components.attention + - components.ffn From 795786e6c463a112c46e33e4f617ead0bac3ee46 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:28:33 +0300 Subject: [PATCH 08/11] Add DeepSeek-V3 architecture manifest --- data/architectures/deepseek-v3.yaml | 56 +++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 data/architectures/deepseek-v3.yaml diff --git a/data/architectures/deepseek-v3.yaml b/data/architectures/deepseek-v3.yaml new file mode 100644 index 0000000..ec8bce1 --- /dev/null +++ b/data/architectures/deepseek-v3.yaml @@ -0,0 +1,56 @@ +id: arch:deepseek-v3 +type: architecture_spec +name: DeepSeek-V3 architecture +target: release:deepseek-v3 +status: reviewed +topology: + type: decoder_only +dimensions: + layers: 61 + d_model: 7168 + head_dim: 128 +components: + attention: multi_head_latent_attention + ffn: dense_then_deepseek_moe + routing: auxiliary_loss_free_load_balancing +attention: + query_heads: 128 + kv_compression_dim: 512 + query_compression_dim: 1536 +feed_forward: + expert_intermediate_dim: 2048 + shared_experts: 1 + routed_experts: 256 + active_routed_experts: 8 +blocks: + - range: [0, 2] + attention: multi_head_latent_attention + ffn: dense + - range: [3, 60] + attention: multi_head_latent_attention + ffn: deepseek_moe +evidence: + - source: source:deepseek-v3-report + locator: '§2.1 Basic Architecture and §2.1.1 Multi-Head Latent Attention' + fields: + - topology.type + - components.attention + - source: source:deepseek-v3-report + locator: '§2.1.2 DeepSeekMoE with Auxiliary-Loss-Free Load Balancing' + fields: + - components.ffn + - components.routing + - source: source:deepseek-v3-report + locator: '§4.2 Hyper-Parameters > Model Hyper-Parameters' + fields: + - dimensions.layers + - dimensions.d_model + - dimensions.head_dim + - attention.query_heads + - attention.kv_compression_dim + - attention.query_compression_dim + - feed_forward.expert_intermediate_dim + - feed_forward.shared_experts + - feed_forward.routed_experts + - feed_forward.active_routed_experts + - blocks From a1ba962aa6c516d9c69070a6a4af76abc66bb7b7 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:28:42 +0300 Subject: [PATCH 09/11] Add Llama 3.1 405B architecture manifest --- data/architectures/llama-3.1-405b.yaml | 33 ++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 data/architectures/llama-3.1-405b.yaml diff --git a/data/architectures/llama-3.1-405b.yaml b/data/architectures/llama-3.1-405b.yaml new file mode 100644 index 0000000..c03a25f --- /dev/null +++ b/data/architectures/llama-3.1-405b.yaml @@ -0,0 +1,33 @@ +id: arch:llama-3.1-405b +type: architecture_spec +name: Llama 3.1 405B architecture +target: variant:llama-3.1-405b +status: reviewed +topology: + type: decoder_only +dimensions: + layers: 126 + d_model: 16384 +tokenization: + vocab_size: 128256 +components: + position: scaled_rope + attention: grouped_query_attention +attention: + query_heads: 128 +evidence: + - source: source:llama-3-paper + locator: '§3.2 Model Architecture, Table 3' + fields: + - topology.type + - components.attention + - source: source:llama-models-sku-list + locator: 'models/sku_list.py: LLAMA3_VOCAB_SIZE and llama3_1_base_models() 405B BF16 MP8/FP8/MP16 entries, commit 0e0b8c519242d5833d8c11bffc1232b77ad7f301' + fields: + - dimensions.layers + - dimensions.d_model + - tokenization.vocab_size + - components.position + - attention.query_heads + note: 'The same core model is packaged with n_kv_heads=8 for BF16 MP8/FP8 and n_kv_heads=16 for BF16 MP16.' +notes: "attention.kv_heads is intentionally omitted at the model-variant level because Meta's first-party checkpoint SKUs expose packaging-dependent KV-head counts for the same 405B core model." From dc3e8f6f01ff9bf44dbecafab35564ebde011525 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:29:21 +0300 Subject: [PATCH 10/11] Document architecture manifest evidence policy --- data/README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/data/README.md b/data/README.md index 7ac81f7..cadd442 100644 --- a/data/README.md +++ b/data/README.md @@ -75,6 +75,34 @@ Do not overload values: Evidence references should identify a source plus the smallest useful locator available: section, table, page, config key, file/line range, release-note heading, or commit. +## Architecture manifests + +An `ArchitectureSpec` targets exactly one canonical model release or model variant through `target`. Every populated architecture fact must be covered by at least one field-level evidence entry. Evidence entries identify a canonical `source`, a narrow `locator`, and the exact fact paths supported by that locator. + +```yaml +id: arch:example-model +type: architecture_spec +name: Example model architecture +target: variant:example-model +status: reviewed +topology: + type: decoder_only +attention: + query_heads: 32 +evidence: + - source: source:example-model-report + locator: '§2 Model Architecture, Table 1' + fields: + - topology.type + - attention.query_heads +``` + +The validator rejects evidence paths that point to absent or `null` values and rejects populated architecture facts that lack evidence. `notes` are editorial context and are not treated as architecture facts requiring field evidence. + +Layer-plan ranges in `blocks` are zero-based and inclusive. Ranges must be ordered internally, must not overlap, and must remain within `dimensions.layers` when the layer count is present. + +Architecture fields whose values are unestablished or vary by checkpoint packaging within the manifest's target should be omitted rather than guessed, averaged, or selected from one package and presented as intrinsic architecture. Use `null` only when preserving an explicit reviewed-but-unestablished slot is itself useful to the record. + ## Dates and timestamps Quote ISO dates and timestamps in hand-authored YAML when practical. The shared record loader normalizes YAML-native `date` and `datetime` scalars to ISO strings before schema validation and generation, so equivalent unquoted YAML remains valid. From a3dc8b0db61c17bf6a794da1b7dd290e7541e157 Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:29:51 +0300 Subject: [PATCH 11/11] Define architecture manifest semantics in ontology --- docs/ontology.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/ontology.md b/docs/ontology.md index 08f83ec..267b6ad 100644 --- a/docs/ontology.md +++ b/docs/ontology.md @@ -183,19 +183,39 @@ These use different edge types. Conceptual similarity must never imply checkpoin ## 7. Architecture representation -Architecture records should support heterogeneous layer plans rather than assuming every block is identical. +An `ArchitectureSpec` targets exactly one `ModelRelease` or `ModelVariant`. Architecture facts are stored as structured fields, and every populated fact must be mapped to evidence at field granularity. This keeps a compact manifest auditable without multiplying every architectural scalar into a separate claim record. ```yaml +id: arch:example-model +type: architecture_spec +name: Example model architecture +target: variant:example-model +status: reviewed +topology: + type: decoder_only +dimensions: + layers: 61 blocks: - range: [0, 2] - attention: component:mla - ffn: component:dense-swiglu + attention: multi_head_latent_attention + ffn: dense - range: [3, 60] - attention: component:mla - ffn: component:sparse-moe + attention: multi_head_latent_attention + ffn: sparse_moe +evidence: + - source: source:example-technical-report + locator: '§4.2 Model Hyper-Parameters' + fields: + - topology.type + - dimensions.layers + - blocks ``` -Unknown values are represented as `null`; `null` does not mean zero or not applicable. +`blocks.range` is zero-based and inclusive. Ranges must not overlap and must stay within the declared layer count when `dimensions.layers` is present. Heterogeneous plans may leave gaps when the source only establishes a subset of the layer plan. + +Evidence entries name the canonical source, the smallest useful locator, and the exact populated fact paths supported by that locator. Editorial `notes` are not treated as architecture facts. A populated field with no valid evidence is a validation error, as is evidence that points to an absent or `null` field. + +For architecture manifests, values that are not established at the target's granularity should normally be omitted. This is especially important when first-party checkpoint packaging exposes different values for what appears to be the same broader model variant; choosing one packaging value would overstate it as intrinsic architecture. `null` remains available when explicitly preserving a reviewed-but-unestablished slot is useful, and never means zero or not applicable. ## 8. Evaluation ontology