Metadata-Version: 2.1
Name: verskyt
Version: 0.1.2
Summary: A library for Tversky Neural Networks - psychologically plausible deep learning
Author: Verskyt Contributors
License: MIT
Project-URL: Homepage, https://github.com/jeffreyksmithjr/verskyt
Project-URL: Bug Tracker, https://github.com/jeffreyksmithjr/verskyt/issues
Project-URL: Documentation, https://verskyt.readthedocs.io
Project-URL: Source, https://github.com/jeffreyksmithjr/verskyt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.10.0
Requires-Dist: numpy>=1.19.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: tqdm>=4.62.0
Provides-Extra: benchmarks
Requires-Dist: torchvision>=0.11.0; extra == "benchmarks"
Requires-Dist: scikit-learn>=1.0.0; extra == "benchmarks"
Requires-Dist: pandas>=1.3.0; extra == "benchmarks"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Requires-Dist: torchvision>=0.11.0; extra == "dev"
Requires-Dist: sphinx>=5.0.0; extra == "dev"
Requires-Dist: furo>=2022.6.21; extra == "dev"
Requires-Dist: myst-parser>=0.18.0; extra == "dev"
Requires-Dist: myst-nb>=0.17.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "dev"
Provides-Extra: visualization
Requires-Dist: seaborn>=0.11.0; extra == "visualization"
Requires-Dist: plotly>=5.0.0; extra == "visualization"

# Verskyt
*A versatile toolkyt for Tversky Neural Networks*

*Pronounced "ver-SKIT"*

[![CI](https://github.com/jeffreyksmithjr/verskyt/workflows/CI/badge.svg)](https://github.com/jeffreyksmithjr/verskyt/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/jeffreyksmithjr/verskyt/branch/main/graph/badge.svg)](https://codecov.io/gh/jeffreyksmithjr/verskyt) [![PyPI version](https://badge.fury.io/py/verskyt.svg)](https://badge.fury.io/py/verskyt)

**Verskyt** is a Python library that implements Tversky Neural Networks (TNNs) with advanced research and analysis capabilities. Beyond providing faithful PyTorch-compatible TNN layers, Verskyt offers a complete toolkit for model introspection, causal intervention, and prototype analysis, making it a foundational platform for researchers exploring interpretable deep learning.

## 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

While TNNs define the mathematical framework, **Verskyt delivers the implementation plus advanced research capabilities** that go far beyond basic TNN functionality:

### 🧠 Complete TNN Implementation

**Production-Ready 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
- **Complete Specification**: All 6 intersection reduction methods and 2 difference methods from the original paper
- **Validated Implementation**: Passes all mathematical correctness tests, including the XOR non-linearity benchmark

### 🔬 Advanced Research Toolkit

**Verskyt's unique contribution** is a suite of analysis tools not available elsewhere:

**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

**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

Go beyond prediction and start interrogating your model's logic with the built-in 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 |
| **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:

  * [ ] **Interactive Visualization Suite**: 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

## Documentation

For complete usage guides, tutorials, and the API reference, please see the **[Full Documentation Website](https://verskyt.readthedocs.io)**.

## 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_jr_2025_verskyt,
  author       = {Smith Jr., Jeffrey K.},
  title        = {{Verskyt: A versatile toolkyt for Tversky Neural Networks}},
  month        = jan,
  year         = 2025,
  publisher    = {Zenodo},
  version      = {v0.1.2},
  doi          = {10.5281/zenodo.PENDING},
  url          = {https://doi.org/10.5281/zenodo.PENDING}
}
```

*Note: DOI will be updated upon the next release. For now, you can cite the current version using the GitHub repository URL.*
