PuppyGraph AI

PuppyGraph AI turns connected data into graph work you can inspect. From the AI page, it can:

Inspect catalog metadata, sample rows, profile columns, and probe likely joins.
Propose nodes and edges for a graph schema.
Apply approved schema changes.
Translate natural-language questions into graph queries and explain results.

For a complete hands-on schema-building walkthrough, see Building a Graph with PuppyGraph AI.

Enable PuppyGraph AI

PuppyGraph AI calls an external model API, so it needs an API key before it can answer anything. PuppyGraph works with both the Anthropic Messages API structure and the OpenAI Chat Completions API structure, so you can point it at either.

In a local Docker setup, configure it with environment variables. Anthropic is the default, so a key is enough:

environment:
  - AI_ENABLED=true
  - AI_API_KEY=${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY for PuppyGraph AI}

To use OpenAI instead, select the OpenAI structure and replace the model list, which otherwise still names Anthropic models:

environment:
  - AI_ENABLED=true
  - AI_API_STRUCTURE=openai_style
  - AI_MODELS=gpt-5.6
  - AI_API_KEY=${OPENAI_API_KEY:?Set OPENAI_API_KEY for PuppyGraph AI}

Configure the Model Endpoint

Variable	Default	Description
`AI_ENABLED`	`true`	Turns the AI features on. Set to `false` to hide the AI page.
`AI_API_STRUCTURE`	`anthropic_style`	Request and response structure. `anthropic_style` posts to `<AI_BASE_URL>/v1/messages`, `openai_style` to `<AI_BASE_URL>/chat/completions`. Other APIs that implement the selected structure can work too. See API Structure and AI Provider.
`AI_BASE_URL`	`https://api.anthropic.com`, or `https://api.openai.com/v1` under `openai_style`	Base URL of the API, not a complete model endpoint. Set `AI_API_STRUCTURE` alongside it, and use a securely deployed HTTPS endpoint: requests carry catalog metadata, sampled rows, and generated queries.
`AI_API_KEY`	`""`	Deployment-wide API key for the configured API. Treat as a secret. A key a user saves for themselves overrides it for that user.
`AI_MODELS`	`claude-opus-5-5,claude-sonnet-5,claude-haiku-4-5-20251001`	Comma-separated model IDs the deployment allows. They fill the model selector on the AI page, and the first entry is the default. Use IDs the configured API publishes, and models that support streaming and tool calling.
`AI_MAX_TOKENS`	`64000`	Maximum tokens in a single model response.

The default model list is Anthropic's, so always set AI_MODELS when you change the API.

API Structure and AI Provider

AI_API_STRUCTURE names a request and response structure, not an AI provider. The provider is the company that hosts the model and issues your API key. Many providers expose an endpoint that follows one of the two structures, so pick the structure the provider's endpoint implements, then point AI_BASE_URL at that endpoint and use the provider's own key and model IDs. A provider whose endpoint implements the OpenAI Chat Completions structure does not need an OpenAI account or an OpenAI API key.

Provider	`AI_API_STRUCTURE`	`AI_BASE_URL`	Example
Anthropic	`anthropic_style` (default)	Leave unset	The default example under Enable PuppyGraph AI
Google Gemini	`openai_style`	`https://generativelanguage.googleapis.com/v1beta/openai/`	Using Gemini with PuppyGraph AI

Gemini works through Google's OpenAI-compatible endpoint with a Gemini API key from Google AI Studio. Gemini 3 models require thought signatures to be sent back with tool calls, which PuppyGraph 1.14.0 adds. Earlier releases fail after the first tool call with a 400 error that mentions a missing thought_signature.

environment:
  - AI_ENABLED=true
  - AI_API_STRUCTURE=openai_style
  - AI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
  - AI_MODELS=gemini-3.8-flash
  - AI_API_KEY=${GEMINI_API_KEY:?Set GEMINI_API_KEY for PuppyGraph AI}

Endpoints from other providers that implement one of the two structures can also work. PuppyGraph AI needs streaming and tool calling, so choose models that support both, and send a test message from the AI page before you roll one out. If you have questions about a provider, contact us.

Configuration and provider errors

PuppyGraph checks the instance-level AI settings before it contacts the provider. If one is not valid, the AI page shows a message that starts with Invalid AI API configuration: and names the setting, for example AI_API_STRUCTURE must be anthropic_style or openai_style or AI_BASE_URL: base URL must not contain a query or fragment. Fix the variable and restart PuppyGraph.

When the provider returns status 429 (rate limit) or 503 (overloaded), PuppyGraph retries the request up to three times, waiting about 1, 2, and 4 seconds, or as long as the provider's Retry-After header asks. It does not retry when the provider asks for a wait longer than 30 seconds. Errors that remain appear in the chat as AI service error:, followed by the provider's status code and message. PuppyGraph replaces the API key with [redacted] wherever a provider's message repeats it.

Instead of sharing one deployment key, each user can store their own, in the PuppyGraph AI section of the Preferences tab on the Settings page, or by entering it when the AI page asks for a key. A key issued for one API is not valid for another, so PuppyGraph records each saved key together with the API structure and base URL that were in effect at the time. If you later change AI_API_STRUCTURE or AI_BASE_URL, those keys are not sent to the new endpoint. The users who saved them fall back to AI_API_KEY, and where the deployment has no key of its own, the AI page asks each of them to enter a key for the new API.

Personal keys depend on CLUSTER_SECURITYKEY

PuppyGraph stores these personal keys encrypted, with a key derived from CLUSTER_SECURITYKEY. If you change CLUSTER_SECURITYKEY, PuppyGraph can no longer read the saved keys, so each user is asked to enter their key again. The default CLUSTER_SECURITYKEY is public, so set your own value before users save keys.

Build a graph schema

Connect at least one catalog from the Catalogs page. If you have not connected one yet, see Connecting for the parameters your data source needs.
Open AI from the left navigation.
Ask PuppyGraph AI to build the graph:

Please inspect my connected catalog and build a graph schema. Profile the tables,
propose a schema, and apply it when the draft is ready.

PuppyGraph AI may ask for confirmation before applying schema changes. Review the proposed nodes, edges, source tables, identifiers, and key mappings before approving them. Use auto-confirm only when you are comfortable letting PuppyGraph AI apply the proposed graph without per-change approval.

Ask questions about the graph

After a graph schema is active, use PuppyGraph AI as a graph query assistant:

Show the top relationship types connected to User nodes.

Good prompts name the labels, relationships, time windows, filters, or limits you care about. If PuppyGraph AI returns no rows, ask it to show which labels and relationships it queried so you can check whether the graph model matches your question.

Use it well

Keep the provider API key private. Do not paste secrets into chat messages.
Ask for bounded results, such as "top 10" or "limit 20", when exploring data.
Review generated queries before turning them into production application logic.
Use PuppyGraph AI for graph exploration and approved schema changes. Keep unrestricted administrative automation out of normal chat sessions.
Use Role-Based Access Control and Row-Level Security when different users should have different access to graph data.