KG-SSOT

KG-SSOT

Verifiable knowledge graphs in plain text: every claim says where it came from, when it was last verified and what depends on it, and your CI rejects the ones that don't.

English | Português (Brasil)

Manual · Adopt it · The contract · Conformance suite · Changelog · For AI agents

Why

Teams, of people or of agents, pile up conclusions: "the retry is idempotent", "we decided on three attempts". They live in meeting notes, tickets and chat memories, and on the way they lose three things: the source, the date it was last verified and what depends on it. A convincing sentence without any of the three passes a hurried review.

KG-SSOT treats this as a format problem, not a discipline problem. Knowledge lives in a .kg.yaml graph, versioned next to the code, and a formal contract decides in CI what fails:

• a confirmed or production node without provenance fails (a claim with no recoverable source is declared unverifiable instead);
• a source that is only a placeholder (unknown, n/a, tbd) fails;
• an edge that points nowhere fails, and so does a node with no edges;
• a verification stamp with nothing to check against, a decision with no origin and a production claim backed only by testimony raise warnings.

Get started in 60 seconds

pip install kg-ssot

# the conformance suite against the reference reader, from the installed package
kg-conformance | tail -2

# one valid graph and one that fails
kg-validate valid.kg.yaml broken.kg.yaml

Or straight from the repository, with hash-checked dependencies:

git clone https://github.com/marciocar/kg-ssot && cd kg-ssot
python3 -m venv .venv && .venv/bin/pip install --require-hashes -r tools/requirements.txt
.venv/bin/python3 -I tools/kg_validate.py \
  spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml \
  spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml

PASS spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml
FAIL spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml
  MUST   form.required.node.label ×1
· 2 files; 1 pass the MUST; 0 with a SHOULD warning (kg-contract-v4.schema.json + kg-contract-v4.should.schema.json)

The tools print in English by default and in Brazilian Portuguese when your locale is pt_BR (or KG_SSOT_LANG=pt-BR). Codes, exit codes and JSON keys never change with the language; only the human text does.

Install

A node, inside

- id: C_RETRY_SAFE
  node_type: claim
  plane: PROD
  status: confirmed
  impact: 4
  confidence: 0.8
  label: The payment retry is idempotent.
  verified_at: "2026-10-01"
  verified_against: tests/payment_retry_test.py
  provenance:
    source: tests/payment_retry_test.py
    locator: test_retry_is_idempotent
    method: "medição: integration test in CI"

The label is the claim, short. The provenance says where it came from and how: one of five method classes, medição (measurement), leitura (reading), juízes (judges), derivado (derived) or testemunho (testimony). The stamp says when it was verified and against what. The method classes are literal values of the contract and stay as written.

Use it from an AI agent

The reference MCP server gives a model the contract and a store: it validates a graph, writes only what passes, reads, lists, queries with every edge resolved to the label on the other end, and shows history. Read-only tools are annotated as such, so a client can skip confirmation for them.

kg-mcp --root ./graphs          # stdio, for Claude Desktop, Claude Code and other MCP clients

kg_schema_help returns the current contract, a minimal passing example and the fixes for the most common codes, so a model can write a passing graph on the first try. llms.txt indexes the documentation for agents, and llms-full.txt has all of it in one file.

How it works

flowchart LR
  subgraph product["Product (one tag kg-ssot-vX.Y.Z)"]
    C["Contract<br/>JSON Schema MUST + SHOULD<br/>+ integrity rules"]
    S["Conformance suite<br/>438 cases as plain data"]
    R["Reference reader<br/>kg_validate.py"]
    S -- "every reader passes" --> R
    C --> R
  end
  subgraph adopter["Adopter repository"]
    V["vendor/kg-ssot<br/>+ sha256 stamp"]
    G["kg_gate.py in CI<br/>per-graph ratchet"]
    K["the team's .kg.yaml"]
    V --> G
    K --> G
  end
  product -- "kg_vendor.py update --tag" --> V
  G -- "nothing gets worse:<br/>a new graph passes,<br/>debt only shrinks" --> PR["PR approved"]

1. The contract is JSON Schema 2020-12 at two levels: MUST fails, SHOULD warns. The rules a schema cannot express (unique ids, existing edge ends, orphan nodes) are part of it.
2. The suite is the compatibility proof: each case is a real YAML file with the expected verdict and codes, and a reader passes only if it emits exactly the same codes.
3. The kit brings the contract to a repository by tag, with a stamp that fails local edits, and runs the per-graph ratchet in CI: what already failed becomes named debt, a new graph has to pass, and the debt only shrinks.

Features

What KG-SSOT is not

Status

• Current: contract v4, release kg-ssot-v4.25.0. The reference reader passes 424 of 438 cases in latest/.
• In use: three adopters run the gate in CI, one of them in production.
• Next: v5 will fail a method outside the <class>: <detail> form, which only warns today.
• Open: the semantic layer (freshness, contradiction, domain completeness) lives in optional/, and the reference reader does not implement it: it passes only the 10 valid cases there.

Documentation

Contributing

A contract change starts with a conformance case: the .kg.yaml that shows the behavior and the expected verdict. Releases are tags kg-ssot-vX.Y.Z of the development repository, where every pull request that touches spec/ or tools/ runs the suite and the kit tests in CI. The release mirror holds only what each tag ships, one commit per tag, and does not take pull requests: a proposal or a bug goes in as an issue, ideally with the case that shows it. A reader in another language is welcome: chapter 7 of the manual explains how to measure it.

License

The product (what the release ships, listed in spec/release.json: the contract, the suite, the .kg.yaml cases, the kit in tools/, ADOPTING.md, this README and the manual) is Apache-2.0: LICENSE, with the scope in NOTICE.

KG-SSOT was born inside the Onion framework, which now adopts it by tag like any other adopter. The product does not depend on it.