# Verskyt
*A versatile toolkyt for Tversky Neural Networks*
[](https://github.com/jeffreyksmithjr/verskyt/actions/workflows/ci.yml) [](https://codecov.io/gh/jeffreyksmithjr/verskyt) [](https://badge.fury.io/py/verskyt) [](https://doi.org/10.5281/zenodo.17014431)
**Verskyt** (pronounced "ver-SKIT") is a Python library for Tversky Neural Networks (TNNs) built on three design principles: **Modularity**, **Introspection**, and **Extensibility**. Verskyt provides PyTorch-compatible TNN implementations alongside tools for model introspection, prototype analysis, and causal interventions.
## What are Tversky Neural Networks?
Tversky Neural Networks represent a novel paradigm in deep learning, introduced by Doumbouya et al. (2025). TNNs replace traditional linear transformations with **similarity-based computations** grounded in cognitive science, specifically Tversky's feature-based similarity theory. TNNs operate by projecting inputs into a learned feature space (Ω), where similarity to explicit prototypes (Π) is computed.
**Key TNN Properties:**
- **Psychologically Plausible**: Based on established cognitive models of human similarity perception
- **Asymmetric Similarity**: Can learn that "A is more similar to B than B is to A" (unlike standard neural networks)
- **Interpretable Representations**: Uses explicit prototypes and feature sets that can be directly examined
- **Non-linear Single Layer**: Can solve non-linearly separable problems (like XOR) with just one layer
## What Verskyt Provides
**Design Principles:**
**🔧 Modularity**: Clean, composable components that integrate with existing PyTorch workflows
**🔍 Introspection**: Tools for examining model internals, learned prototypes, and decision processes
**🚀 Extensibility**: Built for researchers to modify and develop novel TNN-based architectures
### 🧠 TNN Implementation
**PyTorch Integration:**
- **Drop-in Compatibility**: Replace `torch.nn.Linear` layers with `verskyt.TverskyProjectionLayer` in existing models
- **Full Parameter Control**: All TNN components (prototypes (Π), features (Ω), and asymmetry parameters (α, β)) are learnable and accessible
- **Full Specification**: All 6 intersection reduction methods and 2 difference methods from the original paper
- **Tested Implementation**: Passes mathematical correctness tests, including the XOR non-linearity benchmark
### 🔬 Research Tools
Verskyt includes research tools for TNN exploration and development:
**Model Introspection:**
- **Prototype Analysis**: Examine learned prototype vectors and their semantic meanings
- **Feature Bank Inspection**: Understand which features the model has discovered
- **Similarity Landscape Mapping**: Visualize how the model perceives relationships between concepts
**Visualization Suite:**
- **Prototype Space Visualization**: PCA and t-SNE plots of learned prototype distributions
- **Data Clustering Analysis**: See how input data clusters around different prototypes
- **Feature-Prototype Relationships**: Advanced analysis of internal similarity computations
- **Interactive Research Tools**: High-quality plots for papers and presentations
**Causal Intervention Framework:**
- **Prototype Surgery**: Directly edit model concepts and observe behavioral changes
- **Counterfactual Analysis**: Simulate "what if" scenarios by modifying internal representations
- **Concept Grafting**: Transfer learned concepts between different models
**Experimental Infrastructure:**
- **Benchmark Suites**: Testing against paper specifications
- **Reproducible Research**: Tools for systematic hyperparameter exploration and results validation
## Quick Start
Install from PyPI:
`pip install verskyt`
### Basic Usage: Drop-in Replacement
`verskyt` layers are designed as drop-in replacements for standard PyTorch layers.
```python
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, # Dimensionality of the input vector
num_prototypes=10, # Corresponds to output classes
num_features=256, # Dimensionality of the internal learned 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
Inspect and modify model internals using the intervention toolkit:
```python
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()
```
## Library Implementation Status
Verskyt provides a complete, production-ready implementation of TNNs with research capabilities:
| Implementation Area | Component | Status |
| :--- | :--- | :--- |
| **TNN Core** | `TverskyProjectionLayer` | ✅ **Complete** - Drop-in PyTorch compatibility |
| | `TverskySimilarityLayer` | ✅ **Complete** - All similarity computations |
| | Intersection Methods | ✅ **Complete** - All 6 from paper: `product`, `min`, `max`, `mean`, `gmean`, `softmin` |
| | Difference Methods | ✅ **Complete** - Both `substractmatch` & `ignorematch` |
| **Paper Validation** | XOR Benchmark | ✅ **Complete** - Non-linearity verified |
| | Mathematical Correctness | ✅ **Complete** - All specifications validated |
| **Research Tools** | `InterventionManager` | ✅ **Complete** - Prototype surgery & analysis |
| | `FeatureGrounder` | ✅ **Complete** - Concept mapping framework |
| | Prototype Analysis | ✅ **Complete** - Introspection APIs |
| | Visualization Suite | ✅ **Complete** - PCA/t-SNE prototype analysis |
| **Development** | Comprehensive Testing | ✅ **Complete** - 60+ tests, 75% coverage |
| | CI/CD Pipeline | ✅ **Complete** - Automated quality & releases |
| | Documentation Site | ✅ **Complete** - Automated docs building and publishing |
## 🚀 Future Work
Verskyt continues expanding its research toolkit capabilities:
* [x] **Interactive Visualization Suite**: ✅ **Complete** - Tools for prototype visualization, similarity landscapes, and intervention impact analysis
* [ ] **Extended Benchmark Suite**: Evaluation across more datasets and TNN configurations
* [ ] **Performance Profiling**: Optimization for large-scale models and training efficiency
* [ ] **TverskyResNet Implementation**: Pre-built architecture demonstrating TNN integration in complex models
* [ ] **Concept Transfer Tools**: Framework for moving learned concepts between different TNN models
* [ ] **Uncertainty Quantification**: Tools for measuring confidence in TNN predictions and prototype assignments
* [ ] **Multi-Modal Extensions**: Extend TNN concepts to handle different data modalities simultaneously
## Examples & Visualizations
Verskyt includes comprehensive examples demonstrating all capabilities:
### 🎨 Visualization Demo
**[`examples/visualization_demo.py`](examples/visualization_demo.py)** - Complete visualization showcase:
- Prototype space analysis with PCA and t-SNE
- Data clustering by prototype similarity
- Advanced prototype-feature relationship analysis
- XOR problem demonstration
*Learned prototype space visualized with PCA and t-SNE*
### 🔬 Research Examples
- **[Research Tutorial](examples/research_tutorial.py)** - Advanced TNN research workflows
- **[Intervention Demo](examples/intervention_demo.py)** - Prototype surgery and causal analysis
**Installation for visualizations:**
```bash
pip install verskyt[visualization]
```
## Documentation
For complete usage guides, tutorials, and the API reference, please see the **[Full Documentation Website](https://verskyt.readthedocs.io)**.
- **[Examples Directory](examples/README.md)** - All example scripts with comprehensive documentation
- **[Visualization Guide](docs/tutorials/visualization-guide.md)** - Step-by-step tutorial for using the visualization suite
- **[API Reference](https://verskyt.readthedocs.io/en/latest/api/)** - Complete function documentation
## Contributing
Contributions are welcome! Please see our development and contribution guidelines.
## Citation
If you use Verskyt in your research, please cite both the original Tversky Neural Network paper and this library.
### 1. Foundational Paper:
```bibtex
@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}
}
```
### 2. This Library (Verskyt):
We recommend citing the specific version of the software you used. You can get a persistent DOI for each version from [Zenodo](https://zenodo.org).
```bibtex
@software{smith_2025_verskyt,
author = {Smith, Jeff},
title = {{Verskyt: A versatile toolkyt for Tversky Neural Networks}},
month = aug,
year = 2025,
publisher = {Zenodo},
version = {v0.2.4},
doi = {10.5281/zenodo.17014431},
url = {https://doi.org/10.5281/zenodo.17014431}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "verskyt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "deep-learning, neural-networks, tversky, similarity, pytorch, research, interpretability",
"author": "Jeff Smith",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/db/7e/e79871f2f5a794f661429775402e3c4fc3ec6368741ff5074c8e7cad86d9/verskyt-0.2.4.tar.gz",
"platform": null,
"description": "# Verskyt\n*A versatile toolkyt for Tversky Neural Networks*\n\n\n[](https://github.com/jeffreyksmithjr/verskyt/actions/workflows/ci.yml) [](https://codecov.io/gh/jeffreyksmithjr/verskyt) [](https://badge.fury.io/py/verskyt) [](https://doi.org/10.5281/zenodo.17014431)\n\n**Verskyt** (pronounced \"ver-SKIT\") is a Python library for Tversky Neural Networks (TNNs) built on three design principles: **Modularity**, **Introspection**, and **Extensibility**. Verskyt provides PyTorch-compatible TNN implementations alongside tools for model introspection, prototype analysis, and causal interventions.\n\n## What are Tversky Neural Networks?\n\nTversky Neural Networks represent a novel paradigm in deep learning, introduced by Doumbouya et al. (2025). TNNs replace traditional linear transformations with **similarity-based computations** grounded in cognitive science, specifically Tversky's feature-based similarity theory. TNNs operate by projecting inputs into a learned feature space (\u03a9), where similarity to explicit prototypes (\u03a0) is computed.\n\n**Key TNN Properties:**\n- **Psychologically Plausible**: Based on established cognitive models of human similarity perception\n- **Asymmetric Similarity**: Can learn that \"A is more similar to B than B is to A\" (unlike standard neural networks)\n- **Interpretable Representations**: Uses explicit prototypes and feature sets that can be directly examined\n- **Non-linear Single Layer**: Can solve non-linearly separable problems (like XOR) with just one layer\n\n## What Verskyt Provides\n\n**Design Principles:**\n\n**\ud83d\udd27 Modularity**: Clean, composable components that integrate with existing PyTorch workflows\n**\ud83d\udd0d Introspection**: Tools for examining model internals, learned prototypes, and decision processes\n**\ud83d\ude80 Extensibility**: Built for researchers to modify and develop novel TNN-based architectures\n\n### \ud83e\udde0 TNN Implementation\n\n**PyTorch Integration:**\n- **Drop-in Compatibility**: Replace `torch.nn.Linear` layers with `verskyt.TverskyProjectionLayer` in existing models\n- **Full Parameter Control**: All TNN components (prototypes (\u03a0), features (\u03a9), and asymmetry parameters (\u03b1, \u03b2)) are learnable and accessible\n- **Full Specification**: All 6 intersection reduction methods and 2 difference methods from the original paper\n- **Tested Implementation**: Passes mathematical correctness tests, including the XOR non-linearity benchmark\n\n### \ud83d\udd2c Research Tools\n\nVerskyt includes research tools for TNN exploration and development:\n\n**Model Introspection:**\n- **Prototype Analysis**: Examine learned prototype vectors and their semantic meanings\n- **Feature Bank Inspection**: Understand which features the model has discovered\n- **Similarity Landscape Mapping**: Visualize how the model perceives relationships between concepts\n\n**Visualization Suite:**\n- **Prototype Space Visualization**: PCA and t-SNE plots of learned prototype distributions\n- **Data Clustering Analysis**: See how input data clusters around different prototypes\n- **Feature-Prototype Relationships**: Advanced analysis of internal similarity computations\n- **Interactive Research Tools**: High-quality plots for papers and presentations\n\n**Causal Intervention Framework:**\n- **Prototype Surgery**: Directly edit model concepts and observe behavioral changes\n- **Counterfactual Analysis**: Simulate \"what if\" scenarios by modifying internal representations\n- **Concept Grafting**: Transfer learned concepts between different models\n\n**Experimental Infrastructure:**\n- **Benchmark Suites**: Testing against paper specifications\n- **Reproducible Research**: Tools for systematic hyperparameter exploration and results validation\n\n## Quick Start\n\nInstall from PyPI:\n`pip install verskyt`\n\n### Basic Usage: Drop-in Replacement\n\n`verskyt` layers are designed as drop-in replacements for standard PyTorch layers.\n\n```python\nimport torch\nfrom verskyt.layers import TverskyProjectionLayer\n\n# A TNN layer that can replace nn.Linear(in_features=128, out_features=10)\nlayer = TverskyProjectionLayer(\n in_features=128, # Dimensionality of the input vector\n num_prototypes=10, # Corresponds to output classes\n num_features=256, # Dimensionality of the internal learned feature space (\u03a9)\n)\n\n# It works just like a standard PyTorch layer\nx = torch.randn(32, 128)\noutput = layer(x) # shape: [32, 10]\n```\n\n### Advanced Usage: Introspection & Intervention\n\nInspect and modify model internals using the intervention toolkit:\n\n```python\nfrom verskyt.interventions import InterventionManager\n\n# Assume 'model' is a trained model with TverskyProjectionLayer\nmanager = InterventionManager(model)\n\n# 1. Inspect the model's learned concepts\nprototypes = manager.list_prototypes()\nprint(f\"Inspecting {len(prototypes)} learned prototypes.\")\n\n# 2. Examine individual prototypes and features\nproto_info = manager.get_prototype(\"layer_name\", 0)\nprint(f\"Prototype 0: shape={proto_info.shape}, norm={proto_info.norm:.3f}\")\n\n# 3. Permanently edit a prototype (\"prototype surgery\")\noriginal_proto = manager.get_prototype(\"layer_name\", 0)\nmodified_vector = original_proto.vector * 0.5 # Dampen the prototype\nmanager.modify_prototype(\"layer_name\", 0, modified_vector)\n\n# 4. Reset to original state when done\nmanager.reset_to_original()\n```\n\n## Library Implementation Status\n\nVerskyt provides a complete, production-ready implementation of TNNs with research capabilities:\n\n| Implementation Area | Component | Status |\n| :--- | :--- | :--- |\n| **TNN Core** | `TverskyProjectionLayer` | \u2705 **Complete** - Drop-in PyTorch compatibility |\n| | `TverskySimilarityLayer` | \u2705 **Complete** - All similarity computations |\n| | Intersection Methods | \u2705 **Complete** - All 6 from paper: `product`, `min`, `max`, `mean`, `gmean`, `softmin` |\n| | Difference Methods | \u2705 **Complete** - Both `substractmatch` & `ignorematch` |\n| **Paper Validation** | XOR Benchmark | \u2705 **Complete** - Non-linearity verified |\n| | Mathematical Correctness | \u2705 **Complete** - All specifications validated |\n| **Research Tools** | `InterventionManager` | \u2705 **Complete** - Prototype surgery & analysis |\n| | `FeatureGrounder` | \u2705 **Complete** - Concept mapping framework |\n| | Prototype Analysis | \u2705 **Complete** - Introspection APIs |\n| | Visualization Suite | \u2705 **Complete** - PCA/t-SNE prototype analysis |\n| **Development** | Comprehensive Testing | \u2705 **Complete** - 60+ tests, 75% coverage |\n| | CI/CD Pipeline | \u2705 **Complete** - Automated quality & releases |\n| | Documentation Site | \u2705 **Complete** - Automated docs building and publishing |\n\n## \ud83d\ude80 Future Work\n\nVerskyt continues expanding its research toolkit capabilities:\n\n * [x] **Interactive Visualization Suite**: \u2705 **Complete** - Tools for prototype visualization, similarity landscapes, and intervention impact analysis\n * [ ] **Extended Benchmark Suite**: Evaluation across more datasets and TNN configurations\n * [ ] **Performance Profiling**: Optimization for large-scale models and training efficiency\n * [ ] **TverskyResNet Implementation**: Pre-built architecture demonstrating TNN integration in complex models\n * [ ] **Concept Transfer Tools**: Framework for moving learned concepts between different TNN models\n * [ ] **Uncertainty Quantification**: Tools for measuring confidence in TNN predictions and prototype assignments\n * [ ] **Multi-Modal Extensions**: Extend TNN concepts to handle different data modalities simultaneously\n\n## Examples & Visualizations\n\nVerskyt includes comprehensive examples demonstrating all capabilities:\n\n### \ud83c\udfa8 Visualization Demo\n**[`examples/visualization_demo.py`](examples/visualization_demo.py)** - Complete visualization showcase:\n- Prototype space analysis with PCA and t-SNE\n- Data clustering by prototype similarity\n- Advanced prototype-feature relationship analysis\n- XOR problem demonstration\n\n\n*Learned prototype space visualized with PCA and t-SNE*\n\n### \ud83d\udd2c Research Examples\n- **[Research Tutorial](examples/research_tutorial.py)** - Advanced TNN research workflows\n- **[Intervention Demo](examples/intervention_demo.py)** - Prototype surgery and causal analysis\n\n**Installation for visualizations:**\n```bash\npip install verskyt[visualization]\n```\n\n## Documentation\n\nFor complete usage guides, tutorials, and the API reference, please see the **[Full Documentation Website](https://verskyt.readthedocs.io)**.\n\n- **[Examples Directory](examples/README.md)** - All example scripts with comprehensive documentation\n- **[Visualization Guide](docs/tutorials/visualization-guide.md)** - Step-by-step tutorial for using the visualization suite\n- **[API Reference](https://verskyt.readthedocs.io/en/latest/api/)** - Complete function documentation\n\n## Contributing\n\nContributions are welcome! Please see our development and contribution guidelines.\n\n## Citation\n\nIf you use Verskyt in your research, please cite both the original Tversky Neural Network paper and this library.\n\n### 1. Foundational Paper:\n\n```bibtex\n@article{doumbouya2025tversky,\n title={Tversky Neural Networks: Psychologically Plausible Deep Learning with Differentiable Tversky Similarity},\n author={Doumbouya, Moussa Koulako Bala and Jurafsky, Dan and Manning, Christopher D.},\n journal={arXiv preprint arXiv:2506.11035},\n year={2025}\n}\n```\n\n### 2. This Library (Verskyt):\n\nWe recommend citing the specific version of the software you used. You can get a persistent DOI for each version from [Zenodo](https://zenodo.org).\n\n```bibtex\n@software{smith_2025_verskyt,\n author = {Smith, Jeff},\n title = {{Verskyt: A versatile toolkyt for Tversky Neural Networks}},\n month = aug,\n year = 2025,\n publisher = {Zenodo},\n version = {v0.2.4},\n doi = {10.5281/zenodo.17014431},\n url = {https://doi.org/10.5281/zenodo.17014431}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for Tversky Neural Networks with research tools for model introspection and prototype analysis",
"version": "0.2.4",
"project_urls": {
"Bug Tracker": "https://github.com/jeffreyksmithjr/verskyt/issues",
"Documentation": "https://verskyt.readthedocs.io",
"Homepage": "https://github.com/jeffreyksmithjr/verskyt",
"Source": "https://github.com/jeffreyksmithjr/verskyt"
},
"split_keywords": [
"deep-learning",
" neural-networks",
" tversky",
" similarity",
" pytorch",
" research",
" interpretability"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d7f88fcb972be5ecbb933939564d043d557cc92b1b19d3fe017f1b8e6fc0a92",
"md5": "7d07c7536938445c1f9a45dc1820cc02",
"sha256": "a4f595bee1c6102dd5a49dea782242f5403f4f862e1abfe7e67919be5ce18133"
},
"downloads": -1,
"filename": "verskyt-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d07c7536938445c1f9a45dc1820cc02",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 40830,
"upload_time": "2025-09-02T03:43:02",
"upload_time_iso_8601": "2025-09-02T03:43:02.408078Z",
"url": "https://files.pythonhosted.org/packages/7d/7f/88fcb972be5ecbb933939564d043d557cc92b1b19d3fe017f1b8e6fc0a92/verskyt-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "db7ee79871f2f5a794f661429775402e3c4fc3ec6368741ff5074c8e7cad86d9",
"md5": "fec4fc44a1a34000dcd5b92bf9b9cdb9",
"sha256": "1a7044569239a7649da151937fb994069674d99c69f23c993333a2baa96b3ef7"
},
"downloads": -1,
"filename": "verskyt-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "fec4fc44a1a34000dcd5b92bf9b9cdb9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39718,
"upload_time": "2025-09-02T03:43:03",
"upload_time_iso_8601": "2025-09-02T03:43:03.207407Z",
"url": "https://files.pythonhosted.org/packages/db/7e/e79871f2f5a794f661429775402e3c4fc3ec6368741ff5074c8e7cad86d9/verskyt-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 03:43:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeffreyksmithjr",
"github_project": "verskyt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "verskyt"
}
JSON
