Dev

.env.sample

@@ -1,16 +1,51 @@
-SERPER_API_KEY=
+# --- AI providers ---
 GEMINI_API_KEY=
+GEMINI_MODEL_NAME=google:gemini-3-flash-preview
 OPENAI_API_KEY=
-VERTEX_PROJECT_ID=
-VERTEX_PROJECT_LOCATION=
-MONGO_DB_CONNECTION_STRING=
+OPENAI_MODEL_NAME=openai:gpt-5.2
+SERPER_API_KEY=
+API_TIMEOUT=10
+
+# --- Auth ---
 JWT_SECRET=
-JWT_ALGORITHM=
-RATE_LIMIT=  # requests per minute
-MAX_WORKERS=  # concurrent workers
-BAN_THRESHOLD=  # violations before ban
-BAN_DURATION=  # ban duration in seconds
-
-# JWT Settings
-ACCESS_TOKEN_EXPIRE_MINUTES=
-REFRESH_TOKEN_EXPIRE_DAYS=
+JWT_ALGORITHM=HS256
+GOOGLE_CLIENT_ID=
+
+# --- App ---
+LOG_LEVEL=INFO
+ENVIRONMENT=development
+
+# --- Rate limiting / workers ---
+RATE_LIMIT=100
+MAX_WORKERS=10
+BAN_THRESHOLD=5
+BAN_DURATION=3600
+
+# --- Cache ---
+CACHE_TTL=3600
+CACHE_ENABLED=true
+CACHE_PREFIX=nawab:
+
+# --- Database ---
+POSTGRES_DB_URL=postgresql+asyncpg://user:password@localhost:5432/nawab
+REDIS_URL=redis://localhost:6379/0
+SESSION_TIMEOUT=3600
+MAX_CONTEXT_MESSAGES=20
+
+# --- Email / SMTP (OTP delivery) ---
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=
+SMTP_PASSWORD=
+SMTP_FROM=Nawab AI <noreply@example.com>
+
+# --- City / multi-persona ---
+DEFAULT_CITY_ID=lucknow
+
+# --- CORS — comma-separated list of allowed frontend origins ---
+FRONTEND_ORIGINS=http://localhost:3000,http://localhost:9001
+
+# --- Cookies ---
+# COOKIE_SECURE defaults to `ENVIRONMENT != development`; override explicitly if needed.
+COOKIE_SECURE=
+COOKIE_SAMESITE=none

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,74 @@
+name: 🐛 Bug Report
+description: Report something that isn't working as expected
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the sections below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce this?
+      placeholder: |
+        1. Go to '...'
+        2. Call endpoint / click '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened? Include error messages, logs, or screenshots.
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Node/Python version, deployment (local/staging/prod), commit/branch, etc.
+      placeholder: e.g. Ubuntu 22.04, Node 20, prod, commit abc1234
+    validations:
+      required: false
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      options:
+        - Low
+        - Medium
+        - High
+        - Critical
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Anything else relevant (related issues, workarounds tried, etc.)
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Frontend repo
+    url: https://github.com/LucknowAI/nawabAiFrontend/issues/new/choose
+    about: File a frontend-specific issue in the nawabAiFrontend repo instead.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,52 @@
+name: ✨ Feature Request
+description: Suggest an enhancement or new feature
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement! Please fill out the sections below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What problem does this solve, or what need does it address?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe what you'd like to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any alternative solutions or features you've considered.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      options:
+        - Low
+        - Medium
+        - High
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Screenshots, references, related issues, etc.
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## Summary
+
+<!-- What does this PR do and why? -->
+
+## Related issue
+
+Closes #
+
+## Changes
+
+-
+
+## How to test
+
+<!-- Steps to verify this change locally -->
+
+## Checklist
+
+- [ ] Tests added/updated (if applicable)
+- [ ] Docs updated (if applicable)
+- [ ] No breaking changes, or breaking changes called out above

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main, dev]
+  push:
+    branches: [main, dev]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install ruff
+      # Blocking: syntax errors and undefined names would break the app at
+      # runtime — these always fail the build.
+      - name: Lint (errors only, blocking)
+        run: ruff check . --select=E9,F63,F7,F82
+      # Advisory: full style/lint pass. Reported but not blocking yet, since
+      # the codebase doesn't have a ruff config/baseline established.
+      - name: Lint (full, advisory)
+        run: ruff check . || true
+
+  test:
+    runs-on: ubuntu-latest
+    env:
+      POSTGRES_DB_URL: "postgresql+asyncpg://user:pass@localhost:5432/testdb"
+      JWT_SECRET: "ci-test-secret"
+      JWT_ALGORITHM: "HS256"
+      ENVIRONMENT: "development"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Run tests
+        run: pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build Docker image
+        run: docker build -t nawabai2.0:ci .

.github/workflows/deploy-dev.yml

@@ -0,0 +1,18 @@
+name: Deploy dev to VPS
+
+on:
+  push:
+    branches: [dev]
+  workflow_dispatch: {}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy over SSH
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: ${{ secrets.DEPLOY_HOST }}
+          username: ${{ secrets.DEPLOY_USER }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          script: bash /home/sniffer/scripts/deploy/nawabai20-dev/deploy-dev.sh

.gitignore

@@ -13,6 +13,7 @@ __pycache__/
 # GCP Service Account Keys (CRITICAL - NEVER COMMIT THESE!)
 *.json
 !package.json
+!src/cities/metro/*.json
 
 # Query logs and data
 query_logs/
@@ -32,3 +33,5 @@ sample.md
 
 # Logs
 *.log
+# Added by code-review-graph
+.code-review-graph/

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to nawabAi2.0
+
+## Setup
+
+Follow [README.md](README.md#setup) to get a local instance running before making changes.
+
+## Branching & PRs
+
+- `main` is the production branch; `dev` is the integration branch auto-deployed to the dev server on every push (see [.github/workflows/deploy-dev.yml](.github/workflows/deploy-dev.yml)).
+- Branch off `dev` for new work: `git checkout -b <type>/<short-description>` (e.g. `fix/token-limit-guard`).
+- Open PRs against `dev`. Use the PR template checklist.
+- CI ([.github/workflows/ci.yml](.github/workflows/ci.yml)) runs on every PR: lint (blocking on syntax/undefined-name errors, advisory on style), `pytest`, and a Docker build sanity check. All three must pass before merge.
+- Keep commits focused; a PR that fixes a bug and refactors unrelated code makes review harder.
+
+## Code style
+
+- Python 3.12, type hints on new functions.
+- No enforced formatter yet — match the surrounding file's style (import grouping, docstring style, naming).
+- `ruff check .` runs in CI as an advisory pass; fixing warnings it raises in files you touch is welcome but not required.
+
+## Tests
+
+```bash
+pytest
+```
+
+- Tests that hit real external APIs are marked `@pytest.mark.network` and excluded by default (see [pytest.ini](pytest.ini)); CI never runs them, since they'd depend on network access and third-party quotas.
+- Add tests for new logic under `tests/`, mirroring the module path being tested (e.g. `src/utils/context_budget.py` → `tests/test_context_budget.py`).
+- Bug fixes should come with a regression test that fails before the fix and passes after.
+
+## Environment variables
+
+Copy `.env.sample` to `.env` and fill in the values documented in the README. Never commit real secrets — `.env` is gitignored.
+
+## Reporting issues
+
+Use the issue templates (bug report / feature request) so triage has what it needs: repro steps, expected vs. actual behavior, environment.