espnet3.contract.kinds.base.Kind

source

class espnet3.contract.kinds.base.Kind

Bases: ABC

What a field’s kind means: how a value is converted, checked and joined.

A kind turns what a caller gives into what a hook receives, checks what a hook returns, and says how pieces of a stream join. The built-in kinds are audio, text and segments; a new modality - a conversation, video, a JSON document - is a subclass passed to register_kind().

####################### Examples

>>> class Messages(Kind):
...     def check(self, value, field, model, *, output):
...         if not isinstance(value, list):
...             raise TypeError(f"{field.name} must be a list of turns")
...         return value
>>> register_kind("messages", Messages())
>>> Field("messages", "messages").kind
'messages'

accepts(value: Any, field: Field) → bool

Tell whether value could hold this kind, with no model.

For checking a value found with nothing to run - a dataset item - where check() is not an option because it may need the model it is never given. Defaults to calling check() with model=None and treating TypeError as “no”; override when a kind’s check() needs the model for something a model-free caller cannot supply (audio needs a rate when none is carried).

• Parameters:
  • value – The value to test.
  • field – The declaration the value is for.
• Returns:True when check accepts value without a model.

####################### Examples

>>> from espnet3.contract import Field
>>> from espnet3.contract.kinds.text import TextKind
>>> TextKind().accepts("hi", Field("text", "text"))
True
>>> TextKind().accepts(7, Field("text", "text"))
False

apply(value, field, model, options, , output)

Check, normalize, and recheck a value using this Kind’s configuration.

• Parameters:
  • value – What the caller gave, or what the hook returned.
  • field – The declaration the value is for.
  • model – The instance, for what it knows (its sample_rate).
  • options – The field’s kind-specific options, including normalize.
  • output – Whether the value is a hook’s result.
• Returns: The value after the checks and the listed normalizers.

####################### Examples

>>> from espnet3.contract import Field
>>> from espnet3.contract.kinds.text import TextKind
>>> options = {"normalize": ["strip", "to_lower"]}
>>> TextKind().apply(
...     "  Hi ", Field("text", "text"), None, options, output=False
... )
'hi'

abstractmethod check(value: Any, field: Field, model: Any, , output: bool) → Any

Return value as this kind holds it, or raise TypeError.

The kind decides the form; field supplies the name for the error and any per-field detail a kind may read off its declaration.

• Parameters:
  • value – What the caller gave, or what the hook returned.
  • field – The declaration the value is for.
  • model – The instance, for what it knows (its sample_rate).
  • output – Whether the value is a hook’s result rather than a caller’s argument; a kind may accept different forms for each.
• Returns:value in the form this kind holds it.

####################### Examples

>>> from espnet3.contract import Field
>>> from espnet3.contract.kinds.text import TextKind
>>> TextKind().check("hi", Field("text", "text"), None, output=False)
'hi'

check_configured(value, field, model, options, , output)

Check a value using per-field options; override for Kind-specific rules.

• Parameters:
  • value – What the caller gave, or what the hook returned.
  • field – The declaration the value is for.
  • model – The instance, for what it knows (its sample_rate).
  • options – The field’s kind-specific options.
  • output – Whether the value is a hook’s result.
• Returns:value in the form this kind holds it.

####################### Examples

>>> from espnet3.contract import Field
>>> from espnet3.contract.kinds.text import TextKind
>>> field = Field("text", "text")
>>> TextKind().check_configured("hi", field, None, {}, output=False)
'hi'

is_batch(value: Any, field: Field, model: Any) → bool

Tell one entry per sample from one value of this kind.

A list that is not itself a valid value of the kind is a batch: a list of arrays is several utterances, a [rate, samples] pair is one; a list of turns is one conversation, a list of those is several. Override when a kind can say it more cheaply.

• Parameters:
  • value – What the caller gave.
  • field – The declaration the value is for.
  • model – The instance, for what it knows (its sample_rate).
• Returns:True when value is a list with one entry per sample.

####################### Examples

>>> from espnet3.contract import Field
>>> from espnet3.contract.kinds.text import TextKind
>>> TextKind().is_batch(["a", "b"], Field("text", "text"), None)
True
>>> TextKind().is_batch("a", Field("text", "text"), None)
False

join(first: Any, second: Any) → Any

Join two consecutive pieces of one field, for gather().

Each kind says how its pieces join - text appends, audio concatenates in time - and a kind that does not say cannot be streamed: there is no default, since + on two arrays would silently add them.

• Parameters:
  • first – The piece gathered so far.
  • second – The piece that follows it.
• Returns: The two as one piece.
• Raises:NotImplementedError – Always, unless the kind overrides it.

####################### Examples

>>> from espnet3.contract.kinds.text import TextKind
>>> TextKind().join("a", "b")
'ab'

normalizers = {}

option_names = frozenset({'normalize'})

to_demo_output(value)

Convert a checked output to the value consumed by a demo component.

• Parameters:value – An output already checked by this kind.
• Returns: What the demo component shows; value unless overridden.

####################### Examples

>>> from espnet3.contract.kinds.text import TextKind
>>> TextKind().to_demo_output("hi")
'hi'

to_model_input(value, field)

Convert a checked value to the representation consumed by the runner.

• Parameters:
  • value – A value already checked by this kind.
  • field – The declaration the value is for.
• Returns: What the runner hands to the backend; value unless overridden.

####################### Examples

>>> from espnet3.contract import Field
>>> from espnet3.contract.kinds.text import TextKind
>>> TextKind().to_model_input("hi", Field("text", "text"))
'hi'

validate_options(options) → None

Validate field options. Custom Kinds may add names and constraints.

Example:

option_names = Kind.option_names | {"max_length"}

def validate_options(self, options):
    super().validate_options(options)
    if options.get("max_length", 1) <= 0:
        raise ValueError("max_length must be positive")

• Parameters:options – The field’s kind-specific options, including normalize.
• Returns: None.

####################### Examples

>>> from espnet3.contract.kinds.text import TextKind
>>> TextKind().validate_options({"normalize": ["strip"]})
>>> TextKind().validate_options({"bogus": 1})
Traceback (most recent call last):
ValueError: Unknown TextKind option(s): ['bogus']