rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/prompts.py

@@ -0,0 +1,331 @@
+"""Markdown prompt template system: discovery, loading, rendering, and slash-command expansion."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+# ── constants ──────────────────────────────────────────────────────────────
+
+_MD_SUFFIX = ".md"
+_FRONT_MATTER_RE = re.compile(r"\A---[ \t]*\n(.*?\n)---[ \t]*\n", re.DOTALL)
+_PLACEHOLDER_RE = re.compile(r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}")
+_RESERVED_PREFIXES = ("skill:",)
+_ARGUMENT_ALIASES = frozenset({"arguments", "args"})
+
+
+# ── diagnostic severity ───────────────────────────────────────────────────
+
+
+class Severity(Enum):
+    """Non-fatal diagnostic severity level."""
+
+    INFO = "info"
+    WARNING = "warning"
+
+
+# ── data models ────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class PromptTemplate:
+    """An immutable, loaded markdown prompt template."""
+
+    name: str
+    path: Path
+    content: str
+    description: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateDiagnostic:
+    """A non-fatal issue encountered during template discovery."""
+
+    severity: Severity
+    path: Path
+    message: str
+
+
+# ── errors ─────────────────────────────────────────────────────────────────
+
+
+class TemplateLoadError(Exception):
+    """Fatal error while loading a template file."""
+
+
+class TemplateRenderError(Exception):
+    """A required placeholder variable was not supplied."""
+
+
+# ── front-matter helpers ──────────────────────────────────────────────────
+
+
+def _parse_front_matter(text: str) -> tuple[dict[str, str], str]:
+    """Split optional YAML front matter from the markdown body."""
+    match = _FRONT_MATTER_RE.match(text)
+    if match is None:
+        return {}, text
+
+    raw = match.group(1)
+    body = text[match.end():]
+    meta: dict[str, str] = {}
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        colon = stripped.find(":")
+        if colon < 1:
+            continue
+        key = stripped[:colon].strip()
+        value = stripped[colon + 1:].strip()
+        if len(value) >= 2 and value[0] in ('"', "'") and value[-1] == value[0]:
+            value = value[1:-1]
+        meta[key] = value
+    return meta, body
+
+
+def _derive_description(body: str) -> str | None:
+    """Extract the first non-heading, non-blank line as a description."""
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("#"):
+            continue
+        if stripped.startswith("---"):
+            continue
+        return stripped
+    return None
+
+
+# ── single-file loading ───────────────────────────────────────────────────
+
+
+def _template_name_from_path(path: Path) -> str:
+    """Derive a template name from a file path (stem without extension)."""
+    return path.stem
+
+
+def _load_template_file(path: Path) -> PromptTemplate:
+    """Read a single markdown file and return a ``PromptTemplate``."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise TemplateLoadError(f"Cannot read {path}: {exc}") from exc
+    except UnicodeDecodeError as exc:
+        raise TemplateLoadError(f"{path} is not valid UTF-8: {exc}") from exc
+
+    meta, body = _parse_front_matter(raw)
+    name = meta.get("name", _template_name_from_path(path))
+    description = meta.get("description") or _derive_description(body)
+
+    return PromptTemplate(
+        name=name,
+        path=path,
+        content=body,
+        description=description,
+    )
+
+
+# ── directory discovery ───────────────────────────────────────────────────
+
+
+def _discover_in_directory(
+    root: Path,
+) -> tuple[list[PromptTemplate], list[TemplateDiagnostic]]:
+    """Scan *root* for ``.md`` files and load them as templates."""
+    templates: list[PromptTemplate] = []
+    diagnostics: list[TemplateDiagnostic] = []
+    seen: dict[str, Path] = {}
+
+    if not root.is_dir():
+        return templates, diagnostics
+
+    for child in sorted(root.iterdir()):
+        if child.is_dir():
+            continue
+        if child.suffix.lower() != _MD_SUFFIX:
+            continue
+
+        try:
+            tpl = _load_template_file(child)
+        except TemplateLoadError as exc:
+            diagnostics.append(TemplateDiagnostic(
+                severity=Severity.WARNING,
+                path=child,
+                message=str(exc),
+            ))
+            continue
+
+        if tpl.name in seen:
+            diagnostics.append(TemplateDiagnostic(
+                severity=Severity.WARNING,
+                path=child,
+                message=(
+                    f"Duplicate template name {tpl.name!r}; "
+                    f"already loaded from {seen[tpl.name]}"
+                ),
+            ))
+            continue
+
+        seen[tpl.name] = child
+        templates.append(tpl)
+
+    return templates, diagnostics
+
+
+# ── public loading API ─────────────────────────────────────────────────────
+
+
+def load_prompt_templates_with_diagnostics(
+    resource_dirs: Sequence[Path],
+) -> tuple[list[PromptTemplate], list[TemplateDiagnostic]]:
+    """Load templates from multiple resource directories with diagnostics."""
+    combined: dict[str, PromptTemplate] = {}
+    all_diagnostics: list[TemplateDiagnostic] = []
+
+    for root in resource_dirs:
+        templates, diags = _discover_in_directory(root)
+        all_diagnostics.extend(diags)
+        for tpl in templates:
+            if tpl.name not in combined:
+                combined[tpl.name] = tpl
+
+    return list(combined.values()), all_diagnostics
+
+
+def load_prompt_templates(resource_dirs: Sequence[Path]) -> list[PromptTemplate]:
+    """Load templates from resource directories, discarding diagnostics."""
+    templates, _ = load_prompt_templates_with_diagnostics(resource_dirs)
+    return templates
+
+
+# ── placeholder utilities ─────────────────────────────────────────────────
+
+
+def _collect_placeholders(content: str) -> set[str]:
+    """Return the set of placeholder names found in *content*."""
+    return set(_PLACEHOLDER_RE.findall(content))
+
+
+def _references_arguments(content: str) -> bool:
+    """Return whether *content* contains an ``{{arguments}}`` or ``{{args}}`` placeholder."""
+    return bool(_ARGUMENT_ALIASES & _collect_placeholders(content))
+
+
+# ── rendering ──────────────────────────────────────────────────────────────
+
+
+def render_template(
+    template: PromptTemplate,
+    variables: Mapping[str, str] | None = None,
+    *,
+    strict: bool = True,
+    missing_value: str = "",
+) -> str:
+    """Render a template by replacing ``{{ var }}`` placeholders."""
+    vars_ = variables or {}
+
+    def _replace(match: re.Match[str]) -> str:
+        name = match.group(1)
+        if name in vars_:
+            return vars_[name]
+        if strict:
+            raise TemplateRenderError(
+                f"Missing variable {name!r} in template {template.name!r}"
+            )
+        return missing_value
+
+    return _PLACEHOLDER_RE.sub(_replace, template.content)
+
+
+# ── slash-command parsing ──────────────────────────────────────────────────
+
+
+def _is_reserved_command(name: str) -> bool:
+    """Return whether *name* belongs to another command system."""
+    return any(name.startswith(prefix) for prefix in _RESERVED_PREFIXES)
+
+
+def _parse_slash_command(text: str) -> tuple[str, str] | None:
+    """Parse ``/<name> args…`` into ``(name, args)`` or return ``None``."""
+    if not text.startswith("/"):
+        return None
+    if text.startswith("//"):
+        return None
+
+    body = text[1:]
+    parts = body.split(None, 1)
+    if not parts:
+        return None
+
+    name = parts[0]
+    if _is_reserved_command(name):
+        return None
+
+    arguments = parts[1] if len(parts) > 1 else ""
+    return name, arguments
+
+
+def _lookup_template(
+    name: str,
+    registry: Mapping[str, PromptTemplate],
+) -> PromptTemplate | None:
+    """Find a template by name, returning ``None`` on miss."""
+    return registry.get(name)
+
+
+def _build_variables(arguments: str) -> dict[str, str]:
+    """Build the default variable mapping for a slash-command invocation."""
+    return {"arguments": arguments, "args": arguments}
+
+
+def _maybe_append_arguments(rendered: str, arguments: str, content: str) -> str:
+    """Append *arguments* to *rendered* if the template never referenced them."""
+    if not arguments:
+        return rendered
+    if _references_arguments(content):
+        return rendered
+    return rendered + "\n\n" + arguments
+
+
+# ── public expansion API ───────────────────────────────────────────────────
+
+
+def expand_slash_command(
+    text: str,
+    registry: Mapping[str, PromptTemplate],
+    *,
+    extra_variables: Mapping[str, str] | None = None,
+) -> str | None:
+    """Expand a ``/<template-name> args…`` slash command."""
+    parsed = _parse_slash_command(text)
+    if parsed is None:
+        return None
+
+    name, arguments = parsed
+    tpl = _lookup_template(name, registry)
+    if tpl is None:
+        return None
+
+    variables = dict(extra_variables) if extra_variables else {}
+    variables.update(_build_variables(arguments))
+
+    rendered = render_template(tpl, variables, strict=False, missing_value="")
+    return _maybe_append_arguments(rendered, arguments, tpl.content)
+
+
+__all__ = [
+    "PromptTemplate",
+    "Severity",
+    "TemplateDiagnostic",
+    "TemplateLoadError",
+    "TemplateRenderError",
+    "expand_slash_command",
+    "load_prompt_templates",
+    "load_prompt_templates_with_diagnostics",
+    "render_template",
+]

rlmagent/prune.py

@@ -0,0 +1,60 @@
+"""`rlm-agent session prune`: find and remove old sessions and their undo snapshots."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import stat
+import sys
+from pathlib import Path
+from time import time
+
+from rlmagent.harness.session.index import SessionCatalog
+from rlmagent.undo import Shadow
+
+_SAFE_ID = re.compile(r"[\w-]+")
+
+
+def _size(path: Path) -> int:
+    if path.is_file():
+        return path.stat().st_size
+    return sum(p.stat().st_size for p in path.rglob("*") if p.is_file())
+
+
+def _remove(path: Path) -> None:
+    if path.is_file():
+        path.unlink()
+        return
+
+    def writable(function, name, _error):  # git marks its objects read-only on Windows
+        os.chmod(name, stat.S_IWRITE)
+        function(name)
+
+    shutil.rmtree(path, onexc=writable)
+
+
+def prune(base: Path, home: Path, days: int, *, apply: bool = False, out=sys.stdout) -> int:
+    """List what is older than `days`; removes it only when `apply` is set."""
+    catalog = SessionCatalog(base)
+    cutoff = time() - days * 86400
+    metas = catalog.list_all()
+    old = [m for m in metas if m.updated_at < cutoff and _SAFE_ID.fullmatch(m.session_id)]
+    kept = {Shadow(m.cwd, home).git_dir for m in metas if m not in old and m.cwd}
+    targets = [f for m in old for f in base.glob(f"{m.session_id}.*")]
+    shadows = {Shadow(m.cwd, home).git_dir for m in old if m.cwd} - kept
+    targets += [s for s in shadows if s.exists()]
+    total = sum(_size(t) for t in targets)
+    print(f"{len(old)} of {len(metas)} sessions are older than {days} days; "
+          f"{total / 1_000_000:.1f} MB in {len(targets)} files and snapshot folders.", file=out)
+    if not apply:
+        for target in targets[:20]:
+            print(f"  {target}", file=out)
+        if old:
+            print("Nothing was removed. Add --yes to remove these.", file=out)
+        return 0
+    for target in targets:
+        _remove(target)
+    catalog.remove({m.session_id for m in old})
+    print("Removed.", file=out)
+    return 0

rlmagent/reasoning.py

@@ -0,0 +1,135 @@
+"""Provider-neutral thinking mode primitives."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal
+
+# ── canonical levels ────────────────────────────────────────────────────
+
+ThinkingLevel = Literal["off", "minimal", "low", "medium", "high", "xhigh"]
+
+THINKING_LEVELS: tuple[ThinkingLevel, ...] = (
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+)
+
+DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium"
+
+THINKING_DESCRIPTIONS: dict[ThinkingLevel, str] = {
+    "off": "Thinking off",
+    "minimal": "Think a little",
+    "low": "Think briefly",
+    "medium": "Think normally",
+    "high": "Think hard",
+    "xhigh": "Think as long as allowed",
+}
+
+_LEVEL_SET: frozenset[str] = frozenset(THINKING_LEVELS)
+
+
+# ── validation ──────────────────────────────────────────────────────────
+
+
+def normalize_thinking_level(value: str | None) -> ThinkingLevel:
+    """Resolve *value* to a canonical thinking level."""
+    if value is None:
+        return DEFAULT_THINKING_LEVEL
+
+    cleaned = value.strip().lower()
+    if cleaned not in _LEVEL_SET:
+        available = ", ".join(THINKING_LEVELS)
+        raise ValueError(
+            f"Unknown thinking level {value!r}. "
+            f"Available levels: {available}"
+        )
+    return cleaned  # type: ignore[return-value]
+
+
+def normalize_thinking_levels(values: Sequence[str]) -> tuple[ThinkingLevel, ...]:
+    """Normalize a sequence of thinking-level strings."""
+    if not values:
+        raise ValueError("At least one thinking level is required")
+
+    result: list[ThinkingLevel] = []
+    seen: set[ThinkingLevel] = set()
+    for v in values:
+        level = normalize_thinking_level(v)
+        if level in seen:
+            raise ValueError(f"Duplicate thinking level: {level!r}")
+        seen.add(level)
+        result.append(level)
+    return tuple(result)
+
+
+# ── provider mappings ───────────────────────────────────────────────────
+
+# Each helper converts a ThinkingLevel into the parameter shape expected
+# by one family of model providers.  Provider names are intentionally kept
+# out of public API surface — callers pick the right helper via their own
+# provider resolution logic.
+
+_EFFORT_MAP: dict[ThinkingLevel, str] = {
+    "off": "none",
+    "minimal": "minimal",
+    "low": "low",
+    "medium": "medium",
+    "high": "high",
+    "xhigh": "xhigh",
+}
+
+_BUDGET_MAP: dict[ThinkingLevel, int | None] = {
+    "off": None,
+    "minimal": 1024,
+    "low": 2048,
+    "medium": 4096,
+    "high": 8192,
+    "xhigh": 16384,
+}
+
+
+def thinking_to_effort(level: ThinkingLevel) -> str:
+    """Map a thinking level to an effort-style parameter value."""
+    return _EFFORT_MAP[level]
+
+
+def thinking_to_budget(level: ThinkingLevel) -> int | None:
+    """Map a thinking level to a token-budget parameter value."""
+    return _BUDGET_MAP[level]
+
+
+# ── cycling helper ──────────────────────────────────────────────────────
+
+
+def next_thinking_level(
+    current: str,
+    *,
+    available: Sequence[ThinkingLevel] = THINKING_LEVELS,
+) -> ThinkingLevel:
+    """Return the level that follows *current* in *available*."""
+    if not available:
+        return DEFAULT_THINKING_LEVEL
+
+    cleaned = current.strip().lower()
+    for i, lvl in enumerate(available):
+        if lvl == cleaned:
+            return available[(i + 1) % len(available)]
+    # Unknown value — start from the beginning.
+    return available[0]
+
+
+__all__ = [
+    "DEFAULT_THINKING_LEVEL",
+    "THINKING_DESCRIPTIONS",
+    "THINKING_LEVELS",
+    "ThinkingLevel",
+    "next_thinking_level",
+    "normalize_thinking_level",
+    "normalize_thinking_levels",
+    "thinking_to_budget",
+    "thinking_to_effort",
+]

rlmagent/refinement/__init__.py

@@ -0,0 +1 @@
+"""Explicit, bounded updates to reusable agent guidance."""