CLAUDE.md

Welcome to the Tenant First Aid repository. This file contains the main points for new contributors.

Repository overview

• Source code: see Architecture.md for code organization
• Tests: see Architecture.md for test organization and README.md for backend quality check flows/commands; see frontend-builds job in pr-checks for frontend commands
• Documentation: see Architecture.md for architectural documentation
• Utilities: developer commands are defined in the Makefile.
• PR template: pull_request_template.md describes the information every PR must include.

Local ./backend workflow

1. Format, lint and type‑check your changes:

   make fmt
   make lint
   make typecheck

2. Run the tests:

   make test

   To run a single test, use uv run pytest -s -k <test_name>.

3. Coverage can be generated with (optional but recommended for code changes):

   make test TEST_OPTIONS="--cov tenantfirstaid --cov-report html --cov-branch"

All python commands should be run via uv run python ...

LangChain Agent Architecture

The backend uses LangChain 1.0.8+ for agent-based conversation management with Vertex AI integration.

Key Components

• LangChainChatManager: Main agent orchestration class (backend/tenantfirstaid/langchain_chat.py)
• retrieve_city_law: Tool for city-specific legal retrieval
• retrieve_state_law: Tool for state-wide legal retrieval
• ChatVertexAI: LangChain wrapper for Google Gemini 2.5 Pro

Environment Variables

MODEL_NAME=gemini-2.5-pro              # LLM model name
VERTEX_AI_DATASTORE=projects/.../datastores/...  # RAG corpus ID
SHOW_MODEL_THINKING=false              # Enable Gemini thinking mode
LANGSMITH_API_KEY=...                  # Optional: Enable tracing
LANGSMITH_PROJECT=tenant-first-aid     # Optional: LangSmith project name

Testing LangChain Components

# Run LangChain-specific tests
uv run pytest -k langchain

# Run with LangSmith tracing (requires API key)
LANGSMITH_TRACING=true uv run pytest -k langchain

# Run evaluations (see docs/EVALUATION.md)
uv run python scripts/run_langsmith_evaluation.py --num-samples 20

Local ./frontend workflow

1. Format, lint and type‑check your changes:

   npm run lint
   npx run format

2. Build frontend code

   npm run build

3. Test frontend code

   npm run test -- --run

4. Test Coverage can be generated with (optional but recommended for code changes):

   npm run test -- --run --coverage

Style notes

• Write comments as full sentences and end them with a period.

Pull request expectations

PRs should use the template located at pull_request_template.md. Provide a summary, test plan and issue number if applicable, then check that:

• for frontend, backend and backend/scripts
  • New tests are added when needed.
  • Documentation is updated.
  • make lint and make format have been run.
  • The full test suite passes.

Commit Messages

Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.

Write commit messages and PR descriptions as a humble but experienced engineer would. Keep it casual, avoid listicles, briefly describe what we're doing and highlight non-obvious implementation choices but don't overthink it.

Don't embarrass me with robot speak, marketing buzzwords, or vague fluff. Just leave a meaningful trace so someone can understand the choices later. Assume the reader is able to follow the code perfectly fine.

What reviewers look for

• Tests covering new behaviour.
• Consistent style: code formatted with uv run ruff format, imports sorted, and type hints passing make typecheck.
• Clear documentation for any public API changes.
• Clean history and a helpful PR description.