Ferramentas do Ecossistema OKF

Curadoria honesta das ferramentas que existem hoje (jun/2026) ao redor do Open Knowledge Format. Para cada item: o que faz, como usar, onde encontrar, e minha opinião sobre maturidade.

1. Enrichment Agent (OKF — BigQuery → Bundles)

O que é: Agente de referência que ingere metadata de uma fonte plugável (hoje BigQuery) e cospe um bundle OKF completo — diretório de markdowns com YAML frontmatter prontos pra humanos, LLMs e ferramentas de catálogo.

Como funciona:

• BQ pass: Gera um doc OKF por conceito usando só metadados do BigQuery (schemas, descrições, tabelas).
• Web pass: O LLM (Gemini via ADK) vira crawler: recebe seed URLs, decide quais links são documentação autoritativa, e enriquece docs existentes ou cria docs de referência novos.

Stack: Python 3.13, Google Agent Development Kit (ADK), Gemini como backend de modelo.

Como rodar:

# Instalar
python3.13 -m venv .venv
.venv/bin/pip install -e .[dev]

# Credenciais
gcloud auth application-default login
export GEMINI_API_KEY=<sua-key>  # ou Vertex AI

# Rodar (mínimo)
.venv/bin/python -m enrichment_agent enrich \
    --source bq \
    --dataset <project>.<dataset> \
    --web-seed-file seeds.txt \
    --out ./bundles/<nome>

# Só BigQuery (sem web crawl)
.venv/bin/python -m enrichment_agent enrich \
    --source bq \
    --dataset bigquery-public-data.ga4_obfuscated_sample_ecommerce \
    --no-web \
    --out ./bundles/ga4

Bundles de exemplo incluídos:

• bundles/ga4/ — GA4 e-commerce
• bundles/stackoverflow/ — Stack Overflow public dataset
• bundles/crypto_bitcoin/ — Bitcoin blocks/transactions

Link: github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf

Limitações:

• Só BigQuery como source (a interface Source existe mas ninguém implementou outra)
• Exige Gemini API key ou Vertex AI configurado
• Web pass pode queimar bastante token se os seeds forem muitos
• Não faz incremental updates — roda do zero cada vez

🟡 Maturidade: Proof of concept funcional. Os bundles gerados são legítimos, mas o agente em si é demo do que dá pra fazer, não produto pronto. Funciona bem pra datasets públicos do BigQuery. Pra produção, você vai querer customizar prompt e seeds.

2. Static HTML Visualizer (viz.html)

O que é: Subcomando visualize que pega qualquer bundle OKF e gera um HTML self-contained — grafo interativo de conceitos, painel de detalhes, busca, filtros por tipo, backlinks. Zero backend, zero instalação pro viewer.

O que mostra:

• Grafo force-directed (Cytoscape.js) com nós coloridos por tipo
• Painel lateral com frontmatter + body renderizado
• Links internos navegáveis dentro do próprio viewer
• Seção “Cited by” (backlinks computados)
• Busca por título, ID, tags
• Layouts alternativos (cose, concentric, breadthfirst, circle, grid)

Como gerar:

.venv/bin/python -m enrichment_agent visualize --bundle ./bundles/ga4
# Gera bundles/ga4/viz.html

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

Como consumir: Abra o viz.html em qualquer browser moderno. Pode hospedar em file server estático, compartilhar por email, commitar no repo.

Link: Mesmo repo — okf/README.md#visualize

Limitações:

• Bundles grandes geram HTMLs pesados (tudo inline no JSON)
• Viewer é SPA minimal — sem paginação, sem lazy loading
• Depende de CDN pra Cytoscape.js e marked.js (não é 100% offline sem ajuste)

🟢 Maturidade: Funciona de verdade. Simples, faz o que promete. Pra bundles de 10-50 conceitos, perfeito. Pra 500+, provavelmente precisa de otimização.

3. Metadata as Code (kcmd) — Sync com Knowledge Catalog

O que é: Sync bidirecional entre metadata local (YAML/markdown no filesystem) e o Google Cloud Knowledge Catalog (antigo Dataplex). Tipo “git para metadados” — edita localmente, faz push/pull pro catálogo cloud.

Formato: YAML pra entries, sidecar .md pra conteúdos ricos (overviews, descriptions). Organização hierárquica espelhando a estrutura de recursos.

Distribuição: TypeScript library (npm install kcmd), CLI standalone (kcmd), e MCP server.

Como usar (CLI):

# Inicializar snapshot de um dataset BigQuery
kcmd init --bigquery-dataset <projectId>.<datasetId>

# Puxar metadata do catálogo
kcmd pull

# Ver mudanças locais
kcmd status

# Enviar mudanças para o catálogo (com dry-run)
kcmd push --dry-run
kcmd push

Como usar (MCP Server):

{
  "mcpServers": {
    "kc-mac": {
      "command": "kcmd",
      "args": ["mcp", "--path", "/path/to/root"]
    }
  }
}

Tools MCP disponíveis: pull, push, list-entries, lookup-entry, modify-entry.

Link: github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode

Limitações:

• Exige projeto GCP com Knowledge Catalog habilitado
• Auth via gcloud (não suporta service accounts direto)
• Formato YAML/sidecar difere do OKF puro (mais voltado pro Dataplex)
• Docs ainda esparsa

🟡 Maturidade: Early product, mas bem pensado. CLI funciona, MCP server é real, workflow push/pull faz sentido. O fato de ter library + CLI + MCP mostra intenção de servir ambientes variados. Ainda sem releases versionadas no npm.

4. Enrichment Agent (Toolbox — kcenrich)

O que é: Versão mais “production-oriented” do enrichment, integrada ao workflow do kcmd. Diferente do agente OKF (que gera bundles standalone), este enriquece metadata já no formato do catálogo.

Diferença do agente OKF:

• O OKF agent gera bundles markdown autônomos
• O kcenrich enriquece snapshots do Knowledge Catalog (formato kcmd)
• Usa MCP servers como sources (ex: md-fileset pra crawlear docs locais)
• Customizável via prompt.md + diretório de tools/skills/

Como usar:

# Pré-requisito: ter um snapshot kcmd já inicializado
kcmd init --bigquery-dataset <project>.<dataset>
kcmd pull

# Rodar enrichment com tools customizados
kcagent enrich --catalog-path . --tools-path tools --prompt-path prompt.md

Link: github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/enrichment

Limitações:

• Depende do kcmd configurado
• Demo funciona mas exige setup BigQuery real
• Sem release binário standalone

🟠 Maturidade: Mais proof of concept que produto. O demo é didático, mas é showcase de como combinar MCP + skills + catálogo. Não é “instala e sai usando” — precisa montar a infra de tools por volta.

5. Google Cloud Knowledge Catalog (Ingestão Nativa)

O que é: O produto GCP (antigo Dataplex) que serve de catálogo de metadados AI-powered. É o “backend oficial” com quem o ecossistema de ferramentas acima sincroniza.

Features relevantes pra OKF:

• Harvesting automático de BigQuery, AlloyDB, Spanner, Cloud SQL, Firestore, Looker
• Integrações 3P: Ab Initio, Anomalo, Atlan, Collibra, Datahub
• Enrichment nativo com Gemini — gera descrições, glossários, mapeia entidades
• Semantic search sub-segundo pra agentes
• Context APIs + MCP tools pra agentes descobrirem assets
• Data products — empacotamento de assets com SLAs e governança

Pricing (resumo):

• Free tier: 100 DCU-hour/mês + 1 MiB storage + 1M API calls/mês
• Standard: $0.06/DCU-hour
• Premium (lineage, quality, profiling): $0.089/DCU-hour
• Storage: $2/GiB/mês (acima de 1 MiB)

Link: cloud.google.com/products/knowledge-catalog

Limitações:

• Vendor lock-in GCP (o kcmd é a ponte pra portabilidade)
• Pricing escala rápido com muitos DCU-hours
• Formato nativo NÃO é OKF — OKF é a camada portável que interopera

🟢 Maturidade: Produto GA do Google Cloud. Real, em produção, com SLA e suporte enterprise. O Knowledge Catalog em si tá maduro — o que é novo são as ferramentas open-source ao redor.

6. Possíveis Integrações

6.1 Obsidian

Status: Não tem plugin oficial, mas o OKF foi deliberadamente desenhado pra funcionar com Obsidian out-of-the-box.

Por que funciona:

• Bundles OKF são diretórios de .md com YAML frontmatter — exatamente o que o Obsidian espera
• Links internos funcionam como wikilinks (paths relativos)
• Tags do frontmatter aparecem nativamente
• O index.md funciona como nota índice

Como usar hoje:

1. Gere um bundle OKF com o enrichment agent
2. Abra o diretório como vault no Obsidian
3. Navegue, edite, use o graph view nativo

O que faltaria pra um plugin real:

• Validação inline (lint de conformidade OKF)
• Template pra criar novos conceitos
• Sync com Knowledge Catalog via kcmd

🟢 Compatibilidade natural. Não precisa de plugin — funciona por design. Plugin seria nice-to-have pra validação, mas não bloqueia nada.

6.2 GitHub Actions

Status: Nenhum Action oficial publicado, mas tudo é scriptável.

Workflows possíveis:

# .github/workflows/okf-validate.yml
name: Validate OKF Bundle
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.13'
      - run: pip install okf-validator  # quando existir
      - run: okf validate ./bundles/

# .github/workflows/okf-enrich.yml (mais avançado)
name: Enrich on Schedule
on:
  schedule:
    - cron: '0 6 * * 1'  # Toda segunda
jobs:
  enrich:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -e ./okf[dev]
      - run: |
          python -m enrichment_agent enrich \
            --source bq --dataset ${{ secrets.BQ_DATASET }} \
            --no-web --out ./bundles/weekly
      - uses: peter-evans/create-pull-request@v6
        with:
          title: "chore: weekly OKF enrichment"

🟡 Potencial alto, zero implementação oficial. O workflow “enrich → commit → PR” é natural pro OKF. Nosso projeto (okf.md) poderia publicar um Action reutilizável como diferencial.

6.3 MCP Servers

Status: O kcmd mcp é real e documentado. Ponto de integração mais maduro do ecossistema.

O que o MCP server do kcmd oferece:

Onde usar:

• Gemini CLI / Google AI Studio
• Claude Desktop (via MCP config)
• Cursor / VS Code (qualquer editor com suporte MCP)
• Agentes customizados (LangChain, ADK, etc.)

Também existe: O md-fileset MCP server (usado pelo toolbox/enrichment) para navegar diretórios de markdown como knowledge base.

🟢 Maturidade do kcmd MCP: Funcional. Está documentado com exemplo de config JSON, tools claras. O md-fileset é mais básico mas serve como padrão.

6.4 Coding Agents (Claude, Codex, Cursor, Gemini)

Status: Nenhuma skill oficial publicada — e é exatamente aí que nosso projeto entra.

O que existe hoje:

• README do OKF funciona como doc pra um agente entender o formato
• O SPEC.md é legível o suficiente pra um LLM gerar bundles conformantes
• O toolbox/enrichment usa tools/skills/ como diretório de skills

O que falta (e onde a gente entra):

• Skill .md standalone que ensine qualquer agente a produzir OKF
• Validação em tempo de geração (agente checa conformidade antes de salvar)
• Templates reutilizáveis pra cenários comuns (SaaS metrics, analytics, APIs)

Padrão de skill que o toolbox já usa:

---
name: fileset-source
description: >
  Use the fileset source to find relevant markdown documents...
---

[instruções de uso das tools]

🟡 Oportunidade clara. O formato OKF foi feito para ser agent-friendly, mas ninguém empacotou isso como skill distribuível ainda. Nosso okf-skill será o primeiro.

Mapa de Maturidade

Conclusão

O ecossistema OKF tem duas camadas:

1. Camada portável (OKF puro): Format spec + enrichment agent + visualizer. Funciona standalone, sem GCP. É onde mora a oportunidade pra comunidade.

2. Camada enterprise (Knowledge Catalog): kcmd + kcenrich + catálogo GCP. Funciona em produção mas exige infra Google Cloud.

Nosso projeto (okf.md / okf.ia.br) vive na camada 1 — tornando OKF acessível, validável e produzível por qualquer agente, sem amarrar a cloud provider nenhum.