sliceagent 0.1.0__py3-none-any.whl

sliceagent/finding_types.py

@@ -0,0 +1,70 @@
+"""Typed findings schema (item 14a) — deterministic classification of a promoted note into
+one of a small fixed vocabulary, so recall is sharper (a 'decision' reads differently from a
+'ruled-out' dead end). Pure + deterministic → testable offline, no LLM.
+
+Vocabulary (fixed, small — the point is sharp typed recall, not a taxonomy):
+    DECISION         — a choice was made / an approach was adopted
+    RESOLVED         — a question got answered / a bug was fixed / it now works
+    RULED_OUT        — an approach was tried and abandoned / didn't work (a dead end to avoid)
+    FILE_TOUCHED     — a concrete edit landed (the change set)
+    NOTE             — fallback: an observation with no stronger signal
+
+The classifier reads cheap lexical signals from the note text and the episode meta (was a
+file edited? did an error clear?). It is intentionally conservative: an ambiguous note stays
+NOTE rather than mis-typed. neocortex.py tags promoted lessons with the type; hippocampus.py
+renders it as a leading [TYPE] badge.
+
+NO-TRANSCRIPT INVARIANT: classification reads already-stored episode records; it produces a
+tag on a durable note, never new context.
+
+PUBLIC SIGNATURES (pinned):
+    DECISION, RESOLVED, RULED_OUT, FILE_TOUCHED, NOTE   # str constants
+    classify_finding(note: str, *, edited: bool = False, had_error: bool = False,
+                     resolved: bool = False) -> str
+    badge(kind: str) -> str                              # "[decision] " etc. (or "" for NOTE)
+"""
+from __future__ import annotations
+
+import re
+
+DECISION = "decision"
+RESOLVED = "resolved-question"
+RULED_OUT = "ruled-out"
+FILE_TOUCHED = "file-touched"
+NOTE = "note"
+
+_RULED_OUT_RE = re.compile(
+    r"\b(rule[ds]?\s+out|ruled out|doesn'?t work|didn'?t work|won'?t work|not\s+the\s+"
+    r"(cause|issue|problem)|dead\s*end|abandon(ed)?|gave up|turned out not|no longer "
+    r"(works|needed)|reverted|backed out)\b", re.I)
+# NOTE: "instead of" is deliberately NOT a ruled-out signal — it reads as a DECISION
+# ("use a queue instead of a list"). Ruled-out needs an explicit negative-outcome phrase.
+_DECISION_RE = re.compile(
+    r"\b(decided|decision|chose|choosing|will use|going with|approach|opt(ed)?\s+for|"
+    r"settled on|plan to|strategy|prefer)\b", re.I)
+_RESOLVED_RE = re.compile(
+    r"\b(fixed|resolved|works now|passing|solved|answer(ed)?|root cause|the (bug|issue|"
+    r"problem) was|turned out (to be|that)|because)\b", re.I)
+
+
+def classify_finding(note: str, *, edited: bool = False, had_error: bool = False,
+                     resolved: bool = False) -> str:
+    """Classify `note` into the fixed vocabulary. Precedence (strongest signal wins):
+    RULED_OUT (a dead end is the most valuable-to-flag and easiest to mis-file as RESOLVED) >
+    DECISION > RESOLVED > FILE_TOUCHED > NOTE. `edited`/`had_error`/`resolved` come from the
+    episode meta and reinforce the structural signal when the text is ambiguous."""
+    text = note or ""
+    if _RULED_OUT_RE.search(text):
+        return RULED_OUT
+    if _DECISION_RE.search(text):
+        return DECISION
+    if _RESOLVED_RE.search(text) or (had_error and resolved):
+        return RESOLVED
+    if edited:
+        return FILE_TOUCHED
+    return NOTE
+
+
+def badge(kind: str) -> str:
+    """Leading badge for rendering. NOTE → '' (the unmarked default keeps the index clean)."""
+    return "" if (not kind or kind == NOTE) else f"[{kind}] "

sliceagent/flags.py

@@ -0,0 +1,63 @@
+"""Experimental feature flags.
+
+A tiny env-driven registry so a not-yet-default feature can ship gated and OFF by default, then be
+flipped on by setting its `default=True` once proven. State is read LIVE from the environment on every
+call (nothing cached) so tests and process-env changes take effect immediately.
+
+Precedence:
+  1. master switch AGENT_EXPERIMENTAL_ALL truthy  → every flag ON
+  2. per-flag env AGENT_EXPERIMENTAL_<ID>         → forces ON/OFF when set to a recognized bool
+  3. the flag's registered `default`
+
+Usage: `flags.register(Flag("cron", "Scheduled tasks"))` once at import, then gate with
+`if flags.enabled("cron"): ...`. An unknown id resolves False (typo-safe).
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+MASTER_ENV = "AGENT_EXPERIMENTAL_ALL"
+
+
+@dataclass(frozen=True)
+class Flag:
+    id: str
+    description: str = ""
+    default: bool = False
+
+    @property
+    def env(self) -> str:
+        return "AGENT_EXPERIMENTAL_" + self.id.upper()
+
+
+_FLAGS: dict[str, Flag] = {}
+
+
+def register(flag: Flag) -> Flag:
+    """Register (or replace) a flag. Returns it so a module can `MY = register(Flag(...))`."""
+    _FLAGS[flag.id] = flag
+    return flag
+
+
+def _parse_bool(value: str | None) -> bool | None:
+    if value is None:
+        return None
+    v = value.strip().lower()
+    if v in ("1", "true", "yes", "on"):
+        return True
+    if v in ("0", "false", "no", "off", ""):
+        return False
+    return None   # unrecognized → defer to the next precedence level
+
+
+def enabled(flag_id: str) -> bool:
+    f = _FLAGS.get(flag_id)
+    if f is None:
+        return False                                   # unknown flag → off (typo-safe)
+    if _parse_bool(os.environ.get(MASTER_ENV)) is True:
+        return True                                    # master switch forces all on
+    per = _parse_bool(os.environ.get(f.env))
+    if per is not None:
+        return per                                     # explicit per-flag override
+    return f.default

sliceagent/fuzzy.py

@@ -0,0 +1,135 @@
+"""Indentation-tolerant unique-span finder for str_replace.
+
+Implements ONLY the two whitespace-tolerant strategies that are safe enough to
+anchor an edit on (line-trim + indentation-flexible), plus their two position
+helpers. Stripped of all replacement logic: this module NEVER writes. It only
+answers "where, if anywhere uniquely, does ``old`` live in ``content``?" as a
+single ``(start, end)`` character span.
+
+The single public entry point is :func:`fuzzy_find_unique`. The caller does the
+actual splice (``content[:start] + new + content[end:]``); keeping find and
+replace separate is what lets the edit tool fall back from an exact match to a
+fuzzy one without this module ever touching file bytes.
+
+Uniqueness gate: a strategy that finds 0 or >1 candidates yields nothing. We
+try line-trim first, then indentation-flexible, and return the span only when a
+strategy produces exactly ONE candidate.
+"""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+
+__all__ = ["fuzzy_find_unique"]
+
+
+def fuzzy_find_unique(content: str, old: str) -> Tuple[int, int] | None:
+    """Return the sole ``(start, end)`` char span matching ``old`` in ``content``.
+
+    Tries, in order, the line-trimmed strategy then the indentation-flexible
+    strategy. Returns the span only when a strategy finds EXACTLY ONE match.
+    Returns ``None`` when:
+
+    - ``old`` is empty,
+    - a strategy finds zero candidates and no later strategy matches uniquely,
+    - the first strategy that matches finds more than one candidate
+      (ambiguous — the caller must supply more context).
+
+    The returned span is a byte-correct slice into ``content``: for any
+    replacement ``new``, ``content[:start] + new + content[end:]`` is the
+    edited content. This function never replaces text itself.
+    """
+    if not old or not old.strip():   # an all-whitespace old has no anchor (matches every blank line → zero-width insert)
+        return None
+
+    for strategy in (_strategy_line_trimmed, _strategy_indentation_flexible):
+        matches = strategy(content, old)
+        if not matches:
+            continue
+        if len(matches) > 1:
+            # Ambiguous under this strategy. Treat >1 as a hard failure
+            # (needs more context) rather than falling through to a looser
+            # strategy that would only be more ambiguous.
+            return None
+        return matches[0]
+
+    return None
+
+
+# =============================================================================
+# Matching strategies
+# =============================================================================
+
+def _strategy_line_trimmed(content: str, pattern: str) -> List[Tuple[int, int]]:
+    """Match line-by-line after stripping leading/trailing whitespace per line."""
+    pattern_lines = [line.strip() for line in pattern.split("\n")]
+    pattern_normalized = "\n".join(pattern_lines)
+
+    content_lines = content.split("\n")
+    content_normalized_lines = [line.strip() for line in content_lines]
+
+    return _find_normalized_matches(
+        content, content_lines, content_normalized_lines,
+        pattern, pattern_normalized,
+    )
+
+
+def _strategy_indentation_flexible(content: str, pattern: str) -> List[Tuple[int, int]]:
+    """Match line-by-line ignoring leading indentation entirely.
+
+    Strips only LEADING whitespace (``lstrip``), so trailing whitespace still
+    has to line up — this is intentionally narrower than line-trim and acts as a
+    second, indentation-only tolerance pass.
+    """
+    content_lines = content.split("\n")
+    content_stripped_lines = [line.lstrip() for line in content_lines]
+    pattern_lines = [line.lstrip() for line in pattern.split("\n")]
+
+    return _find_normalized_matches(
+        content, content_lines, content_stripped_lines,
+        pattern, "\n".join(pattern_lines),
+    )
+
+
+# =============================================================================
+# Position helpers
+# =============================================================================
+
+def _calculate_line_positions(content_lines: List[str], start_line: int,
+                              end_line: int, content_length: int) -> Tuple[int, int]:
+    """Map a [start_line, end_line) line range to a (start, end) char span.
+
+    Each line in ``content_lines`` is stored without its trailing newline, so the
+    ``+ 1`` per line re-adds the ``\\n`` consumed by ``str.split('\\n')``. The
+    end position drops the final newline and is clamped to ``content_length``.
+    """
+    start_pos = sum(len(line) + 1 for line in content_lines[:start_line])
+    end_pos = sum(len(line) + 1 for line in content_lines[:end_line]) - 1
+    end_pos = min(content_length, end_pos)
+    return start_pos, end_pos
+
+
+def _find_normalized_matches(content: str, content_lines: List[str],
+                              content_normalized_lines: List[str],
+                              pattern: str, pattern_normalized: str) -> List[Tuple[int, int]]:
+    """Find every block whose normalized lines equal the normalized pattern.
+
+    Slides a window of ``len(pattern_norm_lines)`` lines across the normalized
+    content; on each equal block it maps the line window back to an
+    ORIGINAL-content char span via :func:`_calculate_line_positions`. Returns
+    all such spans (the caller enforces uniqueness).
+    """
+    pattern_norm_lines = pattern_normalized.split("\n")
+    num_pattern_lines = len(pattern_norm_lines)
+
+    matches: List[Tuple[int, int]] = []
+
+    for i in range(len(content_normalized_lines) - num_pattern_lines + 1):
+        block = "\n".join(content_normalized_lines[i:i + num_pattern_lines])
+        if block == pattern_normalized:
+            start_pos, end_pos = _calculate_line_positions(
+                content_lines, i, i + num_pattern_lines, len(content)
+            )
+            matches.append((start_pos, end_pos))
+
+    return matches