Metadata-Version: 2.2
Name: llm-json
Version: 0.1.5
Summary: A JSON library wrapper that gracefully handles markdown-wrapped JSON from LLMs.
Author-email: Alex Volkov <alex@alexw.me>
License: MIT License Copyright (c) 2025 Alex Volkov
        
        Permission is hereby granted, free of
        charge, to any person obtaining a copy of this software and associated
        documentation files (the "Software"), to deal in the Software without
        restriction, including without limitation the rights to use, copy, modify, merge,
        publish, distribute, sublicense, and/or sell copies of the Software, and to
        permit persons to whom the Software is furnished to do so, subject to the
        following conditions:
        
        The above copyright notice and this permission notice
        (including the next paragraph) shall be included in all copies or substantial
        portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
        ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
        EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
Project-URL: Homepage, https://github.com/altryne/llm-json
Keywords: json,LLMs,markdown,ai
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# llm-json - stop begging LLMs for valid JSON

![llm-json](https://cln.sh/Dkx2W8Jr+)

[![PyPI version](https://img.shields.io/pypi/v/llm-json)](https://pypi.org/project/llm-json)
[![Upload Python Package](https://github.com/altryne/llm-json/actions/workflows/python-publish.yml/badge.svg)](https://github.com/altryne/llm-json/actions/workflows/python-publish.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**llm-json** is a Python package that acts as a drop-in replacement for the standard \json\ library. It automatically handles JSON strings that are often returned by Large Language Models (LLMs) wrapped in Markdown code fences or backticks—so you don’t have to beg the AI to always produce “valid JSON.”

## Why This Project?
After repeatedly struggling with LLMs returning JSON (but *also* including backticks, code fences, or extraneous text), I got fed up. Structured output is nice, but it’s not always possible (or desirable) to force the LLM to output *perfect* JSON. Rather than overcomplicating prompt engineering, **llm-json** does the messy cleanup for you.

## Installation
Grab the latest release from PyPI:

```bash
uv pip install llm-json
```

## Can't you just use Structured Outputs?
Yes, but not all providers support them in the same way

## Why not use Instructor / Outlines
I love both of those tools, this is just a simple wrapper to make my life easier, I don't need a full blown library for structured outputs, just a simple json validator that works the way LLMs do!

## Usage
The core idea is that **llm-json** works exactly like the standard Python `json` library, but with automatic fallback parsing for those pesky backticks:

```python
from llm_json import json

# A string returned by an LLM, might be in triple-backtick code blocks or inline backticks
s = """
```json
{
  "hello": "world"
}
```"""

data = json.loads(s)
print(data)  # => {'hello': 'world'}
```

All other functions (`json.dump`, `json.dumps`, `json.load`) also work the same way. Just replace your existing `import json` with `from llm_json import json`, and you’re good to go.

### Handling Extra Text
**llm-json** will ignore extraneous text before and after the code fences and attempt to parse the first valid snippet it finds. It also handles inline backticks (like \`\`\`{"hello":"world"}\`\`\`).

## Contributing
Pull requests and issues are very welcome! Check out the [GitHub repo](https://github.com/altryne/llm-json) to file issues or propose changes.

## Testing
We use [pytest](https://pytest.org/). To run tests locally:

```bash
git clone https://github.com/altryne/llm-json.git
cd llm-json
pip install -e .
pip install pytest
pytest tests
```

You should see something like:

```
============================= test session starts =============================
platform darwin -- Python 3.x, pytest-8.x, ...
collected 9 items

tests/test_json.py .........                                                 [100%]

============================== 9 passed in 0.02s ==============================
```

## License
This project is licensed under the [MIT License](LICENSE).

## Author
Made with ❤️ by [@altryne](https://x.com/altryne).  
- GitHub: [github.com/altryne](https://github.com/altryne)  
- X (formerly Twitter): [x.com/altryne](https://x.com/altryne)

