# Vehicle Search (AI)

### Overview <a href="#overview" id="overview"></a>

The `Vehicle Search AI` component provides a natural language search interface for vehicles. It allows users to search for cars using conversational queries rather than structured filters, making it more intuitive and user-friendly.

### Installation <a href="#installation" id="installation"></a>

The component is part of the Carpose application and requires no separate installation.

### Usage <a href="#usage" id="usage"></a>

To use the Vehicle Search AI component in a standard HTML page:

```html
<div
  data-carpose-component="vehicle-search-ai"
  data-api-key="your-api-key"
></div>
```

### Configuration Attributes <a href="#configuration-attributes" id="configuration-attributes"></a>

The component reads configuration from data attributes on the provided element:

| Attribute                | Type   | Default | Description                                                                               |
| ------------------------ | ------ | ------- | ----------------------------------------------------------------------------------------- |
| `data-carpose-component` | string | -       | Identifies the component type, must be set to "car-search-ai"                             |
| `data-api-key`           | string | -       | API key for authentication with the Carpose backend services. Required for data fetching. |

### Features <a href="#features" id="features"></a>

* Natural language search input for intuitive queries
* Results displayed as car cards with vehicle details
* Sorting options for search results:
  * Price (ascending/descending)
  * Mileage (ascending/descending)
  * Power (ascending/descending)
* Pagination for navigating through search results
* Loading indicators during search
* "No results" message when no matching vehicles are found
* Session storage persistence for search state (query, page, sorting)

### Example <a href="#example" id="example"></a>

```html
<div
  data-carpose-component="vehicle-search-ai"
  data-api-key="your-api-key"
></div>
```

### Behavior <a href="#behavior" id="behavior"></a>

1. **Search Interface**:
   * The component displays a prominent search input with a placeholder suggesting example queries.
   * Users can type natural language queries like "I'm looking for a city car" or "Show me SUVs with less than 50,000 km".
   * The search button triggers the query and displays loading indicators during the search process.
2. **Results Display**:
   * Search results are displayed as car cards below the search interface.
   * Each car card shows key information about the vehicle.
   * A count of total matching vehicles is displayed above the results.
   * If no matching vehicles are found, a friendly message is displayed.
3. **Sorting and Pagination**:
   * Once results are displayed, a sorting dropdown appears allowing users to sort by price, mileage, or power.
   * If there are more than 30 results, pagination controls appear at the bottom of the page.
   * Changing the sort order resets to the first page of results.
   * Clicking a pagination number fetches the corresponding page of results.
4. **State Persistence**:
   * The component stores the current search query, page number, and sorting preference in session storage.
   * If the user leaves and returns to the page, their previous search state is restored.
   * This allows users to continue browsing from where they left off.
5. **Responsive Behavior**:
   * The component adapts to different screen sizes.
   * On mobile devices, the sorting control appears above the results count for better usability.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carpose.de/vehicle-search-modules/vehicle-search-ai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.