eigencore 0.4.0__py3-none-any.whl

eigencore/__init__.py

@@ -0,0 +1,82 @@
+"""EigenCore — CPU-first LLM intelligence runtime."""
+
+__version__ = "0.4.0"
+
+from eigencore.agent.executor import ToolExecutor, ToolResult
+from eigencore.agent.grammar import GBNFBuilder
+from eigencore.agent.policy import AuditLog, PolicyEngine, ToolCapability, default_policy
+from eigencore.agent.react import AgentResult, AgentStep, ReActAgent, StepKind
+from eigencore.agent.tool import Tool, ToolParam, ToolRegistry
+from eigencore.benchmark import (
+    DEFAULT_CASES,
+    BenchmarkReport,
+    QualityCase,
+    build_report,
+    run_cases,
+)
+from eigencore.context.manager import ContextManager
+from eigencore.engine.inference import GenerationConfig, GenerationResult, InferenceEngine
+from eigencore.engine.layer_skip import LayerSkipScheduler, SkipPlan, SkipStrategy
+from eigencore.engine.sparse_inference import SparseExecutionPlan, SparsityCache, SparsityPredictor
+from eigencore.engine.speculative import SpeculativeDecoder, SpeculativeResult
+from eigencore.fit import (
+    FitEstimate,
+    FitVerdict,
+    ModelGeometry,
+    estimate_fit,
+    max_context_for_budget,
+)
+from eigencore.forge import Forge
+from eigencore.hal.profiler import HardwareProfile, profile_hardware
+from eigencore.kernels import ScalarBackend, rms_norm
+from eigencore.models.registry import ModelRegistry, ModelSpec
+from eigencore.router.classifier import RoutingDecision, TaskDomain, TaskRouter
+
+__all__ = [
+    "DEFAULT_CASES",
+    "AgentResult",
+    "AgentStep",
+    "AuditLog",
+    "BenchmarkReport",
+    "ContextManager",
+    "FitEstimate",
+    "FitVerdict",
+    "Forge",
+    "GBNFBuilder",
+    "GenerationConfig",
+    "GenerationResult",
+    "HardwareProfile",
+    "InferenceEngine",
+    "LayerSkipScheduler",
+    "ModelGeometry",
+    "ModelRegistry",
+    "ModelSpec",
+    "PolicyEngine",
+    "QualityCase",
+    "ReActAgent",
+    "RoutingDecision",
+    "ScalarBackend",
+    "SkipPlan",
+    "SkipStrategy",
+    "SparseExecutionPlan",
+    "SparsityCache",
+    "SparsityPredictor",
+    "SpeculativeDecoder",
+    "SpeculativeResult",
+    "StepKind",
+    "TaskDomain",
+    "TaskRouter",
+    "Tool",
+    "ToolCapability",
+    "ToolExecutor",
+    "ToolParam",
+    "ToolRegistry",
+    "ToolResult",
+    "build_report",
+    "default_policy",
+    "estimate_fit",
+    "max_context_for_budget",
+    "profile_hardware",
+    "rms_norm",
+    "run_cases",
+]

eigencore/agent/__init__.py

@@ -0,0 +1,45 @@
+"""Agent framework — tool calling, GBNF grammars, and ReAct reasoning."""
+
+from eigencore.agent.executor import ToolExecutor, ToolResult
+from eigencore.agent.grammar import GBNFBuilder
+from eigencore.agent.policy import (
+    ApprovalManager,
+    ApprovalMode,
+    ApprovalRequest,
+    AuditEntry,
+    AuditLog,
+    PolicyDecision,
+    PolicyEngine,
+    ToolCapability,
+    default_policy,
+    redact_args,
+    redact_text,
+    resolve_in_workspace,
+)
+from eigencore.agent.react import AgentResult, AgentStep, ReActAgent, StepKind
+from eigencore.agent.tool import Tool, ToolParam, ToolRegistry
+
+__all__ = [
+    "ApprovalManager",
+    "ApprovalMode",
+    "ApprovalRequest",
+    "AgentResult",
+    "AgentStep",
+    "AuditEntry",
+    "AuditLog",
+    "GBNFBuilder",
+    "PolicyDecision",
+    "PolicyEngine",
+    "ReActAgent",
+    "StepKind",
+    "Tool",
+    "ToolCapability",
+    "ToolExecutor",
+    "ToolParam",
+    "ToolRegistry",
+    "ToolResult",
+    "default_policy",
+    "redact_args",
+    "redact_text",
+    "resolve_in_workspace",
+]

eigencore/agent/executor.py

@@ -0,0 +1,297 @@
+"""Safe tool execution with validation and timeouts."""
+
+from __future__ import annotations
+
+import os
+import pickle
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any
+
+from eigencore.agent.policy import (
+    ApprovalManager,
+    PolicyEngine,
+    default_policy,
+    redact_text,
+    resolve_in_workspace,
+)
+from eigencore.agent.tool import Tool, ToolRegistry
+
+
+class ToolStatus(Enum):
+    SUCCESS = auto()
+    ERROR = auto()
+    TIMEOUT = auto()
+    VALIDATION_ERROR = auto()
+    POLICY_DENIED = auto()
+
+
+@dataclass
+class ToolResult:
+    """Result of executing a tool."""
+
+    tool_name: str
+    status: ToolStatus
+    output: Any = None
+    error: str | None = None
+    elapsed_seconds: float = 0.0
+
+    @property
+    def ok(self) -> bool:
+        return self.status == ToolStatus.SUCCESS
+
+    def format_for_prompt(self) -> str:
+        if self.ok:
+            return f"[{self.tool_name}] Result: {self.output}"
+        return f"[{self.tool_name}] Error ({self.status.name}): {self.error}"
+
+
+@dataclass
+class ExecutionLog:
+    """Tracks all tool executions in an agent run."""
+
+    entries: list[ToolResult] = field(default_factory=list)
+
+    def add(self, result: ToolResult) -> None:
+        self.entries.append(result)
+
+    @property
+    def total_calls(self) -> int:
+        return len(self.entries)
+
+    @property
+    def success_count(self) -> int:
+        return sum(1 for e in self.entries if e.ok)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for e in self.entries if not e.ok)
+
+    @property
+    def total_time(self) -> float:
+        return sum(e.elapsed_seconds for e in self.entries)
+
+
+class ToolExecutor:
+    """Executes tools with policy enforcement, validation, killable timeouts, logging.
+
+    Deny-by-default: when no policy is passed, a `default_policy()` (READ-only,
+    workspace-confined) is used — an executor never runs a tool just because a
+    caller forgot to attach a policy.
+    """
+
+    DEFAULT_TIMEOUT = 30.0
+
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_output_chars: int = 4096,
+        policy: PolicyEngine | None = None,
+        max_cpu_seconds: int = 60,
+        max_memory_mb: int = 4096,
+        max_file_size_mb: int = 64,
+        max_processes: int = 0,  # 0 = do not set RLIMIT_NPROC (breaks library imports); >0 enables it
+        approver: ApprovalManager | None = None,
+        ask_fn=None,  # callable(tool_name, args) -> bool; required when approver needs a human
+    ):
+        self.registry = registry
+        self.timeout = timeout
+        self.max_output_chars = max_output_chars
+        self.policy = policy if policy is not None else default_policy()
+        # POSIX resource limits applied to the child process (best-effort;
+        # silently skipped on platforms without resource/preexec_fn).
+        self.max_cpu_seconds = max_cpu_seconds
+        self.max_memory_mb = max_memory_mb
+        self.max_file_size_mb = max_file_size_mb
+        self.max_processes = max_processes
+        self.approver = approver
+        self.ask_fn = ask_fn
+        self.log = ExecutionLog()
+
+    def execute(self, tool_name: str, args: dict[str, Any]) -> ToolResult:
+        tool = self.registry.get(tool_name)
+        if tool is None:
+            result = ToolResult(
+                tool_name=tool_name,
+                status=ToolStatus.ERROR,
+                error=f"Unknown tool: '{tool_name}'. Available: {self.registry.tool_names}",
+            )
+            self.log.add(result)
+            return result
+
+        # Policy enforcement happens BEFORE validation/running, in code —
+        # never in prompt text and never in the UI layer.
+        decision = self.policy.check(tool, args)
+        if not decision.allowed:
+            result = ToolResult(
+                tool_name=tool_name,
+                status=ToolStatus.POLICY_DENIED,
+                error=f"Denied by policy: {decision.reason}",
+            )
+            self.log.add(result)
+            if self.policy.audit_log is not None:
+                entry = self.policy.audit_log.entries[-1]
+                entry.status = ToolStatus.POLICY_DENIED.name
+            return result
+
+        # Approval gate: after policy, before validation/running. Enforcement
+        # is here in code; the UI only renders and collects the answer.
+        if self.approver is not None and self.approver.needs_approval(tool_name):
+            if self.ask_fn is None:
+                result = ToolResult(
+                    tool_name=tool_name,
+                    status=ToolStatus.POLICY_DENIED,
+                    error="Denied: approval required but no approval callback is attached",
+                )
+                self.log.add(result)
+                return result
+            approved = bool(self.ask_fn(tool_name, args))
+            self.approver.record(tool_name, approved)
+            if not approved:
+                result = ToolResult(
+                    tool_name=tool_name,
+                    status=ToolStatus.POLICY_DENIED,
+                    error="Denied by user approval",
+                )
+                self.log.add(result)
+                return result
+
+        try:
+            validated_args = tool.validate_args(args)
+        except (ValueError, TypeError) as e:
+            result = ToolResult(
+                tool_name=tool_name,
+                status=ToolStatus.VALIDATION_ERROR,
+                error=str(e),
+            )
+            self.log.add(result)
+            return result
+
+        # Resolve declared path params to workspace-confined absolute paths
+        # BEFORE the handler sees them (no raw outside-workspace paths).
+        if self.policy.workspace_root is not None:
+            for param in tool.parameters:
+                if (
+                    param.is_path
+                    and param.name in validated_args
+                    and isinstance(validated_args[param.name], str)
+                ):
+                    validated_args[param.name] = str(
+                        resolve_in_workspace(validated_args[param.name], self.policy.workspace_root)
+                    )
+
+        result = self._run_with_timeout(tool, validated_args)
+        self.log.add(result)
+        if self.policy.audit_log is not None:
+            entry = self.policy.audit_log.entries[-1]
+            entry.status = result.status.name
+            entry.elapsed_seconds = result.elapsed_seconds
+        return result
+
+    def _run_with_timeout(self, tool: Tool, args: dict[str, Any]) -> ToolResult:
+        """Run the handler in a child `python` process; on timeout, kill it.
+
+        A thread-pool timeout cannot stop a running handler; a child process
+        can. Uses subprocess+pickle (not multiprocessing spawn) because spawn
+        is unreliable under pytest on Windows. Handlers must be picklable
+        (top-level functions) — lambdas/closures are rejected up front.
+        """
+        start = time.perf_counter()
+        try:
+            payload = pickle.dumps((tool.handler, args))
+        except Exception as e:
+            return ToolResult(
+                tool_name=tool.name,
+                status=ToolStatus.ERROR,
+                error=f"handler/args not picklable for process isolation: {e}",
+                elapsed_seconds=time.perf_counter() - start,
+            )
+        proc = subprocess.Popen(
+            [sys.executable, "-c", _WORKER_CODE],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            preexec_fn=self._limits_fn() if os.name == "posix" else None,
+        )
+        try:
+            out, _ = proc.communicate(input=payload, timeout=self.timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.communicate()
+            return ToolResult(
+                tool_name=tool.name,
+                status=ToolStatus.TIMEOUT,
+                error=f"Tool execution timed out after {self.timeout}s (process killed)",
+                elapsed_seconds=self.timeout,
+            )
+        elapsed = time.perf_counter() - start
+        if proc.returncode != 0 or not out:
+            return ToolResult(
+                tool_name=tool.name,
+                status=ToolStatus.ERROR,
+                error=f"handler process exited with code {proc.returncode}",
+                elapsed_seconds=elapsed,
+            )
+        try:
+            kind, value = pickle.loads(out)
+        except Exception:
+            return ToolResult(
+                tool_name=tool.name,
+                status=ToolStatus.ERROR,
+                error="handler process returned an unreadable result",
+                elapsed_seconds=elapsed,
+            )
+        if kind == "ok":
+            output = value
+            if isinstance(value, str):
+                output = redact_text(value)
+                if len(output) > self.max_output_chars:
+                    output = output[: self.max_output_chars] + "... [truncated]"
+            return ToolResult(
+                tool_name=tool.name,
+                status=ToolStatus.SUCCESS,
+                output=output,
+                elapsed_seconds=elapsed,
+            )
+        return ToolResult(
+            tool_name=tool.name,
+            status=ToolStatus.ERROR,
+            error=redact_text(value),
+            elapsed_seconds=elapsed,
+        )
+
+    def _limits_fn(self):
+        """Build a preexec_fn applying rlimits to the child (POSIX only)."""
+        import resource
+
+        max_cpu = self.max_cpu_seconds
+        max_mem = self.max_memory_mb * 1024 * 1024
+        max_fsize = self.max_file_size_mb * 1024 * 1024
+        max_nproc = self.max_processes
+
+        def apply() -> None:
+            resource.setrlimit(resource.RLIMIT_CPU, (max_cpu, max_cpu + 5))
+            resource.setrlimit(resource.RLIMIT_AS, (max_mem, max_mem))
+            resource.setrlimit(resource.RLIMIT_FSIZE, (max_fsize, max_fsize))
+            if max_nproc > 0:
+                resource.setrlimit(resource.RLIMIT_NPROC, (max_nproc, max_nproc))
+
+        return apply
+
+
+_WORKER_CODE = """
+import pickle, sys, traceback
+try:
+    handler, args = pickle.loads(sys.stdin.buffer.read())
+    try:
+        result = handler(**args)
+        sys.stdout.buffer.write(pickle.dumps(("ok", result)))
+    except Exception as e:
+        sys.stdout.buffer.write(pickle.dumps(("err", f"{type(e).__name__}: {e}\\n{traceback.format_exc()}")))
+except Exception as e:
+    sys.stdout.buffer.write(pickle.dumps(("err", f"unpickle failed: {e}")))
+"""

eigencore/agent/grammar.py

@@ -0,0 +1,121 @@
+"""GBNF grammar builder for structured LLM output.
+
+GBNF (GGML BNF) is llama.cpp's grammar format for constraining token
+generation. On CPU this is nearly free — the grammar mask is applied
+during sampling with no extra forward passes. This gives CPU inference
+a structural advantage: guaranteed valid JSON tool calls without
+retries or validation loops.
+"""
+
+from __future__ import annotations
+
+from eigencore.agent.tool import Tool, ToolRegistry
+
+
+class GBNFBuilder:
+    """Builds GBNF grammars that constrain model output to valid structures."""
+
+    # reusable primitives
+    _WS = "ws ::= [ \\t\\n]*"
+    _STRING = r'string ::= "\"" ([^"\\] | "\\" .)* "\""'
+    _INTEGER = 'integer ::= "-"? [0-9]+'
+    _NUMBER = 'number ::= "-"? [0-9]+ ("." [0-9]+)?'
+    _BOOLEAN = 'boolean ::= "true" | "false"'
+
+    @classmethod
+    def tool_call_grammar(cls, registry: ToolRegistry) -> str:
+        if not registry.tools:
+            raise ValueError("Cannot build grammar for empty tool registry")
+
+        rules: list[str] = []
+        tool_alternatives: list[str] = []
+
+        for tool in registry.tools:
+            rule_name = f"call_{tool.name}"
+            tool_alternatives.append(rule_name)
+            rules.append(cls._tool_rule(tool, rule_name))
+
+        root = 'root ::= ws "{" ws tool_call ws "}" ws'
+        tool_union = "tool_call ::= " + " | ".join(tool_alternatives)
+
+        parts = [
+            root,
+            tool_union,
+            *rules,
+            cls._WS,
+            cls._STRING,
+            cls._INTEGER,
+            cls._NUMBER,
+            cls._BOOLEAN,
+        ]
+        return "\n".join(parts)
+
+    @classmethod
+    def json_object_grammar(cls, properties: dict[str, str]) -> str:
+        """Build a grammar for a fixed JSON object shape.
+
+        Args:
+            properties: mapping of key name → type ("string", "integer", "number", "boolean")
+        """
+        if not properties:
+            return 'root ::= ws "{" ws "}" ws\n' + cls._WS
+
+        pairs: list[str] = []
+        for key, val_type in properties.items():
+            type_rule = cls._type_to_rule(val_type)
+            pairs.append(f'"\\"" "{key}" "\\"" ws ":" ws {type_rule}')
+
+        body = ' ws "," ws '.join(pairs)
+        root = f'root ::= ws "{{" ws {body} ws "}}" ws'
+        return "\n".join([root, cls._WS, cls._STRING, cls._INTEGER, cls._NUMBER, cls._BOOLEAN])
+
+    @classmethod
+    def _tool_rule(cls, tool: Tool, rule_name: str) -> str:
+        name_literal = f'"\\"{tool.name}\\""'
+        tool_name_part = f'"\\"tool\\"" ws ":" ws {name_literal}'
+
+        if not tool.parameters:
+            args_part = '"\\"args\\"" ws ":" ws "{" ws "}"'
+            return f'{rule_name} ::= {tool_name_part} ws "," ws {args_part}'
+
+        param_pairs: list[str] = []
+        for param in tool.parameters:
+            type_rule = cls._type_to_rule(param.type)
+            if param.enum:
+                enum_alts = " | ".join(f'"\\"{v}\\""' for v in param.enum)
+                type_rule = f"({enum_alts})"
+            param_pair = f'"\\"{param.name}\\"" ws ":" ws {type_rule}'
+            param_pairs.append(param_pair)
+
+        args_body = ' ws "," ws '.join(param_pairs)
+        args_part = f'"\\"args\\"" ws ":" ws "{{" ws {args_body} ws "}}"'
+        return f'{rule_name} ::= {tool_name_part} ws "," ws {args_part}'
+
+    @staticmethod
+    def _type_to_rule(type_name: str) -> str:
+        mapping = {
+            "string": "string",
+            "integer": "integer",
+            "number": "number",
+            "boolean": "boolean",
+        }
+        rule = mapping.get(type_name)
+        if rule is None:
+            raise ValueError(f"Unsupported type for GBNF: {type_name}")
+        return rule
+
+    @classmethod
+    def thought_or_action_grammar(cls, registry: ToolRegistry) -> str:
+        """Grammar for ReAct: model must output either a thought or a tool call."""
+        tool_grammar = cls.tool_call_grammar(registry)
+
+        thought_rule = 'thought ::= "\\"thought\\"" ws ":" ws string'
+        action_rule = 'action ::= "\\"action\\"" ws ":" ws "{" ws tool_call ws "}"'
+
+        new_root = 'root ::= ws "{" ws (thought_block | action_block) ws "}" ws'
+        thought_block = 'thought_block ::= "\\"type\\"" ws ":" ws "\\"thought\\"" ws "," ws thought'
+        action_block = 'action_block ::= "\\"type\\"" ws ":" ws "\\"action\\"" ws "," ws action'
+
+        remaining = "\n".join(tool_grammar.split("\n")[1:])
+        parts = [new_root, thought_block, action_block, thought_rule, action_rule, remaining]
+        return "\n".join(parts)