| Name | kgl JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Knowledge Graph Language (KGL) parser. |
| upload_time | 2024-03-23 21:37:19 |
| maintainer | None |
| docs_url | None |
| author | James (capjamesg) |
| requires_python | <4.0,>=3.8 |
| license | MIT |
| keywords |
knowledge graph
graphs
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Knowledge Graph Language (KGL)
Knowledge Graph Language is a query language for interacting with graphs. It accepts semantic triples (i.e. `("James", "Enjoys", "Coffee")`), indexes them, and makes them available for querying.
You can use this language to:
- Find all attributes associated with a node in a graph.
- Return all nodes that are connected to a node.
- Return all nodes that are connected to a node and meet a specified condition.
- Find how two nodes connect in a graph.
This language is a work in progress.
## Ingesting Information
This project allows you to index triples of data like:
```python
("James", "Enjoys", "Coffee")
("James", "Hobbies", "Making coffee")
("James", "WorksFor", "Roboflow")
("Roboflow", "Makes", "Computer Vision")
("Roboflow", "EntityType", "Company")
```
A graph is then constructed from the triples that you can then query.
## Syntax
### Query a Single Item
You can query a single item:
```
{ James }
```
This will return all items associated with the `James` entry:
```
{'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Making coffee']}
```
### Sequential Queries
The Knowledge Graph Language flows from left to right. You can make a statement, then use an arrow (`->`) to query an attribute related to the result:
Consider the following query:
```
{ James -> WorksFor -> Makes }
```
This query gets the `James` item, retrieves for whom James works, then reports the `Makes` attribute for the employer.
The query returns:
```
['Computer vision software.']
```
### Filter Queries
You can filter queries so that the flow of data is constrained to only work with results that match a condition.
Consider this query:
```
{ Roboflow ("EntityType" = "Company") -> WorksFor ("Enjoys" = "Coffee") -> Hobbies }
```
This query gets the instance of `Roboflow` that has the `EntityType` property `Company`. This could be used for disambiguation.
Then, the query gets everyone who works at Roboflow who enjoys coffee. The query then finds who everyone works for, and returns their hobbies.
This returns:
```
['Making coffee']
```
You can filter by the number of items connected to a node in the graph, too.
Consider these triples:
```
("CLIP", "isA", "Paper")
("CLIP", "Authors", "Person 1")
("CLIP", "Authors", "Person 2")
("Person 1", "Citations", "Paper 42")
("Person 2", "Citations", "Paper 1")
("Person 2", "Citations", "Paper 2")
("Person 2", "Citations", "Paper 3")
("Person 2", "Citations", "Paper 4")
```
Suppose you want to find all authors of the CLIP paper in a research graph, but you only want to retrieve authors whose work has been cited at least three times. You can do this with the following query:
```
{ CLIP -> Authors ("Citations" > "3") }
```
This query returns:
```
['Person 2']
```
This is because only `Person 2` has greater than three citations to their works.
### Describe Relationships
Suppose you want to know how `James` and `Roboflow` relate. For this, you can use the interrelation query operator (`<->`).
Consider this query:
```
{ Roboflow <-> James }
```
This returns:
```
['Roboflow', ('James', 'WorksFor')]
```
Serialized into Knowledge Graph Language, this response is represented as:
```
Roboflow -> WorksFor
```
If we execute that query in introspection mode, we can see all information about James:
```
{ Roboflow -> WorksFor }!
```
This returns:
```
[{'James': {'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Coffee']}}, {'Lenny': {'WorksFor': ['MetaAI', 'Roboflow']}}]
```
### Introspection
By default, all Sequential Queries return single values. For example, this query returns the names of everyone who works at Roboflow:
```
{ Roboflow -> WorksFor }
```
The response is:
```
['James', 'Lenny']
```
We can enable introspection mode to learn more about each of these responses. To enable introspection mode, append a `!` to the end of your query:
```
{ Roboflow -> WorksFor }!
```
This returns all attributes related, within one degree, to James and Lenny, who both work at Roboflow:
```
[{'James': {'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Coffee']}}, {'Lenny': {'WorksFor': ['MetaAI', 'Roboflow']}}]
```
### Description Operators
By default, Knowledge Graph Language returns the value associated with your query. You can add operators to the end of your query to change the output.
You can use:
- `?` to return True if your query returns a response and False if your query returns no response.
- `#` to count the number of responses
- `!` to return an introspection response.
## Python API
First, install KGL:
```
pip install kgl
```
### Create a Knowledge Graph
```python
from kgl import KnowledgeGraph
kg = KnowledgeGraph()
```
### Ingest Items
You can ingest triples of strings:
```python
kg.add_node(("Roboflow", "Owned", "Lenny"))
```
You can also ingest triples whose third item is a list:
```python
kg.add_node(("Alex", "Citations", ["MetaAI", "GoogleAI", "Coffee", "Teacup", "Roboflow"]))
```
### Evaluate a Query
```python
result = kg.evaluate("{ James }")
print(result)
```
Responses are valid Python objects, whose type varies depending on your query.
By default, KGL returns a list.
But:
- `!` queries return dictionaries.
- `#` queries return integers.
- `?` queries return booleans.
## Tests
To run the project test suite, run:
```
pytest test
```
## License
This project is licensed under an [MIT license](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "kgl",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "knowledge graph, graphs",
"author": "James (capjamesg)",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2e/fb/ba1be37dfbd3a2263397a4c00c2f529662f2fa4aaba97aee99a3320c994a/kgl-0.1.1.tar.gz",
"platform": null,
"description": "# Knowledge Graph Language (KGL)\n\nKnowledge Graph Language is a query language for interacting with graphs. It accepts semantic triples (i.e. `(\"James\", \"Enjoys\", \"Coffee\")`), indexes them, and makes them available for querying.\n\nYou can use this language to:\n\n- Find all attributes associated with a node in a graph.\n- Return all nodes that are connected to a node.\n- Return all nodes that are connected to a node and meet a specified condition.\n- Find how two nodes connect in a graph.\n\nThis language is a work in progress.\n\n## Ingesting Information\n\nThis project allows you to index triples of data like:\n\n```python\n(\"James\", \"Enjoys\", \"Coffee\")\n(\"James\", \"Hobbies\", \"Making coffee\")\n(\"James\", \"WorksFor\", \"Roboflow\")\n(\"Roboflow\", \"Makes\", \"Computer Vision\")\n(\"Roboflow\", \"EntityType\", \"Company\")\n```\n\nA graph is then constructed from the triples that you can then query.\n\n## Syntax\n\n### Query a Single Item\n\nYou can query a single item:\n\n```\n{ James }\n```\n\nThis will return all items associated with the `James` entry:\n\n```\n{'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Making coffee']}\n```\n\n### Sequential Queries\n\nThe Knowledge Graph Language flows from left to right. You can make a statement, then use an arrow (`->`) to query an attribute related to the result:\n\nConsider the following query:\n\n```\n{ James -> WorksFor -> Makes }\n```\n\nThis query gets the `James` item, retrieves for whom James works, then reports the `Makes` attribute for the employer.\n\nThe query returns:\n\n```\n['Computer vision software.']\n```\n\n### Filter Queries\n\nYou can filter queries so that the flow of data is constrained to only work with results that match a condition.\n\nConsider this query:\n\n```\n{ Roboflow (\"EntityType\" = \"Company\") -> WorksFor (\"Enjoys\" = \"Coffee\") -> Hobbies }\n```\n\nThis query gets the instance of `Roboflow` that has the `EntityType` property `Company`. This could be used for disambiguation.\n\nThen, the query gets everyone who works at Roboflow who enjoys coffee. The query then finds who everyone works for, and returns their hobbies.\n\nThis returns:\n\n```\n['Making coffee']\n```\n\nYou can filter by the number of items connected to a node in the graph, too.\n\nConsider these triples:\n\n```\n(\"CLIP\", \"isA\", \"Paper\")\n(\"CLIP\", \"Authors\", \"Person 1\")\n(\"CLIP\", \"Authors\", \"Person 2\")\n(\"Person 1\", \"Citations\", \"Paper 42\")\n(\"Person 2\", \"Citations\", \"Paper 1\")\n(\"Person 2\", \"Citations\", \"Paper 2\")\n(\"Person 2\", \"Citations\", \"Paper 3\")\n(\"Person 2\", \"Citations\", \"Paper 4\")\n```\n\n\nSuppose you want to find all authors of the CLIP paper in a research graph, but you only want to retrieve authors whose work has been cited at least three times. You can do this with the following query:\n\n```\n{ CLIP -> Authors (\"Citations\" > \"3\") }\n```\n\nThis query returns:\n\n```\n['Person 2']\n```\n\nThis is because only `Person 2` has greater than three citations to their works.\n\n### Describe Relationships\n\nSuppose you want to know how `James` and `Roboflow` relate. For this, you can use the interrelation query operator (`<->`).\n\nConsider this query:\n\n```\n{ Roboflow <-> James }\n```\n\nThis returns:\n\n```\n['Roboflow', ('James', 'WorksFor')]\n```\n\nSerialized into Knowledge Graph Language, this response is represented as:\n\n```\nRoboflow -> WorksFor\n```\n\nIf we execute that query in introspection mode, we can see all information about James:\n\n```\n{ Roboflow -> WorksFor }!\n```\n\nThis returns:\n\n```\n[{'James': {'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Coffee']}}, {'Lenny': {'WorksFor': ['MetaAI', 'Roboflow']}}]\n```\n\n### Introspection\n\nBy default, all Sequential Queries return single values. For example, this query returns the names of everyone who works at Roboflow:\n\n```\n{ Roboflow -> WorksFor }\n```\n\nThe response is:\n\n```\n['James', 'Lenny']\n```\n\nWe can enable introspection mode to learn more about each of these responses. To enable introspection mode, append a `!` to the end of your query:\n\n```\n{ Roboflow -> WorksFor }!\n```\n\nThis returns all attributes related, within one degree, to James and Lenny, who both work at Roboflow:\n\n```\n[{'James': {'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Coffee']}}, {'Lenny': {'WorksFor': ['MetaAI', 'Roboflow']}}]\n```\n\n### Description Operators\n\nBy default, Knowledge Graph Language returns the value associated with your query. You can add operators to the end of your query to change the output.\n\nYou can use:\n\n- `?` to return True if your query returns a response and False if your query returns no response.\n- `#` to count the number of responses\n- `!` to return an introspection response.\n \n## Python API\n\nFirst, install KGL:\n\n```\npip install kgl\n```\n\n### Create a Knowledge Graph\n\n```python\nfrom kgl import KnowledgeGraph\n\nkg = KnowledgeGraph()\n```\n\n### Ingest Items\n\nYou can ingest triples of strings:\n\n```python\nkg.add_node((\"Roboflow\", \"Owned\", \"Lenny\"))\n```\n\nYou can also ingest triples whose third item is a list:\n\n```python\nkg.add_node((\"Alex\", \"Citations\", [\"MetaAI\", \"GoogleAI\", \"Coffee\", \"Teacup\", \"Roboflow\"]))\n```\n\n### Evaluate a Query\n\n```python\nresult = kg.evaluate(\"{ James }\")\nprint(result)\n```\n\nResponses are valid Python objects, whose type varies depending on your query.\n\nBy default, KGL returns a list.\n\nBut:\n\n- `!` queries return dictionaries.\n- `#` queries return integers.\n- `?` queries return booleans.\n\n## Tests\n\nTo run the project test suite, run:\n\n```\npytest test\n```\n\n## License\n\nThis project is licensed under an [MIT license](LICENSE).\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Knowledge Graph Language (KGL) parser.",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"knowledge graph",
" graphs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "36d55149eb8a49c5aac8bb6091484edad3379343f68ec331412b1a458c8edddb",
"md5": "11899b9cc9537c6b1dd06b663f095c49",
"sha256": "c2573de8dfca7e49fb863526f6d106edf27f05925e410c1187e3a5482bb128fb"
},
"downloads": -1,
"filename": "kgl-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "11899b9cc9537c6b1dd06b663f095c49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 9545,
"upload_time": "2024-03-23T21:37:18",
"upload_time_iso_8601": "2024-03-23T21:37:18.065198Z",
"url": "https://files.pythonhosted.org/packages/36/d5/5149eb8a49c5aac8bb6091484edad3379343f68ec331412b1a458c8edddb/kgl-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2efbba1be37dfbd3a2263397a4c00c2f529662f2fa4aaba97aee99a3320c994a",
"md5": "5b2080947b024db3f605acdff229cffb",
"sha256": "5dc210d9ee52380a047c89bab4afa06362c1ce3f181d1ac82257ca92d6654a1d"
},
"downloads": -1,
"filename": "kgl-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "5b2080947b024db3f605acdff229cffb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 10688,
"upload_time": "2024-03-23T21:37:19",
"upload_time_iso_8601": "2024-03-23T21:37:19.611268Z",
"url": "https://files.pythonhosted.org/packages/2e/fb/ba1be37dfbd3a2263397a4c00c2f529662f2fa4aaba97aee99a3320c994a/kgl-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-23 21:37:19",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "kgl"
}
