SciVis Embeddings Workbench

Getting Started

These steps are intended for someone running the project locally for the first time.

1) Prerequisites

• Python 3.13+
• uv for dependency management
• Git

2) Clone the repository

git clone https://github.com/NCAR/bams-ai-data-exploration.git
cd bams-ai-data-exploration

3) Install dependencies

uv sync

This creates or updates a local virtual environment and installs dependencies from pyproject.toml and uv.lock.

4) Run notebooks

Start Jupyter and open any notebook under the notebooks/ directory.

uv run jupyter notebook

5) Run the Python entry point (optional)

uv run python main.py

What To Do Next

After your environment is working, a good next path is:

1. Open notebooks/01-prepare-data/ and run the notebooks from top to bottom.
2. Move to notebooks/02-generate-embeddings/.
3. Use the Colab badge above if you prefer a hosted environment instead of local setup.

How to Review and Contribute

Review local changes

git status
git diff

Run tests before opening a PR

uv run pytest tests/ -v

Create a contribution branch

git checkout -b <short-feature-name>

Commit and push your changes

git add .
git commit -m "Describe your change"
git push -u origin <short-feature-name>

Open a pull request

1. Open your branch in GitHub.
2. Create a PR into main.
3. Include:
   • What changed
   • Why it changed
   • How you tested it

Development Tips

• Keep dependencies updated with uv lock and uv sync.
• Keep notebook and script changes focused so they are easier to review.