Metadata-Version: 2.5
Name: toolcall-unleak
Version: 0.1.0
Summary: Recover LLM tool calls from any text dialect — detect, parse, nudge. Zero dependencies.
Project-URL: Homepage, https://github.com/CloudsDocker/toolcall-unleak
Project-URL: Repository, https://github.com/CloudsDocker/toolcall-unleak
Project-URL: Issues, https://github.com/CloudsDocker/toolcall-unleak/issues
Author: CloudsDocker
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,dialect,function-calling,llm,ollama,parser,tool-calling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# toolcall-unleak

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

[![PyPI](https://img.shields.io/pypi/v/toolcall-unleak.svg)](https://pypi.org/project/toolcall-unleak/)
[![CI](https://github.com/CloudsDocker/toolcall-unleak/actions/workflows/ci.yml/badge.svg)](https://github.com/CloudsDocker/toolcall-unleak/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/toolcall-unleak.svg)](https://pypi.org/project/toolcall-unleak/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](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

```bash
pip install toolcall-unleak
```

```python
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:

```python
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`](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`](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.
