Personal Research Assistant

🤖 AI-powered research assistant built with LangChain and Streamlit, designed to plan, execute, and synthesize web research into structured reports.

Table of Contents

• Overview
• Key Features
• Tech Stack
• Getting Started
• Environment Variables
• How to Use
• Deployment
• CI/CD Pipeline
• Development Workflow
• Project Structure
• Troubleshooting
• Contributing
• License

Overview

This project uses a multi-agent workflow to:

1. Build a research plan
2. Collect relevant information from the web
3. Synthesize findings into a professional, readable report

The application is built for local usage and cloud deployment on Render.

Key Features

• Intelligent planning with LLM-assisted research decomposition
• Multi-agent execution for search and synthesis tasks
• Web research integration powered by Tavily
• Live progress updates through Streamlit
• Structured report generation for clear outcomes
• Docker + Render deployment support with GitHub Actions automation

Tech Stack

• Language: Python 3.11+
• Frameworks/Libraries: Streamlit, LangChain
• Search: Tavily API
• Model Providers: OpenRouter, Groq
• Deployment: Docker, Render
• Automation: GitHub Actions

Getting Started

Prerequisites

• Python 3.11.13 or later
• Git
• Docker (optional, for containerized local runs)

Local Setup

1. Clone the repository

   git clone <your-repo-url>
   cd personal-research-assistant

2. Create and activate a virtual environment

   # Windows (PowerShell)
   python -m venv venv
   .\venv\Scripts\Activate.ps1
   
   # macOS/Linux
   python -m venv venv
   source venv/bin/activate

3. Install dependencies

   pip install pip-tools
   pip-compile requirements.in
   pip install -r requirements.txt

4. Configure environment variables

   # macOS/Linux
   cp .env.example .env
   
   # Windows PowerShell
   Copy-Item .env.example .env

5. Run the app

   streamlit run src/main.py

6. Open: http://localhost:8501

Environment Variables

Copy .env.example to .env and set the following values:

Variable	Required	Description
OPENROUTER_API_KEY	Yes	OpenRouter API key
OPENROUTER_BASE_URL	Yes	OpenRouter base URL (default: https://openrouter.ai/api/v1)
YOUR_SITE_URL	Yes	Public URL for your deployed app
YOUR_SITE_NAME	Yes	Display name for your app
GROQ_API_KEY	Yes	Groq API key
TAVILY_API_KEY	Yes	Tavily API key

How to Use

1. Start the app with streamlit run src/main.py
2. Enter your research topic in the UI
3. Let the assistant plan and execute research tasks
4. Review the generated report in the Streamlit interface

Deployment

Option 1: Render Blueprint (Recommended)

Use the included render.yaml for infrastructure-as-code deployment.

1. Go to Render Dashboard
2. Click New → Blueprint
3. Connect your GitHub repository
4. Render will detect render.yaml
5. Set required environment variables in Render

Option 2: Manual Render Setup

1. Create a Web Service on Render
2. Connect your repository
3. Configure:
   • Environment: Docker
   • Dockerfile Path: ./Dockerfile
   • Branch: main
   • Plan: Free
4. Set all required environment variables

For full deployment walkthrough and screenshots, see RENDER_DEPLOYMENT.md.

CI/CD Pipeline

GitHub Actions workflow file: .github/workflows/ci.yml

Current pipeline includes:

• Dependency installation in a test job
• Docker image build with cache optimization
• Trivy vulnerability scan (CRITICAL, HIGH)
• Optional image push to GHCR (non-PR pushes to main/develop)
• Optional Render deployment trigger on main

Development Workflow

Code Quality Commands

ruff check . --fix
black .
isort .
pytest

Local Deployment Check

./deploy.sh

Project Structure

personal-research-assistant/
├── .github/workflows/ci.yml
├── src/
│   ├── agent/
│   ├── tools/
│   ├── ui/
│   └── main.py
├── tests/
├── .env.example
├── .pre-commit-config.yaml
├── Dockerfile
├── README.md
├── RENDER_DEPLOYMENT.md
├── deploy.sh
├── pyproject.toml
├── render.yaml
├── requirements.in
└── requirements.txt

Troubleshooting

Common Issues

1. Import or module errors

   • Ensure your virtual environment is activated
   • Reinstall dependencies with pip install -r requirements.txt

2. API key issues

   • Confirm all required variables are present in .env
   • Check for typos in variable names
   • Verify keys are active and have available quota

3. Docker build failures

   docker system prune -a
   docker build --no-cache -t research-assistant .

4. Render deployment problems

   • Verify environment variables in Render dashboard
   • Check build/deploy logs in Render
   • Ensure PORT=8501 is set where needed

Windows-Specific Quick Reference

Task	Linux/macOS	Windows PowerShell
Activate venv	source venv/bin/activate	.\venv\Scripts\Activate.ps1
Copy env file	cp .env.example .env	Copy-Item .env.example .env
Run deploy script	./deploy.sh	bash deploy.sh

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run formatting/linting/tests
5. Open a pull request with a clear description

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Built with ❤️ using LangChain, Streamlit, and modern DevOps practices.