### Visualize ChromaDB Collection

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/visualize_collection.md

This example demonstrates how to create a ChromaDB collection, populate it with data, and then visualize it using the `visualize_collection` function. Ensure you have chromadb and chromaviz installed.

```python
import chromadb
from chromaviz import visualize_collection

# Create and populate a ChromaDB collection
client = chromadb.Client()
collection = client.get_or_create_collection(name="my_docs")
collection.add(
    documents=["Hello world", "Goodbye world"],
    metadatas=[{"source": "greeting"}, {"source": "farewell"}],
    ids=["id1", "id2"]
)

# Visualize the collection
visualize_collection(collection, port=5000)
```

--------------------------------

### Three.js Camera Initial Setup

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/configuration.md

Configure the initial position of the Three.js camera within the ThreePointViz component. This setup determines the starting viewpoint for the 3D visualization.

```javascript
<Canvas camera={{ position: [0, 0, -5] }}>
```

--------------------------------

### Configuration Options

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/REFERENCE_INDEX.md

Examples of common configuration parameters for visualization and dimensionality reduction.

```python
visualize_collection(col, port=5000)
```

```python
PCA(n_components=50)
```

```python
TSNE(perplexity=40, n_iter=300)
```

```python
AppSettings {showDocuments, ...}
```

--------------------------------

### Example GET /data Request

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

This snippet shows how to make a request to the /data endpoint using curl. No request body or query parameters are required.

```bash
curl http://127.0.0.1:5000/data
```

--------------------------------

### GET /

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/REFERENCE_INDEX.md

Serves the main application interface.

```APIDOC
## GET /

### Description
Serves the main application interface.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- Serves the main HTML page for the application.
```

--------------------------------

### GET / Endpoint

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Serves the main HTML interface for the visualization. Loads from 'chromaviz/index.html' using importlib.resources.

```python
@app.route("/")
def hello_world()
```

```python
response = requests.get("http://127.0.0.1:5000/")
# Returns HTML page with 3D visualization interface
```

--------------------------------

### Start Visualization with Specific Port

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

Call this Python function to start the Flask app and open the visualization in a browser. Specify the desired port for the Flask server.

```python
visualize_collection(collection, port=5000)
```

--------------------------------

### Example GET /data Response Structure

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

This JSON structure represents a successful response from the /data endpoint. It contains an array of points, each with its 3D position, original document text, metadata, ID, and group assignment.

```json
{
  "points": [
    {
      "position": [0.82, -1.34, 0.56],
      "document": "The quick brown fox jumps over the lazy dog",
      "metadata": {
        "source": "animals.txt",
        "category": "mammals"
      },
      "id": "doc_001",
      "group": 5
    },
    {
      "position": [-0.45, 0.91, -0.23],
      "document": "A journey of a thousand miles begins with a single step",
      "metadata": {
        "source": "quotes.txt",
        "author": "Lao Tzu"
      },
      "id": "doc_002",
      "group": 12
    }
  ]
}
```

--------------------------------

### Basic ChromaViz Visualization

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/OVERVIEW.md

Visualize a ChromaDB collection using the default settings. Ensure chromadb and chromaviz are installed.

```python
import chromadb
from chromaviz import visualize_collection

client = chromadb.Client()
collection = client.get_or_create_collection("documents")
# Add documents with embeddings...
visualize_collection(collection)
```

--------------------------------

### App Component Usage

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Example of how to import and render the App component in a React application using ReactDOM.

```jsx
import App from './App.jsx'
import ReactDOM from 'react-dom/client'

ReactDOM.createRoot(document.getElementById('root')).render(<App />)
```

--------------------------------

### Initialize and Visualize ChromaDB Collection

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/OVERVIEW.md

Use this snippet to initialize a ChromaDB collection, add documents with embeddings and metadata, and then visualize the collection using ChromaViz. Ensure ChromaDB is installed and accessible.

```python
from chromaviz import visualize_collection
import chromadb

collection = chromadb.Client().get_or_create_collection("docs")
collection.add(
    documents=["text1", "text2"],
    metadatas=[{"key": "value"}, {}],
    embeddings=[[...], [...]]  # High-dimensional vectors
)

visualize_collection(collection, port=5000)
```

--------------------------------

### Configure ChromaDB Client Settings

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/configuration.md

Example of configuring ChromaDB client settings, specifically disabling anonymized telemetry.

```python
from chromadb.config import Settings

settings = Settings(
    anonymized_telemetry=False  # Disable telemetry
)
client = chromadb.Client(settings=settings)
```

--------------------------------

### ButtonGroup Usage Example

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Shows how to integrate the ButtonGroup component into the application. It expects a 'settings' prop which is a tuple containing the current settings object and a function to update it.

```jsx
<ButtonGroup settings={[settings, setSettings]} />
```

--------------------------------

### Footer Component Usage

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Example of how to use the Footer component in your application, passing the settings state tuple.

```jsx
<Footer settings={[settings, setSettings]} />
```

--------------------------------

### t-SNE Output Scaling Example

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/data_processing.md

Illustrates the effect of scaling t-SNE output by dividing by 3. Shows raw output and the resulting scaled values.

```python
# Raw t-SNE output
[[12.4, -15.3, 8.2],
 [-18.7, 9.1, -12.5]]

# After / 3
[[4.13, -5.1, 2.73],
 [-6.23, 3.03, -4.17]]
```

--------------------------------

### GET /assets/* - Static Assets

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/MANIFEST.txt

Serves static assets such as CSS, JavaScript, and images.

```APIDOC
## GET /assets/*

### Description
Serves static assets like CSS, JavaScript, and images.

### Method
GET

### Endpoint
/assets/*

### Parameters
#### Path Parameters
- ***** (string) - Required - Path to the requested asset.
```

--------------------------------

### GET /

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Serves the main HTML interface for the visualization. This endpoint loads the complete HTML document with embedded CSS and JavaScript from the built Vite application.

```APIDOC
## GET /

### Description
Serves the main HTML interface for the visualization.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200 OK)
- Content-Type: text/html
- Body: Complete HTML document with embedded CSS and JavaScript from the built Vite application.

### Request Example
```python
response = requests.get("http://127.0.0.1:5000/")
# Returns HTML page with 3D visualization interface
```
```

--------------------------------

### DataLines Usage Example

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Shows how to conditionally render the DataLines component based on settings and provides the necessary props.

```jsx
{settings[0].showLines && 
  <DataLines 
    data={data} 
    palette={palette}
    highlightedGroup={highlightedGroup}
  />
}
```

--------------------------------

### ThreePointVis Lighting Setup

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Configuration for ambient and hemisphere lighting within the ThreePointVis component to illuminate the 3D scene.

```javascript
// Ambient light for overall illumination
<ambientLight color="#ffffff" intensity={0.1} />

// Hemisphere light for depth perception
<hemisphereLight
  color="#ffffff"
  skyColor="#ffffbb"
  groundColor="#080820"
  intensity={1.0}
/>
```

--------------------------------

### Langchain Integration for Visualization

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/visualize_collection.md

This example shows how to visualize a ChromaDB collection that was created using Langchain's vectorstore wrapper. It extracts the underlying ChromaDB collection object from the Langchain vectorstore and passes it to the `visualize_collection` function.

```python
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings
from chromaviz import visualize_collection

vectordb = Chroma.from_documents(
    documents=my_documents,
    embedding=OpenAIEmbeddings(),
    ids=doc_ids
)

# Extract underlying ChromaDB collection
visualize_collection(vectordb._collection)
```

--------------------------------

### Import Data from ChromaDB

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

Example of retrieving data from a ChromaDB collection, including documents, metadatas, and embeddings, before sending it to the `/import-data` endpoint.

```python
data = col.get(include=["documents", "metadatas", "embeddings"])
# Result structure:
{
  "ids": ["id1", "id2", ...],
  "embeddings": [[0.1, 0.2, ...], [0.3, 0.4, ...], ...],
  "documents": ["doc1 text", "doc2 text", ...],
  "metadatas": [{"key": "value"}, {"key": "value"}, ...]
}
```

--------------------------------

### DataPoints Usage Example

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Illustrates how to use the DataPoints component in a React application. Ensure that the necessary props like data, palette, and state management for highlighting are provided.

```jsx
<DataPoints 
  data={data} 
  palette={palette}
  highlightedGroup={highlightedGroup}
  setHighlightedGroup={setHighlightedGroup}
  settings={settings}
/>
```

--------------------------------

### ChromaDB Collection Get Method

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/types.md

The `get` method of a ChromaDB Collection object allows retrieval of embeddings, documents, and metadatas.

```APIDOC
## ChromaDB Collection

### Description
Retrieves data from a ChromaDB collection.

### Method
`get`

### Parameters
#### Query Parameters
- **include** (List[str]) - Required - A list of strings specifying which data to include (e.g., "embeddings", "documents", "metadatas", "ids").

### Response
#### Success Response
- **embeddings** (List[List[float]]) - A list of embedding vectors.
- **documents** (List[str]) - A list of associated documents.
- **metadatas** (List[Dict[str, Any]]) - A list of metadata dictionaries.
- **ids** (List[str]) - A list of unique identifiers.
```

--------------------------------

### ChromaDB Collection Get Method Signature

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/types.md

Type definition for the get method of a ChromaDB Collection, specifying the include parameter and return type.

```python
# From chromadb.api.models.Collection
class Collection:
    def get(self, include: List[str]) -> Dict[str, Any]:
        """
        Returns:
        {
            'embeddings': [[float, ...], ...],
            'documents': [str, ...],
            'metadatas': [{str: Any}, ...],
            'ids': [str, ...]
        }
        """
        ...
```

--------------------------------

### HTTP API: GET /assets/<filename>

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/OVERVIEW.md

Serves static assets such as JavaScript and CSS files required for the visualization.

```APIDOC
## GET /assets/<filename>

### Description
Static assets (JS, CSS).

### Method
GET

### Endpoint
/assets/<filename>

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the asset file to retrieve.
```

--------------------------------

### GET / - Main HTML Page

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/MANIFEST.txt

Serves the main HTML page for the ChromaViz application.

```APIDOC
## GET /

### Description
Serves the main HTML page of the ChromaViz application.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- HTML content for the main page.
```

--------------------------------

### ThreePointVis Component Usage

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Example of how to use the ThreePointVis component, passing the data and settings state from its parent.

```jsx
<ThreePointVis 
  data={data} 
  settings={[settings, setSettings]} 
/>
```

--------------------------------

### App Component Setup

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

The root component that manages application state, including data fetching, loading, and error handling. It passes display settings to child components.

```jsx
function App()
```

--------------------------------

### Visualize ChromaDB Collection

Source: https://github.com/mtybadger/chromaviz/blob/main/README.md

Use this function to visualize a ChromaDB collection. Ensure ChromaDB is installed and a collection object is available.

```python
from chromaviz import visualize_collection
visualize_collection(chromadb.Collection)
```

--------------------------------

### Example JSON Output Structure

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/data_processing.md

Illustrates the expected JSON format for the 'points' array, showing the structure of each individual point object including its position, document content, metadata, ID, and group.

```json
{
  "points": [
    {
      "position": [4.13, -5.1, 2.73],
      "document": "Original document text...",
      "metadata": {"source": "file.txt", "page": 1},
      "id": "doc_001",
      "group": 12
    },
    ...
  ]
}
```

--------------------------------

### GET /data

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/REFERENCE_INDEX.md

Retrieves processed data for visualization.

```APIDOC
## GET /data

### Description
Retrieves processed data for visualization.

### Method
GET

### Endpoint
/data

### Response
#### Success Response (200)
- Returns the processed data in a suitable format for frontend consumption.
```

--------------------------------

### Python API: visualize_collection

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/OVERVIEW.md

Starts an interactive 3D visualization of a ChromaDB collection. This function runs a Flask server and opens the visualization in your browser.

```APIDOC
## visualize_collection

### Description
Start an interactive 3D visualization of a ChromaDB collection.
Opens browser automatically to `http://127.0.0.1:{port}`.
Runs Flask server indefinitely until stopped.

### Parameters
- **col** (chromadb.api.models.Collection.Collection) - Required - The ChromaDB collection to visualize.
- **port** (int) - Optional - The port to run the Flask server on. Defaults to 5000.
```

--------------------------------

### GET /assets/<path:filename> Endpoint

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Serves static assets like CSS and JavaScript files from the built frontend. The Content-Type is determined by the file extension.

```python
@app.route('/assets/<path:filename>')
def serve_assets(filename)
```

```python
response = requests.get("http://127.0.0.1:5000/assets/index-351494fc.js")
# Returns compiled React application bundle
```

--------------------------------

### Visualize Collection with Default Port

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/configuration.md

Call visualize_collection with a ChromaDB Collection object to start a visualization on the default port 5000.

```python
visualize_collection(my_collection)
```

--------------------------------

### GET /assets/<path:filename>

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Serves static assets such as CSS and JavaScript files from the built frontend. The content type is automatically determined based on the file extension.

```APIDOC
## GET /assets/<path:filename>

### Description
Serves static assets (CSS, JavaScript files) from the built frontend.

### Method
GET

### Endpoint
/assets/<path:filename>

### Parameters
#### Path Parameters
- **filename** (string) - Required - File path within assets directory (e.g., `bundle.js`, `styles.css`)

### Response
#### Success Response (200 OK)
- Content-Type: Automatically determined based on file extension:
  - `.js` → `text/javascript`
  - `.css` → `text/css`
  - Other → `text/html`
- Body: File contents read from package resources

### Request Example
```python
response = requests.get("http://127.0.0.1:5000/assets/index-351494fc.js")
# Returns compiled React application bundle
```
```

--------------------------------

### visualize_collection

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/visualize_collection.md

Main entry point for visualizing a ChromaDB collection in 3D. This function starts a Flask web server to display the collection's data in a web browser.

```APIDOC
## visualize_collection

### Description
Starts a Flask web server to visualize a ChromaDB collection in 3D. The server hosts an HTML interface and provides endpoints for data import and retrieval.

### Function Signature
```python
def visualize_collection(col: chromadb.api.models.Collection.Collection, port: int = 5000) -> None
```

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
- **col** (chromadb.api.models.Collection.Collection) - Required - A ChromaDB Collection object containing documents, metadata, and embeddings to visualize.
- **port** (int) - Optional - Port number on which to host the Flask web server. Defaults to 5000.

### Return Value
Returns `None`. Blocks execution and runs the Flask development server indefinitely until manually stopped.

### Behavior
1. Extracts all documents, metadatas, and embeddings from the ChromaDB collection.
2. Opens a web browser automatically to `http://127.0.0.1:{port}`.
3. Runs Flask development server on the specified port.
4. Server makes data available through endpoints: `GET /`, `POST /import-data`, `GET /data`.
5. Serves static assets (CSS, JavaScript) from the built Vite application.

### Raises
No explicit error handling is defined. Will raise underlying errors from ChromaDB if collection access fails or from Flask if port is already in use.

### Usage Example
```python
import chromadb
from chromaviz import visualize_collection

client = chromadb.Client()
collection = client.get_or_create_collection(name="my_docs")
collection.add(
    documents=["Hello world", "Goodbye world"],
    metadatas=[{"source": "greeting"}, {"source": "farewell"}],
    ids=["id1", "id2"]
)

visualize_collection(collection, port=5000)
```
```

--------------------------------

### Pandas DataFrame Creation from Embeddings

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/types.md

Example of creating a Pandas DataFrame from a dictionary of embeddings, showing the expected shape.

```python
# Created from embeddings dict
df = pd.DataFrame.from_dict(data=data["embeddings"])
# Shape: (n_docs, embedding_dim)
```

--------------------------------

### Example Embeddings to DataFrame Transformation

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/data_processing.md

Illustrates the conversion of raw embedding data (list of lists) into a structured pandas DataFrame format.

```python
# Input embeddings
[
    [0.1, 0.2, 0.3, 0.4],
    [0.5, 0.6, 0.7, 0.8],
    [0.9, 1.0, 1.1, 1.2]
]

# Output DataFrame
     0    1    2    3
0  0.1  0.2  0.3  0.4
1  0.5  0.6  0.7  0.8
2  0.9  1.0  1.1  1.2
```

--------------------------------

### Example PCA Result and Group Assignment

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/data_processing.md

Illustrates a sample PCA result for 5 documents and the corresponding group assignments derived by finding the maximum component index for each document.

```python
pca_result_50 = [
    [0.1, 0.5, 0.3, ...],    # max at index 1 → group 1
    [0.9, 0.2, 0.4, ...],    # max at index 0 → group 0
    [0.2, 0.1, 0.8, ...],    # max at index 2 → group 2
    [0.3, 0.6, 0.2, ...],    # max at index 1 → group 1
    [0.7, 0.3, 0.1, ...]     # max at index 0 → group 0
]
groups = [1, 0, 2, 1, 0]
```

--------------------------------

### Tooltip Usage Example

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Demonstrates how to conditionally render the Tooltip component based on hover state. The Html component is used to ensure pointer events are disabled for the tooltip.

```jsx
{hovered && (
  <Html style={{ pointerEvents: 'none' }}>
    <Tooltip tip={datum} settings={settings}></Tooltip>
  </Html>
)}
```

--------------------------------

### Initial Camera State

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/ui_controls.md

Sets the initial position of the 3D camera and the target for OrbitControls. The camera starts at [0, 0, -5] looking at the world origin.

```javascript
<Canvas camera={{ position: [0, 0, -5] }}>
  <OrbitControls target={[0, 0, 0]} />
</Canvas>
```

--------------------------------

### Request Main Visualization Interface

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

Use this endpoint to serve the main visualization interface HTML page. No authentication is required.

```bash
curl http://127.0.0.1:5000/
```

--------------------------------

### GET /data - Dimensional Reduction

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/MANIFEST.txt

Retrieves dimensionally reduced data for visualization.

```APIDOC
## GET /data

### Description
Retrieves dimensionally reduced data, typically after PCA or t-SNE processing.

### Method
GET

### Endpoint
/data

### Query Parameters
- **reduction_method** (string) - Optional - Specifies the reduction method (e.g., 'pca', 'tsne'). Defaults to 'tsne'.
- **dimensions** (integer) - Optional - The target number of dimensions. Defaults to 3.

### Response
#### Success Response (200)
- **points** (array) - Array of points with reduced dimensions.
- **labels** (array) - Labels corresponding to each point.
- **metadata** (array) - Metadata associated with each point.
```

--------------------------------

### HTTP API: GET /data

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/OVERVIEW.md

Initiates dimensional reduction processing and returns the resulting 3D points.

```APIDOC
## GET /data

### Description
Dimensional reduction processing, returns 3D points.

### Method
GET

### Endpoint
/data
```

--------------------------------

### Serve Frontend Assets

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

This endpoint serves compiled frontend assets like JavaScript bundles and CSS files. The Content-Type is determined by the file extension.

```bash
curl http://127.0.0.1:5000/assets/index-351494fc.js
```

```bash
curl http://127.0.0.1:5000/assets/index-26d05a53.css
```

--------------------------------

### Initialize and Run t-SNE

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/data_processing.md

Initializes the t-SNE model with specified parameters and transforms the PCA-reduced data into 3 dimensions. The output is then scaled by 1/3.

```python
tsne = TSNE(n_components=3, verbose=0, perplexity=40, n_iter=300)
tsne_pca_results = tsne.fit_transform(pca_result_50)
tsne_pca_results = tsne_pca_results / 3  # Scale by 1/3
```

--------------------------------

### visualize_collection() - ChromaViz Entry Point

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/MANIFEST.txt

The main entry point function for the ChromaViz library. It handles the visualization of collections with detailed parameter and return value documentation.

```APIDOC
## visualize_collection()

### Description
This is the main entry point for the chromaviz library, responsible for visualizing collections.

### Signature
(parameters with defaults)

### Parameters
- **param1** (type) - Required/Optional - Description of parameter 1
- **param2** (type) - Required/Optional - Description of parameter 2

### Return Value
Documentation of the return value.

### Usage Examples
- Basic usage example.
- Langchain integration example.

### Source Location
Reference to the source file.
```

--------------------------------

### PCA Algorithm Configuration

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/data_processing.md

Shows the default configuration options for the PCA algorithm, including parameters like n_components, copy, whiten, svd_solver, and random_state.

```python
PCA(
    n_components=50,
    copy=True,          # Don't modify input
    whiten=False,       # Don't standardize variance
    svd_solver='auto',  # Use optimal solver
    random_state=None   # Random initialization
)
```

--------------------------------

### GET /data

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

Performs dimensional reduction on embeddings and returns 3D visualization points. This endpoint does not require any request body or query parameters.

```APIDOC
## GET /data

### Description
Performs dimensional reduction on embeddings and returns 3D visualization points.

### Method
GET

### Endpoint
/data

### Parameters

No request body or query parameters are accepted.

### Request Example
```bash
curl http://127.0.0.1:5000/data
```

### Response
#### Success Response (200 OK)
- **points** (array) - Array of point objects, one per input document
  - **position** ([number, number, number]) - 3D coordinates for visualization after t-SNE reduction. Array of exactly 3 floats (x, y, z). Values typically range from -1.5 to 1.5.
  - **document** (string) - Original text from input documents array
  - **metadata** (object) - Original metadata object from input metadatas array
  - **id** (string) - Original document ID from input ids array
  - **group** (number) - Group assignment computed as argmax of 50-dimensional PCA result. Used for coloring related embeddings. Range: 0-49

#### Response Example
```json
{
  "points": [
    {
      "position": [0.82, -1.34, 0.56],
      "document": "The quick brown fox jumps over the lazy dog",
      "metadata": {
        "source": "animals.txt",
        "category": "mammals"
      },
      "id": "doc_001",
      "group": 5
    },
    {
      "position": [-0.45, 0.91, -0.23],
      "document": "A journey of a thousand miles begins with a single step",
      "metadata": {
        "source": "quotes.txt",
        "author": "Lao Tzu"
      },
      "id": "doc_002",
      "group": 12
    }
  ]
}
```
```

--------------------------------

### Vite Build Configuration

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/configuration.md

Basic Vite configuration for a React project, setting the base path and including the React plugin.

```javascript
export default defineConfig({
  plugins: [react()],
  base: ""
})
```

--------------------------------

### GET /data

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Performs dimensional reduction on the stored embeddings and returns 3D visualization points. Includes processing steps like PCA and t-SNE.

```APIDOC
## GET /data

### Description
Performs dimensional reduction on embeddings and returns 3D visualization points.

### Method
GET

### Endpoint
/data

### Response
#### Success Response (200 OK)
- Content-Type: application/json
- Body: JSON object with points array. Each point includes position, document, metadata, id, and group.

Response structure:
```json
{
  "points": [
    {
      "position": [x, y, z],
      "document": "original_text",
      "metadata": {key: value, ...},
      "id": "document_id",
      "group": 0
    },
    ...
  ]
}
```

### Request Example
```python
response = requests.get("http://127.0.0.1:5000/data")
data = response.json()
# data['points'] contains array of visualization points
for point in data['points']:
    print(f"Point {point['id']} at {point['position']}")
```
```

--------------------------------

### AppSettings Interface

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/types.md

Defines the configuration object for controlling visualization display options such as showing documents, metadata, and lines.

```typescript
interface AppSettings {
  showDocuments: boolean;
  showMetadata: boolean;
  showLines: boolean;
}
```

--------------------------------

### React AppSettings State Management

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/types.md

Demonstrates how to manage application settings using React's `useState` hook. Settings are passed as a tuple to child components and updated by toggling boolean flags.

```jsx
const [settings, setSettings] = useState({
  showDocuments: true,
  showMetadata: true,
  showLines: true
})

// Passed as tuple to child components
<Component settings={[settings, setSettings]} />

// Updated by toggling
setSettings({
  ...settings,
  showDocuments: !settings.showDocuments
})
```

--------------------------------

### Serve Frontend Assets

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

Serves compiled frontend assets such as JavaScript bundles and CSS files required by the visualization interface.

```APIDOC
## GET /assets/<path:filename>

### Description
Serves compiled frontend assets (JavaScript bundles, CSS files).

### Method
GET

### Endpoint
/assets/<path:filename>

### Parameters
#### Path Parameters
- **filename** (string) - Required - Path to asset file relative to assets directory (e.g., `index-351494fc.js`, `index-26d05a53.css`)

### Response
#### Success Response (200 OK)
- **Content-Type**: Determined by file extension (`text/javascript` for `.js`, `text/css` for `.css`, `text/html` for others).
- **Body**: Raw file contents.

### Request Example
```bash
curl http://127.0.0.1:5000/assets/index-351494fc.js
curl http://127.0.0.1:5000/assets/index-26d05a53.css
```
```

--------------------------------

### POST /import-data

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/REFERENCE_INDEX.md

Imports data into the visualization system.

```APIDOC
## POST /import-data

### Description
Imports data into the visualization system.

### Method
POST

### Endpoint
/import-data

### Response
#### Success Response (200)
- Indicates successful data import.
```

--------------------------------

### Visualize Collection in Python

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/REFERENCE_INDEX.md

Use this function to visualize a data collection. Specify the port for the web server.

```python
from chromaviz import visualize_collection
visualize_collection(col, port=5000)
```

--------------------------------

### GET /data Endpoint

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Performs dimensional reduction (PCA and t-SNE) on the stored embeddings and returns 3D visualization points. The response is a JSON object containing an array of points, each with position, document, metadata, id, and group.

```python
@app.route("/data", methods=["GET"])
def data_api()
```

```json
{
  "points": [
    {
      "position": [x, y, z],
      "document": "original_text",
      "metadata": {key: value, ...},
      "id": "document_id",
      "group": 0
    },
    ...
  ]
}
```

```python
response = requests.get("http://127.0.0.1:5000/data")
data = response.json()
# data['points'] contains array of visualization points
for point in data['points']:
    print(f"Point {point['id']} at {point['position']}")
```

--------------------------------

### ChromaViz Visualization with Langchain

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/OVERVIEW.md

Visualize a ChromaDB collection integrated with Langchain. This snippet assumes documents and embeddings are already set up.

```python
from langchain.vectorstores import Chroma
from chromaviz import visualize_collection

vectordb = Chroma.from_documents(documents, embeddings)
visualize_collection(vectordb._collection)
```

--------------------------------

### Serve Visualization Interface

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/endpoints.md

Serves the main visualization interface HTML page. This is the primary endpoint to access the ChromaViz application.

```APIDOC
## GET /

### Description
Serves the main visualization interface HTML page.

### Method
GET

### Endpoint
/

### Parameters
No request body or parameters.

### Response
#### Success Response (200 OK)
- **Content-Type**: text/html; charset=utf-8
- **Body**: Complete HTML document with embedded CSS and compiled JavaScript, loaded from `chromaviz/index.html`.

### Request Example
```bash
curl http://127.0.0.1:5000/
```

### Response Example (excerpt)
```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>ChromaViz</title>
    <style>...</style>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/assets/index-351494fc.js"></script>
  </body>
</html>
```
```

--------------------------------

### Footer

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Application footer component that displays version information and includes settings controls.

```APIDOC
## Footer

Application footer with version and controls.

### Props

- **settings** (object | function) - Required - Tuple of `[settings, setSettings]` from App state.

### Content

- Renders ButtonGroup with settings controls
- Displays version text: "chroma visualizer 0.0.2"

### Usage Example

```jsx
<Footer settings={[settings, setSettings]} />
```
```

--------------------------------

### Include Package Data

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/configuration.md

Configuration to include data files specified in MANIFEST.in for Python packages.

```toml
include_package_data = True
```

--------------------------------

### Application Footer

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/ui_controls.md

Renders the application footer, which includes a ButtonGroup for display toggles and the application version information. Note that the version displayed in the footer may be outdated.

```jsx
<div className="footer">
  <ButtonGroup settings={settings} />
  <h4>chroma visualizer 0.0.2</h4>
</div>
```

--------------------------------

### Initialize Flask App with CORS

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Initializes the Flask application and enables Cross-Origin Resource Sharing (CORS) to allow requests from the frontend.

```python
from flask import Flask
from flask_cors import CORS

app = Flask(__name__)
CORS(app)
```

--------------------------------

### Generated Project Files

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/README.md

Lists the files generated by the ChromaViz project, including README, overview, API specifications, type definitions, and configuration files.

```tree
output/
├── README.md                          # This file
├── OVERVIEW.md                        # Project summary and architecture
├── REFERENCE_INDEX.md                 # Complete navigation guide
├── endpoints.md                       # HTTP API specification
├── types.md                           # Type definitions
├── configuration.md                   # Configuration reference
└── api-reference/
    ├── visualize_collection.md        # Main entry point
    ├── flask_app.md                   # Flask app and endpoints
    ├── react_components.md            # React components
    ├── data_processing.md             # Dimensional reduction
    └── ui_controls.md                 # UI interactions
```

--------------------------------

### Configure Ambient and Hemisphere Lights

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/configuration.md

Use ambientLight for global illumination and hemisphereLight for directional gradient lighting. Adjust colors and intensity for desired visual effects.

```javascript
<ambientLight color="#ffffff" intensity={0.1} />
<hemisphereLight
  color="#ffffff"
  skyColor="#ffffbb"
  groundColor="#080820"
  intensity={1.0}
/>
```

--------------------------------

### ChromaViz Visualization on Custom Port

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/OVERVIEW.md

Visualize a ChromaDB collection and specify a custom port for the web interface. This will open the visualization at http://127.0.0.1:8080.

```python
visualize_collection(collection, port=8080)
# Opens http://127.0.0.1:8080
```

--------------------------------

### App

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Root component that manages application state and data fetching. It handles loading data from an API, managing loading and error states, and passing settings to child components.

```APIDOC
## App

Root component that manages application state and data fetching.

```jsx
function App()
```

### Props
- None (root component)

### State
- `data` (object): Visualization point data from `/data` endpoint, initially `[[]]`
- `loading` (boolean): Whether data is currently being fetched, initially `true`
- `error` (object|null): Error object if data fetch fails, initially `null`
- `settings` (object): Display settings object, initially `{showDocuments: true, showMetadata: true, showLines: true}`

### Behavior
1. On mount, fetches data from `http://127.0.0.1:5000/data`
2. Sets `loading = false` when data arrives or error occurs
3. Renders a centered loading spinner while `loading = true`
4. Renders visualization and footer controls when data is loaded
5. Passes settings state to child components as tuple `[settings, setSettings]`

### Usage Example
```jsx
import App from './App.jsx'
import ReactDOM from 'react-dom/client'

ReactDOM.createRoot(document.getElementById('root')).render(<App />)
```
```

--------------------------------

### Initialize Global Data Structure

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/types.md

The 'data' variable is initialized as an empty list of lists at module load. It is later populated with specific keys like 'embeddings', 'documents', 'metadatas', and 'ids'.

```python
data: Dict[str, Any] = [[]]  # Initially empty list of lists

# After population, structure:
data: Dict[str, List] = {
    'embeddings': List[List[float]],      # n_docs x embedding_dim
    'documents': List[str],               # n_docs
    'metadatas': List[Dict[str, Any]],   # n_docs
    'ids': List[str]                      # n_docs
}
```

--------------------------------

### Handle Toggle Documents

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/ui_controls.md

Updates the application settings to toggle the 'showDocuments' state. This handler is associated with the 'docs' button and affects tooltip content.

```javascript
const handleToggleDocuments = () => {
  settings.settings[1]({
    showDocuments: !settings.settings[0].showDocuments,
    showMetadata: settings.settings[0].showMetadata,
    showLines: settings.settings[0].showLines
  })
}
```

--------------------------------

### Default Visualization Display Settings

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/configuration.md

These are the default settings for controlling the display of documents, metadata, and convex hull lines in tooltips and visualizations. Adjust these to customize the information shown.

```javascript
{
  showDocuments: true,   // Display document text in tooltips
  showMetadata: true,    // Display metadata in tooltips
  showLines: true        // Render convex hull lines around groups
}
```

--------------------------------

### Footer Component Definition

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/react_components.md

Defines the application footer, which displays version information and settings controls. It accepts settings from the application state.

```jsx
const Footer = ({ settings }) => { ... }
```

--------------------------------

### POST /import-data Endpoint

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Receives embedding data in JSON format and stores it in the global 'data' variable. Expects a specific JSON structure for embeddings, documents, metadatas, and ids.

```python
@app.route("/import-data", methods=["POST"])
def import_data_api()
```

```json
{
  "embeddings": [[float, ...], ...],
  "documents": ["text", ...],
  "metadatas": [{key: value}, ...],
  "ids": ["id", ...]
}
```

```python
import requests
import json

data = {
    "embeddings": [[0.1, 0.2, ...], [0.3, 0.4, ...]],
    "documents": ["doc1", "doc2"],
    "metadatas": [{"type": "a"}, {"type": "b"}],
    "ids": ["id1", "id2"]
}
requests.post("http://127.0.0.1:5000/import-data", json=data)
```

--------------------------------

### Visualize Langchain Chroma Collection

Source: https://github.com/mtybadger/chromaviz/blob/main/README.md

Visualize a Chroma collection when using Langchain. This requires accessing the underlying ChromaDB collection object from the Langchain vector store.

```python
from langchain.vectorstores import Chroma
vectordb = Chroma.from_documents(data, embeddings, ids)

from chromaviz import visualize_collection
visualize_collection(vectordb._collection)
```

--------------------------------

### Display Loading Spinner

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/ui_controls.md

Conditionally displays a centered loading spinner using BarLoader while data is being fetched. The spinner is visible when the 'loading' state is true and is replaced by the visualization upon successful data retrieval.

```jsx
{loading && (
  <div style={{
    position: 'absolute',
    left: '50%',
    top: '50%',
    transform: 'translate(-50%, -50%)'
  }}>
    <BarLoader
      size={150}
      aria-label="Loading Spinner"
      data-testid="loader"
    />
  </div>
)}
```

--------------------------------

### Handle Toggle Metadata

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/ui_controls.md

Updates the application settings to toggle the 'showMetadata' state. This handler is associated with the 'metadata' button and controls the display of metadata in tooltips.

```javascript
const handleToggleMetadata = () => {
  settings.settings[1]({
    showDocuments: settings.settings[0].showDocuments,
    showMetadata: !settings.settings[0].showMetadata,
    showLines: settings.settings[0].showLines
  })
}
```

--------------------------------

### Print Explained Variance Ratio

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/data_processing.md

Calculates and prints the cumulative explained variance ratio of the selected PCA components. This indicates the proportion of the original data's variance that is retained in the reduced dimensions.

```python
print(np.sum(pca_50.explained_variance_ratio_))
# Output: e.g., 0.891 (89.1% of variance in first 50 components)
```

--------------------------------

### Generate Distinct Color Palette

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/configuration.md

Configure the distinct-colors package to generate a palette of a specified number of colors with constraints on lightness and chroma. Ensure parameters are set for visibility and saturation.

```javascript
const palette = distinctColors({
  count: 50,
  lightMin: 50,
  lightMax: 80,
  chromaMin: 70
})
```

--------------------------------

### POST /import-data

Source: https://github.com/mtybadger/chromaviz/blob/main/_autodocs/api-reference/flask_app.md

Receives and stores embedding data in global memory for processing. Expects a JSON payload containing embeddings, documents, metadatas, and ids.

```APIDOC
## POST /import-data

### Description
Receives and stores embedding data in global memory for processing.

### Method
POST

### Endpoint
/import-data

### Request Body
- **embeddings** (list of lists of floats) - Required - List of embedding vectors.
- **documents** (list of strings) - Required - List of corresponding document texts.
- **metadatas** (list of objects) - Required - List of metadata objects for each document.
- **ids** (list of strings) - Required - List of unique identifiers for each document.

### Request Example
```python
import requests
import json

data = {
    "embeddings": [[0.1, 0.2, ...], [0.3, 0.4, ...]],
    "documents": ["doc1", "doc2"],
    "metadatas": [{"type": "a"}, {"type": "b"}],
    "ids": ["id1", "id2"]
}
requests.post("http://127.0.0.1:5000/import-data", json=data)
```

### Response
#### Success Response (204 No Content)
- Body: Empty
```