This project demonstrates a zero-config AI agent that uses LangGraph to answer natural language questions by querying a SQL database — all orchestrated with Docker Compose.

• Docker Desktop 4.43.0+ or Docker Engine installed.
• A laptop or workstation with a GPU (e.g., a MacBook) for running open models locally. If you don't have a GPU, you can alternatively use Docker Offload.
• If you're using Docker Engine on Linux or Docker Desktop on Windows, ensure that the Docker Model Runner requirements are met (specifically that GPU support is enabled) and the necessary drivers are installed.
• If you're using Docker Engine on Linux, ensure you have Docker Compose 2.38.1 or later installed.

docker compose up

That’s all. The agent spins up automatically, sets up PostgreSQL, loads a pre-seeded database (Chinook.db), and starts answering your questions.

By default, this project uses Docker Model Runner to handle LLM inference locally — no internet connection or external API key is required.

If you’d prefer to use OpenAI instead:

1. Create a secret.openai-api-key file with your OpenAI API key:

   sk-...
   

2. Restart the project with the OpenAI configuration:

   docker compose down -v
   docker compose -f compose.yaml -f compose.openai.yaml up

The project lets you explore the Chinkook database using natural language. This database represents a digital media store with information regarding artists, albums, media tracks, invoices, and customers.

The agent will write the SQL for your natural language questions:

• “Who was the best-selling sales agent in 2010?”
• “List the top 3 albums by sales.”
• “How many customers are from Brazil?”

You can customize the initial question asked by the agent — just edit the question in compose.yaml.

Need to work with a different dataset? Simply swap out Chinook.db with your own SQLite file and update the mount path in compose.yaml.

flowchart TD
    A[User] -->|Natural language query| B[Agent]

    B --> C{Agent Flow}

    C -->|Tool call| D[(Docker MCP Server)]
    D -->|SQL Query| E[(PostgreSQL)]

    C -->|LLM call| F[(Docker Model Runner)]

    E -->|Results| D
    D -->|Structured Output| B
    F -->|Generated Answer| B

    B -->|Response| A

• The LangGraph-based agent transforms questions into SQL.
• PostgreSQL is populated from a SQLite dump at runtime.
• All components are fully containerized for plug-and-play usage.

To stop and remove containers and volumes:

docker compose down -v

• LangGraph
• PostgreSQL
• Docker Compose