shesha-geometry 0.1.0__py3-none-any.whl

shesha_geometry-0.1.0.dist-info/METADATA

@@ -0,0 +1,396 @@
+Metadata-Version: 2.1
+Name: shesha-geometry
+Version: 0.1.0
+Summary: Self-consistency metrics for representational stability analysis
+Author-email: Prashant Raju <rajuprashant@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/prashantcraju/shesha
+Project-URL: Documentation, https://github.com/prashantcraju/shesha#readme
+Project-URL: Repository, https://github.com/prashantcraju/shesha
+Project-URL: Issues, https://github.com/prashantcraju/shesha/issues
+Keywords: representation learning,neural networks,geometric stability,geometric analysis,manifold analysis,latent space,single-cell,crispr,perturb-seq,anndata,functional genomics,phenotypic stability,computational biology,scanpy,llm alignment,concept drift,model steering,ai safety,constitutional ai,perturbation analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.7
+Requires-Dist: anndata>=0.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+[![DOI](https://zenodo.org/badge/1133185691.svg)](https://doi.org/10.5281/zenodo.18227453)
+<p align="center">
+    <img src="https://i.imgur.com/oJ5YhBo.jpg" alt="Shesha Logo" width="300">
+</p>
+
+# Shesha
+
+Self-consistency metrics for representational stability analysis.
+
+Shesha measures the geometric stability of high-dimensional representations by quantifying the self-consistency of their pairwise distance structure (RDMs) under controlled internal perturbations.
+
+## Installation
+
+```bash
+pip install shesha-geometry
+```
+
+## Quick Start
+
+```python
+import numpy as np
+import shesha
+
+# Your embeddings: (n_samples, n_features)
+X = np.random.randn(500, 768)
+
+# Feature-split stability (unsupervised)
+stability = shesha.feature_split(X, n_splits=30, seed=320)
+print(f"Feature-split stability: {stability:.3f}")
+```
+
+With labels:
+
+```python
+y = np.random.randint(0, 10, 500)
+alignment = shesha.supervised_alignment(X, y)
+print(f"Supervised alignment: {alignment:.3f}")
+```
+
+Measuring drift between representations:
+
+```python
+X_before = np.random.randn(100, 256)
+X_after = X_before + np.random.randn(100, 256) * 0.3  # Add noise
+
+# Compare before/after fine-tuning
+similarity = shesha.rdm_similarity(X_before, X_after)
+drift = shesha.rdm_drift(X_before, X_after)
+print(f"RDM similarity: {similarity:.3f}, drift: {drift:.3f}")
+```
+
+
+## Variants
+
+### Unsupervised (no labels required)
+
+**`feature_split(X, n_splits=30, metric='cosine', seed=None)`**
+
+Correlates RDMs from random feature partitions. Use for internal consistency and drift detection.
+
+**`sample_split(X, n_splits=30, subsample_fraction=0.4, seed=None)`**
+
+Correlates RDMs from bootstrap samples. Use for robustness to sampling.
+
+**`anchor_stability(X, n_splits=30, n_anchors=100, seed=None)`**
+
+Distance profile consistency from fixed anchors. Use for large-scale stability.
+
+### Supervised (labels required)
+
+**`variance_ratio(X, y)`**
+
+Between-class / total variance. Use for quick separability check.
+
+**`supervised_alignment(X, y, metric='correlation', seed=None)`**
+
+Correlation with ideal label RDM. Use for task alignment.
+
+### Drift Metrics (comparing two representations)
+
+**`rdm_similarity(X, Y, method='spearman', metric='cosine')`**
+
+RDM correlation between two representations. Use for comparing models or tracking changes.
+
+**`rdm_drift(X, Y, method='spearman', metric='cosine')`**
+
+Representational drift (1 - similarity). Use for quantifying how much geometry has changed.
+
+## Examples
+
+### Comparing model stability
+
+```python
+import numpy as np
+import shesha
+
+# Example embeddings from two different models
+embeddings_a = np.random.randn(500, 768)  # Model A embeddings
+embeddings_b = np.random.randn(500, 768)  # Model B embeddings
+
+models = {'model_a': embeddings_a, 'model_b': embeddings_b}
+
+for name, X in models.items():
+    fs = shesha.feature_split(X, seed=320)
+    print(f"{name}: {fs:.3f}")
+```
+
+### Monitoring fine-tuning drift
+
+```python
+import shesha
+
+X_initial = model.encode(data)
+
+for epoch in range(10):
+    train_one_epoch(model)
+    X_current = model.encode(data)
+    
+    # Internal stability
+    stability = shesha.feature_split(X_current, seed=320)
+    
+    # Drift from initial
+    drift = shesha.rdm_drift(X_initial, X_current)
+    
+    print(f"Epoch {epoch}: stability={stability:.3f}, drift={drift:.3f}")
+```
+
+### Comparing two models
+
+```python
+import shesha
+
+X_model1 = model1.encode(data)
+X_model2 = model2.encode(data)
+
+# How similar are their geometric structures?
+similarity = shesha.rdm_similarity(X_model1, X_model2)
+print(f"Model similarity: {similarity:.3f}")
+```
+
+### Analyzing single-cell perturbations
+
+Measure the geometric consistency of CRISPR/drug screens directly from `AnnData` objects:
+
+```python
+import numpy as np
+from shesha.bio import compute_stability, compute_magnitude
+from anndata import AnnData
+
+
+# 1. Setup mock single-cell data (1000 cells, 50 PCA features)
+n_cells = 1000
+n_genes = 2000  # Original feature space (genes)
+n_pcs = 50
+
+# Create a mock AnnData object
+# Note: Shesha works best on PCA coordinates (latent space), not raw counts
+adata = AnnData(X=np.random.randn(n_cells, n_genes))  # Raw counts (unused)
+adata.obsm['X_pca'] = np.random.randn(n_cells, n_pcs)  # PCA embeddings
+adata.obs['guide_id'] = ['NT'] * 800 + ['KLF1'] * 200  # Metadata
+
+
+# Create a proxy for PCA coordinates (Recommended for robust geometry)
+adata_pca = AnnData(X=adata.obsm['X_pca'], obs=adata.obs)
+
+
+# Compute Stability (Consistency of the phenotype)
+stability = compute_stability(
+    adata_pca, 
+    perturbation_key='guide_id', 
+    control_label='NT',
+    metric='cosine'
+)
+
+# Compute Magnitude (Strength of the phenotype)
+magnitude = compute_magnitude(
+    adata_pca, 
+    perturbation_key='guide_id', 
+    control_label='NT', 
+    metric='euclidean'
+)
+
+print(f"KLF1 Stability: {stability['KLF1']:.3f}")  # e.g., 0.85 (High = Consistent)
+print(f"KLF1 Magnitude: {magnitude['KLF1']:.3f}")  # e.g., 2.40 (High = Strong)
+```
+
+
+## API Reference
+
+### `shesha.feature_split(X, n_splits=30, metric='cosine', seed=None, max_samples=1600)`
+
+Measures internal geometric consistency by correlating RDMs computed from random, disjoint subsets of feature dimensions.
+
+**Parameters:**
+- `X` - array of shape (n_samples, n_features)
+- `n_splits` - number of random partitions to average
+- `metric` - 'cosine' or 'correlation'
+- `seed` - random seed for reproducibility
+- `max_samples` - subsample if exceeded
+
+**Returns:** float in [-1, 1], higher = more stable
+
+### `shesha.sample_split(X, n_splits=30, subsample_fraction=0.4, metric='cosine', seed=None, max_samples=1500)`
+
+Measures robustness to input variation via bootstrap resampling.
+
+**Parameters:**
+- `X` - array of shape (n_samples, n_features)
+- `n_splits` - number of bootstrap iterations
+- `subsample_fraction` - fraction of samples per bootstrap
+- `metric` - 'cosine' or 'correlation'
+- `seed` - random seed for reproducibility
+- `max_samples` - subsample if exceeded
+
+**Returns:** float in [-1, 1], higher = more stable
+
+### `shesha.anchor_stability(X, n_splits=30, n_anchors=100, n_per_split=200, metric='cosine', rank_normalize=True, seed=None, max_samples=1500)`
+
+Measures stability of distance profiles from fixed anchor points.
+
+**Parameters:**
+- `X` - array of shape (n_samples, n_features)
+- `n_splits` - number of random splits
+- `n_anchors` - number of fixed anchor points
+- `n_per_split` - samples per split
+- `metric` - 'cosine' or 'euclidean'
+- `rank_normalize` - rank-normalize distances within each anchor
+- `seed` - random seed for reproducibility
+- `max_samples` - subsample if exceeded
+
+**Returns:** float in [-1, 1], higher = more stable
+
+### `shesha.variance_ratio(X, y)`
+
+Ratio of between-class to total variance.
+
+**Parameters:**
+- `X` - array of shape (n_samples, n_features)
+- `y` - array of shape (n_samples,) with class labels
+
+**Returns:** float in [0, 1], higher = better class separation
+
+### `shesha.supervised_alignment(X, y, metric='correlation', seed=None, max_samples=300)`
+
+Spearman correlation between model RDM and ideal label-based RDM.
+
+**Parameters:**
+- `X` - array of shape (n_samples, n_features)
+- `y` - array of shape (n_samples,) with class labels
+- `metric` - 'cosine' or 'correlation'
+- `seed` - random seed for reproducibility
+- `max_samples` - subsample if exceeded (RDM is O(n^2))
+
+**Returns:** float in [-1, 1], higher = better task alignment
+
+### `shesha.rdm_similarity(X, Y, method='spearman', metric='cosine')`
+
+Computes RDM correlation between two representations. Useful for comparing models, tracking drift during training, or measuring the effect of interventions.
+
+**Parameters:**
+- `X` - array of shape (n_samples, n_features_x), first representation
+- `Y` - array of shape (n_samples, n_features_y), second representation (same n_samples)
+- `method` - 'spearman' (rank-based, default) or 'pearson' (linear)
+- `metric` - 'cosine', 'correlation', or 'euclidean'
+
+**Returns:** float in [-1, 1], higher = more similar geometric structure
+
+### `shesha.rdm_drift(X, Y, method='spearman', metric='cosine')`
+
+Computes representational drift as 1 - rdm_similarity. Useful for quantifying how much a representation has changed.
+
+**Parameters:**
+- `X` - array of shape (n_samples, n_features_x), baseline representation
+- `Y` - array of shape (n_samples, n_features_y), comparison representation
+- `method` - 'spearman' (rank-based, default) or 'pearson' (linear)
+- `metric` - 'cosine', 'correlation', or 'euclidean'
+
+**Returns:** float in [0, 2], where 0 = identical, 1 = uncorrelated, 2 = inverted
+
+## Biological Perturbation Analysis
+
+The `shesha.bio` module provides metrics for single-cell perturbation experiments (e.g., Perturb-seq, CRISPR screens).
+
+### `shesha.bio.perturbation_stability(X_control, X_perturbed, metric='cosine', seed=None, max_samples=1000)`
+
+Measures consistency of perturbation effects across samples. High values indicate coherent, reproducible perturbation effects.
+
+**Parameters:**
+- `X_control` - array of shape (n_control, n_features), control population
+- `X_perturbed` - array of shape (n_perturbed, n_features), perturbed population
+- `metric` - 'cosine' (default) or 'euclidean'
+- `seed` - random seed for reproducibility
+- `max_samples` - subsample perturbed population if exceeded
+
+**Returns:** float in [-1, 1], higher = more consistent perturbation
+
+### `shesha.bio.perturbation_effect_size(X_control, X_perturbed)`
+
+Cohen's d-like effect size measuring magnitude of perturbation shift.
+
+**Parameters:**
+- `X_control` - array of shape (n_control, n_features)
+- `X_perturbed` - array of shape (n_perturbed, n_features)
+
+**Returns:** float >= 0, higher = larger perturbation effect
+
+### Scanpy / AnnData Integration
+
+For single-cell analysis, Shesha provides high-level wrappers that work directly with `AnnData` objects.
+
+### `shesha.bio.compute_stability(adata, perturbation_key, control_label, layer=None, metric='cosine')`
+
+Computes the geometric stability for every perturbation in the dataset.
+
+**Parameters:**
+- `adata` - AnnData object.
+- `perturbation_key` - Column in `adata.obs` identifying the perturbation (e.g., `'guide_id'`).
+- `control_label` - The label in that column representing control cells (e.g., `'NT'`).
+- `layer` - (Optional) Layer to use (e.g., `'pca'`). If None, uses `.X`.
+- `metric` - `'cosine'` (default) or `'euclidean'`.
+
+**Returns:** Dictionary `{perturbation_name: stability_score}`.
+
+### `shesha.bio.compute_magnitude(adata, perturbation_key, control_label, layer=None, metric='euclidean')`
+
+Computes the magnitude (effect size) for every perturbation.
+
+**Parameters:**
+- `adata` - AnnData object.
+- `metric` - `'euclidean'` (default, raw distance) or `'cohen'` (standardized effect size).
+
+**Returns:** Dictionary `{perturbation_name: magnitude_score}`.
+
+
+## Citation
+
+If you use `shesha-geometry`, please cite:
+```bibtex
+@software{shesha2026,
+    title = {Shesha: Self-consistency Metrics for Representational Stability},
+    author = {Prashant C. Raju},
+    year = {2026},
+    url = {https://github.com/prashantcraju/shesha},
+    publisher = {Zenodo},
+    doi = {10.5281/zenodo.18227454},
+    note = {Python package version 0.1.0}
+}
+
+@article{raju2026geometric,
+    title={Geometric Stability: The Missing Axis of Representations},
+    author={Prashant C. Raju},
+    journal={arXiv},
+    year={2026}
+}
+```
+
+## License
+
+MIT
+
+---
+
+<sub>Logo generated by [Nano Banana Pro](https://nanobananapro.com)</sub>

shesha_geometry-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+examples/tutorial.py,sha256=HoDNK_NgCEW7_PkfOkKswNH2mitCHPJ56yuldiH8skI,12167
+shesha/__init__.py,sha256=KaDsrk_j30OeFn7M70nHmCXp5MJ-cumS-eiT7PZyJQY,1390
+shesha/bio.py,sha256=4fZHfLfkMIbAYEJ80MJreP8Hg9ApoOQUtk0uDuX1ejo,10465
+shesha/core.py,sha256=_M--xVtbOBRujpCeSNu_Ala_gTjDhfJUbv8BvaaUHGM,19986
+tests/__init__.py,sha256=YYq097nXxIO0mWUP8sqw6YS-CSjFRWVEa1lPN7ATA0U,27
+tests/test_bio.py,sha256=71poE9FbfjWnAQFYFHAiPsGbdyGurRmxX6qRxHuEths,2142
+tests/test_core.py,sha256=UmVV56VkmM71ZPySsOEKEG4_sXt9D0dvXX5cfB-EGrI,5545
+tests/test_crispr.py,sha256=tUSOgXLyvd9PkEuXZ7NeqYWMWcu0aUMcXOdP7ErVLMg,6202
+shesha_geometry-0.1.0.dist-info/LICENSE,sha256=HWzfciMdWWnz_MNV5xEni15hw7Jnks3FWBmhRbb-bFk,1072
+shesha_geometry-0.1.0.dist-info/METADATA,sha256=J_LirSGGwV0amvXS5i3F7kP9tgHzFZhanT1eHRvvrE8,13036
+shesha_geometry-0.1.0.dist-info/WHEEL,sha256=iAkIy5fosb7FzIOwONchHf19Qu7_1wCWyFNR5gu9nU0,91
+shesha_geometry-0.1.0.dist-info/top_level.txt,sha256=30aOCV4WW_bVgWOawbrRZPahW9ilJ-S9jd-oj4-Rucw,22
+shesha_geometry-0.1.0.dist-info/RECORD,,

shesha_geometry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.3.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

shesha_geometry-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+examples
+shesha
+tests

tests/__init__.py

@@ -0,0 +1 @@
+# Tests for shesha package

tests/test_bio.py

@@ -0,0 +1,49 @@
+import numpy as np
+from shesha.bio import perturbation_stability, perturbation_effect_size
+
+# Test 1: Basic functionality
+print("=== Test 1: Basic functionality ===")
+X_ctrl = np.random.randn(200, 50)
+X_pert = np.random.randn(200, 50)
+stability = perturbation_stability(X_ctrl, X_pert, seed=320)
+effect = perturbation_effect_size(X_ctrl, X_pert)
+print(f"Random data - Stability: {stability:.3f}, Effect size: {effect:.3f}")
+
+# Test 2: Coherent perturbation (should have HIGH stability)
+print("\n=== Test 2: Coherent perturbation ===")
+X_ctrl = np.random.randn(200, 50)
+shift = np.random.randn(50) * 3  # Same direction for all cells
+X_pert = X_ctrl + shift + np.random.randn(200, 50) * 0.1  # Small noise
+stability = perturbation_stability(X_ctrl, X_pert, seed=320)
+effect = perturbation_effect_size(X_ctrl, X_pert)
+print(f"Coherent shift - Stability: {stability:.3f} (should be >0.8), Effect: {effect:.3f}")
+
+# Test 3: Incoherent perturbation (should have LOW stability)
+print("\n=== Test 3: Incoherent perturbation ===")
+X_ctrl = np.random.randn(200, 50)
+X_pert = X_ctrl + np.random.randn(200, 50)  # Each cell shifts randomly
+stability = perturbation_stability(X_ctrl, X_pert, seed=320)
+effect = perturbation_effect_size(X_ctrl, X_pert)
+print(f"Random shifts - Stability: {stability:.3f} (should be <0.5), Effect: {effect:.3f}")
+
+# Test 4: Large vs small effect
+print("\n=== Test 4: Effect size comparison ===")
+X_ctrl = np.random.randn(200, 50)
+X_pert_small = X_ctrl + 0.1  # Small shift
+X_pert_large = X_ctrl + 5.0  # Large shift
+effect_small = perturbation_effect_size(X_ctrl, X_pert_small)
+effect_large = perturbation_effect_size(X_ctrl, X_pert_large)
+print(f"Small shift effect: {effect_small:.3f}")
+print(f"Large shift effect: {effect_large:.3f} (should be >> small)")
+
+# Test 5: Determinism
+print("\n=== Test 5: Determinism ===")
+X_ctrl = np.random.randn(200, 50)
+X_pert = np.random.randn(200, 50)
+r1 = perturbation_stability(X_ctrl, X_pert, seed=320)
+r2 = perturbation_stability(X_ctrl, X_pert, seed=320)
+print(f"Run 1: {r1:.6f}")
+print(f"Run 2: {r2:.6f}")
+print(f"Deterministic: {r1 == r2}")
+
+print("\n=== All tests complete ===")

tests/test_core.py

@@ -0,0 +1,164 @@
+"""Basic tests for Shesha metrics."""
+
+import numpy as np
+import pytest
+import shesha
+
+
+class TestFeatureSplit:
+    """Tests for feature_split variant."""
+    
+    def test_basic_usage(self):
+        """Test basic functionality."""
+        X = np.random.randn(100, 64)
+        result = shesha.feature_split(X, n_splits=10, seed=320)
+        assert isinstance(result, float)
+        assert -1 <= result <= 1
+    
+    def test_determinism(self):
+        """Test reproducibility with seed."""
+        X = np.random.randn(100, 64)
+        r1 = shesha.feature_split(X, seed=320)
+        r2 = shesha.feature_split(X, seed=320)
+        assert r1 == r2
+    
+    def test_structured_data_high_stability(self):
+        """Structured data should have high stability."""
+        # Create data with redundant structure
+        latent = np.random.randn(100, 10)
+        projection = np.random.randn(10, 128)
+        X = latent @ projection
+        
+        result = shesha.feature_split(X, n_splits=30, seed=320)
+        assert result > 0.5, "Structured data should have high stability"
+    
+    def test_random_data_low_stability(self):
+        """Random iid features should have lower stability."""
+        X = np.random.randn(100, 128)
+        result = shesha.feature_split(X, n_splits=30, seed=320)
+        # Random data can still have moderate stability, just check it runs
+        assert -1 <= result <= 1
+    
+    def test_too_few_features(self):
+        """Should return NaN with too few features."""
+        X = np.random.randn(100, 3)
+        result = shesha.feature_split(X)
+        assert np.isnan(result)
+    
+    def test_too_few_samples(self):
+        """Should return NaN with too few samples."""
+        X = np.random.randn(3, 64)
+        result = shesha.feature_split(X)
+        assert np.isnan(result)
+
+
+class TestSampleSplit:
+    """Tests for sample_split variant."""
+    
+    def test_basic_usage(self):
+        X = np.random.randn(200, 64)
+        result = shesha.sample_split(X, n_splits=10, seed=320)
+        assert isinstance(result, float)
+        assert -1 <= result <= 1
+    
+    def test_determinism(self):
+        X = np.random.randn(200, 64)
+        r1 = shesha.sample_split(X, seed=320)
+        r2 = shesha.sample_split(X, seed=320)
+        assert r1 == r2
+
+
+class TestAnchorStability:
+    """Tests for anchor_stability variant."""
+    
+    def test_basic_usage(self):
+        X = np.random.randn(500, 64)
+        result = shesha.anchor_stability(X, n_splits=10, seed=320)
+        assert isinstance(result, float)
+        assert -1 <= result <= 1
+    
+    def test_small_data_handling(self):
+        """Should handle small datasets gracefully."""
+        X = np.random.randn(50, 64)
+        result = shesha.anchor_stability(X, seed=320)
+        # Should either return valid result or NaN, not crash
+        assert np.isnan(result) or (-1 <= result <= 1)
+
+
+class TestVarianceRatio:
+    """Tests for variance_ratio variant."""
+    
+    def test_basic_usage(self):
+        X = np.random.randn(100, 64)
+        y = np.random.randint(0, 5, 100)
+        result = shesha.variance_ratio(X, y)
+        assert isinstance(result, float)
+        assert 0 <= result <= 1
+    
+    def test_perfect_separation(self):
+        """Perfectly separated classes should have high ratio."""
+        # Create well-separated clusters
+        X = np.vstack([
+            np.random.randn(50, 64) + np.array([10] * 64),
+            np.random.randn(50, 64) + np.array([-10] * 64),
+        ])
+        y = np.array([0] * 50 + [1] * 50)
+        
+        result = shesha.variance_ratio(X, y)
+        assert result > 0.8, "Well-separated classes should have high variance ratio"
+    
+    def test_single_class(self):
+        """Single class should return NaN."""
+        X = np.random.randn(100, 64)
+        y = np.zeros(100)
+        result = shesha.variance_ratio(X, y)
+        assert np.isnan(result)
+
+
+class TestSupervisedAlignment:
+    """Tests for supervised_alignment variant."""
+    
+    def test_basic_usage(self):
+        X = np.random.randn(100, 64)
+        y = np.random.randint(0, 5, 100)
+        result = shesha.supervised_alignment(X, y, seed=320)
+        assert isinstance(result, float)
+        assert -1 <= result <= 1
+    
+    def test_determinism(self):
+        X = np.random.randn(100, 64)
+        y = np.random.randint(0, 5, 100)
+        r1 = shesha.supervised_alignment(X, y, seed=320)
+        r2 = shesha.supervised_alignment(X, y, seed=320)
+        assert r1 == r2
+
+
+class TestUnifiedInterface:
+    """Tests for the unified shesha() function."""
+    
+    def test_feature_split_variant(self):
+        X = np.random.randn(100, 64)
+        result = shesha.shesha(X, variant='feature_split', seed=320)
+        expected = shesha.feature_split(X, seed=320)
+        assert result == expected
+    
+    def test_supervised_variant(self):
+        X = np.random.randn(100, 64)
+        y = np.random.randint(0, 5, 100)
+        result = shesha.shesha(X, y, variant='supervised', seed=320)
+        expected = shesha.supervised_alignment(X, y, seed=320)
+        assert result == expected
+    
+    def test_missing_labels_error(self):
+        X = np.random.randn(100, 64)
+        with pytest.raises(ValueError, match="Labels required"):
+            shesha.shesha(X, variant='supervised')
+    
+    def test_unknown_variant_error(self):
+        X = np.random.randn(100, 64)
+        with pytest.raises(ValueError, match="Unknown variant"):
+            shesha.shesha(X, variant='nonexistent')
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])