{"id":31798422,"url":"https://github.com/drakonis96/zotreader","last_synced_at":"2025-10-10T21:28:47.507Z","repository":{"id":293361597,"uuid":"983795417","full_name":"Drakonis96/zotreader","owner":"Drakonis96","description":"ZotReader is a webapp that lets you read, annotate and talk (using AI) with your Zotero PDFs from your browser.","archived":false,"fork":false,"pushed_at":"2025-05-31T09:59:44.000Z","size":3883,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-31T20:12:19.431Z","etag":null,"topics":["ai","pdf","pdfreader","react","zotero"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Drakonis96.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-14T23:46:18.000Z","updated_at":"2025-05-31T11:30:28.000Z","dependencies_parsed_at":"2025-05-15T00:48:15.813Z","dependency_job_id":null,"html_url":"https://github.com/Drakonis96/zotreader","commit_stats":null,"previous_names":["drakonis96/zotreader"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Drakonis96/zotreader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drakonis96%2Fzotreader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drakonis96%2Fzotreader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drakonis96%2Fzotreader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drakonis96%2Fzotreader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Drakonis96","download_url":"https://codeload.github.com/Drakonis96/zotreader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drakonis96%2Fzotreader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005420,"owners_count":26083883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","pdf","pdfreader","react","zotero"],"created_at":"2025-10-10T21:28:37.087Z","updated_at":"2025-10-10T21:28:47.494Z","avatar_url":"https://github.com/Drakonis96.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Centered logo at the top --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"frontend/public/logo.png\" alt=\"ZotReader Logo\" width=\"180\"/\u003e\n\u003c/p\u003e\n\n# ZotReader 📚🤖\n\nZotReader is a modern web application designed to help you read, annotate, and interact with your PDF documents using powerful AI tools—all from your browser! Whether you're a student, researcher, or just love reading, ZotReader makes it easy to highlight, take notes, and chat with AI about your documents in real time.\n\n\u003c!-- DISCLAIMER: This application is not affiliated with or endorsed by Zotero or its parent company. ZotReader is an independent project developed solely to help users view and annotate documents linked to their Zotero library and a WebDAV server through the browser. We have no connection or association with the official Zotero software or organization. --\u003e\n\n\u003e **Important Notice:**\n\u003e\n\u003e ZotReader is **not intended to replace the official Zotero application**. Rather than being a substitute (which it is not), ZotReader should be considered a companion app that offers AI-powered features and works from any device with a browser. It is designed to complement your Zotero workflow, not to replace it.\n\u003e\n\u003e **Note:** Annotations and notes made in ZotReader are **not synchronized with Zotero**. The way annotations are handled in ZotReader is different from Zotero's native system.\n\n\u003e **First-time startup notice:**\n\u003e\n\u003e The first time you start ZotReader, it may take a bit longer to load. This is because the app needs to synchronize your Zotero library structure for the first time. Subsequent startups will be much faster.\n\n---\n\n## 🚀 Main Features\n- **Read and Annotate PDFs:** Highlight, underline, and add notes directly in your browser. Compatible with Apple Pencil and other styluses for a natural writing experience.\n- **AI-Powered Assistance:** Ask questions, summarize, or get explanations from your documents using integrated AI (supports Gemini, OpenRouter, OpenAI, and more).\n- **Seamless Experience:** Use the app from any device—desktop, tablet, or mobile.\n- **Easy Document Management:** Upload, organize, and access your PDFs anytime.\n- **Beta Notice:** ZotReader is currently in beta. You may encounter bugs or unexpected results. Your feedback is welcome!\n\n## 💡 Recommended AI APIs\nWe highly recommend using **free AI APIs** like Gemini and OpenRouter, which offer generous free usage while ZotReader is in beta. OpenAI is also supported.\n\n---\n\n# 🛠️ Getting Started\n\n## Option 1: Run with Docker Compose (Recommended) 🐳\n1. **Install Docker Desktop** if you haven't already: [Download Docker](https://www.docker.com/products/docker-desktop/)\n2. **Clone this repository:**\n   ```bash\n   git clone https://github.com/Drakonis96/zotreader\n   cd ZotReader\n   ```\n3. **Configure environment variables:**\n   - Copy `.env.example` to `.env`:\n     ```bash\n     cp .env.example .env\n     ```\n   - You can open the `.env` file with your favorite editor, for example:\n     ```bash\n     code .env\n     ```\n     Or on macOS you can also use:\n     ```bash\n     open .env\n     ```\n   - Open the `.env` file in your favorite editor and fill in the required API keys:\n     - `OPENAI_API_KEY` (optional, for OpenAI)\n     - `GEMINI_API_KEY` (recommended, for Gemini)\n     - `OPENROUTER_API_KEY` (recommended, for OpenRouter)\n     - `WEBDAV_URL`, `WEBDAV_USERNAME`, `WEBDAV_PASSWORD` (optional, for cloud storage integration, e.g., Koofr)\n     - Any other variables as needed for your setup\n   - Example:\n     ```env\n     OPENAI_API_KEY=sk-...\n     GEMINI_API_KEY=your-gemini-key-here\n     OPENROUTER_API_KEY=your-openrouter-key-here\n     # Example Koofr WebDAV configuration\n     WEBDAV_URL=https://app.koofr.net/dav/USERNAME@koofr.net/\n     WEBDAV_USERNAME=USERNAME@koofr.net\n     WEBDAV_PASSWORD=your-koofr-app-password\n     ```\n   - We recommend using Gemini or OpenRouter for free usage during beta.\n4. **Start the app:**\n   ```bash\n   docker-compose up --build\n   ```\n5. **Access the app:**\n   - Open your browser and go to [http://localhost:8006](http://localhost:8006)\n\n\u003e **Note:** Although the backend runs internally on port 8000, the application will be available on the port you have configured in the `docker-compose.yml` file (by default, in this project it is **8006**). Make sure to access the correct URL, for example: http://localhost:8006\n\n## Option 2: Manual Setup (Python Backend + Frontend)\n\n### 1. Backend (Python)\n- **Install Python 3.11+ and pip**\n- **Install dependencies:**\n  ```bash\n  cd backend\n  pip install -r requirements.txt\n  ```\n- **Configure environment variables:**\n  - Copy `.env.example` to `.env`:\n    ```bash\n    cp .env.example .env\n    ```\n  - You can open the `.env` file with your favorite editor, for example:\n    ```bash\n    code .env\n    ```\n    Or on macOS you can also use:\n    ```bash\n    open .env\n    ```\n  - Open the `.env` file in your favorite editor and fill in the required API keys:\n    - `OPENAI_API_KEY` (optional, for OpenAI)\n    - `GEMINI_API_KEY` (recommended, for Gemini)\n    - `OPENROUTER_API_KEY` (recommended, for OpenRouter)\n    - `WEBDAV_URL`, `WEBDAV_USERNAME`, `WEBDAV_PASSWORD` (optional, for cloud storage integration, e.g., Koofr)\n    - Any other variables as needed for your setup\n  - Example:\n    ```env\n    ZOTERO_USER_ID=your_user_id\n    ZOTERO_API_KEY=your_zotero_api_key\n    WEBDAV_URL=https://app.koofr.net/dav/Koofr #Koofr provided as example\n    WEBDAV_USER=your_webdav_user\n    WEBDAV_PASS=your_webdav_pass\n    GOOGLE_API_KEY=your_google_api_key\n    OPENAI_API_KEY=your_openai_api_key\n    OPENROUTER_API_KEY=your_openrouter_api_key\n    REDIS_URL=redis://redis:6379/0\n    ```\n  - We recommend using Gemini or OpenRouter for free usage during beta.\n- **Run the backend server:**\n  ```bash\n  uvicorn main:app --reload --host 0.0.0.0 --port 8000\n  ```\n\n### 2. Frontend (Vite + React)\n- **Install Node.js (v18+) and npm**\n- **Install dependencies:**\n  ```bash\n  cd frontend\n  npm install\n  ```\n- **Run the frontend:**\n  ```bash\n  npm run dev\n  ```\n- **Access the app:**\n  - Open your browser and go to the URL: http://localhost:8006\n\n---\n\n## ℹ️ About the REDIS_URL variable\n\n- The `REDIS_URL` environment variable specifies the connection address for a Redis server, which is used as a cache and temporary storage system for the application.\n- **Default value:** If you do not define `REDIS_URL` in your `.env` or in `docker-compose.yml`, the backend will automatically use:\n  \n  ```env\n  REDIS_URL=redis://redis:6379/0\n  ```\n  \n  This value connects to a Redis service named `redis` (usually defined in Docker Compose) on port 6379 and database 0.\n- **Customization:** You can change this value according to your environment (for example, to use an external Redis, another host, port, database, or credentials).\n- If the variable does not exist and the code does not find a default value, the application will throw an error when trying to connect to Redis.\n\n---\n\n# ⚠️ Beta Disclaimer\nZotReader is in **beta**. You may experience bugs or unexpected results. Please use free AI APIs (Gemini, OpenRouter) to avoid unnecessary costs during this period. Your feedback is appreciated!\n\n# 🌐 Browser-Based \u0026 Pencil Friendly\n- Designed for use in your browser—no installation required on your device.\n- Fully compatible with Apple Pencil and other styluses for smooth annotation.\n- Use AI chat while reading and highlighting your documents, from any device!\n\n---\n\n# 🙏 Acknowledgments\n\nThis app was created with the help of advanced AI models from OpenAI (GPT-4.1 and O4), Anthropic (Claude 3.7), and Google (Gemini 2.5 Pro Preview). Any contributions or suggestions to improve the project are very welcome!\n\nEnjoy smarter reading and annotating with ZotReader! ✨\n\n---\n\n## 📸 Screenshots\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/Screenshot 1.png\" alt=\"Screenshot 1\" width=\"600\"/\u003e\n  \u003cbr/\u003e\n  \u003cimg src=\"screenshots/Screenshot 2.png\" alt=\"Screenshot 2\" width=\"600\"/\u003e\n  \u003cbr/\u003e\n  \u003cimg src=\"screenshots/Screenshot 3.png\" alt=\"Screenshot 3\" width=\"600\"/\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrakonis96%2Fzotreader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrakonis96%2Fzotreader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrakonis96%2Fzotreader/lists"}