home_stack/AGENTS.md

AGENTS.md

Agent guide for /home/system/home_stack.

This repository is a FastAPI + React/Vite full-stack app with Docker-based local integration. Use this as the default operating guide for coding agents working here.

Rule Sources

• No .cursor/rules/ directory was found.
• No .cursorrules file was found.
• No .github/copilot-instructions.md file was found.
• If any of those files are added later, treat them as higher-priority instructions.

Repository Layout

• backend/: FastAPI app, SQLModel models, Alembic migrations, pytest suite, backend scripts.
• frontend/: React 19 + TypeScript + Vite app, Chakra UI, TanStack Router, TanStack Query, Playwright tests.
• ai_stack/: AI inference backends (llamacpp, ollama, speaches, vllm).
• esphome/: ESPHome configuration for IoT devices.
• glance/: Glance dashboard configuration.
• notebooks/: Jupyter notebooks for AI/ML experiments (Gemma, Qwen, Whisper, Pydantic AI).
• scripts/: top-level Docker and integration scripts.
• hooks/: Copier project generation hooks.
• .github/: GitHub workflows, issue/discussion templates, dependabot config.
• docker-compose*.yml: Docker Compose configurations (base, override, traefik).
• makefile: Make commands for common tasks.
• frontend/src/client/: generated OpenAPI client; avoid manual edits.
• frontend/src/routeTree.gen.ts: generated route tree; do not hand-edit.

Toolchains

• Python: uv, Python >=3.10,<4.0.
• Node: .nvmrc pins Node 20; frontend uses npm.
• Backend quality tools: ruff, mypy, pytest, coverage.
• Frontend quality tools: biome, playwright.

Setup

Backend

Run from backend/:

uv sync
source .venv/bin/activate

Frontend

Run from frontend/:

nvm use   # or fnm use
npm install

Full stack

From repo root:

docker compose up -d --wait backend

Use Docker when you need PostgreSQL, backend container behavior, or Playwright prerequisites.

Build Commands

Frontend

• Dev server: cd frontend && npm run dev
• Production build: cd frontend && npm run build
• Preview built app: cd frontend && npm run preview

Backend

• No dedicated local build beyond dependency sync.
• Containerized dev server: docker compose watch
• Inside the backend container: fastapi run --reload app/main.py

Docker / stack

• Full Docker build script: ./scripts/build.sh
• Full Docker build via Compose: docker compose build

Lint / Format / Typecheck

Frontend

• Lint and auto-apply fixes: cd frontend && npm run lint
• Format generated client: cd frontend && npx biome format --write ./src/client
• Typecheck via build: cd frontend && npm run build

Notes:

• frontend/biome.json enables import organization.
• Biome uses spaces, double quotes, and no semicolons.
• npm run lint applies unsafe fixes; do not treat it as read-only.

Backend

• Lint + typecheck + format check: cd backend && bash scripts/lint.sh
• Auto-fix + format: cd backend && bash scripts/format.sh
• Direct commands:
  • cd backend && ruff check app
  • cd backend && ruff format app --check
  • cd backend && mypy app

Notes:

• Mypy is strict.
• Ruff excludes alembic and sorts imports.

Test Commands

Backend

• Full backend/integration flow from repo root: bash ./scripts/test.sh
• If the stack is already up: docker compose exec backend bash scripts/tests-start.sh
• Local backend test script: cd backend && bash scripts/test.sh
• Direct pytest with coverage: cd backend && coverage run --source=app -m pytest

Run a single backend test

• By file: cd backend && pytest app/tests/api/routes/test_users.py
• By file and test name: cd backend && pytest app/tests/api/routes/test_users.py -k test_get_users_superuser_me
• By node id: cd backend && pytest app/tests/api/routes/test_users.py::test_get_users_superuser_me
• In Docker with passthrough args: docker compose exec backend bash scripts/tests-start.sh app/tests/api/routes/test_users.py -k test_get_users_superuser_me

Prefer direct pytest for fast iteration and scripts/tests-start.sh when Dockerized behavior matters.

Frontend / Playwright

• Start backend stack first: docker compose up -d --wait backend
• Full suite: cd frontend && npx playwright test
• UI mode: cd frontend && npx playwright test --ui

Run a single frontend test

• Single file: cd frontend && npx playwright test tests/login.spec.ts
• Single test by title: cd frontend && npx playwright test tests/login.spec.ts --grep "login"
• Single browser project: cd frontend && npx playwright test tests/login.spec.ts --project=chromium

Code Generation

• Regenerate frontend API client from backend OpenAPI: ./scripts/generate-client.sh
• Manual client generation: cd frontend && npm run generate-client
• After backend API schema changes, regenerate frontend/src/client/ and review the diff.

Backend Style Guidelines

• Follow Ruff formatting/imports first; avoid style-only churn beyond touched code.
• Use 4-space indentation and Black/Ruff-compatible formatting.
• Prefer absolute imports from app... over relative imports.
• Group imports as standard library, third-party, then local app imports.
• Prefer built-in generics and PEP 604 unions in new code (list[str], User | None).
• Keep type hints on public functions; strict mypy makes vague typing snowball quickly.
• Use Any sparingly and only at integration boundaries.
• Prefer small helpers over long route handlers.
• Keep business logic in crud.py, helpers, or dedicated modules instead of bloating route files.
• Validate request/response shapes with Pydantic or SQLModel models rather than ad hoc dict shaping.
• Use dependency injection (Depends, SessionDep, CurrentUser) for shared resources.
• Raise HTTPException with explicit status codes and stable detail messages.
• Commit SQLModel changes explicitly with session.add(...), session.commit(), and session.refresh(...) when needed.
• Keep route docstrings brief and action-oriented.
• Tests use plain pytest functions named test_*; mirror existing naming.

Frontend Style Guidelines

• Let Biome control formatting; normalize touched legacy files when practical.
• Prefer functional React components and hooks.
• Prefer TypeScript types on props, query results, and form payloads.
• Avoid any; use generated API types from @/client when available.
• Use the @/ path alias for imports from src/.
• Keep imports organized; Biome will reorder them.
• Use double quotes and omit semicolons.
• Keep route definitions next to page components with createFileRoute(...).
• Prefer route-local schemas/helpers unless broadly reused.
• Use TanStack Query for server state and invalidation instead of manual fetch state.
• Keep auth token reads/writes consistent with the existing localStorage flow.
• Prefer Chakra UI primitives and existing wrappers in frontend/src/components/ui/.
• Reuse existing hooks like useAuth and useCustomToast before adding abstractions.
• Surface async errors through shared helpers such as handleError and the toast flow.
• For forms, follow the existing react-hook-form pattern and validation helpers in frontend/src/utils.ts.

Naming Conventions

• Python: snake_case for functions/variables/modules, PascalCase for classes, UPPER_SNAKE_CASE for constants.
• React components: PascalCase filenames and component names.
• Hooks: useSomething.
• Backend tests: test_*.py.
• Frontend tests: *.spec.ts; setup files use *.setup.ts.

Error Handling Guidance

• Preserve user-visible API error messages unless there is a clear improvement reason.
• Prefer guard clauses over deeply nested conditionals.
• In backend routes, map expected failures to 4xx and upstream/service failures to 5xx or 503.
• In frontend UI flows, surface errors through the existing toast/error helper patterns.
• Avoid bare except blocks; catch specific exceptions.

Agent Working Agreements

• Check for generated files before editing; prefer source-of-truth files.
• Do not hand-edit generated client code unless the task explicitly requires it.
• When changing backend endpoints or schemas, consider whether ./scripts/generate-client.sh should be run.
• Favor the smallest coherent change that matches surrounding conventions.