pixeltable 0.2.12__py3-none-any.whl → 0.2.13__py3-none-any.whl

pixeltable/__version__.py

@@ -1,3 +1,3 @@
 # These version placeholders will be replaced during build.
-__version__ = "0.2.12"
-__version_tuple__ = (0, 2, 12)
+__version__ = "0.2.13"
+__version_tuple__ = (0, 2, 13)

pixeltable/catalog/insertable_table.py

@@ -129,11 +129,11 @@ class InsertableTable(Table):
                     msg = str(e)
                     raise excs.Error(f'Error in column {col.name}: {msg[0].lower() + msg[1:]}\nRow: {row}')
 
-    def delete(self, where: Optional['pixeltable.exprs.Predicate'] = None) -> UpdateStatus:
+    def delete(self, where: Optional['pixeltable.exprs.Expr'] = None) -> UpdateStatus:
         """Delete rows in this table.
 
         Args:
-            where: a Predicate to filter rows to delete.
+            where: a predicate to filter rows to delete.
 
         Examples:
             Delete all rows in a table:

pixeltable/catalog/table.py

@@ -113,7 +113,7 @@ class Table(SchemaObject):
         from pixeltable.dataframe import DataFrame
         return DataFrame(self._tbl_version_path).select(*items, **named_items)
 
-    def where(self, pred: 'exprs.Predicate') -> 'pixeltable.dataframe.DataFrame':
+    def where(self, pred: 'exprs.Expr') -> 'pixeltable.dataframe.DataFrame':
         """Return a DataFrame for this table.
         """
         # local import: avoid circular imports
@@ -716,13 +716,13 @@ class Table(SchemaObject):
         raise NotImplementedError
 
     def update(
-            self, value_spec: dict[str, Any], where: Optional['pixeltable.exprs.Predicate'] = None, cascade: bool = True
+            self, value_spec: dict[str, Any], where: Optional['pixeltable.exprs.Expr'] = None, cascade: bool = True
     ) -> UpdateStatus:
         """Update rows in this table.
 
         Args:
             value_spec: a dictionary mapping column names to literal values or Pixeltable expressions.
-            where: a Predicate to filter rows to update.
+            where: a predicate to filter rows to update.
             cascade: if True, also update all computed columns that transitively depend on the updated columns.
 
         Examples:
@@ -786,11 +786,11 @@ class Table(SchemaObject):
             row_updates.append(col_vals)
         return self._tbl_version.batch_update(row_updates, rowids, cascade)
 
-    def delete(self, where: Optional['pixeltable.exprs.Predicate'] = None) -> UpdateStatus:
+    def delete(self, where: Optional['pixeltable.exprs.Expr'] = None) -> UpdateStatus:
         """Delete rows in this table.
 
         Args:
-            where: a Predicate to filter rows to delete.
+            where: a predicate to filter rows to delete.
 
         Examples:
             Delete all rows in a table:

pixeltable/catalog/table_version.py

@@ -678,12 +678,12 @@ class TableVersion:
         return result
 
     def update(
-        self, value_spec: dict[str, Any], where: Optional['exprs.Predicate'] = None, cascade: bool = True
+        self, value_spec: dict[str, Any], where: Optional['exprs.Expr'] = None, cascade: bool = True
     ) -> UpdateStatus:
         """Update rows in this TableVersionPath.
         Args:
             value_spec: a list of (column, value) pairs specifying the columns to update and their new values.
-            where: a Predicate to filter rows to update.
+            where: a predicate to filter rows to update.
             cascade: if True, also update all computed columns that transitively depend on the updated columns,
                 including within views.
         """
@@ -694,8 +694,8 @@ class TableVersion:
 
         update_spec = self._validate_update_spec(value_spec, allow_pk=False, allow_exprs=True)
         if where is not None:
-            if not isinstance(where, exprs.Predicate):
-                raise excs.Error(f"'where' argument must be a Predicate, got {type(where)}")
+            if not isinstance(where, exprs.Expr):
+                raise excs.Error(f"'where' argument must be a predicate, got {type(where)}")
             analysis_info = Planner.analyze(self.path, where)
             # for now we require that the updated rows can be identified via SQL, rather than via a Python filter
             if analysis_info.filter is not None:
@@ -757,7 +757,7 @@ class TableVersion:
 
     def _update(
             self, conn: sql.engine.Connection, update_targets: dict[Column, 'pixeltable.exprs.Expr'],
-            where_clause: Optional['pixeltable.exprs.Predicate'] = None, cascade: bool = True,
+            where_clause: Optional['pixeltable.exprs.Expr'] = None, cascade: bool = True,
             show_progress: bool = True
     ) -> UpdateStatus:
         from pixeltable.plan import Planner
@@ -789,8 +789,6 @@ class TableVersion:
                 raise excs.Error(f'Column {col_name} is computed and cannot be updated')
             if col.is_pk and not allow_pk:
                 raise excs.Error(f'Column {col_name} is a primary key column and cannot be updated')
-            if col.col_type.is_media_type():
-                raise excs.Error(f'Column {col_name} has type image/video/audio/document and cannot be updated')
 
             # make sure that the value is compatible with the column type
             try:
@@ -848,17 +846,17 @@ class TableVersion:
         result.cols_with_excs = list(dict.fromkeys(result.cols_with_excs).keys())  # remove duplicates
         return result
 
-    def delete(self, where: Optional['exprs.Predicate'] = None) -> UpdateStatus:
+    def delete(self, where: Optional['exprs.Expr'] = None) -> UpdateStatus:
         """Delete rows in this table.
         Args:
-            where: a Predicate to filter rows to delete.
+            where: a predicate to filter rows to delete.
         """
         assert self.is_insertable()
-        from pixeltable.exprs import Predicate
+        from pixeltable.exprs import Expr
         from pixeltable.plan import Planner
         if where is not None:
-            if not isinstance(where, Predicate):
-                raise excs.Error(f"'where' argument must be a Predicate, got {type(where)}")
+            if not isinstance(where, Expr):
+                raise excs.Error(f"'where' argument must be a predicate, got {type(where)}")
             analysis_info = Planner.analyze(self.path, where)
             # for now we require that the updated rows can be identified via SQL, rather than via a Python filter
             if analysis_info.filter is not None:
@@ -872,11 +870,11 @@ class TableVersion:
         return status
 
     def propagate_delete(
-            self, where: Optional['exprs.Predicate'], base_versions: List[Optional[int]],
+            self, where: Optional['exprs.Expr'], base_versions: List[Optional[int]],
             conn: sql.engine.Connection, timestamp: float) -> int:
         """Delete rows in this table and propagate to views.
         Args:
-            where: a Predicate to filter rows to delete.
+            where: a predicate to filter rows to delete.
         Returns:
             number of deleted rows
         """

pixeltable/catalog/view.py

@@ -51,7 +51,7 @@ class View(Table):
     @classmethod
     def create(
             cls, dir_id: UUID, name: str, base: TableVersionPath, schema: Dict[str, Any],
-            predicate: 'pxt.exprs.Predicate', is_snapshot: bool, num_retained_versions: int, comment: str,
+            predicate: 'pxt.exprs.Expr', is_snapshot: bool, num_retained_versions: int, comment: str,
             iterator_cls: Optional[Type[ComponentIterator]], iterator_args: Optional[Dict]
     ) -> View:
         columns = cls._create_columns(schema)
@@ -213,5 +213,5 @@ class View(Table):
     ) -> UpdateStatus:
         raise excs.Error(f'{self.display_name()} {self._name!r}: cannot insert into view')
 
-    def delete(self, where: Optional['pixeltable.exprs.Predicate'] = None) -> UpdateStatus:
+    def delete(self, where: Optional['pixeltable.exprs.Expr'] = None) -> UpdateStatus:
         raise excs.Error(f'{self.display_name()} {self._name!r}: cannot delete from view')

pixeltable/dataframe.py

@@ -153,7 +153,7 @@ class DataFrame:
         self,
         tbl: catalog.TableVersionPath,
         select_list: Optional[List[Tuple[exprs.Expr, Optional[str]]]] = None,
-        where_clause: Optional[exprs.Predicate] = None,
+        where_clause: Optional[exprs.Expr] = None,
         group_by_clause: Optional[List[exprs.Expr]] = None,
         grouping_tbl: Optional[catalog.TableVersion] = None,
         order_by_clause: Optional[List[Tuple[exprs.Expr, bool]]] = None,  # List[(expr, asc)]
@@ -530,7 +530,11 @@ class DataFrame:
             limit=self.limit_val,
         )
 
-    def where(self, pred: exprs.Predicate) -> DataFrame:
+    def where(self, pred: exprs.Expr) -> DataFrame:
+        if not isinstance(pred, exprs.Expr):
+            raise excs.Error(f'Where() requires a Pixeltable expression, but instead got {type(pred)}')
+        if not pred.col_type.is_bool_type():
+            raise excs.Error(f'Where(): expression needs to return bool, but instead returns {pred.col_type}')
         return DataFrame(
             self.tbl,
             select_list=self.select_list,
@@ -628,12 +632,9 @@ class DataFrame:
     def __getitem__(self, index: object) -> DataFrame:
         """
         Allowed:
-        - [<Predicate>]: filter operation
         - [List[Expr]]/[Tuple[Expr]]: setting the select list
         - [Expr]: setting a single-col select list
         """
-        if isinstance(index, exprs.Predicate):
-            return self.where(index)
         if isinstance(index, tuple):
             index = list(index)
         if isinstance(index, exprs.Expr):
@@ -668,7 +669,7 @@ class DataFrame:
         tbl = catalog.TableVersionPath.from_dict(d['tbl'])
         select_list = [(exprs.Expr.from_dict(e), name) for e, name in d['select_list']] \
             if d['select_list'] is not None else None
-        where_clause = exprs.Predicate.from_dict(d['where_clause']) \
+        where_clause = exprs.Expr.from_dict(d['where_clause']) \
             if d['where_clause'] is not None else None
         group_by_clause = [exprs.Expr.from_dict(e) for e in d['group_by_clause']] \
             if d['group_by_clause'] is not None else None

pixeltable/exec/expr_eval_node.py

@@ -50,7 +50,14 @@ class ExprEvalNode(ExecNode):
 
     def _open(self) -> None:
         warnings.simplefilter("ignore", category=TqdmWarning)
-        if self.ctx.show_pbar:
+        # This is a temporary hack. When B-tree indices on string columns were implemented (via computed columns
+        # that invoke the `BtreeIndex.str_filter` udf), it resulted in frivolous progress bars appearing on every
+        # insertion. This special-cases the `str_filter` call to suppress the corresponding progress bar.
+        # TODO(aaron-siegel) Remove this hack once we clean up progress bars more generally.
+        is_str_filter_node = all(
+            isinstance(expr, exprs.FunctionCall) and expr.fn.name == 'str_filter' for expr in self.output_exprs
+        )
+        if self.ctx.show_pbar and not is_str_filter_node:
             self.pbar = tqdm(
                 total=len(self.target_exprs) * self.ctx.num_rows,
                 desc='Computing cells',

pixeltable/exec/sql_scan_node.py

@@ -19,7 +19,7 @@ class SqlScanNode(ExecNode):
     def __init__(
             self, tbl: catalog.TableVersionPath, row_builder: exprs.RowBuilder,
             select_list: Iterable[exprs.Expr],
-            where_clause: Optional[exprs.Expr] = None, filter: Optional[exprs.Predicate] = None,
+            where_clause: Optional[exprs.Expr] = None, filter: Optional[exprs.Expr] = None,
             order_by_items: Optional[List[Tuple[exprs.Expr, bool]]] = None,
             limit: int = 0, set_pk: bool = False, exact_version_only: Optional[List[catalog.TableVersion]] = None
     ):

pixeltable/exprs/__init__.py

@@ -17,7 +17,6 @@ from .json_mapper import JsonMapper
 from .json_path import RELATIVE_PATH_ROOT, JsonPath
 from .literal import Literal
 from .object_ref import ObjectRef
-from .predicate import Predicate
 from .row_builder import RowBuilder, ColumnSlotIdx, ExecProfile
 from .rowid_ref import RowidRef
 from .similarity_expr import SimilarityExpr

pixeltable/exprs/comparison.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Optional, List, Any, Dict, Tuple
+from typing import Optional, List, Any, Dict
 
 import sqlalchemy as sql
 
@@ -9,15 +9,15 @@ from .data_row import DataRow
 from .expr import Expr
 from .globals import ComparisonOperator
 from .literal import Literal
-from .predicate import Predicate
 from .row_builder import RowBuilder
 import pixeltable.exceptions as excs
 import pixeltable.index as index
+import pixeltable.type_system as ts
 
 
-class Comparison(Predicate):
+class Comparison(Expr):
     def __init__(self, operator: ComparisonOperator, op1: Expr, op2: Expr):
-        super().__init__()
+        super().__init__(ts.BoolType())
         self.operator = operator
 
         # if this is a comparison of a column to a literal (ie, could be used as a search argument in an index lookup),
@@ -50,7 +50,7 @@ class Comparison(Predicate):
     def _equals(self, other: Comparison) -> bool:
         return self.operator == other.operator
 
-    def _id_attrs(self) -> List[Tuple[str, Any]]:
+    def _id_attrs(self) -> list[tuple[str, Any]]:
         return super()._id_attrs() + [('operator', self.operator.value)]
 
     @property

pixeltable/exprs/compound_predicate.py

@@ -1,20 +1,20 @@
 from __future__ import annotations
-from typing import Optional, List, Any, Dict, Tuple, Callable
+
 import operator
+from typing import Optional, List, Any, Dict, Callable
 
 import sqlalchemy as sql
 
+from .data_row import DataRow
 from .expr import Expr
 from .globals import LogicalOperator
-from .predicate import Predicate
-from .data_row import DataRow
 from .row_builder import RowBuilder
-import pixeltable.catalog as catalog
+import pixeltable.type_system as ts
 
 
-class CompoundPredicate(Predicate):
-    def __init__(self, operator: LogicalOperator, operands: List[Predicate]):
-        super().__init__()
+class CompoundPredicate(Expr):
+    def __init__(self, operator: LogicalOperator, operands: List[Expr]):
+        super().__init__(ts.BoolType())
         self.operator = operator
         # operands are stored in self.components
         if self.operator == LogicalOperator.NOT:
@@ -22,7 +22,7 @@ class CompoundPredicate(Predicate):
             self.components = operands
         else:
             assert len(operands) > 1
-            self.operands: List[Predicate] = []
+            self.operands: List[Expr] = []
             for operand in operands:
                 self._merge_operand(operand)
 
@@ -34,14 +34,14 @@ class CompoundPredicate(Predicate):
         return f' {self.operator} '.join([f'({e})' for e in self.components])
 
     @classmethod
-    def make_conjunction(cls, operands: List[Predicate]) -> Optional[Predicate]:
+    def make_conjunction(cls, operands: List[Expr]) -> Optional[Expr]:
         if len(operands) == 0:
             return None
         if len(operands) == 1:
             return operands[0]
         return CompoundPredicate(LogicalOperator.AND, operands)
 
-    def _merge_operand(self, operand: Predicate) -> None:
+    def _merge_operand(self, operand: Expr) -> None:
         """
         Merge this operand, if possible, otherwise simply record it.
         """
@@ -55,11 +55,11 @@ class CompoundPredicate(Predicate):
     def _equals(self, other: CompoundPredicate) -> bool:
         return self.operator == other.operator
 
-    def _id_attrs(self) -> List[Tuple[str, Any]]:
+    def _id_attrs(self) -> list[tuple[str, Any]]:
         return super()._id_attrs() + [('operator', self.operator.value)]
 
     def split_conjuncts(
-            self, condition: Callable[[Predicate], bool]) -> Tuple[List[Predicate], Optional[Predicate]]:
+            self, condition: Callable[[Expr], bool]) -> tuple[list[Expr], Optional[Expr]]:
         if self.operator == LogicalOperator.OR or self.operator == LogicalOperator.NOT:
             return super().split_conjuncts(condition)
         matches = [op for op in self.components if condition(op)]

pixeltable/exprs/expr.py

@@ -518,6 +518,38 @@ class Expr(abc.ABC):
             return ArithmeticExpr(op, self, Literal(other))  # type: ignore[arg-type]
         raise TypeError(f'Other must be Expr or literal: {type(other)}')
 
+    def __and__(self, other: object) -> Expr:
+        if not isinstance(other, Expr):
+            raise TypeError(f'Other needs to be an expression: {type(other)}')
+        if not other.col_type.is_bool_type():
+            raise TypeError(f'Other needs to be an expression that returns a boolean: {other.col_type}')
+        from .compound_predicate import CompoundPredicate
+        return CompoundPredicate(LogicalOperator.AND, [self, other])
+
+    def __or__(self, other: object) -> Expr:
+        if not isinstance(other, Expr):
+            raise TypeError(f'Other needs to be an expression: {type(other)}')
+        if not other.col_type.is_bool_type():
+            raise TypeError(f'Other needs to be an expression that returns a boolean: {other.col_type}')
+        from .compound_predicate import CompoundPredicate
+        return CompoundPredicate(LogicalOperator.OR, [self, other])
+
+    def __invert__(self) -> Expr:
+        from .compound_predicate import CompoundPredicate
+        return CompoundPredicate(LogicalOperator.NOT, [self])
+
+    def split_conjuncts(
+            self, condition: Callable[[Expr], bool]) -> tuple[list[Expr], Optional[Expr]]:
+        """
+        Returns clauses of a conjunction that meet condition in the first element.
+        The second element contains remaining clauses, rolled into a conjunction.
+        """
+        assert self.col_type.is_bool_type()  # only valid for predicates
+        if condition(self):
+            return [self], None
+        else:
+            return [], self
+
     def _make_applicator_function(self, fn: Callable, col_type: Optional[ts.ColumnType]) -> 'pixeltable.func.Function':
         """
         Creates a unary pixeltable `Function` that encapsulates a python `Callable`. The result type of

pixeltable/exprs/in_predicate.py

@@ -5,20 +5,20 @@ from typing import Optional, List, Any, Dict, Tuple, Iterable
 import sqlalchemy as sql
 
 import pixeltable.exceptions as excs
+import pixeltable.type_system as ts
 from .data_row import DataRow
 from .expr import Expr
-from .predicate import Predicate
 from .row_builder import RowBuilder
 
 
-class InPredicate(Predicate):
+class InPredicate(Expr):
     """Predicate corresponding to the SQL IN operator."""
 
     def __init__(self, lhs: Expr, value_set_literal: Optional[Iterable] = None, value_set_expr: Optional[Expr] = None):
         assert (value_set_literal is None) != (value_set_expr is None)
         if not lhs.col_type.is_scalar_type():
             raise excs.Error(f'isin(): only supported for scalar types, not {lhs.col_type}')
-        super().__init__()
+        super().__init__(ts.BoolType())
 
         self.value_list: Optional[list] = None  # only contains values of the correct type
         if value_set_expr is not None:

pixeltable/exprs/is_null.py

@@ -1,18 +1,18 @@
 from __future__ import annotations
+
 from typing import Optional, List, Dict
 
 import sqlalchemy as sql
 
-from .predicate import Predicate
-from .expr import Expr
+import pixeltable.type_system as ts
 from .data_row import DataRow
+from .expr import Expr
 from .row_builder import RowBuilder
-import pixeltable.catalog as catalog
 
 
-class IsNull(Predicate):
+class IsNull(Expr):
     def __init__(self, e: Expr):
-        super().__init__()
+        super().__init__(ts.BoolType())
         self.components = [e]
         self.id = self._create_id()
 

pixeltable/func/aggregate_function.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 
 import abc
-import importlib
 import inspect
-from typing import Optional, Any, Type, List, Dict, Callable
-import itertools
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Type
 
 import pixeltable.exceptions as excs
 import pixeltable.type_system as ts
+
 from .function import Function
-from .signature import Signature, Parameter
 from .globals import validate_symbol_path
+from .signature import Parameter, Signature
+
+if TYPE_CHECKING:
+    import pixeltable
 
 
 class Aggregator(abc.ABC):
@@ -40,6 +42,7 @@ class AggregateFunction(Function):
         self.requires_order_by = requires_order_by
         self.allows_std_agg = allows_std_agg
         self.allows_window = allows_window
+        self.__doc__ = aggregator_class.__doc__
 
         # our signature is the signature of 'update', but without self,
         # plus the parameters of 'init' as keyword-only parameters
@@ -135,6 +138,9 @@ class AggregateFunction(Function):
                     f'expression'
                 )
 
+    def __repr__(self) -> str:
+        return f'<Pixeltable Aggregator {self.name}>'
+
 
 def uda(
         *,

pixeltable/func/callable_function.py

@@ -25,6 +25,7 @@ class CallableFunction(Function):
         self.py_fn = py_fn
         self.self_name = self_name
         self.batch_size = batch_size
+        self.__doc__ = py_fn.__doc__
         super().__init__(signature, self_path=self_path)
 
     @property
@@ -113,3 +114,6 @@ class CallableFunction(Function):
                         f'{self.display_name}(): '
                         f'parameter {param.name} must be a constant value, not a Pixeltable expression'
                     )
+
+    def __repr__(self) -> str:
+        return f'<Pixeltable UDF {self.name}>'

pixeltable/func/function_registry.py

@@ -66,6 +66,8 @@ class FunctionRegistry:
     #             self.module_fns[fn_path] = obj
 
     def register_function(self, fqn: str, fn: Function) -> None:
+        if fqn in self.module_fns:
+            raise excs.Error(f'A UDF with that name already exists: {fqn}')
         self.module_fns[fqn] = fn
 
     def list_functions(self) -> List[Function]:

pixeltable/functions/globals.py

@@ -1,4 +1,4 @@
-from typing import Union
+from typing import Optional, Union
 
 import pixeltable.func as func
 import pixeltable.type_system as ts
@@ -14,6 +14,7 @@ def cast(expr: exprs.Expr, target_type: ts.ColumnType) -> exprs.Expr:
 
 @func.uda(update_types=[ts.IntType()], value_type=ts.IntType(), allows_window=True, requires_order_by=False)
 class sum(func.Aggregator):
+    """Sums the selected integers or floats."""
     def __init__(self):
         self.sum: Union[int, float] = 0
 
@@ -38,6 +39,40 @@ class count(func.Aggregator):
         return self.count
 
 
+@func.uda(update_types=[ts.FloatType()], value_type=ts.FloatType(nullable=True), allows_window=True, requires_order_by=False)
+class max(func.Aggregator):
+    def __init__(self):
+        self.val = None
+
+    def update(self, val: Optional[float]) -> None:
+        if val is not None:
+            if self.val is None:
+                self.val = val
+            else:
+                import builtins
+                self.val = builtins.max(self.val, val)
+
+    def value(self) -> Optional[float]:
+        return self.val
+
+
+@func.uda(update_types=[ts.FloatType()], value_type=ts.FloatType(nullable=True), allows_window=True, requires_order_by=False)
+class min(func.Aggregator):
+    def __init__(self):
+        self.val = None
+
+    def update(self, val: Optional[float]) -> None:
+        if val is not None:
+            if self.val is None:
+                self.val = val
+            else:
+                import builtins
+                self.val = builtins.min(self.val, val)
+
+    def value(self) -> Optional[float]:
+        return self.val
+
+
 @func.uda(update_types=[ts.IntType()], value_type=ts.FloatType(), allows_window=False, requires_order_by=False)
 class mean(func.Aggregator):
     def __init__(self):

pixeltable/functions/huggingface.py

@@ -1,3 +1,12 @@
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs)
+that wrap various models from the Hugging Face `transformers` package.
+
+These UDFs will cause Pixeltable to invoke the relevant models locally. In order to use them, you must
+first `pip install transformers` (or in some cases, `sentence-transformers`, as noted in the specific
+UDFs).
+"""
+
 from typing import Callable, TypeVar, Optional, Any
 
 import PIL.Image
@@ -13,15 +22,39 @@ from pixeltable.utils.code import local_public_names
 
 @pxt.udf(batch_size=32, return_type=ts.ArrayType((None,), dtype=ts.FloatType()))
 def sentence_transformer(
-    sentences: Batch[str], *, model_id: str, normalize_embeddings: bool = False
+    sentence: Batch[str], *, model_id: str, normalize_embeddings: bool = False
 ) -> Batch[np.ndarray]:
-    """Runs the specified sentence transformer model."""
+    """
+    Runs the specified pretrained sentence-transformers model. `model_id` should be a pretrained model, as described
+    in the [Sentence Transformers Pretrained Models](https://sbert.net/docs/sentence_transformer/pretrained_models.html)
+    documentation.
+
+    __Requirements:__
+
+    - `pip install sentence-transformers`
+
+    Args:
+        sentence: The sentence to embed.
+        model_id: The pretrained model to use for the encoding.
+        normalize_embeddings: If `True`, normalizes embeddings to length 1; see the
+            [Sentence Transformers API Docs](https://sbert.net/docs/package_reference/sentence_transformer/SentenceTransformer.html)
+            for more details
+
+    Returns:
+        An array containing the output of the embedding model.
+
+    Examples:
+        Add a computed column that applies the model `all-mpnet-base-2` to an existing Pixeltable column `tbl.sentence`
+        of the table `tbl`:
+
+        >>> tbl['result'] = sentence_transformer(tbl.sentence, model_id='all-mpnet-base-v2')
+    """
     env.Env.get().require_package('sentence_transformers')
     from sentence_transformers import SentenceTransformer
 
     model = _lookup_model(model_id, SentenceTransformer)
 
-    array = model.encode(sentences, normalize_embeddings=normalize_embeddings)
+    array = model.encode(sentence, normalize_embeddings=normalize_embeddings)
     return [array[i] for i in range(array.shape[0])]
 
 
@@ -49,7 +82,32 @@ def sentence_transformer_list(sentences: list, *, model_id: str, normalize_embed
 
 @pxt.udf(batch_size=32)
 def cross_encoder(sentences1: Batch[str], sentences2: Batch[str], *, model_id: str) -> Batch[float]:
-    """Runs the specified cross-encoder model."""
+    """
+    Runs the specified cross-encoder model to compute similarity scores for pairs of sentences.
+    `model_id` should be a pretrained model, as described in the
+    [Cross-Encoder Pretrained Models](https://www.sbert.net/docs/cross_encoder/pretrained_models.html)
+    documentation.
+
+    __Requirements:__
+
+    - `pip install sentence-transformers`
+
+    Parameters:
+        sentences1: The first sentence to be paired.
+        sentences2: The second sentence to be paired.
+        model_id: The identifier of the cross-encoder model to use.
+
+    Returns:
+        The similarity score between the inputs.
+
+    Examples:
+        Add a computed column that applies the model `ms-marco-MiniLM-L-4-v2` to the sentences in
+        columns `tbl.sentence1` and `tbl.sentence2`:
+
+        >>> tbl['result'] = sentence_transformer(
+                tbl.sentence1, tbl.sentence2, model_id='ms-marco-MiniLM-L-4-v2'
+            )
+    """
     env.Env.get().require_package('sentence_transformers')
     from sentence_transformers import CrossEncoder