Skip to content

Commit 29cc809

Browse files
ajaysharmadeveloperclaude
ajaysharmadeveloper
and
claude
committed
Initial release — PiperQL v1.0.0
Open-source AI database agent that lets you talk to PostgreSQL databases in plain English. Ask questions, get direct answers, auto-generated charts, and safe write operations with confirmation. Stack: FastAPI + LangGraph + Next.js + PostgreSQL License: AGPL-3.0 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
0 parents  commit 29cc809

87 files changed

Lines changed: 14549 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.dockerignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
backend/.venv/
2+
backend/__pycache__/
3+
backend/.env
4+
frontend/node_modules/
5+
frontend/.next/
6+
frontend/.env.local
7+
.git/
8+
*.pyc

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Auto detect text files and perform LF normalization
2+
* text=auto

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug to help us improve PiperQL
4+
title: '[Bug] '
5+
labels: bug
6+
---
7+
8+
## Describe the Bug
9+
10+
A clear description of what the bug is.
11+
12+
## Steps to Reproduce
13+
14+
1. Go to '...'
15+
2. Click on '...'
16+
3. See error
17+
18+
## Expected Behavior
19+
20+
What you expected to happen.
21+
22+
## Actual Behavior
23+
24+
What actually happened.
25+
26+
## Screenshots
27+
28+
If applicable, add screenshots.
29+
30+
## Environment
31+
32+
- OS: [e.g., macOS 15, Ubuntu 24.04]
33+
- Browser: [e.g., Chrome 120]
34+
- PiperQL version: [e.g., v0.1.0]
35+
- Deployment: [Docker / Manual]

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
name: Feature Request
3+
about: Suggest a feature for PiperQL
4+
title: '[Feature] '
5+
labels: enhancement
6+
---
7+
8+
## Problem
9+
10+
What problem does this feature solve?
11+
12+
## Proposed Solution
13+
14+
How should it work?
15+
16+
## Alternatives Considered
17+
18+
Any alternative solutions you've thought about.
19+
20+
## Additional Context
21+
22+
Any other context, screenshots, or examples.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## What does this PR do?
2+
3+
Brief description of the changes.
4+
5+
## Related Issue
6+
7+
Fixes #(issue number)
8+
9+
## Checklist
10+
11+
- [ ] I've tested my changes locally
12+
- [ ] I've followed the project's code style
13+
- [ ] I've updated documentation if needed
14+
- [ ] All existing tests pass (`make test`)

‎.github/workflows/ci.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
backend:
11+
name: Backend Tests
12+
runs-on: ubuntu-latest
13+
14+
services:
15+
postgres:
16+
image: postgres:16
17+
env:
18+
POSTGRES_USER: postgres
19+
POSTGRES_PASSWORD: postgres
20+
POSTGRES_DB: test_db
21+
ports:
22+
- 5432:5432
23+
options: >-
24+
--health-cmd pg_isready
25+
--health-interval 10s
26+
--health-timeout 5s
27+
--health-retries 5
28+
29+
steps:
30+
- uses: actions/checkout@v4
31+
32+
- name: Set up Python 3.12
33+
uses: actions/setup-python@v5
34+
with:
35+
python-version: '3.12'
36+
37+
- name: Install dependencies
38+
run: |
39+
cd backend
40+
pip install -r requirements.txt
41+
42+
- name: Run tests
43+
env:
44+
APP_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
45+
JWT_SECRET: test-secret-key
46+
run: |
47+
cd backend
48+
python -m pytest tests/ -v
49+
50+
frontend:
51+
name: Frontend Build
52+
runs-on: ubuntu-latest
53+
54+
steps:
55+
- uses: actions/checkout@v4
56+
57+
- name: Set up Node.js 20
58+
uses: actions/setup-node@v4
59+
with:
60+
node-version: '20'
61+
cache: 'npm'
62+
cache-dependency-path: frontend/package-lock.json
63+
64+
- name: Install dependencies
65+
run: |
66+
cd frontend
67+
npm ci
68+
69+
- name: Build
70+
env:
71+
NEXT_PUBLIC_API_URL: http://localhost:8000
72+
run: |
73+
cd frontend
74+
npm run build

‎.gitignore‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# ============================================
2+
# Python / Backend
3+
# ============================================
4+
__pycache__/
5+
*.py[cod]
6+
*.pyo
7+
*.egg-info/
8+
*.egg
9+
dist/
10+
build/
11+
*.whl
12+
backend/.venv/
13+
.pytest_cache/
14+
.mypy_cache/
15+
.ruff_cache/
16+
htmlcov/
17+
.coverage
18+
19+
# ============================================
20+
# Node / Frontend
21+
# ============================================
22+
node_modules/
23+
frontend/.next/
24+
frontend/out/
25+
frontend/build/
26+
.pnp.*
27+
.yarn/*
28+
!.yarn/patches
29+
!.yarn/plugins
30+
!.yarn/releases
31+
!.yarn/versions
32+
*.tsbuildinfo
33+
next-env.d.ts
34+
35+
# ============================================
36+
# Environment & Secrets
37+
# ============================================
38+
.env
39+
.env.*
40+
!.env.example
41+
!.env.local.example
42+
backend/.env
43+
frontend/.env.local
44+
45+
# ============================================
46+
# Superpowers (brainstorming artifacts)
47+
# ============================================
48+
.superpowers/
49+
50+
# ============================================
51+
# IDE & OS
52+
# ============================================
53+
.DS_Store
54+
Thumbs.db
55+
.vscode/
56+
.idea/
57+
*.swp
58+
*.swo
59+
*~
60+
61+
# ============================================
62+
# Logs & Debug
63+
# ============================================
64+
*.log
65+
npm-debug.log*
66+
yarn-debug.log*
67+
yarn-error.log*
68+
.pnpm-debug.log*
69+
70+
# ============================================
71+
# Misc
72+
# ============================================
73+
*.pem
74+
.vercel
75+
.benchmarks/

‎CODE_OF_CONDUCT.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to a positive environment:
15+
16+
* Using welcoming and inclusive language
17+
* Being respectful of differing viewpoints and experiences
18+
* Gracefully accepting constructive criticism
19+
* Focusing on what is best for the community
20+
* Showing empathy towards other community members
21+
22+
Examples of unacceptable behavior:
23+
24+
* The use of sexualized language or imagery, and sexual attention or advances of any kind
25+
* Trolling, insulting or derogatory comments, and personal or political attacks
26+
* Public or private harassment
27+
* Publishing others' private information without explicit permission
28+
* Other conduct which could reasonably be considered inappropriate in a professional setting
29+
30+
## Enforcement
31+
32+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
33+
reported by opening an issue at https://github.com/ajaysharmadeveloper/piperql/issues.
34+
35+
All complaints will be reviewed and investigated promptly and fairly.
36+
37+
## Attribution
38+
39+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

‎CONTRIBUTING.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Contributing to PiperQL
2+
3+
Thank you for your interest in contributing to PiperQL! This guide will help you get started.
4+
5+
## How to Contribute
6+
7+
### Reporting Bugs
8+
9+
1. Check [existing issues](https://github.com/ajaysharmadeveloper/piperql/issues) to avoid duplicates
10+
2. Open a new issue using the bug report template
11+
3. Include steps to reproduce, expected behavior, and actual behavior
12+
13+
### Suggesting Features
14+
15+
1. Check [existing issues](https://github.com/ajaysharmadeveloper/piperql/issues) for similar requests
16+
2. Open a new issue using the feature request template
17+
3. Describe the problem your feature would solve
18+
19+
### Submitting Code
20+
21+
1. Fork the repository
22+
2. Create a feature branch from `main`:
23+
```bash
24+
git checkout -b feature/your-feature-name
25+
```
26+
3. Make your changes
27+
4. Run tests:
28+
```bash
29+
make test
30+
```
31+
5. Commit with a clear message:
32+
```bash
33+
git commit -m "feat: add your feature description"
34+
```
35+
6. Push and open a Pull Request
36+
37+
### Commit Message Convention
38+
39+
We follow [Conventional Commits](https://www.conventionalcommits.org/):
40+
41+
- `feat:` — new feature
42+
- `fix:` — bug fix
43+
- `docs:` — documentation changes
44+
- `chore:` — maintenance tasks
45+
- `refactor:` — code refactoring
46+
- `test:` — adding or updating tests
47+
48+
## Development Setup
49+
50+
```bash
51+
# Clone your fork
52+
git clone https://github.com/YOUR_USERNAME/piperql.git
53+
cd piperql
54+
55+
# Install dependencies
56+
make install
57+
58+
# Set up environment
59+
cp backend/.env.example backend/.env
60+
cp frontend/.env.local.example frontend/.env.local
61+
# Edit with your settings
62+
63+
# Run migrations
64+
make migrate
65+
66+
# Start development
67+
make run
68+
```
69+
70+
## Project Structure
71+
72+
- `frontend/` — Next.js app (TypeScript, Tailwind CSS)
73+
- `backend/` — FastAPI backend (Python)
74+
- `backend/app/agent/` — LangGraph AI agent
75+
- `backend/app/routers/` — API routes
76+
- `backend/app/models/` — SQLAlchemy models
77+
- `backend/app/schemas/` — Pydantic schemas
78+
79+
## Code Style
80+
81+
- **Python:** Follow PEP 8
82+
- **TypeScript:** Follow the existing ESLint config
83+
- **General:** Keep changes focused and minimal
84+
85+
## Questions?
86+
87+
Open an issue or reach out to [@ajaysharmadeveloper](https://github.com/ajaysharmadeveloper).

‎Dockerfile‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
FROM python:3.12-slim AS backend
2+
3+
WORKDIR /app/backend
4+
5+
RUN apt-get update && apt-get install -y --no-install-recommends \
6+
gcc libpq-dev curl && \
7+
curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
8+
apt-get install -y nodejs && \
9+
rm -rf /var/lib/apt/lists/*
10+
11+
COPY backend/requirements.txt .
12+
RUN pip install --no-cache-dir -r requirements.txt
13+
14+
COPY backend/ .
15+
16+
WORKDIR /app/frontend
17+
COPY frontend/package.json frontend/package-lock.json ./
18+
RUN npm ci
19+
COPY frontend/ .
20+
RUN npm run build
21+
22+
WORKDIR /app
23+
COPY start.sh .
24+
RUN chmod +x start.sh
25+
26+
EXPOSE 8000 3000
27+
28+
CMD ["./start.sh"]

0 commit comments

Comments
 (0)