Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
app
app
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
requirements.txt
requirements.txt
 
 
run.py
run.py
 
 

Repository files navigation

QuickAnswer Serper Agent

A streaming AI web-search assistant powered by Groq, LangChain, LangGraph memory, and Streamlit

Overview

QuickAnswer Serper Agent is a lightweight, modular AI question-answering application that combines an LLM, live Google search, short-term conversational memory, and a clean Streamlit chat interface.

The project is designed to answer user queries by intelligently deciding when to use web search via the Google Serper API, then generating concise, context-aware responses using a Groq-hosted LLM. It supports streaming responses, thread-based memory, and a clean modular architecture that makes the repository easy to maintain, extend, and showcase.

This repository is built to look and feel like a real-world production-oriented AI application rather than a single-file prototype.

Why This Project Matters

Traditional chatbot demos often fail in two important ways:

  • they rely only on the LLM's static knowledge
  • they are written as monolithic scripts that are hard to scale or maintain

This project addresses both issues by:

  • integrating real-time web search for fresher answers
  • using LangGraph checkpointer-based memory for multi-turn interactions
  • implementing a modular architecture with clear separation of concerns
  • providing a streaming chat UI for a more natural user experience

It is especially useful as a portfolio project for demonstrating practical skills in:

  • LLM application engineering
  • tool-augmented agents
  • memory-aware AI workflows
  • Streamlit-based product prototyping
  • clean Python project organization

Features

  • LLM-powered conversational assistant
  • Google Serper web search integration
  • LangGraph short-term memory with thread-based context
  • Streaming token-by-token responses
  • Modular production-style codebase
  • Reusable service and UI components
  • Environment-based configuration
  • GitHub-ready clean project structure
  • Easy extension for more tools, persistent memory, or deployment

Tech Stack

Core Technologies

  • Python
  • Streamlit
  • LangChain
  • LangGraph
  • Groq API
  • Google Serper API

Supporting Libraries

  • langchain-groq
  • langchain-community
  • pydantic-settings
  • python-dotenv

Architecture / Workflow

The system follows a modular agent-driven workflow:

  1. The user enters a question in the Streamlit chat UI.
  2. The request is passed to the chat service layer.
  3. The agent receives the user message along with a thread_id.
  4. The LLM decides whether a web search is needed.
  5. If required, the agent uses the Google Serper search tool.
  6. Search results are passed back to the LLM.
  7. The LLM generates a concise final answer.
  8. The answer is streamed back to the UI token by token.
  9. The conversation context is stored in memory for follow-up queries.

High-Level Flow

User Query
   ↓
Streamlit UI
   ↓
Chat Service
   ↓
Agent Builder
   ↓
LLM + Search Tool + Memory
   ↓
Streaming Response
   ↓
Chat UI Rendering

System Design Notes

This project is intentionally structured in a modular way to support future growth.

Core Modules

  • LLM Layer: initializes the Groq chat model
  • Tool Layer: exposes Google Serper as an agent tool
  • Memory Layer: manages thread-based conversational memory
  • Prompt Layer: defines the system behavior and response rules
  • Agent Builder: combines model, tools, prompt, and memory
  • Service Layer: orchestrates streaming responses
  • UI Layer: handles Streamlit rendering and chat state

Current Design Choice

This project currently uses in-memory checkpointing for simplicity and fast local development. For production, this can be replaced with a persistent backend such as PostgreSQL or another supported storage layer.

Project Structure

quickanswer-serper-agent/
├── app/
│   ├── main.py                 # Streamlit entrypoint
│   ├── __init__.py
│   ├── config/
│   │   ├── __init__.py
│   │   └── settings.py         # Environment variables and app config
│   ├── agent/
│   │   ├── __init__.py
│   │   ├── llm.py              # ChatGroq initialization
│   │   ├── toolkit.py          # Google Serper search tool
│   │   ├── memory.py           # Checkpointer and thread memory
│   │   ├── prompt.py           # System prompt
│   │   └── builder.py          # Agent construction
│   ├── services/
│   │   ├── __init__.py
│   │   └── chat_service.py     # Streaming response orchestration
│   ├── ui/
│   │   ├── __init__.py
│   │   └── components.py       # Reusable Streamlit UI components
│   └── utils/
│       ├── __init__.py
│       └── logger.py           # Logging utility
├── .env
├── .env.example
├── .gitignore
├── requirements.txt
├── README.md
└── run.py                      # Optional launcher

Installation

1. Clone the repository

git clone https://github.com/[YOUR_GITHUB_USERNAME]/[YOUR_REPOSITORY_NAME].git
cd [YOUR_REPOSITORY_NAME]

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 -r requirements.txt

4. Configure environment variables

Create a .env file in the project root:

GROQ_API_KEY=your_groq_api_key
SERPER_API_KEY=your_serper_api_key
MODEL_NAME=openai/gpt-oss-20b
APP_TITLE=QuickAnswer - Q&A Bot with Google Serper API
APP_DESCRIPTION=Ask any question and the bot will use Google Serper to search the web.

You can also copy from the example file:

cp .env.example .env

On Windows, create .env manually if needed.

Usage

Run the application

streamlit run app/main.py

Or:

streamlit run run.py

What you can ask

  • factual questions that benefit from live web search
  • follow-up questions that depend on previous conversation context
  • short knowledge queries requiring concise answers

Example interaction

User: Who won the FIFA World Cup in 2022?
Assistant: Argentina won the 2022 FIFA World Cup.

User: Who was the captain?
Assistant: Lionel Messi was the captain of Argentina.

Modules and Responsibilities

app/main.py

Streamlit application entrypoint. Initializes session state, loads the agent, renders chat history, and handles user input.

app/config/settings.py

Loads environment variables and centralizes runtime configuration such as API keys, model name, and UI labels.

app/agent/llm.py

Initializes the Groq LLM client used by the agent.

app/agent/toolkit.py

Defines the Google Serper search tool exposed to the agent.

app/agent/memory.py

Manages checkpointer-based thread memory for multi-turn chat.

app/agent/prompt.py

Contains the system prompt that controls assistant behavior.

app/agent/builder.py

Creates the final agent by combining the model, tools, prompt, and memory.

app/services/chat_service.py

Streams the final assistant response and filters internal tool messages from the UI.

app/ui/components.py

Contains reusable Streamlit components for chat rendering and layout.

app/utils/logger.py

Provides basic logging support for debugging and visibility.

Example Output / Results

Example 1

Input

What is the capital of Japan?

Output

Tokyo is the capital of Japan.

Example 2

Input

Who won the most recent Ballon d'Or?

Output

[Example output here based on live search results]

Example 3

Input

Did he win the World Cup too?

Output

[Context-aware follow-up answer using memory]

Configuration

Required Environment Variables

Variable Description
GROQ_API_KEY API key for Groq model access
SERPER_API_KEY API key for Google Serper search
MODEL_NAME LLM model name
APP_TITLE UI title shown in Streamlit
APP_DESCRIPTION Short app description in the UI

Deployment Notes

This project currently targets local development and portfolio demonstration.

Recommended future deployment options

  • Streamlit Community Cloud
  • Render
  • Railway
  • Dockerized VPS deployment
  • Hugging Face Spaces with UI adaptation if needed

Before deployment

  • move from in-memory memory to persistent storage
  • add structured error handling
  • improve observability and tracing
  • secure secrets through environment-based deployment configuration

Roadmap

  • Add persistent memory backend
  • Add citation-style answer formatting
  • Add tool usage logging and monitoring
  • Add source links in the final response
  • Add conversation export feature
  • Add multi-tool support beyond Google search
  • Add authentication and user-based chat sessions
  • Containerize with Docker
  • Deploy public demo

Contributing

Contributions are welcome.

If you would like to improve the project:

  1. Fork the repository
  2. Create a new feature branch
  3. Make your changes
  4. Commit with a clear message
  5. Open a pull request

Example:

git checkout -b feature/improve-streaming
git commit -m "Improve streaming response handling"
git push origin feature/improve-streaming

Repository Highlights

This project demonstrates:

  • practical LLM application engineering
  • tool-augmented agent design
  • conversational memory handling
  • streaming response pipelines
  • modular Python architecture for AI applications

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages