Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/FloxTBoTyy/BoardPulse-AI/llms.txt

Use this file to discover all available pages before exploring further.

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.
1

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.
2

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.
3

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.
4

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.
5

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:
FieldTypeDefaultDescription
messagestringrequiredYour question (2–2000 characters)
workspace_idstring"default"Workspace to query against
modelstring | nullnullOverride the model name for this request
preferred_provider"cloud" | "local" | "hybrid" | "mock" | nullnullAI provider preference
include_sqlbooleantrueInclude 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:
FieldTypeDescription
answerstringExecutive-quality natural-language summary of the result
sqlstring | nullThe validated SQL that was generated (only when include_sql: true)
executed_sqlstring | nullThe exact SQL that ran, including any injected LIMIT. Always returned when a query was executed.
providerstringThe AI provider that handled the request (cloud, local, mock)
tableQueryResultTable | nullStructured result set with columns and rows
chartChartSpec | nullChart spec with type, labels, series, and optional base64 image
exportsExportArtifact[]CSV and XLSX download artifacts
warningsstring[]Non-fatal warnings from the pipeline
metaobjectMetadata — source dialect, approved tables, row count
timestampdatetimeUTC 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us