learning-commons-evaluators 0.1.0__tar.gz

learning_commons_evaluators-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Learning Commons
+
+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 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.

learning_commons_evaluators-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+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

learning_commons_evaluators-0.1.0/README.md

@@ -0,0 +1,54 @@
+# 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

learning_commons_evaluators-0.1.0/pyproject.toml

@@ -0,0 +1,121 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "learning-commons-evaluators"
+version = "0.1.0"
+description = "Python SDK for Learning Commons educational evaluators"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Learning Commons" }]
+keywords = ["education", "evaluators", "literacy", "text-complexity"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+]
+dependencies = [
+    # LLM access is via LangChain; the langchain-* packages pull in provider SDKs as needed.
+    "pydantic>=2.0.0",
+    "textstat>=0.7.0",
+    "langchain-anthropic>=0.2.0",
+    "langchain-core>=0.3.0",
+    "langchain-google-genai>=2.0.0",
+    "langchain-openai>=0.2.0",
+    "tomli>=2.0.0; python_version < \"3.11\"",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    # Mypy is configured for Python 3.10 even when dev tooling runs on newer Python,
+    # so it needs the 3.10 tomllib backport available for type checking.
+    "tomli>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/learning-commons-org/evaluators"
+Repository = "https://github.com/learning-commons-org/evaluators/tree/main/sdks/python"
+Documentation = "https://docs.learningcommons.org/evaluators"
+"Bug Tracker" = "https://github.com/learning-commons-org/evaluators/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+learning_commons_evaluators = [
+    "py.typed",
+    "settings/**/*.toml",
+]
+
+# The settings TOML files inside the package are the bundled copy used when the
+# SDK is installed via pip.  The authoritative shared copy lives at sdks/settings/
+# (shared with TypeScript and other SDKs); keep the two in sync after any prompt
+# or settings change — see the README for instructions.
+#
+# When developing inside the monorepo, set EVALUATORS_SETTINGS_DIR to
+# sdks/settings/ so the SDK reads the shared copy instead of the bundled one:
+#
+#   export EVALUATORS_SETTINGS_DIR=/path/to/evaluators/sdks/settings
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+# ── Ruff (lint + format) ──────────────────────────────────────────────────────
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+extend-exclude = [
+    # Codegen output from ``make generate-settings`` — not hand-edited.
+    "src/learning_commons_evaluators/settings/_generated_*_settings.py",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+]
+ignore = ["E501"]  # line length — formatter wraps where it matters
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/generate_settings.py" = ["E402"]
+
+# ── Mypy ──────────────────────────────────────────────────────────────────────
+
+[tool.mypy]
+python_version = "3.10"
+mypy_path = ["src", "tests"]
+explicit_package_bases = true
+plugins = ["pydantic.mypy"]
+warn_unused_configs = true
+show_error_codes = true
+# Intentional `validate(self) -> None` on models shadows Pydantic v2's classmethod `validate`.
+disable_error_code = ["override"]
+
+[[tool.mypy.overrides]]
+module = "learning_commons_evaluators.settings.load_settings"
+disable_error_code = ["import-untyped"]
+
+[[tool.mypy.overrides]]
+module = "learning_commons_evaluators.providers.langchain"
+# LangChain stubs lag the runtime API (e.g. ChatAnthropic kwargs).
+disable_error_code = ["call-arg", "arg-type"]

learning_commons_evaluators-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

learning_commons_evaluators-0.1.0/src/learning_commons_evaluators/__init__.py

@@ -0,0 +1,154 @@
+"""Learning Commons Evaluators – Python SDK for educational text evaluators."""
+
+# Bind __version__ first so consumers reading it during package init never see AttributeError.
+from learning_commons_evaluators.version import __description__, __version__  # noqa: I001
+
+# Config
+from learning_commons_evaluators.config import (
+    AnthropicLLMProviderConfig,
+    EvaluatorConfig,
+    GoogleLLMProviderConfig,
+    LLMProviderConfig,
+    OpenAILLMProviderConfig,
+    PromptSettings,
+    TelemetryConfig,
+    create_config,
+    create_config_no_telemetry,
+    create_config_telemetry_with_full_input,
+)
+
+# Errors
+from learning_commons_evaluators.errors import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    EvaluatorError,
+    InputValidationError,
+    NetworkError,
+    OutputValidationError,
+    RateLimitError,
+    RequestTimeoutError,
+    wrap_provider_error,
+)
+
+# Evaluators
+from learning_commons_evaluators.evaluators import (
+    BaseEvaluator,
+    ConventionalityEvaluator,
+    InputT,
+    OutputT,
+    VocabularyEvaluationInput,
+    VocabularyEvaluator,
+)
+from learning_commons_evaluators.evaluators.conventionality import (
+    ConventionalityEvaluationInput,
+)
+
+# Logger (uses Python standard logging)
+from learning_commons_evaluators.logger import (
+    SDK_LOGGER_NAME,
+    Logger,
+    create_logger,
+    create_silent_logger,
+    get_logger,
+)
+from learning_commons_evaluators.schemas.common_inputs import (
+    GradeInputField,
+    TextInputField,
+)
+from learning_commons_evaluators.schemas.config import EvaluationSettings, LLMProvider
+from learning_commons_evaluators.schemas.conventionality import (
+    ConventionalityEvaluationSettings,
+    ConventionalityOutput,
+)
+
+# Schemas (core)
+from learning_commons_evaluators.schemas.evaluator import (
+    EvaluationAnswer,
+    EvaluationExplanation,
+    EvaluationInput,
+    EvaluationResult,
+    InputField,
+)
+from learning_commons_evaluators.schemas.input_specs import (
+    AnyInputSpec,
+    GradeInputSpec,
+    InputSpec,
+    TextInputSpec,
+)
+from learning_commons_evaluators.schemas.metadata import (
+    EvaluationMetadata,
+    EvaluatorMaturity,
+    EvaluatorMetadata,
+    Status,
+    TokenUsage,
+)
+from learning_commons_evaluators.schemas.text_complexity import (
+    TextComplexityEvaluationInput,
+)
+from learning_commons_evaluators.schemas.vocabulary import (
+    VocabularyComplexityOutput,
+    VocabularyEvaluationSettings,
+    normalize_complexity_output,
+)
+
+__all__ = [
+    "__description__",
+    "__version__",
+    "APIError",
+    "AnthropicLLMProviderConfig",
+    "AuthenticationError",
+    "BaseEvaluator",
+    "ConfigurationError",
+    "ConventionalityEvaluationInput",
+    "ConventionalityEvaluationSettings",
+    "ConventionalityEvaluator",
+    "ConventionalityOutput",
+    "EvaluationAnswer",
+    "EvaluationExplanation",
+    "EvaluationInput",
+    "EvaluationMetadata",
+    "EvaluationResult",
+    "EvaluationSettings",
+    "EvaluatorConfig",
+    "EvaluatorError",
+    "EvaluatorMaturity",
+    "EvaluatorMetadata",
+    "GoogleLLMProviderConfig",
+    "AnyInputSpec",
+    "GradeInputField",
+    "GradeInputSpec",
+    "InputField",
+    "InputSpec",
+    "InputT",
+    "InputValidationError",
+    "TextInputSpec",
+    "LLMProvider",
+    "LLMProviderConfig",
+    "Logger",
+    "NetworkError",
+    "OpenAILLMProviderConfig",
+    "OutputT",
+    "OutputValidationError",
+    "PromptSettings",
+    "RateLimitError",
+    "RequestTimeoutError",
+    "SDK_LOGGER_NAME",
+    "Status",
+    "TelemetryConfig",
+    "TextComplexityEvaluationInput",
+    "TextInputField",
+    "TokenUsage",
+    "VocabularyEvaluationInput",
+    "VocabularyEvaluationSettings",
+    "VocabularyEvaluator",
+    "VocabularyComplexityOutput",
+    "normalize_complexity_output",
+    "create_config",
+    "create_config_no_telemetry",
+    "create_config_telemetry_with_full_input",
+    "create_logger",
+    "create_silent_logger",
+    "get_logger",
+    "wrap_provider_error",
+]

learning_commons_evaluators-0.1.0/src/learning_commons_evaluators/config.py

@@ -0,0 +1,27 @@
+"""Re-export evaluator config from schemas.config for package-level imports."""
+
+from learning_commons_evaluators.schemas.config import (
+    AnthropicLLMProviderConfig,
+    EvaluatorConfig,
+    GoogleLLMProviderConfig,
+    LLMProviderConfig,
+    OpenAILLMProviderConfig,
+    PromptSettings,
+    TelemetryConfig,
+    create_config,
+    create_config_no_telemetry,
+    create_config_telemetry_with_full_input,
+)
+
+__all__ = [
+    "AnthropicLLMProviderConfig",
+    "EvaluatorConfig",
+    "GoogleLLMProviderConfig",
+    "OpenAILLMProviderConfig",
+    "LLMProviderConfig",
+    "PromptSettings",
+    "TelemetryConfig",
+    "create_config",
+    "create_config_no_telemetry",
+    "create_config_telemetry_with_full_input",
+]

learning_commons_evaluators-0.1.0/src/learning_commons_evaluators/errors.py

@@ -0,0 +1,31 @@
+"""Re-export error types from schemas.errors for package-level imports."""
+
+from learning_commons_evaluators.schemas.errors import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    EvaluatorError,
+    InputValidationError,
+    NetworkError,
+    OutputValidationError,
+    RateLimitError,
+    RequestTimeoutError,
+    format_error_for_metadata,
+    sanitize_pydantic_errors,
+    wrap_provider_error,
+)
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "ConfigurationError",
+    "EvaluatorError",
+    "InputValidationError",
+    "NetworkError",
+    "OutputValidationError",
+    "RateLimitError",
+    "RequestTimeoutError",
+    "format_error_for_metadata",
+    "sanitize_pydantic_errors",
+    "wrap_provider_error",
+]

learning_commons_evaluators-0.1.0/src/learning_commons_evaluators/evaluators/__init__.py

@@ -0,0 +1,29 @@
+"""Evaluator implementations.
+
+Config types (``EvaluatorConfig``, ``GoogleLLMProviderConfig``, etc.) are
+exported from the top-level :mod:`learning_commons_evaluators` package, not
+from here.  Import evaluator classes directly from this sub-package only when
+you want to be explicit about the source.
+"""
+
+from learning_commons_evaluators.evaluators.base import BaseEvaluator, InputT, OutputT
+from learning_commons_evaluators.evaluators.conventionality import (
+    ConventionalityEvaluationInput,
+    ConventionalityEvaluator,
+)
+from learning_commons_evaluators.evaluators.vocabulary import (
+    VocabularyEvaluationInput,
+    VocabularyEvaluator,
+)
+from learning_commons_evaluators.schemas.vocabulary import normalize_complexity_output
+
+__all__ = [
+    "BaseEvaluator",
+    "ConventionalityEvaluationInput",
+    "ConventionalityEvaluator",
+    "InputT",
+    "OutputT",
+    "VocabularyEvaluationInput",
+    "VocabularyEvaluator",
+    "normalize_complexity_output",
+]