Metadata-Version: 2.4
Name: mongodb-ai-widget-challenge
Version: 0.28
Summary: A Jupyter widget for exploring MongoDB AI capabilities through a challenge
Author-email: Thibaut Gourdel <thibaut.gourdel@mongodb.com>
License: MIT License
        
        Copyright (c) 2025 MongoDB, Inc.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/mongodb-developer/mongodb-ai-widgets
Project-URL: Repository, https://github.com/mongodb-developer/mongodb-ai-widgets
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anywidget
Requires-Dist: ipywidgets
Requires-Dist: traitlets
Requires-Dist: langchain>=1.0
Requires-Dist: langchain-core>=1.0
Requires-Dist: langchain-community
Requires-Dist: langchain-classic
Requires-Dist: langchain-mongodb
Requires-Dist: langchain_voyageai
Requires-Dist: pymongo
Requires-Dist: pypdf
Requires-Dist: tiktoken
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# MongoDB AI Playground

MongoDB AI Playground is a set of interactive widgets for to explore, test, and visualize MongoDB-powered AI capabilities in notebooks, including Retrieval-Augmented Generation (RAG) and GraphRAG workflows, using modern LLM and vector search integrations.

---

## Overview

![Screenshot MongoDB AI Playground](assets/screenshot1.png)

Built as a set of [AnyWidget](https://anywidget.dev/) Jupyter widgets, this playground is designed for rapid prototyping, learning, and demonstration of GenAI + MongoDB workflows.

## Prerequisites

- An [**Atlas account**](https://account.mongodb.com/account/register?tck=docs_atlas) with a cluster running **MongoDB version 6.0.11**, **7.0.2**, or later (including release candidates). Ensure your **IP address** is included in your Atlas project's [**access list**](https://www.mongodb.com/docs/atlas/security/ip-access-list/#std-label-access-list). To learn more, see [**Create a Cluster**](https://www.mongodb.com/docs/atlas/tutorial/create-new-cluster/#std-label-create-new-cluster).
- An environment to run interactive Python notebooks such as JupyterLab, Jupyter Notebook, Google Colab and VSCode. Make sure you have widget support enabled (it is enabled by default on most platforms).
- Create a database and collection (if you choose to use an existing collection, usage with the playground will erase the collection's data. Providing a new collection is recommended)
- [**Create an Atlas Vector Search index**](https://www.mongodb.com/docs/compass/current/indexes/create-vector-search-index/) with the correct dimension associated with the embedding model you will use. The field containing the embedding must be named **`embedding`**.

## Installation

```bash
pip install mongodb-ai-playground
```

## Usage

### RAG Playground

```python
from mongodb_ai_playground import MongoDBRAGPlayground

# Example: Pass your own loader, embedding model, LLM, and MongoDB collection
widget = MongoDBRAGPlayground(
    loader=...,              # LangChain loader
    embedding_model=...,     # LangChain embedding model 
    llm=...,                 # LangChain Chat Model (LLM) for answering questions (OpenAI, Claude, DeepSeek, etc.)
    mongo_collection=...,    # PyMongo collection for storing vectors
    index_name=...           # Name of your Atlas Vector Search index, you need to create if you don't have one, with the correct dimension (field containing the embedding is 'embedding')
)
widget # Display the playground widget
```

- All interactions are performed via the interactive UI in Jupyter-compatible environments.
- Visualize chunking, embeddings, vector search results, and question answering.

Notebook examples

| Description                                        | Link                                                                                                                                                      |
|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Wikipedia data + Voyage AI embedding + OpenAI LLM | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/mongodb-developer/mongodb-ai-playground/blob/main/examples/mongodb_rag_playground_wiki_voyageai_openai.ipynb) |


## Development

### Setup

To set up the environment for development, clone the repository and install the package in editable mode. This allows changes to the Python code and the JavaScript/CSS (via `anywidget`'s live reloading) to be reflected immediately.

```bash
# Clone the repository
git clone https://github.com/mongodb-developer/mongodb-ai-playground.git
cd mongodb-ai-playground

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

# Install in editable mode
pip install -e .
```

### Testing in a Notebook

To test the widget during development:

1.  Start JupyterLab or Jupyter Notebook:
    ```bash
    pip install jupyterlab
    jupyter lab
    ```
2.  Open the example notebook in `examples/mongodb_rag_playground_wiki_voyageai_openai.ipynb`.
3.  Ensure you have the necessary environment variables or credentials set up (Atlas connection string, OpenAI API key, etc.) as described in the notebook.
4.  Run the notebook cells to interact with the widget. Changes to `mongodb_ai_playground/index.js` or `mongodb_ai_playground/index.css` will be reflected upon refreshing the page or re-running the widget cell.

### Building the Package

To build the package for distribution (creating `.tar.gz` and `.whl` files):

1.  Install the build tool:
    ```bash
    pip install build
    ```
2.  Run the build command from the root of the repository:
    ```bash
    python -m build
    ```
3.  The build artifacts will be generated in the `dist/` directory.


## Features

- 📄 **Document Chunking**: Flexible strategies (fixed, recursive, markdown) for splitting documents.
- 🧠 **Embeddings & Vector Search**: Store and search embeddings in MongoDB Atlas using [langchain-mongodb](https://github.com/langchain-ai/langchain-mongodb).
- 🔎 **RAG Playground UI**: Step-by-step interface for chunking, embedding, and querying.
- 🕸️ **Knowledge Graph RAG**: Build and visualize entity/relation graphs from docs and run graph-based QA.
- 🧩 **Extensible**: Built for experimentation with LangChain so that you can use different loaders, embeddings models, LLMs and more.

---

## Project Structure

```
mongodb_ai_playground/
├── rag_widget.py         # RAG playground widget (chunking, embedding, RAG)
├── graphrag_widget.py    # Graph RAG playground widget (graph ingest, QA)
├── index.js              # JS frontend for RAG widget
├── graphrag.js           # JS frontend for Graph RAG widget
├── index.css             # Shared widget styles
├── __init__.py           # Exports widgets
...
```

---

## Requirements
- Python 3.7+
- Jupyter widget compatible environments (JupyterLab, Jupyter Notebook, Colab, Marimo, etc.) 
- MongoDB Atlas deployment (for vector/graph storage)
- Any LLM and embedding model using LangChain components (OpenAI, HuggingFace, etc.)

---

## License

This project is licensed under the [MIT License](LICENSE).

## Acknowledgments

- [AnyWidget](https://anywidget.dev/)
- [LangChain](https://python.langchain.com/)
- [langchain-mongodb](https://github.com/mongodb-developer/langchain-mongodb)
- [PyMongo](https://pymongo.readthedocs.io/)
- [MongoDB Atlas](https://www.mongodb.com/atlas)

## Additional Resources

* [GenAI Showcase](https://github.com/mongodb-developer/GenAI-Showcase)
* [AI Learning Hub](https://www.mongodb.com/resources/use-cases/artificial-intelligence?utm_campaign=ai_learning_hub&utm_source=github&utm_medium=referral)
* [GenAI Community Forum](https://www.mongodb.com/community/forums/c/generative-ai/162)
* [Tutorials and code examples from our official docs](https://github.com/mongodb/docs-notebooks)
