Context

A Context object defines the scope and circumstances in which features are expected to be served. Examples include:

weekly batch predictions for an active customer that has made at least one purchase over the past 12 weeks
real time predictions for a credit card transaction that has been recently processed

Creating a Context¶

Use the create() class method to add a Context to the active catalog:

context = fb.Context.create(
    name="Active Customer", # Name of the context
    primary_entity=["Customer"] # Primary entity related to the context
)

While basic context creation requires only the entity identification, adding a detailed description is recommended. This description could cover:

Contextual Subset Details: Characteristics of the entity subset being targeted.
Serving Timing: Insights into when predictions are needed, whether in batch or real-time scenarios.
Inference Data Availability: What data is available at the time of inference.
Constraints: Any legal, operational, or other constraints.

context.update_description(
    "This context identifies 'Active Customers' as those individuals "
    "whose customerid in the Customer Profile have no recorded "
    "termination date, signifying ongoing engagement or activity. \n"
    "The serving of features related to this context can be invoked at "
    "any point in time. \n"
    "Furthermore, there are no specific operational, legal, or other constraints."
)

Context with Treatment for Causal Modeling¶

For causal inference and uplift modeling scenarios, you can associate a Treatment with a context. This is essential when you want to measure the causal impact of an intervention or treatment on an outcome.

To create a context with a treatment, first create the treatment object, then reference it when creating the context:

# Create a treatment
treatment = fb.Treatment.create(
    name="Discount Campaign",
    dtype=fb.DBVarType.INT,
    treatment_type=fb.TreatmentType.BINARY,
    source="randomized",
    design="simple-randomization",
    time="static",
    time_structure="instantaneous",
    interference="none",
    treatment_labels=[0, 1],
    control_label=0,
    propensity=fb.Propensity(
        granularity="global",
        knowledge="design-known",
        p_global=0.5,
    ),
)

# Create a context with the treatment
causal_context = fb.Context.create(
    name="Active Customers in Discount Campaign",
    primary_entity=["customer"],
    description="Active customers who participated in the discount A/B test",
    treatment_name="Discount Campaign"
)

When a context is associated with a treatment, it provides the experimental or observational setting for causal analysis. This allows FeatureByte to:

Apply appropriate causal identification strategies
Select suitable statistical methods for uplift modeling
Ensure model evaluation metrics align with the experimental design

The context with treatment can then be combined with a Target in a Use Case to build and evaluate causal models.

Context with Forecast Point for Forecast Modeling¶

For time series forecasting scenarios, you can define a ForecastPointSchema on a context. The forecast point represents the future date/time being predicted for, as opposed to POINT_IN_TIME which represents when the prediction is made.

The ForecastPointSchema defines the granularity (day, week, hour, etc.), data type, and timezone handling for the FORECAST_POINT column in observation tables.

# Create a forecast point schema for daily forecasting
forecast_schema = fb.ForecastPointSchema(
    granularity=fb.TimeIntervalUnit.DAY,
    dtype=fb.DBVarType.DATE,
    is_utc_time=False,
    timezone="America/New_York",
)

# Create a context with the forecast point schema
forecast_context = fb.Context.create(
    name="Daily Sales Forecast",
    primary_entity=["store"],
    description="Daily sales forecast for each store",
    forecast_point_schema=forecast_schema,
)

Once a forecast context is created, you can use the get_forecast_point_feature() method to derive features from the forecast point. This returns a Feature with the correct dtype and timezone information, enabling operations like local time date part extraction and forecast horizon calculation:

# Extract month from forecast point in local time
forecast_month = forecast_context.get_forecast_point_feature().dt.month
forecast_month.name = "Forecast Month (Local)"

# Calculate forecast horizon (days between prediction time and forecast point)
forecast_horizon = (
    forecast_context.get_forecast_point_feature() - fb.RequestColumn.point_in_time()
).dt.day
forecast_horizon.name = "Forecast Horizon Days"

A more advanced use case is combining the forecast point with category-based aggregations. For example, to get the total sales on the same weekday as the forecast point over the past 91 calendar days:

# Extract day of week from forecast point
forecast_day_of_week = forecast_context.get_forecast_point_feature().dt.day_of_week
forecast_day_of_week.name = "Forecast_Day_Of_Week"

# Extract day of week from sales records
sales_view["Weekday"] = sales_view["date"].dt.day_of_week

# Aggregate sales by weekday category
sales_by_weekday = sales_view.groupby(
    ["item_store_id"], category="Weekday"
).aggregate_over(
    "sales",
    method="sum",
    feature_names=["Sales_by_Weekday_91cD"],
    windows=[fb.CalendarWindow(unit="DAY", size=91)],
)["Sales_by_Weekday_91cD"]

# Look up the value matching the forecast weekday
sales_same_forecast_weekday = sales_by_weekday.cd.get_value(forecast_day_of_week)
sales_same_forecast_weekday.name = "Sales_91cD_same_Forecast_Weekday"

This example works in three steps: (1) the cross aggregate Sales_by_Weekday_91cD produces a dictionary keyed by weekday (e.g., {0: 1200, 1: 980, ...}) containing total sales per weekday over the past 91 days, (2) the forecast point's day of week is extracted, and (3) cd.get_value() looks up the matching entry — yielding, for instance, the total Monday sales if the forecast point falls on a Monday. This pattern is useful for seasonal forecasting where same-weekday or same-month historical values are strong predictors.

When a context has a forecast point schema, observation tables associated with it must include a FORECAST_POINT column matching the schema's data type. FeatureByte automatically computes forecast point statistics (min/max values, forecast horizon) for the observation table.

The forecast context can then be combined with a Target in a Use Case to build forecast models. The Use Case will automatically be typed as a FORECAST use case.

Context with User-Provided Columns¶

Contexts can define user-provided columns that will be supplied in observation tables during feature materialization. These columns allow you to incorporate external data — such as customer-provided information or real-time inputs — into your feature engineering workflow without requiring them to be stored in source tables.

Define user-provided columns when creating a context using UserProvidedColumn:

context = fb.Context.create(
    name="Loan Approval",
    primary_entity=["customer"],
    user_provided_columns=[
        fb.UserProvidedColumn(
            name="annual_income",
            dtype=fb.DBVarType.FLOAT,
            feature_type=fb.FeatureType.NUMERIC,
            description="Customer's self-reported annual income",
        ),
        fb.UserProvidedColumn(
            name="loan_purpose",
            dtype=fb.DBVarType.VARCHAR,
            feature_type=fb.FeatureType.CATEGORICAL,
            description="Purpose of the loan application",
        ),
    ],
)

You can also add user-provided columns to an existing context using the add_user_provided_column() method:

context.add_user_provided_column(
    name="employment_length",
    dtype=fb.DBVarType.INT,
    feature_type=fb.FeatureType.NUMERIC,
    description="Years of employment",
)

To use a user-provided column as a feature, call the get_user_provided_feature() method. The returned Feature can be transformed or combined with other features:

income_feature = context.get_user_provided_feature("annual_income")
income_feature.name = "Annual Income"
income_feature.save()

When serving features, the observation table must include columns matching the names defined in the context. These columns are validated at materialization time.

Association with Observation Table¶

Once the Context is defined, you can link an observation table using the add_observation_table() method.

context = catalog.get_context("Active Customer")
context.add_observation_table(<observation_table_name>)

You can also define an observation table to be used as the default preview / eda table for the Context using the update_default_eda_table() and update_default_preview_table() methods.

context.update_default_eda_table(<observation_table_name>)

context.update_default_preview_table(<observation_table_name>)

Finally, you can list observation tables associated with the Context using the list_observation_tables() method.

context.list_observation_tables()