Neo4j documentation states, “Neo4j is a native graph database.”

So, Neo4j is definitely two things-

1. Graph model-based
2. Database

Neo4j is a native graph database. It stores and represents data in graph format through nodes and relationships (aka links). The relationships have directions and mark source & destination nodes. These nodes and relationships have one or more properties associated with them. Neo4j also has most of the capabilities of a traditional database. You can define constraints & indexes, execute transactions, run subqueries, etc.

Neo4j is available in several forms. Its cloud-based solution is available under the name Neo4j Aura. It is also available as a graph database on all major cloud service providers. It is also available on Docker and Kubernetes, and has plugins for most of the major programming languages, including Python, JS, Java, Go, etc.

Read more about Neo4j Solutions

In this story, you will read about Data Model- Creating a Data Model and Data Source- Importing a Data Source.

Data Model

A data model defines the schema for the database to support the queries and structure of stored data. A good model will help gather all required fields and return query responses with the least data traversal. One must understand the domain and specific use case requirements to create a well-designed data model.

Read more about Neo4j Data Modeling

Creating a Data Model

There are several ways to create a data model. When using the Neo4j Aura cloud solution, the Import option offers the easiest, hassle-free way to create a model.

Although there are several other efficient ways to create a model and import data, when creating the model manually, one can better understand the features, constraints, and nuances of the Neo4j platform.

Follow the steps below to create a Customer — Product data model from scratch. A rough sketch of the model is shown below-

(:Customer)-[:PLACED]->(:Order)-[:CONTAINS]->(:Product)-[:BELONGS_TO]->(:Category)
       │                                     ▲
       └──────────────[:REVIEWED]────────────┘

Node Labels and their Properties

• Customer: customerId (ID), name, email, joinedDate
• Order: orderId (ID), orderDate, status, paymentMethod
• Product: productId (ID), name, price, sku
• Category: categoryId (ID), name

Relationships and their Properties

• (:Customer)-[:PLACED]->(:Order)
• (:Order)-[:CONTAINS {quantity: Integer, unitPrice: Float}]->(:Product)
• (:Product)-[:BELONGS_TO]->(:Category)
• (:Customer)-[:REVIEWED {rating: Integer, comment: String, reviewDate: Datetime}]->(:Product)

1. Create a new Import Model

Go to the Import Models tab and click on the Create Import Model button at the center of the screen. A pop-up box will open.

Provide a name (ex: Customer) and description for your model. Then click on the Create button.

2. Define Model Manually

In the next step, you’ll get the option to define the source of data for your model. The data source could either be a database (like MySQL, AWS Redshift) or CSV/TSV files. Based on the data, you can ask Neo4j to infer the model structure.

However, you can create the model manually as well by defining each graph element yourself (nodes, relationships, properties, constraints, etc.). Click on the Define Manually card at the center of the screen.

3. Create Node Labels

In the next screen, you’ll get an interactive playground where you can create nodes, relationships, etc.

Start by adding labels to the blank node visible on screen and defining label properties in the right sidebar. (Labels can be considered as node types or tags. Each node can belong to multiple labels.)

Also, there is a toolbar at the bottom of the screen that can be used to add more node labels/relationships in the model.

Create the following node labels-

• Customer
• Order
• Product
• Category

4. Add Node Label Properties

To add Properties to a label, select the label. Then, on the right sidebar, click on the add icon ‘+’ next to the Properties and give a suitable name & datatype to the property. You can add any number of properties in the same manner. From the Constraints tab, you can configure constraints for these properties.

Now, add all required properties for all the node labels. Also set a suitable property as the ID (or Primary Key) for each label (ex: customerId can be the ID for the Customer Label). You can set a single or combination of properties as the ID.

5. Create Relationships

To create a relationship, select the starting node. A thick border appears around it. Press on this border, then drag and drop over the destination node. A relationship will be created between these two nodes.

If required, relationship direction can be changed by clicking the Reverse Direction button in the bottom toolbar. Relationship Type can be added from the right sidebar.

Create the following relationships-

• PLACED
• CONTAINS
• BELONGS_TO
• REVIEWED

6. Add Relationship Properties

Add properties for the relationships (required for CONTAINS and REVIEWED relationships). You can follow the same steps as for adding properties to node labels.

Node ID mapping will be completed later once the data source is added.

With that, you successfully created a Customer-Product data model.

Data Source

The data model lays out the schema for your database. But a database without data is still nothing. To populate data in a Neo4j DB instance, you have several options. You can upload CSV/TSV files or connect with MySQL, PostgreSQL, AWS Redshift, AWS S3, etc., to load your data.

Read more about Neo4j Data Sources

Import Data Source

After creating the data model, in the next step you need to add a data source to this model. Neo4j supports several data source types, but here you will load sample data from CSV files.

Download all the files from this GitHub link and store them on your local system. The .json file contains the data model schema, and the .csv files contain sample data for node labels and relationships.

1. Upload Data Source Files

Click Browse on the left sidebar in the CSV/TSV box. Select all required .csv files.

Once uploaded, the CSV files and their details will be displayed on the left side.

2. Map Node Label Properties with Data Source Columns

Select a node label. In the Properties tab on the right sidebar, you need to select the data source (table) and map the properties to the appropriate table columns.

Perform this step for all the properties of all the node labels.

3. Map Relationship Properties with Data Source Columns

You need to perform a similar step for relationship properties as well. Map all relationship properties with their respective columns from data source tables.

Also, you need to complete Node ID mapping. This mapping helps the relationship to identify the source and destination nodes by their respective IDs. Map the columns in the relationship data source with the respective From & To Node ID properties.

4. Run Import

Once all the Labels & Relationships, their properties & IDs are defined, you are ready to import the model and sample data into your database instance.

Click on the Run Import button in the top right corner. A pop-up box will open; select your instance in which you want to load the model and source data. Then click on the Run Import button.

Thus, your data model with some sample data gets successfully created and deployed in your database instance. Your database is now ready to store and query data.

Query and Visualization

A database system is never used only to store data. Querying this data is another crucial purpose of a database. Neo4j has plugins available in several programming languages that you can integrate with your application to manage your database.

Neo4j supports queries in the Cypher language. Cypher is a declarative query language. It is close to natural language and visually matches the patterns and relationships in its syntax. Example-

MATCH (n: From_Node_Label)-[r:RELATIONSHIP]->(m:To_Node_Label)
RETURN n, r, m

Read more about Cypher

Run Query

To query and visualize your data, you can use the Query option from the left sidebar. In the typing area, write a Cypher query and click on the Run button.

The query response will generally be returned in multiple formats. The graph format is a representation of the response in the form of nodes and relationships. You can click on graph elements to view their properties and interact with them. Besides this, the response is also returned in table and raw formats.

Cypher query used above-

MATCH (c:Customer)-[r]->(p)
RETURN c, r, p

The query returns all the Customer nodes, their immediate relationships, and the linked nodes.

You can integrate the database instance with your application and perform complex queries through plugins and api calls.

Read more about Neo4j

Read more about Graph Database

Neo4j: Data Model & Data Source was originally published in The Pythoneers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Why every Python developer needs a preflight check for their code

I used to have a recurring nightmare. I’d be halfway through a machine learning experiment, three hours into training, when suddenly everything would explode. Not because my code was wrong, but because my environment was quietly broken in a way I couldn’t see coming. Wrong Python version. A package that got installed with pip instead of conda. A wheel that claimed to support my architecture but didn’t. Rosetta 2 running my arm64 Python as x86_64 and tanking my GPU acceleration.

The error messages were always cryptic. The fixes were always tedious. And the worst part? I never knew if my environment was actually healthy until something went wrong.

So I built [EnvGuard]—a CLI tool that validates your Python environment before you run your code, not after it breaks. Think of it as a preflight checklist for your Python projects. If something’s wrong, it blocks execution and tells you exactly what’s broken and how to fix it. If everything passes, your command runs in a validated environment.

It’s macOS-first (because that’s where I do my work), runs on Linux with partial support, and deliberately doesn’t support Windows (because life’s too short for three-platform maintenance). You can install it from [PyPI] as `envguard-tool` — the CLI command is just `envguard`.

The Problem: Python Environments Are Fragile and Invisible

Python environment management is a solved problem in the same way that herding cats is a solved problem. Technically there are tools. Practically, things go wrong constantly.

Here’s what actually happens in the wild:

The architecture confusion. You install Python on an M1 Mac, but somehow you’re running the x86_64 version under Rosetta 2. Everything works, but your Metal Performance Shaders (MPS) acceleration is silently disabled. PyTorch falls back to CPU. Your training takes 10x longer. You don’t notice until you check `activity monitor` and see no GPU usage.

The mixed ownership trap. You create a conda environment, but then you pip install something because the conda version is outdated. Then you conda install something else. Now you have packages owned by two different managers, and `pip check` is screaming about conflicts, but your code still runs so you ignore it until it doesn’t.

The CUDA delusion. You’re on macOS, but your `requirements.txt` includes `torch==2.0.0+cu118` because you copied it from a Linux server. It installs fine. It even imports. But CUDA doesn’t exist on Apple Silicon, and your code fails three layers deep in a stack trace that mentions nothing about GPU compatibility.

The “it worked yesterday” mystery. Your environment was fine. Then you updated one package. Now something else is broken. You have no idea what changed or when.

These aren’t exotic edge cases. They’re daily experiences for Python developers working on ML, data science, or scientific computing projects. The existing tools — conda, pip, poetry, uv, pyenv — are great at creating environments. They’re terrible at validating them continuously.

The Solution: Preflight Validation Every Single Time

EnvGuard’s core idea is simple: instead of running `python train.py` and hoping, you run `envguard run — python train.py`. Before your code executes, EnvGuard runs a nine-step preflight pipeline:

1. Detect the host — OS version, architecture (native arm64 vs Intel vs Rosetta 2), available package managers, network connectivity
2. Discover the project — scan for `pyproject.toml`, `requirements.txt`, `environment.yml`, `Pipfile`, `poetry.lock`, etc.
3. Analyze intent — figure out what environment type (venv/conda/pipenv/poetry), Python version, and accelerator targets (CPU/MPS/CUDA) the project needs
4. Evaluate rules — run 15+ validation rules to catch problems
5. Fail-fast on critical issues — block execution if anything is unrecoverable
6. Create a resolution plan — determine exactly how to satisfy the environment requirements
7. Create or repair the environment— make sure the actual environment matches the requirements
8. Validate the environment — run `pip check` or equivalent to verify consistency
9. Smoke test— try importing key packages in an isolated subprocess to catch runtime failures

If any step fails with a `CRITICAL` finding, your command never runs. You get a clear error message explaining what went wrong and how to fix it. No cryptic tracebacks. No debugging environment issues at 2am.

What EnvGuard Actually Catches

The rules engine evaluates 15+ specific checks. Here are the ones that have saved me the most pain:

| Rule                          | Severity  | What it catches                                                                 |
|-------------------------------|-----------|----------------------------------------------------------------------------------|
| `CUDA_ON_MACOS`               | **CRITICAL** | Any CUDA dependency on macOS (hardware impossibility)                           |
| `ROSETTA_TRANSLATION_DETECTED`| WARNING   | x86_64 Python running under Rosetta 2 on Apple Silicon (kills MPS performance)  |
| `ARCHITECTURE_MISMATCH`       | ERROR     | Python architecture doesn't match project requirements                          |
| `MIXED_PIP_CONDA_OWNERSHIP`   | WARNING   | Packages installed by both pip and conda (dependency hell indicator)            |
| `WHEEL_INCOMPATIBLE`          | WARNING   | Wheel file doesn't match current platform/architecture                          |
| `BROKEN_ENVIRONMENT`          | ERROR     | Active venv/conda is missing Python binary or critical files                    |
| `PYTHON_VERSION_BELOW_MINIMUM`| ERROR     | Python version below `requires-python` in pyproject.toml                        |
| `MPS_NOT_AVAILABLE`           | INFO      | Apple Silicon present but MPS not available (usually means PyTorch wasn't built with MPS support) |

The `CUDA_ON_MACOS` rule alone has probably saved me hours of debugging. Here’s what happens: you copy a `requirements.txt` from a Linux machine that specifies `torch==2.1.0+cu118`. You install it on your M1 Mac. It seems to work — pip doesn’t complain, the import succeeds. But when you actually try to move tensors to the GPU, you get a cryptic error about CUDA devices not being available. EnvGuard catches this at the dependency resolution stage and blocks execution with a message telling you to use `mps` or `cpu` targets instead.

The `ROSETTA_TRANSLATION_DETECTED` rule is subtler but equally important. If you’re running an x86_64 Python binary on an Apple Silicon Mac (usually because you installed it before Rosetta was properly configured, or you’re using an old pyenv), everything works — but MPS acceleration is silently disabled. Your ML training runs on CPU. Your inference is 10x slower than it should be. EnvGuard detects this via `sysctl proc_translated` and warns you that you’re leaving performance on the table.

The Technical Architecture: How It Actually Works

EnvGuard is built as a layered Python package with clear separation of concerns. The source is in [the GitHub repo](https://github.com/rotsl/envguard) under `src/envguard/`.

CLI Layer (`cli.py`): Typer-based interface with 25 commands across environment management, dependency resolution, lock files, publishing, and self-updating. Every command supports ` — json` output for CI/CD integration.

Orchestration Layer (`preflight.py`, `doctor.py`): The preflight engine runs the nine-step pipeline. The doctor runs standalone diagnostics without execution. Both use the same underlying detection and rules systems.

Domain Layer: The heavy lifting happens here:
- `detect.py` — `HostDetector` class gathers OS, architecture, Python, shell, network, and permission facts
- `rules.py` — `RulesEngine` evaluates all 15+ validation rules
- `repair.py` — `RepairEngine` can automatically fix broken environments (recreate venvs, fix mixed ownership, switch Python versions)
- `models.py` — Pydantic models for `HostFacts`, `ProjectIntent`, `RuleFinding`, `ResolutionRecord`, etc.
- `project/` — Discovery (scanning for project files), intent analysis (inferring requirements), resolution (dependency solving), and lifecycle management
- `resolver/` — Pluggable backends for PyPI (BFS resolution via JSON API), uv, pip, and conda
- `lock/` — Lock file generation and management (`envguard.lock` in TOML format with SHA-256 content hashes)
- `update/` — Self-updating mechanism with SHA-256 verification and rollback support

Platform Layer: macOS-specific code for permissions, Rosetta detection, Xcode CLI tools, and LaunchAgent management. Linux gets partial support here — core pipeline works, but no LaunchAgent, no MPS detection, no Rosetta checks.

All state files (in `.envguard/`) are written atomically using write-to-temp-then-rename to prevent corruption from interrupted writes. Every subprocess call has explicit timeouts. The security model is documented in detail — checksum verification for updates, no shell=True with string interpolation, path traversal protection for archive extraction.

Real Usage: What My Workflow Looks Like

I work on a lot of ML projects with different requirements. Some need PyTorch with MPS. Some need TensorFlow (which has its own special hell on macOS). Some are pure Python data pipelines. Here’s how I actually use EnvGuard day-to-day.

Starting a new project:

cd ~/projects/new-ml-experiment
envguard init

This creates a `.envguard/` directory with `state.json`, `envguard.toml` (config), and subdirectories for snapshots, cache, logs, and backups. It scans my project files to figure out what I’m building.

Checking if everything is healthy:

envguard doctor

This runs 10 diagnostic checks: host detection, project discovery, Python environment, package manager health, dependency consistency, accelerator support, permissions, network connectivity, and environment ownership. It outputs a report showing what’s working and what’s not.

Running my actual code:

envguard run - python train.py - epochs 100 - batch-size 32

Before `train.py` executes, the preflight pipeline runs. If my environment has drifted — say, I updated PyTorch and now there’s a version conflict with torchvision — EnvGuard catches it and blocks execution. I can then run `envguard repair` to fix it automatically, or `envguard lock sync` to reinstall from my lock file.

Locking dependencies for reproducibility:

envguard resolve
envguard lock generate

`resolve` uses the PyPI JSON API to resolve my project dependencies to exact pinned versions. `lock generate` writes an `envguard.lock` file with SHA-256 content hashes. I commit this to git. When someone else clones the repo, they run `envguard install — from-lock` and get exactly the same environment I have.

Self-updating:

envguard update - dry-run # check if there's a new version
envguard update # actually update with SHA-256 verification and automatic rollback snapshot

EnvGuard can update itself. Before applying an update, it creates a rollback snapshot. If something goes wrong, `envguard rollback` restores the previous version.

The Lock File: Reproducibility Without the Pain

Python dependency management has a reproducibility problem. `requirements.txt` with loose version constraints means “install something that hopefully works.” `requirements.txt` with pinned versions means “this worked on my machine at one specific moment, but good luck if you’re on a different architecture or Python version.”

EnvGuard’s lock file (`envguard.lock`) tries to be smarter. It’s a TOML file that includes:

- The exact resolved dependency graph with specific versions
- SHA-256 content hashes for verification
- Platform and Python version markers (so you can have different resolutions for macOS-arm64 vs Linux-x86_64 if needed)
- The source files that contributed to the resolution (`pyproject.toml`, `requirements.txt`, etc.)

The lock file is human-readable but machine-generated. You don’t edit it manually. You regenerate it with `envguard lock generate` or update specific packages with `envguard lock update — package <name>`.

In CI, you can run `envguard lock check` to verify that the lock file is up-to-date with your source requirements. It exits with code 13 if stale, which you can use to fail builds that might have inconsistent dependencies.

What It Doesn’t Do (And Why)

EnvGuard has deliberate limitations that are worth understanding:

It doesn’t intercept unmanaged launches. If you run `python train.py` directly, EnvGuard doesn’t see it. Only commands routed through `envguard run` get validated. This is by design — EnvGuard is opt-in, not a system-wide interceptor that could break other workflows.

It doesn’t support Windows. The codebase uses POSIX-specific APIs throughout (`os.access()` for permissions, list-form subprocess arguments, `/tmp` paths). Adding Windows support would require a parallel implementation of the platform layer, and I don’t use Windows enough to maintain that. WSL2 works if you need it.

It doesn’t make CUDA work on macOS. Apple Silicon physically cannot run NVIDIA CUDA. EnvGuard detects CUDA dependencies and blocks them with a clear error, but it can’t magically add CUDA support where none exists.

It doesn’t auto-activate environments on directory change. If you want `cd my-project` to automatically activate the right venv, use `direnv`. EnvGuard’s shell hooks are minimal and opt-in — they just load the integration, not the environments themselves.

These limitations are documented in the repo’s `docs/limitations.md` and tracked as architectural decisions in `docs/adrs/`.

Installation and Getting Started

If you’re on macOS 12+ (Monterey) or Linux, installation is straightforward:

pip install envguard-tool

The PyPI package is named `envguard-tool` because `envguard` was taken. The CLI command and Python import are both just `envguard`.

For macOS, there’s also a bootstrap script that installs shell hooks and the LaunchAgent for automatic update checking:

git clone https://github.com/rotsl/envguard.git
cd envguard
bash scripts/bootstrap.sh

Once installed, verify it works:

envguard - version
envguard doctor

Then initialize any Python project:

cd /path/to/your/project
envguard init
envguard run - python your_script.py

Why I Built This (And Who It’s For)

I built EnvGuard for myself, primarily. I’m a researcher working on machine learning for biology — specifically computer vision for fungal pathogen analysis. I work on Apple Silicon Macs. I collaborate with people on Linux servers. I deal with PyTorch, TensorFlow, JAX, and a lot of scientific Python packages with complex native dependencies.

I was tired of debugging environment issues that had nothing to do with my actual research. I wanted a tool that would catch problems before they cost me hours of training time or corrupted experimental results.

EnvGuard is for Python developers who:
- Work on macOS (especially Apple Silicon) and are tired of Rosetta/architecture surprises
- Need MPS acceleration for PyTorch and want to know when it’s not actually available
- Collaborate across different machines and need reproducible environments
- Are tired of “works on my machine” and want validation that happens before execution
- Prefer CLI tools that integrate into existing workflows rather than replacing them entirely

It’s not for everyone. If you’re a web developer working with simple Python environments, you probably don’t need this. If you’re on Windows, this won’t help you (yet). If you want a full IDE-like environment manager with GUI buttons, look elsewhere.

But if you’re doing scientific Python or ML and you’ve ever lost a day to a broken environment that you didn’t know was broken until it was too late — EnvGuard might save you some pain.

Python environment management has been broken for a long time. We’ve accepted “it works on my machine” as an inevitable part of the development experience. We’ve normalized spending hours debugging issues that have nothing to do with our actual code.

I don’t think it has to be this way. EnvGuard is my attempt to bring some of the safety and validation we expect from production systems (preflight checks, reproducible builds, clear error messages) to the messy world of Python development.

It’s not perfect. It’s alpha software with known limitations. But it’s already saved me hours of debugging, and I hope it can do the same for you.

If you’re tired of environment surprises, give it a try. Run `pip install envguard-tool`, run `envguard doctor` on your project, and see what it finds. You might discover that your “working” environment has been quietly broken in ways you never noticed.

Links:

- GitHub: github.com/rotsl/envguard
- PyPI: pypi.org/project/envguard-tool/

#Python #MachineLearning #MLOps #DeveloperTools #macOS #AppleSilicon #PyTorch #EnvironmentManagement #DevOps #OpenSource #Reproducibility #CLI #Preflight #SoftwareEngineering

I Built a Safety Net for Python Environments Because I Was Tired of Debugging “It Works on My… was originally published in The Pythoneers on Medium, where people are continuing the conversation by highlighting and responding to this story.