## Field

A `Field` is a [Task](https://goguava.ai/docs/tasks) checklist item instructing the Guava agent to collect structured data from the caller. The agent elicits the value through natural conversation, validates it against the specified type, and marks the checklist item complete when satisfied.

### PythonTypeScript

```python
# Field Example
field = guava.Field(
    key="caller_name",
    description="Get the caller's name",
)
```

### Signature

```python
guava.Field(
    # Identifier used to retrieve the value via get_field() after collection.
    key: str,

# Natural-language instruction to the LLM about how to collect this value.
    description: str = '',

# Encourages the agent to ask for the field in a particular way.
    question: str = '',

# Controls parsing and validation.
    field_type: Literal[
        'text', 'date', 'datetime', 'integer', 'multiple_choice', 'calendar_slot'\
    ] = 'text',

# If False, the agent can skip this field if the caller is unwilling to provide it.
    required: bool = True,

# Static list of valid options for "calendar_slot" and "multiple_choice" fields.
    choices: list[str] = [],

# When True, enables dynamic search for "multiple_choice" and "calendar_slot" fields.
    searchable: bool = False,
)
```

### Basic Examples

```python
# Basic text field
field = guava.Field(
    key="caller_name",
    description="Get the caller's name",
)

# Integer field with question
field = guava.Field(
    key="caller_age",
    question="How old are you?",
    field_type="integer",
)

# Multiple choice with static choices
field = guava.Field(
    key="caller_preference",
    description="Get the caller's preferred fruit",
    field_type="multiple_choice",
    choices=["apple", "banana", "orange"],
    required=False,
)
```

### Search Fields

Some fields can have a very large set of valid options. For example, a `destination_airport` field may include thousands of airports worldwide. In other cases, options must be generated dynamically, such as an `appointment_time` field populated from a booking system.

```python
field = guava.Field(
    key="airport",
    description="Find a suitable airport for the caller",
    field_type="multiple_choice",
    searchable=True,
)

@agent.on_search_query("airport")
def search_airports(call: guava.Call, query: str):
    matching_airports: list[str] = []
    other_airports: list[str] = []
    ...
    return matching_airports, other_airports
```

### Field Types Reference

| Type              | Example collected value                           | Return type from `get_field()`                              |
|-------------------|--------------------------------------------------|------------------------------------------------------------|
| `text`            | "I want to cancel my appointment"               | `str`                                                     |
| `date`            | {"year": 2024, "month": 3, "day": 15}     | `dict` with keys `year`, `month`, `day` (all `int`)     |
| `integer`         | `42`                                             | `int`                                                     |
| `multiple_choice` | "apple"                                        | `str` (guaranteed to be one of `choices` or returned by `choice_generator`) |
| `calendar_slot`   | "2022-12-31T17:30"                             | ISO-8601 datetime `str`                                   |