GraphPilot ✈️

A desktop app for building and managing knowledge graphs locally, with seamless two-way sync to Graph Commons.

Work offline at full speed. Sync to Graph Commons when you're ready for visual network analysis.

---

Setup

Requirements: Python 3.11+, a Graph Commons account (email/password — social login not supported)

git clone https://github.com/YOUR_USERNAME/GraphPilot.git
cd GraphPilot
pip install -r requirements.txt
python main.py

requirements.txt

PySide6
PySide6-WebEngine
requests

---

Core Concepts

Database file (.json) — your local graph. Stores nodes, edges, pending sync state, and the schema (node types, edge types, properties) for that specific graph. You can have as many as you want. Open them via File → Open Database or File → Open Recent.

settings.json — app-level preferences only: auto-save behaviour, startup path, GC credentials, recent file list, GPU setting. Never stores graph data or schema.

---

Workflows

Starting fresh from Graph Commons

1. Go to Graph Commons → API Settings — enter your email, password, and Graph ID
2. Click ⬇️ Load from Graph Commons in the menu bar
3. Your graph loads locally: all nodes, edges, types, and property schemas are pulled in
4. The open database file is saved automatically after a successful load

Building a graph locally first

1. File → Save Database to create a .json file
2. Use the Fast-Logger tab to log connections — pick source type + name, edge verb, target type + name, fill properties, hit Log
3. Sync to Graph Commons when ready with ☁️ Sync to Graph Commons

Daily logging flow

• Fast-Logger tab: source type/name → edge verb → target/name → properties → Log Connection
• Name dropdowns filter to only show nodes matching the selected type
• Properties shown are pre-populated from the node's type schema — fill what's relevant
• After logging, new property keys you introduced are automatically added to all other nodes of that type (matching how Graph Commons handles type-level schemas)

Editing existing nodes

• Switch to the Viewer tab — search or browse the table
• Click a node row — its properties appear in the Details pane on the right
• Hit Edit Properties, modify inline, Save Changes
• Same property propagation applies: new keys spread to all nodes of that type

Syncing to Graph Commons

GraphPilot tracks exactly what changed since the last sync in a _pending log inside the database file. On sync it runs up to 4 sequential API calls:

Step	What happens
1a	New node types created in GC with their property schemas
1a2	New custom properties registered on existing node type schemas
1b	New edge types created with correct source/target type constraints
2	Single patch: node creates + updates + edge creates + deletes

After a successful sync, all Graph Commons IDs are back-filled locally and _pending is cleared.

Viewing the live graph

Click 🎨 Open Graph Commons in the menu bar — the graph opens in an embedded browser inside the app, authenticated automatically using your saved credentials.

---

Schema & Properties

Node types, edge types, and property definitions live inside the database file, not in settings. Each graph can have its own schema.

Locked universal properties — Description, Image URL, Reference — are present on every node and map to Graph Commons' first-class node fields. They cannot be removed.

Universal properties — any additional properties you want on every node regardless of type.

Specific properties — per-type (e.g. Job on Person, Color on Object). Adding a specific property injects it with an empty value into all existing nodes of that type immediately — no need to sync first to see it.

To manage schema: File → Settings, then the Node Types / Edge Types / Properties tabs. Clicking OK saves both settings.json (prefs) and the open database file (schema) to disk immediately.

---

Settings Reference

Setting	Saved in
Node types, edge verbs, properties	Database file
Startup database path	settings.json
Auto-save triggers (log, delete, edit)	settings.json
Graph Commons credentials	settings.json (password encrypted)
Recent databases (last 5)	settings.json
GPU acceleration	settings.json

---

Project Structure

GraphPilot/
├── main.py           # Entry point, GPU/rendering config
├── engine.py         # All data logic — local DB, GC sync, schema
├── app_ui.py         # Main window, event handling
├── settings_ui.py    # Settings and GC credentials dialogs
├── visualizer.py     # Embedded GC browser window
├── ui/
│   ├── mainform.py         # Qt Designer generated main window
│   ├── settings_dialog.py  # Qt Designer generated settings dialog
│   └── stylesheet.py       # App-wide dark theme
└── settings.json     # Auto-generated on first run

---