API REFERENCE/omnibias-core

omnibias.core.proof.catalog

0.5.0rc1Release candidatePython >=3.10Apache-2.0

Coefficient recurrences, activation contracts, jet algebra, and verified arithmetic shared by the numerical backends.

import omnibias.core.proof.catalog

Module contract & mathematical conventions

Cross-package registry of discoverable statements.

Core never imports holonomic / combinatorics / symbolic / pinn. Owning packages call register_catalog at import time. list_catalog therefore shows only packages that have already been imported. discover runs a registered factory or tells the caller which package to import.

Modes:

• exact_search -- ~omnibias.core.proof.discovery.run_discovery
• exact_replay -- an existing verify_* (never a planted fake search)
• enclosure / empirical -- ProofMachine or residual payload; never an ~omnibias.core.proof.discovery.ExactCheck forged from a float residual

Shared formulas do not imply universal floating-point identity. Verify dtype, shape, derivative-order support, and the stated numerical assumptions for the path you use.

Module source ↗Source revision 9a2d73df0573Running reference examples →

CLASS

CatalogEntry

omnibias.core.proof.CatalogEntrySource ↗

class CatalogEntry

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

Metadata for one discoverable kind. Factories live beside the entry.

Parameters

Name	Type & default	Contract
kinddataclass field	strRequired	See the operation contract and implementation below.
obligationdataclass field	strRequired	See the operation contract and implementation below.
parentdataclass field	strRequired	See the operation contract and implementation below.
parent_statusdataclass field	ParentStatusRequired	See the operation contract and implementation below.
packagedataclass field	strRequired	See the operation contract and implementation below.
modedataclass field	CatalogModeRequired	See the operation contract and implementation below.
completedataclass field	boolRequired	See the operation contract and implementation below.
existentialdataclass field	boolDefault: True	See the operation contract and implementation below.

Regression example · kind collision raises

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_kind_collision_raises() -> None:
    kind = "integer_square_toy_collision"
    register_catalog(_toy_entry(kind))
    try:
        register_catalog(
            CatalogEntry(
                kind=kind,
                obligation="a different obligation",
                parent="toy",
                parent_status="already_true",
                package="omnibias.core.proof",
                mode="exact_search",
                complete=True,
            )
        )
    except ValueError as exc:
        assert "collision" in str(exc)
    else:
        raise AssertionError("expected ValueError")

python -m pytest packages/omnibias-core/tests/test_catalog.py -k test_kind_collision_raises -q

Fields & methods

kindfield

kind: str

Declared str field on CatalogEntry. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

obligationfield

obligation: str

Declared str field on CatalogEntry. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

parentfield

parent: str

Declared str field on CatalogEntry. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

parent_statusfield

parent_status: ParentStatus

Declared ParentStatus field on CatalogEntry. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

packagefield

package: str

Declared str field on CatalogEntry. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

modefield

mode: CatalogMode

Declared CatalogMode field on CatalogEntry. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

completefield

complete: bool

Declared bool field on CatalogEntry. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

existentialfield

existential: bool = True

Declared bool field on CatalogEntry. Default expression: True.

View source ↗

Read the implementation

class CatalogEntry:
    """Metadata for one discoverable kind. Factories live beside the entry."""

    kind: str
    obligation: str
    parent: str
    parent_status: ParentStatus
    package: str
    mode: CatalogMode
    complete: bool
    existential: bool = True

Other public import paths

• omnibias.core.proof.CatalogEntry
• omnibias.core.proof.catalog.CatalogEntry

CONSTANT

CatalogFactory

omnibias.core.proof.catalog.CatalogFactorySource ↗

CatalogFactory = Callable[..., Any]

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

CatalogFactory = Callable[..., Any]

CONSTANT

CatalogMode

omnibias.core.proof.catalog.CatalogModeSource ↗

CatalogMode = Literal['exact_search', 'exact_replay', 'enclosure', 'empirical']

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

CatalogMode = Literal["exact_search", "exact_replay", "enclosure", "empirical"]

FUNCTION

catalog_entry

omnibias.core.proof.catalog_entrySource ↗

catalog_entry(kind: str) -> CatalogEntry | None

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
kindpositional-or-keyword	strRequired	See the operation contract and implementation below.

ReturnsCatalogEntry | None

Executed regression · same entry is idempotent

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_same_entry_is_idempotent() -> None:
    entry = _toy_entry()
    register_catalog(entry, _toy_factory)
    register_catalog(entry, _toy_factory)
    assert catalog_entry("integer_square_toy") == entry

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_same_entry_is_idempotent" -q

Read the implementation

def catalog_entry(kind: str) -> CatalogEntry | None:
    return _ENTRIES.get(kind)

Other public import paths

• omnibias.core.proof.catalog_entry
• omnibias.core.proof.catalog.catalog_entry

FUNCTION

discover

omnibias.core.proof.discoverSource ↗

discover(kind: str, **kwargs: Any) -> Any

Run the registered factory for kind.

Raises

KeyError No factory is registered. Import the owning package first.

Parameters

Name	Type & default	Contract
kindpositional-or-keyword	strRequired	See the operation contract and implementation below.
kwargsvariadic keyword	AnyRequired	See the operation contract and implementation below.

ReturnsAny

Explicit validation & failure cases

• When factory is None, raises KeyError(f'no factory for {kind!r}; import {package}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · unknown kind names owning package

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_unknown_kind_names_owning_package() -> None:
    try:
        discover("not_a_kind")
    except KeyError as exc:
        assert "the owning package" in str(exc)
    else:
        raise AssertionError("expected KeyError")

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_unknown_kind_names_owning_package" -q

Regression example · register and discover toy

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest packages/omnibias-core/tests/test_catalog.py -k test_register_and_discover_toy -q

Read the implementation

def discover(kind: str, **kwargs: Any) -> Any:
    """Run the registered factory for ``kind``.

    Raises
    ------
    KeyError
        No factory is registered. Import the owning package first.
    """

    factory = _FACTORIES.get(kind)
    if factory is None:
        entry = _ENTRIES.get(kind)
        package = entry.package if entry is not None else "the owning package"
        raise KeyError(f"no factory for {kind!r}; import {package}")
    return factory(**kwargs)

Other public import paths

• omnibias.core.proof.discover
• omnibias.core.proof.catalog.discover

FUNCTION

list_catalog

omnibias.core.proof.list_catalogSource ↗

list_catalog() -> tuple[CatalogEntry, ...]

Entries from packages imported so far, sorted by kind.

Returnstuple[CatalogEntry, ...]

Executed regression · register and discover toy

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Read the implementation

def list_catalog() -> tuple[CatalogEntry, ...]:
    """Entries from packages imported so far, sorted by kind."""

    return tuple(sorted(_ENTRIES.values(), key=lambda item: item.kind))

Other public import paths

• omnibias.core.proof.list_catalog
• omnibias.core.proof.catalog.list_catalog

FUNCTION

register_catalog

omnibias.core.proof.register_catalogSource ↗

register_catalog(entry: CatalogEntry, factory: CatalogFactory | None=None) -> None

Register entry (and optionally its factory). Same entry is idempotent.

Parameters

Name	Type & default	Contract
entrypositional-or-keyword	CatalogEntryRequired	See the operation contract and implementation below.
factorypositional-or-keyword	CatalogFactory | NoneDefault: None	See the operation contract and implementation below.

ReturnsNone

Explicit validation & failure cases

• When existing is not None and existing != entry, raises ValueError(f'catalog kind collision: {entry.kind!r} already registered as {existing}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · same entry is idempotent

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_same_entry_is_idempotent() -> None:
    entry = _toy_entry()
    register_catalog(entry, _toy_factory)
    register_catalog(entry, _toy_factory)
    assert catalog_entry("integer_square_toy") == entry

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_same_entry_is_idempotent" -q

Regression example · register and discover toy

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest packages/omnibias-core/tests/test_catalog.py -k test_register_and_discover_toy -q

Read the implementation

def register_catalog(
    entry: CatalogEntry,
    factory: CatalogFactory | None = None,
) -> None:
    """Register ``entry`` (and optionally its factory). Same entry is idempotent."""

    existing = _ENTRIES.get(entry.kind)
    if existing is not None and existing != entry:
        raise ValueError(
            f"catalog kind collision: {entry.kind!r} already registered as {existing}"
        )
    _ENTRIES[entry.kind] = entry
    if factory is not None:
        _FACTORIES[entry.kind] = factory

Other public import paths

• omnibias.core.proof.register_catalog
• omnibias.core.proof.catalog.register_catalog

← Package overviewRunnable learning examples →