natc 0.1.0__py3-none-any.whl

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/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/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/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()
+

natc/cache/__init__.py

@@ -0,0 +1,217 @@
+"""Neural fragment cache with RAM and persistent disk storage."""
+
+from __future__ import annotations
+
+import json
+import pickle
+import sqlite3
+import time
+from contextlib import closing
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from natc.utils import cosine_similarity, stable_hash, text_embedding
+
+
+@dataclass(slots=True)
+class CacheRecord:
+    """A stored neural fragment."""
+
+    key: str
+    text: str
+    payload: Any
+    embedding: np.ndarray
+    metadata: dict[str, Any]
+    created_at: float
+    last_accessed: float
+
+
+class FragmentStore:
+    """SQLite-backed persistent fragment store."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._initialize()
+
+    def put(
+        self,
+        key: str,
+        text: str,
+        payload: Any,
+        embedding: np.ndarray,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        now = time.time()
+        with closing(sqlite3.connect(self.path)) as conn:
+            with conn:
+                conn.execute(
+                    """
+                    INSERT OR REPLACE INTO fragments
+                    (key, text, payload, embedding, metadata, created_at, last_accessed)
+                    VALUES (?, ?, ?, ?, ?, COALESCE((SELECT created_at FROM fragments WHERE key = ?), ?), ?)
+                    """,
+                    (
+                        key,
+                        text,
+                        pickle.dumps(payload),
+                        np.asarray(embedding, dtype=np.float32).tobytes(),
+                        json.dumps(metadata or {}),
+                        key,
+                        now,
+                        now,
+                    ),
+                )
+
+    def get(self, key: str) -> CacheRecord | None:
+        with closing(sqlite3.connect(self.path)) as conn:
+            with conn:
+                row = conn.execute(
+                    """
+                    SELECT key, text, payload, embedding, metadata, created_at, last_accessed
+                    FROM fragments WHERE key = ?
+                    """,
+                    (key,),
+                ).fetchone()
+                if row is None:
+                    return None
+                conn.execute(
+                    "UPDATE fragments SET last_accessed = ? WHERE key = ?",
+                    (time.time(), key),
+                )
+        return _row_to_record(row)
+
+    def all(self) -> list[CacheRecord]:
+        with closing(sqlite3.connect(self.path)) as conn:
+            rows = conn.execute(
+                """
+                SELECT key, text, payload, embedding, metadata, created_at, last_accessed
+                FROM fragments
+                """
+            ).fetchall()
+        return [_row_to_record(row) for row in rows]
+
+    def _initialize(self) -> None:
+        with closing(sqlite3.connect(self.path)) as conn:
+            with conn:
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS fragments (
+                        key TEXT PRIMARY KEY,
+                        text TEXT NOT NULL,
+                        payload BLOB NOT NULL,
+                        embedding BLOB NOT NULL,
+                        metadata TEXT NOT NULL,
+                        created_at REAL NOT NULL,
+                        last_accessed REAL NOT NULL
+                    )
+                    """
+                )
+
+
+class PatternIndexer:
+    """Similarity lookup for cached prompt and reasoning fragments."""
+
+    def __init__(self, store: FragmentStore) -> None:
+        self.store = store
+
+    def lookup(self, text: str, *, top_k: int = 3) -> list[tuple[CacheRecord, float]]:
+        query = text_embedding(text)
+        scored = [
+            (record, cosine_similarity(query, record.embedding))
+            for record in self.store.all()
+        ]
+        scored.sort(key=lambda item: item[1], reverse=True)
+        return scored[:top_k]
+
+
+class NeuralCache:
+    """Two-level RAM plus disk neural fragment cache."""
+
+    def __init__(
+        self,
+        cache_dir: str | Path,
+        *,
+        similarity_threshold: float = 0.84,
+        max_ram_items: int = 512,
+    ) -> None:
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.store = FragmentStore(self.cache_dir / "fragments.sqlite3")
+        self.indexer = PatternIndexer(self.store)
+        self.similarity_threshold = similarity_threshold
+        self.max_ram_items = max_ram_items
+        self._ram: dict[str, CacheRecord] = {}
+        self.hits = 0
+        self.misses = 0
+
+    def key_for(self, text: str) -> str:
+        return stable_hash({"text": text.strip().lower()})
+
+    def put(
+        self,
+        text: str,
+        payload: Any,
+        *,
+        key: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        cache_key = key or self.key_for(text)
+        embedding = text_embedding(text)
+        self.store.put(cache_key, text, payload, embedding, metadata=metadata)
+        record = self.store.get(cache_key)
+        if record is not None:
+            self._remember(record)
+        return cache_key
+
+    def get(self, text_or_key: str, *, exact: bool = False) -> Any | None:
+        key = text_or_key if exact else self.key_for(text_or_key)
+        record = self._ram.get(key) or self.store.get(key)
+        if record is not None:
+            self.hits += 1
+            self._remember(record)
+            return record.payload
+        if exact:
+            self.misses += 1
+            return None
+        similar = self.lookup(text_or_key, top_k=1)
+        if similar and similar[0][1] >= self.similarity_threshold:
+            self.hits += 1
+            self._remember(similar[0][0])
+            return similar[0][0].payload
+        self.misses += 1
+        return None
+
+    def lookup(self, text: str, *, top_k: int = 3) -> list[tuple[CacheRecord, float]]:
+        return self.indexer.lookup(text, top_k=top_k)
+
+    def hit_ratio(self) -> float:
+        total = self.hits + self.misses
+        return float(self.hits / total) if total else 0.0
+
+    def _remember(self, record: CacheRecord) -> None:
+        if len(self._ram) >= self.max_ram_items:
+            oldest = min(self._ram.values(), key=lambda item: item.last_accessed)
+            self._ram.pop(oldest.key, None)
+        self._ram[record.key] = record
+
+
+def _row_to_record(row: tuple[Any, ...]) -> CacheRecord:
+    key, text, payload_blob, embedding_blob, metadata_json, created_at, last_accessed = row
+    embedding = np.frombuffer(embedding_blob, dtype=np.float32).copy()
+    return CacheRecord(
+        key=str(key),
+        text=str(text),
+        payload=pickle.loads(payload_blob),
+        embedding=embedding,
+        metadata=json.loads(metadata_json),
+        created_at=float(created_at),
+        last_accessed=float(last_accessed),
+    )
+
+
+__all__ = ["CacheRecord", "FragmentStore", "NeuralCache", "PatternIndexer"]

natc/capsules/__init__.py

@@ -0,0 +1,160 @@
+"""Prompt-routed reasoning capsules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from natc.utils import cosine_similarity, text_embedding
+
+
+@dataclass(slots=True)
+class ReasoningCapsule:
+    """A lightweight expert region selected from prompt semantics."""
+
+    name: str
+    keywords: tuple[str, ...]
+    description: str
+    activation_cost: float = 1.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def score(self, prompt: str) -> float:
+        lowered = prompt.lower()
+        keyword_hits = sum(1 for keyword in self.keywords if keyword.lower() in lowered)
+        keyword_score = keyword_hits / max(1, len(self.keywords))
+        semantic_score = cosine_similarity(
+            text_embedding(prompt),
+            text_embedding(f"{self.name} {self.description} {' '.join(self.keywords)}"),
+        )
+        return float(0.68 * keyword_score + 0.32 * max(0.0, semantic_score))
+
+    def execute(self, prompt: str, context: dict[str, Any] | None = None) -> dict[str, Any]:
+        return {
+            "capsule": self.name,
+            "score": self.score(prompt),
+            "context": context or {},
+            "embedding": text_embedding(prompt, dimensions=32),
+        }
+
+
+class MathCapsule(ReasoningCapsule):
+    def __init__(self) -> None:
+        super().__init__(
+            name="math",
+            keywords=("math", "proof", "equation", "calculate", "algebra", "geometry"),
+            description="symbolic arithmetic, equations, proofs, and quantitative reasoning",
+        )
+
+
+class CodeCapsule(ReasoningCapsule):
+    def __init__(self) -> None:
+        super().__init__(
+            name="code",
+            keywords=("code", "python", "function", "bug", "api", "class", "compile"),
+            description="software engineering, debugging, APIs, and programming languages",
+        )
+
+
+class CreativeCapsule(ReasoningCapsule):
+    def __init__(self) -> None:
+        super().__init__(
+            name="creative",
+            keywords=("story", "write", "poem", "brand", "creative", "voice", "scene"),
+            description="creative writing, style, narrative, and ideation",
+        )
+
+
+class ScienceCapsule(ReasoningCapsule):
+    def __init__(self) -> None:
+        super().__init__(
+            name="science",
+            keywords=("physics", "biology", "chemistry", "experiment", "theory", "quantum"),
+            description="scientific explanation, experiments, and technical concepts",
+        )
+
+
+class MedicalCapsule(ReasoningCapsule):
+    def __init__(self) -> None:
+        super().__init__(
+            name="medical",
+            keywords=("medical", "health", "symptom", "clinical", "diagnosis", "treatment"),
+            description="medical terminology, health context, and careful clinical reasoning",
+        )
+
+
+class CapsuleRouter:
+    """Score and select capsules for a prompt."""
+
+    def __init__(self, capsules: list[ReasoningCapsule] | None = None) -> None:
+        self.capsules = capsules or [
+            MathCapsule(),
+            CodeCapsule(),
+            CreativeCapsule(),
+            ScienceCapsule(),
+            MedicalCapsule(),
+        ]
+
+    def route(
+        self,
+        prompt: str,
+        *,
+        top_k: int = 3,
+        threshold: float = 0.05,
+    ) -> list[tuple[ReasoningCapsule, float]]:
+        scored = [(capsule, capsule.score(prompt)) for capsule in self.capsules]
+        scored.sort(key=lambda item: item[1], reverse=True)
+        selected = [(capsule, score) for capsule, score in scored[:top_k] if score >= threshold]
+        if selected:
+            return selected
+        best = scored[0]
+        return [best] if best[1] > 0.0 else []
+
+
+class CapsuleManager:
+    """Register, activate, and inspect prompt capsules."""
+
+    def __init__(self, capsules: list[ReasoningCapsule] | None = None) -> None:
+        self.router = CapsuleRouter(capsules)
+        self.active: dict[str, float] = {}
+
+    def select(self, prompt: str, *, top_k: int = 3) -> list[ReasoningCapsule]:
+        routed = self.router.route(prompt, top_k=top_k)
+        self.active = {capsule.name: score for capsule, score in routed}
+        return [capsule for capsule, _ in routed]
+
+    def activation_vector(self) -> np.ndarray:
+        names = [capsule.name for capsule in self.router.capsules]
+        return np.asarray([self.active.get(name, 0.0) for name in names], dtype=np.float32)
+
+
+class CapsuleExecutor:
+    """Execute active capsules and merge their activation summaries."""
+
+    def execute(
+        self,
+        capsules: list[ReasoningCapsule],
+        prompt: str,
+        *,
+        context: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        results = [capsule.execute(prompt, context=context) for capsule in capsules]
+        if not results:
+            return {"capsules": [], "activation": np.zeros(32, dtype=np.float32)}
+        activation = np.mean([item["embedding"] for item in results], axis=0)
+        return {"capsules": results, "activation": activation.astype(np.float32)}
+
+
+__all__ = [
+    "CapsuleExecutor",
+    "CapsuleManager",
+    "CapsuleRouter",
+    "CodeCapsule",
+    "CreativeCapsule",
+    "MathCapsule",
+    "MedicalCapsule",
+    "ReasoningCapsule",
+    "ScienceCapsule",
+]
+