chore: document and clean up the generic SDK layout

Makefile

@@ -2,11 +2,14 @@ PYTHON ?= python3
 REPO_ROOT := $(CURDIR)
 export PYTHONPATH := $(REPO_ROOT)/python:$(REPO_ROOT)/compiler$(if $(PYTHONPATH),:$(PYTHONPATH))
 
-.PHONY: check examples native-sdk-check package package-test python-check repository-check shell-check test validate
+.PHONY: check examples native-sdk-check package package-test python-check repository-check shell-check static-check test validate
 
 python-check:
 	$(PYTHON) -m compileall -q compiler/netra_compiler python/netra_kernel tools/compiler tools/ci tests/compiler tests/package
 
+static-check:
+	$(PYTHON) -m ruff check compiler/netra_compiler python/netra_kernel tools tests --select F401,F811,F821,F841
+
 test:
 	$(PYTHON) -m unittest discover -s tests/compiler -v
 
@@ -29,7 +32,7 @@ shell-check:
 	git ls-files -z '*.sh' | xargs -0 -r -n1 bash -n
 	git diff --check
 
-check: python-check test package-test repository-check native-sdk-check validate examples shell-check
+check: python-check static-check test package-test repository-check native-sdk-check validate examples shell-check
 
 package:
 	PYTHON=$(PYTHON) bash tools/ci/build_package.sh

README.md

@@ -110,6 +110,44 @@ stream. Direct fixed launches remain available when graph capture is disabled.
 The installed SDK exports `libnetra_engine.so.1`, `<netra/engine.h>`, CMake and
 pkg-config metadata, plus a framework-neutral `netra_kernel.Engine` binding.
 
+## Repository layout
+
+The public integration surface is separated from target-specific kernels and
+inference-engine adapters:
+
+```text
+netra-kernel/
+├── compiler/netra_compiler/   # AOT compiler, IR, planners, frontends, backends
+│   ├── backends/gfx950/       # Target-specific compiler implementation
+│   └── library_data/          # Packaged kernels, manifests, and schemas
+├── python/netra_kernel/       # Bundle, runtime, CLI, and adapter APIs
+│   ├── runtime/               # Framework-neutral Python FFI
+│   ├── sglang/                # SGLang adapter and startup plugin only
+│   └── assets/                # Deployment profiles and packaged overlays
+├── include/netra/engine.h     # Stable framework-neutral C ABI
+├── runtime/                   # Native runtime implementations
+├── examples/reference_engine/ # Minimal C consumer with no framework dependency
+├── kernels/                   # Architecture-specific kernel sources
+├── manifests/                 # Model, deployment, and tactic contracts
+├── schemas/                   # Public JSON schemas
+├── docker/sglang/             # Thin-plugin and accepted-source images
+├── tools/                     # Build, compiler, benchmark, and CI tooling
+├── tests/                     # Compiler, package, and GPU validation
+└── docs/                      # Integration guides and acceptance evidence
+```
+
+`netra-compiler` and `netra-kernel` are separate installable distributions.
+The compiler emits a deterministic engine directory; `libnetra_engine.so.1`
+loads and launches it; an optional adapter translates only the surrounding
+inference-engine boundary. New engines integrate through the
+`netra.inference_engines` entry-point group without importing SGLang code.
+
+The top-level `kernels/gfx950`, `manifests`, and `schemas` paths point to the
+same canonical data packaged in the wheels. This preserves convenient
+source-tree commands without maintaining duplicate catalogs that can drift.
+Architecture-specific harnesses, profiling scripts, and historical results
+remain outside the public SDK surface.
+
 ## Supported today
 
 | Capability | Current support |

compiler/netra_compiler/engine.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import hashlib
-import json
 import shutil
 from collections.abc import Mapping
 from pathlib import Path
@@ -16,7 +15,7 @@
 from .memory import BufferRequest, checked_mul, plan_buffers
 from .planner import Plan, plan_graph
 from .profiles import ShapeProfile
-from .types import canonical_json, stable_hash, write_json
+from .types import stable_hash, write_json
 
 
 FORMAT_VERSION = "netra-engine-1"

compiler/netra_compiler/tactics.py

@@ -2,7 +2,6 @@
 
 from collections.abc import Mapping
 from dataclasses import dataclass
-from pathlib import Path
 from typing import Any, Iterable
 
 from .contracts import GoldenKernelContract, KernelArgument, KernelContract, Launch, Workspace

docs/notes/gfx1151-causal-conv-stream64-2026-07-29.md

@@ -37,7 +37,7 @@ The raw path delivered the expected ~1.07 s host benefit, but pair-b changed its
 The retained raw ASM and harness are:
 
 - `kernels/gfx1151/gdn/experiments/causal_conv1d_stream64_gfx1151.s`
-- `kernels/gfx1151/gdn/experiments/causal_conv1d_state_update_gfx1151.s`
+- `kernels/gfx1151/gdn/causal_conv1d_state_update_gfx1151.s`
 - `harness/gfx1151/gdn/causal_conv1d_stream64_launcher.hip`
 - `tools/benchmark/benchmark_causal_conv1d_stream64.py`
 

pyproject.toml

@@ -18,7 +18,7 @@ classifiers = [
 
 [project.optional-dependencies]
 sglang = ["torch>=2.8"]
-test = ["pytest>=8", "build>=1.2"]
+test = ["pytest>=8", "build>=1.2", "ruff>=0.16"]
 
 [project.scripts]
 netra-kernel = "netra_kernel.kernel_cli:main"

python/netra_kernel/cli.py

@@ -77,7 +77,6 @@ def _doctor(bundle_path: Path | None) -> dict:
     expected_source_snapshot = None
     bundle_result = None
     if bundle_path is not None:
-        payload = load_bundle(bundle_path)
         integration = integration_configuration(bundle_path, "sglang")
         required = tuple(integration.get("required_modules", ()))
         expected_source_snapshot = integration.get("source_snapshot")

python/netra_kernel/native.py

@@ -10,7 +10,7 @@
 import ctypes
 import ctypes.util
 import os
-from importlib.resources import as_file, files
+from importlib.resources import files
 from pathlib import Path
 from typing import Iterator
 

tests/compiler/test_engine_manifest.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import hashlib
 import json
 import tempfile
 import unittest

tests/gfx1151/test_netra_mxfp4_sgl_decode.py

@@ -3,7 +3,6 @@
 
 import ctypes
 import json
-import math
 import os
 from pathlib import Path
 

tests/gfx1151/test_netra_mxfp4_sgl_linear.py

@@ -93,12 +93,12 @@ def main() -> None:
     if status:
         raise RuntimeError(f"launch failed: {status}")
     torch.cuda.synchronize()
+    output = output_groups.view(-1, n)[:m].to(torch.bfloat16)
     if os.environ.get("NETRA_ARGS_DEBUG") == "1":
         print(output.view(torch.int32).cpu()[0, :8].tolist())
         return
 
     weight64 = dequant(packed_cpu, scales_cpu)
-    output = output_groups.view(-1, n)[:m].to(torch.bfloat16)
     reference = activation.cpu().to(torch.float64) @ weight64.t()
     ref_bf16 = reference.to(torch.bfloat16)
     got = output.cpu()

tools/benchmark/benchmark_extend_attention_tiles.py

@@ -96,8 +96,11 @@ def call() -> None:
                 "max_abs_vs_64x64": max_abs,
                 "normalized_l2_vs_64x64": normalized_l2,
             })
-        del q, k, v, k_buffer, v_buffer, reference
-
+        # Drop the closure before its captured tensors so the next prefix does
+        # not temporarily retain two full attention fixtures.
+        call = output = None
+        q = k = v = k_buffer = v_buffer = reference = None
+        torch.cuda.empty_cache()
     module._get_block_sizes_for_extend_attention = original_blocks
     result = {
         "target": "gfx1151",

tools/benchmark/benchmark_qkvzba_split_copy.py

@@ -154,7 +154,10 @@ def launch_triton() -> None:
                 "bit_mismatches_qkv_z_b_a": mismatches,
             }
         )
-        del raw_tensors, triton_tensors
+        # The launch closures capture the tensors; release them first so
+        # empty_cache can return storage before the next token shape.
+        launch_raw = launch_triton = None
+        raw_tensors = triton_tensors = None
         torch.cuda.empty_cache()
 
     report = {

tools/ci/smoke_package.py

@@ -6,7 +6,6 @@
 import argparse
 import os
 import subprocess
-import sys
 import tempfile
 import venv
 from pathlib import Path

tools/profiling/rocprof_attach.py

@@ -10,7 +10,6 @@
 import ctypes
 import os
 import signal
-import sys
 import time
 
 DEFAULT_LIBRARY = (