pal-code 0.1.0__py3-none-any.whl

pal/notes_manager/pipeline.py

@@ -0,0 +1,138 @@
+"""The Notes Manager: everything about the notes the chat keeps across sessions, in one place.
+
+  * WHAT IS KEPT      only messages you typed (never attachments, never model replies), at least `min_chars` long, and never anything that
+                      looks like a secret (API keys, passwords, private keys).
+  * WHAT IS RECALLED  notes from *other* sessions that match the current question, within a token budget, added to that one request.
+  * UPKEEP            old notes beyond a cap are pruned; duplicate notes are merged in the background (no model, an OTHER-class job nobody
+                      waits for), every `tidy_every` turns.
+  * CONTROL           count, clear, forget one session's notes, and the RAM / disk numbers behind them.
+
+It sits on the Memory Manager (RAM cache, LRU-K eviction) which sits on the Storage Manager (the disk). It owns its own lock, so callers never
+have to. Nothing here leaves the machine except the recalled notes that go to the API model inside a request.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+
+from pal.config import MemoryConfig
+from pal.llm_scheduler.types import TaskClass
+from pal.notes_manager.components.privacy import looks_secret
+from pal.notes_manager.components.recall import Recall, build_recall
+from pal.notes_manager.components.tidy import tidy_steps
+from pal.tokens import estimate_tokens
+
+log = logging.getLogger(__name__)
+_MAX_NOTES_PRUNE = 50
+
+__all__ = ["NotesManager", "Recall", "looks_secret"]
+
+
+class NotesManager:
+    def __init__(self, sdk, cfg: MemoryConfig | dict | None = None, count: Callable[[str], int] = estimate_tokens,
+                 max_notes: int = 1000, scheduler=None):
+        self.sdk = sdk
+        self.cfg = MemoryConfig.coerce(cfg)
+        self.count = count
+        self.max_notes = max_notes
+        self.scheduler = scheduler
+        self._lock = threading.RLock()
+        self._new_notes = 0
+
+    @property
+    def enabled(self) -> bool:
+        return self.cfg.enabled
+
+    def attach_scheduler(self, scheduler) -> None:
+        """The scheduler that runs the background tidy-up (it needs a local line to run on)."""
+        self.scheduler = scheduler
+
+    # -- keeping and recalling --------------------------------------------------------------------------------------------
+    def remember(self, session_id: str, message: str) -> bool:
+        text = message.strip()
+        if not self.enabled or len(text) < self.cfg.min_chars or looks_secret(text):
+            return False
+        try:
+            with self._lock:
+                self.sdk.remember(text[:1000], tags=["user"], session_id=session_id)
+                self._prune()
+        except Exception:
+            log.exception("memory write failed")  # notes are best-effort: never fail the chat
+            return False
+        return True
+
+    def recall(self, session_id: str, query: str) -> Recall | None:
+        if not self.enabled or not self.cfg.recall_notes or not query.strip():
+            return None
+        try:
+            with self._lock:
+                notes = self.sdk.memory.retrieve(query, top_k=self.cfg.recall_notes * 3, min_score=self.cfg.min_score)
+        except Exception:
+            log.exception("memory recall failed")
+            return None
+        return build_recall(notes, session_id, self.cfg.recall_notes, self.cfg.budget_tokens, self.count)
+
+    # -- control ------------------------------------------------------------------------------------------------------------
+    def count_notes(self) -> int:
+        with self._lock:
+            return len(self.sdk.memory)
+
+    __len__ = count_notes
+
+    def clear(self) -> int:
+        with self._lock:
+            n = len(self.sdk.memory)
+            self.sdk.memory.clear()
+            self._new_notes = 0
+            return n
+
+    def forget_session(self, session_id: str) -> int:
+        """Delete the notes that one session wrote. Returns how many."""
+        with self._lock:
+            mine = [n for n in self.sdk.memory.storage.read_all() if n.session_id == session_id]
+            for n in mine:
+                self.sdk.memory.manager.delete(n.id)
+            return len(mine)
+
+    def stats(self) -> dict:
+        """How many notes there are, how they split between RAM and disk, how full the RAM cache is, and how many are new since the last tidy."""
+        with self._lock:
+            return {"enabled": self.enabled, "notes": len(self.sdk.memory), "since_tidy": self._new_notes, "max_notes": self.max_notes, **self.sdk.memory.stats()}
+
+    # -- upkeep -----------------------------------------------------------------------------------------------------------
+    def tidy_steps(self, near: float = 0.9, batch: int = 100):
+        """Merge duplicate and near-duplicate notes (see components/tidy.py). A generator, so a scheduler can pause it."""
+        return tidy_steps(self.sdk.memory, self._lock, near, batch)
+
+    def tidy(self) -> int:
+        """Run tidy_steps to the end. Returns how many notes were removed."""
+        gen = self.tidy_steps()
+        while True:
+            try:
+                next(gen)
+            except StopIteration as done:
+                return int(done.value or 0)
+
+    def after_turn(self, ephemeral: bool = False) -> None:
+        """Called after each chat turn. Every `tidy_every` turns it hands the tidy-up to the scheduler as a background job."""
+        local = getattr(self.scheduler, "local", None)
+        if ephemeral or local is None:
+            return
+        try:
+            every = self.cfg.tidy_every
+            self._new_notes += 1
+            if not every or not self.enabled or self._new_notes < every:
+                return
+            self._new_notes = 0
+            local.submit_steps(self.tidy_steps(), TaskClass.OTHER, "tidy memory")
+        except Exception:
+            log.exception("background upkeep could not be scheduled")      # never fail the chat because of housekeeping
+
+    def _prune(self) -> None:
+        over = len(self.sdk.memory) - self.max_notes
+        if over <= 0:
+            return
+        notes = sorted(self.sdk.memory.storage.read_all(), key=lambda n: (n.retrieval_count, n.timestamp))
+        for n in notes[: min(over + _MAX_NOTES_PRUNE, len(notes))]:
+            self.sdk.memory.manager.delete(n.id)

pal/orchestrator/__init__.py

@@ -0,0 +1,26 @@
+from pal.orchestrator.components.agent import Agent, AgentConfig
+from pal.orchestrator.components.cgroup_manager import (
+    CgroupError,
+    CgroupManager,
+    NullResourceManager,
+    ResourceLimits,
+    create_resource_manager,
+)
+from pal.orchestrator.components.context_interrupt import ContextInterruptController, InterruptResult
+from pal.orchestrator.components.scheduler import ScheduledAgent, Scheduler
+from pal.orchestrator.components.syscall_scheduler import (
+    SchedulingStrategy,
+    SyscallRequest,
+    SyscallScheduler,
+    SyscallStatus,
+)
+from pal.orchestrator.pipeline import OrchestratorPipeline
+
+__all__ = [
+    "OrchestratorPipeline",
+    "Agent", "AgentConfig",
+    "CgroupManager", "CgroupError", "NullResourceManager", "ResourceLimits", "create_resource_manager",
+    "Scheduler", "ScheduledAgent",
+    "ContextInterruptController", "InterruptResult",
+    "SchedulingStrategy", "SyscallRequest", "SyscallScheduler", "SyscallStatus",
+]

pal/orchestrator/components/__init__.py

@@ -0,0 +1,26 @@
+from pal.orchestrator.components import limits
+from pal.orchestrator.components.agent import Agent, AgentConfig
+from pal.orchestrator.components.cgroup_manager import (
+    CgroupError,
+    CgroupManager,
+    NullResourceManager,
+    ResourceLimits,
+    create_resource_manager,
+)
+from pal.orchestrator.components.context_interrupt import ContextInterruptController, InterruptResult
+from pal.orchestrator.components.scheduler import ScheduledAgent, Scheduler
+from pal.orchestrator.components.syscall_scheduler import (
+    SchedulingStrategy,
+    SyscallRequest,
+    SyscallScheduler,
+    SyscallStatus,
+)
+
+__all__ = [
+    "Agent", "AgentConfig",
+    "CgroupManager", "CgroupError", "NullResourceManager", "ResourceLimits", "create_resource_manager",
+    "Scheduler", "ScheduledAgent",
+    "ContextInterruptController", "InterruptResult",
+    "SchedulingStrategy", "SyscallRequest", "SyscallScheduler", "SyscallStatus",
+    "limits",
+]

pal/orchestrator/components/agent.py

@@ -0,0 +1,105 @@
+import multiprocessing as mp
+from dataclasses import dataclass
+
+from pal.orchestrator.components.cgroup_manager import CgroupManager, ResourceLimits
+
+
+def _agent_worker(backend: str, model: str, host: str, task_q: mp.Queue, result_q: mp.Queue):
+    """
+    Runs inside the child process. Imports pal lazily, here, not
+    at module level -- the parent process doesn't need pal
+    importable to manage cgroups/scheduling, only the child that
+    actually runs a Pipeline does. Keeps the orchestrator's own
+    dependency footprint minimal.
+    """
+    from pal.llm_wrapper.components.base import WrapperConfig
+    from pal.pipeline import Pipeline
+
+    pipeline = Pipeline(WrapperConfig(backend=backend, model=model, host=host))
+
+    while True:
+        task = task_q.get()
+        if task is None:
+            break
+        system_prompt, user_message = task
+        try:
+            result = pipeline.run(system_prompt, user_message)
+            result_q.put(("ok", result, pipeline.summary()))
+        except Exception as e:
+            result_q.put(("error", str(e), None))
+
+
+@dataclass
+class AgentConfig:
+    name: str
+    backend: str = "ollama"
+    model: str = "llama3"
+    host: str = "http://localhost:11434"
+    limits: ResourceLimits = None
+
+
+class Agent:
+    """
+    One agent = one real OS process running a Pal Pipeline, bound
+    to its own cgroup slice. The cgroup enforces the resource envelope;
+    the process boundary is what makes that enforcement meaningful
+    (unlike an in-process object, which shares the parent's resource
+    pool).
+    """
+
+    def __init__(self, config: AgentConfig, cgroup_manager: CgroupManager):
+        self.config = config
+        self.cgroup_manager = cgroup_manager
+        self.process: mp.Process | None = None
+        self.task_q: mp.Queue = mp.Queue()
+        self.result_q: mp.Queue = mp.Queue()
+        self._started = False
+
+    def start(self) -> None:
+        if self._started:
+            raise RuntimeError(f"agent {self.config.name} already started")
+
+        limits = self.config.limits or ResourceLimits(memory_max="512M", pids_max="50")
+        self.cgroup_manager.create_slice(self.config.name, limits)
+
+        self.process = mp.Process(
+            target=_agent_worker,
+            args=(self.config.backend, self.config.model, self.config.host, self.task_q, self.result_q),
+            daemon=True,
+        )
+        self.process.start()
+
+        # Assign immediately after spawn so the process's entire
+        # lifetime -- including model/library imports and any threads it
+        # spins up -- is subject to the cgroup's limits, not just the
+        # work it does after some later point.
+        self.cgroup_manager.assign_pid(self.config.name, self.process.pid)
+        self._started = True
+
+    def run_turn(self, system_prompt: str, user_message: str, timeout: float = 60) -> dict:
+        if not self._started:
+            raise RuntimeError(f"agent {self.config.name} not started")
+
+        self.task_q.put((system_prompt, user_message))
+        status, payload, summary = self.result_q.get(timeout=timeout)
+
+        if status == "error":
+            raise RuntimeError(f"agent {self.config.name} failed: {payload}")
+
+        return {"response": payload, "metrics": summary}
+
+    def stats(self) -> dict:
+        return self.cgroup_manager.stats(self.config.name)
+
+    def stop(self) -> None:
+        if not self._started:
+            return
+
+        self.task_q.put(None)
+        self.process.join(timeout=5)
+        if self.process.is_alive():
+            self.process.terminate()
+            self.process.join(timeout=5)
+
+        self.cgroup_manager.delete_slice(self.config.name)
+        self._started = False

pal/orchestrator/components/cgroup_manager.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+CGROUP_ROOT = Path("/sys/fs/cgroup")
+log = logging.getLogger(__name__)
+_SLICE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+_LIMIT_VALUE = re.compile(r"^[0-9A-Za-z ]{1,32}$")
+
+
+def _check_name(name: str) -> str:
+    """Slice names become directory names under /sys/fs/cgroup and are used in privileged commands,
+    so only plain names are accepted."""
+    if not _SLICE_NAME.match(name or "") or name.endswith("."):
+        raise CgroupError(f"invalid slice name: {name!r}")
+    return name
+
+
+def _check_value(value: str) -> str:
+    if not _LIMIT_VALUE.match(str(value)):
+        raise CgroupError(f"invalid limit value: {value!r}")
+    return str(value)
+
+
+@dataclass
+class ResourceLimits:
+    memory_max: str | None = None   # e.g. "256M", "1G"
+    cpu_max: str | None = None      # e.g. "50000 100000" = 50% of one CPU
+    pids_max: str | None = None     # e.g. "50"
+
+
+class CgroupError(RuntimeError):
+    pass
+
+
+class CgroupManager:
+    """
+    Creates and manages cgroup v2 slices, one per agent, under a single
+    parent slice (default: /sys/fs/cgroup/pal.slice/<agent_name>).
+
+    Requires root (via sudo) on this host -- WSL2's systemd user-session
+    delegation wasn't reliably attached to interactive shells here, so
+    operations run through `sudo` explicitly rather than assuming direct
+    write access. This is isolated behind this module so a future port
+    to a real delegated slice (or to a custom kernel) only changes
+    _run(), not any caller.
+    """
+
+    enforced = True
+
+    def __init__(self, parent_slice: str = "pal2.slice"):
+        self.parent_path = CGROUP_ROOT / _check_name(parent_slice)
+        self._ensure_parent()
+
+    @staticmethod
+    def supported() -> bool:
+        """Linux with cgroup v2 mounted, and either root or sudo to write to it."""
+        if not sys.platform.startswith("linux") or not (CGROUP_ROOT / "cgroup.controllers").exists():
+            return False
+        return _is_root() or shutil.which("sudo") is not None
+
+    def _privileged(self, cmd: list[str]) -> list[str]:
+        return cmd if _is_root() else ["sudo", *cmd]
+
+    def _run(self, cmd: list[str]) -> subprocess.CompletedProcess:
+        result = subprocess.run(self._privileged(cmd), capture_output=True, text=True)
+        if result.returncode != 0:
+            raise CgroupError(f"command failed: {' '.join(cmd)}\n{result.stderr}")
+        return result
+
+    def _write(self, path: Path, value: str) -> None:
+        # value goes in on stdin to `tee`: no shell, so nothing in `value` or `path` can inject a command
+        result = subprocess.run(self._privileged(["tee", str(path)]), input=f"{value}\n", capture_output=True,
+                                text=True)
+        if result.returncode != 0:
+            raise CgroupError(f"failed writing {value!r} to {path}: {result.stderr}")
+
+    def _ensure_parent(self) -> None:
+        if not self.parent_path.exists():
+            self._run(["mkdir", "-p", str(self.parent_path)])
+
+        # A cgroup only passes controllers down to its own children once
+        # they're explicitly enabled in *its* cgroup.subtree_control --
+        # inheriting them at the root level isn't enough. Without this,
+        # child slices exist as directories but reject writes to
+        # memory.max / cpu.max / pids.max with Permission denied.
+        root_subtree = CGROUP_ROOT / "cgroup.subtree_control"
+        if root_subtree.exists():
+            enabled = root_subtree.read_text(encoding="utf-8").split()
+            missing = [c for c in ("cpu", "memory", "pids") if c not in enabled]
+            if missing:
+                flags = " ".join(f"+{c}" for c in missing)
+                self._write(root_subtree, flags)
+
+        parent_subtree = self.parent_path / "cgroup.subtree_control"
+        if parent_subtree.exists():
+            enabled = parent_subtree.read_text(encoding="utf-8").split()
+            missing = [c for c in ("cpu", "memory", "pids") if c not in enabled]
+            if missing:
+                flags = " ".join(f"+{c}" for c in missing)
+                self._write(parent_subtree, flags)
+
+    def create_slice(self, agent_name: str, limits: ResourceLimits) -> Path:
+        slice_path = self.parent_path / _check_name(agent_name)
+        if slice_path.exists():
+            raise CgroupError(f"slice already exists: {agent_name}")
+
+        self._run(["mkdir", "-p", str(slice_path)])
+
+        if limits.memory_max:
+            self._write(slice_path / "memory.max", _check_value(limits.memory_max))
+        if limits.cpu_max:
+            self._write(slice_path / "cpu.max", _check_value(limits.cpu_max))
+        if limits.pids_max:
+            self._write(slice_path / "pids.max", _check_value(limits.pids_max))
+
+        return slice_path
+
+    def assign_pid(self, agent_name: str, pid: int) -> None:
+        slice_path = self.parent_path / agent_name
+        if not slice_path.exists():
+            raise CgroupError(f"no such slice: {agent_name}")
+        self._write(slice_path / "cgroup.procs", str(pid))
+
+    def current_pids(self, agent_name: str) -> list[int]:
+        slice_path = self.parent_path / agent_name
+        procs_file = slice_path / "cgroup.procs"
+        if not procs_file.exists():
+            raise CgroupError(f"no such slice: {agent_name}")
+        content = procs_file.read_text(encoding="utf-8").strip()
+        return [int(p) for p in content.splitlines() if p]
+
+    def stats(self, agent_name: str) -> dict:
+        slice_path = self.parent_path / agent_name
+        stats = {}
+        for fname in ("memory.current", "memory.max", "pids.current"):
+            fpath = slice_path / fname
+            if fpath.exists():
+                stats[fname] = fpath.read_text(encoding="utf-8").strip()
+        return stats
+
+    def delete_slice(self, agent_name: str) -> None:
+        slice_path = self.parent_path / agent_name
+        if not slice_path.exists():
+            return
+        # cgroups can only be removed once empty of processes.
+        pids = self.current_pids(agent_name)
+        if pids:
+            raise CgroupError(f"cannot delete slice {agent_name}: still has PIDs {pids}")
+        self._run(["rmdir", str(slice_path)])
+
+    def list_slices(self) -> list[str]:
+        if not self.parent_path.exists():
+            return []
+        return [p.name for p in self.parent_path.iterdir() if p.is_dir()]
+
+
+def _is_root() -> bool:
+    return hasattr(os, "geteuid") and os.geteuid() == 0
+
+
+class NullResourceManager:
+    """Used where cgroups are unavailable (macOS, Windows, Linux without cgroup v2 or sudo). Agents still
+    run as separate processes, but memory/CPU/process limits are NOT enforced. The orchestrator logs
+    that once, at construction."""
+
+    enforced = False
+
+    def __init__(self, parent_slice: str = "pal.slice"):
+        self.parent_slice = parent_slice
+        self._slices: dict[str, ResourceLimits] = {}
+
+    def create_slice(self, agent_name: str, limits: ResourceLimits):
+        if agent_name in self._slices:
+            raise CgroupError(f"slice already exists: {agent_name}")
+        self._slices[agent_name] = limits
+        return
+
+    def assign_pid(self, agent_name: str, pid: int) -> None:
+        if agent_name not in self._slices:
+            raise CgroupError(f"no such slice: {agent_name}")
+
+    def current_pids(self, agent_name: str) -> list[int]:
+        return []
+
+    def stats(self, agent_name: str) -> dict:
+        return {"enforced": False}
+
+    def delete_slice(self, agent_name: str) -> None:
+        self._slices.pop(agent_name, None)
+
+    def list_slices(self) -> list[str]:
+        return sorted(self._slices)
+
+
+def create_resource_manager(parent_slice: str = "pal.slice", manager_cls=CgroupManager):
+    """A real cgroup manager where the OS supports it, otherwise a no-op one (with a warning)."""
+    if manager_cls is not CgroupManager or CgroupManager.supported():
+        return manager_cls(parent_slice)
+    log.warning("cgroup v2 is not available here (needs Linux with cgroup v2 and root or sudo): agent "
+                "resource limits will NOT be enforced")
+    return NullResourceManager(parent_slice)