# Usage

Welcome to **Chatformers**, a Python library that leverages advanced language models for chatbot creation and interaction with built-in memory management using vector stores. Chatformers simplify integrating large language models (LLMs) into your applications, supporting configurable memory through providers like Chroma, Qdrant, Pggvector, OpenAI, Groq, Ollama, Mem0AI, etc.

### Table of Contents

* Installation
* Getting Started
* Configuration
* Usage Example
* Optional Features
  * Adding Memories
  * Retrieving Memories
* Documentation
* License

### Installation

Before using the library, ensure you have the necessary dependencies installed.

```bash
pip install chatformers
```

Additionally, ensure that you have the required API key from [GROQ API](https://groq.com), [OpenAI](https://openai.com), or any OpenAI compatible library.

### Getting Started

#### Step 1: Importing the Library

To begin, import the necessary modules and set up the API key.

```python
from chatformers.chatbot import Chatbot
import os
from openai import OpenAI
```

Set your `GROQ_API_KEY` environment variable:

```python
os.environ["GROQ_API_KEY"] = "<API_KEY>"
GROQ_API_KEY = os.getenv("GROQ_API_KEY")
```

#### Step 2: Initializing the OpenAI Client

Configure the OpenAI client to communicate with the GROQ LLM service.

```python
groq_base_url = "https://api.groq.com/openai/v1"
client = OpenAI(base_url=groq_base_url, api_key=GROQ_API_KEY)
```

#### Step 3: Setting Up Chatbot Character

You can configure the chatbot character with specific attributes.

```python
character_data = {
    "name": "Julia",
    "description": "You are on an online chatting website, chatting with strangers."
}
```

#### Step 4: Configuring Chatformers

Chatformers use [**mem0ai**](https://docs.mem0.ai/overview) for memory management. Refer to the [mem0 documentation](https://docs.mem0.ai/overview) for more details.

```python
config = {
    "vector_store": {
        "provider": "chroma",
        "config": {
            "collection_name": "test",
            "path": "db"
        }
    },
    "embedder": {
        "provider": "ollama",
        "config": {
            "model": "nomic-embed-text:latest"
        }
    },
    "llm": {
        "provider": "groq",
        "config": {
            "model": "llama-3.1-8b-instant",
            "temperature": 0.1,
            "max_tokens": 4000
        }
    }
}
```

#### Step 5: Creating the Chatbot Instance

Initialize the chatbot with the OpenAI client, model name, character configuration, and memory configuration.

```python
chatbot = Chatbot(
    llm_client=client,
    model_name="llama-3.1-8b-instant",
    character_data=character_data,
    config=config
)
```

### Usage Example

#### Basic Chat Interaction

Below is an example of a chatbot conversation where the user asks the bot a question and receives a response based on previous chats.

```python
# Define user ID and conversation history
user_id = "Sam-Julia"
message_history = [
    {"role": "user", "content": "where r u from?"},
    {"role": "assistant", "content": "I am from CA, USA"}
]

# User's current question
query = "what is my name?"

# Get a response from the chatbot
response = chatbot.chat(query=query, message_history=message_history, user_id=user_id, print_stream=True)
print("Assistant: ", response)
```

#### Output

The chatbot responds based on previous conversations stored in memory and any additional context provided by the user.

```vbnet
Assistant: Your name is Sam!
```

### Optional Features

#### Adding Memories

Chatformers allow you to embed memories directly into the vector database, making future interactions more contextual.

```python
memory_messages = [
    {"role": "user", "content": "My name is Sam, what about you?"},
    {"role": "assistant", "content": "Hello Sam! I'm Julia."}
]
chatbot.add_memories(memory_messages, user_id=user_id)
```

#### Retrieving Memories

You can retrieve the memories associated with a specific user to understand the context better.

```python
memories = chatbot.get_memories(user_id=user_id)
for memory in memories:
    print(memory)
```

You can also query for related memories based on specific prompts.

```python
related_memories = chatbot.related_memory(user_id=user_id, query="yes I am Sam? what is your name")
print(related_memories)
```

### Documentation

For further details on the configuration and advanced features of **Chatformers**, refer to the following resources:

* [Mem0 Documentation](https://docs.mem0.ai/overview)
* [Chroma Vector Database](https://docs.trychroma.com/)

### License

Chatformers is open-source software licensed under the MIT License.