Skip to main content

vibe-fim

Bounded AI code edits via Codestral fill-in-the-middle. Rewrite only the region between two anchors — the rest of the file comes out byte-for-byte identical, by construction, including existing LF, CRLF, or CR line endings.

CI Python License deps


Why this exists

Many AI editing workflows regenerate a block and paste it back. The model re-emits your whole function (or file) token by token, so it can silently change things you never asked it to touch — reflow a comment, drop a trailing newline, "fix" an unrelated line, normalise quotes.

Fill-in-the-middle (FIM) makes that structurally impossible. You hand the model a verbatim prefix and suffix; it only writes the middle. So the edit is provably confined to the region between two anchors. Everything outside is never sent to be rewritten — it cannot drift.

vibe-fim wraps Mistral's Codestral FIM in a one-call surgical-patch primitive. The bytes outside the region are the original slices, concatenated unchanged — so bounded scope is structural. On top of that it runs the checks that can actually fail (below), so a bad completion is caught, not shipped.

vibe-fim packages Codestral FIM as an agent-callable bounded-edit primitive, with a scope report and a parse check where the standard library supports the language. Bounded scope does not prove semantic correctness or runtime behavior; those remain downstream checks.

Install

pip install vibe-fim
export MISTRAL_API_KEY=...   # from https://console.mistral.ai

Zero runtime dependencies (stdlib urllib only).

CLI

# Rewrite only what's between the two anchors; show the diff without writing.
vibe-fim patch --file units.py \
  --before "def to_celsius(f):" \
  --after  $'\n\ndef to_fahrenheit' \
  --hint   "round the result to 1 decimal place" \
  --dry-run

The scope report goes to stderr:

[BOUNDED + PARSES] edit confined between anchors.
  frozen prefix: 142 chars (unchanged)
  frozen suffix: 98 chars (unchanged)
  region: 31 chars -> 39 chars

Drop --dry-run to write the file in place. If the patched file no longer parses, the CLI refuses to write (exit 3) unless you pass --allow-broken.

Many edits, one transaction

patch-many applies N bounded edits to one file as a single all-or-nothing transaction. Every segment between and around the regions stays byte-identical, the assembled file is parse-checked once, and the whole result is written or nothing is. A model that drifts in one region cannot corrupt the others; a result that doesn't parse is rejected as a unit.

vibe-fim patch-many --file app.py --json --edits '[
  {"before": "def to_celsius(f):", "after": "\ndef to_fahrenheit", "hint": "round to 1dp"},
  {"before": "def format_row(f):", "after": "\nTABLE_FOOTER",      "hint": "pad to 6 cols"}
]'
# {"bounded": true, "parses": true, "regions": 2, ... "wrote": true}

Edits must be in file order and non-overlapping; an ambiguous/missing anchor, an overlap, or a non-parsing result rejects the whole transaction (nothing is applied). from vibe_fim import patch_regions for the same as a library call.

Grow tests, provably additive

grow-tests uses FIM to append new test_* functions and proves the change is additive — your green tests stay green by execution, not by hope:

vibe-fim grow-tests --file tests/test_app.py --focus "edge cases" --json

A four-part gate, all-or-nothing (nothing is written unless all hold):

  1. byte-identical prefix — the original file is prepended verbatim, so every pre-existing test is the same source (not regenerated-and-hopefully-equal);
  2. parses — the assembled file still parses;
  3. node-ids monotonic — a real pytest run collects every old test id plus the new ones (nothing renamed, removed, or shadowed by a duplicate name);
  4. green stays green — each pre-existing test keeps the outcome it had on the original file, and each new test actually executed.

The pytest run is the proof (via the builtin --junit-xml channel — no plugin dep). Exit 4 if the additive proof fails; exit 3 if it does not parse. Generated tests are candidates — review them for meaning: the gate proves they are additive and that they run, not that they are good tests. A live Codestral run, replayable offline, is committed at examples/GROW_TESTS_RECEIPT.md.

Agent-callable

An agent shells out and consumes a stable JSON contract — no screen-scraping:

vibe-fim patch --stdin --before "…" --after "…" --name app.py --json
# {"bounded": true, "parses": true, "scope_report": "...", "unified_diff": "...",
#  "frozen_prefix_chars": 142, "frozen_suffix_chars": 98, "trimmed_overlap": 0,
#  "new_middle": "...", "wrote": false}

--stdin/--text pass the source inline (no disk round-trip); on error the record is {"bounded": false, "error": "..."} with a non-zero exit, so a loop can branch. There is also an MCP server — see Wiring into an agent below.

Library

from vibe_fim import patch_region

result = patch_region(
    source_code,
    before="def to_celsius(f):",   # frozen prefix ends right after this
    after="\n\ndef to_fahrenheit", # frozen suffix starts right at this
    hint="round the result to 1 decimal place",
)

assert result.bounded                         # structural invariant
assert source_code.startswith(result.prefix)  # prefix is byte-identical
assert result.parses is not False             # patched file still parses
new_source = result.text

The completion backend is injectable, so the bounded-edit logic is fully testable with no network:

patch_region(src, before, after, fim_fn=lambda prefix, suffix: "    return 42")

Anchors must be unique in the file. A missing or ambiguous anchor raises FimError instead of guessing — surgical edits should never be applied to the wrong place.

Verification that can fail

Bounded scope is structural (the prefix/suffix are the original slices). The value is in the checks that a bad completion can actually trip:

  • Boundary echo. FIM models sometimes re-emit the start of the suffix (or end of the prefix) inside the middle — duplicating code, on the same line, not just across a line break. patch_region detects and strips a real re-emission (a run of ≥4 non-whitespace chars) while leaving a coincidental shared } or a boundary newline alone. result.trimmed_overlap reports what was removed.
  • Truncation. A completion cut off at max_tokens is an incomplete middle. finish_reason == "length" raises instead of shipping a half-written edit.
  • Parse gate. For languages we can parse with the stdlib (Python via ast), the patched file is re-parsed; result.parses is True/False/None, the report shows [BOUNDED + PARSES] / [BOUNDED + DOES NOT PARSE], and the CLI refuses to write a non-parsing result by default.

The guarantee, and the drift — demonstrated

Two separate claims, kept separate:

  • The guarantee is structural: surgical FIM changes 0 lines outside the target, by construction, because the frozen regions are never regenerated.
  • The drift is measured. examples/bench.py replays a committed Codestral transcript (examples/fixtures/) and counts collateral with one newline-aware counter for both approaches:
surgical FIM      : 0 lines changed outside target
block regeneration: 2 lines changed outside target   # one source line: its trailing newline dropped (counted as a -/+ diff pair)

It runs offline by default (no key, same numbers for every reviewer); pass --live to re-capture from the API. The block-regen baseline produced the correct body and still silently altered the file outside the edit.

python examples/bench.py            # offline replay of the committed fixture
MISTRAL_API_KEY=... python examples/bench.py --live

Wiring into an agent

vibe-fim patch --json is the stable contract for shelling out. For a native tool, install the optional MCP server and point any MCP client at it:

pip install "vibe-fim[mcp]"
vibe-fim-mcp          # stdio MCP server exposing one tool: surgical_patch

The tool returns the unified diff plus the scope report, so the agent sees the bounded proof — not just a success flag. (The base package stays zero-dependency; the mcp SDK is pulled in only by the [mcp] extra. The core CLI supports Python 3.9+; the MCP extra requires Python 3.10+.)

The MCP tools only read and write files under one workspace root: the directory the server was started in, or VIBE_FIM_ROOT when set. A path that resolves outside it (absolute, .., or through a symlink) is refused before anything is read or sent to the model. grow_tests runs the candidate test file with pytest on your machine to prove the change is additive: treat it like running the project's own test suite, and do not point it at code you would not execute.

How it works

  1. Locate the unique before and after anchors.
  2. prefix = text[:end_of_before], suffix = text[start_of_after:].
  3. Send (prefix, suffix) to Codestral FIM → middle (de-duplicated, truncation-checked).
  4. new_text = prefix + middle + suffix; the bytes outside the region are the same slices, concatenated unchanged.
  5. Run the parse gate and surface the result.

License

MIT © Guillaume Vele

Metadata

Release files for vibe-fim 0.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vibe-fim 0.4.2
File Size Uploaded Provenance Actions
vibe_fim-0.4.2.tar.gz 30.3 kB With provenance Details for vibe_fim-0.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vibe-fim 0.4.2
File Interpreter ABI Platform Actions
vibe_fim-0.4.2-py3-none-any.whl Python 3 none any Details for vibe_fim-0.4.2-py3-none-any.whl

Total release size: 54.0 kB

Release files / vibe_fim-0.4.2.tar.gz

Download URL vibe_fim-0.4.2.tar.gz
Size 30.3 kB
Tags Source
SHA-256 checksum
How to use checksums
ab57c71c7e3376b95dd9fe9547228a5f5fd265908d38af2a493cae067b5704bd
BLAKE2b-256 checksum
How to use checksums
e8fa05913da2fd2b743e4279b7543fd56cd34bc92bcb70a70a4a682caf0989b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / vibe_fim-0.4.2-py3-none-any.whl

Download URL vibe_fim-0.4.2-py3-none-any.whl
Size 23.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
58d8523d289a1526fcae94e0b04502ff4713d480b283f21768307733d5a9abd5
BLAKE2b-256 checksum
How to use checksums
d570309f6009c5423d16ed1e0e08916645267cbefaea8fd9c7b76c7e61262fdc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for vibe-fim 0.4.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vibe_fim-0.4.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page