Graphiti

https://help.getzep.com/graphiti/
Admin
Graphiti is a Python framework for building temporally-aware knowledge graphs designed for AI...
Tokens:29,931
Snippets:253
Trust Score:8.4
Update:9 hours ago
Show doc for...
Tokens:
Raw
### Install graphiti-core with uv

Source: https://help.getzep.com/graphiti/getting-started/quick-start

Alternative installation method using uv, a fast Python package installer.

```bash
uv add graphiti-core
```

--------------------------------

### Install graphiti-core with Neptune extra using uv

Source: https://help.getzep.com/graphiti/configuration/neptune-configuration

Install the required dependencies for Neptune integration using uv.

```bash
uv add graphiti-core[neptune]
```

--------------------------------

### Install graphiti-core with Groq support

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Install the Graphiti core package with the Groq extra to enable Groq integration.

```bash
pip install "graphiti-core[groq]"
```

--------------------------------

### Install graphiti-core

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Install the graphiti-core package using pip.

```bash
pip install graphiti-core
```

--------------------------------

### Install dependencies with pip

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Install required packages: graphiti-core, langchain-openai, langgraph, and ipywidgets. Ensure Neo4j is installed per the Graphiti quick-start guide.

```bash
pip install graphiti-core langchain-openai langgraph ipywidgets
```

--------------------------------

### Install Graphiti with FalkorDB support using uv

Source: https://help.getzep.com/graphiti/configuration/falkordb-configuration

Alternative installation method using uv package manager. Requires version 1.1.2 or higher.

```bash
uv add graphiti-core[falkordb]
```

--------------------------------

### Clone and install Graphiti MCP server

Source: https://help.getzep.com/graphiti/getting-started/mcp-server

Clone the Graphiti repository and install the MCP server dependencies using uv.

```bash
git clone https://github.com/getzep/graphiti.git
cd graphiti
```

```bash
cd mcp_server
uv sync
```

--------------------------------

### Install Graphiti with Google Gemini support

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Install the graphiti-core package with the google-genai extra to enable Google Gemini integration.

```bash
pip install "graphiti-core[google-genai]"
```

--------------------------------

### Neo4j environment configuration

Source: https://help.getzep.com/graphiti/getting-started/mcp-server

Set connection variables for Neo4j and select the provider when starting the server.

```bash
OPENAI_API_KEY=your_openai_api_key_here
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password
```

--------------------------------

### Install graphiti-core with Neptune extra using pip

Source: https://help.getzep.com/graphiti/configuration/neptune-configuration

Install the required dependencies for Neptune integration using pip.

```bash
pip install graphiti-core[neptune]
```

--------------------------------

### Install Graphiti with Anthropic support

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Install the graphiti-core package with the anthropic extra to enable Anthropic Claude integration.

```bash
pip install "graphiti-core[anthropic]"
```

--------------------------------

### Run MCP server with Neo4j provider

Source: https://help.getzep.com/graphiti/getting-started/mcp-server

Start the server with the Neo4j database provider using a command-line argument.

```bash
uv run main.py --database-provider neo4j
```

--------------------------------

### Install Ollama and pull models

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Install Ollama and pull the required models: deepseek-r1:7b for the LLM and nomic-embed-text for embeddings.

```bash
# Install Ollama (visit https://ollama.ai for installation instructions)
# Then pull the models you want to use:
ollama pull deepseek-r1:7b     # LLM
ollama pull nomic-embed-text   # embeddings
```

--------------------------------

### Run MCP server with default transport

Source: https://help.getzep.com/graphiti/getting-started/mcp-server

Start the server from the mcp_server directory using streamable HTTP transport.

```bash
uv run main.py
```

--------------------------------

### Docker Compose deployment

Source: https://help.getzep.com/graphiti/getting-started/mcp-server

Run the provided Compose file from the mcp_server directory to start FalkorDB and the MCP server.

```bash
docker compose -f docker/docker-compose.yml up
```

--------------------------------

### Edge type mapping: good and overly granular examples

Source: https://help.getzep.com/graphiti/core-concepts/custom-entity-and-edge-types

Shows two edge_type_map examples: a good one with specific but meaningful entity type pairs, and an overly granular one that creates too many specific types. Use the good example to balance specificity and generality.

```python
# Good: Specific and meaningful
edge_type_map = {
    ("Person", "Company"): ["Employment", "Investment"],
    ("Company", "Company"): ["Partnership", "Acquisition"],
    ("Person", "Product"): ["Usage", "Review"],
}
```

```python
# Avoid: Too granular
edge_type_map = {
    ("CEO", "TechCompany"): ["CEOEmployment"],
    ("Engineer", "TechCompany"): ["EngineerEmployment"],
    # This creates too many specific types
}
```

--------------------------------

### Install Graphiti with FalkorDB support using pip

Source: https://help.getzep.com/graphiti/configuration/falkordb-configuration

Install the Graphiti package with FalkorDB dependencies using pip. Requires version 1.1.2 or higher.

```bash
pip install graphiti-core[falkordb]
```

--------------------------------

### Hybrid Search and Node Distance Reranking Example

Source: https://help.getzep.com/graphiti/working-with-data/searching

Demonstrates both search approaches: hybrid search using `await graphiti.search(query)` and node distance reranking using `await graphiti.search(query, focal_node_uuid)`. The example shows how to retrieve facts and print them, with sample output for each method.

```python
query = "Can Jane wear Allbirds Wool Runners?"
jane_node_uuid = "123e4567-e89b-12d3-a456-426614174000"
def print_facts(edges):
    print("\n".join([edge.fact for edge in edges]))
# Hybrid Search
results = await graphiti.search(query)
print_facts(results)
# The Allbirds Wool Runners are sold by Allbirds.
# Men's SuperLight Wool Runners - Dark Grey (Medium Grey Sole) has a runner silhouette.
# Jane purchased SuperLight Wool Runners.
# Hybrid Search with Node Distance Reranking
reranked_results = await graphiti.search(
    query,
    center_node_uuid=jane_node_uuid,
)
print_facts(reranked_results)
# Jane purchased SuperLight Wool Runners.
# Jane is allergic to wool.
# The Allbirds Wool Runners are sold by Allbirds.
```

--------------------------------

### Docker Installation for Neo4j Enterprise Edition

Source: https://help.getzep.com/graphiti/configuration/neo4j-configuration

Runs a Neo4j 5.26 Enterprise container with APOC plugin, authentication, and license acceptance.

```bash
docker run \
    --name neo4j-enterprise \
    -p 7474:7474 -p 7687:7687 \
    -e NEO4J_AUTH=neo4j/your_password \
    -e NEO4J_PLUGINS='["apoc"]' \
    -e NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
    neo4j:5.26-enterprise
```

--------------------------------

### Multi-tenant namespacing example

Source: https://help.getzep.com/graphiti/core-concepts/graph-namespacing

Shows how to use tenant_id as a namespace for adding and searching customer data. The add_customer_data function creates an episode with a group_id based on the tenant, while search_tenant_data queries only within that tenant's namespace using group_ids.

```python
import json
async def add_customer_data(tenant_id, customer_data):
    """Add customer data to a tenant-specific namespace"""
    
    # Use the tenant_id as the namespace
    namespace = f"tenant_{tenant_id}"
    
    # Create an episode for this customer data
    await graphiti.add_episode(
        name=f"customer_data_{customer_data['id']}",
        episode_body=json.dumps(customer_data),
        source=EpisodeType.json,
        source_description="Customer profile update",
        reference_time=datetime.now(),
        group_id=namespace  # Namespace by tenant
    )
async def search_tenant_data(tenant_id, query):
    """Search within a tenant's namespace"""
    
    namespace = f"tenant_{tenant_id}"
    
    # Only search within this tenant's namespace
    return await graphiti.search(
        query=query,
        group_ids=[namespace]
    )
```

--------------------------------

### Docker Installation for Neo4j Community Edition

Source: https://help.getzep.com/graphiti/configuration/neo4j-configuration

Runs a Neo4j 5.26 Community container with APOC plugin and authentication. Exposes ports 7474 and 7687.

```bash
docker run \
    --name neo4j-community \
    -p 7474:7474 -p 7687:7687 \
    -e NEO4J_AUTH=neo4j/your_password \
    -e NEO4J_PLUGINS='["apoc"]' \
    neo4j:5.26-community
```

--------------------------------

### Run FalkorDB locally with Docker

Source: https://help.getzep.com/graphiti/configuration/falkordb-configuration

Starts a FalkorDB container exposing port 6379 for Redis protocol and port 3000 for web interface. Runs in foreground mode for easy testing.

```bash
docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
```

--------------------------------

### Configure Graphiti Client

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Initializes the Graphiti client using environment variables with defaults. Requires neo4j running and a database created.

```python
# Configure Graphiti
from graphiti_core import Graphiti
from graphiti_core.edges import EntityEdge
from graphiti_core.nodes import EpisodeType
from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_EPISODE_MENTIONS
from graphiti_core.utils.bulk_utils import RawEpisode
from graphiti_core.utils.maintenance.graph_data_operations import clear_data
neo4j_uri = os.environ.get('NEO4J_URI', 'bolt://localhost:7687')
neo4j_user = os.environ.get('NEO4J_USER', 'neo4j')
neo4j_password = os.environ.get('NEO4J_PASSWORD', 'password')
client = Graphiti(
    neo4j_uri,
    neo4j_user,
    neo4j_password,
)

```

--------------------------------

### Initialize LLM with bound tools

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Creates a ChatOpenAI instance with the gpt-4.1-mini model, zero temperature, and binds the tools variable. This is the first step before testing the tool node.

```python
llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0).bind_tools(tools)
```

--------------------------------

### Set up logging

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Defines a setup_logging() function that configures a logger to output INFO-level messages to stdout with a specific format. The logger is then created and assigned to the variable 'logger'.

```python
def setup_logging():
    logger = logging.getLogger()
    logger.setLevel(logging.ERROR)
    console_handler = logging.StreamHandler(sys.stdout)
    console_handler.setLevel(logging.INFO)
    formatter = logging.Formatter('%(name)s - %(levelname)s - %(message)s')
    console_handler.setFormatter(formatter)
    logger.addHandler(console_handler)
    return logger
logger = setup_logging()
```

--------------------------------

### Configure logging and Neo4j environment variables

Source: https://help.getzep.com/graphiti/getting-started/quick-start

Sets up logging and loads environment variables for Neo4j connection parameters, with defaults and a validation check.

```python
# Configure logging
logging.basicConfig(
    level=INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S',
)
logger = logging.getLogger(__name__)
load_dotenv()
# Neo4j connection parameters
# Make sure Neo4j Desktop is running with a local DBMS started
neo4j_uri = os.environ.get('NEO4J_URI', 'bolt://localhost:7687')
neo4j_user = os.environ.get('NEO4J_USER', 'neo4j')
neo4j_password = os.environ.get('NEO4J_PASSWORD', 'password')
if not neo4j_uri or not neo4j_user or not neo4j_password:
    raise ValueError('NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD must be set')
```

--------------------------------

### Delete an entity edge

Source: https://help.getzep.com/graphiti/working-with-data/crud-operations

Deletes an entity edge through the same namespace. The entity edge namespace also provides methods to get edges between two nodes, get edges for one node, and operate on lists of UUIDs.

```python
await graphiti.edges.entity.delete(loaded_edge)
```

--------------------------------

### Claude Desktop stdio client configuration

Source: https://help.getzep.com/graphiti/getting-started/mcp-server

Configure a stdio client for Claude Desktop with the main.py entry point, including environment variables for Neo4j.

```json
{
  "mcpServers": {
    "graphiti-context": {
      "transport": "stdio",
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/graphiti/mcp_server",
        "main.py",
        "--transport",
        "stdio",
        "--database-provider",
        "neo4j"
      ],
      "env": {
        "OPENAI_API_KEY": "your_api_key",
        "MODEL_NAME": "gpt-5.5",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  }
}
```

--------------------------------

### Get an entity node

Source: https://help.getzep.com/graphiti/working-with-data/crud-operations

Retrieves an entity node by its UUID, or multiple nodes by UUIDs or group IDs.

```APIDOC
## Get an entity node

### Description
Retrieves an entity node by its UUID, or multiple nodes by UUIDs or group IDs.

### Methods
- get_by_uuid
- get_by_uuids
- get_by_group_ids

### Namespace
graphiti.nodes.entity

### Parameters
- **uuid** (str) - Required - The UUID of the node to retrieve.
- **uuids** (list[str]) - Required - List of UUIDs to retrieve.
- **group_ids** (list[str]) - Required - List of group IDs to retrieve nodes for.
- **limit** (int) - Optional - Maximum number of nodes to return (default 100).

### Request Example
```python
node = await graphiti.nodes.entity.get_by_uuid(saved_node.uuid)
nodes = await graphiti.nodes.entity.get_by_uuids(["uuid-1", "uuid-2"])
group_nodes = await graphiti.nodes.entity.get_by_group_ids(
    ["customer-123"],
    limit=100,
)
```

### Response
Returns the requested EntityNode or list of EntityNodes.
```

--------------------------------

### Get an entity node

Source: https://help.getzep.com/graphiti/working-with-data/crud-operations

Retrieves a single entity node by UUID, or multiple nodes by UUIDs or group IDs.

```python
node = await graphiti.nodes.entity.get_by_uuid(saved_node.uuid)
```

```python
nodes = await graphiti.nodes.entity.get_by_uuids(["uuid-1", "uuid-2"])
group_nodes = await graphiti.nodes.entity.get_by_group_ids(
    ["customer-123"],
    limit=100,
)
```

--------------------------------

### Initialize Graphiti with Neo4j connection

Source: https://help.getzep.com/graphiti/getting-started/quick-start

Connects to Neo4j, builds indices and constraints, and closes the connection in a finally block.

```python
# Initialize Graphiti with Neo4j connection
graphiti = Graphiti(neo4j_uri, neo4j_user, neo4j_password)
try:
    # Initialize the graph database with graphiti's indices. This only needs to be done once.
    await graphiti.build_indices_and_constraints()
    
    # Additional code will go here
    
finally:
    # Close the connection
    await graphiti.close()
    print('\nConnection closed')
```

--------------------------------

### Connect to Neptune and create Graphiti instance in Python

Source: https://help.getzep.com/graphiti/configuration/neptune-configuration

Create a NeptuneDriver using environment variables and pass it to Graphiti. Requires NEPTUNE_HOST and AOSS_HOST to be set, otherwise raises ValueError. The port is optional and defaults to 8182.

```python
import os
from graphiti_core import Graphiti
from graphiti_core.driver.neptune_driver import NeptuneDriver
# Get connection parameters from environment
neptune_uri = os.getenv('NEPTUNE_HOST')
neptune_port = int(os.getenv('NEPTUNE_PORT', 8182))
aoss_host = os.getenv('AOSS_HOST')
# Validate required parameters
if not neptune_uri or not aoss_host:
    raise ValueError("NEPTUNE_HOST and AOSS_HOST environment variables must be set")
# Create Neptune driver
driver = NeptuneDriver(
    host=neptune_uri,        # Required: neptune-db:// endpoint or neptune-graph:// graph ID
    aoss_host=aoss_host,     # Required: OpenSearch Serverless collection endpoint
    port=neptune_port        # Optional: Neptune port (defaults to 8182)
)
# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)
```

--------------------------------

### Configure Graphiti with Google Gemini clients

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Initializes Graphiti with GeminiClient for LLM inference, GeminiEmbedder for embeddings, and GeminiRerankerClient for cross-encoding. Uses gemini-3.7-flash for generation and reranking. Requires a Google API key.

```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
from graphiti_core.cross_encoder.gemini_reranker_client import GeminiRerankerClient
# Google API key configuration
api_key = "<your-google-api-key>"
# Initialize Graphiti with Gemini clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=GeminiClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-3.7-flash"
        )
    ),
    embedder=GeminiEmbedder(
        config=GeminiEmbedderConfig(
            api_key=api_key,
            embedding_model="embedding-001"
        )
    ),
    cross_encoder=GeminiRerankerClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-3.7-flash"
        )
    )
)
```

--------------------------------

### Save and get an entity edge

Source: https://help.getzep.com/graphiti/working-with-data/crud-operations

Saves an EntityEdge to the graph and retrieves it by UUID. The entity edge namespace generates the fact embedding before saving.

```APIDOC
## Save and get an entity edge

### Description
Saves an EntityEdge to the graph and retrieves it by UUID. The entity edge namespace generates the fact embedding before saving the edge.

### Methods
- save
- get_by_uuid

### Namespace
graphiti.edges.entity

### Parameters
- **edge** (EntityEdge) - Required - The edge to save.
- **uuid** (str) - Required - The UUID of the edge to retrieve.

### Request Example
```python
from datetime import datetime, timezone
from graphiti_core.edges import EntityEdge
from graphiti_core.nodes import EntityNode
target_node = await graphiti.nodes.entity.save(
    EntityNode(
        name="Graphiti",
        group_id="customer-123",
        summary="A temporal knowledge graph framework",
    )
)
edge = EntityEdge(
    name="USES",
    fact="Acme uses Graphiti",
    group_id="customer-123",
    source_node_uuid=saved_node.uuid,
    target_node_uuid=target_node.uuid,
    created_at=datetime.now(timezone.utc),
)
saved_edge = await graphiti.edges.entity.save(edge)
loaded_edge = await graphiti.edges.entity.get_by_uuid(saved_edge.uuid)
```

### Response
Returns the saved or loaded EntityEdge.
```

--------------------------------

### Create async main function

Source: https://help.getzep.com/graphiti/getting-started/quick-start

Defines the async main function and runs it with asyncio.run.

```python
async def main():
    # Main function implementation will go here
    pass
if __name__ == '__main__':
    asyncio.run(main())
```

--------------------------------

### Clear Database and Build Indices

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Destructive operation that wipes the entire database. Only required for the first run or when starting over. Builds indices and constraints after clearing.

```python
# Note: This will clear the database
await clear_data(client.driver)
await client.build_indices_and_constraints()

```

--------------------------------

### Compound contact_info attribute (anti-pattern)

Source: https://help.getzep.com/graphiti/core-concepts/custom-entity-and-edge-types

Shows an example of storing compound information in a single attribute, which is discouraged. Use atomic attributes instead for better granularity.

```python
class Customer(BaseModel):
    contact_info: Optional[str] = Field(None, description="Name and email")  # Don't do this
```

--------------------------------

### Save and get an entity edge

Source: https://help.getzep.com/graphiti/working-with-data/crud-operations

Creates a target EntityNode, saves it, then creates and saves an EntityEdge, and retrieves it. The entity edge namespace generates the fact embedding before saving.

```python
from datetime import datetime, timezone
from graphiti_core.edges import EntityEdge
from graphiti_core.nodes import EntityNode
target_node = await graphiti.nodes.entity.save(
    EntityNode(
        name="Graphiti",
        group_id="customer-123",
        summary="A temporal knowledge graph framework",
    )
)
edge = EntityEdge(
    name="USES",
    fact="Acme uses Graphiti",
    group_id="customer-123",
    source_node_uuid=saved_node.uuid,
    target_node_uuid=target_node.uuid,
    created_at=datetime.now(timezone.utc),
)
saved_edge = await graphiti.edges.entity.save(edge)
loaded_edge = await graphiti.edges.entity.get_by_uuid(saved_edge.uuid)
```

--------------------------------

### Exclude entity types from extraction with excluded_entity_types

Source: https://help.getzep.com/graphiti/core-concepts/custom-entity-and-edge-types

Use the excluded_entity_types parameter in add_episode to prevent extraction of specified entity types, such as 'Person'. This example shows excluding Person entities while still extracting other types.

```python
await graphiti.add_episode(
    name="Business Update",
    episode_body="The meeting discussed various topics including weather and sports.",
    source_description="Meeting notes",
    reference_time=datetime.now(),
    entity_types=entity_types,
    excluded_entity_types=["Person"]  # Won't extract Person entities
)
```

--------------------------------

### Connect to FalkorDB in Python

Source: https://help.getzep.com/graphiti/configuration/falkordb-configuration

Creates a FalkorDriver instance using environment variables and initializes Graphiti with it. Connects via Redis protocol on port 6379. Authentication is typically not required for local instances.

```python
import os
from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver
falkor_driver = FalkorDriver(
    host=os.environ.get("FALKORDB_HOST", "localhost"),
    port=int(os.environ.get("FALKORDB_PORT", "6379")),
    username=os.environ.get("FALKORDB_USERNAME"),
    password=os.environ.get("FALKORDB_PASSWORD"),
)
graphiti = Graphiti(graph_driver=falkor_driver)
```

--------------------------------

### Configure Groq LLM with OpenAI embeddings and reranking

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Sets up a Graphiti instance using GroqClient for the LLM, OpenAIEmbedder for embeddings, and OpenAIRerankerClient for reranking. Requires Groq and OpenAI API keys. Uses the llama-3.1-70b-versatile model and smaller model for small tasks.

```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.groq_client import GroqClient, LLMConfig
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
# Configure Groq LLM with OpenAI embeddings and reranking
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password", 
    llm_client=GroqClient(
        config=LLMConfig(
            api_key="<your-groq-api-key>",
            model="llama-3.1-70b-versatile",
            small_model="llama-3.1-8b-instant"
        )
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="<your-openai-api-key>",
            embedding_model="text-embedding-3-small"
        )
    ),
    cross_encoder=OpenAIRerankerClient(
        config=LLMConfig(
            api_key="<your-openai-api-key>",
            model="gpt-4.1-nano"
        )
    )
)
```

--------------------------------

### Configure Graphiti with Anthropic LLM and OpenAI embeddings

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Initializes Graphiti with AnthropicClient for LLM inference, OpenAIEmbedder for embeddings, and OpenAIRerankerClient for reranking. Requires both ANTHROPIC_API_KEY and OPENAI_API_KEY environment variables.

```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.anthropic_client import AnthropicClient, LLMConfig
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
# Configure Anthropic LLM with OpenAI embeddings and reranking
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j", 
    "password",
    llm_client=AnthropicClient(
        config=LLMConfig(
            api_key="<your-anthropic-api-key>",
            model="claude-sonnet-4-5-latest",
            small_model="claude-haiku-4-5-latest"
        )
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="<your-openai-api-key>",
            embedding_model="text-embedding-3-small"
        )
    ),
    cross_encoder=OpenAIRerankerClient(
        config=LLMConfig(
            api_key="<your-openai-api-key>",
            model="gpt-4.1-nano"
        )
    )
)
```

--------------------------------

### Ingest Products Data

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Loads shoe and related products from a JSON file into Graphiti. Only needs to be done once; rerun after clear_data. May take a while.

```python
async def ingest_products_data(client: Graphiti):
    script_dir = Path.cwd().parent
    json_file_path = script_dir / 'data' / 'manybirds_products.json'
    with open(json_file_path) as file:
        products = json.load(file)['products']
    episodes: list[RawEpisode] = [
        RawEpisode(
            name=product.get('title', f'Product {i}'),
            content=json.dumps({k: v for k, v in product.items() if k != 'images'}),
            source_description='ManyBirds products',
            source=EpisodeType.json,
            reference_time=datetime.now(),
        )
        for i, product in enumerate(products)
    ]
    await client.add_episode_bulk(episodes)
await ingest_products_data(client)

```

--------------------------------

### Invoke LangGraph agent with a sample user query

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Calls graph.ainvoke with a user message and configuration including a unique thread_id. The input includes user_name and user_node_uuid variables.

```python
await graph.ainvoke(
    {
        'messages': [
            {
                'role': 'user',
                'content': 'What sizes do the TinyBirds Wool Runners in Natural Black come in?',
            }
        ],
        'user_name': user_name,
        'user_node_uuid': user_node_uuid,
    },
    config={'configurable': {'thread_id': uuid.uuid4().hex}},
)
```

--------------------------------

### Import modules and load environment variables

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Imports standard and third-party libraries, including asyncio, json, logging, os, sys, uuid, ipywidgets, dotenv, IPython.display, and typing_extensions. Calls load_dotenv() to load environment variables.

```python
import asyncio
import json
import logging
import os
import sys
import uuid
from contextlib import suppress
from datetime import datetime
from pathlib import Path
from typing import Annotated
import ipywidgets as widgets
from dotenv import load_dotenv
from IPython.display import Image, display
from typing_extensions import TypedDict
load_dotenv()
```

--------------------------------

### Configure Graphiti with OpenAIGenericClient

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Python configuration for using OpenAI-compatible services with Graphiti. Sets up the LLM client, embedder, and cross-encoder with placeholder values for API keys, model names, and base URLs.

```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
# Configure OpenAI-compatible service
llm_config = LLMConfig(
    api_key="<your-api-key>",
    model="<your-main-model>",        # e.g., "mistral-large-latest"
    small_model="<your-small-model>", # e.g., "mistral-small-latest"
    base_url="<your-base-url>",       # e.g., "https://api.mistral.ai/v1"
)
# Initialize Graphiti with OpenAI-compatible service
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=OpenAIGenericClient(config=llm_config),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="<your-api-key>",
            embedding_model="<your-embedding-model>", # e.g., "mistral-embed"
            base_url="<your-base-url>",
        )
    ),
    cross_encoder=OpenAIRerankerClient(
        config=LLMConfig(
            api_key="<your-api-key>",
            model="<your-small-model>",  # Use smaller model for reranking
            base_url="<your-base-url>",
        )
    )
)
```

--------------------------------

### Configure Graphiti with Ollama clients

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Configure Graphiti to use Ollama's OpenAI-compatible API via OpenAIGenericClient, OpenAIEmbedder, and OpenAIRerankerClient. Ensure Ollama is running with 'ollama serve' and models are pulled.

```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
# Configure Ollama LLM client using OpenAIGenericClient for compatibility
llm_config = LLMConfig(
    api_key="ollama",  # Ollama doesn't require a real API key
    model="deepseek-r1:7b",
    small_model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1",
)
llm_client = OpenAIGenericClient(config=llm_config)
# Initialize Graphiti with Ollama clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="ollama",
            embedding_model="nomic-embed-text",
            embedding_dim=768,
            base_url="http://localhost:11434/v1",
        )
    ),
    cross_encoder=OpenAIRerankerClient(client=llm_client.client, config=llm_config),
)
```

--------------------------------

### Bulk load episodes with add_episode_bulk

Source: https://help.getzep.com/graphiti/core-concepts/adding-episodes

Loads multiple episodes in one batch using add_episode_bulk. The bulk path resolves invalidated edges and extracts temporal dates before saving. Requires importing RawEpisode from graphiti_core.utils.bulk_utils.

```python
import json
from datetime import datetime, timezone
from graphiti_core.nodes import EpisodeType
from graphiti_core.utils.bulk_utils import RawEpisode
product_data = [
    {
        "id": "PROD001",
        "name": "Men's SuperLight Wool Runners",
        "color": "Dark Grey",
        "sole_color": "Medium Grey",
        "material": "Wool",
        "technology": "SuperLight Foam",
        "price": 125.00,
        "in_stock": True,
        "last_updated": "2024-03-15T10:30:00Z"
    },
    {
        "id": "PROD0100",
        "name": "Kids Wool Runner-up Mizzles",
        "color": "Natural Grey",
        "sole_color": "Orange",
        "material": "Wool",
        "technology": "Water-repellent",
        "price": 80.00,
        "in_stock": True,
        "last_updated": "2024-03-17T14:45:00Z"
    }
]
bulk_episodes = [
    RawEpisode(
        name=f"Product Update - {product['id']}",
        content=json.dumps(product),
        source=EpisodeType.json,
        source_description="Allbirds product catalog update",
        reference_time=datetime.now(timezone.utc),
    )
    for product in product_data
]
await graphiti.add_episode_bulk(bulk_episodes)
```

--------------------------------

### Configure Azure OpenAI with Graphiti

Source: https://help.getzep.com/graphiti/configuration/llm-configuration

Configure Graphiti to use Azure OpenAI for LLM inference and embeddings. Uses Azure deployment names as model names. Requires an Azure OpenAI resource and API key.

```python
from openai import AsyncOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client.azure_openai_client import AzureOpenAILLMClient
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.openai.azure.com"
model_deployment = "<your-model-deployment>"
small_model_deployment = "<your-small-model-deployment>"
embedding_deployment = "<your-embedding-deployment>"
azure_client = AsyncOpenAI(
    base_url=f"{endpoint}/openai/v1/",
    api_key=api_key,
)
azure_llm_config = LLMConfig(
    model=model_deployment,
    small_model=small_model_deployment,
)
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=AzureOpenAILLMClient(
        azure_client=azure_client,
        config=azure_llm_config,
    ),
    embedder=AzureOpenAIEmbedderClient(
        azure_client=azure_client,
        model=embedding_deployment,
    ),
    cross_encoder=OpenAIRerankerClient(
        client=azure_client,
        config=LLMConfig(model=small_model_deployment),
    ),
)
```

--------------------------------

### Agent response output for sample query

Source: https://help.getzep.com/graphiti/integrations/lang-graph-agent

Shows the output of the agent invocation, containing the user message and the AI response with token usage metadata. The response lists available sizes for the TinyBirds Wool Runners.

```json
{
    "messages": [
        {
            "content": "What sizes do the TinyBirds Wool Runners in Natural Black come in?",
            "id": "6a940637-70a0-4c95-a4d7-4c4846909747",
            "type": "HumanMessage"
        },
        {
            "content": "The TinyBirds Wool Runners in Natural Black are available in the following sizes for little kids: 5T, 6T, 8T, 9T, and 10T. \n\nDo you have a specific size in mind, or are you looking for something else? Let me know your needs, and I can help you find the perfect pair!",
            "additional_kwargs": {
                "refusal": null
            },
            "response_metadata": {
                "token_usage": {
                    "completion_tokens": 76,
                    "prompt_tokens": 314,
                    "total_tokens": 390
                },
                "finish_reason": "stop",
                "logprobs": null
            },
            "id": "run-d2f79c7f-4d41-4896-88dc-476a8e38bea8-0",
            "usage_metadata": {
                "input_tokens": 314,
                "output_tokens": 76,
                "total_tokens": 390
            },
            "type": "AIMessage"
        }
    ],
    "user_name": "jess",
    "user_node_uuid": "186a845eee4849619d1e625b178d1845"
}
```

--------------------------------

### Build communities with graphiti.build_communities()

Source: https://help.getzep.com/graphiti/core-concepts/communities

Call this method on the graphiti class to generate communities. It removes existing communities before creating new ones, so rebuild periodically to recalculate all groups.

```typescript
await graphiti.build_communities()
```
Tokens:
Raw