Metadata-Version: 2.4
Name: sinapsis-vowpal-wabbit
Version: 0.1.0
Summary: Package for Vowpal Wabbit algorithms, featuring high-performance implementations of Contextual Bandits (ADF) and reinforcement learning patterns.
Author-email: SinapsisAI <dev@sinapsis.tech>
Project-URL: Homepage, https://sinapsis.tech
Project-URL: Documentation, https://docs.sinapsis.tech/docs
Project-URL: Tutorials, https://docs.sinapsis.tech/tutorials
Project-URL: Repository, https://github.com/Sinapsis-AI/sinapsis-vowpal-wabbit.git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.3.3
Requires-Dist: setuptools==81.0.0
Requires-Dist: sinapsis>=0.2.26
Requires-Dist: vowpalwabbit>=9.10.0
Provides-Extra: sinapsis-data-readers
Requires-Dist: sinapsis-data-readers>=0.1.26; extra == "sinapsis-data-readers"
Provides-Extra: all
Requires-Dist: sinapsis-vowpal-wabbit[scikit-learn,sentence-transformers,sinapsis-data-readers]; extra == "all"
Provides-Extra: sentence-transformers
Requires-Dist: sentence-transformers>=5.2.3; extra == "sentence-transformers"
Provides-Extra: scikit-learn
Requires-Dist: scikit-learn>=1.7.2; extra == "scikit-learn"
Dynamic: license-file

<h1 align="center">
<br>
<a href="https://sinapsis.tech/">
  <img
    src="https://github.com/Sinapsis-AI/brand-resources/blob/main/sinapsis_logo/4x/logo.png?raw=true"
    alt="" width="300">
</a><br>
Sinapsis Vowpal-Wabbit
<br>
</h1>

<h4 align="center">High-performance Contextual Bandits and Reinforcement Learning using Vowpal Wabbit</h4>

<p align="center">
<a href="#installation">🐍 Installation</a> •
<a href="#features">🚀 Features</a> •
<a href="#usage">📚 Usage example</a> •
<a href="#documentation">📙 Documentation</a> •
<a href="#license">🔍 License</a>
</p>

**Sinapsis Vowpal Wabbit** provides a modular framework for implementing real-time decision-making systems. By leveraging the industry-standard Vowpal Wabbit engine, this module enables efficient online learning and reinforcement learning (RL) workflows with minimal latency.

<h2 id="installation">🐍 Installation</h2>

Install using your package manager of choice. We encourage the use of <code>uv</code>

Example with <code>uv</code>:

```bash
  uv pip install sinapsis-vowpal-wabbit --extra-index-url https://pypi.sinapsis.tech
```

 or with raw <code>pip</code>:

```bash
  pip install sinapsis-vowpal-wabbit --extra-index-url https://pypi.sinapsis.tech
```

> [!IMPORTANT]
> Templates may require extra dependencies. For development, we recommend installing the package with all the optional dependencies:
>

with <code>uv</code>:

```bash
  uv pip install sinapsis-vowpal-wabbit[all] --extra-index-url https://pypi.sinapsis.tech
```

 or with raw <code>pip</code>:

```bash
  pip install sinapsis-vowpal-wabbit[all] --extra-index-url https://pypi.sinapsis.tech
```

> [!TIP]
> Use CLI command ```sinapsis info --all-template-names``` to show a list with all the available Template names installed with Sinapsis OCR.

> [!TIP]
> Use CLI command ```sinapsis info --example-template-config CBExploreADFPredict``` to produce an example Agent config for the CBExploreADFPredict template.

<h2 id="features">🚀 Features</h2>

<h3>Templates Supported</h3>

This repository implements specific templates for Vowpal Wabbit's most powerful reductions:

- **CBExploreADFPredict**: Handles real-time inference for Contextual Bandits using Action-Dependent Features (ADF).

- **CBExploreADFLearn**: Template to perform offline learning. It iterates through historical datasets (context, action, reward) for a defined number of epochs to optimize the model weights before deployment.

- **CBExploreADFPredictEmbeddings**: Handles real-time inference for Contextual Bandits using Action-Dependent Features (ADF) enhanced with text embeddings. This template processes incoming context and actions by combining traditional raw text features with vector-based embeddings to provide more nuanced, semantically aware predictions in production environments.

- **CBExploreADFLearnEmbeddings**: Template for offline learning that incorporates text embeddings into the optimization process. It iterates through historical datasets (context, actions, and rewards) over a defined number of epochs. By training on a combination of raw text and sentence based embeddings, it captures deeper semantic relationships to more effectively optimize model weights prior to deployment.

<h2 id="usage">📚 Usage example</h2>

<details>
<summary><strong><span style="font-size: 1.4em;"> CBExploreADFPredict Example</span></strong></summary>

```yaml
agent:
  name: my_test_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}
- template_name: CBExploreADFPredict
  class_name: CBExploreADFPredict
  template_input: InputTemplate
  attributes:
    stop_words: ["from", "at", "i", "you"]
    clean_text_pattern: '[^a-z0-9\s]'
    actions: ["action_1", "action_2","action_3"]
    vw_workspace_params:
      bit_precision: 24
      quadratic_interactions: ["CA"]
      cubic_interactions: []
      ngram_namespaces: ["C"]
      ngram_size: 2
      learning_rate: 0.5
      l1: 0.0
      l2: 0.0
      exploration_method: epsilon
      exploration_value: 0.2
      adaptive: true
      normalized: true
      quiet: false
    remove_stop_words: false
    remove_special_characters: true
    model_path: "artifacts/model.vw"
    inference_only: true
    threshold: 0
    top_k: 3
```

</details>

To run, simply use:

```bash
sinapsis run name_of_the_config.yml
```

<h2 id="documentation">📙 Documentation</h2>

Documentation for this and other sinapsis packages is available on the [sinapsis website](https://docs.sinapsis.tech/docs)

Tutorials for different projects within sinapsis are available at [sinapsis tutorials page](https://docs.sinapsis.tech/tutorials)

<h2 id="license">🔍 License</h2>

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the [LICENSE](LICENSE) file.

For commercial use, please refer to our [official Sinapsis website](https://sinapsis.tech) for information on obtaining a commercial license.
