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.
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):
- byte-identical prefix — the original file is prepended verbatim, so every pre-existing test is the same source (not regenerated-and-hopefully-equal);
- parses — the assembled file still parses;
- 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);
- 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_regiondetects 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_overlapreports what was removed. - Truncation. A completion cut off at
max_tokensis 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.parsesisTrue/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.pyreplays 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
- Locate the unique
beforeandafteranchors. prefix = text[:end_of_before],suffix = text[start_of_after:].- Send
(prefix, suffix)to Codestral FIM →middle(de-duplicated, truncation-checked). new_text = prefix + middle + suffix; the bytes outside the region are the same slices, concatenated unchanged.- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.