judgevet.providers

Status: draft.

judgevet.providers

Explicit provider selection and application-owned resource lifetimes.

There is no default provider, discovery or fallback in this module. Source: https://github.com/Alberto-Codes/judgevet/issues/201#issuecomment-5850529268. provider_scope and ProviderFactory serve a synchronous port. async_provider_scope and AsyncProviderFactory serve an asynchronous port. ProviderBusyError marks a backend that another model or caller holds. Source: https://github.com/Alberto-Codes/judgevet/issues/251.

Examples:

from judgevet.providers import ProviderError, ProviderUnavailableError

error = ProviderUnavailableError("Install the application provider extra")
assert isinstance(error, ProviderError)
See Also

AsyncProviderFactory

Bases: Protocol

Construct an async context that owns an asynchronous provider.

This Protocol mirrors ProviderFactory for an AsyncSystemOnePort. The application owns rollback if entry fails before returning a port. Source: https://github.com/Alberto-Codes/judgevet/issues/251.

Attributes:

Name Type Description
__call__ method

Construct the provider's owning async context.

Examples:

from contextlib import nullcontext

import anyio

from judgevet import NoulAnswer
from judgevet.providers import AsyncProviderFactory
from judgevet.testing import AsyncFakeSystemOnePort

factory: AsyncProviderFactory = lambda: nullcontext(
    AsyncFakeSystemOnePort(answers={"q": NoulAnswer(0.9)})
)


async def main():
    async with factory() as port:
        return await port.system_one(
            "synthetic", {"q": {"type": "noul"}}, "fixture"
        )


assert anyio.run(main).answers["q"] == NoulAnswer(0.9)

__call__()

Return an async context responsible for acquisition and cleanup.

Returns:

Type Description
AbstractAsyncContextManager[AsyncSystemOnePort]

An async context yielding the selected asynchronous judgment port.

Raises:

Type Description
ProviderUnavailableError

Application support is unavailable.

ProviderBusyError

Bases: ProviderUnavailableError

The provider is up, but another model or caller holds the backend.

No judgment ran. A shared router that refuses to load the requested model while another model holds it maps to this class. Source: https://github.com/Alberto-Codes/typevet/issues/461.

Attributes:

Name Type Description
args tuple

Standard exception arguments containing a safe message.

Examples:

from judgevet.providers import ProviderBusyError, ProviderUnavailableError

error = ProviderBusyError("Another model holds the backend")
assert isinstance(error, ProviderUnavailableError)

ProviderCapabilityError

Bases: ProviderError

The selected provider does not support a required capability.

Attributes:

Name Type Description
args tuple

Standard exception arguments containing a safe message.

Examples:

from judgevet.providers import ProviderCapabilityError

error = ProviderCapabilityError("Synthetic provider failure")
assert str(error) == "Synthetic provider failure"

ProviderError

Bases: JudgevetError

Base for declared application provider failures.

The hosted Jev hierarchy derives from this class, so the conformance kit accepts a hosted failure as a provider failure. The public import path is judgevet.providers; judgevet.domain.provider_errors re-exports it. Source: https://github.com/Alberto-Codes/judgevet/issues/259#issuecomment-5910551186.

Attributes:

Name Type Description
args tuple

Standard exception arguments containing a safe message.

Examples:

from judgevet.providers import ProviderError

error = ProviderError("Synthetic provider failure")
assert str(error) == "Synthetic provider failure"

ProviderFactory

Bases: Protocol

Construct a context that owns a synchronous provider.

The application owns rollback if entry fails before returning a port.

Attributes:

Name Type Description
__call__ method

Construct the provider's owning context.

Examples:

from contextlib import nullcontext

from judgevet import NoulAnswer
from judgevet.providers import ProviderFactory
from judgevet.testing import FakeSystemOnePort

factory: ProviderFactory = lambda: nullcontext(
    FakeSystemOnePort(answers={"q": NoulAnswer(0.9)})
)
with factory() as port:
    response = port.system_one("synthetic", {"q": {"type": "noul"}}, "fixture")
assert response.answers["q"] == NoulAnswer(0.9)

__call__()

Return a context responsible for provider acquisition and cleanup.

Returns:

Type Description
AbstractContextManager[SystemOnePort]

A context yielding the selected judgment port.

Raises:

Type Description
ProviderUnavailableError

Application support is unavailable.

ProviderRequestError

Bases: ProviderError

The provider rejects the supplied request.

Attributes:

Name Type Description
args tuple

Standard exception arguments containing a safe message.

Examples:

from judgevet.providers import ProviderRequestError

error = ProviderRequestError("Synthetic provider failure")
assert str(error) == "Synthetic provider failure"

ProviderResponseError

Bases: ProviderError

The provider returned data that violates the typed answer contract.

Attributes:

Name Type Description
args tuple

Standard exception arguments containing a safe message.

Examples:

from judgevet.providers import ProviderResponseError

error = ProviderResponseError("Synthetic provider failure")
assert str(error) == "Synthetic provider failure"

ProviderTransportError

Bases: ProviderError

Communication with the selected provider failed.

Attributes:

Name Type Description
args tuple

Standard exception arguments containing a safe message.

Examples:

from judgevet.providers import ProviderTransportError

error = ProviderTransportError("Synthetic provider failure")
assert str(error) == "Synthetic provider failure"

ProviderUnavailableError

Bases: ProviderError

The selected provider cannot be acquired or used.

Attributes:

Name Type Description
args tuple

Standard exception arguments containing a safe message.

Examples:

from judgevet.providers import ProviderUnavailableError

error = ProviderUnavailableError("Synthetic provider failure")
assert str(error) == "Synthetic provider failure"

async_provider_scope(*, port=None, factory=None) async

Borrow an async port or enter an application's owning async context.

This scope keeps every provider_scope guarantee for an asynchronous port. Selection and validation occur on entry. Borrowed resources remain open. Once factory entry succeeds, exit runs exactly once, including invalid-port validation and BaseException interruption. A context cannot suppress an escaping body exception. An exception raised by cleanup itself propagates with the original failure as its exception context. Source: https://github.com/Alberto-Codes/judgevet/issues/251.

Parameters:

Name Type Description Default
port AsyncSystemOnePort | None

A caller-owned asynchronous judgment port.

 None
factory AsyncProviderFactory | None

A callable returning an owning async context for a port.

 None

Yields:

Type Description
AsyncIterator[AsyncSystemOnePort]

The explicitly selected provider, unchanged.

Raises:

Type Description
ValueError

Neither or both selection arguments are supplied.
ProviderUnavailableError

The selected port lacks callable system_one.
BaseException

Acquisition, body and cleanup failures propagate.

provider_scope(*, port=None, factory=None)

Borrow a port or enter an application's owning provider context.

Selection and validation occur on entry. Borrowed resources remain open. Once factory entry succeeds, exit runs exactly once, including invalid-port validation and BaseException interruption. A context cannot suppress an escaping body exception. An exception raised by cleanup itself propagates with the original failure as its exception context.

Parameters:

Name Type Description Default
port SystemOnePort | None

A caller-owned judgment port.

 None
factory ProviderFactory | None

A callable returning an owning context for a judgment port.

 None

Yields:

Type Description
SystemOnePort

The explicitly selected provider, unchanged.

Raises:

Type Description
ValueError

Neither or both selection arguments are supplied.
ProviderUnavailableError

The selected port lacks callable system_one.
BaseException

Acquisition, body and cleanup failures propagate.