vespaembed 0.0.1__tar.gz → 0.0.2__tar.gz

vespaembed-0.0.2/PKG-INFO

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: vespaembed
+Version: 0.0.2
+Summary: vespaembed: no-code training for embedding models
+Author: Abhishek Thakur
+License: Apache 2.0
+Project-URL: Homepage, https://github.com/vespaai-playground/vespaembed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: transformers>=4.40.0
+Requires-Dist: accelerate>=0.26.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: datasets>=2.18.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: websockets>=12.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: tensorboard>=2.15.0
+Requires-Dist: peft>=0.18.1
+Requires-Dist: unsloth>=2026.1.4
+Provides-Extra: unsloth
+Requires-Dist: unsloth; extra == "unsloth"
+Provides-Extra: onnx
+Requires-Dist: onnx>=1.14.0; extra == "onnx"
+Requires-Dist: onnxruntime>=1.23.2; extra == "onnx"
+Provides-Extra: dev
+Requires-Dist: black==26.1.0; extra == "dev"
+Requires-Dist: isort==7.0.0; extra == "dev"
+Requires-Dist: flake8==7.3.0; extra == "dev"
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# VespaEmbed
+
+No-code training for embedding models. Train custom embedding models with a web UI or CLI.
+
+## Features
+
+- **Web UI** - Visual interface for configuring and monitoring training
+- **CLI** - Command-line interface for scripting and automation
+- **Multiple Tasks** - Support for pairs, triplets, similarity scoring, and unsupervised learning
+- **Loss Variants** - Choose from multiple loss functions per task
+- **Matryoshka Embeddings** - Train multi-dimensional embeddings for flexible retrieval
+- **LoRA Support** - Parameter-efficient fine-tuning with LoRA adapters
+- **Unsloth Integration** - Faster training with Unsloth optimizations
+- **HuggingFace Integration** - Load datasets, models from HuggingFace Hub, push models to Hub
+
+## Installation
+
+> **Note:** VespaEmbed is in experimental phase. Install from source.
+
+```bash
+git clone https://github.com/vespaai-playground/vespaembed.git
+cd vespaembed
+uv sync
+```
+
+### Optional Dependencies
+
+```bash
+# For Unsloth acceleration (requires NVIDIA/AMD GPU)
+uv sync --extra unsloth
+
+# For ONNX export
+uv sync --extra onnx
+
+# For development
+uv sync --extra dev
+```
+
+## Quick Start
+
+### Web UI
+
+Launch the web interface:
+
+```bash
+vespaembed
+```
+
+Open http://localhost:8000 in your browser. The UI lets you:
+- Upload training data (CSV or JSONL)
+- Select task type and base model
+- Configure hyperparameters
+- Monitor training progress
+- Download trained models
+
+### CLI
+
+Train a model from the command line:
+
+```bash
+vespaembed train \
+  --data examples/data/pairs.csv \
+  --task pairs \
+  --base-model sentence-transformers/all-MiniLM-L6-v2 \
+  --epochs 3
+```
+
+Or use a YAML config file:
+
+```bash
+vespaembed train --config config.yaml
+```
+
+## Tasks
+
+VespaEmbed supports 4 training tasks based on your data format:
+
+### Pairs
+
+Text pairs for semantic search. Use when you have query-document pairs without explicit negatives.
+
+**Data format:**
+```csv
+anchor,positive
+What is machine learning?,Machine learning is a subset of AI...
+How does photosynthesis work?,Photosynthesis converts sunlight...
+```
+
+**Loss variants:** `mnr` (default), `mnr_symmetric`, `gist`, `cached_mnr`, `cached_gist`
+
+### Triplets
+
+Text triplets with hard negatives. Use when you have explicit negative examples.
+
+**Data format:**
+```csv
+anchor,positive,negative
+What is Python?,Python is a programming language...,A python is a large snake...
+```
+
+**Loss variants:** `mnr` (default), `mnr_symmetric`, `gist`, `cached_mnr`, `cached_gist`
+
+### Similarity
+
+Text pairs with similarity scores (STS-style). Use when you have continuous similarity labels.
+
+**Data format:**
+```csv
+sentence1,sentence2,score
+A man is playing guitar,A person plays music,0.85
+The cat is sleeping,A dog is running,0.12
+```
+
+**Loss variants:** `cosine` (default), `cosent`, `angle`
+
+### TSDAE
+
+Unsupervised learning with denoising auto-encoder. Use when you only have unlabeled text for domain adaptation.
+
+**Data format:**
+```csv
+text
+Machine learning is transforming how we analyze data.
+Natural language processing enables computers to understand human language.
+```
+
+## Configuration
+
+### CLI Arguments
+
+```bash
+vespaembed train \
+  --data <path>              # Training data (CSV, JSONL, or HF dataset)
+  --task <task>              # Task type: pairs, triplets, similarity, tsdae
+  --base-model <model>       # Base model name or path
+  --project <name>           # Project name (optional)
+  --eval-data <path>         # Evaluation data (optional)
+  --epochs <n>               # Number of epochs (default: 3)
+  --batch-size <n>           # Batch size (default: 32)
+  --learning-rate <lr>       # Learning rate (default: 2e-5)
+  --optimizer <opt>          # Optimizer (default: adamw_torch)
+  --scheduler <sched>        # LR scheduler (default: linear)
+  --matryoshka               # Enable Matryoshka embeddings
+  --matryoshka-dims <dims>   # Dimensions (default: 768,512,256,128,64)
+  --unsloth                  # Use Unsloth for faster training
+  --subset <name>            # HuggingFace dataset subset
+  --split <name>             # HuggingFace dataset split
+```
+
+### Optimizers
+
+| Option | Description |
+|--------|-------------|
+| `adamw_torch` | AdamW (default) |
+| `adamw_torch_fused` | Fused AdamW (faster on CUDA) |
+| `adamw_8bit` | 8-bit AdamW (memory efficient) |
+| `adafactor` | Adafactor (memory efficient, no momentum) |
+| `sgd` | SGD with momentum |
+
+### Schedulers
+
+| Option | Description |
+|--------|-------------|
+| `linear` | Linear decay (default) |
+| `cosine` | Cosine annealing |
+| `cosine_with_restarts` | Cosine with warm restarts |
+| `constant` | Constant learning rate |
+| `constant_with_warmup` | Constant after warmup |
+| `polynomial` | Polynomial decay |
+
+### YAML Configuration
+
+```yaml
+task: pairs
+base_model: sentence-transformers/all-MiniLM-L6-v2
+
+data:
+  train: train.csv
+  eval: eval.csv            # optional
+
+training:
+  epochs: 3
+  batch_size: 32
+  learning_rate: 2e-5
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  fp16: true
+  eval_steps: 500
+  save_steps: 500
+  logging_steps: 100
+  optimizer: adamw_torch    # adamw_torch, adamw_8bit, adafactor, sgd
+  scheduler: linear         # linear, cosine, constant, polynomial
+
+output:
+  dir: ./output
+  push_to_hub: false
+  hf_username: null
+
+# Optional: LoRA configuration
+lora:
+  enabled: false
+  r: 64
+  alpha: 128
+  dropout: 0.1
+  target_modules: [query, key, value, dense]
+
+# Optional: Matryoshka dimensions
+matryoshka_dims: [768, 512, 256, 128, 64]
+
+# Optional: Loss variant (uses task default if not specified)
+loss_variant: mnr
+```
+
+### HuggingFace Datasets
+
+Load datasets directly from HuggingFace Hub:
+
+```bash
+vespaembed train \
+  --data sentence-transformers/all-nli \
+  --subset triplet \
+  --split train \
+  --task triplets \
+  --base-model sentence-transformers/all-MiniLM-L6-v2
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `vespaembed` | Launch web UI (default) |
+| `vespaembed serve` | Launch web UI |
+| `vespaembed train` | Train a model |
+| `vespaembed evaluate` | Evaluate a model |
+| `vespaembed export` | Export model to ONNX |
+| `vespaembed info` | Show task information |
+
+## Output
+
+Trained models are saved to `~/.vespaembed/projects/<project-name>/`:
+
+```
+~/.vespaembed/projects/my-project/
+├── final/              # Final trained model
+├── checkpoint-500/     # Training checkpoints
+├── checkpoint-1000/
+└── logs/               # TensorBoard logs
+```
+
+## Column Aliases
+
+VespaEmbed automatically recognizes common column name variations:
+
+| Task | Expected | Also Accepts |
+|------|----------|--------------|
+| pairs | `anchor` | `query`, `question`, `sent1`, `sentence1`, `text1` |
+| pairs | `positive` | `document`, `answer`, `pos`, `sent2`, `sentence2`, `text2` |
+| triplets | `negative` | `neg`, `hard_negative`, `sent3`, `sentence3`, `text3` |
+| similarity | `sentence1` | `sent1`, `text1`, `anchor`, `query` |
+| similarity | `sentence2` | `sent2`, `text2`, `positive`, `document` |
+| similarity | `score` | `similarity`, `label`, `sim_score` |
+| tsdae | `text` | `sentence`, `sentences`, `content`, `input` |
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest tests/
+
+# Run tests with coverage
+uv run pytest tests/ --cov=vespaembed
+
+# Format code
+make format
+
+# Lint
+make lint
+```
+
+## License
+
+Apache 2.0

vespaembed-0.0.2/README.md

@@ -0,0 +1,285 @@
+# VespaEmbed
+
+No-code training for embedding models. Train custom embedding models with a web UI or CLI.
+
+## Features
+
+- **Web UI** - Visual interface for configuring and monitoring training
+- **CLI** - Command-line interface for scripting and automation
+- **Multiple Tasks** - Support for pairs, triplets, similarity scoring, and unsupervised learning
+- **Loss Variants** - Choose from multiple loss functions per task
+- **Matryoshka Embeddings** - Train multi-dimensional embeddings for flexible retrieval
+- **LoRA Support** - Parameter-efficient fine-tuning with LoRA adapters
+- **Unsloth Integration** - Faster training with Unsloth optimizations
+- **HuggingFace Integration** - Load datasets, models from HuggingFace Hub, push models to Hub
+
+## Installation
+
+> **Note:** VespaEmbed is in experimental phase. Install from source.
+
+```bash
+git clone https://github.com/vespaai-playground/vespaembed.git
+cd vespaembed
+uv sync
+```
+
+### Optional Dependencies
+
+```bash
+# For Unsloth acceleration (requires NVIDIA/AMD GPU)
+uv sync --extra unsloth
+
+# For ONNX export
+uv sync --extra onnx
+
+# For development
+uv sync --extra dev
+```
+
+## Quick Start
+
+### Web UI
+
+Launch the web interface:
+
+```bash
+vespaembed
+```
+
+Open http://localhost:8000 in your browser. The UI lets you:
+- Upload training data (CSV or JSONL)
+- Select task type and base model
+- Configure hyperparameters
+- Monitor training progress
+- Download trained models
+
+### CLI
+
+Train a model from the command line:
+
+```bash
+vespaembed train \
+  --data examples/data/pairs.csv \
+  --task pairs \
+  --base-model sentence-transformers/all-MiniLM-L6-v2 \
+  --epochs 3
+```
+
+Or use a YAML config file:
+
+```bash
+vespaembed train --config config.yaml
+```
+
+## Tasks
+
+VespaEmbed supports 4 training tasks based on your data format:
+
+### Pairs
+
+Text pairs for semantic search. Use when you have query-document pairs without explicit negatives.
+
+**Data format:**
+```csv
+anchor,positive
+What is machine learning?,Machine learning is a subset of AI...
+How does photosynthesis work?,Photosynthesis converts sunlight...
+```
+
+**Loss variants:** `mnr` (default), `mnr_symmetric`, `gist`, `cached_mnr`, `cached_gist`
+
+### Triplets
+
+Text triplets with hard negatives. Use when you have explicit negative examples.
+
+**Data format:**
+```csv
+anchor,positive,negative
+What is Python?,Python is a programming language...,A python is a large snake...
+```
+
+**Loss variants:** `mnr` (default), `mnr_symmetric`, `gist`, `cached_mnr`, `cached_gist`
+
+### Similarity
+
+Text pairs with similarity scores (STS-style). Use when you have continuous similarity labels.
+
+**Data format:**
+```csv
+sentence1,sentence2,score
+A man is playing guitar,A person plays music,0.85
+The cat is sleeping,A dog is running,0.12
+```
+
+**Loss variants:** `cosine` (default), `cosent`, `angle`
+
+### TSDAE
+
+Unsupervised learning with denoising auto-encoder. Use when you only have unlabeled text for domain adaptation.
+
+**Data format:**
+```csv
+text
+Machine learning is transforming how we analyze data.
+Natural language processing enables computers to understand human language.
+```
+
+## Configuration
+
+### CLI Arguments
+
+```bash
+vespaembed train \
+  --data <path>              # Training data (CSV, JSONL, or HF dataset)
+  --task <task>              # Task type: pairs, triplets, similarity, tsdae
+  --base-model <model>       # Base model name or path
+  --project <name>           # Project name (optional)
+  --eval-data <path>         # Evaluation data (optional)
+  --epochs <n>               # Number of epochs (default: 3)
+  --batch-size <n>           # Batch size (default: 32)
+  --learning-rate <lr>       # Learning rate (default: 2e-5)
+  --optimizer <opt>          # Optimizer (default: adamw_torch)
+  --scheduler <sched>        # LR scheduler (default: linear)
+  --matryoshka               # Enable Matryoshka embeddings
+  --matryoshka-dims <dims>   # Dimensions (default: 768,512,256,128,64)
+  --unsloth                  # Use Unsloth for faster training
+  --subset <name>            # HuggingFace dataset subset
+  --split <name>             # HuggingFace dataset split
+```
+
+### Optimizers
+
+| Option | Description |
+|--------|-------------|
+| `adamw_torch` | AdamW (default) |
+| `adamw_torch_fused` | Fused AdamW (faster on CUDA) |
+| `adamw_8bit` | 8-bit AdamW (memory efficient) |
+| `adafactor` | Adafactor (memory efficient, no momentum) |
+| `sgd` | SGD with momentum |
+
+### Schedulers
+
+| Option | Description |
+|--------|-------------|
+| `linear` | Linear decay (default) |
+| `cosine` | Cosine annealing |
+| `cosine_with_restarts` | Cosine with warm restarts |
+| `constant` | Constant learning rate |
+| `constant_with_warmup` | Constant after warmup |
+| `polynomial` | Polynomial decay |
+
+### YAML Configuration
+
+```yaml
+task: pairs
+base_model: sentence-transformers/all-MiniLM-L6-v2
+
+data:
+  train: train.csv
+  eval: eval.csv            # optional
+
+training:
+  epochs: 3
+  batch_size: 32
+  learning_rate: 2e-5
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  fp16: true
+  eval_steps: 500
+  save_steps: 500
+  logging_steps: 100
+  optimizer: adamw_torch    # adamw_torch, adamw_8bit, adafactor, sgd
+  scheduler: linear         # linear, cosine, constant, polynomial
+
+output:
+  dir: ./output
+  push_to_hub: false
+  hf_username: null
+
+# Optional: LoRA configuration
+lora:
+  enabled: false
+  r: 64
+  alpha: 128
+  dropout: 0.1
+  target_modules: [query, key, value, dense]
+
+# Optional: Matryoshka dimensions
+matryoshka_dims: [768, 512, 256, 128, 64]
+
+# Optional: Loss variant (uses task default if not specified)
+loss_variant: mnr
+```
+
+### HuggingFace Datasets
+
+Load datasets directly from HuggingFace Hub:
+
+```bash
+vespaembed train \
+  --data sentence-transformers/all-nli \
+  --subset triplet \
+  --split train \
+  --task triplets \
+  --base-model sentence-transformers/all-MiniLM-L6-v2
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `vespaembed` | Launch web UI (default) |
+| `vespaembed serve` | Launch web UI |
+| `vespaembed train` | Train a model |
+| `vespaembed evaluate` | Evaluate a model |
+| `vespaembed export` | Export model to ONNX |
+| `vespaembed info` | Show task information |
+
+## Output
+
+Trained models are saved to `~/.vespaembed/projects/<project-name>/`:
+
+```
+~/.vespaembed/projects/my-project/
+├── final/              # Final trained model
+├── checkpoint-500/     # Training checkpoints
+├── checkpoint-1000/
+└── logs/               # TensorBoard logs
+```
+
+## Column Aliases
+
+VespaEmbed automatically recognizes common column name variations:
+
+| Task | Expected | Also Accepts |
+|------|----------|--------------|
+| pairs | `anchor` | `query`, `question`, `sent1`, `sentence1`, `text1` |
+| pairs | `positive` | `document`, `answer`, `pos`, `sent2`, `sentence2`, `text2` |
+| triplets | `negative` | `neg`, `hard_negative`, `sent3`, `sentence3`, `text3` |
+| similarity | `sentence1` | `sent1`, `text1`, `anchor`, `query` |
+| similarity | `sentence2` | `sent2`, `text2`, `positive`, `document` |
+| similarity | `score` | `similarity`, `label`, `sim_score` |
+| tsdae | `text` | `sentence`, `sentences`, `content`, `input` |
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest tests/
+
+# Run tests with coverage
+uv run pytest tests/ --cov=vespaembed
+
+# Format code
+make format
+
+# Lint
+make lint
+```
+
+## License
+
+Apache 2.0

{vespaembed-0.0.1 → vespaembed-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vespaembed"
-version = "0.0.1"
+version = "0.0.2"
 description = "vespaembed: no-code training for embedding models"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -9,11 +9,28 @@ authors = [
     {name = "Abhishek Thakur"}
 ]
 dependencies = [
-    "pandas>=3.0.0",
+    "sentence-transformers>=3.0.0",
+    "transformers>=4.40.0",
+    "accelerate>=0.26.0",
+    "torch>=2.0.0",
+    "datasets>=2.18.0",
+    "pandas>=2.0.0",
+    "pydantic>=2.0.0",
+    "rich>=13.0.0",
+    "fastapi>=0.111.0",
+    "uvicorn>=0.30.0",
+    "python-multipart>=0.0.9",
+    "websockets>=12.0",
+    "jinja2>=3.1.0",
+    "pyyaml>=6.0.0",
+    "tensorboard>=2.15.0",
+    "peft>=0.18.1",
+    "unsloth>=2026.1.4",
 ]
 
 [project.optional-dependencies]
-onnxruntime = ["onnxruntime>=1.23.2"]
+unsloth = ["unsloth"]
+onnx = ["onnx>=1.14.0", "onnxruntime>=1.23.2"]
 dev = [
     "black==26.1.0",
     "isort==7.0.0",
@@ -50,17 +67,14 @@ exclude = '''
   | env
   | build
   | dist
+  | unsloth_examples
 )/
 '''
 
 [tool.isort]
-ensure_newline_before_comments = true
-force_grid_wrap = 0
-include_trailing_comma = true
+profile = "black"
 line_length = 119
-lines_after_imports = 2
-multi_line_output = 3
-use_parentheses = true
+skip = [".venv", "venv", ".env", "env", "build", "dist", "unsloth_examples"]
 
 [tool.flake8]
 ignore = ["E203", "E501", "W503"]

vespaembed-0.0.2/src/vespaembed/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.2"

vespaembed-0.0.2/src/vespaembed/cli/__init__.py

@@ -0,0 +1,17 @@
+from abc import ABC, abstractmethod
+from argparse import ArgumentParser
+
+
+class BaseCommand(ABC):
+    """Base class for all CLI commands."""
+
+    @staticmethod
+    @abstractmethod
+    def register_subcommand(parser: ArgumentParser):
+        """Register the subcommand with argparse."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def execute(self):
+        """Execute the command."""
+        raise NotImplementedError

vespaembed-0.0.2/src/vespaembed/cli/commands/__init__.py

@@ -0,0 +1,7 @@
+from vespaembed.cli.commands.evaluate import EvaluateCommand
+from vespaembed.cli.commands.export import ExportCommand
+from vespaembed.cli.commands.info import InfoCommand
+from vespaembed.cli.commands.serve import ServeCommand
+from vespaembed.cli.commands.train import TrainCommand
+
+__all__ = ["EvaluateCommand", "ExportCommand", "InfoCommand", "ServeCommand", "TrainCommand"]