Skip to content

Latest commit

 

History

History
172 lines (116 loc) · 7.66 KB

README.md

File metadata and controls

172 lines (116 loc) · 7.66 KB

TLOChatBot

A Next.js chat application that connects a Genkit-powered AI assistant (Google/Genkit) with a Firebase-backed knowledge base. This repository provides a polished chat UI, Genkit flows for generating and regenerating AI responses, and a seed script to upload local knowledge-base files into Firebase Storage and Firestore.

This README explains how the project is structured and gives step-by-step reproduction instructions so you can run the app locally, seed the knowledge base, and run the AI flows.

What this repo is

TLOChatBot is a Next.js (App Router) front-end for a Genkit-based conversational assistant. Key features:

  • Chat UI with message bubbles, attachments, and regenerate functionality.
  • Genkit flows that call the Google/Genkit plugin to generate responses.
  • A simple knowledge-base implementation: local files are uploaded to Firebase Storage and indexed in Firestore by the seed script.
  • Server actions (Next.js) that validate input with Zod, call Genkit flows, and return formatted responses to the UI.

Quick architecture overview

  • Next.js (app) — UI and server actions (entry at src/app/page.tsx).
  • Genkit + Google AI — configured in src/ai/genkit.ts; flows live in src/ai/flows/.
  • Firebase (client SDK) — initialization in src/lib/firebase.ts; Storage + Firestore host knowledge-base files and metadata.
  • Seed script — scripts/seed-knowledge-base.ts uploads local files to Storage and creates Firestore documents.
  • UI components — src/components/* (chat interface, input, header, message bubbles, and UI atoms under src/components/ui).

Prerequisites

  • Node.js (recommended 18+).
  • npm (or a compatible package manager).
  • A Firebase project with Firestore and Storage configured.
  • Google Cloud credentials or API key for the Google generative AI access (Gemini) if you plan to run Genkit flows that call Google.

Environment variables

Create a .env file in the repository root (do NOT commit real credentials). Example:

# Firebase web SDK configuration (from Firebase Console -> Project settings -> Your apps)
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_DATABASE_URL=https://your_project.firebaseio.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# Google / Genkit credentials (one of these approaches)
# Option 1: API key
GOOGLE_API_KEY=your_google_api_key

# Option 2: Service account JSON (recommended for server-side / admin operations)
# Set this to an absolute path on the machine where Genkit or server-side code runs
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Optional: used by local Genkit code
GENKIT_ENV=dev

Notes:

  • The app uses the client Firebase SDK; the seed script also uses the client SDK by default. For production or privileged operations, use the Firebase Admin SDK with a service account.
  • If you use GOOGLE_APPLICATION_CREDENTIALS, ensure the service account has the required permissions for the Google generative AI APIs.

Quick start (copy/paste)

  1. Install dependencies
npm install

  1. Create .env (see example above) and fill with your Firebase and Google credentials.

  2. Start the Next.js dev server (the project config sets port 9002):

npm run dev
# open http://localhost:9002
  1. (Optional) Run Genkit locally to activate flows that the server actions call:
npm run genkit:dev
  1. (Optional) Seed the knowledge base from local files in src/knowledge-base/:
npm run db:seed
  1. Interact with the chat UI in the browser and test responses.

Knowledge base seeding

Place any .txt or .docx files into src/knowledge-base/ (create that folder if required). The seed script will:

  • Read local files.
  • Upload each file to Firebase Storage under a knowledge-base/ path.
  • Create a Firestore document (collection: knowledgeBaseFiles) with metadata for each uploaded file.

Run the seed script:

npm run db:seed

Implementation notes:

  • The seed script uses the Firebase client SDK configured from NEXT_PUBLIC_... environment variables. If you encounter permission errors, either adjust Firebase Storage/Firestore rules or switch to using the Firebase Admin SDK with a service account.
  • .docx extraction uses mammoth in the flow to pull plaintext.

Genkit and AI flows

  • Configuration: src/ai/genkit.ts — sets up Genkit runtime and configures the @genkit-ai/googleai plugin.
  • Chat flow: src/ai/flows/chat-flow.ts — builds prompts, fetches knowledge-base content from Firestore + Storage, and asks the model to produce a Markdown response.
  • Regeneration: src/ai/flows/regenerate-ai-response.ts — small flow to re-evaluate or improve a previous response.

To develop or test flows locally, keep the Genkit runtime running (npm run genkit:dev). Genkit will execute the TypeScript flow definitions in src/ai/ and expose them to server actions.

Model and plugin details:

  • The repository includes @genkit-ai/googleai and defaults to a Gemini-class model in genkit.ts (e.g., googleai/gemini-2.0-flash). Change the model name in src/ai/genkit.ts if needed.

Frontend behavior and server actions

  • UI: src/components/chat-interface.tsx — wires the chat UI to server-side handlers.
  • Input + attachments: src/components/chat-input.tsx — attachments are converted to data URIs and voice input uses the Web Speech API where supported.
  • Server actions: src/lib/actions.ts — validate requests with Zod (src/lib/ai-schemas.ts), call the Genkit flows, and return structured responses.

Deployment

Recommended options:

  • Vercel: easiest for Next.js — connect the repository, set the environment variables in the dashboard, and deploy. Ensure Genkit flows are available (you may run Genkit as a separate service or adapt flows to a server environment).
  • Firebase Hosting + Cloud Run: you can build the app and serve static assets via Firebase Hosting with rewrites to Cloud Run for server-side behavior.
  • Any host: build and run with:
npm run build
npm run start

Important deployment notes:

  • Genkit flows may require a running Genkit runtime or alternate server-side integration for the model calls in production.
  • Keep credentials secure: do not store private keys or service account JSON in the repo.

File map (important files)

  • package.json — scripts and dependencies (dev port: 9002).
  • src/app/page.tsx — app entry that mounts the chat UI.
  • src/ai/genkit.ts — Genkit runtime and plugin configuration.
  • src/ai/flows/chat-flow.ts — main chat flow.
  • src/ai/flows/regenerate-ai-response.ts — regenerate flow.
  • src/lib/firebase.ts — Firebase initialization.
  • scripts/seed-knowledge-base.ts — seed script to upload local KB files.
  • src/components/chat-interface.tsx, src/components/chat-input.tsx — frontend chat behavior.

Troubleshooting

  • Error: Firebase permission denied when running db:seed — check Storage and Firestore rules or run an Admin-based seed.
  • Genkit flow errors or missing responses — ensure npm run genkit:dev is running if flows are executed locally, and check src/ai/genkit.ts for correct credentials.
  • Model authorization errors — verify GOOGLE_API_KEY or GOOGLE_APPLICATION_CREDENTIALS and their permission scopes.

Contributing

If you'd like to extend the project:

  • Add flows under src/ai/flows/ (follow Genkit flow patterns).
  • Add UI components under src/components/ or src/components/ui/.
  • Update the seed script if you want different indexing behavior or to use the Admin