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:
objectStateless 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 derivesrepr(the first line),strandsummary()(every line), and the HTML display of notebooks (the same text, escaped, in apreelement).A dataclass that uses the mixin is declared with
repr=False, otherwise the generated__repr__replaces this one.
- class civiqhub_selene.types.Interval(lower, upper, confidence)[source]¶
Bases:
UncertaintyInterval 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 > upperorconfidenceis 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:
objectIdentity 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:
objectWhat 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, ...])
- engine_version¶
civiqhub_selene.__version__when the computation ran.- Type:
str
- 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¶
Nonefor 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
Nonefor 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_versionanddependenciesare left out: the same request on a newer NumPy is the same request.- Return type:
str
- class civiqhub_selene.types.Randomness(generator, seed)[source]¶
Bases:
objectPseudo-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; testis_available.- Parameters:
outcome (T_co | Unavailable)
provenance (Provenance)
uncertainty (Uncertainty | None)
- outcome¶
The value, or the
Unavailablethat explains its absence.- Type:
civiqhub_selene.types.T_co | Unavailable
- provenance¶
How the result was produced.
- Type:
- uncertainty¶
The uncertainty of the value, or
Nonewhen the method does not define one.Noneis 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.
The explained absence, or
Nonewhen there is a value.
- 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:
UncertaintyStandard 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.
Bases:
objectAn explained absence of value.
- Parameters:
reason (UnavailableReason)
detail (str)
The kind of absence.
- Type:
One English sentence that names the numbers at stake.
- Type:
str
Bases:
StrEnumWhy a method has no value to return.
- class civiqhub_selene.types.Uncertainty[source]¶
Bases:
ABCUncertainty of a value.
Nonein 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
valueto 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 itsrepr.- 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()whenobjis not a dataclass instance.- Parameters:
obj (object)
- Return type:
tuple[tuple[str, Any], …]