Rx Assistant – Developer Manual

1. Project Overview

Rx Assistant is a Streamlit-based AI chatbot platform built to support domain-specific conversations. It includes:

• Multiple knowledge agents (personas) with assigned knowledge bases (KBs)
• Semantic search using pgvector and LLMs (Gemini, OpenRouter, Groq)
• File-based KB ingestion: PDF, DOCX, TXT, CSV, JSON
• User/Admin authentication with session management
• PostgreSQL-backed storage with vector search
• Full chat and feedback logging

---

2. Getting Started

Prerequisites

• Python 3.9+
• PostgreSQL 14+ with vector extension enabled
• API keys for:
  • Google Gemini
  • OpenRouter
  • Groq
• .env file with credentials

Quickstart

# 1. Clone the repo
git clone https://github.com/your-org/rx-assistant.git
cd CHATBOT


# 2. Install dependencies
pip install -r requirements.txt

# 3. Set up environment variables
cp .env.example .env  # then edit the .env file

# 4. Apply PostgreSQL schema
psql -U youruser -d yourdb -f database-schema.txt

# 5. Run the app
streamlit run app.py


## 3. Project Structure

| File                  | Description                                                   |
|-----------------------|---------------------------------------------------------------|
| `app.py`              | Entry point: handles routing, role check, auth                |
| `admin.py`            | Admin panel for KB upload, activation, agents, feedback       |
| `auth.py`             | Signup/login system and token-based session management        |
| `chatbot.py`          | User-facing chatbot interface and feedback UI                 |
| `chatbot_core.py`     | Main backend: embeddings, semantic search, DB logic           |
| `llm_providers.py`    | Unified API interface for Gemini, OpenRouter, and Groq        |
| `database-schema.txt` | Full PostgreSQL schema with tables, roles, indexes            |
| `requirements.txt`    | Python packages needed for the project                        |

---

## 4. Database Schema (PostgreSQL)

### Key Tables

- **knowledge_bases**: Info about uploaded KBs  
- **kb_chunks**: KB content chunks and vector embeddings  
- **active_kb**: Tracks which KB is currently used  
- **knowledge_agents**: Defines chatbot personas  
- **agent_knowledge_bases**: Agent-KB many-to-many relationship  
- **users, roles**: User auth and role management  
- **sessions**: Token-based session tracking  
- **chat_sessions, chat_messages**: Chat history logs  
- **chat_feedback**: User feedback (thumbs up/down + comments)

 **Run all commands in `database-schema.txt` to set up the database.**

---

## 5. Module Breakdown

### `app.py`

- `main()` – Initializes app, handles user roles, login/logout, and loads either the admin panel or chatbot UI.

### `admin.py`

- `AdminPanel()` – Main admin interface with:
  - Upload KBs (`upload_knowledge_base`)
  - Activate KBs (`manage_active_kb`)
  - Manage Agents (`manage_knowledge_agents`)
  - Feedback Analytics (`feedback_analytics`)
  - View/Delete KBs (`view_knowledge_bases`)

### `auth.py`

- `AuthSystem` – Handles password hashing, session tokens, login/register  
- `show_auth_forms()` – Renders login/signup UI in Streamlit

### `chatbot.py`

- `MedicalChatbotUI()` – Chat UI with model/agent selection, full chat history, and feedback buttons:
  - `handle_user_input()`
  - `display_chat_messages()`
  - `handle_feedback()`

### `chatbot_core.py`

- `ChatbotCore` – Backend engine for:
  - Semantic vector search (`semantic_search`)
  - LLM interaction (`generate_response`)
  - Chat session, feedback, message DB ops
  - Agent-KB validation and chunk retrieval

### `llm_providers.py`

- `LLMProvider` – Wrapper for different LLM APIs:
  - `get_embedding(text)`
  - `generate_response(prompt)`
  - Supports Gemini, OpenRouter, Groq

---

##  6. Workflow Overview

1. Admin uploads documents as KBs (PDF, DOCX, TXT, etc.)
2. Extracted text is chunked and embedded
3. KB is activated and linked to knowledge agents (personas)
4. Users chat with selected agent and LLM
5. User input → embed → semantic search → prompt LLM
6. Response shows sources (chunk IDs or snippets)

![Rx Assistant Flowchart](assets/flowchart.png)
---

## 7. Example `.env` File

```env
PG_HOST=localhost
PG_PORT=5432
PG_DB=rxassistant
PG_USER=postgres
PG_PASSWORD=yourpassword

GOOGLE_API_KEY=your-gemini-key
OPENROUTER_API_KEY=your-openrouter-key
GROQ_API_KEY=your-groq-key