> ## Documentation Index
> Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Assistant (Veni)

> Intelligent chatbot powered by Google Gemini for metadata extraction and conversational item creation

## Overview

Invenicum's AI Assistant, named **Veni**, leverages Google Gemini to streamline inventory management through natural language conversations. The assistant can extract product metadata from URLs, auto-fill item details, and guide you through creating inventory items using simple chat commands.

> **Smart Extraction**
>
> Extract product details from web URLs automatically

> **Conversational UI**
>
> Create items through natural language chat

> **Multi-language**
>
> Supports locale-based responses (en, es, etc.)

> **Persistent History**
>
> Chat history syncs across devices

## How It Works

The AI Assistant integrates with your workflow in two primary ways:

### 1. URL-Based Metadata Extraction

When adding a new item, paste a product URL (Amazon, eBay, manufacturer site) and Veni will automatically extract:

* Product name
* Description
* Pricing information
* Technical specifications
* Images (where available)

**1. Paste Product URL**

In the item creation form, look for the "Extract from URL" option and paste the product link.

**2. Select Fields to Extract**

Choose which fields you want the AI to populate (name, description, custom fields).

**3. Review & Confirm**

Veni will populate the form with extracted data. Review for accuracy and make manual adjustments if needed.

**4. Save Item**

Complete the creation process with pre-filled metadata, saving significant time.

> [!NOTE]
>
> The AI extraction works best with structured product pages from major retailers and manufacturers. Custom or poorly formatted pages may yield incomplete results.

### 2. Conversational Item Creation

Chat directly with Veni to create items, search your inventory, or get help navigating the system.

**Example Conversation:**

```
You: Add a new laptop to my Tech Equipment container
Veni: I can help you create a laptop. What's the model name?

You: Dell XPS 15, 32GB RAM, 1TB SSD
Veni: Got it! I'll create a Dell XPS 15. Should I add those specs 
     as custom fields?

You: Yes
Veni: ✓ Created "Dell XPS 15" in Tech Equipment with RAM and 
     storage specs.
```

> [!TIP]
>
> Use the `SAY_HELLO_INITIAL` command when first opening the chat interface to get a personalized greeting based on your locale.

## Technical Implementation

Veni is powered by two core services:

### ChatService

Manages conversation state and message history:

* **Persistent History**: Messages are stored server-side and loaded via `/ai/chat/history` (lib/data/services/veni\_chatbot\_service.dart:23)
* **Real-time Updates**: Uses Flutter's `ChangeNotifier` to update UI instantly
* **Locale Support**: Automatically sends user language preferences to Gemini

### AIService

Handles URL metadata extraction:

* **Endpoint**: `POST /ai/extract` (lib/data/services/ai\_service.dart:17)
* **Input**: URL and list of fields to extract
* **Output**: Structured JSON matching your item schema

## Use Cases

> **E-commerce Imports**
>
> Quickly catalog online purchases by pasting order confirmation links.

> **Equipment Onboarding**
>
> Add new office equipment by extracting specs from manufacturer sites.

> **Parts Inventory**
>
> Auto-populate technical specifications for electronic components.

> **Collection Management**
>
> Fast-track adding collectibles with details from auction sites.

## Best Practices

### For URL Extraction

1. **Use Direct Product Pages**: Avoid category pages or search results
2. **Check Extracted Data**: AI interpretation isn't perfect—always review
3. **Supplement Custom Fields**: Add domain-specific fields manually after extraction

### For Chat Interactions

1. **Be Specific**: "Add laptop" is vague; "Add Dell XPS 15 to Tech Equipment" works better
2. **One Action at a Time**: Break complex workflows into individual requests
3. **Provide Context**: Mention container names, quantities, or locations explicitly

> [!WARNING]
>
> The AI Assistant requires an active internet connection and uses your organization's API quota for Google Gemini. Large-scale extractions may incur additional costs.

## Limitations

* **Rate Limits**: Heavy usage may hit Gemini API quotas
* **Accuracy**: Extraction quality depends on source page structure
* **Language**: Works best with English content; other languages may have reduced accuracy
* **Privacy**: URLs are sent to Google's servers for processing

## API Reference

For developers integrating with Veni, see the API documentation for the Chat Service and AI Service implementations.


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