Quickstart

#User cases

The running workspace offers three built-in examples: Demi-Gods and Semi-Devils, financial risk management, and molecular property analysis. Choose Use example graph to enter its conversation, or select a question topic on a home-page case to load its preset graph and start analysis immediately, without uploading or reconstructing it. The User cases page provides scenario descriptions and demonstration videos.

#Prerequisites

Run the following commands from the project root to start iGraph itself. Docker Compose manages the Python services and PostgreSQL; this static documentation website runs independently of the application.

• Install Docker with Compose and obtain an API key and base URL for a model provider supported by the project.
• Copy .env.example and fill in the relevant provider block. Keep your real .env out of version control.

cp .env.example .env
python -c "import secrets; print(secrets.token_hex(32))"

Set IGRAPH_CONTROL_SERVICE_KEY in .env to the generated value. Backend, Agent Runtime, and both Graph Engine adapters require the same non-empty key, even when run cancellation is disabled. In Windows PowerShell, use Copy-Item .env.example .env to copy the template.

#Start the services

docker compose up --build -d
docker compose ps
curl http://localhost:21108/health

Compose defines seven services: frontend, backend, agent-runtime, graph-engine-api, graph-engine-mcp, graph-engine-worker, and postgres. By default only frontend port 21108 is published to the host, and it proxies /api/* to Backend. graph-engine-worker handles background large-graph jobs and has no HTTP health check; running is expected for that worker. Wait for the other services to become healthy.

The single-user deployment binds the frontend to 127.0.0.1:21108 by default, configurable through FRONTEND_BIND_ADDRESS / FRONTEND_PORT. Use an SSH tunnel or a controlled access entry point for remote access. IGRAPH_ADMIN_USER_ID selects the workspace owner, defaulting to admin; no login accounts need to be created or maintained.

#Your first analysis in the UI

• Open the default workspace directly without signing in or registering. Configure a provider connection and model in Model services, then choose the model for your analysis.
• Open Create your graph and select Upload source. A single file may be SQL, CSV, or TXT; multi-file selection accepts CSV files only.
• Review Source data preview first. For CSV bundles, check table names, headers, primary keys, and foreign keys; for plain text, choose line-based records or model-based entity and relation extraction.
• Start construction, wait for the draft, and inspect its size, structure, and revision. Click Save construction result to reach ready and use it for analysis. Closing the panel does not stop server-side construction; reopen it to check progress.
• Create a project and choose Load a constructed graph from its dataset controls. After importing an independent copy, create a conversation in that project and select the dataset.
• First ask the agent to confirm the dataset, graph version, node count, edge count, and relationship direction, then query neighbors or paths using real node IDs.

#Your first API request

The public API uses the default workspace automatically; clients do not need a user ID or login token. Read workspace information, then create a session. Examples use Bash; in PowerShell use curl.exe and adapt line continuations.

curl http://localhost:21108/api/workspace

curl -X POST http://localhost:21108/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"reasoning_mode":"direct","planning_mode":"auto"}'

Read session_id from the creation response, then send a message. Omit the model to use the default, or choose an available model with a configured connection. Accept-Language selects the response language for this turn: the example uses zh-CN; use en for English.

curl -N -X POST http://localhost:21108/api/sessions/SESSION_ID/chat/stream \
  -H "Accept-Language: zh-CN" \
  -H "X-iGraph-Stream-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{"message":"介绍可用的图分析能力","start_request_id":"31ac1101-cd5a-4b60-a2f7-d8379d934fe9","reasoning_mode":"direct","planning_mode":"auto","stream":true,"background":true}'

#Verify the result

• GET /api/workspace should return valid: true, single_user: true, the workspace owner, and model information. This reads workspace context; it does not sign in.
• Session creation returns session_id; streaming requests should incrementally return text/event-stream events.
• Normal construction produces a draft; save it to obtain ready state and a revision available for analysis. After loading it in a session, check graph_version and graph size with get_graph_info. Uploading or generating a draft does not mean it has been saved and loaded.