gaia package

GAIA Framework - Generative Algebraic Intelligence Architecture

A categorical deep learning framework based on category theory.

Usage:

import gaia from gaia.models import GAIATransformer from gaia.nn import SpectralLinear from gaia.core import SimplicialFunctor

class gaia.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.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.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.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
gaia.FuzzySet

alias of IntegratedFuzzySet

gaia.FuzzySimplicialSet

alias of IntegratedFuzzySimplicialSet

class gaia.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.

gaia.create_model(model_type='transformer', **kwargs)[source]

Create GAIA models.

gaia.get_training_components()[source]

Get training components without circular imports

gaia.get_advanced_components()[source]

Get advanced components without circular imports

gaia.version()[source]

Get GAIA version

gaia.info()[source]

Get GAIA framework information

gaia.status()[source]

Check GAIA framework status

gaia.list_components()[source]

List all available GAIA components

Subpackages

Submodules