diff --git a/DEVELOP.md b/DEVELOP.md index a41050a0ae5..79d03d85eb7 100644 --- a/DEVELOP.md +++ b/DEVELOP.md @@ -22,6 +22,31 @@ for MacOS `brew install protobuf` You can also install `chromadb` the `pypi` package locally and in editable mode with `pip install -e .`. +### Python-only dev setup (Windows) + +If you want to work on the Python package only and you're on Windows (PowerShell), this minimal setup gets you started quickly. + +Prerequisites + +- Windows with Python 3.8+ installed and on PATH +- Git (optional, for cloning/forking) + +Quick steps (PowerShell) + +1. Create and activate a virtual environment: + +```powershell +python -m venv .venv +.\\.venv\\Scripts\\Activate.ps1 +``` + +2. Install dependencies and set up pre-commit hooks: + +```powershell +pip install -r .\requirements.txt +pip install -r .\requirements_dev.txt +pip install -e . +pre-commit install ## Local dev setup for distributed chroma We use tilt for providing local dev setup. Tilt is an open source project diff --git a/README.md b/README.md index 7579f324dcb..ac17d42df1d 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ pip install chromadb # python client # for client-server mode, chroma run --path /chroma_db_path ``` +Windows developers: for a minimal Python-only Windows (PowerShell) dev setup see the "Python-only dev setup (Windows)" section in `DEVELOP.md`. + ## Chroma Cloud Our hosted service, Chroma Cloud, powers serverless vector and full-text search. It's extremely fast, cost-effective, scalable and painless. Create a DB and try it out in under 30 seconds with $5 of free credits. @@ -65,15 +67,17 @@ results = collection.query( Learn about all features on our [Docs](https://docs.trychroma.com) ## Features -- __Simple__: Fully-typed, fully-tested, fully-documented == happiness -- __Integrations__: [`🦜️🔗 LangChain`](https://blog.langchain.dev/langchain-chroma/) (python and js), [`🦙 LlamaIndex`](https://twitter.com/atroyn/status/1628557389762007040) and more soon -- __Dev, Test, Prod__: the same API that runs in your python notebook, scales to your cluster -- __Feature-rich__: Queries, filtering, regex and more -- __Free & Open Source__: Apache 2.0 Licensed -## Use case: ChatGPT for ______ +- **Simple**: Fully-typed, fully-tested, fully-documented == happiness +- **Integrations**: [`🦜️🔗 LangChain`](https://blog.langchain.dev/langchain-chroma/) (python and js), [`🦙 LlamaIndex`](https://twitter.com/atroyn/status/1628557389762007040) and more soon +- **Dev, Test, Prod**: the same API that runs in your python notebook, scales to your cluster +- **Feature-rich**: Queries, filtering, regex and more +- **Free & Open Source**: Apache 2.0 Licensed + +## Use case: ChatGPT for **\_\_** For example, the `"Chat your data"` use case: + 1. Add documents to your database. You can pass in your own embeddings, embedding function, or let Chroma embed them for you. 2. Query relevant documents with natural language. 3. Compose documents into the context window of an LLM like `GPT4` for additional summarization or analysis. @@ -83,16 +87,17 @@ For example, the `"Chat your data"` use case: What are embeddings? - [Read the guide from OpenAI](https://platform.openai.com/docs/guides/embeddings/what-are-embeddings) -- __Literal__: Embedding something turns it from image/text/audio into a list of numbers. 🖼️ or 📄 => `[1.2, 2.1, ....]`. This process makes documents "understandable" to a machine learning model. -- __By analogy__: An embedding represents the essence of a document. This enables documents and queries with the same essence to be "near" each other and therefore easy to find. -- __Technical__: An embedding is the latent-space position of a document at a layer of a deep neural network. For models trained specifically to embed data, this is the last layer. -- __A small example__: If you search your photos for "famous bridge in San Francisco". By embedding this query and comparing it to the embeddings of your photos and their metadata - it should return photos of the Golden Gate Bridge. +- **Literal**: Embedding something turns it from image/text/audio into a list of numbers. 🖼️ or 📄 => `[1.2, 2.1, ....]`. This process makes documents "understandable" to a machine learning model. +- **By analogy**: An embedding represents the essence of a document. This enables documents and queries with the same essence to be "near" each other and therefore easy to find. +- **Technical**: An embedding is the latent-space position of a document at a layer of a deep neural network. For models trained specifically to embed data, this is the last layer. +- **A small example**: If you search your photos for "famous bridge in San Francisco". By embedding this query and comparing it to the embeddings of your photos and their metadata - it should return photos of the Golden Gate Bridge. Embeddings databases (also known as **vector databases**) store embeddings and allow you to search by nearest neighbors rather than by substrings like a traditional database. By default, Chroma uses [Sentence Transformers](https://docs.trychroma.com/guides/embeddings#default:-all-minilm-l6-v2) to embed for you but you can also use OpenAI embeddings, Cohere (multilingual) embeddings, or your own. ## Get involved Chroma is a rapidly developing project. We welcome PR contributors and ideas for how to improve the project. + - [Join the conversation on Discord](https://discord.gg/MMeYNTmh3x) - `#contributing` channel - [Review the 🛣️ Roadmap and contribute your ideas](https://docs.trychroma.com/roadmap) - [Grab an issue and open a PR](https://github.com/chroma-core/chroma/issues) - [`Good first issue tag`](https://github.com/chroma-core/chroma/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) diff --git a/examples/getting_started_windows_dev.ipynb b/examples/getting_started_windows_dev.ipynb new file mode 100644 index 00000000000..b691f1492a7 --- /dev/null +++ b/examples/getting_started_windows_dev.ipynb @@ -0,0 +1,64 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "8ec3ad5a", + "metadata": {}, + "source": [ + "# Getting started: Python-only dev on Windows (PowerShell)\n", + "\n", + "This notebook shows a minimal example you can run after setting up the Python-only developer environment described in `DEVELOP.md` -> 'Python-only dev setup (Windows)'.\n", + "\n", + "If you installed the repository in editable mode (`pip install -e .`) in the same environment used to run this notebook, you can import `chromadb` directly below." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "9eec5697", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Query results: {'ids': [['w1']], 'embeddings': None, 'documents': [['Hello from Windows']], 'uris': None, 'included': ['metadatas', 'documents', 'distances'], 'data': None, 'metadatas': [[{'source': 'notebook'}]], 'distances': [[0.8225913047790527]]}\n" + ] + } + ], + "source": [ + "# Minimal runtime example: create a client, a collection, add docs, and query\n", + "try:\n", + " import chromadb\n", + " client = chromadb.Client()\n", + " collection = client.create_collection('example_windows')\n", + " collection.add(documents=['Hello from Windows','Second doc'], metadatas=[{'source':'notebook'},{'source':'notebook'}], ids=['w1','w2'])\n", + " results = collection.query(query_texts=['Hello'], n_results=1)\n", + " print('Query results:', results)\n", + "except Exception as e:\n", + " print('Make sure you have followed the Windows Python-only setup in DEVELOP.md and installed the package in the active virtualenv. Error:', e)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": ".venv (3.13.7)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.7" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}