> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goguava.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# DatetimeFilter

> Match natural-language time requests against available slots

`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

<Tabs>
  <Tab title="Python">
    ```python signature theme={null}
    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"`). |
  </Tab>

  <Tab title="TypeScript">
    ```typescript signature theme={null}
    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"`). |
  </Tab>
</Tabs>

## Methods

<Tabs>
  <Tab title="Python">
    **`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`.
  </Tab>

  <Tab title="TypeScript">
    **`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`.
  </Tab>
</Tabs>

## 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

<Tabs>
  <Tab title="Python">
    ```python datetime_filter.py theme={null}
    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)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript datetime_filter.ts theme={null}
    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)
    ```
  </Tab>
</Tabs>

## Using with Field and search queries

<Tabs>
  <Tab title="Python">
    A common pattern is to pair `DatetimeFilter` with a [`Field`](/sdk-reference/field) of type `"calendar_slot"` with `searchable=True`, and wire the filter into the `on_search_query` callback:

    ```python scheduling_agent.py theme={null}
    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)
    ```
  </Tab>

  <Tab title="TypeScript">
    A common pattern is to pair `DatetimeFilter` with a [`Field`](/sdk-reference/field) of type `"calendar_slot"` with `searchable: true`, and wire the filter into the `onSearchQuery` callback:

    ```typescript scheduling_agent.ts theme={null}
    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 });
    })
    ```
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.