https://github.com/olaflaitinen/laga
A fast, conservative JSON repair library for malformed model output, hand-written config, and almost-JSON text. Repairs common syntax issues and returns clean Python objects.
https://github.com/olaflaitinen/laga
ai cli configuration data-cleanup json json-parser json-repair llm malformed-json markdown openai parser python python-library text-processing trusted-publishing
Last synced: about 19 hours ago
JSON representation
A fast, conservative JSON repair library for malformed model output, hand-written config, and almost-JSON text. Repairs common syntax issues and returns clean Python objects.
- Host: GitHub
- URL: https://github.com/olaflaitinen/laga
- Owner: olaflaitinen
- License: mit
- Created: 2026-07-24T07:43:37.000Z (2 days ago)
- Default Branch: main
- Last Pushed: 2026-07-24T08:37:55.000Z (2 days ago)
- Last Synced: 2026-07-24T10:04:57.862Z (2 days ago)
- Topics: ai, cli, configuration, data-cleanup, json, json-parser, json-repair, llm, malformed-json, markdown, openai, parser, python, python-library, text-processing, trusted-publishing
- Language: Python
- Homepage: https://pypi.org/project/laga/
- Size: 103 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Security: SECURITY.md
Awesome Lists containing this project
README
# laga
`laga` repairs malformed JSON and returns Python objects.
It is built for the real world: model output, hand-written config, copied snippets, and other almost-JSON text that is usually close enough to recover but not strict enough for `json.loads`.
## Highlights
- Repairs common JSON mistakes such as trailing commas, missing commas, single quotes, unquoted keys, comments, fences, smart quotes, and truncated containers.
- Tries the standard library first, so valid JSON stays fast and strict.
- Keeps the public API small: `repair`, `repair_to_str`, `loads`, and `LagaError`.
- Ships with a CLI, JSONL support, type information, tests, docs, and CI.
## Supported Versions
`laga` 0.1.6 supports Python 3.10 through 3.13.
## Install
For normal use from PyPI:
```bash
python -m pip install laga
```
For local development from a checkout:
```bash
python -m pip install -e ".[dev]"
```
## Quick Start
```python
import laga
text = "{name: 'Ada', active: True, roles: ['admin', 'writer',],}"
data = laga.repair(text)
print(data)
print(laga.repair_to_str(text))
```
## CLI
You can also use `laga` from the command line:
```bash
laga "{name: 'Ada', active: True, roles: ['admin',]}"
laga --strict '{"a": 1,}'
```
Use `--strict` when you want to reject ambiguous repairs instead of filling in gaps.
Use `--pretty` to format output for humans, `--stdin` to read from standard input, and `--duplicate-keys error` when duplicate keys should fail.
Use `--input` to read from a file, `--output` to write the repaired result back to disk, or `--in-place` to overwrite the input file directly.
Use `--jsonl` when each non-empty line is a separate JSON record and you want one repaired value per line.
```bash
laga --stdin --pretty
laga --input sample.txt --output fixed.json
laga --input sample.txt --in-place --pretty
laga --jsonl --stdin
laga --max-depth 64 --max-input-size 10000 --duplicate-keys error '{"a": 1}'
```
## API
| Function | Returns | Description |
| --- | --- | --- |
| `laga.repair(text, strict=False)` | Python object | Repairs malformed JSON and returns Python data. |
| `laga.repair_to_str(text, strict=False)` | `str` | Repairs malformed JSON and returns normalized JSON text. |
| `laga.repair_jsonl(text, strict=False)` | `list[object]` | Repairs newline-delimited JSON records and returns Python values. |
| `laga.repair_jsonl_to_str(text, strict=False)` | `str` | Repairs newline-delimited JSON records and returns newline-delimited JSON text. |
| `laga.repair_file(path, strict=False)` | Python object | Reads a file and repairs its contents. |
| `laga.loads(text, strict=False)` | Python object | Alias for `laga.repair`. |
| `laga.LagaError` | Exception type | Raised when repair fails or input is unrecoverable. |
## What It Repairs
| Rule | Before | After |
| --- | --- | --- |
| Trailing comma | `{"a": 1,}` | `{"a":1}` |
| Missing comma | `{"a": 1 "b": 2}` | `{"a":1,"b":2}` |
| Single quotes | `{'a': 'b'}` | `{"a":"b"}` |
| Unquoted keys | `{name: "Ada"}` | `{"name":"Ada"}` |
| Python literals | `{"ok": True, "none": None}` | `{"ok":true,"none":null}` |
| Comments | `{"a": 1 // note\n}` | `{"a":1}` |
| Markdown fences | ```json\n{"a":1}\n``` | `{"a":1}` |
| Smart quotes | `“a”` | `"a"` |
| Prose around JSON | `Result: {"a":1}` | `{"a":1}` |
| Truncated structure | `{"a": [1, 2` | `{"a":[1,2]}` |
## Strict Mode
`strict=True` is for validation workflows where you want `laga` to fail instead of guessing.
In strict mode, `laga` rejects ambiguous recoveries such as:
- missing commas between object members or array items
- unterminated objects or arrays
- other repairs that would require filling in structure the input did not clearly provide
## Behavior Notes
- `json.loads` is still the best choice when you control the producer and the input is already valid JSON.
- Duplicate keys use last-value-wins behavior, matching Python dict semantics.
- Use `duplicate_keys="error"` when you want duplicate object members to fail instead of being merged.
- `laga` does not evaluate expressions or try to invent arbitrary JavaScript syntax.
- The parser is intentionally conservative around malformed numbers and highly ambiguous text.
## Quick Decision Guide
| Situation | Best choice |
| --- | --- |
| You control the producer and the input is valid JSON | `json.loads` |
| You have noisy LLM output, copied config, or prose around JSON | `laga.repair` |
| You have JSONL or line-delimited records to repair | `laga.repair_jsonl` |
| You need to repair a file directly | `laga.repair_file` |
| You want duplicate keys to fail | `duplicate_keys="error"` |
| You want a human-friendly result | `repair_to_str(..., pretty=True)` |
## When To Use `laga`
Use `laga` when the input is noisy, user-facing, or generated by a model and you need a predictable repair step before parsing.
Use `json.loads` when correctness and strictness matter more than recovery.
## Development
```bash
make install
make lint
make typecheck
make test
make build
```
## Project Links
- Documentation: [docs/index.md](docs/index.md)
- API details: [docs/api.md](docs/api.md)
- Usage examples: [docs/usage.md](docs/usage.md)
- Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
## Citation
If you use `laga` in academic work, research notes, or other formal writing, please cite the repository using the metadata in [CITATION.cff](CITATION.cff).
Suggested citation format:
```text
Laitinen-Fredriksson Lundström-Imanov, G. O. Y. (2026). laga (Version 0.1.6) [Computer software]. https://github.com/olaflaitinen/laga
```