How to Run samples in OKF repo?

1. Clone the repository

git clone https://github.com/GoogleCloudPlatform/open-knowledge-format.git

cd open-knowledge-format

he current repository expects Python 3.13 and installs the project in editable mode

python3.13 -m venv .venv

source .venv/bin/activate

.venv/bin/pip install --index-url https://pypi.org/simple/ -e ".[dev]"

python -m reference_agent --help

2. Easiest way: use the existing sample bundles

You do not need BigQuery or Gemini initially just to see the visualization.

The repository already contains bundles such as:

GA4

Stack Overflow

Bitcoin

Acme Retail

and each has a viz.html.

For example:

ls bundles

You should see directories similar to:

stackoverflow

crypto_bitcoin

acme_retail

Then generate the visualization yourself:

.venv/bin/python -m reference_agent visualize \

    --bundle ./bundles/ga4

bundles/ga4/viz.html

The visualize command generates a self-contained interactive HTML file, so you don't need to run a web server or database to view it.

3. Open the visualization

On macOS:

open bundles/ga4/viz.html

open bundles/crypto_bitcoin/viz.html

You can also simply double-click the viz.html file in Finder.

The visualization contains a knowledge graph:

              ┌─────────────┐

              │   Dataset   │

              └──────┬──────┘

                     │

          ┌──────────┼──────────┐

          ▼          ▼          ▼

      ┌────────┐ ┌────────┐ ┌────────┐

      │ Table  │ │ Table  │ │ Table  │

      └───┬────┘ └───┬────┘ └───┬────┘

          │          │          │

          └──────────┼──────────┘

                     ▼

               ┌──────────┐

               │Reference │

               └──────────┘

The viewer provides a force-directed graph, concept details, backlinks, search, type filtering, and several graph layouts.