Skip to main content

Blue Core Graph Toolbox

Web Application for loading and manipulating Blue Core RDF.

The Toolbox is being rebuilt as an Airflow 3 plugin that runs inside Blue Core Workflows. The original standalone PyScript site has been removed; its screens are being rebuilt as Toolbox applications.

SPARQL queries and graph analysis will run in the browser, using PyScript and rdflib, over RDF loaded from Blue Core. The plugin has no backend SPARQL endpoint.

Existing and Planned Functionality

  • Run SPARQL queries on one or more Blue Core Resources
  • Download RDF in various serializations like Turtle, XML/RDF, and json-ld
  • Chat with Blue Core AI Agents
  • Import and convert MARC to Blue Core BIBFRAME Resources
  • Export Blue Core Constrained Bound Descriptions (CBD) to MARC21 records

Running as an Airflow plugin

The bluecore_graph_toolbox package registers itself with Airflow through the airflow.plugins entry point, so installing it into the Airflow environment is all that's needed; nothing goes in the plugins folder. Shared helpers, the base template and styles come from bluecore-airflow-common.

Requires Python 3.12 and Airflow 3.2 or later (tested against 3.3.2).

Releases are published to PyPI as bluecore-graph-toolbox

uv build
uv add bluecore-graph-toolbox

In bluecore-workflows, add the pin to dependencies in its pyproject.toml and run uv lock; the Docker image installs it from the lockfile, so no wheel is copied in. When a new Toolbox release adds screens or API routes, bump that pin and uv lock again in a Workflows pull request.

Once installed, a Toolbox item appears in the Airflow navigation. The UI shows it in an iframe at /plugin/graph-toolbox; the app itself is mounted at /graph-toolbox:

Route Sign-in Purpose
GET /graph-toolbox/ required Landing page
GET /graph-toolbox/api/config required Browser-safe settings: {"version", "public_url"}
GET /graph-toolbox/dashboard required Dashboard (stub, #45)
GET /graph-toolbox/marc-bibframe-operations required MARC and BIBFRAME operations (stub, #46)
GET /graph-toolbox/sparql required SPARQL Query and Update (stub, #54)
GET /graph-toolbox/ai-search required AI-Assisted Search (stub, #39)
GET /graph-toolbox/health none {"status", "version"}
/graph-toolbox/static/… none Toolbox and shared Blue Core assets

Each stub answers {"application", "implemented": false, "issue"} until its ticket replaces it. Errors from every route use one shape, {"error": {"code", "message", "upstream_status", "request_id"}}; details are logged under the request_id, never returned.

Sign-in is Airflow's own: the page uses Airflow's JWT cookie (Keycloak in a Blue Core stack), and the Toolbox has no login of its own.

All URLs follow [api] base_url, so the same build works with Airflow at the root or proxied under a path such as /workflows (AIRFLOW__API__BASE_URL=http://localhost/workflows), where the routes above become /workflows/graph-toolbox/….

Configuration

The Toolbox adds no settings of its own. It reads the Blue Core integration settings from bluecore-airflow-common, from the same environment variables the rest of the bluecore-stack passes to every Airflow container:

Variable Required Meaning
BLUECORE_API_INTERNAL_URL yes Blue Core API root as the Airflow containers reach it, e.g. http://bc_api:8100. Never sent to browsers.
BLUECORE_URL yes Blue Core site root as browsers reach it, e.g. https://bcld.info. Returned by /api/config as public_url.
AIRFLOW_API_INTERNAL_URL yes Airflow root as the plugin reaches it, e.g. http://airflow-apiserver:8080/workflows. Never sent to browsers.
BLUECORE_REQUEST_TIMEOUT no Seconds allowed for each upstream request. Default 10.
BLUECORE_MAX_RETRIES no Retries for GET and HEAD requests only. Default 2, at most 5.

There is one environment per deployment: no route accepts an environment or API URL, and the UI has no environment selector. Missing or invalid settings are logged when the plugin loads, and only the routes that need them fail.

Calls to Blue Core and Airflow are made as the signed-in user, with their own Keycloak and Airflow tokens, never a shared service account. Leave API_KEYCLOAK_USER and API_KEYCLOAK_PASSWORD unset in the Airflow containers. Tokens are redacted from the logs.

The service contracts the Toolbox applications build on are in bluecore-airflow-common's integration contracts.

Development

uv sync
uv run ruff check
uv run ruff format --check
uv run pytest

Releasing

Releases go to PyPI from .github/workflows/python-publish.yml using trusted publishing, so no API token is stored in the repo.

  1. Bump version in pyproject.toml (uv version --bump minor, say) and merge it to main.
  2. Create a GitHub release whose tag is v plus that version, e.g. v2.1.0.
  3. Publishing the release runs the workflow: it checks the tag against pyproject.toml, runs the tests, builds the wheel and sdist, checks that the wheel installs as an Airflow plugin, and uploads both to PyPI. Approve the pypi environment deployment if it asks.
  4. Bump the pin in bluecore-workflows as described above.

Metadata

Release files for bluecore-graph-toolbox 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bluecore-graph-toolbox 2.1.0
File Size Uploaded Provenance Actions
bluecore_graph_toolbox-2.1.0.tar.gz 17.3 kB With provenance Details for bluecore_graph_toolbox-2.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bluecore-graph-toolbox 2.1.0
File Interpreter ABI Platform Actions
bluecore_graph_toolbox-2.1.0-py3-none-any.whl Python 3 none any Details for bluecore_graph_toolbox-2.1.0-py3-none-any.whl

Total release size: 36.0 kB

Release files / bluecore_graph_toolbox-2.1.0.tar.gz

Download URL bluecore_graph_toolbox-2.1.0.tar.gz
Size 17.3 kB
Tags Source
SHA-256 checksum
How to use checksums
3d948c3288c4f9e1e7de1e3a7321f5d6ec6998ac20a32cd4d510e710c85a4303
BLAKE2b-256 checksum
How to use checksums
7f6c064439c5b053b2d15aebf1825959855f8fe76472fe5dd21f72978b0c26bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / bluecore_graph_toolbox-2.1.0-py3-none-any.whl

Download URL bluecore_graph_toolbox-2.1.0-py3-none-any.whl
Size 18.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bd563003e48dfbedbab6eceb09f00608d4d2cc4855494fc3aa5183c0ce4be8e1
BLAKE2b-256 checksum
How to use checksums
bb54343250c6b63fe6557abe448d512b48f16b8dee6aae5bfd3160679fef5a40
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for bluecore-graph-toolbox 2.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for bluecore_graph_toolbox-2.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page