From 18e570a0a63157be81551a7fc5cf392d766e8e02 Mon Sep 17 00:00:00 2001 From: Yenchi Lin Date: Sat, 14 Feb 2026 13:35:09 -0800 Subject: [PATCH] chore: add repository guidelines and pin google-adk --- AGENTS.md | 38 +++++++++++++++++++++++++++++++++++++ src/python/requirements.txt | 2 +- 2 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..75d628b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,38 @@ +# Repository Guidelines + +## Project Structure & Module Organization +- `src/python/role_play/` contains backend domains: `chat/`, `server/`, `common/`, `evaluation/`, `voice/`, and `dev_agents/`. +- `src/python/run_server.py` is the local backend entrypoint. +- `src/ts/role_play/ui/` is the Vue 3 + TypeScript frontend (`components/`, `services/`, `types/`, `locales/`). +- `test/python/unit/` and `test/python/integration/` hold backend tests; shared fixtures live in `test/python/fixtures/`. +- `data/resources/` stores scenario/character/script JSON content; environment settings live in `config/{dev,beta,prod}.yaml`; project utilities are in `scripts/`. +- Keep backend models and frontend API types aligned (Pydantic models in Python should be reflected in `src/ts/role_play/ui/src/types/`). + +## Build, Test, and Development Commands +- `make dev-setup`: create/recreate `venv`, install Python dependencies, validate resources, and sync resource data. +- `source venv/bin/activate && JWT_SECRET_KEY=dev-secret python src/python/run_server.py`: run backend locally. +- `cd src/ts/role_play/ui && npm install && npm run dev`: run frontend (Vite dev server). +- `make test`: full Python suite with coverage (`--cov-fail-under=25`). +- `make test-unit` / `make test-integration`: targeted backend suites. +- `make validate-resources` and `make update-resource-metadata`: validate and maintain resource JSON metadata. +- `make run-local-docker DATA_DIR=./data_local`: build and run local Docker setup. + +## Coding Style & Naming Conventions +- Python: 4-space indentation, type hints on public interfaces, `snake_case` functions/modules, `PascalCase` classes. +- Backend handlers are stateless: avoid request state in instance/global variables; prefer dependency injection via FastAPI `Depends(...)`. +- Storage keys are extension-free and user-scoped (for example, `users/{user_id}/profile`, not `users/{user_id}.json`). +- Vue/TypeScript: `PascalCase` for component files (for example, `ChatWindow.vue`), `use*` prefix for composables, `*Api.ts` for API service modules. +- Run formatting/type checks before submitting backend changes: `black`, `isort`, and `mypy` (listed in `src/python/requirements-dev.txt`). + +## Testing Guidelines +- Pytest settings are defined in `pytest.ini` (`test_*.py`, `Test*`, `test_*` discovery patterns). +- Place isolated behavior tests in `test/python/unit/`; place cross-module/storage/auth flows in `test/python/integration/`. +- Follow naming patterns used across the tree: `test_.py` files and descriptive `test___()` functions. +- Use markers (`unit`, `integration`, `auth`, `storage`, `slow`) to narrow local runs during development. +- For backend PRs, run affected tests at minimum; use `make test` before merge for broad regressions. + +## Commit & Pull Request Guidelines +- Follow existing commit style: Conventional Commit-like subjects such as `fix(makefile): ...`, `feat(voice): ...`, or `fix: ...`. +- Keep commits focused; reference issue/PR IDs when applicable (for example, `(#53)`). +- PRs should include scope, behavior impact, and verification commands run; add screenshots for UI changes. +- Ensure relevant GitHub checks pass: Python Unit Tests on PRs, plus Make Dry Run when touching Makefile/build/deploy paths. diff --git a/src/python/requirements.txt b/src/python/requirements.txt index a1badf2..aa08fa2 100644 --- a/src/python/requirements.txt +++ b/src/python/requirements.txt @@ -1,4 +1,4 @@ -google-adk +google-adk==1.25.0 openai pydantic[email] langchain