Metadata-Version: 2.4
Name: gitgraf
Version: 0.2.0
Summary: A graph of nodes, facts and edges kept as human-readable YAML files in git, with valid, knowledge and change time on every record
License-Expression: MIT
License-File: LICENSE
Requires-Dist: networkx>=3.3
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Gitgraf

Gitgraf keeps a graph of nodes, facts and edges as human-readable YAML files in a git repository: `pip install`, no server, no database.

Every fact and edge carries three time axes, and nothing is ever overwritten:

- **Valid time** (`valid_from`, `valid_to`): when it is true in the world.
- **Knowledge time** (`known_at`): when it was first known.
- **Change time** (`changed_at`, `superseded_at`): when the record was written or replaced. An update appends a new version, so the graph can be read as it was at any earlier moment.

It is the store that bibliotheke, a knowledge graph framework, is built on, and it works on its own for any register of dated facts.

## Quickstart

```sh
gitgraf init
gitgraf add node windfarm "Hornsea 2"
gitgraf add node bmu "T_HOWBO-1"
gitgraf add fact hornsea-2 capacity_mw 1386 --valid-from 2022-08-31
gitgraf add edge t-howbo-1 part_of hornsea-2 --valid-from 2021-12

gitgraf show hornsea-2                      # the current graph
gitgraf show hornsea-2 --valid-at 2022-01   # what was true then
gitgraf show hornsea-2 --known-at 2024      # what had been learned by then
gitgraf show hornsea-2 --at-commit v1.0     # as committed at a git revision
gitgraf show hornsea-2 --json
```

`add fact` and `add edge` print a record id. Use it to change a record without losing history:

```sh
gitgraf update f53fd77 --value 1320   # appends a new version
gitgraf retract f53fd77               # hides it from the current graph
gitgraf history hornsea-2             # every version, including superseded ones
```

## Sources and edge attributes

Any fact or edge can say where it comes from, and an edge can carry attributes of the link itself, such as a share of ownership:

```sh
gitgraf add fact hornsea-2 capacity_mw 1386 --source "TEC register 2026-03"
gitgraf add edge hornsea-2 owned_by orsted --set share=0.5 --valid-from 2022-09 --source "company announcement"
gitgraf update e2778f9 --set share=0.4 --source "annual report 2025"   # a new version; the old share stays in history
```

A new version keeps the source and attributes it does not change. In a batch for `gitgraf import`, `source` can be set once for the whole batch, per node, or per record, and an edge takes `attrs: {share: 0.5}`.

The data model can type the attributes of a relation and require a source on every record:

```yaml
source: required          # a write without a source is refused; `check` reports hand edits that drop one
edges:
  owned_by:
    from: windfarm
    to: company
    attrs:
      share: {type: number, required: true}
      role:  {type: enum, values: [operator, investor]}
```

`gitgraf model add edge owned_by windfarm company --attr share:number` declares one from the command line. Both are stored only where present, so a graph that uses neither has the same files as before.

## Files

A graph is a directory with a `gitgraf.yaml` marker and one file per node at `nodes/<type>/<id>.yaml`, with optional Markdown next to it at `nodes/<type>/<id>.md`:

```yaml
id: hornsea-2
type: windfarm
name: Hornsea 2
notes: ''
facts:
- id: f53fd77
  key: capacity_mw
  value: 1386
  valid_from: 2022-08-31
  valid_to: null
  known_at: 2026-11-14T10:07:00Z
  changed_at: 2026-11-14T10:07:00Z
  superseded_at: null
edges: []
```

A node's file is dumped deterministically, so a git diff shows only what changed.

## Commands

| Command | What it does |
|---|---|
| `init`, `add node\|fact\|edge`, `update`, `retract`, `import` | Write the graph; `import` merges a batch file and is safe to re-run |
| `show`, `history`, `list`, `types`, `search`, `export` | Read it; all take `--valid-at`, `--known-at`, `--changed-at` and `--at-commit` |
| `merge` | Join two nodes that are the same thing; an alias resolves wherever an id is expected |
| `model`, `model add\|rename\|drop`, `model diff\|log\|version\|tag` | An optional data model: what node types, facts and edges the graph allows, and how it changed |
| `check` | Validate the files against each other and the model; lists possible duplicates |
| `diff` | What changed between two git revisions |
| `hook install`, `ci` | A pre-commit hook and a GitHub Actions workflow that run `check` and refuse destructive model changes |

## From Python

```python
from gitgraf import At, Graph

graph = Graph.open("registry")
node = graph.node("hornsea-2")
facts = graph.facts(node.id, At(valid_at="2022-01", known_at="2024"))
```

`Graph.nx(at)` returns a frozen `networkx.MultiDiGraph` of what is in view.

## Building on it

A package on top keeps its own names with `gitgraf.settings.configure(cli=..., package=..., markers=...)`, called before `gitgraf.cli` is imported, and adds its own commands to `gitgraf.cli.app`. `gitgraf.hooks.checks` and `gitgraf.hooks.rewrites` let it check and maintain its own sections of the marker file.

## Development

```sh
uv sync
uv run pytest
```
