Skip to content

Built-in AI Chatbot

The built-in AI chatbot turns connected data into graph work you can inspect. From the Chat 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 the AI Assistant.

Enable AI Chat

AI Chat 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 AI Chat}

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 AI Chat}

Configure the Model Endpoint

Variable Default Description
AI_ENABLED true Turns the AI features on. Set to false to hide the Chat 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. Any API that implements the selected structure works.
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-4-8,claude-sonnet-5,claude-haiku-4-5-20251001 Comma-separated model IDs the deployment allows. They fill the model selector on the Chat 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 24000 Maximum tokens in a single model response.

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

Instead of sharing one deployment key, each user can store their own, in the AI Chat section of the Preferences tab on the Settings page, or by entering it when the Chat 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, Chat asks each of them to enter a key for the new API.

Build a graph schema

  1. 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.
  2. Open Chat from the left navigation.
  3. Ask the chatbot 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.

The chatbot 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 the chatbot apply the proposed graph without per-change approval.

Ask questions about the graph

After a graph schema is active, use Chat 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 the chatbot 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 the chatbot 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.