| Name | graphiti-core JSON |
| Version |
0.3.16
JSON |
| download |
| home_page | None |
| Summary | A temporal graph building library |
| upload_time | 2024-10-22 14:33:53 |
| maintainer | None |
| docs_url | None |
| author | Paul Paliychuk |
| requires_python | <4.0,>=3.10 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img width="350" alt="Graphiti-ts-small" src="https://github.com/user-attachments/assets/bbd02947-e435-4a05-b25a-bbbac36d52c8">
## Temporal Knowledge Graphs for Agentic Applications
<br />
[](https://discord.com/invite/W8Kw6bsgXQ)
[](https://github.com/getzep/Graphiti/actions/workflows/lint.yml)
[](https://github.com/getzep/Graphiti/actions/workflows/unit_tests.yml)
[](https://github.com/getzep/Graphiti/actions/workflows/typecheck.yml)
[](https://codespaces.new/getzep/Graphiti)
<br />
</div>
Graphiti builds dynamic, temporally aware Knowledge Graphs that represent complex, evolving relationships between
entities over time. Graphiti ingests both unstructured and structured data, and the resulting graph may be queried using
a fusion of time, full-text, semantic, and graph algorithm approaches.
<br />
<p align="center">
<img src="/images/graphiti-graph-intro.gif" alt="Graphiti temporal walkthrough" width="700px">
</p>
<br />
Graphiti helps you create and query Knowledge Graphs that evolve over time. A knowledge graph is a network of
interconnected facts, such as _“Kendra loves Adidas shoes.”_ Each fact is a “triplet” represented by two entities, or
nodes (_”Kendra”_, _“Adidas shoes”_), and their relationship, or edge (_”loves”_). Knowledge Graphs have been explored
extensively for information retrieval. What makes Graphiti unique is its ability to autonomously build a knowledge graph
while handling changing relationships and maintaining historical context.
With Graphiti, you can build LLM applications such as:
- Assistants that learn from user interactions, fusing personal knowledge with dynamic data from business systems like
CRMs and billing platforms.
- Agents that autonomously execute complex tasks, reasoning with state changes from multiple dynamic sources.
Graphiti supports a wide range of applications in sales, customer service, health, finance, and more, enabling long-term
recall and state-based reasoning for both assistants and agents.
## Why Graphiti?
We were intrigued by Microsoft’s GraphRAG, which expanded on RAG text chunking by using a graph to better model a
document corpus and making this representation available via semantic and graph search techniques. However, GraphRAG did
not address our core problem: It's primarily designed for static documents and doesn't inherently handle temporal
aspects of data.
Graphiti is designed from the ground up to handle constantly changing information, hybrid semantic and graph search, and
scale:
- **Temporal Awareness:** Tracks changes in facts and relationships over time, enabling point-in-time queries. Graph
edges include temporal metadata to record relationship lifecycles.
- **Episodic Processing:** Ingests data as discrete episodes, maintaining data provenance and allowing incremental
entity and relationship extraction.
- **Hybrid Search:** Combines semantic and BM25 full-text search, with the ability to rerank results by distance from a
central node e.g. “Kendra”.
- **Scalable:** Designed for processing large datasets, with parallelization of LLM calls for bulk processing while
preserving the chronology of events.
- **Supports Varied Sources:** Can ingest both unstructured text and structured JSON data.
<p align="center">
<img src="/images/graphiti-intro-slides-stock-2.gif" alt="Graphiti structured + unstructured demo" width="700px">
</p>
## Graphiti and Zep Memory
Graphiti powers the core of [Zep's memory layer](https://www.getzep.com) for LLM-powered Assistants and Agents.
We're excited to open-source Graphiti, believing its potential reaches far beyond memory applications.
## Installation
Requirements:
- Python 3.10 or higher
- Neo4j 5.21 or higher
- OpenAI API key (for LLM inference and embedding)
Optional:
- Anthropic or Groq API key (for alternative LLM providers)
> [!TIP]
> The simplest way to install Neo4j is via [Neo4j Desktop](https://neo4j.com/download/). It provides a user-friendly
> interface to manage Neo4j instances and databases.
```bash
pip install graphiti-core
```
or
```bash
poetry add graphiti-core
```
## Quick Start
> [!IMPORTANT]
> Graphiti uses OpenAI for LLM inference and embedding. Ensure that an `OPENAI_API_KEY` is set in your environment.
> Support for Anthropic and Groq LLM inferences is available, too.
```python
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
from datetime import datetime
# Initialize Graphiti
graphiti = Graphiti("bolt://localhost:7687", "neo4j", "password")
# Initialize the graph database with Graphiti's indices. This only needs to be done once.
graphiti.build_indices_and_constraints()
# Add episodes
episodes = [
"Kamala Harris is the Attorney General of California. She was previously "
"the district attorney for San Francisco.",
"As AG, Harris was in office from January 3, 2011 – January 3, 2017",
]
for i, episode in enumerate(episodes):
await graphiti.add_episode(
name=f"Freakonomics Radio {i}",
episode_body=episode,
source=EpisodeType.text,
source_description="podcast",
reference_time=datetime.now()
)
# Search the graph
# Execute a hybrid search combining semantic similarity and BM25 retrieval
# Results are combined and reranked using Reciprocal Rank Fusion
results = await graphiti.search('Who was the California Attorney General?')
[
EntityEdge(
│ uuid = '3133258f738e487383f07b04e15d4ac0',
│ source_node_uuid = '2a85789b318d4e418050506879906e62',
│ target_node_uuid = 'baf7781f445945989d6e4f927f881556',
│ created_at = datetime.datetime(2024, 8, 26, 13, 13, 24, 861097),
│ name = 'HELD_POSITION',
# the fact reflects the updated state that Harris is
# no longer the AG of California
│ fact = 'Kamala Harris was the Attorney General of California',
│ fact_embedding = [
│ │ -0.009955154731869698,
│ ...
│ │ 0.00784289836883545
│],
│ episodes = ['b43e98ad0a904088a76c67985caecc22'],
│ expired_at = datetime.datetime(2024, 8, 26, 20, 18, 1, 53812),
# These dates represent the date this edge was true.
│ valid_at = datetime.datetime(2011, 1, 3, 0, 0, tzinfo= < UTC >),
│ invalid_at = datetime.datetime(2017, 1, 3, 0, 0, tzinfo= < UTC >)
)
]
# Rerank search results based on graph distance
# Provide a node UUID to prioritize results closer to that node in the graph.
# Results are weighted by their proximity, with distant edges receiving lower scores.
await graphiti.search('Who was the California Attorney General?', center_node_uuid)
# Close the connection
graphiti.close()
```
## Graph Service
The `server` directory contains an API service for interacting with the Graphiti API. It is built using FastAPI.
Please see the [server README](./server/README.md) for more information.
## Documentation
- [Guides and API documentation](https://help.getzep.com/graphiti).
- [Quick Start](https://help.getzep.com/graphiti/graphiti/quick-start)
- [Building an agent with LangChain's LangGraph and Graphiti](https://help.getzep.com/graphiti/graphiti/lang-graph-agent)
## Status and Roadmap
Graphiti is under active development. We aim to maintain API stability while working on:
- [x] Implementing node and edge CRUD operations
- [ ] Improving performance and scalability
- [ ] Achieving good performance with different LLM and embedding models
- [ ] Creating a dedicated embedder interface
- [ ] Supporting custom graph schemas:
- Allow developers to provide their own defined node and edge classes when ingesting episodes
- Enable more flexible knowledge representation tailored to specific use cases
- [ ] Enhancing retrieval capabilities with more robust and configurable options
- [ ] Expanding test coverage to ensure reliability and catch edge cases
## Contributing
We encourage and appreciate all forms of contributions, whether it's code, documentation, addressing GitHub Issues, or
answering questions in the Graphiti Discord channel. For detailed guidelines on code contributions, please refer
to [CONTRIBUTING](CONTRIBUTING.md).
## Support
Join the [Zep Discord server](https://discord.com/invite/W8Kw6bsgXQ) and make your way to the **#Graphiti** channel!
Raw data
{
"_id": null,
"home_page": null,
"name": "graphiti-core",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Paul Paliychuk",
"author_email": "paul@getzep.com",
"download_url": "https://files.pythonhosted.org/packages/c4/d3/6847885f2889ba9df341a6377441b905466c663cc9a0b9918df42cb24def/graphiti_core-0.3.16.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n<img width=\"350\" alt=\"Graphiti-ts-small\" src=\"https://github.com/user-attachments/assets/bbd02947-e435-4a05-b25a-bbbac36d52c8\">\n\n## Temporal Knowledge Graphs for Agentic Applications\n\n<br />\n\n[](https://discord.com/invite/W8Kw6bsgXQ)\n[](https://github.com/getzep/Graphiti/actions/workflows/lint.yml)\n[](https://github.com/getzep/Graphiti/actions/workflows/unit_tests.yml)\n[](https://github.com/getzep/Graphiti/actions/workflows/typecheck.yml)\n[](https://codespaces.new/getzep/Graphiti)\n\n<br />\n\n</div>\n\nGraphiti builds dynamic, temporally aware Knowledge Graphs that represent complex, evolving relationships between\nentities over time. Graphiti ingests both unstructured and structured data, and the resulting graph may be queried using\na fusion of time, full-text, semantic, and graph algorithm approaches.\n\n<br />\n\n<p align=\"center\">\n <img src=\"/images/graphiti-graph-intro.gif\" alt=\"Graphiti temporal walkthrough\" width=\"700px\"> \n</p>\n\n<br />\n\nGraphiti helps you create and query Knowledge Graphs that evolve over time. A knowledge graph is a network of\ninterconnected facts, such as _\u201cKendra loves Adidas shoes.\u201d_ Each fact is a \u201ctriplet\u201d represented by two entities, or\nnodes (_\u201dKendra\u201d_, _\u201cAdidas shoes\u201d_), and their relationship, or edge (_\u201dloves\u201d_). Knowledge Graphs have been explored\nextensively for information retrieval. What makes Graphiti unique is its ability to autonomously build a knowledge graph\nwhile handling changing relationships and maintaining historical context.\n\nWith Graphiti, you can build LLM applications such as:\n\n- Assistants that learn from user interactions, fusing personal knowledge with dynamic data from business systems like\n CRMs and billing platforms.\n- Agents that autonomously execute complex tasks, reasoning with state changes from multiple dynamic sources.\n\nGraphiti supports a wide range of applications in sales, customer service, health, finance, and more, enabling long-term\nrecall and state-based reasoning for both assistants and agents.\n\n## Why Graphiti?\n\nWe were intrigued by Microsoft\u2019s GraphRAG, which expanded on RAG text chunking by using a graph to better model a\ndocument corpus and making this representation available via semantic and graph search techniques. However, GraphRAG did\nnot address our core problem: It's primarily designed for static documents and doesn't inherently handle temporal\naspects of data.\n\nGraphiti is designed from the ground up to handle constantly changing information, hybrid semantic and graph search, and\nscale:\n\n- **Temporal Awareness:** Tracks changes in facts and relationships over time, enabling point-in-time queries. Graph\n edges include temporal metadata to record relationship lifecycles.\n- **Episodic Processing:** Ingests data as discrete episodes, maintaining data provenance and allowing incremental\n entity and relationship extraction.\n- **Hybrid Search:** Combines semantic and BM25 full-text search, with the ability to rerank results by distance from a\n central node e.g. \u201cKendra\u201d.\n- **Scalable:** Designed for processing large datasets, with parallelization of LLM calls for bulk processing while\n preserving the chronology of events.\n- **Supports Varied Sources:** Can ingest both unstructured text and structured JSON data.\n\n<p align=\"center\">\n <img src=\"/images/graphiti-intro-slides-stock-2.gif\" alt=\"Graphiti structured + unstructured demo\" width=\"700px\"> \n</p>\n\n## Graphiti and Zep Memory\n\nGraphiti powers the core of [Zep's memory layer](https://www.getzep.com) for LLM-powered Assistants and Agents.\n\nWe're excited to open-source Graphiti, believing its potential reaches far beyond memory applications.\n\n## Installation\n\nRequirements:\n\n- Python 3.10 or higher\n- Neo4j 5.21 or higher\n- OpenAI API key (for LLM inference and embedding)\n\nOptional:\n\n- Anthropic or Groq API key (for alternative LLM providers)\n\n> [!TIP]\n> The simplest way to install Neo4j is via [Neo4j Desktop](https://neo4j.com/download/). It provides a user-friendly\n> interface to manage Neo4j instances and databases.\n\n```bash\npip install graphiti-core\n```\n\nor\n\n```bash\npoetry add graphiti-core\n```\n\n## Quick Start\n\n> [!IMPORTANT]\n> Graphiti uses OpenAI for LLM inference and embedding. Ensure that an `OPENAI_API_KEY` is set in your environment.\n> Support for Anthropic and Groq LLM inferences is available, too.\n\n```python\nfrom graphiti_core import Graphiti\nfrom graphiti_core.nodes import EpisodeType\nfrom datetime import datetime\n\n# Initialize Graphiti\ngraphiti = Graphiti(\"bolt://localhost:7687\", \"neo4j\", \"password\")\n\n# Initialize the graph database with Graphiti's indices. This only needs to be done once.\ngraphiti.build_indices_and_constraints()\n\n# Add episodes\nepisodes = [\n \"Kamala Harris is the Attorney General of California. She was previously \"\n \"the district attorney for San Francisco.\",\n \"As AG, Harris was in office from January 3, 2011 \u2013 January 3, 2017\",\n]\nfor i, episode in enumerate(episodes):\n await graphiti.add_episode(\n name=f\"Freakonomics Radio {i}\",\n episode_body=episode,\n source=EpisodeType.text,\n source_description=\"podcast\",\n reference_time=datetime.now()\n )\n\n# Search the graph\n# Execute a hybrid search combining semantic similarity and BM25 retrieval\n# Results are combined and reranked using Reciprocal Rank Fusion\nresults = await graphiti.search('Who was the California Attorney General?')\n[\n EntityEdge(\n\u2502 uuid = '3133258f738e487383f07b04e15d4ac0',\n\u2502 source_node_uuid = '2a85789b318d4e418050506879906e62',\n\u2502 target_node_uuid = 'baf7781f445945989d6e4f927f881556',\n\u2502 created_at = datetime.datetime(2024, 8, 26, 13, 13, 24, 861097),\n\u2502 name = 'HELD_POSITION',\n# the fact reflects the updated state that Harris is\n# no longer the AG of California\n\u2502 fact = 'Kamala Harris was the Attorney General of California',\n\u2502 fact_embedding = [\n\u2502 \u2502 -0.009955154731869698,\n\u2502 ...\n\u2502 \u2502 0.00784289836883545\n\u2502],\n\u2502 episodes = ['b43e98ad0a904088a76c67985caecc22'],\n\u2502 expired_at = datetime.datetime(2024, 8, 26, 20, 18, 1, 53812),\n# These dates represent the date this edge was true.\n\u2502 valid_at = datetime.datetime(2011, 1, 3, 0, 0, tzinfo= < UTC >),\n\u2502 invalid_at = datetime.datetime(2017, 1, 3, 0, 0, tzinfo= < UTC >)\n)\n]\n\n# Rerank search results based on graph distance\n# Provide a node UUID to prioritize results closer to that node in the graph.\n# Results are weighted by their proximity, with distant edges receiving lower scores.\nawait graphiti.search('Who was the California Attorney General?', center_node_uuid)\n\n# Close the connection\ngraphiti.close()\n```\n\n## Graph Service\n\nThe `server` directory contains an API service for interacting with the Graphiti API. It is built using FastAPI.\n\nPlease see the [server README](./server/README.md) for more information.\n\n## Documentation\n\n- [Guides and API documentation](https://help.getzep.com/graphiti).\n- [Quick Start](https://help.getzep.com/graphiti/graphiti/quick-start)\n- [Building an agent with LangChain's LangGraph and Graphiti](https://help.getzep.com/graphiti/graphiti/lang-graph-agent)\n\n## Status and Roadmap\n\nGraphiti is under active development. We aim to maintain API stability while working on:\n\n- [x] Implementing node and edge CRUD operations\n- [ ] Improving performance and scalability\n- [ ] Achieving good performance with different LLM and embedding models\n- [ ] Creating a dedicated embedder interface\n- [ ] Supporting custom graph schemas:\n - Allow developers to provide their own defined node and edge classes when ingesting episodes\n - Enable more flexible knowledge representation tailored to specific use cases\n- [ ] Enhancing retrieval capabilities with more robust and configurable options\n- [ ] Expanding test coverage to ensure reliability and catch edge cases\n\n## Contributing\n\nWe encourage and appreciate all forms of contributions, whether it's code, documentation, addressing GitHub Issues, or\nanswering questions in the Graphiti Discord channel. For detailed guidelines on code contributions, please refer\nto [CONTRIBUTING](CONTRIBUTING.md).\n\n## Support\n\nJoin the [Zep Discord server](https://discord.com/invite/W8Kw6bsgXQ) and make your way to the **#Graphiti** channel!\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A temporal graph building library",
"version": "0.3.16",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7fa7cae145f03f8827e6241631722ad1add242ecbe19ab87671cf3f1c2cf4183",
"md5": "5ea9663a90227ff8fbac4d8e9c2d5bb7",
"sha256": "2d9d1f51e822d29a09c54655118419ca09ce01181df0e779fa455707123d4ec3"
},
"downloads": -1,
"filename": "graphiti_core-0.3.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ea9663a90227ff8fbac4d8e9c2d5bb7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 76958,
"upload_time": "2024-10-22T14:33:51",
"upload_time_iso_8601": "2024-10-22T14:33:51.856463Z",
"url": "https://files.pythonhosted.org/packages/7f/a7/cae145f03f8827e6241631722ad1add242ecbe19ab87671cf3f1c2cf4183/graphiti_core-0.3.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c4d36847885f2889ba9df341a6377441b905466c663cc9a0b9918df42cb24def",
"md5": "7ff4eec3a82aae95c3ba94e67e4abb02",
"sha256": "f0e805df16bce69b9236fca45a354c23888a3d09ee43e73ac424a052c3cdf9fa"
},
"downloads": -1,
"filename": "graphiti_core-0.3.16.tar.gz",
"has_sig": false,
"md5_digest": "7ff4eec3a82aae95c3ba94e67e4abb02",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 50653,
"upload_time": "2024-10-22T14:33:53",
"upload_time_iso_8601": "2024-10-22T14:33:53.714418Z",
"url": "https://files.pythonhosted.org/packages/c4/d3/6847885f2889ba9df341a6377441b905466c663cc9a0b9918df42cb24def/graphiti_core-0.3.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 14:33:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "graphiti-core"
}
