🧠 Askly: Intelligent RAG & Web Search Agent

Askly is a high-performance RAG (Retrieval-Augmented Generation) system that lets you chat with your documents and falls back to the internet when it doesn't know the answer. Built with Google Gemini, ChromaDB, and real-time streaming.

✨ Key Features

• PDF Intelligence: Upload any PDF to index it into ChromaDB Cloud for instant local retrieval.
• Smart Fallback: If Askly can't find the answer in your documents, it automatically triggers a Tavily Web Search.
• Real-time Streaming: AI responses stream word-by-word via Server-Sent Events (SSE) — exactly like ChatGPT.
• Markdown Rendering: Responses render rich markdown — including bold text, lists, and code blocks.
• Modern UI: A premium, responsive chat interface built with React, Shadcn UI, and Lucide Icons.
• Attachment System: Modern AI-style file attachments for seamless document indexing.
• Real-time Logging: Backend middleware logs every interaction with timestamps.

---

📸 Screenshots

🌐 Web Search in Action

Ask anything without uploading a file — Askly falls back to live Tavily web search and streams the answer with a 🌐 WEB SEARCH badge.

---

📄 PDF Upload & Document Search

Upload any PDF, then ask questions about its content — Askly indexes it into ChromaDB and streams answers from your own data.

---

🏗️ Architecture & Data Flow

Askly follows a robust RAG lifecycle:

1. Ingestion: PDFs are parsed, chunked, and vectorized using Google Gemini Embeddings (gemini-embedding-001) before being stored in ChromaDB Cloud.
2. Retrieval: Queries are converted to vectors and compared via Cosine Similarity to find the most relevant document chunks.
3. Synthesis: If document similarity is below threshold, Askly searches the web via Tavily.
4. Generation: The final context is sent to Gemini 2.5 Flash which streams the answer back word-by-word through Server-Sent Events.

Streaming Architecture

User sends message
    ↓
Frontend creates empty assistant bubble
    ↓
POST /api/query/stream (SSE endpoint)
    ↓
Backend yields: { sources, isFromWeb } → then { chunk: "word" } × N → [DONE]
    ↓
Frontend ReadableStream reader appends each chunk to the bubble in real-time

---

🚀 Getting Started

1. Prerequisites

Ensure you have Node.js v18+ installed and the following API keys:

• Google Gemini API Key — FREE at aistudio.google.com
• ChromaDB Cloud — API Key, Tenant, and Database name from trychroma.com
• Tavily API Key — FREE tier at tavily.com

2. Setup Environment

Create a .env file inside the server/ directory:

GEMINI_API_KEY=your_gemini_key
CHROMA_API_KEY=your_chroma_key
CHROMA_TENANT=your_tenant_id
CHROMA_DATABASE=askly
TAVILY_API_KEY=your_tavily_key

3. Installation

Install dependencies for both client and server:

# Install Server deps
cd server
npm install

# Install Client deps
cd ../client
npm install

4. Running the App

Start the development servers for both:

Backend (Server):

cd server
npm run dev

Frontend (Client):

cd client
npm run dev

The application will be available at http://localhost:5173.

---

🛠️ Tech Stack

Frontend

Technology	Purpose
React 19 + Vite	UI framework & build tool
Tailwind CSS v4	Styling
Shadcn UI + Radix	Component library
react-markdown	Render AI markdown responses
Lucide Icons	Icon set

Backend

Technology	Purpose
Node.js + Express	HTTP server
TypeScript + Tsx	Type safety & dev runner
Google Gemini SDK	LLM generation + embeddings
ChromaDB Cloud	Vector store
Tavily API	Web search fallback
Multer	PDF file upload handling
pdf-parse	PDF text extraction
Server-Sent Events	Real-time streaming

---

📁 Project Structure

askly/
├── client/             # React frontend
│   └── src/
│       ├── components/
│       │   ├── chat/   # ChatHeader, ChatMessage, ChatInput
│       │   └── ui/     # Shadcn components
│       ├── types/      # Shared TypeScript types
│       └── App.tsx     # Main app with SSE streaming logic
└── server/             # Express backend
    └── src/
        ├── lib/
        │   ├── rag.ts        # RAG engine (query + queryStream)
        │   ├── embedding.ts  # Gemini vector embeddings
        │   ├── vectorStore.ts # ChromaDB integration
        │   ├── search.ts     # Tavily web search
        │   └── utils.ts      # Text chunking
        └── server.ts         # Express endpoints (+ /api/query/stream)

---

🎨 Design Philosophy

Askly is designed to be visually stunning and highly functional. It features:

• Glassmorphism: Elegant card layouts with backdrop blurs.
• Micro-animations: Smooth transitions for message bubbles and loaders.
• Responsiveness: Fully optimized for mobile and desktop screens.
• Streaming UX: Text types itself out word-by-word for a natural, fast-feeling experience.

---

Important

To use real AI responses, ensure you have a GEMINI_API_KEY set in your .env file. You can get one for free at Google AI Studio.

Note

The embedding model (gemini-embedding-001) produces 3072-dimensional vectors. ChromaDB collections must be consistent — run a DB reset if switching embedding models.

---

🤝 Contributing

Contributions are welcome! Whether it's a bug fix, new feature, or documentation improvement — every bit helps.

• 📖 Read the Contributing Guide before submitting a PR
• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features via the Feature Request template
• 🔒 Report security issues privately via SECURITY.md
• 🤝 Please follow our Code of Conduct

---

Developed with ❤️ as part of the Askly RAG Learning Series.