gaia.core package

GAIA Core Module - Clean Architecture

This module provides the core categorical structures for the GAIA framework

class gaia.core.SimplicialObject(level, name, payload=None)[source]

Bases: object

Base class for all simplicial objects in the GAIA framework.

level: int
name: str
payload: Any
id: UUID
__init__(level, name, payload=None)
class gaia.core.Simplex0(dim, name, registry, payload=None, same_basis=False, basis_id=None)[source]

Bases: SimplicialObject

0-simplex representing an object in the Param category.

Following Mahadevan (2024), objects are equivalence classes of parameter spaces <d> modulo differentiable isomorphism.

dim
basis_id
__deepcopy__(memo)[source]

Create a deep copy with a new UUID but same basis.

__eq__(other)[source]

Equality based on basis equivalence, not just basis_id.

__hash__()[source]

Hash based on dimension and basis_id.

__init__(dim, name, registry, payload=None, same_basis=False, basis_id=None)[source]
__setattr__(name, value)[source]

Prevent modification after initialization.

id: UUID
level: int
name: str
payload: Any
class gaia.core.Simplex1(morphism, domain, codomain, name, payload=None)[source]

Bases: SimplexN

1-simplex representing a morphism in the Param category.

Following Mahadevan (2024), morphisms are equivalence classes of differentiable maps modulo parameter re-parameterization.

morphism
__call__(x)[source]

Apply the morphism to input tensor x.

If this is a composition morphism (with payload function), always use the payload to ensure dynamic composition is maintained.

__eq__(other)

Equality based on level, components, and name.

__hash__()

Hash based on level, components, and name.

__init__(morphism, domain, codomain, name, payload=None)[source]
property codomain: Simplex0
components
degeneracy(j)

Compute the j-th degeneracy by duplicating the j-th component.

Pure categorical operation with no identity checking.

property domain: Simplex0
eval()[source]

Set morphism to evaluation mode.

face(i)

Compute the i-th face by removing the i-th component.

This is a pure categorical operation - no identity verification. The functor is responsible for maintaining simplicial identities.

id: UUID
level: int
name: str
payload: Any
to(device)[source]

Move morphism to specified device.

class gaia.core.Simplex2(f, g, name, payload=None)[source]

Bases: SimplexN

2-simplex representing a commutative triangle in the Param category.

Following Mahadevan (2024), this implements the inner horn Λ²₁ with endofunctorial solver where h = g ∘ f is computed dynamically to maintain coherence during training.

components
__eq__(other)

Equality based on level, components, and name.

__hash__()

Hash based on level, components, and name.

__init__(f, g, name, payload=None)[source]
degeneracy(j)

Compute the j-th degeneracy by duplicating the j-th component.

Pure categorical operation with no identity checking.

property f: Simplex1
face(i)

Compute the i-th face by removing the i-th component.

This is a pure categorical operation - no identity verification. The functor is responsible for maintaining simplicial identities.

property g: Simplex1
property h: Simplex1
horn_type(missing_face)[source]

Determine the type of horn based on the missing face.

id: UUID
is_inner_horn(missing_face)[source]

Check if this is an inner horn with the specified missing face.

is_outer_horn(missing_face)[source]

Check if this is an outer horn with the specified missing face.

level: int
name: str
payload: Any
class gaia.core.SimplexN(level, name, components, payload=None)[source]

Bases: SimplicialObject

n-simplex for n ≥ 1, representing higher-dimensional simplicial structure.

This is a pure categorical implementation with no local identity checking. All simplicial identities are verified globally at the functor level.

components
__eq__(other)[source]

Equality based on level, components, and name.

__hash__()[source]

Hash based on level, components, and name.

__init__(level, name, components, payload=None)[source]
degeneracy(j)[source]

Compute the j-th degeneracy by duplicating the j-th component.

Pure categorical operation with no identity checking.

face(i)[source]

Compute the i-th face by removing the i-th component.

This is a pure categorical operation - no identity verification. The functor is responsible for maintaining simplicial identities.

id: UUID
level: int
name: str
payload: Any
class gaia.core.SimplicialFunctor(name, basis_registry)[source]

Bases: object

GAIA Simplicial Functor: Δᵒᵖ → Neural-network parameters.

Following Mahadevan (2024), this implements a complete simplicial functor where the functor defines all structural relationships explicitly. The functor is the sole arbiter of simplicial structure.

Key Principles: 1. Pure contravariant functor - defines structure, never discovers it 2. Global simplicial identity verification ONLY 3. Direct horn detection via structure queries 4. Explicit structure definition methods 5. Complete categorical coherence validation

__getitem__(key)[source]

Get a simplex by its UUID.

__init__(name, basis_registry)[source]
add(simplex)[source]

Registers a simplex as an object in the target category.

CRITICAL: This method does NOT infer, discover, or create any structural maps. It ONLY registers the simplex as an object. The functor defines structure through explicit define_face/define_degeneracy calls.

NO LOCAL CHECKS - all validation is global via validate() method.

create_coalgebra_structure_map(simplex_id)[source]

Create structure map γ: X → F(X) from endofunctor update history.

This constructs the coalgebraic structure map from recorded updates.

Parameters:

simplex_id (UUID) – ID of simplex

Returns:

Structure map function

Return type:

Callable

create_morphism(network, source, target, name)[source]

Factory method to create a 1-simplex (morphism) with automatic registration.

This method creates the morphism AND automatically defines its face maps according to the categorical structure.

Parameters:

  • network (Any) – Neural network implementing the morphism

  • source (Simplex0) – Source 0-simplex

  • target (Simplex0) – Target 0-simplex

  • name (str) – Name of the morphism

Returns:

Created and registered 1-simplex with face maps defined

Return type:

Simplex1

create_object(dim, name, same_basis=True)[source]

Factory method to create a 0-simplex (object) with automatic registration.

This is the ONLY correct way to create objects in the functor. The functor maintains complete control over structure.

Parameters:

  • dim (int) – Dimension of the object

  • name (str) – Name of the object

  • same_basis (bool) – Whether to use same basis (for basis registry)

Returns:

Created and registered 0-simplex

Return type:

Simplex0

create_triangle(f, g, name)[source]

Factory method to create a 2-simplex (triangle) with automatic registration.

This method creates the triangle AND automatically defines all its face maps according to the categorical structure.

Parameters:

  • f (Simplex1) – First morphism (f: A → B)

  • g (Simplex1) – Second morphism (g: B → C)

  • name (str) – Name of the triangle

Returns:

Created and registered 2-simplex with all face maps defined

Return type:

Simplex2

define_degeneracy(source_id, index, degen_id)[source]

Explicitly defines the j-th degeneracy map, s_j: [n] → [n+1]. This method is the functor’s action on the co-degeneracy maps in Δᵒᵖ.

This is how the functor DEFINES degeneracy structure.

Parameters:

  • source_id (UUID) – The source simplex UUID

  • index (int) – The degeneracy index (0 ≤ index ≤ source.level)

  • degen_id (UUID) – The target degeneracy simplex UUID

define_face(source_id, index, face_id)[source]

Explicitly defines the i-th face map, d_i: [n] → [n-1]. This method is the functor’s action on the coface maps in Δᵒᵖ.

This is how the functor DEFINES structure - the sole mechanism for creating face relationships in the categorical mapping.

Parameters:

  • source_id (UUID) – The source simplex UUID

  • index (int) – The face index (0 ≤ index ≤ source.level)

  • face_id (UUID) – The target face simplex UUID

degeneracy(index, simplex_id)[source]

Get the degeneracy of a simplex at the given index. Queries the functor’s defined structure directly.

diagnose_partial_structure()[source]

SEPARATE diagnostic method for analyzing incomplete structures.

This method is explicitly for debugging and development, providing insights into the current state of a potentially incomplete functor. It does NOT attempt to validate identities on incomplete structures.

Returns:

Dictionary with diagnostic information about structure completeness

Return type:

Dict[str, Any]

face(index, simplex_id)[source]

Get the face of a simplex at the given index. Queries the functor’s defined structure directly.

find_horns(level, horn_type='both')[source]

Locates all n-simplices where a face map is not defined.

This method now queries the functor’s structure directly

via self.maps rather than relying on non-existent pending caches. A horn is identified structurally as a missing map in the functor.

Parameters:

  • level (int) – The level of simplices to check for horns

  • horn_type (Literal['inner', 'outer', 'both']) – Type of horns to find (“inner”, “outer”, or “both”)

Returns:

List of (simplex_id, face_index) tuples representing horns

Return type:

List[Tuple[UUID, int]]

get_endofunctor_trajectory(simplex_id)[source]

Get trajectory of endofunctor updates for a simplex.

This provides the coalgebraic evolution history γ^n(x₀).

Parameters:

simplex_id (UUID) – ID of simplex

Returns:

List of endofunctor update records

Return type:

List[Dict[str, Any]]

has_lift(f_id, p_id)[source]

Queries the functor to solve a lifting problem.

This method poses the question: Given morphisms f: A -> B and p: E -> B, which morphisms h: A -> E exist such that p ∘ h = f?

Parameters:

  • f_id (UUID) – The UUID of the morphism f.

  • p_id (UUID) – The UUID of the morphism p, which must share a codomain with f.

Returns:

A list of UUIDs for all valid lifting morphisms ‘h’ found. An empty list indicates no solution was found in the functor’s structure.

Return type:

List[UUID]

load_state_dict(state_dict)[source]

Load state from dictionary (PyTorch compatibility)

register_endofunctor_update(simplex_id, old_state, new_state, endofunctor_name='F')[source]

Register endofunctor update for coalgebraic dynamics.

This method implements the structure map γ: X → F(X) for F-coalgebras by recording state transitions under endofunctor application.

Parameters:

  • simplex_id (UUID) – ID of simplex being updated

  • old_state (Any) – Previous state

  • new_state (Any) – New state after endofunctor application

  • endofunctor_name (str) – Name of endofunctor

state_dict()[source]

Return the state dictionary for serialization (PyTorch compatibility)

verify_simplicial_identities()[source]

verification of simplicial identities on a functor.

This method validates that the functor preserves the simplicial identities as required by category theory. It assumes a complete structural definition and performs a clean, elegant validation of the three identity classes:

  1. Face-face identities: d_i ∘ d_j = d_{j-1} ∘ d_i for i < j

  2. Degeneracy-degeneracy identities: s_i ∘ s_j = s_{j+1} ∘ s_i for i ≤ j

  3. Mixed identities: Various d_i ∘ s_j relations

Returns:

Dictionary with validation results for complete structure only

Return type:

Dict[str, Any]

class gaia.core.MapType(value)[source]

Bases: Enum

FACE = 'face'
DEGENERACY = 'degeneracy'
classmethod __contains__(member)

Return True if member is a member of this enum raises TypeError if member is not an enum member

note: in 3.12 TypeError will no longer be raised, and True will also be returned if member is the value of a member in this enum

classmethod __getitem__(name)

Return the member matching name.

classmethod __iter__()

Return members in definition order.

classmethod __len__()

Return the number of members (no aliases)

exception gaia.core.HornError[source]

Bases: SimplicialError

Error raised when a horn is encountered.

__init__(*args, **kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class gaia.core.IntegratedFuzzySet(elements, membership_fn, name='fuzzy_set')[source]

Bases: GAIAComponent

Integrated fuzzy set implementing sheaf structure on [0,1].

__init__(elements, membership_fn, name='fuzzy_set')[source]
alpha_cut(alpha)[source]

Return α-cut {x | μ(x) ≥ α}.

get_membership(element)[source]

Get membership degree for element.

initialize()[source]

Initialize fuzzy set by computing membership for all elements.

merge_with(other, t_conorm=TConorm.MAXIMUM)[source]

Merge with another fuzzy set using t-conorm.

support()[source]

Return support set {x | μ(x) > 0}.

update(state)[source]

Update fuzzy set based on training state.

validate()[source]

Validate fuzzy set properties.

class gaia.core.IntegratedSimplex(dimension, name, components=None, membership=1.0, payload=None)[source]

Bases: SimplicialStructure

Integrated simplex with fuzzy membership and categorical structure.

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__init__(dimension, name, components=None, membership=1.0, payload=None)[source]
degeneracy_map(i)[source]

Apply i-th degeneracy map σᵢ preserving membership.

property dimension: int

Dimension of the simplex.

face_map(i)[source]

Apply i-th face map δᵢ with membership coherence.

verify_simplicial_identities()[source]

Verify simplicial identities hold.

class gaia.core.IntegratedFuzzySimplicialSet(name, max_dimension=3)[source]

Bases: GAIAComponent

Integrated fuzzy simplicial set combining fuzzy and simplicial structures.

__init__(name, max_dimension=3)[source]
add_simplex(dimension, simplex_data, membership=1.0)[source]

Add a simplex with given membership.

get_membership(dimension, simplex_data)[source]

Get membership degree for a simplex.

initialize()[source]

Initialize all fuzzy sets.

merge_with(other, t_conorm=TConorm.MAXIMUM)[source]

Merge with another fuzzy simplicial set.

update(state)[source]

Update fuzzy simplicial set based on training state.

validate()[source]

Validate fuzzy simplicial set properties.

class gaia.core.IntegratedCoalgebra(initial_state, endofunctor, name='coalgebra')[source]

Bases: Coalgebra[<MockTorch name=’mock.Tensor’ id=’4349657872’>], GAIAComponent

Integrated coalgebra for GAIA training dynamics.

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__init__(initial_state, endofunctor, name='coalgebra')[source]
evolve(state)

Evolve state using structure map: γ(state).

initialize()[source]

Initialize coalgebra.

is_bisimilar(other, relation)[source]

Check bisimilarity with another coalgebra.

iterate_dynamics(steps)[source]

Iterate coalgebra dynamics for multiple steps.

update(state)[source]

Update coalgebra with new training state.

validate()[source]

Validate coalgebra properties.

class gaia.core.TConorm(value)[source]

Bases: Enum

T-conorms for fuzzy set operations.

apply(a, b)[source]

Apply the t-conorm operation.

MAXIMUM = 'maximum'
PROBABILISTIC = 'probabilistic'
LUKASIEWICZ = 'lukasiewicz'
classmethod __contains__(member)

Return True if member is a member of this enum raises TypeError if member is not an enum member

note: in 3.12 TypeError will no longer be raised, and True will also be returned if member is the value of a member in this enum

classmethod __getitem__(name)

Return the member matching name.

classmethod __iter__()

Return members in definition order.

classmethod __len__()

Return the number of members (no aliases)

class gaia.core.FuzzyElement(element, membership)[source]

Bases: object

Element with fuzzy membership degree.

__init__(element, membership)
element: Any
membership: float
gaia.core.create_fuzzy_simplex(dimension, name, membership=1.0)[source]

Create a fuzzy simplex with given properties.

gaia.core.create_fuzzy_simplicial_set_from_data(data, k=5, name='data_fss')[source]

Create fuzzy simplicial set from point cloud data using k-NN.

gaia.core.merge_fuzzy_simplicial_sets(*fss_list, t_conorm=TConorm.MAXIMUM)[source]

Merge multiple fuzzy simplicial sets.

class gaia.core.KanComplexVerifier(simplicial_functor)[source]

Bases: object

Complete Kan complex verification system.

This orchestrates all Kan condition verifications and provides a comprehensive assessment of the simplicial structure.

__init__(simplicial_functor)[source]
get_kan_complex_status()[source]

Get overall Kan complex status.

suggest_improvements()[source]

Suggest improvements to achieve Kan complex conditions.

verify_all_conditions(tolerance=1e-3)[source]

Verify all Kan conditions for the entire simplicial complex.

Returns comprehensive verification report.

class gaia.core.KanConditionType(value)[source]

Bases: Enum

Types of Kan conditions to verify.

INNER_HORN_FILLING = 'inner_horn_filling'
OUTER_HORN_FILLING = 'outer_horn_filling'
LIFTING_PROPERTY = 'lifting_property'
FIBRATION_CONDITION = 'fibration_condition'
HOMOTOPY_EXTENSION = 'homotopy_extension'
classmethod __contains__(member)

Return True if member is a member of this enum raises TypeError if member is not an enum member

note: in 3.12 TypeError will no longer be raised, and True will also be returned if member is the value of a member in this enum

classmethod __getitem__(name)

Return the member matching name.

classmethod __iter__()

Return members in definition order.

classmethod __len__()

Return the number of members (no aliases)

class gaia.core.KanConditionResult(condition_type, simplex_id, simplex_name, horn_index, satisfied, confidence, error_message=None, verification_data=<factory>)[source]

Bases: object

Result of a Kan condition verification.

__init__(condition_type, simplex_id, simplex_name, horn_index, satisfied, confidence, error_message=None, verification_data=<factory>)
error_message: str | None = None
condition_type: KanConditionType
simplex_id: UUID
simplex_name: str
horn_index: int | None
satisfied: bool
confidence: float
verification_data: Dict[str, Any]
gaia.core.get_training_components()[source]

Get training components without circular imports

gaia.core.get_advanced_components()[source]

Get advanced components without circular imports

Submodules