natc 0.1.0__tar.gz

natc-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 NATC Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

natc-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: natc
+Version: 0.1.0
+Summary: NeuroSymbolic Adaptive Tensor Compression for CPU-first dynamic inference.
+Author: NATC Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Jatinverma0786/NATC
+Project-URL: Documentation, https://github.com/Jatinverma0786/NATC#readme
+Project-URL: Repository, https://github.com/Jatinverma0786/NATC
+Keywords: tensor-compression,inference,llm,sparse-attention,neural-cache
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.1
+Requires-Dist: transformers>=4.40
+Requires-Dist: accelerate>=0.28
+Requires-Dist: sentence-transformers>=2.6
+Requires-Dist: faiss-cpu>=1.8
+Requires-Dist: numba>=0.59
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: safetensors>=0.4
+Requires-Dist: scipy>=1.10
+Provides-Extra: openvino
+Requires-Dist: openvino>=2024.0; extra == "openvino"
+Provides-Extra: triton
+Requires-Dist: triton>=2.3; extra == "triton"
+Provides-Extra: llama-cpp
+Requires-Dist: llama-cpp-python>=0.2; extra == "llama-cpp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# NATC
+
+NATC, short for NeuroSymbolic Adaptive Tensor Compression, is a Python framework for
+experimenting with CPU-first dynamic inference architecture:
+
+- latent Knowledge DNA encoding for tensors and model state dictionaries
+- on-demand weight reconstruction and sparse materialization
+- prompt-routed reasoning capsules
+- predictive sparse attention routing
+- persistent neural fragment caching
+- recursive fractal tensor storage
+- prompt compilation into execution plans
+- CPU-oriented kernels and benchmark utilities
+
+Install from a local checkout:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Public API:
+
+```python
+from natc import NATCModel
+
+model = NATCModel.from_pretrained("distilgpt2")
+model.enable_dna()
+model.enable_capsules()
+model.enable_sparse_attention()
+model.enable_cache()
+model.enable_cpu_acceleration()
+
+print(model.generate("Explain quantum mechanics"))
+```
+
+The HuggingFace backend is loaded lazily. If a remote model cannot be downloaded in
+the current environment, NATC falls back to a deterministic local text backend so the
+compression, routing, caching, and compiler pipeline remains testable offline.
+
+## Quick Encoder Example
+
+```python
+import numpy as np
+from natc.dna import encode_model, decode_model
+
+state = {"linear.weight": np.random.default_rng(0).normal(size=(64, 32))}
+dna = encode_model(state, rank=8)
+reconstructed = decode_model(dna)
+
+print(dna.compression_ratio())
+print(reconstructed["linear.weight"].shape)
+```
+
+## Benchmark
+
+```bash
+natc-benchmark --layers 4 --rows 128 --cols 128 --rank 16
+```
+
+The benchmark reports compression ratio, memory saved, synthetic tokens/sec, cache hit
+ratio, latency, throughput, and CPU efficiency in JSON.
+

natc-0.1.0/README.md

@@ -0,0 +1,62 @@
+# NATC
+
+NATC, short for NeuroSymbolic Adaptive Tensor Compression, is a Python framework for
+experimenting with CPU-first dynamic inference architecture:
+
+- latent Knowledge DNA encoding for tensors and model state dictionaries
+- on-demand weight reconstruction and sparse materialization
+- prompt-routed reasoning capsules
+- predictive sparse attention routing
+- persistent neural fragment caching
+- recursive fractal tensor storage
+- prompt compilation into execution plans
+- CPU-oriented kernels and benchmark utilities
+
+Install from a local checkout:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Public API:
+
+```python
+from natc import NATCModel
+
+model = NATCModel.from_pretrained("distilgpt2")
+model.enable_dna()
+model.enable_capsules()
+model.enable_sparse_attention()
+model.enable_cache()
+model.enable_cpu_acceleration()
+
+print(model.generate("Explain quantum mechanics"))
+```
+
+The HuggingFace backend is loaded lazily. If a remote model cannot be downloaded in
+the current environment, NATC falls back to a deterministic local text backend so the
+compression, routing, caching, and compiler pipeline remains testable offline.
+
+## Quick Encoder Example
+
+```python
+import numpy as np
+from natc.dna import encode_model, decode_model
+
+state = {"linear.weight": np.random.default_rng(0).normal(size=(64, 32))}
+dna = encode_model(state, rank=8)
+reconstructed = decode_model(dna)
+
+print(dna.compression_ratio())
+print(reconstructed["linear.weight"].shape)
+```
+
+## Benchmark
+
+```bash
+natc-benchmark --layers 4 --rows 128 --cols 128 --rank 16
+```
+
+The benchmark reports compression ratio, memory saved, synthetic tokens/sec, cache hit
+ratio, latency, throughput, and CPU efficiency in JSON.
+

natc-0.1.0/natc/__init__.py

@@ -0,0 +1,7 @@
+"""Public package interface for NATC."""
+
+from natc.config import NATCConfig
+from natc.model import NATCModel
+
+__all__ = ["NATCConfig", "NATCModel"]
+

natc-0.1.0/natc/attention/__init__.py

@@ -0,0 +1,123 @@
+"""Predictive sparse attention routing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from natc.utils import text_embedding
+
+
+@dataclass(slots=True)
+class SparseAttentionResult:
+    """Sparse attention output and its selected graph."""
+
+    output: np.ndarray
+    weights: np.ndarray
+    adjacency: np.ndarray
+
+
+class SparseGraphBuilder:
+    """Build top-k token adjacency graphs from similarity scores."""
+
+    def build(self, scores: np.ndarray, *, top_k: int) -> np.ndarray:
+        if scores.ndim != 2:
+            raise ValueError("scores must be a 2D matrix")
+        top_k = max(1, min(top_k, scores.shape[1]))
+        adjacency = np.zeros_like(scores, dtype=bool)
+        indices = np.argpartition(scores, -top_k, axis=1)[:, -top_k:]
+        rows = np.arange(scores.shape[0])[:, None]
+        adjacency[rows, indices] = True
+        return adjacency
+
+
+class AttentionRouter:
+    """Predict likely attention paths before dense attention execution."""
+
+    def __init__(self, *, top_k: int = 32) -> None:
+        self.top_k = top_k
+        self.graph_builder = SparseGraphBuilder()
+
+    def route_tokens(self, tokens: list[str], *, top_k: int | None = None) -> np.ndarray:
+        if not tokens:
+            return np.zeros((0, 0), dtype=bool)
+        embeddings = np.stack([text_embedding(token, dimensions=64) for token in tokens])
+        scores = embeddings @ embeddings.T
+        return self.graph_builder.build(scores, top_k=top_k or self.top_k)
+
+    def route_embeddings(self, embeddings: np.ndarray, *, top_k: int | None = None) -> np.ndarray:
+        embeddings = _as_2d(embeddings)
+        scores = embeddings @ embeddings.T / max(1.0, float(embeddings.shape[-1]) ** 0.5)
+        return self.graph_builder.build(scores, top_k=top_k or self.top_k)
+
+
+class PredictiveAttention:
+    """Compute sparse scaled dot-product attention using predicted top-k edges."""
+
+    def __init__(self, *, top_k: int = 32) -> None:
+        self.router = AttentionRouter(top_k=top_k)
+
+    def __call__(
+        self,
+        query: np.ndarray,
+        key: np.ndarray,
+        value: np.ndarray,
+        *,
+        top_k: int | None = None,
+    ) -> SparseAttentionResult:
+        return self.forward(query, key, value, top_k=top_k)
+
+    def forward(
+        self,
+        query: np.ndarray,
+        key: np.ndarray,
+        value: np.ndarray,
+        *,
+        top_k: int | None = None,
+    ) -> SparseAttentionResult:
+        query = _as_2d(query)
+        key = _as_2d(key)
+        value = _as_2d(value)
+        if query.shape[-1] != key.shape[-1]:
+            raise ValueError("query and key dimensions must match")
+        if key.shape[0] != value.shape[0]:
+            raise ValueError("key and value token counts must match")
+
+        scores = query @ key.T / max(1.0, float(query.shape[-1]) ** 0.5)
+        adjacency = SparseGraphBuilder().build(scores, top_k=top_k or self.router.top_k)
+        masked_scores = np.where(adjacency, scores, -np.inf)
+        weights = _softmax(masked_scores, axis=1)
+        output = weights @ value
+        return SparseAttentionResult(
+            output=output.astype(np.float32, copy=False),
+            weights=weights.astype(np.float32, copy=False),
+            adjacency=adjacency,
+        )
+
+
+def _softmax(values: np.ndarray, *, axis: int) -> np.ndarray:
+    maximum = np.max(values, axis=axis, keepdims=True)
+    shifted = np.exp(values - maximum)
+    shifted[~np.isfinite(values)] = 0.0
+    denom = shifted.sum(axis=axis, keepdims=True)
+    denom[denom == 0.0] = 1.0
+    return shifted / denom
+
+
+def _as_2d(array: np.ndarray) -> np.ndarray:
+    array = np.asarray(array, dtype=np.float32)
+    if array.ndim == 1:
+        return array.reshape(1, -1)
+    if array.ndim != 2:
+        raise ValueError("attention arrays must be 1D or 2D")
+    return array
+
+
+__all__ = [
+    "AttentionRouter",
+    "PredictiveAttention",
+    "SparseAttentionResult",
+    "SparseGraphBuilder",
+]
+

natc-0.1.0/natc/benchmark/__init__.py

@@ -0,0 +1,135 @@
+"""Benchmark suite for NATC."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import time
+import tracemalloc
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from natc.cache import NeuralCache
+from natc.dna import decode_model, encode_model
+from natc.model import NATCModel
+
+
+@dataclass(slots=True)
+class BenchmarkResult:
+    """NATC benchmark metrics."""
+
+    compression_ratio: float
+    memory_saved: float
+    speedup: float
+    cpu_efficiency: float
+    tokens_per_sec: float
+    cache_hit_ratio: float
+    latency: float
+    throughput: float
+
+    def to_dict(self) -> dict[str, float]:
+        return {
+            "compression_ratio": self.compression_ratio,
+            "memory_saved": self.memory_saved,
+            "speedup": self.speedup,
+            "cpu_efficiency": self.cpu_efficiency,
+            "tokens_per_sec": self.tokens_per_sec,
+            "cache_hit_ratio": self.cache_hit_ratio,
+            "latency": self.latency,
+            "throughput": self.throughput,
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2, sort_keys=True)
+
+
+class BenchmarkRunner:
+    """Run synthetic compression and inference benchmarks."""
+
+    def __init__(
+        self,
+        *,
+        layers: int = 4,
+        rows: int = 128,
+        cols: int = 128,
+        rank: int = 16,
+        seed: int = 13,
+    ) -> None:
+        self.layers = layers
+        self.rows = rows
+        self.cols = cols
+        self.rank = rank
+        self.seed = seed
+
+    def run(self) -> BenchmarkResult:
+        state = self._synthetic_state()
+
+        tracemalloc.start()
+        start = time.perf_counter()
+        dense_outputs = _dense_reference(state)
+        dense_latency = time.perf_counter() - start
+        dense_current, dense_peak = tracemalloc.get_traced_memory()
+
+        start = time.perf_counter()
+        dna = encode_model(state, rank=self.rank)
+        reconstructed = decode_model(dna)
+        compressed_outputs = _dense_reference(reconstructed)
+        compressed_latency = time.perf_counter() - start
+        compressed_current, compressed_peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cache = NeuralCache(tmpdir)
+            cache.put("python pattern", {"value": "cached"})
+            cache.get("python pattern")
+            cache.get("python patterns")
+            cache_hit_ratio = cache.hit_ratio()
+
+        model = NATCModel.from_state_dict(state, rank=self.rank)
+        generated_start = time.perf_counter()
+        output = model.generate("Explain a Python matrix multiplication pattern", max_new_tokens=32)
+        generated_latency = max(time.perf_counter() - generated_start, 1e-9)
+        token_count = max(1, len(output.split()))
+
+        dense_memory = max(dense_peak, dense_current, 1)
+        compressed_memory = max(compressed_peak - dense_peak, compressed_current, 1)
+        memory_saved = max(0.0, 1.0 - (compressed_memory / dense_memory))
+        speedup = dense_latency / max(compressed_latency, 1e-9)
+        throughput = len(compressed_outputs) / max(compressed_latency, 1e-9)
+        cpu_efficiency = min(1.0, speedup / max(1.0, self.rank))
+
+        return BenchmarkResult(
+            compression_ratio=dna.compression_ratio(),
+            memory_saved=memory_saved,
+            speedup=speedup,
+            cpu_efficiency=cpu_efficiency,
+            tokens_per_sec=token_count / generated_latency,
+            cache_hit_ratio=cache_hit_ratio,
+            latency=compressed_latency,
+            throughput=throughput,
+        )
+
+    def _synthetic_state(self) -> dict[str, np.ndarray]:
+        rng = np.random.default_rng(self.seed)
+        state = {}
+        base_left = rng.normal(size=(self.rows, self.rank)).astype(np.float32)
+        base_right = rng.normal(size=(self.rank, self.cols)).astype(np.float32)
+        for layer in range(self.layers):
+            noise = rng.normal(scale=0.01, size=(self.rows, self.cols)).astype(np.float32)
+            state[f"layers.{layer}.weight"] = base_left @ base_right + noise
+        return state
+
+
+def run_benchmark(**kwargs: Any) -> dict[str, float]:
+    return BenchmarkRunner(**kwargs).run().to_dict()
+
+
+def _dense_reference(state: dict[str, np.ndarray]) -> list[np.ndarray]:
+    vector = np.ones((next(iter(state.values())).shape[1], 1), dtype=np.float32)
+    return [weight @ vector for weight in state.values()]
+
+
+__all__ = ["BenchmarkResult", "BenchmarkRunner", "run_benchmark"]
+

natc-0.1.0/natc/benchmark/cli.py

@@ -0,0 +1,30 @@
+"""Command-line benchmark runner."""
+
+from __future__ import annotations
+
+import argparse
+
+from natc.benchmark import BenchmarkRunner
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run NATC benchmark suite.")
+    parser.add_argument("--layers", type=int, default=4)
+    parser.add_argument("--rows", type=int, default=128)
+    parser.add_argument("--cols", type=int, default=128)
+    parser.add_argument("--rank", type=int, default=16)
+    parser.add_argument("--seed", type=int, default=13)
+    args = parser.parse_args()
+    result = BenchmarkRunner(
+        layers=args.layers,
+        rows=args.rows,
+        cols=args.cols,
+        rank=args.rank,
+        seed=args.seed,
+    ).run()
+    print(result.to_json())
+
+
+if __name__ == "__main__":
+    main()
+