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.
- Bump
versioninpyproject.toml(uv version --bump minor, say) and merge it tomain. - Create a GitHub release whose tag is
vplus that version, e.g.v2.1.0. - 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 thepypienvironment deployment if it asks. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.