Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 3d314a1

Browse files
authored
Add comprehensive GitHub Copilot instructions for development workflow (#253)
* Initial plan * Add comprehensive Copilot instructions with validated commands and timing --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
1 parent 23fdf64 commit 3d314a1

File tree

1 file changed

+316
-0
lines changed

1 file changed

+316
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 316 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,316 @@
1+
# RAG on PostgreSQL - Development Instructions
2+
3+
**ALWAYS FOLLOW THESE INSTRUCTIONS FIRST**. Only search for additional information or use bash commands when the instructions below are incomplete or found to be in error.
4+
5+
## Overview
6+
7+
RAG on PostgreSQL is a Python FastAPI backend with React TypeScript frontend that provides a web-based chat application using OpenAI models to answer questions about data in a PostgreSQL database with pgvector extension. The application is designed for Azure deployment via Azure Developer CLI (azd).
8+
9+
## Required Tools and Dependencies
10+
11+
Install the following tools before beginning development:
12+
13+
- **Python 3.10+** (3.12 recommended)
14+
- **Node.js 18+** for frontend development
15+
- **PostgreSQL 14+** with pgvector extension
16+
- **Azure Developer CLI (azd)** for deployment
17+
- **Docker Desktop** for dev containers (optional)
18+
- **Git** for version control
19+
20+
## Development Environment Setup
21+
22+
### Bootstrap the Development Environment
23+
24+
Run these commands in sequence. NEVER CANCEL any long-running commands:
25+
26+
1. **Install Python dependencies** (takes ~90 seconds):
27+
```bash
28+
python3 -m pip install -r requirements-dev.txt
29+
```
30+
31+
2. **Install backend package in editable mode** (takes ~5 seconds):
32+
```bash
33+
python3 -m pip install -e src/backend
34+
```
35+
36+
3. **Install PostgreSQL and pgvector extension**:
37+
```bash
38+
# Ubuntu/Debian:
39+
sudo apt update && sudo apt install -y postgresql-16-pgvector
40+
41+
# Start PostgreSQL and set password
42+
sudo service postgresql start
43+
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres'"
44+
```
45+
46+
4. **Configure environment file**:
47+
```bash
48+
cp .env.sample .env
49+
```
50+
Edit `.env` to set `POSTGRES_USERNAME=postgres` and `POSTGRES_PASSWORD=postgres`.
51+
52+
5. **Set up database and seed data** (takes ~2 seconds each):
53+
```bash
54+
python ./src/backend/fastapi_app/setup_postgres_database.py
55+
python ./src/backend/fastapi_app/setup_postgres_seeddata.py
56+
```
57+
58+
6. **Install frontend dependencies** (takes ~22 seconds):
59+
```bash
60+
cd src/frontend
61+
npm install
62+
cd ../../
63+
```
64+
65+
7. **Build frontend** (takes ~12 seconds):
66+
```bash
67+
cd src/frontend
68+
npm run build
69+
cd ../../
70+
```
71+
72+
8. **Install pre-commit hooks**:
73+
```bash
74+
pre-commit install
75+
```
76+
77+
## Running the Application
78+
79+
### Backend Server
80+
```bash
81+
python -m uvicorn fastapi_app:create_app --factory --reload
82+
```
83+
Serves at `http://localhost:8000` with built frontend included.
84+
85+
### Frontend Development Server (with hot reloading)
86+
```bash
87+
cd src/frontend
88+
npm run dev
89+
```
90+
Serves at `http://localhost:5173/` with hot reloading for development.
91+
92+
### Both via VS Code
93+
Use "Frontend & Backend" configuration in the VS Code Run & Debug menu.
94+
95+
## Code Quality and Testing
96+
97+
### Linting and Formatting (ALWAYS run before committing)
98+
```bash
99+
ruff check . # Lint code (takes <1 second)
100+
ruff format . # Format code (takes <1 second)
101+
mypy . --python-version 3.12 # Type check (takes ~42 seconds)
102+
```
103+
104+
**NOTE**: MyPy may show 1 minor import error in `evals/safety_evaluation.py` which is expected and safe to ignore.
105+
106+
### Testing (NEVER CANCEL - full test suite takes ~25 seconds)
107+
```bash
108+
pytest -s -vv --cov --cov-fail-under=85
109+
```
110+
111+
**CRITICAL**: Some tests may fail with database connection issues if using different PostgreSQL credentials. This is expected in fresh environments and does not indicate broken functionality.
112+
113+
### End-to-End Testing with Playwright (NEVER CANCEL - takes 2+ minutes)
114+
```bash
115+
playwright install chromium --with-deps
116+
pytest tests/e2e.py --tracing=retain-on-failure
117+
```
118+
119+
## Build Times and Timeout Requirements
120+
121+
**CRITICAL TIMING INFORMATION** - Set these timeout values and NEVER CANCEL:
122+
123+
- **Dependencies install**: 90 seconds (use 180+ second timeout)
124+
- **Frontend npm install**: 22 seconds (use 60+ second timeout)
125+
- **Frontend build**: 12 seconds (use 30+ second timeout)
126+
- **MyPy type checking**: 42 seconds (use 90+ second timeout)
127+
- **Full test suite**: 25 seconds (use 60+ second timeout)
128+
- **Playwright E2E tests**: 2+ minutes (use 300+ second timeout)
129+
130+
## Manual Validation After Changes
131+
132+
**ALWAYS perform these validation steps after making code changes:**
133+
134+
1. **Lint and format code**:
135+
```bash
136+
ruff check . && ruff format .
137+
```
138+
139+
2. **Type check (if Python changes)**:
140+
```bash
141+
mypy . --python-version 3.12
142+
```
143+
144+
3. **Run relevant tests**:
145+
```bash
146+
pytest tests/test_<relevant_module>.py -v
147+
```
148+
149+
4. **Test application end-to-end**:
150+
```bash
151+
# Start server
152+
python -m uvicorn fastapi_app:create_app --factory --reload
153+
```
154+
Then in another terminal:
155+
```bash
156+
# Test API endpoints
157+
curl http://localhost:8000/items/1
158+
# Should return JSON with item data
159+
160+
# Test frontend
161+
curl http://localhost:8000/ | head -n 5
162+
# Should return HTML with "RAG on PostgreSQL" title
163+
```
164+
165+
5. **Test frontend build**:
166+
```bash
167+
cd src/frontend && npm run build
168+
```
169+
170+
6. **Functional testing scenarios**:
171+
- Open `http://localhost:8000/` in browser
172+
- Verify the "Product chat" interface loads with example questions
173+
- Click an example question (will show Azure auth error in local dev - this is expected)
174+
- Verify the frontend UI is responsive and properly styled
175+
176+
## Key Project Structure
177+
178+
### Backend (`src/backend/fastapi_app/`)
179+
- `__init__.py` - FastAPI app factory
180+
- `api_models.py` - Pydantic models for API
181+
- `postgres_engine.py` - Database connection setup
182+
- `postgres_searcher.py` - Vector and text search logic
183+
- `rag_simple.py`, `rag_advanced.py` - RAG implementations
184+
- `routes/api_routes.py` - API endpoints
185+
- `routes/frontend_routes.py` - Static file serving
186+
187+
### Frontend (`src/frontend/`)
188+
- React TypeScript app with FluentUI components
189+
- Vite build system
190+
- Built files output to `src/backend/static/`
191+
192+
### Infrastructure (`infra/`)
193+
- Bicep templates for Azure deployment
194+
- `main.bicep` - Main infrastructure definition
195+
196+
### Configuration Files
197+
- `pyproject.toml` - Python project config (ruff, mypy, pytest)
198+
- `requirements-dev.txt` - Development dependencies
199+
- `azure.yaml` - Azure Developer CLI configuration
200+
- `.env.sample` - Environment variable template
201+
202+
## Azure Deployment
203+
204+
**Deploy to Azure using azd** (NEVER CANCEL - can take 10+ minutes):
205+
```bash
206+
azd auth login
207+
azd env new
208+
azd up
209+
```
210+
211+
**Get deployment values**:
212+
```bash
213+
azd env get-values
214+
```
215+
216+
## OpenAI Configuration Options
217+
218+
The application supports multiple OpenAI providers:
219+
220+
1. **Azure OpenAI** (recommended for production):
221+
Set `OPENAI_CHAT_HOST=azure` and `OPENAI_EMBED_HOST=azure`
222+
223+
2. **OpenAI.com**:
224+
Set `OPENAI_CHAT_HOST=openai` and `OPENAI_EMBED_HOST=openai`
225+
226+
3. **Ollama** (local):
227+
Set `OPENAI_CHAT_HOST=ollama`
228+
229+
4. **GitHub Models**:
230+
Set `OPENAI_CHAT_HOST=github`
231+
232+
## Common Issues and Solutions
233+
234+
### Database Connection Issues
235+
- Verify PostgreSQL is running: `sudo service postgresql status`
236+
- Check `.env` file has correct `POSTGRES_USERNAME` and `POSTGRES_PASSWORD`
237+
- Ensure pgvector extension is installed: `sudo apt install postgresql-16-pgvector`
238+
239+
### Frontend Build Issues
240+
- Clear npm cache: `cd src/frontend && npm cache clean --force`
241+
- Delete node_modules and reinstall: `rm -rf node_modules && npm install`
242+
243+
### Azure Authentication in Local Development
244+
- Expected behavior: Chat queries will show "Azure Developer CLI could not be found" error
245+
- This is normal for local development without Azure OpenAI configured
246+
- Core application functionality (database, API endpoints, frontend) works correctly
247+
- For full chat functionality, configure Azure OpenAI or use OpenAI.com API key
248+
249+
### CI/CD Pipeline Requirements
250+
The GitHub Actions require:
251+
- Python 3.10+ with specific versions (3.10, 3.11, 3.12)
252+
- PostgreSQL with pgvector extension
253+
- Node.js 18+
254+
- All code passes `ruff check`, `ruff format --check`, and `mypy`
255+
256+
## Load Testing
257+
258+
Use locust for load testing:
259+
```bash
260+
python -m pip install locust # if not already installed
261+
locust
262+
```
263+
Open `http://localhost:8089/` and point to your running application.
264+
265+
## Available API Endpoints
266+
267+
The application provides these REST API endpoints (view full docs at `http://localhost:8000/docs`):
268+
269+
- `GET /items/{id}` - Get specific item by ID
270+
- `GET /search` - Search items with text query
271+
- `GET /similar` - Find similar items using vector search
272+
- `POST /chat` - Chat with RAG system (requires OpenAI configuration)
273+
- `POST /chat/stream` - Streaming chat responses
274+
275+
Example API usage:
276+
```bash
277+
# Get item details
278+
curl http://localhost:8000/items/1
279+
280+
# Search for tent-related items (requires OpenAI for embeddings)
281+
curl "http://localhost:8000/search?query=tent&limit=5"
282+
```
283+
284+
## Directory Reference
285+
286+
**Quick ls -la output for repository root:**
287+
```
288+
.devcontainer/ # Dev container configuration
289+
.env.sample # Environment variables template
290+
.github/ # GitHub Actions workflows
291+
.gitignore # Git ignore patterns
292+
.pre-commit-config.yaml # Pre-commit hook configuration
293+
CONTRIBUTING.md # Contribution guidelines
294+
README.md # Main project documentation
295+
azure.yaml # Azure Developer CLI configuration
296+
docs/ # Additional documentation
297+
evals/ # Evaluation scripts
298+
infra/ # Azure infrastructure templates
299+
locustfile.py # Load testing configuration
300+
pyproject.toml # Python project configuration
301+
requirements-dev.txt # Development dependencies
302+
scripts/ # Database and deployment scripts
303+
src/ # Source code (backend/ and frontend/)
304+
tests/ # Test suite
305+
```
306+
307+
## Working Effectively
308+
309+
- **Always build and test locally before committing**
310+
- **Use pre-commit hooks** - they run ruff automatically
311+
- **Check the GitHub Actions** in `.github/workflows/` for CI requirements
312+
- **Reference the full README.md** for deployment and Azure-specific details
313+
- **Use VS Code with the Python and Ruff extensions** for the best development experience
314+
- **Never skip the frontend build** - the backend serves static files from `src/backend/static/`
315+
316+
This project follows modern Python and TypeScript development practices with comprehensive tooling for code quality, testing, and deployment.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /