API Reference#

class vowpal_wabbit_next.PredictionType(self: vowpal_wabbit_next._core.PredictionType, value: int)#

Enum where each variant corresponds to Python types for the different prediction types.

Scalar = float#

Scalars = List[float]#

ActionScores = List[Tuple[int, float]]#: Where the tuple is (action_index, score) and action_index is zero based.

Pdf = List[Tuple[float, float, float]]#: Where the tuple is (left, right, value)

ActionProbs = List[Tuple[int, float]]#: Where the tuple is (action_index, probability) and action_index is zero based.

Multiclass = int#

Multilabels = List[int]#

Prob = float#

DecisionProbs = List[List[Tuple[int, float]]]#: Where the tuple is (action_index, probability) and action_index is zero based.

ActionPdfValue = Tuple[float, float]#: Where the tuple is (action, value)

ActiveMulticlass = Tuple[int, List[int]]#: Where the tuple is (predicted_class, more_info_required_for_classes)

NoPred = None#

class vowpal_wabbit_next.LabelType(self: vowpal_wabbit_next._core.LabelType, value: int)#

Enum where each variant corresponds to Python types for the different label types.

Simple#: Type: SimpleLabel

CB#: Type: CBLabel

CBEval#: Type: NotImplemented

CS#: Type: CSLabel

CCB#: Type: NotImplemented

Continuous#: Type: NotImplemented

Multiclass#: Type: MulticlassLabel

Multilabel#: Type: NotImplemented

NoLabel#: Type: None

Slates#: Type: NotImplemented

vowpal_wabbit_next.apply_delta(model: Workspace[Literal[False]], delta: ModelDelta) → Workspace[Literal[False]]#

Apply the delta to the model.

Parameters:

model (Workspace) – The model to apply the delta to
delta (ModelDelta) – The delta to apply

Returns:

The new model

Return type:

Workspace

class vowpal_wabbit_next.CacheFormatReader(workspace: Workspace[T], file: BinaryIO)#

Read VW examples in cache format from the given file.

Examples

>>> from vowpal_wabbit_next import Workspace, TextFormatParser, CacheFormatWriter
>>> workspace = Workspace()
>>> with open("data.cache", "rb") as f:
...     with CacheFormatReader(workspace, f) as reader:
...         for example in reader:
...               workspace.predict_one(example)

Parameters:

workspace (Workspace) – Workspace object used to configure this reader
file (BinaryIO) – File to read from

__iter__() → Iterator[Union[Example, List[Example]]]#

class vowpal_wabbit_next.CacheFormatWriter(workspace: Workspace[T], file: BinaryIO)#

Creates a VW cache file.

Examples

>>> from vowpal_wabbit_next import Workspace, TextFormatParser, CacheFormatWriter
>>> workspace = Workspace()
>>> parser = TextFormatParser(workspace)
>>> with open("data.cache", "wb") as f:
...     with CacheFormatWriter(workspace, f) as writer:
...         writer.write_example(parser.parse_line("1.0 | price:.18 sqft:.15 age:.35 1976"))

Parameters:

workspace (Workspace) – Workspace object used to configure this writer.
file (BinaryIO) – File to write cache to

write_example(example: Union[Example, List[Example]]) → None#

Write a single example to the cache file.

Parameters:: example (Union[Example, List[Example]]) – Either a single or multiex to be written.

vowpal_wabbit_next.calculate_delta(base_model: Workspace[T], derived_model: Workspace[T]) → ModelDelta#

Produce a delta between two existing models.

Parameters:

base_model (Workspace) – The base of the model
derived_model (Workspace) – The model produced from further training of base_model

Returns:

The delta between the models.

Return type:

ModelDelta

class vowpal_wabbit_next.CBLabel(self: vowpal_wabbit_next._core.CBLabel, *, label: Optional[Union[Tuple[float, float], Tuple[int, float, float]]] = None, weight: float = 1.0, shared: bool = False)#

A label representing a contextual bandit problem.

Note

Currently the label can only contain 1 or 0 cb costs. There is a mode in vw for CB (non-adf) that allows for multiple cb_classes per example, but it is not currently accessible via direct label access. If creating examples/labels from parsed input it should still work as expected. If you need this feature, please open an issue on the github repo.

Parameters:

label (Optional[Union[Tuple[float, float], Tuple[int, float, float]]) – This is (action, cost, probability). The same rules as VW apply for if the action can be left out of the tuple.
weight (float) – The weight of the example.
shared (bool) – Whether the example is shared. This is only used for ADF examples and must be the first example. There can only be one shared example per ADF example list.

property label#: The label for the example. The format of the label is (action, cost, probability). If the action is not specified, it will be set to 0.

property shared#: Whether the example is shared. This is only used for ADF examples and must be the first example. There can only be one shared example per ADF example list.

property weight#: The weight of the example.

exception vowpal_wabbit_next.CLIError(message: str, driver_output: str, log_output: List[str])#

Represents a failure when running the CLI. Exposes output for additional context.

Parameters:

message (str) – Error message
driver_output (str) – Output of the VW driver
log_output (List[str]) – List of logs messages

class vowpal_wabbit_next.CSLabel(self: vowpal_wabbit_next._core.CSLabel, *, costs: Optional[List[Tuple[float, float]]] = None, shared: bool = False)#

A label representing a cost sensitive classification problem.

Parameters:

costs (Optional[List[Tuple[int, float]]]) – List of classes and costs. If there is no label, this should be None.
shared (bool) – Whether the example represents the shared context

property costs#: The costs for the example. The format of the costs is (class_index, cost).

property shared#: Whether the example represents the shared context.

class vowpal_wabbit_next.CCBExampleType(self: vowpal_wabbit_next._core.CCBExampleType, value: int)#

Action = <CCBExampleType.Action: 2>#

Shared = <CCBExampleType.Shared: 1>#

Slot = <CCBExampleType.Slot: 3>#

Unset = <CCBExampleType.Unset: 0>#

property name#

property value#

class vowpal_wabbit_next.CCBLabel(self: vowpal_wabbit_next._core.CCBLabel, type: vowpal_wabbit_next._core.CCBExampleType, *, outcome: Optional[Tuple[float, List[Tuple[int, float]]]] = None, explicit_included_actions: Optional[List[int]] = None)#

A label representing a conditional contextual bandit problem.

Parameters:

type (CCBExampleType) – The type of the example. Unset is invalid.
outcome (Optional[Tuple[float, List[Tuple[int, float]]]]) – The outcome of the example. The format of the outcome is (cost, [(action, probability)]).
explicit_included_actions (Optional[List[int]]) – The list of actions explicitly included from the slot.

property example_type#: Whether the example represents the shared context.

property explicit_included_actions#: The list of actions explicitly excluded from the slot.

property outcome#: The outcome of the example. The format of the outcome is (cost, [(action, probability)]).

class vowpal_wabbit_next.DebugNode#

A node in the computation tree of a single learn/predict call. This represents the state of the example as it is entering a given reduction.

Warning

This is a highly experimental feature.

property children#: The child computations that this node processed. This represents traversal of the stack.

property function#: The function that was called on this reduction. Either ‘learn’ or ‘predict’.

property input_labels#: The label that was passed into this reduction. Or, list of labels if this reduction is a multi-example reduction.

property interactions#: The interactions that were used to generate the features for this reduction. Or, list of interactions if this reduction is a multi-example reduction.

property is_multiline#: Whether this reduction is a multi-example reduction.

property name#: Name of the reduction being called.

property num_examples#: The number of examples that were processed by this reduction. This is always 1 for single example reductions.

property offset#: The offset of the example. Or, list of offsets if this reduction is a multi-example reduction. This also includes the stride of the bottom learner.

property output_prediction#: The prediction that this reduction produced.

property partial_prediction#: The partial prediction on the example after this reduction ran. Or, list of partial predictions if this reduction is a multi-example reduction. This is generally only set by the bottom of the stack.

property self_duration_ns#: The duration of this reduction in nanoseconds. It does not include time it takes to call children.

property total_duration_ns#: The duration of this reduction and all children in nanoseconds.

property updated_prediction#: The partial prediction on the example after this reduction ran. Or, list of partial predictions if this reduction is a multi-example reduction. This is generally only set by the bottom of the stack.

property weight#: The weight of the example. Or, list of weights if this reduction is a multi-example reduction.

class vowpal_wabbit_next.DSJsonFormatParser(workspace: Workspace[T])#

Parse VW DSJson format examples.

Parameters:: workspace (Workspace) – Workspace object used to configure this parser

parse_json(text: str) → List[Example]#

Parse a single json object in dsjson format.

Examples

>>> from vowpal_wabbit_next import Workspace, DSJsonFormatParser
>>> workspace = Workspace(["--cb_explore_adf"])
>>> parser = DSJsonFormatParser(workspace)
>>> json_str = """
... {
...     "_label_cost": -1.0,
...     "_label_probability": 0.5,
...     "_label_Action": 2,
...     "_labelIndex": 1,
...     "a": [2, 1],
...     "c": {
...         "shared": { "f": "1" },
...         "_multi": [{ "action": { "f": "1" } }, { "action": { "f": "2" } }]
...     },
...     "p": [0.5, 0.5]
... }
... """
>>> example = parser.parse_json(json_str)

Parameters:: text (str) – JSON string of input
Returns:: List of parsed examples
Return type:: List[Example]

class vowpal_wabbit_next.DSJsonFormatReader(workspace: Workspace[T], file: TextIO)#

Read VW DSJson format examples from the given text file. This reader always produces lists of examples.

Examples

>>> from vowpal_wabbit_next import Workspace, DSJsonFormatReader
>>> workspace = Workspace()
>>> with open("data.txt", "r") as f:
...     with DSJsonFormatReader(workspace, f) as reader:
...         for example in reader:
...               workspace.predict_one(example)

Parameters:

workspace (Workspace) – Workspace object used to configure this reader
file (BinaryIO) – File to read from

__iter__() → Iterator[List[Example]]#

class vowpal_wabbit_next.Example(*, _existing_example: ~typing.Optional[~vowpal_wabbit_next._core.Example] = None, _label_type: ~vowpal_wabbit_next._core.LabelType = <LabelType.NoLabel: 9>)#

A single VW example.

Parameters:

_existing_example (Optional[_core.Example], optional) – This is an internal parameter and should not be used by end users.
_label_type (LabelType, optional) – This is an internal parameter and should not be used by end users.

get_label() → Optional[Union[SimpleLabel, MulticlassLabel, CBLabel, CSLabel, CCBLabel]]#

Get the label of the example.

Returns:: The label of the example
Return type:: AllLabels

set_label(label: Optional[Union[SimpleLabel, MulticlassLabel, CBLabel, CSLabel, CCBLabel]]) → None#

Set the label of the example.

Parameters:: label (AllLabels) – The label to set
Raises:: ValueError – If the label type is not supported.

property tag: str#

Get the tag of the example.

Returns:: The tag of the example
Return type:: str

property feat_group_indices: List[int]#

Get the populated feature groups for this example.

Returns:: The populated feature groups for this example
Return type:: List[int]

__iter__() → Iterator[FeatureGroupRef]#

Iterate over the feature groups in this example.

Examples

>>> for fg in example:
>>>     print(fg.feat_group_index)
>>>     print(fg.indices)
>>>     print(fg.values)

Yields:: Iterator[FeatureGroupRef] – An iterator over the feature groups in this example

__getitem__(key: Union[str, int]) → FeatureGroupRef#

Get a reference to a feature group. If it doesn’t already exist it will be created.

Parameters:: key (Union[str, int]) – Either the first character of namespace or index of namespace

Examples

>>> print(example["d"].feat_group_index)
>>> print(example["d"].indices)
>>> print(example["d"].values)

Returns:: A reference to the feature group
Return type:: FeatureGroupRef

__delitem__(key: Union[str, int]) → None#

Delete a feature group.

Parameters:: key (Union[str, int]) – Either the first character of namespace or index of namespace

__contains__(key: Union[str, int]) → bool#

Check if a feature group exists.

Parameters:: key (Union[str, int]) – Either the first character of namespace or index of namespace
Returns:: True if the feature group exists, False otherwise
Return type:: bool

class vowpal_wabbit_next.JsonFormatParser(workspace: Workspace[T])#

Parse VW Json format examples.

Parameters:: workspace (Workspace) – Workspace object used to configure this parser

parse_json(text: str) → Union[Example, List[Example]]#

Parse a single json object in json format.

Examples

>>> from vowpal_wabbit_next import Workspace, JsonFormatParser
>>> workspace = Workspace()
>>> parser = JsonFormatParser(workspace)
>>> json_str = """
... {
...     "_label": -1.0,
...     "feat1": 0.5,
...     "feat2": 2,
... }
... """
>>> example = parser.parse_json(json_str)

Parameters:: text (str) – JSON string of input
Returns:: Parsed example or list of examples
Return type:: Union[Example, List[Example]]

class vowpal_wabbit_next.JsonFormatReader(workspace: Workspace[T], file: TextIO)#

Read VW Json format examples from the given text file. This reader always produces lists of examples.

Examples

>>> from vowpal_wabbit_next import Workspace, JsonFormatReader
>>> workspace = Workspace()
>>> with open("data.txt", "r") as f:
...     with JsonFormatReader(workspace, f) as reader:
...         for example in reader:
...               workspace.predict_one(example)

Parameters:

workspace (Workspace) – Workspace object used to configure this reader
file (BinaryIO) – File to read from

__iter__() → Iterator[Union[Example, List[Example]]]#

vowpal_wabbit_next.merge_deltas(deltas: List[ModelDelta]) → ModelDelta#

Merge a list of deltas into a single delta.

Parameters:: deltas (List[ModelDelta]) – The deltas to merge. All deltas should come from the same base model.
Returns:: The merged delta.
Return type:: ModelDelta

class vowpal_wabbit_next.ModelDelta(data: bytes, *, _existing_model_delta: Optional[ModelDelta] = None)#

A delta between two VW models.

The standard way to create one is with vowpal_wabbit_next.calculate_delta().

Parameters:

data (bytes) – Bytes of a previously serialized ModelDelta to be used for loading
_existing_model_delta (Optional[_core.ModelDelta], optional) – This is an internal parameter and should not be used by end users.

serialize() → bytes#

Serialize the delta.

Returns:: The serialized delta.
Return type:: bytes

class vowpal_wabbit_next.MulticlassLabel(self: vowpal_wabbit_next._core.MulticlassLabel, label: int, weight: float = 1.0)#

A label representing a multiclass classification problem.

Parameters:

label (int) – The label.
weight (float) – The weight of the example.

property label#: The class of this label.

property weight#: The weight of this label.

vowpal_wabbit_next.run_cli_driver(args: List[str], *, onethread: bool = False, cwd: Optional[Path] = None) → Tuple[str, List[str]]#

Is the equivalent of running the VW command line tool with the given command line.

There are a few differences:

Any input from stdin is not supported
The argfile input to command line is not supported
If any place in VW writes to stdout, stderr directly it is not captured. This means that –version and –help are not currently captured.

Warning

This is an experimental feature.

Examples

>>> from vowpal_wabbit_next import run_cli_driver
>>> driver_output, logs = run_cli_driver(["-d", "my_data.txt"])

You can use shlex to split a command line:

>>> from vowpal_wabbit_next import run_cli_driver
>>> import shlex
>>> driver_output, logs = run_cli_driver(shlex.split("-d my_data.txt"))

Parameters:

args (List[str]) – Arguments to be passed to the command line driver
onethread (bool, optional) – Whether to use background thread for parsing. If False, a background thread is used for parsing. If True, no background threads are used and everything is done in the foreground of this call.
cwd (Optional[Path], optional) – The current working directory to use for the command line driver. If None, the current working directory is used.

Raises:

CLIError – If there is any error raised by execution.

Returns:

driver output and log messages respectively as a tuple

Return type:

Tuple[str, List[str]]

class vowpal_wabbit_next.SimpleLabel(self: vowpal_wabbit_next._core.SimpleLabel, label: float, weight: float = 1.0, initial: float = 0.0)#

A label representing a simple regression problem.

Parameters:

label (float) – The label.
weight (float) – The weight of the example.
initial (float) – The initial value of the prediction.

property initial#: The initial value of the prediction.

property label#: The label.

property weight#: The weight of this label.

class vowpal_wabbit_next.TextFormatParser(workspace: Workspace[T])#

Parse VW text format examples.

Parameters:: workspace (Workspace) – Workspace object used to configure this parser

parse_line(text: str) → Example#

Parse a single line.

Examples

>>> from vowpal_wabbit_next import Workspace, TextFormatParser
>>> workspace = Workspace()
>>> parser = TextFormatParser(workspace)
>>> example = parser.parse_line("1.0 | price:.18 sqft:.15 age:.35 1976")

Parameters:: text (str) – Text to parse
Returns:: Parsed example
Return type:: Example

class vowpal_wabbit_next.TextFormatReader(workspace: Workspace[T], file: TextIO)#

Read VW text format examples from the given text file. This reader produces either single Examples or List[Example] based on if the given workspace is multiline or not.

Examples

>>> from vowpal_wabbit_next import Workspace, TextFormatReader
>>> workspace = Workspace()
>>> with open("data.txt", "r") as f:
...     with TextFormatReader(workspace, f) as reader:
...         for example in reader:
...               workspace.predict_one(example)

Parameters:

workspace (Workspace) – Workspace object used to configure this reader
file (BinaryIO) – File to read from

__iter__() → Iterator[Union[Example, List[Example]]]#

vowpal_wabbit_next.VW_COMMIT: str = '9db1f5ffd'#: Commit of VowpalWabbit that this package is built with

vowpal_wabbit_next.VW_VERSION: str = '9.9.0'#: Version number of VowpalWabbit that this package is built with

class vowpal_wabbit_next.Workspace(args: List[str] = [], *, model_data: Optional[bytes] = None, record_feature_names: bool = False, record_metrics: bool = False, enable_debug_tree: Literal[False] = False)#

class vowpal_wabbit_next.Workspace(*, _existing_workspace: Optional[Workspace] = None)

Main object used for making predictions and training a model.

The VW library logs various things while running. There are two streams of logging exposed, which can be accessed via the standard Python logging interface. * vowpal_wabbit_next.log - VW’s structured logging stream. If it outputs a warning it will be logged here. * vowpal_wabbit_next.driver - This is essentially the CLI driver output. This is rarely needed from Python.

See the logging example below.

Examples

Load a model from a file:

>>> from vowpal_wabbit_next import Workspace
>>> with open("model.bin", "rb") as f:
...     model_data = f.read()
>>> workspace = Workspace(model_data=model_data)

Create a workspace for training a contextual bandit with action dependent features model:

>>> from vowpal_wabbit_next import Workspace
>>> workspace = Workspace(["--cb_explore_adf"])

Outputting structured logging messages from VW:

>>> from vowpal_wabbit_next import Workspace
>>> import logging
>>> logging.basicConfig(level=logging.INFO)
>>> logging.getLogger("vowpal_wabbit_next.log").setLevel("INFO")
>>> workspace = Workspace()

Parameters:

args (List[str]) – VowpalWabbit command line options for configuring the model. An overall list can be found here. Options which affect the driver are not supported. For example: –sort_features, –ngram, –feature_limit, –ignore, –extra_metrics, –dump_json_weights_experimental
model_data (Optional[bytes], optional) – Bytes of a VW model to be loaded.
record_feature_names (bool, optional) – If true, the invert hash will be recorded for each example. This is required to use vowpal_wabbit_next.Workspace.json_weights(). This will slow down parsing and learn/predict.
record_metrics (bool, optional) – If true, reduction metrics will be enabled and can be fetched with vowpal_wabbit_next.Workspace.metrics
enable_debug_tree (bool, optional) –
If true, debug information in the form of the computation tree will be emitted by learn_one(), predict_one() and predict_then_learn_one(). This will affect performance negatively. See DebugNode for more information.

Warning

This is an experimental feature.
_existing_workspace (Optional[_core.Workspace], optional) – This is for internal usage and should not be set by a user.

predict_one(example: Union[Example, List[Example]]) → Tuple[Optional[Union[float, List[float], List[Tuple[int, float]], List[List[Tuple[int, float]]], int, List[int], List[Tuple[float, float, float]], Tuple[float, float], Tuple[int, List[int]]]], DebugNode]#

predict_one(example: Union[Example, List[Example]]) → Optional[Union[float, List[float], List[Tuple[int, float]], List[List[Tuple[int, float]]], int, List[int], List[Tuple[float, float, float]], Tuple[float, float], Tuple[int, List[int]]]]

Make a single prediction.

Examples

>>> from vowpal_wabbit_next import Workspace, TextFormatParser
>>> workspace = Workspace()
>>> parser = TextFormatParser(workspace)
>>> workspace.learn_one(parser.parse_line("1.0 | price:.18 sqft:.15 age:.35 1976"))
>>> workspace.predict_one(parser.parse_line("| price:.53 sqft:.32 age:.87 1924"))
1.0

Parameters:: example (Union[Example, List[Example]]) – Example to use for prediction. This should be a list if this workspace is vowpal_wabbit_next.Workspace.multiline(), otherwise it is should be a single Example
Returns:: Prediction produced by this example. Or, if enable_debug_tree=True was passed in the constructor then a tuple of prediction and DebugNode will be returned. The type corresponds to the prediction_type() of the model. See PredictionType for the mapping to types.
Return type:: Prediction

learn_one(example: Union[Example, List[Example]]) → List[DebugNode]#

learn_one(example: Union[Example, List[Example]]) → None

Learn from one single example. Note, passing a list of examples here means the input is a multiline example, and not several individual examples. The label type of the example must match what is returned by vowpal_wabbit_next.Workspace.label_type().

Examples

>>> from vowpal_wabbit_next import Workspace, TextFormatParser
>>> workspace = Workspace()
>>> parser = TextFormatParser(workspace)
>>> workspace.learn_one(parser.parse_line("1.0 | price:.18 sqft:.15 age:.35 1976"))
>>> workspace.predict_one(parser.parse_line("| price:.53 sqft:.32 age:.87 1924"))
1.0

Parameters:: example (Union[Example, List[Example]]) – Example to learn on.
Returns:: If enable_debug_tree=True was passed in the constructor then a DebugNode will be returned. Otherwise, None is returned.
Return type:: Union[None, DebugNode]

predict_then_learn_one(example: Union[Example, List[Example]]) → Tuple[Optional[Union[float, List[float], List[Tuple[int, float]], List[List[Tuple[int, float]]], int, List[int], List[Tuple[float, float, float]], Tuple[float, float], Tuple[int, List[int]]]], List[DebugNode]]#

predict_then_learn_one(example: Union[Example, List[Example]]) → Optional[Union[float, List[float], List[Tuple[int, float]], List[List[Tuple[int, float]]], int, List[int], List[Tuple[float, float, float]], Tuple[float, float], Tuple[int, List[int]]]]

Make a prediction then learn from the example. This is potentially more efficient than a predict_one call followed by a learn_one call as the implementation is able to avoid duplicated work as long as the prediction is guaranteed to be from before learning.

Examples

>>> from vowpal_wabbit_next import Workspace, TextFormatParser
>>> workspace = Workspace()
>>> parser = TextFormatParser(workspace)
>>> workspace.predict_then_learn_one(parser.parse_line("1.0 | price:.18 sqft:.15 age:.35 1976"))
0.0

Parameters:: example (Union[Example, List[Example]]) – Example to use for prediction. This should be a list if this workspace is vowpal_wabbit_next.Workspace.multiline(), otherwise it is should be a single Example
Returns:: Prediction produced by this example. Or, if enable_debug_tree=True was passed in the constructor then a tuple of prediction and DebugNode will be returned. The type corresponds to the prediction_type() of the model. See PredictionType for the mapping to types.
Return type:: Prediction

end_pass() → None#: Signal the end of a pass to the model.

property prediction_type: PredictionType#

Based on the command line parameters used to setup VW a certain type of prediction is produced. See vowpal_wabbit_next.PredictionType for the list of types and their corresponding Python type.

Returns:: The type of prediction this Workspace produces
Return type:: PredictionType

property label_type: LabelType#

Based on the command line parameters used to setup VW a certain label type is required. This can also be thought of as the type of problem being solved.

Returns:: The type of label Examples must have to be used by this Workspace
Return type:: LabelType

property multiline: bool#

Based on the command line parameters used to setup VW, the input to learn, predict or parsers expects either single Examples or lists of Examples.

Returns:: True if this Workspace is configured as multiline, otherwise False
Return type:: bool

property metrics: Dict[str, Union[int, float, str, bool, MetricsDict]]#

Metrics is a dictionary of names to values recorded internally by VW. There may be nested mappings. This is completely dependent on the command line parameters used to setup VW and the reductions enabled.

Returns:: Dictionary of metrics
Return type:: MetricsDict
Raises:: ValueError – If the workspace is not configured to record metrics

serialize() → bytes#

Serialize the current workspace as a VW model that can be loaded by the Workspace constructor, or command line tool.

Returns:: raw bytes of serialized Workspace
Return type:: bytes

static load_from_file(file_path: Union[str, os.PathLike[Any]], args: List[str] = [], *, record_feature_names: bool = False, record_metrics: bool = False, enable_debug_tree: bool = False) → Workspace[Any]#

Load a VW model from a file.

Parameters:

file_path (Union[str, os.PathLike[Any]]) – Path to file containing serialized model
args (List[str]) –
VowpalWabbit command line options for configuring the model. An overall list can be found here. Options which affect the driver are not supported. For example: –sort_features, –ngram, –feature_limit, –ignore, –extra_metrics, –dump_json_weights_experimental
record_feature_names (bool, optional) – If true, the invert hash will be recorded for each example. This is required to use vowpal_wabbit_next.Workspace.json_weights(). This will slow down parsing and learn/predict.
record_metrics (bool, optional) – If true, reduction metrics will be enabled and can be fetched with vowpal_wabbit_next.Workspace.metrics
enable_debug_tree (bool, optional) –
If true, debug information in the form of the computation tree will be emitted by learn_one(), predict_one() and predict_then_learn_one(). This will affect performance negatively. See DebugNode for more information.

Warning

This is an experimental feature.

Returns:

Workspace with the loaded model

Return type:

Workspace[Any]

serialize_to_file(file_path: Union[str, os.PathLike[Any]]) → None#: Serialize the current workspace as a VW model to a file.

weights() → ndarray[Any, dtype[float32]]#

Access to the weights of the model currently.

This function returns a view of the weights and any changes to the returned array will be reflected in the model.

There are 3 dimensions:

The feature index (aka weight index)
The index of the interleaved model, which should usually be 0
The weight itself and the extra state stored with the weight

Attention

Only dense weights are supported.

Warning

This is an experimental feature.

Examples

>>> from vowpal_wabbit_next import Workspace
>>> model = Workspace()
>>> print(model.weights().shape)
(262144, 1, 4)

Returns:: Array of weights
Return type:: np.ndarray

json_weights(*, include_feature_names: bool = False, include_online_state: bool = False) → str#

Debugging utility which dumps the weights in the model currently as a JSON string.

Warning

This is an experimental feature.

Parameters:

include_feature_names (bool, optional) – Includes the feature names and interaction terms in the output. This requires the workspace to be configured to support it by passing record_feature_names=True to the constructor of vowpal_wabbit_next.Workspace. Defaults to False.
include_online_state (bool, optional) – Includes extra save_resume state in the output.

Returns:

JSON string representing model weights

Return type:

str

Raises:

ValueError – If the workspace is not configured to record feature names and include_feature_names is True

readable_model(*, include_feature_names: bool = False) → str#

Equivalent to the –readable_model command line option. If include_feature_names is True, then the equivalent of –invert_hash.

Parameters:: include_feature_names (bool, optional) – Includes the feature names and interaction terms in the output. This requires the workspace to be configured to support it by passing record_feature_names=True to the constructor of vowpal_wabbit_next.Workspace. Defaults to False.
Returns:: JSON string representing model
Return type:: str
Raises:: ValueError – If the workspace is not configured to record feature names and include_feature_names is True

get_index_for_scalar_feature(feature_name: str, *, feature_value: Optional[str] = None, namespace_name: str = ' ') → int#

Calculate the model index for a given feature.

The logic is rather complicated to work out an index. This function also takes into account index truncation caused by the index multiplier taking the index out of the standard weight space.

Warning

This is an experimental feature, the interface may change.

Examples

>>> from vowpal_wabbit_next import Workspace
>>> model = Workspace()
>>> # Feature which looks like "|test thing" in text format
>>> model.get_index_for_scalar_feature("thing", namespace_name="test")
148099

Parameters:

feature_name (str) – The name of the feature
feature_value (Optional[str], optional) – String value of feature. If passed chain hashing will be used. In text format this looks like feature_name:feature_value
namespace_name (str, optional) – Namespace of feature. Defaults to “ “ which is the default namespace.

Returns:

The index of the feature

Return type:

int

class vowpal_wabbit_next._core.FeatureGroupRef#

property feat_group_index#: The index of the feature group. Since this is just the first letter of the namespace, multiple namespaces can map to the same group.

property indices#: Feature indices in this group.

push_feature(self: vowpal_wabbit_next._core.FeatureGroupRef, index: int, value: float) → None#: Push a single feature into this group. This is an advanced function. Specifically, to ensure consistency with data that comes from parsers the index passed should incorporate the namespace hash.

push_many_features(self: vowpal_wabbit_next._core.FeatureGroupRef, indices: numpy.ndarray[numpy.uint64], values: numpy.ndarray[numpy.float32]) → None#: Push many features into this group. This is an advanced function. Specifically, to ensure consistency with data that comes from parsers the index passed should incorporate the namespace hash.

truncate_to(self: vowpal_wabbit_next._core.FeatureGroupRef, i: int) → None#: Truncate this feature group to the given size

property values#: Feature values in this group.