Tenant First Aid

A chatbot that provides legal information related to housing and eviction in Oregon.

Live at https://tenantfirstaid.com/

Local Development

Prerequisites

GitHub account

• You will need a GitHub account (free) to contribute to the project. No account is necessary to browse the source code.
  • You will be invited to join the Contributor team after you complete step 2 ("Connect on Discord & Request Access") of the Code PDX onboarding
  • Look for the invitation email and click the link in the email to accept the invitation.
  • You will also have to enable commit signing by adding a key (typically GPG) to your GitHub account (click on your avatar -> Settings -> SSH and GPG keys).

Astral UV

• uv is used in the backend to install/manage Python dependencies and run Python sub-tools (e.g. pytest) Install uv

Google Cloud application default credentials file

• This is needed to spin up a local instance of the backend (i.e. API calls to the chat LLM and RAG agent).
• The chatbot now uses Google Gemini (previously OpenAI's ChatGPT).
• The tenantfirstaid Google project admin will need to manually assign a role to you (gmail account). Reach out in the Discord channel #tenantfirstaid-general to arrange this.
• You need to authenticate with the gcloud cli to develop, following these instructions:
  1. install gcloud
  2. generate application default credentials file
  3. gcloud auth application-default login
  4. gcloud auth application-default set-quota-project tenantfirstaid
  5. add GOOGLE_APPLICATION_CREDENTIALS=<PATH_TO_CREDS> to your backend/.env file. The default path will be something like /home/<USERNAME>/.config/gcloud/application_default_credentials.json on Unix systems. (HINT: don't use path shortcuts like ~ for home, python won't be able to find it).

LangChain/LangSmith

• langsmith Developer (free) or Plus account and API key

Quick Start

1. clone repo
2. copy backend/.env.example to a new file named .env in the same directory.
   1. set GOOGLE_APPLICATION_CREDENTIALS as per Google Cloud application default credentials file
   2. set LANGSMITH_API_KEY as per LangChain/LangSmith
3. cd backend
4. uv sync
5. uv run python -m tenantfirstaid.app
6. Open a new terminal / tab
7. cd ../frontend
8. npm install
9. npm run generate-types
10. npm run dev
11. Go to http://localhost:5173
12. Start chatting

Backend Development & Checks

1. change to the backend/ directory

   % cd backend

• run individual checks

  1. format Python code with ruff

     % uv run ruff format

     or

     % make fmt

  2. lint Python code with ruff

     % uv run ruff check

     or

     % make lint

  3. typecheck Python code with ty

     % uv run ty check

     or

     % make typecheck

     typecheck with other Python typecheckers which are not protected in PR Checks - useful for completeness & a 2nd opinion

     1. typecheck Python code with mypy

        % uv run mypy -p tenantfirstaid --python-executable .venv/bin/python3 --check-untyped-defs

        or

        % make typecheck-mypy

     2. typecheck Python code with pyrefly

        % uv run pyrefly check --python-interpreter .venv/bin/python3

        or

        % make typecheck-pyrefly

  4. test Python code with pytest

     % uv run pytest

     or

     % make test

• or run the above checks in one-shot

  % make --keep-going check

  --keep-going will continue to run checks, even if previous make rule fail. Omit if you want to stop after the first make rule fails.

Frontend Development & Checks

1. change to the frontend/ directory

   % cd frontend

2. generate TypeScript types from backend models (required before type-checking or building)

   % npm run generate-types

   This writes src/types/models.ts from the backend Pydantic models (gitignored). Non-generated frontend types are stored in src/shared/types/ and are checked into source control.

• run individual checks

  1. lint TypeScript code with eslint

     % npm run lint

  2. typecheck TypeScript code with tsc

     % npm run typecheck

  3. test TypeScript code with vitest

     % npm run test -- --run

Contributing

We currently have regular project meetups: https://www.meetup.com/codepdx/ . Also check out https://www.codepdx.org/ to find our Discord server.

Deployment

For information on how the application is deployed, where it runs, how to debug issues, and who has access, see Deployment.md.