eigencore 0.4.0__py3-none-any.whl

eigencore/agent/policy.py

@@ -0,0 +1,262 @@
+"""
+Tool policy engine — Phase 4 (guardrails).
+
+Enforcement lives here, in code, below any UI: a tool call is denied unless
+its capability is explicitly allow-listed, and path arguments are confined to
+an authorized workspace root (symlinks resolved, traversal rejected). Every
+decision is written to an append-only audit log with sensitive values
+redacted.
+
+This is a policy layer, NOT a sandbox: handlers still run in-process. OS-level
+process isolation is a separate, later hardening step.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum, auto
+from pathlib import Path
+from typing import Any
+
+from eigencore.agent.tool import Tool, ToolCapability
+
+# Parameter names that look like paths and must stay inside the workspace.
+_PATH_PARAM_NAMES = {
+    "path",
+    "file",
+    "file_path",
+    "filename",
+    "target",
+    "dest",
+    "destination",
+    "dir",
+    "directory",
+    "folder",
+    "output_path",
+    "out",
+}
+
+# Parameter names whose values must never appear in audit logs.
+_SENSITIVE_PARAM_NAMES = {
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "api_key",
+    "apikey",
+    "access_key",
+    "private_key",
+    "auth",
+    "credential",
+    "credentials",
+}
+
+_SENSITIVE_RE = re.compile(
+    r"(?i)(password|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|authorization)\s*[:=]\s*\S+"
+)
+
+
+def _is_path_param(name: str) -> bool:
+    return name.lower() in _PATH_PARAM_NAMES
+
+
+def _is_sensitive_param(name: str) -> bool:
+    return name.lower() in _SENSITIVE_PARAM_NAMES
+
+
+def redact_text(text: str) -> str:
+    """Scrub obvious credential assignments from free text (tool output, errors)."""
+    return _SENSITIVE_RE.sub(r"\1=***REDACTED***", text)
+
+
+def redact_args(args: dict[str, Any]) -> dict[str, Any]:
+    return {k: ("***REDACTED***" if _is_sensitive_param(k) else v) for k, v in args.items()}
+
+
+@dataclass
+class PolicyDecision:
+    allowed: bool
+    reason: str
+    capability: ToolCapability | None = None
+
+
+@dataclass
+class AuditEntry:
+    timestamp: str
+    tool_name: str
+    capability: str
+    args: dict[str, Any]
+    decision: str  # "allowed" | "denied"
+    reason: str
+    status: str = ""
+    elapsed_seconds: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "timestamp": self.timestamp,
+            "tool_name": self.tool_name,
+            "capability": self.capability,
+            "args": self.args,
+            "decision": self.decision,
+            "reason": self.reason,
+            "status": self.status,
+            "elapsed_seconds": self.elapsed_seconds,
+        }
+
+
+class AuditLog:
+    """Append-only JSONL audit trail for tool decisions and outcomes."""
+
+    def __init__(self, path: Path | None = None):
+        self.path = Path(path) if path else None
+        self.entries: list[AuditEntry] = []
+
+    def record(self, entry: AuditEntry) -> None:
+        self.entries.append(entry)
+        if self.path is not None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry.to_dict(), default=str) + "\n")
+
+    def denied_count(self) -> int:
+        return sum(1 for e in self.entries if e.decision == "denied")
+
+
+def resolve_in_workspace(path_value: str, workspace_root: Path) -> Path:
+    """Resolve a path and require it to stay inside workspace_root.
+
+    Rejects absolute paths outside the root, `..` traversal, and symlinks
+    that resolve outside the root.
+    """
+    root = workspace_root.resolve()
+    candidate = Path(path_value)
+    if not candidate.is_absolute():
+        candidate = root / candidate
+    resolved = candidate.resolve()
+    if resolved != root and root not in resolved.parents:
+        raise ValueError(f"Path {path_value!r} resolves to {resolved}, outside workspace {root}")
+    return resolved
+
+
+@dataclass
+class PolicyEngine:
+    """Decides whether a tool call may run.
+
+    - Deny by default: a capability must be present in `allowed_capabilities`.
+    - If `workspace_root` is set, path-like string args must resolve inside it.
+    - Every decision is recorded in `audit_log`.
+    """
+
+    allowed_capabilities: set[ToolCapability] = field(default_factory=set)
+    workspace_root: Path | None = None
+    audit_log: AuditLog | None = None
+
+    def check(self, tool: Tool, args: dict[str, Any]) -> PolicyDecision:
+        cap = getattr(tool, "capability", ToolCapability.EXECUTE)
+        if cap not in self.allowed_capabilities:
+            decision = PolicyDecision(
+                allowed=False,
+                capability=cap,
+                reason=(
+                    f"capability {cap.name} is not allow-listed "
+                    f"(allowed: {sorted(c.name for c in self.allowed_capabilities) or 'none'})"
+                ),
+            )
+        else:
+            decision = PolicyDecision(
+                allowed=True, capability=cap, reason="capability allow-listed"
+            )
+
+        if decision.allowed and self.workspace_root is not None:
+            for param in tool.parameters:
+                if param.name in args and param.is_path and isinstance(args[param.name], str):
+                    try:
+                        resolve_in_workspace(args[param.name], self.workspace_root)
+                    except ValueError as e:
+                        decision = PolicyDecision(
+                            allowed=False,
+                            capability=cap,
+                            reason=str(e),
+                        )
+                        break
+
+        if self.audit_log is not None:
+            self.audit_log.record(
+                AuditEntry(
+                    timestamp=datetime.now(timezone.utc).isoformat(),
+                    tool_name=tool.name,
+                    capability=cap.name,
+                    args=redact_args(args),
+                    decision="allowed" if decision.allowed else "denied",
+                    reason=decision.reason,
+                )
+            )
+        return decision
+
+
+def default_policy(
+    workspace_root: Path | None = None, audit_log: AuditLog | None = None
+) -> PolicyEngine:
+    """Conservative default: read-only tools allowed, everything else denied."""
+    return PolicyEngine(
+        allowed_capabilities={ToolCapability.READ},
+        workspace_root=workspace_root,
+        audit_log=audit_log,
+    )
+
+
+class ApprovalMode(Enum):
+    """How a user approves a tool call. Enforcement stays in the policy engine;
+    this only records intent for the UI to ask."""
+
+    ASK = auto()  # ask every time (default)
+    SESSION = auto()  # approve once, allow same tool+capability for the session
+    DENY = auto()  # deny this call
+
+
+@dataclass
+class ApprovalRequest:
+    """A pending tool call awaiting user approval."""
+
+    tool_name: str
+    capability: str
+    args: dict[str, Any]  # already redacted for display
+    reason: str
+
+    def summary(self) -> str:
+        args = ", ".join(f"{k}={v!r}" for k, v in self.args.items())
+        return f"{self.tool_name}({args}) [{self.capability}] — {self.reason}"
+
+
+class ApprovalManager:
+    """Tracks approvals. The executor consults this AFTER policy passes but
+    BEFORE running; the UI renders the pending request and calls
+    `record()`. A session approval covers the same tool name only."""
+
+    def __init__(self, mode: ApprovalMode = ApprovalMode.ASK, audit_log: AuditLog | None = None):
+        self.mode = mode
+        self._session_approved: set[str] = set()
+        self.audit_log = audit_log
+
+    def needs_approval(self, tool_name: str) -> bool:
+        if self.mode is ApprovalMode.ASK:
+            return tool_name not in self._session_approved
+        return False
+
+    def record(self, tool_name: str, approved: bool, session: bool = False) -> None:
+        if approved and session:
+            self._session_approved.add(tool_name)
+        if self.audit_log is not None:
+            self.audit_log.record(
+                AuditEntry(
+                    timestamp=datetime.now(timezone.utc).isoformat(),
+                    tool_name=tool_name,
+                    capability="approval",
+                    args={"approved": approved, "session": session},
+                    decision="approved" if approved else "denied",
+                    reason="user approval",
+                )
+            )

eigencore/agent/react.py

@@ -0,0 +1,261 @@
+"""ReAct agent — interleaved reasoning and action on CPU.
+
+Implements the ReAct pattern (Yao et al., 2022): the model alternates
+between Thought (reasoning about what to do), Action (calling a tool),
+and Observation (reading the tool result). GBNF grammars force valid
+JSON at each step so there are no parsing failures or retry loops.
+
+The loop runs entirely on CPU using the existing InferenceEngine, with
+Phase 2 optimizations (layer skipping, sparsity, speculative decoding)
+active throughout.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any, Optional
+
+from eigencore.agent.executor import ToolExecutor, ToolResult
+from eigencore.agent.tool import ToolRegistry
+
+
+class StepKind(Enum):
+    THOUGHT = auto()
+    ACTION = auto()
+    OBSERVATION = auto()
+    FINAL = auto()
+
+
+@dataclass
+class AgentStep:
+    """A single step in the ReAct loop."""
+
+    kind: StepKind
+    content: str
+    tool_name: Optional[str] = None
+    tool_args: Optional[dict[str, Any]] = None
+    tool_result: Optional[ToolResult] = None
+    elapsed_seconds: float = 0.0
+
+
+@dataclass
+class AgentResult:
+    """Complete result of an agent run."""
+
+    answer: str
+    steps: list[AgentStep] = field(default_factory=list)
+    total_seconds: float = 0.0
+    total_tokens: int = 0
+
+    @property
+    def num_thoughts(self) -> int:
+        return sum(1 for s in self.steps if s.kind == StepKind.THOUGHT)
+
+    @property
+    def num_actions(self) -> int:
+        return sum(1 for s in self.steps if s.kind == StepKind.ACTION)
+
+    @property
+    def tool_calls(self) -> list[AgentStep]:
+        return [s for s in self.steps if s.kind == StepKind.ACTION]
+
+    def format_trace(self) -> str:
+        lines: list[str] = []
+        for i, step in enumerate(self.steps, 1):
+            prefix = f"[{i}] {step.kind.name}"
+            if step.kind == StepKind.THOUGHT:
+                lines.append(f"{prefix}: {step.content}")
+            elif step.kind == StepKind.ACTION:
+                lines.append(f"{prefix}: {step.tool_name}({step.tool_args})")
+            elif step.kind == StepKind.OBSERVATION:
+                lines.append(f"{prefix}: {step.content[:200]}")
+            elif step.kind == StepKind.FINAL:
+                lines.append(f"{prefix}: {step.content}")
+        return "\n".join(lines)
+
+
+_SYSTEM_PROMPT = """You are a helpful assistant with access to tools. To complete the user's task, reason step by step.
+
+At each step, output ONE of these JSON formats:
+
+To think about what to do:
+{{"type": "thought", "content": "your reasoning here"}}
+
+To call a tool:
+{{"type": "action", "tool": "tool_name", "args": {{"param": "value"}}}}
+
+To give your final answer (when you have enough information):
+{{"type": "final", "content": "your answer here"}}
+
+Available tools:
+{tools}
+
+Important:
+- Think before acting. Plan your approach.
+- After each tool result, decide if you need more information or can answer.
+- Always give a final answer. Do not end with a thought or action."""
+
+
+class ReActAgent:
+    """ReAct agent that reasons and acts using CPU-local LLM inference.
+
+    Uses GBNF grammar-constrained decoding to guarantee valid JSON at
+    every step. The grammar mask is applied during sampling — no retries
+    or output validation needed.
+    """
+
+    DEFAULT_MAX_STEPS = 10
+    DEFAULT_MAX_TOKENS_PER_STEP = 256
+
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        executor: Optional[ToolExecutor] = None,
+        max_steps: int = DEFAULT_MAX_STEPS,
+        max_tokens_per_step: int = DEFAULT_MAX_TOKENS_PER_STEP,
+        system_prompt: Optional[str] = None,
+    ):
+        self.registry = registry
+        self.executor = executor or ToolExecutor(registry)
+        self.max_steps = max_steps
+        self.max_tokens_per_step = max_tokens_per_step
+        self._system_prompt = system_prompt
+
+    @property
+    def system_prompt(self) -> str:
+        base = self._system_prompt or _SYSTEM_PROMPT
+        return base.format(tools=self.registry.format_for_prompt())
+
+    def build_messages(self, task: str, history: list[AgentStep]) -> list[dict[str, str]]:
+        messages: list[dict[str, str]] = [
+            {"role": "system", "content": self.system_prompt},
+            {"role": "user", "content": task},
+        ]
+
+        for step in history:
+            if step.kind == StepKind.THOUGHT:
+                msg = json.dumps({"type": "thought", "content": step.content})
+                messages.append({"role": "assistant", "content": msg})
+            elif step.kind == StepKind.ACTION:
+                msg = json.dumps(
+                    {
+                        "type": "action",
+                        "tool": step.tool_name,
+                        "args": step.tool_args,
+                    }
+                )
+                messages.append({"role": "assistant", "content": msg})
+            elif step.kind == StepKind.OBSERVATION:
+                messages.append({"role": "user", "content": f"Observation: {step.content}"})
+
+        return messages
+
+    def parse_step(self, raw: str) -> AgentStep:
+        """Parse a model output into an AgentStep.
+
+        Expects JSON constrained by GBNF grammar, but handles
+        malformed output gracefully.
+        """
+        raw = raw.strip()
+
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            return AgentStep(
+                kind=StepKind.THOUGHT,
+                content=raw,
+            )
+
+        step_type = parsed.get("type", "thought")
+
+        if step_type == "thought":
+            return AgentStep(
+                kind=StepKind.THOUGHT,
+                content=parsed.get("content", ""),
+            )
+        elif step_type == "action":
+            return AgentStep(
+                kind=StepKind.ACTION,
+                content="",
+                tool_name=parsed.get("tool"),
+                tool_args=parsed.get("args", {}),
+            )
+        elif step_type == "final":
+            return AgentStep(
+                kind=StepKind.FINAL,
+                content=parsed.get("content", ""),
+            )
+        else:
+            return AgentStep(kind=StepKind.THOUGHT, content=raw)
+
+    def execute_step(self, step: AgentStep) -> Optional[AgentStep]:
+        if step.kind != StepKind.ACTION or step.tool_name is None:
+            return None
+
+        result = self.executor.execute(step.tool_name, step.tool_args or {})
+        step.tool_result = result
+
+        return AgentStep(
+            kind=StepKind.OBSERVATION,
+            content=result.format_for_prompt(),
+            tool_result=result,
+        )
+
+    def run(
+        self,
+        task: str,
+        generate_fn=None,
+    ) -> AgentResult:
+        """Run the ReAct loop on a task.
+
+        Args:
+            task: The user's task/question.
+            generate_fn: A callable(messages, max_tokens) -> str that runs
+                inference. When None, the agent builds the step history
+                but requires an external caller to drive generation.
+        """
+        start = time.perf_counter()
+        steps: list[AgentStep] = []
+        total_tokens = 0
+
+        for _ in range(self.max_steps):
+            if generate_fn is None:
+                break
+
+            messages = self.build_messages(task, steps)
+            step_start = time.perf_counter()
+            raw_output = generate_fn(messages, self.max_tokens_per_step)
+            step_elapsed = time.perf_counter() - step_start
+
+            step = self.parse_step(raw_output)
+            step.elapsed_seconds = step_elapsed
+            steps.append(step)
+            total_tokens += len(raw_output) // 4
+
+            if step.kind == StepKind.FINAL:
+                break
+
+            if step.kind == StepKind.ACTION:
+                observation = self.execute_step(step)
+                if observation:
+                    steps.append(observation)
+
+        answer = ""
+        for step in reversed(steps):
+            if step.kind == StepKind.FINAL:
+                answer = step.content
+                break
+        if not answer and steps:
+            last_content = [s for s in steps if s.content]
+            if last_content:
+                answer = last_content[-1].content
+
+        return AgentResult(
+            answer=answer,
+            steps=steps,
+            total_seconds=time.perf_counter() - start,
+            total_tokens=total_tokens,
+        )

eigencore/agent/tool.py

@@ -0,0 +1,149 @@
+"""Tool definitions and registry for agent function calling."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any
+
+
+class ToolCapability(Enum):
+    """What a tool is allowed to do. Deny-by-default: nothing runs unless allowed."""
+
+    READ = auto()  # read files / pure computation
+    WRITE = auto()  # modify files
+    EXECUTE = auto()  # run processes / shell
+    NETWORK = auto()  # network access
+
+
+@dataclass(frozen=True)
+class ToolParam:
+    """A single parameter in a tool's signature."""
+
+    name: str
+    type: str  # "string", "integer", "number", "boolean"
+    description: str
+    required: bool = True
+    enum: tuple[str, ...] | None = None
+    default: Any = None
+    is_path: bool = False  # declare explicitly; policy confines these to the workspace
+
+    _TYPE_MAP = {
+        "string": str,
+        "integer": int,
+        "number": (int, float),
+        "boolean": bool,
+    }
+
+    def validate(self, value: Any) -> Any:
+        expected = self._TYPE_MAP.get(self.type)
+        if expected is None:
+            raise ValueError(f"Unknown param type: {self.type}")
+
+        if not isinstance(value, expected):
+            if self.type == "number" and isinstance(value, int):
+                value = float(value)
+            elif self.type == "integer" and isinstance(value, float) and value == int(value):
+                value = int(value)
+            else:
+                raise TypeError(
+                    f"Parameter '{self.name}' expects {self.type}, got {type(value).__name__}"
+                )
+
+        if self.enum and value not in self.enum:
+            raise ValueError(f"Parameter '{self.name}' must be one of {self.enum}, got {value!r}")
+
+        return value
+
+
+@dataclass
+class Tool:
+    """A callable tool that an agent can invoke."""
+
+    name: str
+    description: str
+    handler: Callable[..., Any]
+    parameters: list[ToolParam] = field(default_factory=list)
+    # What this tool does; the PolicyEngine denies anything not allow-listed.
+    capability: ToolCapability = ToolCapability.EXECUTE
+
+    def __post_init__(self):
+        if not self.name.isidentifier():
+            raise ValueError(f"Tool name must be a valid identifier, got {self.name!r}")
+
+    @property
+    def required_params(self) -> list[ToolParam]:
+        return [p for p in self.parameters if p.required]
+
+    @property
+    def optional_params(self) -> list[ToolParam]:
+        return [p for p in self.parameters if not p.required]
+
+    def param_names(self) -> set[str]:
+        return {p.name for p in self.parameters}
+
+    def validate_args(self, args: dict[str, Any]) -> dict[str, Any]:
+        validated: dict[str, Any] = {}
+
+        for param in self.required_params:
+            if param.name not in args:
+                raise ValueError(f"Missing required parameter: '{param.name}'")
+
+        for param in self.parameters:
+            if param.name in args:
+                validated[param.name] = param.validate(args[param.name])
+            elif not param.required and param.default is not None:
+                validated[param.name] = param.default
+
+        unknown = set(args.keys()) - self.param_names()
+        if unknown:
+            raise ValueError(f"Unknown parameters: {unknown}")
+
+        return validated
+
+    def format_for_prompt(self) -> str:
+        lines = [f"### {self.name}", f"{self.description}", "Parameters:"]
+        for p in self.parameters:
+            req = " (required)" if p.required else f" (optional, default={p.default!r})"
+            enum_hint = f", one of: {list(p.enum)}" if p.enum else ""
+            lines.append(f"  - {p.name} ({p.type}{enum_hint}): {p.description}{req}")
+        return "\n".join(lines)
+
+
+class ToolRegistry:
+    """Registry of tools available to an agent."""
+
+    def __init__(self):
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        if tool.name in self._tools:
+            raise ValueError(f"Tool '{tool.name}' already registered")
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def remove(self, name: str) -> bool:
+        return self._tools.pop(name, None) is not None
+
+    @property
+    def tools(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    @property
+    def tool_names(self) -> list[str]:
+        return list(self._tools.keys())
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools
+
+    def format_for_prompt(self) -> str:
+        if not self._tools:
+            return "No tools available."
+        sections = [tool.format_for_prompt() for tool in self._tools.values()]
+        return "\n\n".join(sections)

eigencore/analysis/__init__.py

@@ -0,0 +1,3 @@
+from eigencore.analysis.sparsity import SparsityAnalyzer
+
+__all__ = ["SparsityAnalyzer"]