Metadata-Version: 2.4
Name: sarish-json-extract
Version: 0.0.2
Summary: Extract JSON from LLM responses and mixed text
Author: Sarish
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# sarish-json-extract

A lightweight utility to extract JSON from text — especially useful for parsing LLM responses that embed JSON inside prose or code fences.

## Features

- Extract JSON from plain strings
- Extract JSON from ` ```json ` and ` ``` ` code fences
- Extract JSON embedded in prose (e.g. LLM responses like `"Sure! Here's the data: {"name": "Sarish"} hope that helps"`)
- Handles nested objects and arrays
- Optional schema validation (type-check extracted fields)
- Zero dependencies — pure Python standard library
- Type hints with `py.typed` marker (PEP 561)

## Installation

```bash
pip install sarish-json-extract
```

## Quick Start

```python
from sarish_json_extract import extract_json

# Plain JSON
result = extract_json('{"name": "Sarish", "age": 30}')
print(result)  # {'name': 'Sarish', 'age': 30}

# JSON in code fences
result = extract_json('''Here is the data:
```json
{"city": "Bangalore"}
```
''')
print(result)  # {'city': 'Bangalore'}

# JSON embedded in LLM prose
result = extract_json('Sure! The answer is {"value": 42} as shown below.')
print(result)  # {'value': 42}

# JSON arrays
result = extract_json('Items: [1, 2, 3] done.')
print(result)  # [1, 2, 3]
```

## Schema Validation

Pass an optional `schema` dict to validate that extracted JSON has the expected keys with the correct types:

```python
from sarish_json_extract import extract_json

text = 'The user data is: {"name": "RV", "age": 30, "active": true}'

result = extract_json(text, schema={"name": str, "age": int})
print(result)  # {'name': 'RV', 'age': 30, 'active': True}

# Returns None if schema doesn't match
result = extract_json('{"name": 123}', schema={"name": str})
print(result)  # None
```

## API Reference

### `extract_json(text, schema=None)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | `str` | Yes | A string that contains JSON somewhere in it |
| `schema` | `dict[str, type]` | No | Optional type-checking schema |

**Returns:** `dict | list | None` — parsed JSON, or `None` if no valid JSON is found (or schema validation fails).

### `validate_schema(data, schema)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | `dict` | Yes | The parsed JSON dict to validate |
| `schema` | `dict[str, type]` | Yes | A dict mapping expected keys to their types |

**Returns:** `bool` — `True` if all keys exist with correct types, `False` otherwise.

## License

MIT
