Add some documentation + iterator for result class

Author: Josef-Haupt

src/birdnet/acoustic/inference/core/encoding/encoding_result.py

@@ -72,6 +72,11 @@ def __init__(
 
   @property
   def memory_size_mb(self) -> float:
+    """Return the total result memory usage including embeddings buffers.
+
+    Returns:
+      float: Memory size in megabytes.
+    """
     return super().memory_size_mb + (
       (
         self._embeddings.nbytes
@@ -83,21 +88,46 @@ def memory_size_mb(self) -> float:
 
   @property
   def embeddings(self) -> np.ndarray:
+    """Return the raw embedding tensor produced by the encoder.
+
+    Returns:
+      np.ndarray: Embeddings with shape `(n_inputs, n_segments, emb_dim)`.
+    """
     return self._embeddings
 
   @property
   def embeddings_masked(self) -> np.ndarray:
+    """Return the mask that marks relevant segments across files.
+
+    Returns:
+      np.ndarray: Boolean mask of the same shape as `embeddings`.
+    """
     return self._embeddings_masked
 
   @property
-  def emd_dim(self) -> int:
+  def emb_dim(self) -> int:
+    """Return the embedding dimensionality.
+
+    Returns:
+      int: Number of coefficients per embedding vector.
+    """
     return self._embeddings.shape[-1]
 
   @property
   def max_n_segments(self) -> int:
+    """Return the maximum segment count reserved per input.
+
+    Returns:
+      int: Number of overlapping windows available per file.
+    """
     return self._embeddings.shape[1]
 
   def to_structured_array(self) -> np.ndarray:
+    """Convert the embeddings and timing metadata into a structured array.
+
+    Returns:
+      np.ndarray: Array with fields for input path, start/end times, and embedding.
+    """
     valid_mask_per_segment = ~(self._embeddings_masked).all(axis=2)
     valid_file_idx, valid_seg_idx = np.where(valid_mask_per_segment)
     n_embeddings = len(valid_file_idx)
@@ -108,7 +138,7 @@ def to_structured_array(self) -> np.ndarray:
       (VAR_INPUT, self._input_dtype),
       (VAR_START_TIME, self._input_durations.dtype),
       (VAR_END_TIME, self._input_durations.dtype),
-      (VAR_EMBEDDING, self._embeddings.dtype, self.emd_dim),
+      (VAR_EMBEDDING, self._embeddings.dtype, self.emb_dim),
     ]
 
     structured_array = np.empty(n_embeddings, dtype=dtype)
@@ -154,6 +184,11 @@ def to_structured_array(self) -> np.ndarray:
     return structured_array
 
   def to_arrow_table(self) -> pa.Table:
+    """Produce a PyArrow table that serializes each embedding with timing metadata.
+
+    Returns:
+      pa.Table: Table containing dictionary-encoded inputs and embeddings lists.
+    """
     import pyarrow as pa
 
     structured = self.to_structured_array()
@@ -194,7 +229,7 @@ def to_arrow_table(self) -> pa.Table:
       "model_fmax": str(self._model_fmax[0]),
       "model_sr": str(self._model_sr[0]),
       "model_precision": str(self._model_precision[0]),
-      "embedding_dim": str(self.emd_dim),
+      "embedding_dim": str(self.emb_dim),
     }
     schema_with_metadata = pa.schema(fields, metadata=metadata)
     table = pa.table(arrow_arrays, schema=schema_with_metadata)
@@ -208,6 +243,14 @@ def to_csv(
     buffer_size_kb: int = 1024,
     silent: bool = False,
   ) -> None:
+    """Dump the structured embeddings to a CSV file for downstream analysis.
+
+    Args:
+      path: File path where the CSV will be written (must end with .csv).
+      encoding: Text encoding for the output file.
+      buffer_size_kb: Buffer size used when writing the file.
+      silent: Suppress progress messages when True.
+    """
     if not silent:
       print("Preparing CSV export...")  # noqa: T201
 
@@ -264,6 +307,11 @@ def to_csv(
           f.writelines(block)
 
   def unprocessable_inputs(self) -> np.ndarray:
+    """Return the indices of inputs that could not be processed.
+
+    Returns:
+      np.ndarray: Boolean mask or indices for skipped inputs.
+    """
     return self._unprocessable_inputs
 
   def _get_extra_save_data(self) -> dict[str, np.ndarray]:
@@ -322,9 +370,6 @@ def _input_dtype(self) -> type:
     # -> pointer to python string is more efficient
     return object
 
-  def _format_input_for_csv(self, input_value: str) -> str:
-    return f'"{input_value}"'
-
 
 class AcousticDataEncodingResult(AcousticEncodingResultBase):
   def __init__(

src/birdnet/acoustic/inference/core/prediction/prediction_result.py

@@ -380,9 +380,6 @@ def _input_dtype(self) -> type:
     # -> pointer to python string is more efficient
     return object
 
-  def _format_input_for_csv(self, input_value: str) -> str:
-    return f'"{input_value}"'
-
 
 class AcousticDataPredictionResult(AcousticPredictionResultBase):
   def __init__(
@@ -418,6 +415,3 @@ def __init__(
       model_precision=model_precision,
       model_version=model_version,
     )
-
-  def _format_input_for_csv(self, input_value: Any) -> str:  # noqa: ANN401
-    return f"{input_value}"

src/birdnet/acoustic/inference/core/result_base.py

@@ -3,6 +3,7 @@
 import os
 import time
 from abc import ABC, abstractmethod
+from collections.abc import Iterable
 from multiprocessing import current_process
 from pathlib import Path
 from threading import current_thread
@@ -36,6 +37,8 @@
 
 
 class AcousticResultBase(ResultBase):
+  """Base container for shared acoustic model result metadata and helpers."""
+
   def __init__(
     self,
     model_path: Path,
@@ -50,6 +53,21 @@ def __init__(
     model_fmax: int,
     model_sr: int,
   ) -> None:
+    """Capture model metadata plus per-input timing information.
+
+    Args:
+      model_path: Path to the acoustic model binary used for inference.
+      model_version: Version identifier of the model.
+      model_precision: Precision string (float16/float32) backed by the model.
+      inputs: Typed array of inputs (paths or indices) that were encoded/predicted.
+      input_durations: Duration of each input in seconds.
+      segment_duration_s: Segment length used by the inference pipeline.
+      overlap_duration_s: Overlap between consecutive segments.
+      speed: Speed multiplier applied to the inputs during preprocessing.
+      model_fmin: Lower frequency bound used by the model.
+      model_fmax: Upper frequency bound used by the model.
+      model_sr: Sampling rate that the model expects.
+    """
     super().__init__(
       model_path=model_path,
       model_version=model_version,
@@ -79,38 +97,47 @@ def _input_dtype(self) -> type:
 
   @property
   def segment_duration_s(self) -> float:
+    """Segment duration as configured on the inference pipeline."""
     return float(self._segment_duration_s[0])
 
   @property
   def overlap_duration_s(self) -> float:
+    """Overlap duration between sliding windows in seconds."""
     return float(self._overlap_duration_s[0])
 
   @property
   def speed(self) -> float:
+    """Speed multiplier that was applied to the inputs."""
     return float(self._speed[0])
 
   @property
   def inputs(self) -> np.ndarray:
+    """Identifiers for each input processed by the result."""
     return self._inputs
 
   @property
   def n_inputs(self) -> int:
+    """Number of inputs in the result payload."""
     return self._inputs.shape[0]
 
   @property
   def input_durations(self) -> np.ndarray:
+    """Durations of each input in seconds."""
     return self._input_durations
 
   @property
   def model_fmin(self) -> int:
+    """Lower bound of the model's bandpass filter."""
     return int(self._model_fmin[0])
 
   @property
   def model_fmax(self) -> int:
+    """Upper bound of the model's bandpass filter."""
     return int(self._model_fmax[0])
 
   @property
   def model_sr(self) -> int:
+    """Sampling rate expected by the model."""
     return int(self._model_sr[0])
 
   def _get_extra_save_data(self) -> dict[str, np.ndarray]:
@@ -138,6 +165,11 @@ def _set_extra_load_data(cls, data: dict[str, np.ndarray]) -> None:
 
   @property
   def memory_size_mb(self) -> float:
+    """Memory usage for the base result metadata.
+
+    Returns:
+      float: Memory used by metadata buffers in megabytes.
+    """
     return super().memory_size_mb + (
       (
         self._inputs.nbytes
@@ -169,6 +201,7 @@ def to_csv(
   ) -> None: ...
 
   def to_dataframe(self) -> pd.DataFrame:
+    """Convert the structured array into a pandas DataFrame."""
     import pandas as pd
 
     structured = self.to_structured_array()
@@ -192,6 +225,7 @@ def to_parquet(
     compression_level: int | None = None,
     silent: bool = False,
   ) -> None:
+    """Write the contents to disk as an Arrow Parquet file."""
     import pyarrow.parquet as pq
 
     path = Path(path)
@@ -219,6 +253,10 @@ def to_parquet(
       compression_ratio = original_size / file_size if file_size > 0 else 0
       print(f"Parquet file: {file_size:.1f} MB (compression: {compression_ratio:.1f}x)")  # noqa: T201
 
+  def __iter__(self) -> Iterable[np.ndarray]:
+    """Iterate over the structured records via the iterator protocol."""
+    yield from self.to_structured_array()
+
 
 class SessionBase(ABC):
   def __init__(self) -> None:

src/birdnet/acoustic/inference/session.py

@@ -3,8 +3,6 @@
 import shutil
 from abc import ABC
 from collections.abc import Callable, Collection, Iterable
-from contextlib import contextmanager, suppress
-from multiprocessing import shared_memory
 from pathlib import Path
 from typing import Any, ContextManager, Generic, Literal, Self, cast
 
@@ -35,7 +33,6 @@
   AcousticDataPredictionResult,
   AcousticFilePredictionResult,
 )
-from birdnet.acoustic.inference.core.shm import RingField, create_shm_ring
 from birdnet.acoustic.inference.encoding_strategy import (
   EncodingStrategy,
 )
@@ -50,7 +47,7 @@
 from birdnet.acoustic.inference.strategy import InferenceStrategyBase
 from birdnet.core.backends import VersionedAcousticBackendProtocol
 from birdnet.core.base import SessionBase
-from birdnet.globals import ACOUSTIC_MODEL_VERSIONS, WRITABLE_FLAG
+from birdnet.globals import ACOUSTIC_MODEL_VERSIONS
 
 
 class AcousticSessionBase(
@@ -180,7 +177,7 @@ def end(self) -> None:
     assert self._resources is not None
     self._resources.processing_resources.end_event.set()
 
-  def __exit__(self, *args) -> None:
+  def __exit__(self, *args) -> None:  # noqa: ANN002
     assert self._is_initialized
 
     assert self._resources is not None

src/birdnet/acoustic/models/base.py

@@ -12,9 +12,8 @@
 from birdnet.acoustic.inference.session import (
   AcousticEncodingSession,
   AcousticPredictionSession,
-  AcousticSessionBase,
 )
-from birdnet.core.base import ModelBase, ResultBase
+from birdnet.core.base import ModelBase
 from birdnet.globals import ACOUSTIC_MODEL_VERSIONS
 
 
@@ -29,12 +28,22 @@ def __init__(
 
   @classmethod
   @abstractmethod
-  def get_version(cls) -> ACOUSTIC_MODEL_VERSIONS: ...
+  def get_version(cls) -> ACOUSTIC_MODEL_VERSIONS:  # noqa: ANN002
+    """Return the string label that identifies the acoustic model version.
+
+    Returns:
+      ACOUSTIC_MODEL_VERSIONS: Registered enum constant for the supported version.
+    """
+    ...
 
   @abstractmethod
   def predict(self, *args, **kwargs) -> AcousticPredictionResultBase:  # noqa: ANN002, ANN003
     ...
 
+  @abstractmethod
+  def predict_arrays(self, *args, **kwargs) -> AcousticPredictionResultBase:  # noqa: ANN002, ANN003
+    ...
+
   @abstractmethod
   def predict_session(self, *args, **kwargs) -> AcousticPredictionSession:  # noqa: ANN002, ANN003
     ...
@@ -43,6 +52,10 @@ def predict_session(self, *args, **kwargs) -> AcousticPredictionSession:  # noqa
   def encode(self, *args, **kwargs) -> AcousticEncodingResultBase:  # noqa: ANN002, ANN003
     ...
 
+  @abstractmethod
+  def encode_arrays(self, *args, **kwargs) -> AcousticEncodingResultBase:  # noqa: ANN002, ANN003
+    ...
+
   @abstractmethod
   def encode_session(self, *args, **kwargs) -> AcousticEncodingSession:  # noqa: ANN002, ANN003
     ...