editbuffer 0.2.1__py3-none-any.whl

editbuffer/operations.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Mapping
+
+from .errors import InvalidOperationError
+from .selection import Selection
+
+OperationType = Literal[
+    "append",
+    "replace",
+    "insert_before",
+    "insert_after",
+    "delete",
+    "rollback",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class EditOperation:
+    kind: OperationType
+    target: Selection | None = None
+    text: str = ""
+    version: int | None = None
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> EditOperation:
+        kind = value.get("op")
+        if kind not in {
+            "append",
+            "replace",
+            "insert_before",
+            "insert_after",
+            "delete",
+            "rollback",
+        }:
+            raise InvalidOperationError(f"unknown operation: {kind!r}")
+
+        if kind == "rollback":
+            version = value.get("version")
+            if not isinstance(version, int):
+                raise InvalidOperationError("'rollback' requires integer 'version'")
+            return cls(kind, version=version)
+
+        if kind != "delete" and "text" not in value:
+            raise InvalidOperationError(f"{kind!r} requires 'text'")
+        text = value.get("text", "")
+        if not isinstance(text, str):
+            raise InvalidOperationError("'text' must be a string")
+
+        if kind == "append":
+            return cls(kind, text=text)
+
+        target = value.get("target")
+        if not isinstance(target, Mapping):
+            raise InvalidOperationError("'target' must be a selection object")
+        return cls(kind, target=Selection.from_dict(target), text=text)
+
+    def as_dict(self) -> dict[str, Any]:
+        if self.kind == "rollback":
+            return {"op": "rollback", "version": self.version}
+        result: dict[str, Any] = {"op": self.kind}
+        if self.kind != "delete":
+            result["text"] = self.text
+        if self.target is not None:
+            result["target"] = self.target.as_dict()
+        return result

editbuffer/py.typed

@@ -0,0 +1 @@
+

editbuffer/resolver.py

@@ -0,0 +1,157 @@
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+
+from .errors import (
+    AmbiguousTargetError,
+    FuzzyMatchError,
+    InvalidOperationError,
+    StaleVersionError,
+    TargetNotFoundError,
+)
+from .selection import Selection
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedSelection:
+    start: int
+    end: int
+    confidence: float = 1.0
+
+
+class SelectionResolver:
+    def resolve(
+        self,
+        content: str,
+        selection: Selection,
+        *,
+        version: int,
+    ) -> ResolvedSelection:
+        if selection.type == "range":
+            return self._resolve_range(content, selection, version)
+        if selection.type == "block":
+            from .blocks import find_blocks
+
+            if not selection.block_id:
+                raise InvalidOperationError("block_id must not be empty")
+            return _choose(find_blocks(content, selection.block_id), None)
+        if selection.text == "":
+            raise InvalidOperationError("selection text must not be empty")
+
+        if selection.type == "exact":
+            candidates = _find_all(content, selection.text or "")
+        elif selection.type == "context":
+            candidates = _find_context(content, selection)
+        else:
+            return _find_fuzzy(content, selection)
+        return _choose(candidates, selection.occurrence)
+
+    def _resolve_range(
+        self,
+        content: str,
+        selection: Selection,
+        version: int,
+    ) -> ResolvedSelection:
+        if (
+            selection.expected_version is not None
+            and selection.expected_version != version
+        ):
+            raise StaleVersionError(
+                f"expected version {selection.expected_version}, current version is {version}"
+            )
+        start, end = selection.start, selection.end
+        if start is None or end is None or start < 0 or end < start or end > len(content):
+            raise InvalidOperationError(
+                f"invalid range [{start}, {end}) for content length {len(content)}"
+            )
+        return ResolvedSelection(start, end)
+
+
+def _find_all(content: str, text: str) -> tuple[ResolvedSelection, ...]:
+    matches: list[ResolvedSelection] = []
+    start = 0
+    while (index := content.find(text, start)) != -1:
+        matches.append(ResolvedSelection(index, index + len(text)))
+        start = index + 1
+    return tuple(matches)
+
+
+def _find_context(
+    content: str,
+    selection: Selection,
+) -> tuple[ResolvedSelection, ...]:
+    text = selection.text or ""
+    needle = f"{selection.before}{text}{selection.after}"
+    offset = len(selection.before)
+    return tuple(
+        ResolvedSelection(match.start + offset, match.start + offset + len(text))
+        for match in _find_all(content, needle)
+    )
+
+
+def _choose(
+    candidates: tuple[ResolvedSelection, ...],
+    occurrence: int | None,
+) -> ResolvedSelection:
+    if not candidates:
+        raise TargetNotFoundError("selection did not match the current buffer")
+    if occurrence is not None:
+        if occurrence < 0 or occurrence >= len(candidates):
+            raise TargetNotFoundError(
+                f"occurrence {occurrence} is outside {len(candidates)} matches"
+            )
+        return candidates[occurrence]
+    if len(candidates) > 1:
+        raise AmbiguousTargetError(tuple((match.start, match.end) for match in candidates))
+    return candidates[0]
+
+
+def _find_fuzzy(content: str, selection: Selection) -> ResolvedSelection:
+    text = selection.text or ""
+    if not 0 < selection.threshold <= 1:
+        raise InvalidOperationError("fuzzy threshold must be in (0, 1]")
+    if not 0 <= selection.ambiguity_margin <= 1:
+        raise InvalidOperationError("fuzzy ambiguity_margin must be in [0, 1]")
+
+    variation = max(2, len(text) // 5)
+    raw: list[ResolvedSelection] = []
+    for length in range(max(1, len(text) - variation), len(text) + variation + 1):
+        for start in range(0, len(content) - length + 1):
+            score = SequenceMatcher(None, text, content[start : start + length]).ratio()
+            raw.append(ResolvedSelection(start, start + length, score))
+
+    candidates = _distinct_fuzzy_targets(raw, len(text))
+    diagnostics = tuple(
+        (candidate.start, candidate.end, round(candidate.confidence, 4))
+        for candidate in candidates[:5]
+    )
+    if not candidates or candidates[0].confidence < selection.threshold:
+        raise FuzzyMatchError("below_threshold", diagnostics)
+    eligible = [
+        candidate
+        for candidate in candidates
+        if candidate.confidence >= selection.threshold
+    ]
+    if (
+        len(eligible) > 1
+        and eligible[0].confidence - eligible[1].confidence
+        < selection.ambiguity_margin
+    ):
+        raise FuzzyMatchError("ambiguous", diagnostics)
+    return candidates[0]
+
+
+def _distinct_fuzzy_targets(
+    candidates: list[ResolvedSelection],
+    query_length: int,
+) -> list[ResolvedSelection]:
+    ranked = sorted(candidates, key=lambda item: item.confidence, reverse=True)
+    selected: list[ResolvedSelection] = []
+    separation = max(1, query_length // 2)
+    for candidate in ranked:
+        center = (candidate.start + candidate.end) // 2
+        if all(
+            abs(center - (existing.start + existing.end) // 2) >= separation
+            for existing in selected
+        ):
+            selected.append(candidate)
+    return selected

editbuffer/selection.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Mapping
+
+from .errors import InvalidOperationError
+
+SelectionType = Literal["exact", "context", "range", "fuzzy", "block"]
+
+
+@dataclass(frozen=True, slots=True)
+class Selection:
+    type: SelectionType
+    text: str | None = None
+    before: str = ""
+    after: str = ""
+    start: int | None = None
+    end: int | None = None
+    occurrence: int | None = None
+    expected_version: int | None = None
+    threshold: float = 0.85
+    ambiguity_margin: float = 0.05
+    block_id: str | None = None
+
+    @classmethod
+    def exact(cls, text: str, occurrence: int | None = None) -> Selection:
+        return cls("exact", text=text, occurrence=occurrence)
+
+    @classmethod
+    def context(
+        cls,
+        *,
+        before: str,
+        text: str,
+        after: str,
+        occurrence: int | None = None,
+    ) -> Selection:
+        return cls(
+            "context",
+            text=text,
+            before=before,
+            after=after,
+            occurrence=occurrence,
+        )
+
+    @classmethod
+    def range(
+        cls,
+        start: int,
+        end: int,
+        *,
+        expected_version: int | None = None,
+    ) -> Selection:
+        return cls(
+            "range",
+            start=start,
+            end=end,
+            expected_version=expected_version,
+        )
+
+    @classmethod
+    def fuzzy(
+        cls,
+        text: str,
+        *,
+        threshold: float = 0.85,
+        ambiguity_margin: float = 0.05,
+    ) -> Selection:
+        return cls(
+            "fuzzy",
+            text=text,
+            threshold=threshold,
+            ambiguity_margin=ambiguity_margin,
+        )
+
+    @classmethod
+    def block(cls, block_id: str) -> Selection:
+        return cls("block", block_id=block_id)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> Selection:
+        selection_type = value.get("type")
+        if selection_type == "exact":
+            return cls.exact(
+                _required_string(value, "text"),
+                occurrence=_optional_int(value, "occurrence"),
+            )
+        if selection_type == "context":
+            return cls.context(
+                before=_optional_string(value, "before"),
+                text=_required_string(value, "text"),
+                after=_optional_string(value, "after"),
+                occurrence=_optional_int(value, "occurrence"),
+            )
+        if selection_type == "range":
+            return cls.range(
+                _required_int(value, "start"),
+                _required_int(value, "end"),
+                expected_version=_optional_int(value, "expected_version"),
+            )
+        if selection_type == "fuzzy":
+            return cls.fuzzy(
+                _required_string(value, "text"),
+                threshold=_optional_float(value, "threshold", 0.85),
+                ambiguity_margin=_optional_float(
+                    value,
+                    "ambiguity_margin",
+                    0.05,
+                ),
+            )
+        if selection_type == "block":
+            return cls.block(_required_string(value, "block_id"))
+        raise InvalidOperationError(f"unknown selection type: {selection_type!r}")
+
+    def as_dict(self) -> dict[str, Any]:
+        if self.type == "exact":
+            result: dict[str, Any] = {"type": "exact", "text": self.text}
+            if self.occurrence is not None:
+                result["occurrence"] = self.occurrence
+            return result
+        if self.type == "context":
+            result = {
+                "type": "context",
+                "before": self.before,
+                "text": self.text,
+                "after": self.after,
+            }
+            if self.occurrence is not None:
+                result["occurrence"] = self.occurrence
+            return result
+        if self.type == "range":
+            result = {"type": "range", "start": self.start, "end": self.end}
+            if self.expected_version is not None:
+                result["expected_version"] = self.expected_version
+            return result
+        if self.type == "fuzzy":
+            return {
+                "type": "fuzzy",
+                "text": self.text,
+                "threshold": self.threshold,
+                "ambiguity_margin": self.ambiguity_margin,
+            }
+        return {"type": "block", "block_id": self.block_id}
+
+
+def _required_string(value: Mapping[str, Any], key: str) -> str:
+    result = value.get(key)
+    if not isinstance(result, str):
+        raise InvalidOperationError(f"{key!r} must be a string")
+    return result
+
+
+def _optional_string(value: Mapping[str, Any], key: str) -> str:
+    result = value.get(key, "")
+    if not isinstance(result, str):
+        raise InvalidOperationError(f"{key!r} must be a string")
+    return result
+
+
+def _required_int(value: Mapping[str, Any], key: str) -> int:
+    result = value.get(key)
+    if not isinstance(result, int):
+        raise InvalidOperationError(f"{key!r} must be an integer")
+    return result
+
+
+def _optional_int(value: Mapping[str, Any], key: str) -> int | None:
+    result = value.get(key)
+    if result is not None and not isinstance(result, int):
+        raise InvalidOperationError(f"{key!r} must be an integer")
+    return result
+
+
+def _optional_float(
+    value: Mapping[str, Any],
+    key: str,
+    default: float,
+) -> float:
+    result = value.get(key, default)
+    if not isinstance(result, (int, float)):
+        raise InvalidOperationError(f"{key!r} must be a number")
+    return float(result)

editbuffer/validators.py

@@ -0,0 +1,23 @@
+import json
+import subprocess
+
+from .errors import ValidationError
+
+
+def valid_json(content: str) -> None:
+    try:
+        json.loads(content)
+    except json.JSONDecodeError as error:
+        raise ValidationError(str(error)) from error
+
+
+def valid_shell(content: str) -> None:
+    result = subprocess.run(
+        ["sh", "-n"],
+        input=content,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if result.returncode:
+        raise ValidationError(result.stderr.strip() or "invalid shell syntax")

editbuffer-0.2.1.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: editbuffer
+Version: 0.2.1
+Summary: Selection-based mutable output buffer for LLM tools
+Author: averagedigital
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; extra == "mcp"
+Dynamic: license-file
+
+# editbuffer
+
+`editbuffer` is a small Python runtime for editing an LLM's pending text output
+before it is committed.
+
+The public abstraction is selection-based editing, not file patches:
+
+- select exact, contextual, fuzzy, block, or character-range targets;
+- replace, insert before/after, or delete the selection;
+- reject missing, ambiguous, invalid, and stale selections;
+- inspect the current buffer and its audit history;
+- commit the final artifact.
+
+## Install
+
+```bash
+pip install editbuffer
+```
+
+For local development:
+
+```bash
+python -m pip install -e .
+```
+
+Python 3.11+ is required. The core library has no runtime dependencies.
+
+## Quickstart
+
+```python
+from editbuffer import EditBuffer, Selection
+
+buf = EditBuffer()
+buf.append('find . -name "*.py" -exec grep -n "TODO" {} ;')
+buf.replace(Selection.exact("{} ;"), "{} \\;")
+
+final = buf.commit()
+```
+
+Selections can also be dictionaries:
+
+```python
+buf.replace(
+    {
+        "type": "context",
+        "before": 'grep -n "TODO" ',
+        "text": "{} ;",
+        "after": "",
+    },
+    "{} \\;",
+)
+```
+
+## LLM tool-call format
+
+```json
+{
+  "op": "replace",
+  "target": {
+    "type": "context",
+    "before": "grep -n \"TODO\" ",
+    "text": "{} ;",
+    "after": ""
+  },
+  "text": "{} \\;"
+}
+```
+
+Pass the decoded object to `buffer.apply(operation)`. Supported operations are
+`append`, `replace`, `insert_before`, `insert_after`, and `delete`.
+
+Range selections use half-open character offsets and can reject stale edits:
+
+```json
+{
+  "op": "delete",
+  "target": {
+    "type": "range",
+    "start": 10,
+    "end": 20,
+    "expected_version": 3
+  }
+}
+```
+
+## Failure behavior
+
+- no match raises `TargetNotFoundError`;
+- multiple matches raise `AmbiguousTargetError` with candidate ranges;
+- `occurrence` can explicitly choose a zero-based match;
+- invalid ranges or operations raise `InvalidOperationError`;
+- a mismatched `expected_version` raises `StaleVersionError`;
+- validator failures do not mutate text or history;
+- fuzzy matching is opt-in and rejects low-confidence or competing candidates.
+
+## Fuzzy and block selections
+
+Fuzzy selection uses the standard library and records the accepted confidence:
+
+```python
+buf.replace(
+    Selection.fuzzy(
+        "run integrtion tests",
+        threshold=0.85,
+        ambiguity_margin=0.05,
+    ),
+    "run unit tests",
+)
+```
+
+It never runs as a fallback for exact/context selection. If no candidate meets
+the threshold, or two candidates are too close, `FuzzyMatchError` includes
+candidate ranges and scores.
+
+Block selection requires an explicit ID. Fenced code blocks use:
+
+````markdown
+```python editbuffer:id=setup
+print("old")
+```
+````
+
+Markdown regions use:
+
+```markdown
+<!-- editbuffer:block summary -->
+old content
+<!-- /editbuffer:block -->
+```
+
+`Selection.block("setup")` selects the content inside the markers, preserving
+the fence or comments. Duplicate IDs are rejected as ambiguous.
+
+## Snapshots and rollback
+
+Every successful edit stores an in-memory snapshot:
+
+```python
+buf.append("draft")
+version = buf.version
+buf.replace(Selection.exact("draft"), "final")
+buf.rollback(version)
+```
+
+Rollback restores the snapshot as a new audited version. Snapshots live only
+for the lifetime of the `EditBuffer` process.
+
+## Optional validators
+
+```python
+from editbuffer import EditBuffer
+from editbuffer.validators import valid_json, valid_shell
+
+json_buffer = EditBuffer('{"ok": true}', validators=(valid_json,))
+shell_buffer = EditBuffer("echo ok", validators=(valid_shell,))
+```
+
+`valid_shell` invokes the local POSIX `sh -n` parser without executing the
+command.
+
+## CLI
+
+The CLI stores an operation log in a JSON state file:
+
+```bash
+editbuffer new /tmp/output.json --text "hello world"
+editbuffer replace /tmp/output.json '{"type":"exact","text":"world"}' "there"
+editbuffer view /tmp/output.json
+editbuffer history /tmp/output.json
+editbuffer rollback /tmp/output.json 1
+editbuffer commit /tmp/output.json
+```
+
+Use `editbuffer apply STATE OPERATION_JSON` for the complete operation schema.
+
+## MCP / agent integration
+
+Install the optional server:
+
+```bash
+pipx install 'editbuffer[mcp]'
+```
+
+Until a PyPI release exists, install directly from GitHub:
+
+```bash
+pipx install 'editbuffer[mcp] @ git+https://github.com/averagedigital/editbuffer.git'
+```
+
+Connect it to Codex:
+
+```bash
+codex mcp add editbuffer -- editbuffer-mcp
+```
+
+Codex supports local STDIO MCP servers configured with `codex mcp add`; use
+`/mcp` in the Codex terminal UI to confirm the server is active.
+
+Claude Desktop and generic MCP client examples are in
+[`docs/mcp.md`](docs/mcp.md).
+
+The server exposes:
+
+- `buffer_create`
+- `buffer_list`
+- `buffer_view`
+- `buffer_edit`
+- `buffer_history`
+- `buffer_rollback`
+- `buffer_commit`
+- `command_history`
+- `command_select`
+
+Buffers are in-memory and live for the MCP server process. The MCP layer calls
+the same core API and does not implement separate edit semantics.
+
+`buffer_commit` remembers non-empty committed output as a reusable command.
+`command_history` returns the last 10 commands, newest first. `command_select`
+creates a new pending buffer from a previous command so the model can reuse it
+instead of regenerating it.
+
+## Examples
+
+- [`examples/shell_repair.py`](examples/shell_repair.py)
+- [`examples/json_repair.py`](examples/json_repair.py)
+- [`examples/chat_restructure.py`](examples/chat_restructure.py)
+
+## Scope
+
+This project is not:
+
+- an agent framework;
+- a retrieval system or repo indexer;
+- a full IDE;
+- a replacement for coding agents;
+- a generic output quality evaluator.
+
+Persistent storage, atomic operation batches, TypeScript bindings, and
+syntax-aware block parsing are future work.
+
+## Development
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT