Skip to main content

toolcall-unleak

Recover LLM tool calls from any text dialect — detect, parse, nudge. Zero dependencies.

PyPI CI Python License


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-unleak is 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 — parse never raises; dialect and leaked let 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)

Source distribution for toolcall-unleak 0.1.0
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)

Table of built distributions (wheels) for toolcall-unleak 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

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