toolcall-unleak
Recover LLM tool calls from any text dialect — detect, parse, nudge. Zero dependencies.
The problem
You run an open-weight model (Ollama, LM Studio, llama.cpp, vLLM, MLX) behind an agent. The model wants to call a tool — but instead of clean structured output it emits the call in its own dialect, as plain text:
<function=search_files><parameter=query>quarterly report</tool_call>
Your harness doesn't recognise that shape, so the call leaks into the reply and never runs. The agent stalls, loops, or answers "I don't have access to that" — and there's no error, because nothing failed. Every inference engine re-implements this parsing, slightly differently, and the gaps are exactly these silent drops.
toolcall-unleak is the small, dependency-free safety net that catches them.
Quickstart
pip install toolcall-unleak
from toolcall_unleak import coerce
calls = coerce(model_output, known_tools={"search_files"})
# [ToolCall(name='search_files', arguments={'query': 'quarterly report'})]
Need more than the calls? parse returns everything a harness needs to observe and self-heal:
from toolcall_unleak import parse
result = parse(model_output, known_tools={"search_files"})
result.calls # list[ToolCall] — normalised, names resolved to your tools
result.dialect # Dialect.LLAMA_FN — which shape it recognised
result.leaked # True — a call was recovered from the text body
result.clean_text # the reply with the tool-call markup stripped out
result.nudge() # a corrective message to feed back if the model botched the call
Supported dialects
| Dialect | Shape | Seen in |
|---|---|---|
HERMES |
<tool_call>{json}</tool_call> |
Qwen, Hermes, many GGUF chat templates |
LLAMA_FN |
<function=name><parameter=k>v (even with a mismatched </tool_call> close) |
Llama / mixed GGUF quants |
MISTRAL |
[TOOL_CALLS][{...}] |
Mistral, Mixtral |
MARKDOWN |
```json {...} ``` |
DeepSeek and others that "explain then fence" |
BARE_JSON |
a raw {"name":..., "arguments":...} in prose |
fallback for many models |
PYTHONIC |
tool_name(arg='v') |
code-tuned models |
Tool names are resolved symbol- and case-insensitively, so twg-jira matches your
twg_jira. Parallel calls, surrounding prose, and trailing text are all handled.
Compatibility matrix
The claims above are backed by a conformance corpus of real-shaped outputs — see
MATRIX.md, regenerated by python tools/build_matrix.py straight from the
corpus/ fixtures. If a row is green, there's a test proving it.
Why not just…
- vLLM's built-in tool parser? It's server-side and tied to vLLM.
toolcall-unleakis client/harness-side and provider-agnostic — it works no matter what served the text. - The model's native structured output? Use it when you have it — this library is the net for when you don't: text-only endpoints, templates that leak, quants that drift.
- Writing a regex yourself? That's exactly the per-harness, slightly-wrong re-implementation this library exists to replace, with a corpus that keeps it honest.
Design
- Zero runtime dependencies — pure standard library. Nothing to audit, nothing to pin.
- Recovery-first — a call written as text is recovered, not dropped.
- Observable —
parsenever raises;dialectandleakedlet you log or alert instead of failing silently. - Self-healing —
nudge()turns a botched call into a corrective retry prompt. - Extensible — adding a dialect is one handler plus a corpus case. See
CONTRIBUTING.md.
Limitations & maintenance
Tool-call dialects track a moving target: new models and chat templates appear constantly. This library covers the common shapes and grows by corpus contribution, not by trying to predict every future format. Streaming (delta-by-delta) parsing is intentionally not in v0.x — it parses a complete message. If you hit a dialect it misses, open an issue with the raw output; a fixture plus a handler is usually a small change.
License
Apache-2.0.
Metadata
Release files for toolcall-unleak 0.1.0
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 |
|---|---|---|---|---|
| toolcall_unleak-0.1.0.tar.gz | 20.0 kB | With provenance | Details for toolcall_unleak-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| toolcall_unleak-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for toolcall_unleak-0.1.0-py3-none-any.whl |
Total release size: 35.3 kB
Release files / toolcall_unleak-0.1.0.tar.gz
| Download URL | toolcall_unleak-0.1.0.tar.gz |
|---|---|
| Size | 20.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8424baa3f8dedeb5509db05284da54efe83b4ae46b1b0e514f6a7325216d44a6
|
|
BLAKE2b-256 checksum How to use checksums |
79c8e073e595a9dc66737857de490c8b30658c064b9b3e45ead3269e9a4a05f0
|
| 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 / toolcall_unleak-0.1.0-py3-none-any.whl
| Download URL | toolcall_unleak-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
07396c9cce8214e04acd4f687c2a2ea5903b24a085a3ac7d097add885f4f914f
|
|
BLAKE2b-256 checksum How to use checksums |
32aca8fa6a219a29bb6da3e40a0ebbb073e4c85f256b4f9b524acdefb16e7038
|
| 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 toolcall-unleak 0.1.0
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 toolcall_unleak-0.1.0.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.