verskyt 0.1.0

A library for Tversky Neural Networks - psychologically plausible deep learning

Verskyt

verskyt is an independent, research-focused Python library for Tversky Neural Networks (TNNs). It provides a modular, introspective, and extensible implementation of the psychologically plausible deep learning models described in "Tversky Neural Networks" (Doumbouya et al., 2025).

This library is designed to be a foundational tool for researchers exploring novel neuro-symbolic architectures, interpretable representations, and causal analysis.

Why Verskyt?

Tversky Neural Networks offer a new paradigm for building interpretable models by replacing standard linear projections with a similarity-based mechanism grounded in cognitive science. verskyt provides the tools to both leverage and extend these capabilities.

🧠 A Faithful & Extensible TNN Implementation

• Drop-in Compatibility: Replace torch.nn.Linear layers with verskyt.TverskyProjectionLayer to introduce TNN capabilities into existing PyTorch models.
• Full Parameter Control: All aspects of the Tversky contrast model—prototypes (Π), features (Ω), and asymmetry parameters (α, β)—are learnable and accessible.
• Modular Similarity Functions: Easily experiment with different mathematical formulations for feature intersection and difference to explore their impact on model behavior.

🔬 Built for Advanced Research & Introspection

Beyond a simple implementation, verskyt includes a powerful toolkit for interrogating and manipulating trained models.

• Deep Introspection: Programmatically access and analyze the learned prototypes and feature banks to understand what a model has learned.
• Causal Intervention: Use the InterventionManager to perform "prototype surgery"—directly editing a model's internal concepts and simulating counterfactuals to causally probe its logic.

Quick Start

Install from PyPI: pip install verskyt

Basic Usage: Drop-in Replacement

verskyt layers are designed to be a seamless replacement for standard PyTorch layers.

import torch
from verskyt.layers import TverskyProjectionLayer

# A TNN layer that can replace nn.Linear(in_features=128, out_features=10)
layer = TverskyProjectionLayer(
    in_features=128,
    num_prototypes=10,    # Corresponds to output classes
    num_features=256,     # Size of the internal feature space
)

# It works just like a standard PyTorch layer
x = torch.randn(32, 128)
output = layer(x)  # shape: [32, 10]

Advanced Usage: Introspection & Intervention

Go beyond prediction and start interrogating your model's logic with the built-in intervention toolkit.

from verskyt.interventions import InterventionManager

# Assume 'model' is a trained model with TverskyProjectionLayer
manager = InterventionManager(model)

# 1. Inspect the model's learned concepts
prototypes = manager.list_prototypes()
print(f"Inspecting {len(prototypes)} learned prototypes.")

# 2. Examine individual prototypes and features
proto_info = manager.get_prototype("layer_name", 0)
print(f"Prototype 0: shape={proto_info.shape}, norm={proto_info.norm:.3f}")

# 3. Permanently edit a prototype ("prototype surgery")
original_proto = manager.get_prototype("layer_name", 0)
modified_vector = original_proto.vector * 0.5  # Dampen the prototype
manager.modify_prototype("layer_name", 0, modified_vector)

# 4. Reset to original state when done
manager.reset_to_original()

Features & Status

This library provides a comprehensive implementation of Tversky Neural Networks, validated against the original paper's specifications.

Feature Area	Component	Status
Core TNN Layers	TverskyProjectionLayer	✅ Complete
	TverskySimilarityLayer	✅ Complete
Similarity Functions	Intersection Reductions	✅ Complete (All 6 implemented: product, min, max, mean, gmean, softmin)
	Difference Reductions	✅ Complete (Both substractmatch & ignorematch)
Validation	XOR Non-Linear Benchmark	✅ Complete (Convergence verified)
Research Toolkit	InterventionManager API	✅ Complete (Inspect, Edit, Simulate)
	FeatureGrounder Framework	✅ Complete
	Visualization Suite	⏳ On Roadmap
Model Zoo	ResNet Integration	⏳ On Roadmap

🚀 Roadmap

verskyt is under active development. Key priorities for upcoming releases include:

• Complete Specification Compliance: All intersection reduction methods (max, gmean, softmin) now implemented for full compliance with the original paper.
• Visualization Suite: Add powerful tools for visualizing prototypes in the data domain, plotting decision boundaries, and analyzing the impact of interventions.
• Expanded Model Zoo: Provide pre-built TverskyResNet and other architectures to benchmark performance on standard vision datasets like MNIST and CIFAR-10.
• Performance Optimizations: Profile and optimize the core similarity computations for large-scale training.

Documentation

For complete usage guides, tutorials, and the API reference, please see the Full Documentation Website.

Contributing

Contributions are welcome! Please see our development and contribution guidelines.

Citation

To cite the foundational TNN paper:

@article{doumbouya2025tversky,
  title={Tversky Neural Networks: Psychologically Plausible Deep Learning with Differentiable Tversky Similarity},
  author={Doumbouya, Moussa Koulako Bala and Jurafsky, Dan and Manning, Christopher D.},
  journal={arXiv preprint arXiv:2506.11035},
  year={2025}
}

To cite this library: (BibTeX citation for verskyt to be added upon first archival release)