GraphX.AI

Web app for generating and running read-only Gremlin queries against JanusGraph, then visualizing results as an interactive graph.

Agentic Query Generation

Enter a prompt to retrieve the data you want to access.

Visualize the graph generated by the query

Inspect and run queries

What You Can Do

• Register one or more JanusGraph servers.
• Create sessions for each server.
• Ask questions in natural language.
• Let the agent generate Gremlin and run it.
• Re-run or edit queries and inspect the returned graph.

Requirements

• Node.js 20+
• Reachable JanusGraph Gremlin endpoint(s)
• OpenAI API key

Quick Start (Local Repo)

1. Install dependencies.

pnpm install

2. Create local env file.

cp .env.example .env.local

3. Set required env var in .env.local.

OPENAI_API_KEY=your_key_here

4. Start in development mode.

pnpm dev

5. Open http://localhost:3000.

Quick Start (NPX)

1. Export your API key.

export OPENAI_API_KEY=your_key_here

2. Start GraphX.AI directly:

npx graphx-ai

3. Open http://localhost:3000.

By default, runtime files are created in your current directory under ./server and ./log. Set GRAPHX_AI_HOME to store this data elsewhere.

Run Modes

• Development: pnpm dev
• Production build: pnpm build
• Production start: pnpm start
• Lint: pnpm lint
• Tests: pnpm test

App Utilization Flow

1. Add or select a server connection.
2. Create a new session.
3. Type a prompt describing the graph data you want.
4. Review generated Gremlin + reasoning.
5. Inspect the graph visualization and raw response data.
6. Re-run or edit queries as needed.

Troubleshooting

• If query generation fails, confirm OPENAI_API_KEY is set.
• If query execution fails, verify server URL/credentials and traversal source.
• If a query is blocked, check GREMLIN_REJECT_MUTATIONS in .env.local.

Documentation

Technical and development details were moved to DEVELOPMENT.md.

Publication Checklist

1. Update version in package.json.
2. Validate package contents:

pnpm pack:check

3. Publish to npm:

npm publish