From 928d2332641bd29369f41598ff73f84e2b733fdd Mon Sep 17 00:00:00 2001 From: antejavor Date: Mon, 27 Oct 2025 10:33:15 +0100 Subject: [PATCH 1/7] Init agents docs. --- pages/ai-ecosystem/agents.mdx | 442 ++++++++++++++++++++++++++++++++++ 1 file changed, 442 insertions(+) create mode 100644 pages/ai-ecosystem/agents.mdx diff --git a/pages/ai-ecosystem/agents.mdx b/pages/ai-ecosystem/agents.mdx new file mode 100644 index 000000000..c6273c574 --- /dev/null +++ b/pages/ai-ecosystem/agents.mdx @@ -0,0 +1,442 @@ +--- +title: Agents +description: Memgraph Agents: Here to help you out in building Graph AI applications. +--- +import { Callout, Steps } from 'nextra/components' + + +# Memgraph Agents + +Memgraph Agents are specialized tools designed to streamline and enhance the development of Graph applications. These agents leverage Large Language Models (LLMs) to provide intelligent solutions for various graph-related tasks. By the nature of technology maturity, some agents may be experimental and are continuously evolving to better serve your needs. + +{

Available Agents

} + +# SQL2Graph Agent + +## Overview + +The **SQL2Graph Agent** is an intelligent database migration agent that transforms relational databases (MySQL, PostgreSQL) into graph databases using AI-powered analysis. +It leverages Large Language Models (LLMs) to understand the semantics of your relational schema and generate an optimized property graph model for Memgraph. The +agent enables interactive modeling and refinement of the graph schema, validation after the migration. + +**Key Capabilities:** + +1. **Automatic Database Migration**: Performs end-to-end migration from SQL to graph with minimal user input. +2. **Interactive graph modeling**: Enables users to review and refine the generated graph model incrementally, before executing the migration. +3. **Validation**: Provides pre- and post-migration validation to communicate the quality and correctness of the migration. + + +The Agent supports two main **modeling strategies**: +1. **Deterministic Strategy**: Rule-based mapping of tables to nodes and foreign keys to relationships. +2. **LLM Strategy**: AI-powered analysis using LLMs to generate a semantically rich graph model. + +The agent can also be run in two **modes**: +1. **Automatic Mode**: Fully automated migration without user interaction. +2. **Incremental Mode**: Step-by-step review and refinement of the graph model before migration. + +These are controlled via CLI flags and environment variables. + +## How To Use The Agent + +From this point onward, it is assumed that you have Memgraph installed and running. If you haven't done so, please refer to the [Memgraph installation guide](https://memgraph.com/docs/memgraph/installation). + +Just make sure to start Memgraph with the `--schema-info-enabled=true` flag to enable schema information tracking: + +```bash +docker run -p 7687:7687 memgraph/memgraph --schema-info-enabled +``` + +It is also assumed that you have a running instance of either PostgreSQL or MySQL with a sample database to migrate. + +### Installation + +In order to use you first need to clone the repository and install the dependencies: + + +```bash +# Clone the repository +git clone https://github.com/memgraph/ai-toolkit + +# Navigate to the sql2graph directory +cd agents/sql2graph + +# Install dependencies using uv +uv pip install -e . +``` + +### Configuration + +The configuration enables you to control the agent flow via environment variables. The key information needed are the source database connection details, target Memgraph connection details, and LLM API keys and agent configuration. + +Create a `.env` and fill the following variables: + +```bash +# Source Database +SOURCE_DB_TYPE=postgresql # or mysql + +# PostgreSQL Configuration +POSTGRES_HOST=localhost +POSTGRES_PORT=5432 +POSTGRES_DATABASE=mydb +POSTGRES_USER=username +POSTGRES_PASSWORD=password +POSTGRES_SCHEMA=public + +# MySQL Configuration (if using MySQL) +MYSQL_HOST=localhost +MYSQL_PORT=3306 +MYSQL_DATABASE=mydb +MYSQL_USER=username +MYSQL_PASSWORD=password + +# Target Memgraph Database +MEMGRAPH_URL=bolt://localhost:7687 +MEMGRAPH_USERNAME= +MEMGRAPH_PASSWORD= +MEMGRAPH_DATABASE=memgraph + +# LLM API Keys (for AI-powered features) +# Only provide the key for your chosen provider +OPENAI_API_KEY=sk-... # For GPT models +# ANTHROPIC_API_KEY=sk-ant-... # For Claude models +# GOOGLE_API_KEY=AI... # For Gemini models + +# Optional: Specify LLM model (defaults shown) +# LLM_MODEL=gpt-4o-mini # OpenAI default +# LLM_MODEL=claude-3-5-sonnet-20241022 # Anthropic default +# LLM_MODEL=gemini-2.0-flash-exp # Google default + +# Migration Defaults (can be overridden via CLI flags) +SQL2MG_MODE=automatic # Options: automatic, incremental +SQL2MG_STRATEGY=deterministic # Options: deterministic, llm +SQL2MG_META_POLICY=auto # Options: auto, reset, skip +SQL2MG_LOG_LEVEL=INFO + +``` + +There is an .env.example file in the `agents/sql2graph` directory that you can use as a template. + +**Important**: Ensure Memgraph is started with `--schema-info-enabled=true` for full functionality. + +#### Quick Start - Automatic Migration + +Run with default settings (automatic mode, deterministic strategy): + +```bash +uv run main.py +``` + +The agent will: +1. Validate your environment and database connections +2. Analyze the source database schema +3. Generate a complete graph model +4. Execute the migration +5. Validate the results + +In this mode, no user interaction is required, and the entire process is automated. This means the `SQL2MG_MODE` is set to `automatic`, and the SQL2MG_STRATEGY is set to `deterministic`. +`SQL2MG_MODE` refers **modeling mode** and represents how much user interaction is involved, while `SQL2MG_STRATEGY` refers to how the graph model is generated. + + +#### Refinement with Incremental Mode + +For more control, run in incremental mode to review and refine the model step-by-step: + +```bash +uv run main.py --mode incremental +``` +The agent will: +1. Analyze the source database schema +2. Generate an initial graph model +3. Present each table's proposed transformation for review +4. Allow you to accept, skip, or modify each table's mapping +5. After reviewing all tables, optionally enter a refinement loop for final adjustments +6. Execute the migration +7. Validate the results + +This is predictable and repeatable flow so you can iteratively improve the graph model before migration. + + +#### Interactive Migration with LLM + +Use LLM-powered modeling for AI driven design: + +```bash +uv run main.py --strategy llm +``` + +The agent auto-detects which LLM provider to use based on available API keys. In this strategy, the agent will: +1. Analyze your SQL schema semantically using LLM +2. Generate an initial graph model with AI-optimized design +3. Execute the migration +4. Validate the results + +Keep in mind that in this mode, the entire migration is still automatic and LLM driven. + +#### Incremental Migration with Review + +Control each step of the transformation: + +```bash +uv run main.py --mode incremental --strategy llm +``` + +In incremental mode: +1. The AI generates a complete graph model for all tables +2. You review each table's mapping one at a time +3. Accept or modify individual table transformations +4. After processing all tables, optionally enter a refinement loop +5. Interactively adjust the entire model before final migration + + +## CLI Reference + +### Command-Line Options + +| Flag | Environment Variable | Description | Default | +|------|---------------------|-------------|---------| +| `--mode` | `SQL2MG_MODE` | `automatic` or `incremental` | interactive prompt | +| `--strategy` | `SQL2MG_STRATEGY` | `deterministic` or `llm` | interactive prompt | +| `--provider` | _(none)_ | `openai`, `anthropic`, or `gemini` | auto-detect from API keys | +| `--model` | `LLM_MODEL` | Specific model name | provider default | +| `--meta-graph` | `SQL2MG_META_POLICY` | `auto`, `skip`, or `reset` | `auto` | +| `--log-level` | `SQL2MG_LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` | + +### Usage Examples + +```bash +# Use specific Gemini model +uv run main.py --strategy llm --provider gemini --model gemini-2.0-flash-exp + +# Skip meta-graph comparison (treat as fresh migration) +uv run main.py --meta-graph skip + +# Enable debug logging +uv run main.py --log-level DEBUG + +# Fully configured non-interactive run +uv run main.py \ + --mode automatic \ + --strategy deterministic \ + --meta-graph reset \ + --log-level INFO +``` + +--- + +## LLM Provider Support + +### Provider Comparison + +| Provider | Models | +|----------|--------| +| **OpenAI** | GPT-4o, GPT-4o-mini | +| **Anthropic** | Claude 3.5 Sonnet | +| **Google** | Gemini 2.0 Flash | + +### Provider Selection + +The agent automatically selects a provider based on available API keys: +1. Checks for `OPENAI_API_KEY` +2. Falls back to `ANTHROPIC_API_KEY` +3. Falls back to `GOOGLE_API_KEY` + +Override with `--provider` flag: + +```bash +# Force Anthropic even if OpenAI key exists +uv run main.py --strategy llm --provider anthropic +``` + +### Model Selection + +Each provider has sensible defaults: +- **OpenAI**: `gpt-4o-mini` +- **Anthropic**: `claude-3-5-sonnet-20241022` +- **Google**: `gemini-2.0-flash-exp` + +Override with `--model` or `LLM_MODEL` env variable: + +```bash +# Use more powerful OpenAI model +uv run main.py --strategy llm --model gpt-4o + +# Or via environment variable +export LLM_MODEL=claude-3-opus-20240229 +uv run main.py --strategy llm --provider anthropic +``` + +--- + +## Interactive Features + +### Incremental Mode Workflow + +When you run with `--mode incremental`: + +1. **Initial Analysis**: Agent analyzes all tables and generates complete model +2. **Table-by-Table Review**: + - Shows proposed transformation for each table + - Displays nodes, relationships, and properties + - Options: Accept, Skip, or Modify +3. **Post-Processing Options**: + - Accept entire model as-is + - Enter refinement loop for adjustments + - Abort migration + +### Refinement Loop Operations + +In the interactive refinement loop, you can: + +#### View Current Model +``` +Current Graph Model: + Nodes: 12 + Relationships: 15 + Indexes: 18 + Constraints: 8 +``` + +#### Add Nodes +``` +Enter operation: add node Customer +Label: Customer +Properties: id (int), name (string), email (string) +``` + +#### Modify Properties +``` +Enter operation: make User.email required +Creating uniqueness constraint on User.email +``` + +#### Add Relationships +``` +Enter operation: add relationship PURCHASED from Customer to Product +Creating PURCHASED relationship with properties: + - purchased_at (timestamp) + - quantity (int) +``` + +#### Remove Elements +``` +Enter operation: remove index on User.created_at +Removed index: User.created_at +``` + +#### Natural Language Modifications +The AI interprets commands like: +- "Make email unique on Customer nodes" +- "Add an index on Product name and category" +- "Remove the metadata property from all nodes" +- "Change the OWNS relationship to HAS" + +--- + +## Advanced Features + +### Meta-Graph Storage + +The agent tracks graph model evolution using a meta-graph: + +**Storage Location**: Memgraph database as special nodes with label `__MetaGraph__` + +**Contents**: +- Previous node definitions +- Previous relationship definitions +- User-applied modifications +- Migration timestamps + +**Policies**: +- `auto` (default): Use meta-graph if available, skip if not +- `skip`: Ignore meta-graph, treat as fresh migration +- `reset`: Clear meta-graph, start from scratch + +### Change Detection + +In incremental mode with meta-graph enabled: +- Detects added tables +- Detects removed tables +- Detects column changes (type, nullability, new columns) +- Detects relationship changes +- Shows diff view for each changed table + +### Validation System + +**Pre-Migration Validation**: +- Node labels are valid +- Properties have valid types +- Relationships reference existing nodes +- Indexes target existing properties +- Constraints are consistent + +**Post-Migration Validation**: +- Expected node counts match +- Relationships connect correctly +- Indexes were created +- Constraints are enforced +- No data loss occurred + +**Validation Reports**: +``` +Validation Results: +✅ Schema: 45 checks passed +✅ Data: 12 tables verified +⚠️ Warnings: 2 + - Missing index on User.email (high selectivity) + - Large node degree on Product (>10k relationships) +❌ Errors: 0 +``` + +--- + +## Troubleshooting + +### Common Issues + +#### "API key must be set" +**Problem**: LLM provider API key not found +**Solution**: Set the appropriate environment variable: +```bash +export OPENAI_API_KEY=sk-... +# or +export ANTHROPIC_API_KEY=sk-ant-... +# or +export GOOGLE_API_KEY=AI... +``` + +#### "Connection refused" to Memgraph +**Problem**: Memgraph not running or wrong connection details +**Solution**: +```bash +# Start Memgraph with schema info enabled +docker run -p 7687:7687 memgraph/memgraph --schema-info-enabled=true + +``` + +## Architecture Overview + +If you like the implementation details, here is a high-level overview of the project structure: + +``` +sql2graph/ +├── main.py # CLI entry point +├── core/ +│ ├── migration_agent.py # Main orchestration +│ └── hygm/ # Graph modeling engine +│ ├── hygm.py # HyGM core +│ ├── models/ # Data models +│ ├── strategies/ # Modeling strategies +│ └── validation/ # Validation system +├── database/ +│ ├── analyzer.py # Schema analysis +│ ├── factory.py # Database adapter factory +│ └── adapters/ # DB-specific adapters +├── query_generation/ +│ ├── cypher_generator.py # Cypher query builder +│ └── schema_utilities.py # Schema helpers +└── utils/ + ├── environment.py # Env validation + └── config.py # Configuration +``` + + From 09e02d66afc5d46f4d21ff24f1fe0cbbe0948a37 Mon Sep 17 00:00:00 2001 From: antejavor Date: Mon, 27 Oct 2025 10:34:10 +0100 Subject: [PATCH 2/7] Delete examples. --- pages/ai-ecosystem/agents.mdx | 148 ---------------------------------- 1 file changed, 148 deletions(-) diff --git a/pages/ai-ecosystem/agents.mdx b/pages/ai-ecosystem/agents.mdx index c6273c574..cbbdfae25 100644 --- a/pages/ai-ecosystem/agents.mdx +++ b/pages/ai-ecosystem/agents.mdx @@ -221,7 +221,6 @@ uv run main.py \ --log-level INFO ``` ---- ## LLM Provider Support @@ -265,153 +264,6 @@ export LLM_MODEL=claude-3-opus-20240229 uv run main.py --strategy llm --provider anthropic ``` ---- - -## Interactive Features - -### Incremental Mode Workflow - -When you run with `--mode incremental`: - -1. **Initial Analysis**: Agent analyzes all tables and generates complete model -2. **Table-by-Table Review**: - - Shows proposed transformation for each table - - Displays nodes, relationships, and properties - - Options: Accept, Skip, or Modify -3. **Post-Processing Options**: - - Accept entire model as-is - - Enter refinement loop for adjustments - - Abort migration - -### Refinement Loop Operations - -In the interactive refinement loop, you can: - -#### View Current Model -``` -Current Graph Model: - Nodes: 12 - Relationships: 15 - Indexes: 18 - Constraints: 8 -``` - -#### Add Nodes -``` -Enter operation: add node Customer -Label: Customer -Properties: id (int), name (string), email (string) -``` - -#### Modify Properties -``` -Enter operation: make User.email required -Creating uniqueness constraint on User.email -``` - -#### Add Relationships -``` -Enter operation: add relationship PURCHASED from Customer to Product -Creating PURCHASED relationship with properties: - - purchased_at (timestamp) - - quantity (int) -``` - -#### Remove Elements -``` -Enter operation: remove index on User.created_at -Removed index: User.created_at -``` - -#### Natural Language Modifications -The AI interprets commands like: -- "Make email unique on Customer nodes" -- "Add an index on Product name and category" -- "Remove the metadata property from all nodes" -- "Change the OWNS relationship to HAS" - ---- - -## Advanced Features - -### Meta-Graph Storage - -The agent tracks graph model evolution using a meta-graph: - -**Storage Location**: Memgraph database as special nodes with label `__MetaGraph__` - -**Contents**: -- Previous node definitions -- Previous relationship definitions -- User-applied modifications -- Migration timestamps - -**Policies**: -- `auto` (default): Use meta-graph if available, skip if not -- `skip`: Ignore meta-graph, treat as fresh migration -- `reset`: Clear meta-graph, start from scratch - -### Change Detection - -In incremental mode with meta-graph enabled: -- Detects added tables -- Detects removed tables -- Detects column changes (type, nullability, new columns) -- Detects relationship changes -- Shows diff view for each changed table - -### Validation System - -**Pre-Migration Validation**: -- Node labels are valid -- Properties have valid types -- Relationships reference existing nodes -- Indexes target existing properties -- Constraints are consistent - -**Post-Migration Validation**: -- Expected node counts match -- Relationships connect correctly -- Indexes were created -- Constraints are enforced -- No data loss occurred - -**Validation Reports**: -``` -Validation Results: -✅ Schema: 45 checks passed -✅ Data: 12 tables verified -⚠️ Warnings: 2 - - Missing index on User.email (high selectivity) - - Large node degree on Product (>10k relationships) -❌ Errors: 0 -``` - ---- - -## Troubleshooting - -### Common Issues - -#### "API key must be set" -**Problem**: LLM provider API key not found -**Solution**: Set the appropriate environment variable: -```bash -export OPENAI_API_KEY=sk-... -# or -export ANTHROPIC_API_KEY=sk-ant-... -# or -export GOOGLE_API_KEY=AI... -``` - -#### "Connection refused" to Memgraph -**Problem**: Memgraph not running or wrong connection details -**Solution**: -```bash -# Start Memgraph with schema info enabled -docker run -p 7687:7687 memgraph/memgraph --schema-info-enabled=true - -``` ## Architecture Overview From bd6ec9def6584af968f0b1b541b10581828a68ca Mon Sep 17 00:00:00 2001 From: antejavor Date: Mon, 27 Oct 2025 18:05:51 +0100 Subject: [PATCH 3/7] Update wording. --- pages/ai-ecosystem/agents.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pages/ai-ecosystem/agents.mdx b/pages/ai-ecosystem/agents.mdx index cbbdfae25..fecc418ee 100644 --- a/pages/ai-ecosystem/agents.mdx +++ b/pages/ai-ecosystem/agents.mdx @@ -154,6 +154,8 @@ The agent will: 7. Validate the results This is predictable and repeatable flow so you can iteratively improve the graph model before migration. +Each table is processed one at a time, and you have full control over the transformations, the table will show you +all the proposed nodes, relationships, and properties for that table, and you can choose to accept them as-is, skip the table entirely, or modify the mapping details. #### Interactive Migration with LLM @@ -187,6 +189,8 @@ In incremental mode: 4. After processing all tables, optionally enter a refinement loop 5. Interactively adjust the entire model before final migration +In this mode the LLM is used to generate the initial model, but you have full control to review and refine each table's mapping before migration. +After each modification, the LLM will try to regenerate based on your feedback and validation errors to improve the model iteratively. ## CLI Reference From 5f4b4d3378cacc53e56d3b6f7023b57faac06303 Mon Sep 17 00:00:00 2001 From: antejavor Date: Mon, 27 Oct 2025 18:09:38 +0100 Subject: [PATCH 4/7] Update title. --- pages/ai-ecosystem/agents.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/ai-ecosystem/agents.mdx b/pages/ai-ecosystem/agents.mdx index fecc418ee..ac4f75ffe 100644 --- a/pages/ai-ecosystem/agents.mdx +++ b/pages/ai-ecosystem/agents.mdx @@ -1,6 +1,6 @@ --- title: Agents -description: Memgraph Agents: Here to help you out in building Graph AI applications. +description: Memgraph agents are build to help you build graph applications faster by leveraging the power of AI. --- import { Callout, Steps } from 'nextra/components' From 936c69fc9fd44339144d4a7f13dbb64257c9d77c Mon Sep 17 00:00:00 2001 From: antejavor Date: Tue, 28 Oct 2025 22:38:12 +0100 Subject: [PATCH 5/7] Update paragraphs. --- pages/ai-ecosystem/agents.mdx | 95 +++++++++++++++++++++++------------ 1 file changed, 64 insertions(+), 31 deletions(-) diff --git a/pages/ai-ecosystem/agents.mdx b/pages/ai-ecosystem/agents.mdx index ac4f75ffe..aa15cf5e9 100644 --- a/pages/ai-ecosystem/agents.mdx +++ b/pages/ai-ecosystem/agents.mdx @@ -7,50 +7,66 @@ import { Callout, Steps } from 'nextra/components' # Memgraph Agents -Memgraph Agents are specialized tools designed to streamline and enhance the development of Graph applications. These agents leverage Large Language Models (LLMs) to provide intelligent solutions for various graph-related tasks. By the nature of technology maturity, some agents may be experimental and are continuously evolving to better serve your needs. - -{

Available Agents

} +Memgraph Agents are specialized tools designed to streamline and enhance the +development of Graph applications. These agents leverage Large Language Models +(LLMs) to provide intelligent solutions for various graph-related tasks. By the +nature of technology maturity, some agents may be experimental and are +continuously evolving to better serve your needs. # SQL2Graph Agent ## Overview -The **SQL2Graph Agent** is an intelligent database migration agent that transforms relational databases (MySQL, PostgreSQL) into graph databases using AI-powered analysis. -It leverages Large Language Models (LLMs) to understand the semantics of your relational schema and generate an optimized property graph model for Memgraph. The -agent enables interactive modeling and refinement of the graph schema, validation after the migration. +The **SQL2Graph Agent** is an intelligent database migration agent that +transforms relational databases (MySQL, PostgreSQL) into graph databases using +AI-powered analysis. It leverages Large Language Models (LLMs) to understand the +semantics of your relational schema and generate an optimized property graph +model for Memgraph. The agent enables interactive modeling and refinement of the +graph schema, validation after the migration. **Key Capabilities:** -1. **Automatic Database Migration**: Performs end-to-end migration from SQL to graph with minimal user input. -2. **Interactive graph modeling**: Enables users to review and refine the generated graph model incrementally, before executing the migration. -3. **Validation**: Provides pre- and post-migration validation to communicate the quality and correctness of the migration. +1. **Automatic Database Migration**: Performs end-to-end migration from SQL to + graph with minimal user input. +2. **Interactive graph modeling**: Enables users to review and refine the + generated graph model incrementally, before executing the migration. +3. **Validation**: Provides pre- and post-migration validation to communicate + the quality and correctness of the migration. The Agent supports two main **modeling strategies**: -1. **Deterministic Strategy**: Rule-based mapping of tables to nodes and foreign keys to relationships. -2. **LLM Strategy**: AI-powered analysis using LLMs to generate a semantically rich graph model. +1. **Deterministic Strategy**: Rule-based mapping of tables to nodes and foreign + keys to relationships. +2. **LLM Strategy**: AI-powered analysis using LLMs to generate a semantically + rich graph model. The agent can also be run in two **modes**: 1. **Automatic Mode**: Fully automated migration without user interaction. -2. **Incremental Mode**: Step-by-step review and refinement of the graph model before migration. +2. **Incremental Mode**: Step-by-step review and refinement of the graph model + before migration. These are controlled via CLI flags and environment variables. ## How To Use The Agent -From this point onward, it is assumed that you have Memgraph installed and running. If you haven't done so, please refer to the [Memgraph installation guide](https://memgraph.com/docs/memgraph/installation). +From this point onward, it is assumed that you have Memgraph installed and +running. If you haven't done so, please refer to the [Memgraph installation +guide](https://memgraph.com/docs/memgraph/installation). -Just make sure to start Memgraph with the `--schema-info-enabled=true` flag to enable schema information tracking: +Just make sure to start Memgraph with the `--schema-info-enabled=true` flag to +enable schema information tracking: ```bash docker run -p 7687:7687 memgraph/memgraph --schema-info-enabled ``` -It is also assumed that you have a running instance of either PostgreSQL or MySQL with a sample database to migrate. +It is also assumed that you have a running instance of either PostgreSQL or +MySQL with a sample database to migrate. ### Installation -In order to use you first need to clone the repository and install the dependencies: +In order to use you first need to clone the repository and install the +dependencies: ```bash @@ -66,7 +82,10 @@ uv pip install -e . ### Configuration -The configuration enables you to control the agent flow via environment variables. The key information needed are the source database connection details, target Memgraph connection details, and LLM API keys and agent configuration. +The configuration enables you to control the agent flow via environment +variables. The key information needed are the source database connection +details, target Memgraph connection details, and LLM API keys and agent +configuration. Create a `.env` and fill the following variables: @@ -114,9 +133,11 @@ SQL2MG_LOG_LEVEL=INFO ``` -There is an .env.example file in the `agents/sql2graph` directory that you can use as a template. +There is an .env.example file in the `agents/sql2graph` directory that you can +use as a template. -**Important**: Ensure Memgraph is started with `--schema-info-enabled=true` for full functionality. +**Important**: Ensure Memgraph is started with `--schema-info-enabled=true` for +full functionality. #### Quick Start - Automatic Migration @@ -133,13 +154,17 @@ The agent will: 4. Execute the migration 5. Validate the results -In this mode, no user interaction is required, and the entire process is automated. This means the `SQL2MG_MODE` is set to `automatic`, and the SQL2MG_STRATEGY is set to `deterministic`. -`SQL2MG_MODE` refers **modeling mode** and represents how much user interaction is involved, while `SQL2MG_STRATEGY` refers to how the graph model is generated. +In this mode, no user interaction is required, and the entire process is +automated. This means the `SQL2MG_MODE` is set to `automatic`, and the +SQL2MG_STRATEGY is set to `deterministic`. `SQL2MG_MODE` refers **modeling +mode** and represents how much user interaction is involved, while +`SQL2MG_STRATEGY` refers to how the graph model is generated. #### Refinement with Incremental Mode -For more control, run in incremental mode to review and refine the model step-by-step: +For more control, run in incremental mode to review and refine the model +step-by-step: ```bash uv run main.py --mode incremental @@ -149,13 +174,16 @@ The agent will: 2. Generate an initial graph model 3. Present each table's proposed transformation for review 4. Allow you to accept, skip, or modify each table's mapping -5. After reviewing all tables, optionally enter a refinement loop for final adjustments +5. After reviewing all tables, optionally enter a refinement loop for final + adjustments 6. Execute the migration 7. Validate the results -This is predictable and repeatable flow so you can iteratively improve the graph model before migration. -Each table is processed one at a time, and you have full control over the transformations, the table will show you -all the proposed nodes, relationships, and properties for that table, and you can choose to accept them as-is, skip the table entirely, or modify the mapping details. +This is predictable and repeatable flow so you can iteratively improve the graph +model before migration. Each table is processed one at a time, and you have full +control over the transformations, the table will show you all the proposed +nodes, relationships, and properties for that table, and you can choose to +accept them as-is, skip the table entirely, or modify the mapping details. #### Interactive Migration with LLM @@ -166,13 +194,15 @@ Use LLM-powered modeling for AI driven design: uv run main.py --strategy llm ``` -The agent auto-detects which LLM provider to use based on available API keys. In this strategy, the agent will: +The agent auto-detects which LLM provider to use based on available API keys. In +this strategy, the agent will: 1. Analyze your SQL schema semantically using LLM 2. Generate an initial graph model with AI-optimized design 3. Execute the migration 4. Validate the results -Keep in mind that in this mode, the entire migration is still automatic and LLM driven. +Keep in mind that in this mode, the entire migration is still automatic and LLM +driven. #### Incremental Migration with Review @@ -189,8 +219,10 @@ In incremental mode: 4. After processing all tables, optionally enter a refinement loop 5. Interactively adjust the entire model before final migration -In this mode the LLM is used to generate the initial model, but you have full control to review and refine each table's mapping before migration. -After each modification, the LLM will try to regenerate based on your feedback and validation errors to improve the model iteratively. +In this mode the LLM is used to generate the initial model, but you have full +control to review and refine each table's mapping before migration. After each +modification, the LLM will try to regenerate based on your feedback and +validation errors to improve the model iteratively. ## CLI Reference @@ -271,7 +303,8 @@ uv run main.py --strategy llm --provider anthropic ## Architecture Overview -If you like the implementation details, here is a high-level overview of the project structure: +If you like the implementation details, here is a high-level overview of the +project structure: ``` sql2graph/ From 1f4acb7bd7b36aff37f9ab9843be547a11616f20 Mon Sep 17 00:00:00 2001 From: antejavor Date: Tue, 28 Oct 2025 22:55:19 +0100 Subject: [PATCH 6/7] Update pages with paragraphs. --- pages/ai-ecosystem.mdx | 2 ++ pages/ai-ecosystem/agents.mdx | 7 +++++-- pages/data-migration.mdx | 6 ++++++ pages/data-migration/migrate-from-rdbms.mdx | 6 ++++++ pages/data-modeling.mdx | 7 +++++++ 5 files changed, 26 insertions(+), 2 deletions(-) diff --git a/pages/ai-ecosystem.mdx b/pages/ai-ecosystem.mdx index 7b8617395..34b5952fe 100644 --- a/pages/ai-ecosystem.mdx +++ b/pages/ai-ecosystem.mdx @@ -30,6 +30,8 @@ This section of Memgraph’s documentation is your guide to using Memgraph for A - [GraphChat in Memgraph Lab](/memgraph-lab/features/graphchat): Explore how natural language querying (GraphChat) ties into the GraphRAG ecosystem, making complex graphs accessible to everyone. +- [Agents in Memgraph](/ai-ecosystem/agents): Discover how you can leverage AI + agents to automate graph modeling and migration tasks. \ No newline at end of file diff --git a/pages/ai-ecosystem/agents.mdx b/pages/ai-ecosystem/agents.mdx index aa15cf5e9..24e48998f 100644 --- a/pages/ai-ecosystem/agents.mdx +++ b/pages/ai-ecosystem/agents.mdx @@ -47,6 +47,11 @@ The agent can also be run in two **modes**: These are controlled via CLI flags and environment variables. +## Supported Databases + +- **Source Databases**: PostgreSQL, MySQL +- **Target Database**: Memgraph + ## How To Use The Agent From this point onward, it is assumed that you have Memgraph installed and @@ -260,8 +265,6 @@ uv run main.py \ ## LLM Provider Support -### Provider Comparison - | Provider | Models | |----------|--------| | **OpenAI** | GPT-4o, GPT-4o-mini | diff --git a/pages/data-migration.mdx b/pages/data-migration.mdx index c3478a1b4..addda931a 100644 --- a/pages/data-migration.mdx +++ b/pages/data-migration.mdx @@ -29,6 +29,12 @@ In order to learn all the pre-requisites for importing data into Memgraph, check + +If you have a SQL data model and +want to migrate to Memgraph, you can try out our [Agent](/ai-ecosystem/agents) +that leverages the LLM to automate the process of modeling and migration. + + ## File types ### CSV files diff --git a/pages/data-migration/migrate-from-rdbms.mdx b/pages/data-migration/migrate-from-rdbms.mdx index 960e64abf..d7993b93f 100644 --- a/pages/data-migration/migrate-from-rdbms.mdx +++ b/pages/data-migration/migrate-from-rdbms.mdx @@ -32,6 +32,12 @@ highly connected and require frequent retrieval with a flexible data model. If you're seeking a quick and reliable database that allows effortless modifications of data model and properties, a graph database is the way to go. + +If you have a SQL data model and +want to migrate to Memgraph, you can try out our [Agent](/ai-ecosystem/agents) +that leverages the LLM to automate the process of modeling and migration. It supports + + ## Prerequisites To follow along, you will need: diff --git a/pages/data-modeling.mdx b/pages/data-modeling.mdx index 0f11ee65a..bc76b9f50 100644 --- a/pages/data-modeling.mdx +++ b/pages/data-modeling.mdx @@ -5,6 +5,7 @@ description: Learn to model graphs effectively with Memgraph. A documentation de import { Cards } from 'nextra/components' import {CommunityLinks} from '/components/social-card/CommunityLinks' +import { Callout } from 'nextra/components' # Introduction to graph data modeling @@ -60,6 +61,12 @@ data in Memgraph. as overcomplicating models, duplicating data, and neglecting indexing, and explains how to avoid them. + + If you have a SQL data model and + want to migrate to Memgraph, you can try out our [Agent](/ai-ecosystem/agents) + that leverages the LLM to automate the process of modeling and migration. + + ## Need help with data modeling? Schedule a 30 min session with one of our engineers to discuss how Memgraph fits From eb7f95ea855795dbdc1870c536539a0bc585959a Mon Sep 17 00:00:00 2001 From: matea16 Date: Wed, 29 Oct 2025 14:21:03 +0100 Subject: [PATCH 7/7] update structure --- pages/ai-ecosystem/_meta.ts | 1 + pages/ai-ecosystem/agents.mdx | 97 ++++++++++--------- .../migrate-from-rdbms-directly.md | 29 ++++-- pages/data-migration/migrate-from-rdbms.mdx | 2 +- 4 files changed, 72 insertions(+), 57 deletions(-) diff --git a/pages/ai-ecosystem/_meta.ts b/pages/ai-ecosystem/_meta.ts index 42cc7b357..f78460d14 100644 --- a/pages/ai-ecosystem/_meta.ts +++ b/pages/ai-ecosystem/_meta.ts @@ -2,4 +2,5 @@ export default { "graph-rag": "GraphRAG", "integrations": "Integrations", "machine-learning": "Machine learning", + "agents": "Agents" } \ No newline at end of file diff --git a/pages/ai-ecosystem/agents.mdx b/pages/ai-ecosystem/agents.mdx index 24e48998f..733d4dd15 100644 --- a/pages/ai-ecosystem/agents.mdx +++ b/pages/ai-ecosystem/agents.mdx @@ -3,68 +3,76 @@ title: Agents description: Memgraph agents are build to help you build graph applications faster by leveraging the power of AI. --- import { Callout, Steps } from 'nextra/components' - +import {CommunityLinks} from '/components/social-card/CommunityLinks' # Memgraph Agents -Memgraph Agents are specialized tools designed to streamline and enhance the -development of Graph applications. These agents leverage Large Language Models -(LLMs) to provide intelligent solutions for various graph-related tasks. By the +**Memgraph Agents** are specialized tools designed to streamline and enhance the +development of Graph applications. These agents leverage **Large Language Models +(LLMs)** to provide intelligent solutions for various graph-related tasks. By the nature of technology maturity, some agents may be experimental and are continuously evolving to better serve your needs. -# SQL2Graph Agent - -## Overview +## SQL2Graph Agent The **SQL2Graph Agent** is an intelligent database migration agent that -transforms relational databases (MySQL, PostgreSQL) into graph databases using -AI-powered analysis. It leverages Large Language Models (LLMs) to understand the +transforms **relational databases** (MySQL, PostgreSQL) into **graph databases** using +AI-powered analysis.
+It leverages Large Language Models (LLMs) to understand the semantics of your relational schema and generate an optimized property graph -model for Memgraph. The agent enables interactive modeling and refinement of the +model for Memgraph.
+The agent enables interactive modeling and refinement of the graph schema, validation after the migration. -**Key Capabilities:** +

Key capabilities

-1. **Automatic Database Migration**: Performs end-to-end migration from SQL to +- **Automatic database migration**: Performs end-to-end migration from SQL to graph with minimal user input. -2. **Interactive graph modeling**: Enables users to review and refine the +- **Interactive graph modeling**: Enables users to review and refine the generated graph model incrementally, before executing the migration. -3. **Validation**: Provides pre- and post-migration validation to communicate +- **Validation**: Provides pre- and post-migration validation to communicate the quality and correctness of the migration. +**Modeling strategies** -The Agent supports two main **modeling strategies**: -1. **Deterministic Strategy**: Rule-based mapping of tables to nodes and foreign +1. **Deterministic strategy**: Rule-based mapping of tables to nodes and foreign keys to relationships. -2. **LLM Strategy**: AI-powered analysis using LLMs to generate a semantically +2. **LLM strategy**: AI-powered analysis using LLMs to generate a semantically rich graph model. -The agent can also be run in two **modes**: -1. **Automatic Mode**: Fully automated migration without user interaction. -2. **Incremental Mode**: Step-by-step review and refinement of the graph model +**Operation modes** + +1. **Automatic mode**: Fully automated migration without user interaction. +2. **Incremental mode**: Step-by-step review and refinement of the graph model before migration. These are controlled via CLI flags and environment variables. -## Supported Databases +### Supported databases -- **Source Databases**: PostgreSQL, MySQL -- **Target Database**: Memgraph +| Type | Supported options | +|------|-------------------| +| **Source databases** | PostgreSQL, MySQL | +| **Target database** | Memgraph | -## How To Use The Agent + +### How to use the Agent From this point onward, it is assumed that you have Memgraph installed and running. If you haven't done so, please refer to the [Memgraph installation -guide](https://memgraph.com/docs/memgraph/installation). +guide](/memgraph/installation). -Just make sure to start Memgraph with the `--schema-info-enabled=true` flag to -enable schema information tracking: +Start Memgraph with schema tracking enabled: ```bash docker run -p 7687:7687 memgraph/memgraph --schema-info-enabled ``` + +**Important**: Memgraph must be started with `--schema-info-enabled=true` for +full functionality. + + It is also assumed that you have a running instance of either PostgreSQL or MySQL with a sample database to migrate. @@ -137,14 +145,10 @@ SQL2MG_META_POLICY=auto # Options: auto, reset, skip SQL2MG_LOG_LEVEL=INFO ``` +> 💡 **Tip:** Use `.env.example` in `agents/sql2graph` as a template. -There is an .env.example file in the `agents/sql2graph` directory that you can -use as a template. - -**Important**: Ensure Memgraph is started with `--schema-info-enabled=true` for -full functionality. -#### Quick Start - Automatic Migration +#### Quick start - automatic migration Run with default settings (automatic mode, deterministic strategy): @@ -159,14 +163,14 @@ The agent will: 4. Execute the migration 5. Validate the results -In this mode, no user interaction is required, and the entire process is -automated. This means the `SQL2MG_MODE` is set to `automatic`, and the +In **automatic mode**, no user interaction is required, and the entire process +is automated. This means the `SQL2MG_MODE` is set to `automatic`, and the SQL2MG_STRATEGY is set to `deterministic`. `SQL2MG_MODE` refers **modeling mode** and represents how much user interaction is involved, while `SQL2MG_STRATEGY` refers to how the graph model is generated. -#### Refinement with Incremental Mode +#### Refinement with incremental mode For more control, run in incremental mode to review and refine the model step-by-step: @@ -174,6 +178,7 @@ step-by-step: ```bash uv run main.py --mode incremental ``` + The agent will: 1. Analyze the source database schema 2. Generate an initial graph model @@ -191,7 +196,7 @@ nodes, relationships, and properties for that table, and you can choose to accept them as-is, skip the table entirely, or modify the mapping details. -#### Interactive Migration with LLM +#### Interactive migration with LLM Use LLM-powered modeling for AI driven design: @@ -209,7 +214,7 @@ this strategy, the agent will: Keep in mind that in this mode, the entire migration is still automatic and LLM driven. -#### Incremental Migration with Review +#### Incremental migration with review Control each step of the transformation: @@ -229,9 +234,9 @@ control to review and refine each table's mapping before migration. After each modification, the LLM will try to regenerate based on your feedback and validation errors to improve the model iteratively. -## CLI Reference +### CLI reference -### Command-Line Options +#### Command-line options | Flag | Environment Variable | Description | Default | |------|---------------------|-------------|---------| @@ -242,7 +247,7 @@ validation errors to improve the model iteratively. | `--meta-graph` | `SQL2MG_META_POLICY` | `auto`, `skip`, or `reset` | `auto` | | `--log-level` | `SQL2MG_LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` | -### Usage Examples +#### Usage examples ```bash # Use specific Gemini model @@ -263,7 +268,7 @@ uv run main.py \ ``` -## LLM Provider Support +### LLM provider support | Provider | Models | |----------|--------| @@ -271,7 +276,7 @@ uv run main.py \ | **Anthropic** | Claude 3.5 Sonnet | | **Google** | Gemini 2.0 Flash | -### Provider Selection +#### Provider selection The agent automatically selects a provider based on available API keys: 1. Checks for `OPENAI_API_KEY` @@ -285,7 +290,7 @@ Override with `--provider` flag: uv run main.py --strategy llm --provider anthropic ``` -### Model Selection +#### Model selection Each provider has sensible defaults: - **OpenAI**: `gpt-4o-mini` @@ -304,7 +309,7 @@ uv run main.py --strategy llm --provider anthropic ``` -## Architecture Overview +### Architecture overview If you like the implementation details, here is a high-level overview of the project structure: @@ -331,4 +336,4 @@ sql2graph/ └── config.py # Configuration ``` - + diff --git a/pages/data-migration/migrate-from-rdbms-directly.md b/pages/data-migration/migrate-from-rdbms-directly.md index d5759ddcb..3e410d0ab 100644 --- a/pages/data-migration/migrate-from-rdbms-directly.md +++ b/pages/data-migration/migrate-from-rdbms-directly.md @@ -5,22 +5,31 @@ description: Easily transition from RDBMS to Memgraph using MAGE modules. Our de # Migrate from RDBMS to Memgraph using MAGE modules -This tutorial will help you import your data from a PostgreSQL database into Memgraph -directly using the Memgraph MAGE [`migrate`](/advanced-algorithms/available-algorithms/migrate) module. -The migrate module contains a comprehensive list of data sources from which you're able to migrate your data -to Memgraph in one step. - -This migration tutorial makes migration from an external source to Memgraph possible in one less step -than described in [migrating from a RDBMS to Memgraph using CSV files](/data-migration/migrate-from-rdbms). -The need for migrating directly from the source system arises from the fact that users so far needed to convert the -data from the source system to CSV files in order to migrate to Memgraph. -Make sure you read both tutorials to see what fits your needs. +This tutorial will help you import your data from a PostgreSQL database into +Memgraph directly using the Memgraph MAGE +[`migrate`](/advanced-algorithms/available-algorithms/migrate) module. The +migrate module contains a comprehensive list of data sources from which you're +able to migrate your data to Memgraph in one step. + +This migration tutorial makes migration from an external source to Memgraph +possible in one less step than described in [migrating from a RDBMS to Memgraph +using CSV files](/data-migration/migrate-from-rdbms). The need for migrating +directly from the source system arises from the fact that users so far needed to +convert the data from the source system to CSV files in order to migrate to +Memgraph. Make sure you read both tutorials to see what fits your needs. In two of our blog posts, we've covered the [differences between relational and graph database](https://memgraph.com/blog/graph-database-vs-relational-database) and outlined the [benefits of graph databases](https://memgraph.com/blog/the-benefits-of-using-a-graph-database-instead-of-sql). + + +If you have a SQL data model and +want to migrate to Memgraph, you can try out our [Agent](/ai-ecosystem/agents) +that leverages the LLM to automate the process of modeling and migration. + + ## Prerequisites To follow along, you will need: diff --git a/pages/data-migration/migrate-from-rdbms.mdx b/pages/data-migration/migrate-from-rdbms.mdx index d7993b93f..4b618638d 100644 --- a/pages/data-migration/migrate-from-rdbms.mdx +++ b/pages/data-migration/migrate-from-rdbms.mdx @@ -35,7 +35,7 @@ modifications of data model and properties, a graph database is the way to go. If you have a SQL data model and want to migrate to Memgraph, you can try out our [Agent](/ai-ecosystem/agents) -that leverages the LLM to automate the process of modeling and migration. It supports +that leverages the LLM to automate the process of modeling and migration. ## Prerequisites