Create README.md

README.md

@@ -1,10 +1,270 @@
 ---
-title: Context Caching Gemini Pdf Qa
-emoji: 🐢
-colorFrom: purple
-colorTo: gray
+license: apache-2.0
+title: Long Context Caching Gemini PDF QA
 sdk: docker
-pinned: false
+emoji: 📚
+colorFrom: yellow
 ---
+# 📚 Smart Document Analysis Platform
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+A modern web application that leverages Google Gemini API's caching capabilities to provide efficient document analysis. Upload documents once, ask questions forever!
+
+## 🚀 Features
+
+- **Document Upload**: Upload PDF files via drag-and-drop or URL
+- **Gemini API Caching**: Documents are cached using Gemini's explicit caching feature
+- **Cost-Effective**: Save on API costs by reusing cached document tokens
+- **Real-time Chat**: Ask multiple questions about your documents
+- **Beautiful UI**: Modern, responsive design with smooth animations
+- **Token Tracking**: See how many tokens are cached for cost transparency
+- **Smart Error Handling**: Graceful handling of small documents that don't meet caching requirements
+
+## 🎯 Use Cases
+
+This platform is perfect for:
+
+- **Research Analysis**: Upload research papers and ask detailed questions
+- **Legal Document Review**: Analyze contracts, legal documents, and policies
+- **Academic Studies**: Study course materials and textbooks
+- **Business Reports**: Analyze quarterly reports, whitepapers, and presentations
+- **Technical Documentation**: Review manuals, specifications, and guides
+
+## ⚡️ Deploy on Hugging Face Spaces
+
+You can deploy this app on [Hugging Face Spaces](https://huggingface.co/spaces) using the **Docker** SDK.
+
+### 1. **Select Docker SDK**
+- When creating your Space, choose **Docker** (not Gradio, not Static).
+
+### 2. **Project Structure**
+Make sure your repo includes:
+- `app.py` (Flask app)
+- `requirements.txt`
+- `Dockerfile`
+- `.env.example` (for reference, do not include secrets)
+
+### 3. **Dockerfile**
+A sample Dockerfile is provided:
+```dockerfile
+FROM python:3.10-slim
+WORKDIR /app
+RUN apt-get update && apt-get install -y build-essential && rm -rf /var/lib/apt/lists/*
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+EXPOSE 7860
+CMD ["python", "app.py"]
+```
+
+### 4. **Port Configuration**
+The app will run on the port provided by the `PORT` environment variable (default 7860), as required by Hugging Face Spaces.
+
+### 5. **Set Environment Variables**
+- In your Space settings, add your `GOOGLE_API_KEY` as a secret environment variable.
+
+### 6. **Push to Hugging Face**
+- Push your code to the Space's Git repository.
+- The build and deployment will happen automatically.
+
+---
+
+## 📋 Prerequisites
+
+- Python 3.8 or higher
+- Google Gemini API key
+- Internet connection for API calls
+
+## 🔧 Local Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd smart-document-analysis
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set up environment variables**
+   ```bash
+   cp .env.example .env
+   ```
+   
+   Edit `.env` and add your Google Gemini API key:
+   ```
+   GOOGLE_API_KEY=your_actual_api_key_here
+   ```
+
+4. **Get your API key**
+   - Visit [Google AI Studio](https://makersuite.google.com/app/apikey)
+   - Create a new API key
+   - Copy it to your `.env` file
+
+## 🚀 Running the Application Locally
+
+1. **Start the server**
+   ```bash
+   python app.py
+   ```
+
+2. **Open your browser**
+   Navigate to `http://localhost:7860`
+
+3. **Upload a document**
+   - Drag and drop a PDF file, or
+   - Click to select a file, or
+   - Provide a URL to a PDF
+
+4. **Start asking questions**
+   Once your document is cached, you can ask unlimited questions!
+
+## 💡 How It Works
+
+### 1. Document Upload
+When you upload a PDF, the application:
+- Uploads the file to Gemini's File API
+- Checks if the document meets minimum token requirements (4,096 tokens)
+- If eligible, creates a cache with the document content
+- If too small, provides helpful error message and suggestions
+- Stores cache metadata locally
+- Returns a cache ID for future reference
+
+### 2. Question Processing
+When you ask a question:
+- The question is sent to Gemini API
+- The cached document content is automatically included
+- You only pay for the question tokens, not the document tokens
+- Responses are generated based on the cached content
+
+### 3. Cost Savings
+- **Without caching**: You pay for document tokens + question tokens every time
+- **With caching**: You pay for document tokens once + question tokens for each question
+
+## 🔍 API Endpoints
+
+- `GET /` - Main application interface
+- `POST /upload` - Upload PDF file
+- `POST /upload-url` - Upload PDF from URL
+- `POST /ask` - Ask question about cached document
+- `GET /caches` - List all cached documents
+- `DELETE /cache/<cache_id>` - Delete specific cache
+
+## 📊 Cost Analysis
+
+### Example Scenario
+- Document: 10,000 tokens
+- Question: 50 tokens
+- 10 questions asked
+
+**Without Caching:**
+- Cost = (10,000 + 50) × 10 = 100,500 tokens
+
+**With Caching:**
+- Cost = 10,000 + (50 × 10) = 10,500 tokens
+- **Savings: 90% cost reduction!**
+
+### Token Requirements
+- **Minimum for caching**: 4,096 tokens
+- **Recommended minimum**: 5,000 tokens for cost-effectiveness
+- **Optimal range**: 10,000 - 100,000 tokens
+- **Maximum**: Model-specific limits (check Gemini API docs)
+
+## 🎨 Customization
+
+### Changing the Model
+Edit `app.py` and change the model name:
+```python
+model="models/gemini-2.0-flash-001"  # Current
+model="models/gemini-2.0-pro-001"    # Alternative
+```
+
+### Custom System Instructions
+Modify the system instruction in the cache creation:
+```python
+system_instruction="Your custom instruction here"
+```
+
+### Cache TTL
+Add TTL configuration to cache creation:
+```python
+config=types.CreateCachedContentConfig(
+    system_instruction=system_instruction,
+    contents=[document],
+    ttl='24h'  # Cache for 24 hours
+)
+```
+
+## 🔒 Security Considerations
+
+- API keys are stored in environment variables
+- File uploads are validated for PDF format
+- Cached content is managed securely through Gemini API
+- No sensitive data is stored locally
+
+## 🚧 Production Deployment
+
+For production deployment:
+
+1. **Use a production WSGI server**
+   ```bash
+   pip install gunicorn
+   gunicorn -w 4 -b 0.0.0.0:7860 app:app
+   ```
+
+2. **Add database storage**
+   - Replace in-memory storage with PostgreSQL/MySQL
+   - Add user authentication
+   - Implement session management
+
+3. **Add monitoring**
+   - Log API usage and costs
+   - Monitor cache hit rates
+   - Track user interactions
+
+4. **Security enhancements**
+   - Add rate limiting
+   - Implement file size limits
+   - Add input validation
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+- Google Gemini API for providing the caching functionality
+- Flask community for the excellent web framework
+- The open-source community for inspiration and tools
+
+## 📞 Support
+
+If you encounter any issues:
+
+1. Check the [Gemini API documentation](https://ai.google.dev/docs)
+2. Verify your API key is correct
+3. Ensure your PDF files are valid
+4. Check the browser console for JavaScript errors
+5. **For small document errors**: Upload a larger document or combine multiple documents
+
+## 🔮 Future Enhancements
+
+- [ ] Support for multiple file formats (Word, PowerPoint, etc.)
+- [ ] User authentication and document sharing
+- [ ] Advanced analytics and usage tracking
+- [ ] Integration with cloud storage (Google Drive, Dropbox)
+- [ ] Mobile app version
+- [ ] Multi-language support
+- [ ] Advanced caching strategies
+- [ ] Real-time collaboration features
+- [ ] Document preprocessing to meet token requirements
+- [ ] Batch document processing