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

Python
TypeScript

signature

from guava.helpers.llm import DatetimeFilter

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

Parameter	Type	Required	Description
`source_list`	`list[str]`	Yes	The pool of available appointment datetimes in ISO 8601 format (e.g. `"2026-03-02T09:00:00"`).

signature

import { DatetimeFilter } from "@guava-ai/guava-sdk/helpers";

const dtFilter = new DatetimeFilter(sourceList: string[]);
await dtFilter.filter(query: string, options?: { maxResults?: number }): Promise<[string[], string[]]>

Parameter	Type	Required	Description
`sourceList`	`string[]`	Yes	The pool of available appointment datetimes in ISO 8601 format (e.g. `"2026-03-02T09:00:00"`).

Methods

Python
TypeScript

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.

filter(query: string, { maxResults = 5 }?): Promise<[string[], string[]]>Resolves to a 2-tuple [matchingAppointments, otherAppointments]:

matchingAppointments: datetimes from sourceList that match query, capped at maxResults.
otherAppointments: alternative datetimes to suggest when matchingAppointments is empty, also capped at maxResults.

Edge Cases

The model is instructed to only return values drawn from the source list, never invented 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.
The fallback list may be non-empty even when the matching list is empty — use it to offer the caller nearby alternatives.

Basic Usage

Python
TypeScript

datetime_filter.py

from guava.helpers.llm 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)

datetime_filter.ts

import { DatetimeFilter } from "@guava-ai/guava-sdk/helpers";

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

const dtFilter = new DatetimeFilter(AVAILABLE_SLOTS);

const [matches, suggestions] = await dtFilter.filter("tomorrow morning", { maxResults: 3 });
// matches     == ["2026-04-16T09:00:00", "2026-04-16T10:30:00"]
// suggestions == []  (not needed — matches were found)

Using with Field and search queries

Python
TypeScript

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.llm 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)

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

scheduling_agent.ts

import * as guava from "@guava-ai/guava-sdk";
import { DatetimeFilter } from "@guava-ai/guava-sdk/helpers";

const agent = new guava.Agent({
  name: "Scheduler",
  organization: "Acme Corp",
  purpose: "Help callers schedule appointments.",
});

const datetimeFilter = new DatetimeFilter(AVAILABLE_SLOTS);

agent.onCallStart(async (call: guava.Call) => {
  await call.setTask({
    taskId: "schedule_appointment",
    checklist: [
      guava.Field({
        key: "appointment_time",
        fieldType: "calendar_slot",
        description: "Find a time that works for the caller",
        searchable: true,
      }),
    ],
  });
});

agent.onSearchQuery("appointment_time", async (_call, query) => {
  return datetimeFilter.filter(query, { maxResults: 3 });
})

Getting started

Agent SDK

CLI reference

WebRTC

SIP calling

Phone numbers

Deployments

Compliance

Release notes

Constructor

Methods

Edge Cases

Basic Usage

Using with Field and search queries

​Constructor

​Methods

​Edge Cases

​Basic Usage

​Using with Field and search queries

Constructor

Methods

Edge Cases

Basic Usage

Using with Field and search queries