# How to Integrate the Bambu Lab Dataset with AI Assistants for Analysis

> Integrate the Bambu Lab dataset with AI assistants for analysis. Download the public manifest, merge Parquet shards into DuckDB, and upload to LLMs for natural language insights.

- Repository: [Nelson Chen/bbl-tracker-public-db](https://github.com/nelsonjchen/bbl-tracker-public-db)
- Tags: how-to-guide
- Published: 2026-03-08

---

**You can integrate the Bambu Lab Store Filament Tracker dataset with AI assistants by downloading the public manifest, merging Parquet shards into a local DuckDB file using the provided Python scripts, and uploading the resulting database to any code-interpreter-enabled LLM for natural language analysis.**

The **nelsonjchen/bbl-tracker-public-db** repository provides a complete, zero-setup pipeline for querying historical 3D printer filament stock data and preparing it for AI-driven analysis. This guide shows you how to use the official helper scripts to extract insights from the Cloudflare R2-hosted dataset and feed them directly into ChatGPT, Claude, or Gemini.

## Understanding the Dataset Architecture

The Bambu Lab dataset is structured as a streaming collection of **Parquet shards** updated every six hours, indexed by a central manifest file.

### The Manifest and Parquet Shards

At `https://db-public.bbltracker.com/manifest.json`, the **manifest** lists every available shard with row counts and timestamps. Each shard follows the naming pattern `YYYY-MM-DD-HHMM.parquet`, representing a 6-hour inventory snapshot. According to the repository's [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md), this deterministic naming scheme allows clients to construct URLs directly without requiring bucket listing permissions.

### Schema Design for Instant Querying

Every Parquet file contains the same flat schema optimized for SQL querying:

- `timestamp` – When the snapshot was taken
- `product_name` – Filament type (e.g., "Black PETG")
- `variant_name` – Specific SKU details
- `stock` – Available units
- `region` – Geographic market (e.g., "us", "eu")
- `eta` – Restock estimate
- `max_quantity` – Purchase limits
- `is_flash_sale` – Promotion flag

Because all columns use primitive types, **DuckDB** can read and aggregate these files directly over HTTP without local caching.

## Setting Up Your Local Environment

The repository requires only Python 3.12+ and two pip dependencies (`duckdb`, `pandas`). The maintainers recommend using **uv** for fast environment provisioning.

Install uv and run the quick-look script:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv run script.py

```

This prints a real-time availability table for the last 24 hours, showing which filaments are in stock and their historical fill rates.

## Querying the Data with DuckDB

The repository provides two primary scripts in the root directory that demonstrate different access patterns for the dataset.

### Quick Analysis of Recent Stock ([`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py))

The [`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py) file fetches the manifest, selects the four most recent shards (covering the last 24 hours), and calculates **availability percentages** per variant for the US region. It uses DuckDB's `read_parquet()` to stream remote files directly into a DataFrame.

Example output from the script:

```

full_name                     availability_pct   max_stock_seen   cap_seen
---------------------------------------------------------------
Black PETG - ...                     0.7                1           10
...

```

This pattern is ideal for monitoring current bottlenecks without persisting data locally.

### Building a 30-Day Local Database ([`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py))

For AI assistant integration, use [`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py) to materialize a queryable snapshot:

```bash
uv run reconstruct_db.py

```

This script filters all shards from the last 30 days (based on the filename timestamps), streams them via `read_parquet()`, and writes the merged results to `bambu_stock.duckdb`. The output confirms the operation:

```

--- Bambu Stock DB Reconstructor ---
Fetching manifest...
Found 432 total shards.
Filtering for past 30 days (>= 2026-02-16)... 120 files selected.
Creating bambu_stock.duckdb...
Success! Imported 3,254,876 rows into 'bambu_stock.duckdb'.

```

The resulting file contains a single table `stock_history` that you can upload to any AI code interpreter.

### Direct Remote Queries Without Downloading

You can also query specific date ranges without creating a local database:

```python
import duckdb

# Build URLs for February 20, 2026

urls = [
    f"https://db-public.bbltracker.com/2026-02-20-{h:02d}00.parquet"
    for h in (0, 6, 12, 18)
]

df = duckdb.read_parquet(urls).filter("region = 'us'").df()

```

This approach works in Jupyter notebooks, browser-based Python environments, or any tool with HTTPS access to the Cloudflare R2 endpoint.

## Feeding Data to AI Assistants

Once you have `bambu_stock.duckdb`, integrating with AI assistants requires three steps:

1. **Upload the file** to ChatGPT Code Interpreter, Claude 3 Opus, or Gemini Advanced.
2. **Prompt the assistant** to connect via DuckDB and run analytical queries.
3. **Request visualizations** or statistical summaries in natural language.

### Example AI Assistant Workflow

Upload the database, then use this prompt:

> *"Using the uploaded DuckDB file, give me a line chart of Black PETG availability over the last 30 days, and tell me the longest continuous window where it was in stock."*

The assistant can execute Python code equivalent to:

```python
import duckdb, pandas as pd, matplotlib.pyplot as plt

con = duckdb.connect("bambu_stock.duckdb")
df = con.execute("""
    SELECT timestamp::timestamp AS ts,
           stock
    FROM stock_history
    WHERE product_name = 'Black PETG' AND region = 'us'
    ORDER BY ts
""").df()

# Calculate longest continuous in-stock window

df['in_stock'] = df.stock > 0
df['gap'] = (df['in_stock'] != df['in_stock'].shift()).cumsum()
longest_run = df[df.in_stock].groupby('gap').size().max()

# Visualize

plt.plot(df.ts, df.stock)
plt.title('Black PETG Stock Over Time')
plt.show()
print(f"Longest continuous in-stock window: {longest_run} snapshots")

```

The LLM returns both the rendered chart and the numeric analysis, combining the granular historical data with natural language reasoning.

## Summary

- The **manifest.json** file at `db-public.bbltracker.com` indexes all 6-hour Parquet shards for deterministic access.
- **[`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py)** provides immediate 24-hour availability analysis using DuckDB's remote Parquet streaming.
- **[`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py)** merges 30 days of data into `bambu_stock.duckdb`, creating a portable file for AI assistants.
- The schema uses primitive types only, enabling zero-copy queries across Python, DuckDB, and LLM code interpreters.
- Uploading the DuckDB file to ChatGPT, Claude, or Gemini allows natural language exploration of restock patterns, regional availability, and flash sale timing.

## Frequently Asked Questions

### Do I need to download all Parquet files to query the dataset?

No. Both [`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py) and [`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py) use **DuckDB's `read_parquet()`** function to stream shards directly from the Cloudflare R2 CDN. Only [`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py) creates a local file (`bambu_stock.duckdb`) if you specifically want to upload data to an AI assistant. For ad-hoc queries, you can query remote URLs without persisting anything locally.

### What Python version and dependencies are required?

The repository targets **Python 3.12+** and requires only `duckdb` and `pandas`. The scripts include logic to handle the manifest parsing and URL construction automatically. While you can use standard pip, the repository documentation recommends **uv** for faster dependency resolution and script execution.

### Can I query the dataset without using the provided scripts?

Yes. Because the **manifest.json** structure is public and the Parquet files follow a deterministic `YYYY-MM-DD-HHMM.parquet` naming scheme, you can construct URLs manually or via any HTTP client. DuckDB, Polars, Pandas, and Arrow-based tools can read these Parquet files directly over HTTPS using the appropriate `read_parquet` or `scan_parquet` functions.

### Is the dataset free for commercial AI training and analysis?

The data is published under the **Open Data Commons ODbL** license (see `LICENSE` in the repository). This permits commercial use, modification, and sharing, provided you attribute the source and share-alike any derived databases. You can legally use this stock history to train models, generate reports, or power commercial inventory prediction tools.