Merge pull request #3 from astrowq/dev/cursor

Update dependencies and add AGENTS.md for Python 3.13 compatibility

Author: astrowq

.cursor/rules/aperture-project.mdc

@@ -0,0 +1,21 @@
+---
+description: Aperture project context, stack, and code conventions
+alwaysApply: true
+---
+
+# Aperture — Project Rules
+
+**What it is:** Open-source AI visibility infrastructure. Tracks how brands appear in ChatGPT, Perplexity, and other LLM-powered search. Self-hosted, BYOK. FastAPI backend + React/TypeScript frontend.
+
+**Layout:**
+- `backend/app/` — FastAPI app: `main.py`, `database.py`, `models.py`, `schemas.py`, `routers/`, `services/` (including `services/llm/` for providers)
+- `backend/tests/` — pytest; add tests here for new backend functionality
+- `frontend/src/` — React app: `App.tsx`, `api/`, `components/`, `pages/`, `types/`
+
+**Backend (Python):** PEP 8, type hints throughout, docstrings for public functions. Small, focused functions. New LLM provider: add `backend/app/services/llm/<provider>_service.py`, wire in `audit_service.py` and `routers/audits.py`, then frontend in `Audits.tsx` and `Settings.tsx`.
+
+**Frontend (TypeScript/React):** Strict mode, functional components + hooks only, Tailwind for styling, no inline styles. Keep components focused.
+
+**Commits:** Conventional — `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`.
+
+**Run:** `docker compose up -d` (UI :3000, API :8000). Dev: backend `uvicorn app.main:app --reload`, frontend `npm run dev`. Tests: `cd backend && pytest tests/ -v`. Build check: `cd frontend && npm run build`.

.github/workflows/backend-ci.yml

@@ -0,0 +1,36 @@
+name: Backend CI
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - 'backend/**'
+      - '.github/workflows/backend-ci.yml'
+  pull_request:
+    branches: [main, master]
+    paths:
+      - 'backend/**'
+      - '.github/workflows/backend-ci.yml'
+
+defaults:
+  run:
+    working-directory: backend
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run tests
+        run: pytest tests/ -v

AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md — Context for AI Assistants
+
+**Aperture** is open-source AI visibility infrastructure: it tracks how brands appear (or don’t) across ChatGPT, Perplexity, and other LLM-powered search engines. Self-hosted, bring your own API keys.
+
+## Stack
+
+| Layer   | Tech |
+|--------|------|
+| Backend | Python 3, FastAPI, SQLAlchemy, Pydantic |
+| Frontend | TypeScript, React, Vite, Tailwind CSS |
+| Run     | Docker Compose (optional); can run backend/frontend locally |
+
+## Where to Look
+
+- **API & app entry:** `backend/app/main.py`
+- **DB models & schemas:** `backend/app/models.py`, `backend/app/schemas.py`
+- **API routes:** `backend/app/routers/` (brands, queries, audits, results, settings)
+- **Business logic:** `backend/app/services/` — `audit_service.py`, `analysis.py`, `services/llm/*.py` for each provider
+- **Tests:** `backend/tests/` (pytest)
+- **Frontend:** `frontend/src/` — `App.tsx`, `pages/`, `components/`, `api/`, `types/`
+
+## Run & Test
+
+- **Full stack:** `docker compose up -d` → UI http://localhost:3000, API http://localhost:8000
+- **Backend dev:** `cd backend && pip install -r requirements.txt && uvicorn app.main:app --reload`
+- **Frontend dev:** `cd frontend && npm install && npm run dev`
+- **Backend tests:** `cd backend && pytest tests/ -v`
+- **Frontend build:** `cd frontend && npm run build`
+
+## Conventions
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for code style (PEP 8, type hints, docstrings; TS strict, functional components, Tailwind). See [DOCS.md](DOCS.md) for architecture and configuration.

DOCS.md

@@ -157,6 +157,8 @@ Then use your custom model name in audit runs.
 
 ### Backend
 
+**Python:** 3.10–3.13. If you hit `Failed building wheel for pydantic-core` on 3.13, use 3.11 or 3.12 for the venv (e.g. `pyenv install 3.12 && pyenv local 3.12`), or upgrade to the latest `requirements.txt` which uses Pydantic 2.10+ with 3.13-compatible wheels.
+
 ```bash
 cd backend
 python -m venv .venv

backend/pyproject.toml

@@ -0,0 +1,3 @@
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

backend/requirements.txt

@@ -1,9 +1,11 @@
 fastapi==0.111.0
 uvicorn[standard]==0.30.1
-sqlalchemy==2.0.30
+# 2.0.31+ required for Python 3.13 (langhelpers/symbol/IntFlag fixes)
+sqlalchemy>=2.0.31,<2.1
 alembic==1.13.1
-pydantic==2.7.1
-pydantic-settings==2.3.0
+# Pydantic 2.10+ pulls pydantic-core with Python 3.13 wheels (2.7.x requires building from source on 3.13)
+pydantic>=2.10.0,<3
+pydantic-settings>=2.6.0,<3
 httpx==0.27.0
 openai==1.30.5
 python-multipart==0.0.9