Metadata-Version: 2.4
Name: parsec-llm
Version: 0.1.2
Summary: Lightweight orchestration toolkit to generate, validate, repair and enforce structured output from LLMs
Author-email: Oliver Kwun-Morfitt <oliverkwunmorfitt@gmail.com>
Maintainer-email: Oliver Kwun-Morfitt <oliverkwunmorfitt@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/olliekm/parsec
Project-URL: Repository, https://github.com/olliekm/parsec
Project-URL: Issues, https://github.com/olliekm/parsec/issues
Project-URL: Documentation, https://github.com/olliekm/parsec#readme
Keywords: llm,structured-output,validation,json-schema,openai,anthropic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: aiohttp>=3.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# parsec

[![Tests](https://github.com/olliekm/parsec/actions/workflows/test.yml/badge.svg)](https://github.com/olliekm/parsec/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

Lightweight orchestration toolkit to generate, validate, repair and enforce
structured output from large language models (LLMs). The project provides a
provider-agnostic adapter interface, validators (JSON/pydantic), and an
enforcement engine that retries and repairs LLM output until it conforms to a
schema.

This repository contains:
- Adapter abstractions and a concrete OpenAI adapter.
- Validation and repair utilities for JSON output.
- An `EnforcementEngine` that generates, validates, repairs, and retries.
- Examples and tests demonstrating usage.

## Features

- Provider-agnostic adapter interface for plugging different LLMs.
- Native-structured output support (when providers allow JSON responses).
- JSON validation with schema-based repair heuristics.
- Retry loop with feedback to the model for progressive repair.
- Small test suite and example runner using the OpenAI adapter.

## Installation

```bash
pip install parsec-llm
```

Or for development:

```bash
git clone https://github.com/olliekm/parsec.git
cd parsec
pip install -e ".[dev]"
```

## Quick Example

```python
from parsec.models.adapters import OpenAIAdapter
from parsec.validators import JSONValidator
from parsec.enforcement import EnforcementEngine

# Set up components
adapter = OpenAIAdapter(api_key="your-api-key", model="gpt-4o-mini")
validator = JSONValidator()
engine = EnforcementEngine(adapter, validator)

# Define your schema
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name"]
}

# Enforce structured output
result = await engine.enforce(
    "Extract: John Doe is 30 years old",
    schema
)

print(result.parsed_output)  # {"name": "John Doe", "age": 30}
```

## Development Setup

Requirements: Python 3.9+

1. Install dependencies:

```bash
pip install -e ".[dev]"
```

2. Run tests:

```bash
poetry run pytest -q
```

3. Run the OpenAI example (requires `OPENAI_API_KEY`):

```bash
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o-mini"  # optional
poetry run python examples/run_with_openai.py
```

The example demonstrates using `OpenAIAdapter`, `JSONValidator` and
`EnforcementEngine` to extract structured data using a JSON schema.

## Code Structure

- `src/parsec/core` — core abstractions and schemas.
- `src/parsec/models` — provider adapters (OpenAI, Anthropic).
- `src/parsec/validators` — validator implementations.
- `src/parsec/enforcement` — enforcement/orchestration logic.
- `src/parsec/cache` — caching implementations.
- `src/parsec/utils` — utility functions (partial JSON parsing).
- `examples/` — example runners (real OpenAI example included).
- `tests/` — unit tests with pytest.

## Testing

Run the test suite with:

```bash
poetry run pytest -q
```

## Notes & Next Steps

- The OpenAI example performs real API calls — be mindful of API keys and
	costs when running it.
- Consider mocking adapters for offline or CI-safe tests.
- This project is intentionally minimal and modular — adapters and validators
	can be extended to support additional providers and formats.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Copyright (c) 2025 Oliver Kwun-Morfitt

