HGCN API

The separate graph refinement stage retains its graph curriculum, triplet objective and curvature utilities. The text model has its own objective and monitor.

CurriculumState dataclass

Lightweight container for future curriculum features (Issues #62/#63).

HGCN

Bases: Module

get_loss_weights()

Returns adaptive weights based on learned uncertainties.

HGCNLightningModule

Bases: LightningModule

PyTorch Lightning module for single-stage HGCN training.

get_final_embeddings()

Compute export embeddings with dropout disabled.

Lightning leaves the module in training mode after fit, so the pass runs in eval mode and then restores each submodule's prior mode.

HyperbolicConvolution

Bases: MessagePassing

Hyperbolic graph convolution with edge-aware attention.

Steps
  1. Map hyperbolic features to tangent space
  2. Apply linear projection
  3. Edge-aware attention with learnable relation embeddings
  4. Residual + LayerNorm
  5. Map back to hyperboloid

load_embeddings(parquet_path, device, *, embedding_prefix=STAGE3_EMBEDDING_PREFIX)

Load hyperbolic embeddings from parquet file.

Parameters:

Name Type Description Default
parquet_path str

Parquet with a level column and {embedding_prefix}{i} columns

 required
device device

Device for the returned tensors

 required
embedding_prefix str

Embedding column prefix, STAGE3_EMBEDDING_PREFIX for Stage 3 exports or STAGE4_EMBEDDING_PREFIX for HGCN output

 STAGE3_EMBEDDING_PREFIX

Returns:

Type Description
Tuple[Tensor, Tensor, DataFrame]

Embeddings in numeric column-suffix order, levels, and the full DataFrame

main(config_file='conf/graph.yaml')

Main entry point for single-stage HGCN training via PyTorch Lightning.

triplet_loss_hyp(emb, anchors, positives, negatives, margin, temperature=1.0, c=1.0, negative_weights=None)

Triplet loss with temperature scaling for curriculum learning.

Parameters:

Name Type Description Default
temperature float

Scale factor for loss (lower = sharper gradients)

 1.0