judgevet.ports

Status: draft.

judgevet.ports

Ports for judgment calls and caller-owned state transformation.

Examples:

from judgevet.ports import SystemOnePort
from judgevet.domain.questions import Noul
from judgevet.domain.response import SystemOneResponse


def call_api(port: SystemOnePort) -> SystemOneResponse:
    return port.system_one(
        state="content",
        questions={"q1": Noul(instructions="Question?")},
        model="jev-latest",
    )
See Also

Attributes:

Name Type Description
AsyncSystemOnePort Protocol

Async structural protocol for calling the Jev System One API.
SystemOnePort Protocol

Structural protocol for calling the Jev System One API.
StateRedactor Protocol

Synchronous state transformation before HTTP serialization.

AsyncSystemOnePort

Bases: Protocol

Protocol for calling the Jev System One API asynchronously.

Attributes:

Name Type Description
system_one method

Method to call the Jev System One API.

Examples:

from judgevet.ports import AsyncSystemOnePort
from judgevet.domain.response import SystemOneResponse


async def call_api(port: AsyncSystemOnePort) -> SystemOneResponse:
    return await port.system_one(
        state="content",
        questions={"q1": {"type": "noul"}},
        model="jev-latest",
    )
See Also

system_one(state, questions, model) async

Call the Jev System One API.

Parameters:

Name Type Description Default
state str | dict[str, Any] | list[Any]

The content to evaluate (text, JSON object, or array).

 required
questions Mapping[str, Question | Mapping[str, Any]]

Mapping of question names to question definitions. Both Question objects and raw dicts are accepted; mixed mappings are allowed. Question objects are converted to their wire format.

 required
model str

Model name to use (e.g., jev-1.13.0).

 required

Returns:

Type Description
SystemOneResponse

Typed SystemOneResponse.
Example 
port: AsyncSystemOnePort
response = await port.system_one(
    state="content",
    questions={"q1": {"type": "noul"}},
    model="jev-latest",
)

StateRedactor

Bases: Protocol

Transform caller-owned state through a synchronous structural callback.

The HTTP adapters pass a deep copy of JSON state and serialize the returned state once per logical call. The same callback runs in sync and async clients. Applications own detection rules, callback IO and concurrency safety.

Attributes:

Name Type Description
redact method

Transform copied state before serialization.

Examples:

from typing import Any


class ReplaceState:
    def redact(self, state: str | dict[str, Any] | list[Any]) -> str:
        return "caller-selected replacement"


redactor: StateRedactor = ReplaceState()
assert redactor.redact("synthetic") == "caller-selected replacement"
See Also

redact(state)

Return replacement state without receiving questions or transport metadata.

Parameters:

Name Type Description Default
state str | dict[str, Any] | list[Any]

A private copy of the logical call's text, dictionary or list.

 required

Returns:

Type Description
str | dict[str, Any] | list[Any]

A JSON-serializable string, dictionary or list chosen by the caller.

Raises:

Type Description
Exception

Caller-defined failures propagate before any transmission.

SystemOnePort

Bases: Protocol

Protocol for calling the Jev System One API.

Attributes:

Name Type Description
system_one method

Method to call the Jev System One API.

Examples:

from judgevet.ports import SystemOnePort
from judgevet.domain.response import SystemOneResponse


def call_api(port: SystemOnePort) -> SystemOneResponse:
    return port.system_one(
        state="content",
        questions={"q1": {"type": "noul"}},
        model="jev-latest",
    )
See Also

system_one(state, questions, model)

Call the Jev System One API.

Parameters:

Name Type Description Default
state str | dict[str, Any] | list[Any]

The content to evaluate (text, JSON object, or array).

 required
questions Mapping[str, Question | Mapping[str, Any]]

Mapping of question names to question definitions. Both Question objects and raw dicts are accepted; mixed mappings are allowed. Question objects are converted to their wire format.

 required
model str

Model name to use (e.g., jev-1.13.0).

 required

Returns:

Type Description
SystemOneResponse

Typed SystemOneResponse.
Example 
port: SystemOnePort
response = port.system_one(
    state="content",
    questions={"q1": {"type": "noul"}},
    model="jev-latest",
)