open-knowledge-format README

The project's README from github.com/GoogleCloudPlatform/open-knowledge-format. As one markdown file: README.md.

Open Knowledge Format (OKF)

📖 Read the Open Knowledge Format v0.2 specification → SPEC.md

This repository is primarily about the Open Knowledge Format (OKF).

OKF is a universal, vendor-neutral format for representing knowledge as plain markdown files with YAML frontmatter. It is not tied to any particular agent, framework, model provider, or serving system. The goal is simple:

  • Anyone can produce OKF — humans authoring by hand, agents built on any framework (Google ADK, LangChain, custom), export pipelines from existing catalogs (Dataplex, Unity Catalog, Collibra, …), or scripts walking a database.
  • Anyone can serve and consume OKF — a static file server, a knowledge-management UI (Obsidian, Notion, MkDocs), an LLM loading files into context, a search index, or a graph viewer like the one bundled in this repo.

The agent below is a proof of concept demonstrating one way to produce OKF bundles automatically. The format itself is the contribution; this agent and the visualizer exist to make the format tangible at both ends — production and consumption.

See OKF in practice — three ready-to-browse bundles produced by this agent, checked into bundles/:

Why OKF?

OKF represents catalog knowledge as plain markdown files with YAML frontmatter, organized in a directory hierarchy. That choice unlocks a few properties that are hard to get from a service-owned metadata store:

The net effect is that reference agents, consumption agents, and humans collaborate on the same artifacts in the same way they already collaborate on source code.

Install

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

Credentials

How the reference agent works

The reference agent runs in two passes. The BQ pass writes one OKF doc per concept the source advertises, using BigQuery metadata alone. The web pass then runs the LLM as its own crawler: it receives a list of seed URLs (provided via --web-seed or --web-seed-file), fetches the seeds via the fetch_url tool, and decides which outbound links are worth following based on whether they look like authoritative documentation for the existing concepts. For each page it fetches, the agent chooses to (a) enrich one or more existing concept docs, (b) mint a standalone references/<slug> doc, or (c) skip. A hard --web-max-pages cap and a same-domain allowed-hosts filter (configurable via --web-allowed-host) are enforced inside the tool, so the agent cannot overrun. Use --no-web to skip the web pass.

Run

Minimum invocation — point at a BigQuery dataset and a bundle output directory. Seeds for the web pass are explicit; omit them (or pass --no-web) to run BQ-only:

.venv/bin/python -m reference_agent enrich \
    --source bq \
    --dataset <project>.<dataset> \
    --web-seed-file <path/to/seeds.txt> \
    --out ./bundles/<name>

Iterate on a single concept by adding --concept <type>/<name> (e.g. --concept tables/events_); repeatable.

Samples

Each sample pairs a recipe (samples/<name>/, with the seed URLs and exact enrich command) with the produced bundle (bundles/<name>/) that the recipe generated. Open the recipe to reproduce; open the bundle to browse the result directly.

Visualize

The visualize subcommand renders any OKF bundle as a self-contained interactive HTML file — one file, no backend, no install on the viewing side. Open it in any modern browser, share it as an artifact, host it on a static file server, or commit it next to the bundle (as this repo does).

The viewer is itself a proof-of-concept consumer of OKF, mirroring the way the reference agent is a proof-of-concept producer. OKF bundles can be consumed by anything that reads markdown; this is just one shape.

What it shows

Generate

.venv/bin/python -m reference_agent visualize --bundle ./bundles/<name>

That writes bundles/<name>/viz.html. Flags:

Flag Default Description
--bundle (required) Bundle root directory.
--out <bundle>/viz.html Output HTML path.
--name bundle directory name Display name shown in the viewer header.

Example, writing the output somewhere else and overriding the header:

.venv/bin/python -m reference_agent visualize \
    --bundle ./bundles/crypto_bitcoin \
    --out /tmp/btc.html \
    --name "Bitcoin OKF"

How it's built

The HTML embeds the bundle as a JSON blob and uses Cytoscape.js for the graph and marked for in-browser markdown rendering, both loaded from a CDN. No data leaves the page; the bundle is parsed once at generation time and serialized into the file.

Tests

.venv/bin/pytest

open-knowledge-format (GoogleCloudPlatform/open-knowledge-format)

Searching Database…

1K ·GitHub
Open-knowledge-format
Что это?OKF (Open Knowledge Format) — вендор-нейтральная спецификация от Google Cloud для представления знаний каталога в виде простых markdown-файлов с YAML-frontmatter, не привязанная ни к какому конкретному агенту, фреймворку или провайдеру моделей. Этот репозиторий также содержит референс-агента, создающего OKF-бандлы, и визуализатор, который их отрисовывает.
Это просто спецификация формата файлов или в комплекте есть и рабочие инструменты?И то и другое: SPEC.md определяет сам формат v0.2, а в репозиторий входят Python-агент уровня proof-of-concept, который автоматически создаёт OKF-бандлы из BigQuery и веб-документации, и отдельная команда visualize, превращающая любой бандл в интерактивный HTML-граф.
Как сгенерировать OKF-бандл с помощью референс-агента?Укажите агенту датасет BigQuery и каталог вывода для бандла; он пишет по одному документу на концепт из метаданных BigQuery, затем опционально обходит стартовые URL, переданные через --web-seed, чтобы обогатить эти документы, а после можно запустить сабкоманду visualize и получить viz.html.
Какие учётные данные нужны референс-агенту перед запуском?Нужен gcloud с аутентификацией через application-default login плюс биллинг-проект для доступа к BigQuery, а для LLM — либо GEMINI_API_KEY из AI Studio, либо переменные окружения Vertex AI (GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION).
Не сходит ли веб-краулинг агента с ума по всему интернету?Нет — он ограничен лимитом --web-max-pages и фильтром доменов allowed-hosts, настраиваемым через --web-allowed-host, а весь веб-этап можно пропустить с --no-web и работать только с BigQuery.
Отправляет ли сгенерированный viz.html данные бандла куда-то ещё?Нет, вьюер — это один автономный HTML-файл, в который бандл встроен в виде JSON-блоба; при открытии в браузере ничего наружу не отправляется.
Какие примеры бандлов идут с репозиторием?В bundles/ закоммичены четыре готовых к просмотру бандла: GA4 (датасет электронной коммерции Google Analytics), Stack Overflow (публичная схема), Bitcoin (блоки/транзакции) и Acme Retail, у каждого свой viz.html.
Что на самом деле показывает OKF-вьюер?Граф концепций с силовой раскладкой, раскрашенный по типам, с рёбрами перекрёстных ссылок; панель деталей с frontmatter и отрендеренным markdown выбранного концепта; список обратных ссылок «Cited by»; плюс поиск, фильтр по типу и переключаемые раскладки (cose, concentric, breadth-first, circle, grid).
Зачем markdown и YAML-frontmatter вместо каталога на базе базы данных?Потому что это читаемо людьми и агентами без SDK, живёт в git для диффов/PR/ревью, распространяется простыми переносимыми файлами без привязки к вендору и всё же позволяет запрашивать небольшой набор структурированных полей frontmatter вроде type, tags и сигналов доверия.
Как визуализатор отрисовывает граф без бэкенда?Он встраивает весь бандл в виде JSON-блоба в один HTML-файл и использует Cytoscape.js для графа и marked для рендеринга markdown в браузере — обе библиотеки подтягиваются с CDN, так что итоговый файл работает автономно в любом современном браузере.
What are similar projects?skills, openwiki, Athena-Public, wikiskill, OpenLore, knowledge-catalog, agents-cli, skills
Which topics is it in?graph-visualization, data-warehouse, gcp, specification, graph, yaml, knowledge-management, knowledge-graph, google, data-visualization, knowledge-base, gemini
Creator
GoogleCloudPlatform
Size
0.2 MB
Stars
1K
Updated
CommitAug 21
Age
2mo
Commits · 90 Days