Cursor Rules Template: NLP Chart, SQL & Reports (Python FastAPI Stack) | Suhas Bhairav

Overview

Direct answer: This Cursor rules configuration provides a Python FastAPI + SQLAlchemy + PostgreSQL stack to translate natural language questions into charts (Plotly), SQL queries, and business reports. Paste the included configuration into a .cursorrules file at your repo root to enable Cursor AI to assist data analyst tasks.

Stack: Python, FastAPI, SQLAlchemy, PostgreSQL, Plotly, Pandas, Jinja2, with a reporting workflow.

When to Use These Cursor Rules

When you want Cursor AI to interpret natural language questions and generate corresponding SQL queries against PostgreSQL.
When you need automatic chart generation using Plotly for data exploration and dashboards.
When you require automated business reports (HTML/PDF) produced from SQL results and charts.
When you want a clean architecture with testable service layers and ORM-based data access.

Copyable .cursorrules Configuration

// Cursor Rules Template for: AI Data Analyst App
// Framework and Context
FRAMEWORK: Python FastAPI + SQLAlchemy + PostgreSQL + Plotly
CONTEXT: You are Cursor AI configured to assist building an AI data analyst app that accepts natural language questions and returns charts, SQL and business reports. Prioritize safety, reproducibility, and testability.

// Code Style and Style Guides
LANGUAGE: Python 3.11, PEP8, type hints, docstrings
RECOMMENDED_LIBS: fastapi, sqlalchemy, psycopg2-binary, plotly, pandas, jinja2
CODE_CONVENTIONS: use f-strings, parameterized SQL, typed returns, docstrings in all modules

// Architecture & Directory Rules
DIRECTORY: app/
SUBDIRS: app/api/, app/core/, app/db/, app/models/, app/services/, app/routers/, app/templates/, tests/
PATTERNS: service layer, repository for data access, dependency injection, pydantic models for request validation

// Authentication & Security Rules
AUTH: OAuth2PasswordBearer, JWT tokens; bcrypt for password hashing
PERMISSIONS: authenticated users only; rate limiting on NLQ-to-chart calls

// Database and ORM patterns
DB: PostgreSQL, SQLAlchemy ORM; models: User, Chart, QueryLog, Report, Dataset
MIGRATIONS: Alembic; migrations stored under db/migrations

// Testing & Linting Workflows
TESTS: pytest; mypy; pre-commit; GitHub Actions: lint, type-check, tests, build
CI: tests must pass before merge; run on PRs

// Prohibited Actions and Anti-patterns for the AI
DO_NOT: expose raw SQL in API responses; concatenate SQL strings; bypass auth or validations; access external networks in critical flows

// End of Cursor Rules Template

Recommended Project Structure

app/
├── api/
│   └── v1/
├── core/
├── db/
│   ├── models/
│   │   ├── user.py
│   │   ├── chart.py
│   │   ├── report.py
│   │   └── dataset.py
│   └── migrations/
├── models/
├── services/
├── routers/
├── templates/
│   └── reports/
└── tests/

Core Engineering Principles

Explicit data contracts and input validation at every boundary.
Separation of concerns: NLQ parsing, SQL generation, charting, and reporting are isolated services.
Idempotent data operations and auditable logs.
Test-driven development with CI checks for unit and integration tests.
Safety first: avoid dangerous SQL, avoid auto-execution of external commands.

Code Construction Rules

Use SQLAlchemy ORM models for data access; do not use raw dynamic SQL without parameter binding.
NLQ parser must be deterministic and testable; return a structured AST-like object before query execution.
Charts: render with Plotly; export options included; use consistent theming.
Reports: generate with Pandas + Jinja2 templates; support PDF/HTML exports.
Do not hard-code secrets; fetch from environment or secret manager.

Security and Production Rules

JWT-based authentication; enforce token expiry; rotate refresh tokens.
Use parameterized queries; avoid concatenated SQL strings.
Database connections pooled; handle timeouts and retries gracefully.
Audit logs for NLQ requests and generated SQL.

Testing Checklist

Unit tests for NLQ parsing accuracy across intents.
Integration tests for SQL generation against a test PostgreSQL instance.
End-to-end tests: NLQ → Chart/SQL/Report pipeline.
Static type checks with mypy; linting with black/ruff.
CI includes tests on PRs and checks for secrets scanning.

Common Mistakes to Avoid

Overfitting NLQ to a single schema; failing to validate user inputs.
Returning raw SQL strings to users; always present only parameterized results or safe previews.
Neglecting schema changes in migrations; skip Alembic migrations in tests.
Hard-coding chart styles that break theming across deployments.

Related Cursor rules templates

Explore adjacent Cursor rules templates for similar stacks, workflows, and production constraints.

FAQ

What is a Cursor Rules Template in this stack?

A Cursor Rules Template defines how Cursor AI should operate within the Python FastAPI + SQLAlchemy + PostgreSQL stack to transform natural language questions into charts, SQL, and business reports. It codifies roles, safety rules, architecture, and testing requirements for consistent AI-assisted development.

Which tools does this template assume?

The stack uses Python 3.11+, FastAPI, SQLAlchemy, PostgreSQL, Plotly for charts, Pandas for data processing, and Jinja2 templates for reports. It enforces clean architecture, DI, and secure data access in all NLQ-driven flows.

How do I paste this into my project?

Copy the code block inside Copyable .cursorrules Configuration and place it at the project root as .cursorrules. It will guide Cursor AI to align with your Python FastAPI backend, ORM, and charts/report pipeline.

What are the security expectations?

Authenticate users via OAuth2/JWT, validate inputs, parameterize all queries, hash secrets, and audit NLQ requests. Avoid exposing raw SQL or secrets in responses.

How is testing handled?

Tests cover NLQ parsing accuracy, SQL generation, chart rendering, and report creation. CI runs unit, integration, and end-to-end tests to prevent regressions.

What wins with this template?

Standardized Cursor AI behavior for AI-assisted data analytics, reproducible charts, and auditable reports, with clear separation of concerns and strong security practices.

Cursor Rules Template: NLP Chart, SQL & Reports for AI Data Analyst App

Target User

Use Cases