Cursor Rules Template: Python FastAPI Knowledge Base

Overview

The Cursor Rules configuration is designed for building an enterprise knowledge base assistant using a Python FastAPI backend with PostgreSQL for storage, SQLAlchemy for ORM, and Redis for caching. This template targets document ingestion, citation-enabled responses, and robust permission handling through Cursor AI.

When to Use These Cursor Rules

• When building an enterprise KB that ingests diverse document types (PDF, HTML, Word) and exposes a searchable index.
• When you require per-user or per-group permissions to access KB content and citations.
• When you need citation provenance back in responses and feedback loops to improve results over time.

Copyable .cursorrules Configuration

# Cursor Rules Version 1
Framework Role & Context:
- You are Cursor AI, an enterprise KB assistant for document ingestion, permissions, and citations.
- Stack: Python FastAPI, PostgreSQL, SQLAlchemy, Redis.

Code Style and Style Guides:
- Pythonic, type hints, docstrings, PEP8.

Architecture & Directory Rules:
- Modular architecture: ingestion, kb, permissions, citations, feedback.
- Use a layered approach with services and repositories.

Authentication & Security Rules:
- Implement OAuth2 with JWT, RBAC, and audit trails.
- Never log secrets or plaintext credentials.

Database and ORM patterns:
- SQLAlchemy ORM with AsyncSession per request; migrations with Alembic.
- Define models for Document, Citation, User, Permission, and IngestionJob.

Testing & Linting Workflows:
- Use pytest; lint with black/isort; run mypy for types.

Prohibited Actions and Anti-patterns for the AI:
- Do not bypass auth, expose secrets, or write to prod databases from untrusted sources.
- Do not fetch remote content without validation; avoid brittle regex-based parsing.

Recommended Project Structure

backend/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── v1/
│   │       ├── kb.py
│   │       └── auth.py
│   ├── ingestion/
│   │   ├── processors/
│   │   └── parsers/
│   ├── kb/
│   │   ├── models.py
│   │   ├── repositories.py
│   │   └── services.py
│   ├── permissions/
│   │   └── policies.py
│   └── citations/
│       └── handler.py
├── tests/
├── requirements.txt
└── alembic/

Core Engineering Principles

• Single source of truth for documents and citations in the KB.
• Robust access control with RBAC enforced at the API layer.
• Idempotent ingestion pipelines with replay-safe processing.
• Separation of concerns: ingestion, KB storage, permissions, and citations are distinct services.
• Observability: structured logs, metrics, and tracing for KB operations.

Code Construction Rules

• Use SQLAlchemy ORM models for Document, Citation, User, Permission, and IngestionJob.
• Store citations with provenance metadata and source URL.
• Index ingested content for fast retrieval and linked citations.
• Validate all incoming ingestion payloads against a strict schema.
• Do not bypass authorization checks on KB reads or writes.
• Keep business logic in services, not in API handlers.

Security and Production Rules

• Enforce OAuth2 with JWT and RBAC for all KB endpoints.
• Encrypt sensitive fields at rest; never expose tokens in responses.
• Implement input validation and anti-CSRF measures for state-changing calls.
• Use environment-based configuration and secret management (e.g., Vault, AWS Secrets Manager).
• Regularly rotate credentials and enforce least-privilege access.

Testing Checklist

• Unit tests for ingestion processors and KB models.
• Integration tests for ingestion, search, and citations flows.
• End-to-end tests simulating user queries with citations.
• Static typing checks and linting in CI.
• Security scanning on dependencies in each release.

Common Mistakes to Avoid

• Overcomplicating the ingestion pipeline with unnecessary parsers.
• Neglecting RBAC in all KB access paths.
• Skipping citation provenance in responses.
• Posting raw secrets in logs or responses.
• Unstructured prompts that ignore KB formatting and citation rules.

Related Cursor rules templates

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

• Cursor Rules Template: FastAPI + SQLAlchemy for AI Legal Research Assistant
• Cursor Rules Template for AI Bookkeeping with Python FastAPI & PostgreSQL
• Cursor Rules Template: Construction Project Management Stack
• Cursor Rules Template: IoT Water Monitoring with FastAPI & PostgreSQL

FAQ

What stack does this template target?

This template targets a Python FastAPI backend with PostgreSQL (via SQLAlchemy) and Redis caching. It provides a complete outline for document ingestion, permissioning, and citations within Cursor AI for an enterprise knowledge base.

How do I ingest documents into the KB?

Use the ingestion module to parse PDF/HTML/Office formats, extract text and metadata, and store Documents with linked Citations. Validate sources and preserve versioned content for auditability in Cursor-powered responses.

How are citations generated and presented?

Citations are derived from a provenance-aware index. Each KB response includes a citation trail with the source URL, page or section, and timestamp to enable verification by the user.

How is access controlled across the KB?

RBAC policies enforce read/write permissions at the API layer. All KB modifications are logged in an audit trail, supporting compliance and traceability.

How does feedback looping work?

User feedback is captured and used to adjust indexing, citation rules, and content updates. Feedback becomes part of the KB improvement cycle without compromising provenance.