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

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, 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:

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)

The 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)

For AI assistant integration, use reconstruct_db.py to materialize a queryable snapshot:

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:

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:

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 provides immediate 24-hour availability analysis using DuckDB's remote Parquet streaming.
• 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 and reconstruct_db.py use DuckDB's read_parquet() function to stream shards directly from the Cloudflare R2 CDN. Only 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}