Ask business questions and get executive-quality answers

BoardPulse AI is built around a single idea: executives and analysts should be able to ask questions in plain language and get answers they can act on. You type a question, and the system translates it into a verified SQL query, runs it against your live database, and returns a structured response — including a professional summary, a data table, an optional chart, and downloadable files.

How it works

Each question you send moves through a five-stage LangGraph pipeline that handles everything from loading your workspace schema to composing the final answer.

load_context

BoardPulse loads your workspace configuration — the approved table list, source database dialect, and any workspace-level settings. This context shapes every subsequent step.

draft_query

Your message is sent to the configured AI provider (cloud, local, or mock) along with the workspace schema. The model returns a SQL draft and an executive summary in the answer field.

validate_query

The drafted SQL passes through the SQL guardrail layer. Only SELECT statements against your approved tables are allowed. Any forbidden operation raises an HTTP 422 before execution.

execute_query

The validated query runs against your source database in read-only mode. Results are wrapped with a safety LIMIT, then converted into a table, chart, and export files.

finalize_response

The executive summary and any pipeline warnings are merged into the final answer. The complete ChatResponse is returned to the caller.

Request schema

Send a POST to /api/v1/chat/query with a JSON body matching ChatRequest:

Field	Type	Default	Description
`message`	`string`	required	Your question (2–2000 characters)
`workspace_id`	`string`	`"default"`	Workspace to query against
`model`	`string \| null`	`null`	Override the model name for this request
`preferred_provider`	`"cloud" \| "local" \| "hybrid" \| "mock" \| null`	`null`	AI provider preference
`include_sql`	`boolean`	`true`	Include the generated SQL in the response

Provider options

cloud

Routes to an OpenAI-compatible API (e.g., GPT-4.1-mini). Requires OPENAI_API_KEY.

local

Routes to a local Ollama instance. Requires OLLAMA_ENABLED=true and a running model.

hybrid

Prefers local if Ollama is available, falls back to cloud. Good default for production.

mock

Returns deterministic responses without calling any AI model. Use for testing and CI.

Response schema

A successful query returns a ChatResponse object:

Field	Type	Description
`answer`	`string`	Executive-quality natural-language summary of the result
`sql`	`string \| null`	The validated SQL that was generated (only when `include_sql: true`)
`executed_sql`	`string \| null`	The exact SQL that ran, including any injected `LIMIT`. Always returned when a query was executed.
`provider`	`string`	The AI provider that handled the request (`cloud`, `local`, `mock`)
`table`	`QueryResultTable \| null`	Structured result set with columns and rows
`chart`	`ChartSpec \| null`	Chart spec with type, labels, series, and optional base64 image
`exports`	`ExportArtifact[]`	CSV and XLSX download artifacts
`warnings`	`string[]`	Non-fatal warnings from the pipeline
`meta`	`object`	Metadata — source dialect, approved tables, row count
`timestamp`	`datetime`	UTC timestamp of when the response was generated

Example

Request

curl -X POST http://localhost:8000/api/v1/chat/query \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What were total sales by region last month?",
    "workspace_id": "default",
    "preferred_provider": "cloud",
    "include_sql": true
  }'

Response

{
  "answer": "Total sales last month by region: North America led with $4.2M, followed by Europe at $2.8M and LATAM at $1.1M.",
  "sql": "SELECT region, SUM(amount) AS total_sales FROM sales_orders WHERE order_date >= date_trunc('month', now() - interval '1 month') AND order_date < date_trunc('month', now()) GROUP BY region ORDER BY total_sales DESC",
  "executed_sql": "SELECT region, SUM(amount) AS total_sales FROM sales_orders WHERE order_date >= date_trunc('month', now() - interval '1 month') AND order_date < date_trunc('month', now()) GROUP BY region ORDER BY total_sales DESC LIMIT 1000",
  "provider": "cloud",
  "table": {
    "columns": ["region", "total_sales"],
    "rows": [
      {"region": "North America", "total_sales": 4200000},
      {"region": "Europe", "total_sales": 2800000},
      {"region": "LATAM", "total_sales": 1100000}
    ],
    "row_count": 3
  },
  "chart": {
    "type": "bar",
    "title": "Total Sales by Region",
    "x_label": "Region",
    "y_label": "Sales (USD)",
    "series": [
      {"label": "North America", "value": 4200000},
      {"label": "Europe", "value": 2800000},
      {"label": "LATAM", "value": 1100000}
    ],
    "base64_image": null
  },
  "exports": [
    {"format": "csv", "filename": "total-sales-by-region-1714123456.csv", "url": "/api/v1/exports/total-sales-by-region-1714123456.csv"},
    {"format": "xlsx", "filename": "total-sales-by-region-1714123456.xlsx", "url": "/api/v1/exports/total-sales-by-region-1714123456.xlsx"}
  ],
  "warnings": [],
  "meta": {
    "source_dialect": "postgresql",
    "approved_tables": ["sales_orders", "customers", "products"],
    "row_count": 3
  },
  "timestamp": "2026-04-26T14:32:11.000Z"
}

Tips

Set include_sql: true (the default) to receive both the sql field (the generated and validated query) and executed_sql (the exact query that ran with any injected LIMIT). These are useful for audits, debugging, and building trust in the AI’s output.

The executed_sql field always reflects what actually ran against the database, including safety limits applied by the system. Use this field — not sql — for compliance logging.

Get Started

Configuration

Core Features

Deployment

Ask business questions and get executive-quality answers

How it works

Request schema

Provider options

cloud

local

hybrid

mock

Response schema

Example

Request

Response

Tips

​How it works

​Request schema

​Provider options

cloud

local

hybrid

mock

​Response schema

​Example

​Request

​Response

​Tips

How it works

Request schema

Provider options

Response schema

Example

Request

Response

Tips