https://github.com/ooridata/onya
Knowledge graph expression, serialization, and Python implementation. Useful for LLM context.
https://github.com/ooridata/onya
data graph knowledge-graph model property-graph rdf web
Last synced: about 11 hours ago
JSON representation
Knowledge graph expression, serialization, and Python implementation. Useful for LLM context.
- Host: GitHub
- URL: https://github.com/ooridata/onya
- Owner: OoriData
- License: apache-2.0
- Created: 2021-02-05T18:05:08.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2026-06-10T16:37:32.000Z (22 days ago)
- Last Synced: 2026-06-10T17:11:16.732Z (22 days ago)
- Topics: data, graph, knowledge-graph, model, property-graph, rdf, web
- Language: Python
- Homepage:
- Size: 446 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
**Onya** is a knowledge graph expression and implementation. This repository combines a [data model and format spec](SPEC.md) with a Python parser and API implementation.
Note: Using our provided [onya-graph.SKILL.md](onya-graph.SKILL.md) with your favorite AI coding agent is a good way to automate Onya authoring and explore the format. Try providing a text document and asking it to generate a graph therefrom.
# Python quick start
[](https://pypi.org/project/Onya)
[](https://pypi.org/project/Onya)
## Installation
Requires Python 3.12 or later. The package is still in early development, so install directly from source:
```bash
git clone https://github.com/OoriData/Onya.git
cd Onya
pip install -U .
```
## Command line tool
You can use the built-in CLI to export directly from an Onya Literate (`.onya`) file to the Mermaid diagram format:
```sh
onya convert test/resource/schemaorg/thingsfallapart.onya > out.mmd
```
Then use a site such as https://mermaid.live/ to generate a diagram such as:
## Basic Python Usage
Here's a simple example demonstrating the core Onya API. First, let's define a small friendship graph in Onya Literate format:
```
# @docheader
* @document: http://example.org/friendship-graph
* @nodebase: http://example.org/people/
* @schema: https://schema.org/
# Chuks [Person]
* name: Chukwuemeka Okafor
* nickname: Chuks
* age: 28
# Ify [Person]
* name: Ifeoma Obasi
* nickname: Ify
* age: 27
```
Parse this graph and interact with it using the Python API.
```python
from onya.graph import graph
from onya.serial.literate import LiterateParser
# Parse the Onya Literate text into a graph
onya_text = '''
# @docheader
* @document: http://example.org/friendship-graph
* @nodebase: http://example.org/people/
* @schema: https://schema.org/
# Chuks [Person]
* name: Chukwuemeka Okafor
* nickname: Chuks
* age: 28
# Ify [Person]
* name: Ifeoma Obasi
* nickname: Ify
* age: 27
'''
g = graph()
op = LiterateParser()
result = op.parse(onya_text, g)
doc_iri = result.doc_iri
print(f'Parsed document: {doc_iri}')
print(f'Graph has {len(g)} nodes')
# Access nodes and their properties
chuks = g['http://example.org/people/Chuks']
ify = g['http://example.org/people/Ify']
# Get a specific property value
for prop in chuks.getprop('https://schema.org/name'):
print(f'Name: {prop.value}')
# Add a friendship edge between Chuks and Ify
friendship = chuks.add_edge('https://schema.org/knows', ify)
print(f'Added edge: {friendship}')
# Add nested properties to the friendship (metadata about the relationship)
friendship.add_property('https://schema.org/startDate', '2018-03-15')
friendship.add_property('https://schema.org/description', 'Met at university')
# Add a new property to Ify
ify.add_property('https://schema.org/jobTitle', 'Software Engineer')
# Modify a property by removing the old one and adding a new one
age_props = list(chuks.getprop('https://schema.org/age'))
for prop in age_props:
chuks.remove_property(prop)
chuks.add_property('https://schema.org/age', '29')
# Traverse edges
for edge in chuks.traverse('https://schema.org/knows'):
friend = edge.target
for name_prop in friend.getprop('https://schema.org/name'):
print(f'Chuks knows: {name_prop.value}')
# Access nested properties on the edge
for date_prop in edge.getprop('https://schema.org/startDate'):
print(f' Friends since: {date_prop.value}')
# Find all nodes of a certain type
for person in g.typematch('https://schema.org/Person'):
for name_prop in person.getprop('https://schema.org/name'):
print(f'Person in graph: {name_prop.value}')
# Reserialize to Onya literate
from onya.serial.literate import write
write(g)
```
This example demonstrates:
- Parsing Onya Literate format
- Accessing nodes and properties
- Adding edges with nested properties (reified relationships)
- Modifying properties
- Traversing the graph
- Querying by type
# Visualization / export
Onya includes simple serializers to help you visualize graphs:
- **Graphviz (DOT)**: `from onya.serial import graphviz` → `graphviz.write(g, out=f)` (see `demo/graphviz_basic/`)
- **Mermaid (flowchart)**: `from onya.serial import mermaid` → `mermaid.write(g, out=f)` (see `demo/mermaid_basic/`; quick viewing via [Mermaid Live Editor](https://mermaid.live/))
# Command line tool
You can use the built-in CLI to export directly from an Onya Literate (`.onya`) file:
```bash
# Mermaid (default)
onya convert test/resource/schemaorg/thingsfallapart.onya > out.mmd
# Graphviz DOT
onya convert test/resource/schemaorg/thingsfallapart.onya --dot > out.dot
```
# Acknowledgments
Onya is primarily developed by the crew at Oori Data. We offer LLMOps, data pipelines and software engineering services around AI/LLM applications.
# Background
Onya is based on experience from developing [Versa](https://github.com/uogbuji/versa) and also working on [the MicroXML spec](https://dvcs.w3.org/hg/microxml/raw-file/tip/spec/microxml.html) and implementations thereof.
The URL used for metavocabulary is [managed via purl.org](https://purl.archive.org/purl/onya/vocab).
The name is from Igbo "ọ́nyà", web, snare, trap, and by extension, network. The expanded sense is ọ́nyà úchè, web of knowledge.
# Contributing
Contributions welcome! We're interested in feedback from the community about what works and what doesn't in real-world usage. To get help with the code implementation, read [CONTRIBUTING.md](CONTRIBUTING.md).
# License
- **Code** (Python library): Apache 2.0 - See [LICENSE](LICENSE)
- **Specification** (wordloom_spec.md): [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/) - See [LICENSE-spec](LICENSE-spec)
The specification is under CC BY 4.0 to encourage broad adoption and derivative work while ensuring attribution. We want the format itself to be as open and reusable as possible, allowing anyone to create implementations in any language or adapt the format for their specific needs.
# Related Work
- [networkx](https://github.com/networkx/networkx): Network Analysis in Python
- [Apache AGE](https://github.com/apache/incubator-age): PostgreSQL Extension that for graphs. ANSI SQL & openCypher over the same DB.