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


---

# 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://viznetai.gitbook.io/chatformers/usage.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.