# omasim/klm architecture

> Architecture diagram of the GitHub repository omasim/klm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omasim/klm
- Repository: https://github.com/omasim/klm

## Overview

KLM is an open standard and stdlib-only Python reference toolchain for validating epistemic records, producing verifiable signed attestations, maintaining tamper-evident logs, and creating visibility-tiered disclosures. The main workflow is an emitter or record author supplies a record; validators check its attestation and γ contracts; signing and logging support independent verification; disclosure produces user, auditor, or operator views. The graph also captures canonicalization support and conformance tooling. Some source was sampled only partially, so unsampled implementation links are omitted rather than inferred.

Main entry points: [`schema/validate_attestation.py`](https://github.com/omasim/klm/blob/main/schema/validate_attestation.py) (Attestation validator), [`schema/validate_gamma.py`](https://github.com/omasim/klm/blob/main/schema/validate_gamma.py) (Gamma validator), [`schema/sign_attestation.py`](https://github.com/omasim/klm/blob/main/schema/sign_attestation.py) (Signing and verification), [`schema/disclosure.py`](https://github.com/omasim/klm/blob/main/schema/disclosure.py) (Disclosure views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Record contracts"]
  node_attestation_schema["Attestation schema"]
  node_gamma_schema["Gamma schema"]
end

subgraph group_validation["Validation"]
  node_attestation_validator["Attestation validator"]
  node_gamma_validator["Gamma validator<br/>[validate_gamma.py]"]
end

subgraph group_verification["Proof and history"]
  node_envelope["Signing and verification"]
  node_ed25519["Ed25519 reference<br/>[ed25519_ref.py]"]
  node_canonicalization["JCS reference<br/>[jcs_reference.mjs]"]
  node_log["Hash-chained log<br/>[attestation_log.py]"]
end

subgraph group_views["Disclosure"]
  node_disclosure["Disclosure views<br/>[disclosure.py]"]
end

subgraph group_conformance["Conformance"]
  node_attestation_vectors["Attestation conformance<br/>[run_conformance.py]"]
  node_null_vectors["Honest-null conformance<br/>[run_conformance.py]"]
  node_canonical_vectors["Canonical vector generator<br/>[gen_vectors.mjs]"]
  node_canonical_runner["Canonical conformance runner<br/>[run_conformance.py]"]
end

node_author(("Record author"))
node_user(("User"))
node_auditor(("Auditor"))
node_operator(("Operator"))

node_author -->|"submits record"| node_attestation_validator
node_attestation_validator -->|"checks contract"| node_attestation_schema
node_author -->|"submits γ record"| node_gamma_validator
node_gamma_validator -->|"checks contract"| node_gamma_schema
node_attestation_validator -->|"validates γ"| node_gamma_validator
node_envelope -->|"uses fallback"| node_ed25519
node_log -->|"verifies envelopes"| node_envelope
node_disclosure -->|"uses record hashes"| node_envelope
node_user -->|"requests view"| node_disclosure
node_auditor -->|"requests view"| node_disclosure
node_operator -->|"requests view"| node_disclosure
node_attestation_vectors -->|"grades vectors"| node_attestation_validator
node_null_vectors -->|"cross-checks γ"| node_gamma_validator
node_canonical_vectors -->|"generates vectors"| node_canonicalization
node_canonical_runner -->|"checks behavior"| node_envelope

click node_attestation_schema "https://github.com/omasim/klm/blob/main/schema/klm-attestation.schema.json"
click node_gamma_schema "https://github.com/omasim/klm/blob/main/schema/klm-gamma.schema.json"
click node_attestation_validator "https://github.com/omasim/klm/blob/main/schema/validate_attestation.py"
click node_gamma_validator "https://github.com/omasim/klm/blob/main/schema/validate_gamma.py"
click node_envelope "https://github.com/omasim/klm/blob/main/schema/sign_attestation.py"
click node_ed25519 "https://github.com/omasim/klm/blob/main/schema/ed25519_ref.py"
click node_canonicalization "https://github.com/omasim/klm/blob/main/schema/conformance/canonical/jcs_reference.mjs"
click node_log "https://github.com/omasim/klm/blob/main/schema/attestation_log.py"
click node_disclosure "https://github.com/omasim/klm/blob/main/schema/disclosure.py"
click node_attestation_vectors "https://github.com/omasim/klm/blob/main/schema/conformance/attestation-0.2/run_conformance.py"
click node_null_vectors "https://github.com/omasim/klm/blob/main/schema/conformance/honest-null/run_conformance.py"
click node_canonical_vectors "https://github.com/omasim/klm/blob/main/schema/conformance/canonical/gen_vectors.mjs"
click node_canonical_runner "https://github.com/omasim/klm/blob/main/schema/conformance/canonical/run_conformance.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_attestation_schema,node_gamma_schema,node_user toneBlue
class node_attestation_validator,node_gamma_validator toneAmber
class node_envelope,node_ed25519,node_canonicalization,node_log toneMint
class node_disclosure toneRose
class node_attestation_vectors,node_null_vectors,node_canonical_vectors,node_canonical_runner,node_author,node_auditor,node_operator toneIndigo
```

## Components

### Record contracts

- [Attestation schema](https://github.com/omasim/klm/blob/main/schema/klm-attestation.schema.json): `schema/klm-attestation.schema.json`
- [Gamma schema](https://github.com/omasim/klm/blob/main/schema/klm-gamma.schema.json): `schema/klm-gamma.schema.json`

### Validation

- [Attestation validator](https://github.com/omasim/klm/blob/main/schema/validate_attestation.py): `schema/validate_attestation.py`
- [Gamma validator](https://github.com/omasim/klm/blob/main/schema/validate_gamma.py): `schema/validate_gamma.py`

### Proof and history

- [Signing and verification](https://github.com/omasim/klm/blob/main/schema/sign_attestation.py): `schema/sign_attestation.py`
- [Ed25519 reference](https://github.com/omasim/klm/blob/main/schema/ed25519_ref.py): `schema/ed25519_ref.py`
- [JCS reference](https://github.com/omasim/klm/blob/main/schema/conformance/canonical/jcs_reference.mjs): `schema/conformance/canonical/jcs_reference.mjs`
- [Hash-chained log](https://github.com/omasim/klm/blob/main/schema/attestation_log.py): `schema/attestation_log.py`

### Disclosure

- [Disclosure views](https://github.com/omasim/klm/blob/main/schema/disclosure.py): `schema/disclosure.py`

### Conformance

- [Attestation conformance](https://github.com/omasim/klm/blob/main/schema/conformance/attestation-0.2/run_conformance.py): `schema/conformance/attestation-0.2/run_conformance.py`
- [Honest-null conformance](https://github.com/omasim/klm/blob/main/schema/conformance/honest-null/run_conformance.py): `schema/conformance/honest-null/run_conformance.py`
- [Canonical vector generator](https://github.com/omasim/klm/blob/main/schema/conformance/canonical/gen_vectors.mjs): `schema/conformance/canonical/gen_vectors.mjs`
- [Canonical conformance runner](https://github.com/omasim/klm/blob/main/schema/conformance/canonical/run_conformance.py): `schema/conformance/canonical/run_conformance.py`

### Other components

- **Record author**
- **User**
- **Auditor**
- **Operator**

## Connections

- Record author → Attestation validator: submits record (evidence: `README.md`)
- Attestation validator → Attestation schema: checks contract (evidence: `README.md`)
- Record author → Gamma validator: submits γ record (evidence: `README.md`)
- Gamma validator → Gamma schema: checks contract (evidence: `README.md`)
- Attestation validator → Gamma validator: validates γ (evidence: `schema/validate_attestation.py`)
- Signing and verification → Ed25519 reference: uses fallback (evidence: `schema/sign_attestation.py`)
- Hash-chained log → Signing and verification: verifies envelopes (evidence: `schema/attestation_log.py`)
- Disclosure views → Signing and verification: uses record hashes (evidence: `schema/disclosure.py`)
- User → Disclosure views: requests view (evidence: `README.md`)
- Auditor → Disclosure views: requests view (evidence: `README.md`)
- Operator → Disclosure views: requests view (evidence: `README.md`)
- Attestation conformance → Attestation validator: grades vectors (evidence: `schema/conformance/attestation-0.2/run_conformance.py`)
- Honest-null conformance → Gamma validator: cross-checks γ (evidence: `schema/conformance/honest-null/run_conformance.py`)
- Canonical vector generator → JCS reference: generates vectors (evidence: `schema/conformance/canonical/gen_vectors.mjs`)
- Canonical conformance runner → Signing and verification: checks behavior (evidence: `schema/conformance/canonical/run_conformance.py`)
