docs/DatetimeFilter

DatetimeFilter

DatetimeFilter filters a list of ISO 8601 datetime strings to find entries matching a natural-language query (e.g. "tomorrow afternoon"). Returns both matching datetimes and fallback suggestions when no exact match exists.

Constructor

signature
from guava.helpers.openai import DatetimeFilter

DatetimeFilter(source_list: list[str], client: openai.OpenAI | None = None)
dt_filter.filter(query: str, max_results: int = 5) -> tuple[list[str], list[str]]
ParameterTypeRequiredDescription
source_listlist[str]YesThe pool of available appointment datetimes in ISO 8601 format (e.g. "2026-03-02T09:00:00"). The model will only return values present in this list.
clientopenai.OpenAINoAn OpenAI client to use. If omitted, a client is created automatically.

Methods

filter(query: str, max_results: int = 5) -> tuple[list[str], list[str]]

Returns a 2-tuple (matching_appointments, other_appointments):

  • matching_appointments: datetimes from source_list that match query, capped at max_results.
  • other_appointments: alternative datetimes to suggest when matching_appointments is empty, also capped at max_results.

Edge Cases

  • Raises AssertionError if max_results is not an int.
  • Both output lists are guaranteed to contain only values drawn from source_list — the model is explicitly instructed never to hallucinate datetimes.
  • Today's date is injected into the prompt automatically, so relative queries like "tomorrow" and "next week" resolve correctly without any date math on the caller's side.
  • other_appointments may be non-empty even when matching_appointments is empty — use it to offer the caller nearby alternatives.

Model details: DatetimeFilter uses gpt-5-mini with reasoning.effort = "medium". These settings are not configurable.

Basic Usage

datetime_filter.py
from guava.helpers.openai import DatetimeFilter

AVAILABLE_SLOTS = [
    "2026-04-16T09:00:00",
    "2026-04-16T10:30:00",
    "2026-04-17T14:00:00",
    "2026-04-18T09:00:00",
]

dt_filter = DatetimeFilter(source_list=AVAILABLE_SLOTS)

matches, suggestions = dt_filter.filter("tomorrow morning", max_results=3)
# matches     == ["2026-04-16T09:00:00", "2026-04-16T10:30:00"]
# suggestions == []  (not needed — matches were found)

matches, suggestions = dt_filter.filter("this Friday at noon", max_results=3)
# matches     == []  (no Friday noon slot exists)
# suggestions == ["2026-04-17T14:00:00", ...]  (nearby alternatives offered)

Using with Field and on_search_query

A common pattern is to pair DatetimeFilter with a Field of type "calendar_slot" with searchable=True, and wire the filter into the on_search_query callback:

scheduling_agent.py
import guava
from guava import Agent
from guava.helpers.openai import DatetimeFilter

agent = Agent(
    name="Scheduler",
    organization="Acme Corp",
    purpose="Help callers schedule appointments.",
)

datetime_filter = DatetimeFilter(source_list=AVAILABLE_SLOTS)

@agent.on_call_start
def on_call_start(call: guava.Call):
    call.set_task(
        "schedule_appointment",
        checklist=[
            guava.Field(
                key="appointment_time",
                field_type="calendar_slot",
                description="Find a time that works for the caller",
                searchable=True,
            ),
        ],
    )

@agent.on_search_query("appointment_time")
def search_appointments(call: guava.Call, query: str):
    return datetime_filter.filter(query, max_results=3)
→ Next: Vector Stores

Questions? hi@goguava.ai