Metadata-Version: 2.4
Name: learning-commons-evaluators
Version: 0.1.0
Summary: Python SDK for Learning Commons educational evaluators
Author: Learning Commons
License: MIT
Project-URL: Homepage, https://github.com/learning-commons-org/evaluators
Project-URL: Repository, https://github.com/learning-commons-org/evaluators/tree/main/sdks/python
Project-URL: Documentation, https://docs.learningcommons.org/evaluators
Project-URL: Bug Tracker, https://github.com/learning-commons-org/evaluators/issues
Keywords: education,evaluators,literacy,text-complexity
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: textstat>=0.7.0
Requires-Dist: langchain-anthropic>=0.2.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-google-genai>=2.0.0
Requires-Dist: langchain-openai>=0.2.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"
Requires-Dist: mypy>=1.14.0; extra == "dev"
Requires-Dist: tomli>=2.0.0; extra == "dev"
Dynamic: license-file

# learning-commons-evaluators (Python)

Python SDK for Learning Commons educational text evaluators. Evaluators call LLMs via LangChain, return structured Pydantic results, and share a common configuration and error-handling model.

## Installation

```bash
pip install learning-commons-evaluators
```

Requires **Python 3.10+**. Provider API keys are passed in at runtime (not bundled with the package).

## Quick start

```python
import logging
from learning_commons_evaluators import (
    ConventionalityEvaluator,
    ConventionalityEvaluationInput,
    GoogleLLMProviderConfig,
    create_config_no_telemetry,
)

logging.basicConfig(level=logging.INFO)

config = create_config_no_telemetry(
    google_llm_provider_config=GoogleLLMProviderConfig(api_key="your-google-key"),
)

evaluator = ConventionalityEvaluator(config)
result = evaluator.evaluate_sync(
    ConventionalityEvaluationInput(text="The cat's out of the bag now.", grade=5)
)

print(result.answer.label)        # e.g. "Moderately complex"
print(result.explanation.summary) # Reasoning for the score
```

## Docs

For full implementation details, check out the [Python SDK docs](https://docs.learningcommons.org/evaluators/sdk-api-reference/overview).

## More resources

- [Local development](./docs/local-development.md) – Local setup, testing, and development
- [Evaluators](./docs/evaluators.md) — Shipped evaluators with their inputs, outputs, and evaluation settings
- [Running evaluations](./docs/running-evaluations.md) — Sync / async usage and per-call settings overrides
- [Results](./docs/results.md) — `EvaluationResult` shape and metadata
- [Configuration](./docs/configuration.md) — Provider configs, `EvaluatorConfig`, evaluation settings, logging
- [Error handling](./docs/error-handling.md) — Exception hierarchy, retries, and sanitization

## License

MIT
