🤖 Hybrid Chatbot and Agent System with LangChain

An intelligent hybrid AI system that dynamically routes user queries between a lightweight conversational LLM and a powerful LangChain ReAct Agent with specialized tools. Built with LangChain, Gradio, and Ollama.

📊 Architecture

graph LR
    subgraph UI["🖥️ User Interface"]
        Web[Gradio Web UI]
    end

    subgraph Core["🤖 Hybrid Core"]
        Router[Query Router<br/>LLM Classifier]
        Basic[Basic Chat<br/>Module]
        Agent[ReAct Agent<br/>LangChain]
        Memory[Conversation Memory<br/>BufferWindow k=10]
    end

    subgraph LLM["🦙 Language Model"]
        Ollama[Ollama<br/>Gemma 3 27B]
    end

    subgraph Tools["🛠️ Agent Tools"]
        Search[Web & Academic<br/>DuckDuckGo, Wiki, Arxiv]
        Python[Python REPL<br/>Code Execution]
        Media[Media Processing<br/>YouTube, Whisper]
        Vision[Image Analysis<br/>Multimodal Caption]
        Files[File Handler<br/>Excel, JSON]
        Weather[Weather API<br/>Weatherstack]
    end

    subgraph External["☁️ External Services"]
        OllamaServer[Ollama Server<br/>via Cloudflare]
        APIs[External APIs<br/>Weatherstack]
    end

    Web -->|User Query| Router
    Router -->|BASIC| Basic
    Router -->|AGENT| Agent
    
    Basic -->|Simple Chat| Ollama
    Agent -->|Reasoning| Ollama
    Agent <-->|Context| Memory
    
    Agent -->|Select Tool| Search
    Agent -->|Select Tool| Python
    Agent -->|Select Tool| Media
    Agent -->|Select Tool| Vision
    Agent -->|Select Tool| Files
    Agent -->|Select Tool| Weather
    
    Ollama <-->|API Call| OllamaServer
    Vision -.->|Multimodal| OllamaServer
    Weather -->|Request| APIs
    Files -.->|Download| APIs
    
    Basic -->|Response| Web
    Agent -->|Response| Web

    style Router fill:#FF9800,stroke:#E65100,stroke-width:3px,color:#fff
    style Basic fill:#00BCD4,stroke:#0097A7,stroke-width:3px,color:#fff
    style Agent fill:#4CAF50,stroke:#2E7D32,stroke-width:3px,color:#fff
    style Ollama fill:#2196F3,stroke:#1565C0,stroke-width:3px,color:#fff
    style Memory fill:#E91E63,stroke:#C2185B,stroke-width:3px,color:#fff
    style Web fill:#9C27B0,stroke:#6A1B9A,stroke-width:3px,color:#fff
    style OllamaServer fill:#673AB7,stroke:#4527A0,stroke-width:3px,color:#fff
    style Search fill:#607D8B,stroke:#37474F,stroke-width:2px,color:#fff
    style Python fill:#607D8B,stroke:#37474F,stroke-width:2px,color:#fff
    style Media fill:#607D8B,stroke:#37474F,stroke-width:2px,color:#fff
    style Vision fill:#607D8B,stroke:#37474F,stroke-width:2px,color:#fff
    style Files fill:#607D8B,stroke:#37474F,stroke-width:2px,color:#fff
    style Weather fill:#607D8B,stroke:#37474F,stroke-width:2px,color:#fff
    style APIs fill:#795548,stroke:#5D4037,stroke-width:2px,color:#fff

✨ Key Features

🎯 Intelligent Query Routing

Smart Classification: LLM-powered router analyzes each query and classifies it as BASIC (simple conversation) or AGENT (complex task requiring tools)
Optimized Performance: Simple queries get fast responses; complex queries leverage full agent capabilities

💬 Dual-Mode Processing

Basic Chat Mode

Handles general conversation, greetings, and simple Q&A
Direct connection to Ollama LLM for fast responses
Maintains conversation history for context

Agent Mode (LangChain ReAct)

ReAct Framework: Advanced reasoning with Action-Observation-Thought loops
Persistent Memory: ConversationBufferWindowMemory(k=10) maintains last 10 conversation turns
Tool Orchestration: Automatically selects and executes the right tool based on the query
Error Handling: Built-in handle_parsing_errors=True for robust operation

🛠️ Comprehensive Tool Suite

Category	Tools	Description
Web Search	DuckDuckGo, Wikipedia, Arxiv	Real-time information retrieval from multiple sources
Code Execution	Python REPL	Execute Python code for calculations and data analysis
Weather	Weatherstack API	Current weather information for any location
Media Processing	YouTube Downloader, Whisper Transcriber, Image Captioner	Download and analyze video/audio/image content
File Handling	File Downloader, Excel/JSON Parser	Retrieve and process structured data files

🛠️ Technologies Used

Core Framework

LangChain Classic: ReAct agent implementation with tool orchestration
LangChain Community: Pre-built tool integrations (Wikipedia, DuckDuckGo, Arxiv)
LangChain Experimental: Python REPL tool for code execution
Gradio 6.0: Modern web-based chat interface

AI & ML

Ollama: Local LLM inference server
ChatOllama: LangChain integration for Ollama models
Whisper (OpenAI): State-of-the-art speech-to-text transcription
Gemma 3 27B: Primary language model

Python Libraries

requests: HTTP client for API calls
Pillow (PIL): Image processing and encoding
pandas: Data manipulation and Excel handling
yt-dlp: YouTube video/audio downloading
BeautifulSoup4: Web scraping
python-dotenv: Environment variable management

External Services

Cloudflare Tunnel: Secure access to Ollama server
Weatherstack API: Real-time weather data
Hugging Face: External file hosting for agent tasks

📥 Installation

Prerequisites

Ollama Server: Install and run Ollama with the Gemma 3 27B model
```
ollama pull gemma3:27b
ollama serve
```
Python 3.9+: Ensure Python is installed
yt-dlp: Required for YouTube downloads
```
pip install yt-dlp
```
FFmpeg: Required for audio processing (Whisper)
- Windows: Download from ffmpeg.org
- Linux: sudo apt install ffmpeg
- macOS: brew install ffmpeg

Install Dependencies

git clone https://github.com/baloglu321/Hibrit_Chatbot_with_langchain.git
cd Hibrit_Chatbot_with_langchain
pip install -r requirements.txt

⚙️ Configuration

Create a .env file in the project root:

CLOUDFLARE_TUNNEL_URL=https://your-ollama-tunnel-url/
OLLAMA_MODEL_ID=gemma3:27b
WEATHER_API=your-weatherstack-api-key

Update agent.py and app.py to load environment variables:

import os
from dotenv import load_dotenv

load_dotenv()

CLOUDFLARE_TUNNEL_URL = os.getenv("CLOUDFLARE_TUNNEL_URL")
OLLAMA_MODEL_ID = os.getenv("OLLAMA_MODEL_ID", "gemma3:27b")
WEATHER_API = os.getenv("WEATHER_API")

Configuration Variables

Variable	Files	Example Value	Purpose
`CLOUDFLARE_TUNNEL_URL`	`app.py`, `agent.py`	`"https://your-tunnel.com/"`	Public endpoint for Ollama service
`OLLAMA_MODEL_ID`	`app.py`, `agent.py`	`"gemma3:27b"`	LLM model identifier
`WEATHER_API`	`agent.py`	`"your-api-key"`	Weatherstack API key

🚀 Usage

Start the application:

python app.py

The Gradio interface will launch at http://127.0.0.1:7860

Example Queries

Basic Mode (Fast Response):

"Hello, how are you?"
"Tell me a joke"
"What is Python?"

Agent Mode (Tool-Powered):

"What's the current population of Turkey?" (Web Search)
"What's the weather in Istanbul?" (Weather API)
"Calculate the sum of squares from 1 to 100" (Python REPL)
"Download and transcribe this YouTube video: [URL]" (Media Tools)
"Analyze this image: image.jpg - What objects are in it?" (Image Captioner)

Testing Memory (Follow-up Questions)

The agent maintains conversation context across turns:

User: "What is the current population of Turkey?"
- System: (Routes to AGENT, uses search) "Turkey's population is approximately 85 million."
User: "Who is the founding leader of this country?"
- System: (Routes to AGENT, remembers context) "The founding leader of Turkey is Mustafa Kemal Atatürk."

🏗️ Project Structure

Hibrit_Chatbot_with_langchain/
├── app.py                 # Main Gradio application with routing logic
├── agent.py               # LangChain ReAct Agent setup and tool definitions
├── deneme.py              # Test/demo script
├── requirements.txt       # Python dependencies
├── system_prompt.txt      # Agent system instructions
└── README.md              # This file

🔧 How It Works

1. Query Routing

User Query → route_question() → LLM Classifier → "BASIC" or "AGENT"

2. Basic Path

BASIC → call_llm() → Ollama Direct Response → User

3. Agent Path (ReAct Loop)

AGENT → ReAct Agent → Think → Select Tool → Execute Tool → 
Observe Result → [Loop if needed] → Final Answer → User

4. Memory Management

ConversationBufferWindowMemory (k=10)
├── Stores last 10 conversation turns
├── Loaded before each agent invocation
└── Saved after each response

🧰 Available Tools

1. Web Search Tools

general_web_search (DuckDuckGo): General web search for current news and information
wikipedia_search: Encyclopedic information, history, biographies
academic_search (Arxiv): Academic articles, research papers, theses

2. Code Execution

python_repl_tool: Execute Python code for calculations, data analysis

3. Weather Tool

WeatherInfoTool: Fetches current weather via Weatherstack API

4. Media Processing Tools

youtube_transcript_func: Downloads YouTube audio and generates transcript
transcribe_audio_whisper: Transcribes audio files using Whisper
caption_image_func: Analyzes images with multimodal LLM

5. File Tools

file_download_func: Downloads and parses Excel/JSON files from external sources

🛑 Troubleshooting

Issue	Cause	Solution
`ConnectionError`	Ollama unreachable	Verify Ollama is running: `ollama serve`
`ModuleNotFoundError: langchain`	Missing dependencies	Run `pip install -r requirements.txt`
Agent loses context	Memory not persisting	Ensure `chat_history` is global in `app.py`
Weather tool fails	Invalid API key	Verify Weatherstack API key in `.env`
YouTube download fails	yt-dlp not installed	Install: `pip install yt-dlp`
Whisper transcription fails	FFmpeg missing	Install FFmpeg (see Prerequisites)
Tool parsing errors	Incorrect input format	Check `system_prompt.txt` formatting rules

🔒 Security Best Practices

⚠️ Never commit API keys or secrets to version control!

Store sensitive values in .env file
Add .env to .gitignore
Use environment variables in code
Share .env.example template instead

Example `.gitignore`

# Environment
.env
.env.local

# Python
__pycache__/
*.pyc
*.pyo

# Media downloads
*.mp3
*.mp4
audio.mp3
video.mp4

# Downloaded files
downloaded_*
*.xlsx
*.json

🎯 Use Cases

Research Assistant: Search academic papers, Wikipedia, web simultaneously
Code Assistant: Execute Python calculations and data analysis on-the-fly
Data Analyst: Download and analyze Excel/JSON files automatically
Weather Reporter: Get real-time weather for any location
Content Analyzer: Transcribe videos, caption images, process multimedia
Conversation Partner: Natural, context-aware chat with memory

🔍 Key Differences from LlamaIndex Version

Feature	LangChain (This Project)	LlamaIndex
Agent Framework	ReAct (Action-Observation)	ReAct (Tool Selection)
Memory	`ConversationBufferWindowMemory(k=10)`	`ChatMemoryBuffer(token_limit=40000)`
Tool Definition	`@tool` decorator	`FunctionTool.from_defaults()`
Hub Integration	LangChain Hub (`hwchase17/react-chat`)	Custom prompts
Error Handling	`handle_parsing_errors=True`	Custom error handling
Math Tools	Python REPL (unified)	Separate add/sub/mul/div tools

🤝 Contributing

Contributions are welcome! Areas for improvement:

Add vector database integration (Chroma, Pinecone)
Implement streaming responses for real-time output
Add more specialized tools (email, calendar, database)
Create comprehensive unit tests
Optimize token usage and memory management
Add multilingual support

📄 License

This project is open-source and available under the MIT License.

🙏 Acknowledgments

LangChain: For the powerful agent framework and tool ecosystem
Gradio: For the intuitive and modern UI library
Ollama: For enabling local LLM inference
OpenAI Whisper: For state-of-the-art speech recognition
Hugging Face: For hosting external resources and inspiration

Built with ❤️ using LangChain, Gradio, and Ollama

Name		Name	Last commit message	Last commit date
README.md		README.md
agent.py		agent.py
app.py		app.py
deneme.py		deneme.py
requirements.txt		requirements.txt
system_prompt.txt		system_prompt.txt

Latest commit

History

Folders and files

Repository files navigation