localvectordb.patching module

Pure document patch operations (find/replace + span splice).

This module has no database dependency: it turns a document’s current content plus a list of ops into the new content string. Every higher-level surface (LocalVectorDB.patch(), the HTTP PATCH route, the patch_document MCP tool, the CLI patch command) compiles down to apply_ops().

Op shapes (op selects the kind):

• {"op": "splice", "start": int, "end": int, "text": str} – the primitive. start/end are character offsets into the original content (0 <= start <= end <= len(content)); content[start:end] is replaced by text.

• {"op": "replace", "find": str, "replace": str, "count": int = 1} – find must occur exactly count times (non-overlapping) or the whole patch fails. Each occurrence becomes a splice.

• {"op": "append", "text": str} / {"op": "prepend", "text": str} – the common no-anchor cases; map to zero-width splices at the ends.

All ops in one call are resolved against the original content (not applied sequentially against each other’s output), validated non-overlapping, and applied atomically. Any unmatched/ambiguous find, out-of-range or overlapping splice, or malformed op raises PatchError and produces no output.

class localvectordb.patching.PatchResult(updated: bool, new_hash: str, ops_applied: int)

Bases: object

Outcome of a patch.

updated is False only when the ops produced content byte-for-byte identical to what was stored (and no metadata changed). new_hash is the SHA-256 of the resulting content; ops_applied is the number of ops in the call.

updated: bool

new_hash: str

ops_applied: int

to_dict() → Dict[str, Any]

__init__(updated: bool, new_hash: str, ops_applied: int) → None

localvectordb.patching.apply_ops(content: str, ops: List[Dict[str, Any]]) → str

Apply ops to content and return the new content.

Ops resolve against the original content. The resulting splices are sorted and validated non-overlapping, then applied in a single left-to-right pass. Raises PatchError on any invalid, unmatched, ambiguous, or overlapping op; nothing is applied partially.