Metadata-Version: 2.4
Name: kgl-lang
Version: 0.1.0
Summary: Knowledge Graph Language — parser, linter, and query engine
Author-email: Adrian Bennett <adrian.bennett@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://nakagawabennett.com/kgl
Project-URL: Repository, https://github.com/adriannakagawabennett/kgl
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# KGL — Knowledge Graph Language

A plain-text file format for building file-system-based knowledge graphs. KGL makes relationships between information **first-class citizens** — not an afterthought bolted onto a document format.

```
@Person Alice Nguyen
joined: 2021-03-15
#backend #python

[mentors] → people/diana.kgl#Diana Park
    started: 2023-06
    focus: "backend systems and code review"

→ projects/search-revamp.kgl
~> teams/platform.kgl
```

No database. No graph engine. Just files, folders, and links — readable by humans and navigable by AI.

---

## Why KGL?

Existing formats optimise for data (JSON, CSV) or documents (Markdown, XML). Neither treats **relationships** as structural. KGL is built around the idea that *how things connect* is as important as *what things are*.

- **File-system as graph** — folders are namespaces, files are nodes, links are edges
- **AI-readable by design** — hard links (`→`) signal "follow this", soft links (`~>`) signal "background context"
- **Human-writable** — plain text, no tooling required to create or read
- **Schema-optional** — works without a schema, richer with one
- **Git-native** — plain text means free version history for your entire knowledge graph

---

## Documentation

| Document | Description |
|---|---|
| [Syntax Reference](./documentation/syntax.md) | All primitives, field types, and link semantics |
| [Schema](./documentation/schema.md) | `_schema.kgl` files, inheritance, and validation warnings |
| [Graph Model](./documentation/graph-model.md) | Data structures and relationships |

---

## Quick start

### 1. Create your first file

```
# people/alice.kgl

@Person Alice Nguyen
role: Senior Engineer
joined: 2021-03-15
#backend #python

→ projects/search-revamp.kgl
```

### 2. Link to related files

```
# projects/search-revamp.kgl

@Project Search Revamp
status: in-progress
deadline: 2025-08-01

[staffed-by] → people/alice.kgl#Alice Nguyen
    role: lead engineer
    since: 2024-11-01
```

### 3. Add a schema (optional)

```
# _schema.kgl

@NodeType Person
    joined!: date
    role?:   text

@RelType staffed-by
    from:   Project → Person
    role!:  text
    since!: date
```

That's it. Your knowledge graph lives in the file system. Query it with grep, traverse it with any file-reading tool, or load it into a graph database via the OpenCypher exporter.

---

## File format at a glance

### Nodes

```
@Type Name
@Type|Type Name
```

A file can contain multiple nodes. Each `@Type` declaration starts a new node; everything below it belongs to that node until the next `@Type`.

### Fields

```
key: value
key: "multi word value"
```

### Tags

```
#tag #another-tag
```

### Links

| Syntax | Meaning |
|---|---|
| `→ file.kgl` | Hard link — strong relationship, follow for full context |
| `→ file.kgl#Node Name` | Hard link to a specific node inside a file |
| `~> file.kgl` | Soft link — background context, optional |
| `[rel] → file.kgl` | Named relationship |
| `[rel\|rel] → file.kgl` | Multi-type relationship |

### Relationship properties

```
[employs] → people/alice.kgl#Alice Nguyen
    role: lead engineer
    since: 2024-11-01
```

Indented lines immediately after a link are properties of that relationship. They are scoped to the relationship, not the node.

### Free text body

```
---
Prose goes here. Not parsed as fields.
Useful for context, notes, and nuance that fields can't capture.
```

---

## Schema

A `_schema.kgl` file defines node types, required fields, and allowed relationships. Schema is **warning-only** — files without required fields are valid but flagged by a linter.

Place `_schema.kgl` at the graph root for global rules, and in any subfolder to extend or tighten the global schema for that folder.

---

## File extension

`.kgl` — stands for Knowledge Graph Language.

---

## Status

Early design stage. Contributions and feedback welcome.

---

## License

MIT
