civiqhub_selene.types

Input and output types of SELENE computations.

This module holds the types that cross the engine boundary. It describes what a computation receives and returns, not the CiviqHub product model: projects, proposals, revisions and users belong to the platform and to the civiqhub SDK, which adapts them to these types before calling the engine.

Contract that every type added here follows:

  • Standard library only. Frozen dataclasses, enums and protocols; no dependency on the SDK, the CiviqHub backend, a network client or a storage layer.

  • Opaque identifiers. Entities are referenced by identifiers the engine never interprets; no personal data is required to run a computation.

  • Explicit absence. A missing value is represented as missing, never silently replaced by a default or a neutral value.

  • Explicit parameters. Every tunable of a method is a named, typed field with a documented default; nothing is read from the environment or from global state.

  • Provenance. Every result carries enough to identify how it was produced: input fingerprint and schema version, engine version, method and its parameters, and the model, weights revision and seed whenever they apply.

  • Stability. Changes to these types follow the versioning policy in CHANGELOG.md; the HTTP schemas of the service adapt to them, not the reverse.

civiqhub_selene.types.RESULT_SCHEMA = 'civiqhub_selene.result/0'

Schema identifier written by Result.to_dict().

class civiqhub_selene.types.Displayable[source]

Bases: object

Stateless mixin that gives an object its three displays from one description.

A subclass writes _describe(): the first line is the identity of the object on one line, the following lines summarise it in plain words. The mixin derives repr (the first line), str and summary() (every line), and the HTML display of notebooks (the same text, escaped, in a pre element).

A dataclass that uses the mixin is declared with repr=False, otherwise the generated __repr__ replaces this one.

_describe()[source]

Return the identity line, then the summary lines.

Return type:

list[str]

summary()[source]

Return the full description, the same text as str.

Return type:

str

class civiqhub_selene.types.Interval(lower, upper, confidence)[source]

Bases: Uncertainty

Interval around an estimate.

lower

Lower bound.

Type:

float

upper

Upper bound, at least lower.

Type:

float

confidence

Confidence level, strictly between 0 and 1.

Type:

float

Raises:

InvalidParameterError – If lower > upper or confidence is not in (0, 1).

Parameters:
  • lower (float)

  • upper (float)

  • confidence (float)

property half_width: float

Half the width of the uncertainty around the value.

class civiqhub_selene.types.Method(name, version, reference='')[source]

Bases: object

Identity of a method.

Parameters:
  • name (str)

  • version (str)

  • reference (str)

name

Stable identifier, lower case and underscores, for example ordinal_dissensus.

Type:

str

version

X.Y.Z. It changes as soon as the numbers returned can change.

Type:

str

reference

Citation of the source of the method.

Type:

str

class civiqhub_selene.types.Provenance(method, engine_version, parameters, input_fingerprint, dependencies=(), randomness=None, lineage=())[source]

Bases: object

What it takes to redo a result and to cite it.

Parameters:
  • method (Method)

  • engine_version (str)

  • parameters (tuple[tuple[str, Any], ...])

  • input_fingerprint (str)

  • dependencies (tuple[tuple[str, str], ...])

  • randomness (Randomness | None)

  • lineage (tuple[str, ...])

method

The method.

Type:

Method

engine_version

civiqhub_selene.__version__ when the computation ran.

Type:

str

parameters

The effective settings, as Settings.

Type:

tuple[tuple[str, Any], …]

input_fingerprint

Fingerprint of the input.

Type:

str

dependencies

("python", version) then one pair per third-party package used.

Type:

tuple[tuple[str, str], …]

randomness

None for a method without randomness.

Type:

Randomness | None

lineage

Fingerprints of the computations the input comes from.

Type:

tuple[str, …]

property seed: int | None

The seed as an integer, or None for a method without randomness.

fingerprint()[source]

Return the identity of the computation: 16 hexadecimal characters.

SHA-256 of the canonical JSON of the method name and version, the settings, the randomness, the input fingerprint and the lineage. engine_version and dependencies are left out: the same request on a newer NumPy is the same request.

Return type:

str

to_dict()[source]

Return plain data, ready for JSON.

Return type:

dict[str, Any]

class civiqhub_selene.types.Randomness(generator, seed)[source]

Bases: object

Pseudo-random generator used by a computation, and its seed.

Parameters:
  • generator (str)

  • seed (str)

generator

Name of the bit generator, for example "PCG64".

Type:

str

seed

The seed, kept as text so that an integer of any size survives JSON.

Type:

str

final class civiqhub_selene.types.Result(outcome, provenance, uncertainty=None)[source]

Bases: Displayable, Generic[T_co]

The only type a method of the engine returns.

It carries a value or an explained absence, the provenance, and the uncertainty when the method defines one. It decides nothing: it describes.

Two results of the same computation are equal: equality and hash follow fingerprint(). A result is neither true nor false; test is_available.

Parameters:
outcome

The value, or the Unavailable that explains its absence.

Type:

civiqhub_selene.types.T_co | Unavailable

provenance

How the result was produced.

Type:

Provenance

uncertainty

The uncertainty of the value, or None when the method does not define one. None is not a zero uncertainty.

Type:

Uncertainty | None

property is_available: bool

Whether the result holds a value.

property value: T_co

The value.

Raises:

UnavailableError – If the result has no value. The message gives the reason and the detail of the absence.

property unavailable: Unavailable | None

The explained absence, or None when there is a value.

property method: Method

The method that produced the result.

fingerprint()[source]

Return the identity of the computation, as Provenance.fingerprint().

Return type:

str

to_dict()[source]

Return the result as a dictionary under the schema RESULT_SCHEMA.

The value is written through its own to_dict() when it has one, as it is otherwise.

Return type:

dict[str, Any]

civiqhub_selene.types.Settings

Effective settings of a computation: (name, value) pairs sorted by name.

A setting that is itself a dataclass becomes the tuple (("type", ClassName), *its own pairs).

alias of tuple[tuple[str, Any], …]

class civiqhub_selene.types.StandardError(value)[source]

Bases: Uncertainty

Standard error of an estimate.

Parameters:

value (float)

value

The standard error, in the unit of the estimate.

Type:

float

property half_width: float

Half the width of the uncertainty around the value.

class civiqhub_selene.types.Unavailable(reason, detail)[source]

Bases: object

An explained absence of value.

Parameters:
reason

The kind of absence.

Type:

UnavailableReason

detail

One English sentence that names the numbers at stake.

Type:

str

class civiqhub_selene.types.UnavailableReason(*values)[source]

Bases: StrEnum

Why a method has no value to return.

class civiqhub_selene.types.Uncertainty[source]

Bases: ABC

Uncertainty of a value. None in a result means “not defined”, never “zero”.

abstract property half_width: float

Half the width of the uncertainty around the value.

civiqhub_selene.types.canonical(value)[source]

Serialise value to canonical JSON. The only serialisation used before hashing.

Keys are sorted, NaN and infinities are refused (ValueError), and an object JSON does not know is written as its repr.

Parameters:

value (object)

Return type:

str

civiqhub_selene.types.settings_of(obj)[source]

Return the settings of a dataclass instance as (name, value) pairs sorted by name.

Only the fields a caller can set (init=True) are settings. A field that is itself a dataclass is nested as (("type", ClassName), *its own pairs), and so are dataclasses held in a tuple or a list. Returns () when obj is not a dataclass instance.

Parameters:

obj (object)

Return type:

tuple[tuple[str, Any], …]