Skip to content

api-reference.md

Latest commit

 

History

History
305 lines (238 loc) · 6.62 KB

api-reference.md

File metadata and controls

305 lines (238 loc) · 6.62 KB

API Reference

Complete API documentation for WhiteBoxAI SDK.

WhiteBoxAI Client

Main client for interacting with the WhiteBoxAI API.

Constructor

WhiteBoxAI(
    api_key: str = None,
    base_url: str = "https://api.whiteboxai.io",
    timeout: int = 30,
    max_retries: int = 3,
    enable_offline: bool = False,
    offline_dir: str = "./whiteboxai_offline",
    offline_max_queue_size: int = 10000,
    offline_auto_sync: bool = False,
    offline_sync_interval: int = 60,
    enable_caching: bool = False,
    cache_ttl: int = 3600,
    cache_max_size: int = 1000,
    enable_privacy_filters: bool = False,
    enable_sampling: bool = False,
    sampling_rate: float = 1.0
)

Parameters:

  • api_key (str): API key for authentication. Can be set via EXPLAINAI_API_KEY env var
  • base_url (str): Base URL for API endpoint
  • timeout (int): Request timeout in seconds
  • max_retries (int): Maximum number of retry attempts
  • enable_offline (bool): Enable offline mode with persistent queue
  • offline_dir (str): Directory for offline queue storage
  • offline_max_queue_size (int): Maximum queued operations (0 = unlimited)
  • offline_auto_sync (bool): Enable automatic background sync
  • offline_sync_interval (int): Sync interval in seconds
  • enable_caching (bool): Enable local caching
  • cache_ttl (int): Cache time-to-live in seconds
  • cache_max_size (int): Maximum cache entries
  • enable_privacy_filters (bool): Enable PII detection and masking
  • enable_sampling (bool): Enable prediction sampling
  • sampling_rate (float): Sampling rate (0.0-1.0)

Resources

client.models          # Models resource
client.predictions     # Predictions resource
client.explanations    # Explanations resource
client.drift           # Drift detection resource
client.alerts          # Alerts resource

Methods

Offline Mode

get_offline_status() -> dict

Get offline queue status.

Returns: Dictionary with queue_size, last_sync_time, failed_count

sync_offline_queue() -> dict

Manually sync offline queue.

Returns: Dictionary with synced and failed counts

cleanup_offline_queue(older_than_days: int = 7)

Remove old operations from queue.

ModelMonitor

Simplified monitoring interface.

Constructor

ModelMonitor(
    client: WhiteBoxAI,
    model_id: int = None,
    sampling_rate: float = 1.0,
    enable_explanations: bool = False
)

Methods

register_model(
    name: str,
    model_type: str,
    framework: str = None,
    version: str = None,
    **metadata
) -> int

Register a new model.

Parameters:

  • name (str): Model name
  • model_type (str): Type (classification, regression, etc.)
  • framework (str): Framework name (sklearn, pytorch, etc.)
  • version (str): Model version
  • **metadata: Additional metadata

Returns: Model ID

log_prediction(
    inputs: dict,
    output: dict,
    ground_truth: Any = None,
    explanation: dict = None,
    metadata: dict = None,
    priority: str = "NORMAL"
)

Log a single prediction.

Parameters:

  • inputs (dict): Input features
  • output (dict): Model output
  • ground_truth (Any): Actual value (optional)
  • explanation (dict): Model explanation (optional)
  • metadata (dict): Additional metadata (optional)
  • priority (str): Queue priority (CRITICAL, HIGH, NORMAL, LOW)
log_batch(predictions: List[dict])

Log multiple predictions.

set_baseline(data: np.ndarray, **kwargs)

Set baseline data for drift detection.

detect_drift(data: np.ndarray) -> dict

Detect drift in current data.

Returns: Drift detection report

Decorators

@monitor_model

@monitor_model(
    monitor: ModelMonitor,
    input_keys: List[str] = None,
    output_key: str = None,
    explain: bool = False
)
def predict(...):
    ...

Monitor all predictions from a function.

@monitor_prediction

@monitor_prediction(
    monitor: ModelMonitor,
    input_extractor: Callable = None,
    output_extractor: Callable = None
)
def predict(...):
    ...

Monitor predictions with custom extractors.

Framework Integrations

SklearnMonitor

from whiteboxai.integrations.sklearn import SklearnMonitor

monitor = SklearnMonitor(
    client: WhiteBoxAI,
    model=None,
    model_name: str = None
)

monitor.register_from_model(model_type: str, **kwargs) -> int
monitor.wrap_model(model)
monitor.predict(model, X, y=None, log=True)

TorchMonitor

from whiteboxai.integrations.pytorch import TorchMonitor

monitor = TorchMonitor(
    client: WhiteBoxAI,
    model=None,
    model_name: str = None
)

monitor.register_from_model(model_type: str, **kwargs) -> int
monitor.wrap_model(model)

KerasMonitor

from whiteboxai.integrations.tensorflow import KerasMonitor, WhiteBoxAICallback

monitor = KerasMonitor(
    client: WhiteBoxAI,
    model=None,
    model_name: str = None
)

monitor.register_from_model(model_type: str, **kwargs) -> int
callback = WhiteBoxAICallback(monitor, log_frequency=1)
monitor.predict(X, log=True)

TransformersMonitor

from whiteboxai.integrations.transformers import TransformersMonitor

monitor = TransformersMonitor(
    client: WhiteBoxAI,
    pipeline=None,
    model_name: str = None
)

monitor.register_from_model(name: str, version: str = "1.0.0") -> int
monitor.predict(text, log=True)

LangChainMonitor

from whiteboxai.integrations.langchain import LangChainMonitor

monitor = LangChainMonitor(
    client: WhiteBoxAI,
    application_name: str,
    track_tokens: bool = True,
    track_cost: bool = True
)

monitor.register_application(name: str, version: str = "1.0.0") -> int
callback = monitor.create_callback_handler()

XGBoostMonitor / LightGBMMonitor

from whiteboxai.integrations.boosting import XGBoostMonitor, LightGBMMonitor

monitor = XGBoostMonitor(
    client: WhiteBoxAI,
    model_name: str,
    track_feature_importance: bool = True,
    importance_type: str = "gain"
)

monitor.register_from_model(model, X_train, y_train) -> int
monitor.predict(model, X, y=None, log=True)

Exceptions

from whiteboxai.exceptions import (
    WhiteBoxAIError,          # Base exception
    AuthenticationError,       # Authentication failed
    APIError,                 # API request error
    ValidationError,          # Validation error
    RateLimitError,          # Rate limit exceeded
)

Privacy

from whiteboxai.privacy import mask_data

masked = mask_data(
    data: dict,
    patterns: List[str] = None  # Custom PII patterns
) -> dict

Mask sensitive data before sending to API.