eigencore 0.4.0__py3-none-any.whl

eigencore/fit/gguf_meta.py

@@ -0,0 +1,130 @@
+"""
+GGUF metadata reader - architecture-aware model geometry.
+
+Reads general.architecture and the per-architecture keys
+({arch}.block_count, {arch}.embedding_length, {arch}.attention.head_count,
+{arch}.attention.head_count_kv, {arch}.context_length) from a GGUF file.
+Prefers the pure-Python gguf package; falls back to llama_cpp.Llama.metadata
+when loadable that way. Returns None when neither is available.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from eigencore.fit.estimator import ModelGeometry
+
+
+@dataclass
+class GGUFModelInfo:
+    """Ground-truth facts read from a GGUF file."""
+
+    architecture: str | None
+    geometry: ModelGeometry
+    context_length: int | None
+    file_size_bytes: int | None
+    param_count: int | None
+
+
+def _field_value(field) -> object | None:
+    try:
+        part = field.parts[field.data[0]]
+        if part is None:
+            return None
+        return part.tolist()
+    except Exception:
+        return None
+
+
+def _from_gguf_package(path: Path) -> GGUFModelInfo | None:
+    try:
+        from gguf import GGUFReader
+    except ImportError:
+        return None
+    try:
+        reader = GGUFReader(str(path), mode="no")
+    except Exception:
+        return None
+    fields = {f.name: f for f in reader.fields.values()}
+
+    def get(*names: str):
+        for n in names:
+            f = fields.get(n)
+            if f is not None:
+                v = _field_value(f)
+                if v is not None:
+                    return v
+        return None
+
+    arch = get("general.architecture")
+    architecture = str(arch) if arch is not None else None
+    prefix = f"{architecture}." if architecture else "llama."
+
+    def arch_int(*names: str) -> int | None:
+        for n in names:
+            v = get(prefix + n, n)
+            if v is not None:
+                return int(v)
+        return None
+
+    geometry = ModelGeometry(
+        num_layers=arch_int("block_count"),
+        hidden_size=arch_int("embedding_length"),
+        num_attention_heads=arch_int("attention.head_count"),
+        num_kv_heads=arch_int("attention.head_count_kv"),
+        expert_count=arch_int("expert_count"),
+        expert_used_count=arch_int("expert_used_count"),
+    )
+    ctx = arch_int("context_length") or arch_int("attention.context_length")
+    params = get("general.parameter_count")
+    file_size = path.stat().st_size if path.exists() else None
+    return GGUFModelInfo(
+        architecture=architecture,
+        geometry=geometry,
+        context_length=ctx,
+        file_size_bytes=file_size,
+        param_count=int(params) if params is not None else None,
+    )
+
+
+def _from_llama_metadata(path: Path) -> GGUFModelInfo | None:
+    try:
+        from llama_cpp import Llama
+    except ImportError:
+        return None
+    try:
+        llm = Llama(model_path=str(path), n_ctx=256, verbose=False)
+        meta = dict(llm.metadata or {})
+    except Exception:
+        return None
+    arch = meta.get("general.architecture")
+    prefix = f"{arch}." if arch else "llama."
+
+    def m(name: str) -> int | None:
+        v = meta.get(prefix + name, meta.get(name))
+        return int(v) if v is not None else None
+
+    geometry = ModelGeometry(
+        num_layers=m("block_count"),
+        hidden_size=m("embedding_length"),
+        num_attention_heads=m("attention.head_count"),
+        num_kv_heads=m("attention.head_count_kv"),
+        expert_count=m("expert_count"),
+        expert_used_count=m("expert_used_count"),
+    )
+    return GGUFModelInfo(
+        architecture=arch,
+        geometry=geometry,
+        context_length=m("context_length"),
+        file_size_bytes=path.stat().st_size if path.exists() else None,
+        param_count=None,
+    )
+
+
+def read_gguf_model_info(path: str | Path) -> GGUFModelInfo | None:
+    """Best-effort GGUF metadata read; None when the file cannot be parsed."""
+    path = Path(path)
+    if not path.exists():
+        return None
+    return _from_gguf_package(path) or _from_llama_metadata(path)

eigencore/forge.py

@@ -0,0 +1,216 @@
+"""
+EigenCore — the unified API surface.
+
+Ties together all 4 layers into a single interface:
+  Layer 1: Hardware profiling (auto-detect and configure)
+  Layer 2: Inference (model loading, generation, streaming)
+  Layer 3: Training (QLoRA fine-tuning with adaptive epochs)
+  Layer 4: Agent orchestration (routing, context, tools) — Phase 3
+
+Usage:
+    from eigencore import Forge
+
+    forge = Forge()                           # auto-profiles hardware
+    print(forge.profile.summary())            # see what you're working with
+
+    result = forge.generate("Hello world")    # auto-downloads + runs best model
+    print(result.text)
+
+    for token in forge.stream("Tell me about Python"):
+        print(token, end="")
+
+    decision = forge.route("Write a sorting algorithm")
+    print(decision.domain, decision.model.name)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator, Optional
+
+from eigencore.agent.executor import ToolExecutor
+from eigencore.agent.policy import PolicyEngine
+from eigencore.agent.react import AgentResult, ReActAgent
+from eigencore.agent.tool import ToolRegistry
+from eigencore.context.manager import ContextManager
+from eigencore.engine.inference import GenerationConfig, GenerationResult, InferenceEngine
+from eigencore.hal.profiler import HardwareProfile, profile_hardware
+from eigencore.models.registry import ModelRegistry, ModelSpec
+from eigencore.router.classifier import RoutingDecision, TaskRouter
+
+
+class Forge:
+    """
+    Main entry point for the EigenCore framework.
+
+    Auto-detects hardware, manages models, and provides inference +
+    routing through a single API.
+    """
+
+    def __init__(
+        self,
+        model_name: Optional[str] = None,
+        task: str = "general",
+        cache_dir: Optional[Path] = None,
+        context_db: Optional[Path] = None,
+    ):
+        self.profile: HardwareProfile = profile_hardware()
+        self.registry = ModelRegistry(cache_dir)
+        self.router = TaskRouter(self.profile, self.registry)
+        self.context = ContextManager(
+            max_context_tokens=self.profile.recommended_context_length,
+            db_path=context_db,
+        )
+
+        self._engine: Optional[InferenceEngine] = None
+        self._current_model: Optional[ModelSpec] = None
+        self._default_task = task
+
+        if model_name:
+            self._load_model(model_name)
+
+    def _load_model(self, name: Optional[str] = None, task: Optional[str] = None) -> None:
+        """Load a model by name or auto-select based on hardware + task."""
+        spec = self.registry.resolve(name, self.profile, task or self._default_task)
+
+        if self._current_model and self._current_model.name == spec.name:
+            return  # already loaded
+
+        # unload previous model
+        if self._engine and self._engine.is_loaded:
+            self._engine.unload()
+
+        # download if needed
+        if not self.registry.is_downloaded(spec):
+            self.registry.download(spec)
+
+        model_path = spec.local_path(self.registry.cache_dir)
+        self._engine = InferenceEngine(model_path, self.profile, spec)
+        self._engine.load()
+        self._current_model = spec
+
+    def _ensure_loaded(self, prompt: Optional[str] = None) -> None:
+        """Ensure a model is loaded, using routing if prompt is provided."""
+        if self._engine and self._engine.is_loaded:
+            if prompt:
+                decision = self.router.route(prompt)
+                if self._current_model and self.router.should_swap(self._current_model, decision):
+                    self._load_model(decision.model.name)
+            return
+        self._load_model()
+
+    def generate(
+        self,
+        prompt: str,
+        max_tokens: int = 512,
+        temperature: float = 0.7,
+        **kwargs,
+    ) -> GenerationResult:
+        """Generate a response. Auto-downloads model on first use."""
+        self._ensure_loaded(prompt)
+        config = GenerationConfig(
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stream=False,
+            **kwargs,
+        )
+        return self._engine.generate(prompt, config)
+
+    def stream(
+        self,
+        prompt: str,
+        max_tokens: int = 512,
+        temperature: float = 0.7,
+        **kwargs,
+    ) -> Iterator[str]:
+        """Stream tokens as they're generated."""
+        self._ensure_loaded(prompt)
+        config = GenerationConfig(
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stream=True,
+            **kwargs,
+        )
+        yield from self._engine.stream(prompt, config)
+
+    def chat(
+        self,
+        message: str,
+        max_tokens: int = 512,
+        temperature: float = 0.7,
+    ) -> GenerationResult:
+        """
+        Chat with context management. Messages are tracked and compressed
+        automatically using attention-aware windowing.
+        """
+        self._ensure_loaded(message)
+        self.context.add("user", message)
+        ctx = self.context.get_context()
+
+        messages = [{"role": m.role, "content": m.content} for m in ctx.messages]
+
+        config = GenerationConfig(max_tokens=max_tokens, temperature=temperature, stream=False)
+        result = self._engine.chat(messages, config)
+
+        self.context.add("assistant", result.text)
+        return result
+
+    def route(self, prompt: str) -> RoutingDecision:
+        """Classify a prompt and get the routing decision without generating."""
+        return self.router.route(prompt)
+
+    def unload(self) -> None:
+        """Release the current model from memory."""
+        if self._engine:
+            self._engine.unload()
+        self._current_model = None
+
+    def agent(
+        self,
+        tools: ToolRegistry,
+        max_steps: int = 10,
+        max_tokens_per_step: int = 256,
+        system_prompt: Optional[str] = None,
+        policy: Optional[PolicyEngine] = None,
+    ) -> ReActAgent:
+        """Create a ReAct agent backed by this Forge's inference engine.
+
+        The executor is deny-by-default even when no policy is passed.
+        """
+        return ReActAgent(
+            registry=tools,
+            executor=ToolExecutor(tools, policy=policy),
+            max_steps=max_steps,
+            max_tokens_per_step=max_tokens_per_step,
+            system_prompt=system_prompt,
+        )
+
+    def run_agent(
+        self,
+        task: str,
+        tools: ToolRegistry,
+        max_steps: int = 10,
+    ) -> AgentResult:
+        """Run an agent task end-to-end using this Forge's model."""
+        self._ensure_loaded(task)
+        react = self.agent(tools, max_steps=max_steps)
+
+        def generate_fn(messages, max_tokens):
+            config = GenerationConfig(max_tokens=max_tokens, temperature=0.3, stream=False)
+            result = self._engine.chat(messages, config)
+            return result.text
+
+        return react.run(task, generate_fn=generate_fn)
+
+    @property
+    def loaded_model(self) -> Optional[str]:
+        return self._current_model.name if self._current_model else None
+
+    @property
+    def context_stats(self) -> dict:
+        return {
+            "messages": self.context.message_count,
+            "tokens": self.context.token_count,
+            "max_tokens": self.context.max_context_tokens,
+            "utilization": self.context.token_count / self.context.max_context_tokens,
+        }

eigencore/hal/__init__.py

@@ -0,0 +1,3 @@
+from eigencore.hal.profiler import HardwareProfile, profile_hardware
+
+__all__ = ["HardwareProfile", "profile_hardware"]

eigencore/hal/_cpuid_win.py

@@ -0,0 +1,119 @@
+"""
+Windows-specific CPUID instruction set detection using ctypes and kernel32.
+Falls back to registry-based detection if direct CPUID is unavailable.
+"""
+
+from __future__ import annotations
+
+import winreg
+
+from eigencore.hal.profiler import InstructionSet
+
+
+def _check_registry_features() -> set[str]:
+    """Read CPU feature flags from Windows registry as fallback."""
+    features: set[str] = set()
+    try:
+        key = winreg.OpenKey(
+            winreg.HKEY_LOCAL_MACHINE,
+            r"HARDWARE\DESCRIPTION\System\CentralProcessor\0",
+        )
+        identifier, _ = winreg.QueryValueEx(key, "Identifier")
+        winreg.CloseKey(key)
+    except Exception:
+        pass
+    return features
+
+
+def _check_os_enabled_avx() -> bool:
+    """Check if the OS has enabled AVX state saving (XGETBV check)."""
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        if hasattr(kernel32, "IsProcessorFeaturePresent"):
+            # PF_XMMI64_INSTRUCTIONS_AVAILABLE = 10 (SSE2)
+            # PF_AVX_INSTRUCTIONS_AVAILABLE = 39 (Win10+)
+            # PF_AVX2_INSTRUCTIONS_AVAILABLE = 40 (Win10+)
+            return True
+        return True
+    except Exception:
+        return True
+
+
+def detect_isa_windows() -> InstructionSet:
+    """
+    Detect CPU instruction sets on Windows.
+    Uses IsProcessorFeaturePresent for basic detection,
+    environment variables and CPU name heuristics for extended sets.
+    """
+    isa = InstructionSet.NONE
+
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        ipfp = kernel32.IsProcessorFeaturePresent
+
+        # PF constants from winnt.h
+        PF_XMMI64_INSTRUCTIONS_AVAILABLE = 10  # SSE2
+        PF_SSE4_1_INSTRUCTIONS_AVAILABLE = 37  # SSE4.1
+        PF_SSE4_2_INSTRUCTIONS_AVAILABLE = 38  # SSE4.2
+        PF_AVX_INSTRUCTIONS_AVAILABLE = 39  # AVX
+        PF_AVX2_INSTRUCTIONS_AVAILABLE = 40  # AVX2
+        PF_AVX512F_INSTRUCTIONS_AVAILABLE = 41  # AVX-512F
+
+        if ipfp(PF_XMMI64_INSTRUCTIONS_AVAILABLE):
+            isa |= InstructionSet.SSE2
+        if ipfp(PF_SSE4_1_INSTRUCTIONS_AVAILABLE):
+            isa |= InstructionSet.SSE4_1
+        if ipfp(PF_SSE4_2_INSTRUCTIONS_AVAILABLE):
+            isa |= InstructionSet.SSE4_2
+        if ipfp(PF_AVX_INSTRUCTIONS_AVAILABLE):
+            isa |= InstructionSet.AVX
+            isa |= InstructionSet.FMA
+            isa |= InstructionSet.F16C
+        if ipfp(PF_AVX2_INSTRUCTIONS_AVAILABLE):
+            isa |= InstructionSet.AVX2
+        if ipfp(PF_AVX512F_INSTRUCTIONS_AVAILABLE):
+            isa |= InstructionSet.AVX512F
+            isa |= InstructionSet.AVX512BW
+    except Exception:
+        isa = _fallback_detection()
+
+    return isa
+
+
+def _fallback_detection() -> InstructionSet:
+    """Heuristic fallback based on CPU model name from registry."""
+    isa = InstructionSet.SSE2 | InstructionSet.SSE4_1 | InstructionSet.SSE4_2
+
+    try:
+        key = winreg.OpenKey(
+            winreg.HKEY_LOCAL_MACHINE,
+            r"HARDWARE\DESCRIPTION\System\CentralProcessor\0",
+        )
+        name, _ = winreg.QueryValueEx(key, "ProcessorNameString")
+        winreg.CloseKey(key)
+        name = name.lower()
+
+        # Intel generations with known ISA support
+        if any(g in name for g in ("i7-1", "i9-1", "i5-1", "i3-1", "i7-8", "i7-9")):
+            isa |= (
+                InstructionSet.AVX | InstructionSet.AVX2 | InstructionSet.FMA | InstructionSet.F16C
+            )
+        if any(g in name for g in ("i7-12", "i7-13", "i7-14", "i9-12", "i9-13", "i9-14")):
+            isa |= InstructionSet.AVX512F | InstructionSet.AVX512BW | InstructionSet.AVX512VNNI
+
+        # AMD Zen with known ISA support
+        if "ryzen" in name:
+            isa |= (
+                InstructionSet.AVX | InstructionSet.AVX2 | InstructionSet.FMA | InstructionSet.F16C
+            )
+        if any(g in name for g in ("ryzen 9 7", "ryzen 7 7", "ryzen 9 9")):
+            isa |= InstructionSet.AVX512F | InstructionSet.AVX512BW | InstructionSet.AVX512VNNI
+
+    except Exception:
+        isa |= InstructionSet.AVX | InstructionSet.AVX2
+
+    return isa