{"id":45837644,"url":"https://github.com/gommezen/rag_writing_assistant","last_synced_at":"2026-02-26T23:15:45.571Z","repository":{"id":334440197,"uuid":"1139934676","full_name":"gommezen/rag_writing_assistant","owner":"gommezen","description":"A transparent, fully local RAG document assistant that  grounds every claim in your documents with interactive  citations, coverage tracking, and confidence indicators.","archived":false,"fork":false,"pushed_at":"2026-02-10T02:44:10.000Z","size":947,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-10T05:54:04.418Z","etag":null,"topics":["claude","document-analysis","document-analysis-tool","faiss","fastapi","local-llm","ollama","rag","react","typescript"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gommezen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-22T15:58:53.000Z","updated_at":"2026-02-10T02:44:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gommezen/rag_writing_assistant","commit_stats":null,"previous_names":["gommezen/rag_writing_assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gommezen/rag_writing_assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gommezen%2Frag_writing_assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gommezen%2Frag_writing_assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gommezen%2Frag_writing_assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gommezen%2Frag_writing_assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gommezen","download_url":"https://codeload.github.com/gommezen/rag_writing_assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gommezen%2Frag_writing_assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29876468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T22:37:10.609Z","status":"ssl_error","status_checked_at":"2026-02-26T22:37:09.019Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["claude","document-analysis","document-analysis-tool","faiss","fastapi","local-llm","ollama","rag","react","typescript"],"created_at":"2026-02-26T23:15:45.368Z","updated_at":"2026-02-26T23:15:45.540Z","avatar_url":"https://github.com/gommezen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RAG Document Intelligence\n\n![Python](https://img.shields.io/badge/Python-3.11+-blue)\n![React](https://img.shields.io/badge/React-18-61DAFB)\n![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6)\n![FastAPI](https://img.shields.io/badge/FastAPI-0.109+-009688)\n![License](https://img.shields.io/badge/License-MIT-green)\n![Ollama](https://img.shields.io/badge/LLM-Ollama_(local)-black)\n\nA transparent AI writing assistant that grounds every claim in your documents. Hover any citation to preview the source, click to verify the full context — so you always know exactly where the AI got its information.\n\n![RAG Document Intelligence Screenshot](docs/screenshot.png)\n\n## Features\n\n- **Document upload** - PDF, DOCX, and TXT with drag-and-drop (non-blocking processing)\n- **Grounded generation** - All AI content derived from your uploaded documents\n- **Interactive citations** - Hover to preview source, click to navigate to full context\n- **Confidence indicators** - Visual cues for high/medium/low confidence content\n- **Section-level editing** - Regenerate or manually edit individual sections\n- **Coverage transparency** - See what % of your documents were analyzed\n- **Intent detection** - Auto-selects retrieval strategy per query type (analysis/QA/writing)\n- **Chat mode** - Multi-turn conversations with persistent history\n- **Dark mode** - Toggle between light and dark themes\n- **Keyboard shortcuts** - Ctrl+Enter to generate, Escape to close modals\n- **Fully local** - Documents never leave your machine (runs on Ollama)\n\n## Requirements\n\n- Python 3.11+\n- Node.js 18+\n- [Ollama](https://ollama.ai/) running locally\n\n## Installation\n\n### 1. Install Ollama and pull models\n\n```bash\nollama pull qwen2.5:7b-instruct-q4_0\nollama pull mxbai-embed-large\n```\n\n### 2. Set up the backend\n\n```bash\ncd backend\npip install -r requirements.txt\n```\n\n### 3. Set up the frontend\n\n```bash\ncd frontend\nnpm install\n```\n\n## Running the App\n\nStart both services in separate terminals:\n\n```bash\n# Terminal 1 - Backend\ncd backend\npython -m uvicorn app.main:app --port 8001 --reload\n\n# Terminal 2 - Frontend\ncd frontend\nnpm run dev\n```\n\nOpen http://localhost:5173 in your browser.\n\n## Configuration\n\nCreate `backend/.env` to customize (all optional):\n\n```env\n# LLM Models (must be available in Ollama)\nGENERATION_MODEL=qwen2.5:7b-instruct-q4_0\nEMBEDDING_MODEL=mxbai-embed-large\n\n# Intent-specific models (falls back to GENERATION_MODEL)\nANALYSIS_MODEL=llama3.1:8b-instruct-q8_0\nWRITING_MODEL=qwen2.5:7b-instruct-q4_0\nQA_MODEL=gemma3:4b\n\n# Retrieval settings\nSIMILARITY_THRESHOLD=0.35\nTOP_K=10\n\n# Coverage settings (for analysis/summary mode)\nDEFAULT_COVERAGE_PCT=35\nMAX_COVERAGE_PCT=60\n\n# Ollama connection\nOLLAMA_BASE_URL=http://localhost:11434\n```\n\n## How It Works\n\n### Intent Detection\n\nThe system classifies queries and adjusts retrieval strategy automatically:\n\n| Query Example | Intent | Retrieval | Coverage |\n|---|---|---|---|\n| \"Summarize this document\" | Analysis | Diverse (regions) | ~35% |\n| \"What is data feminism?\" | Q\u0026A | Similarity (top-k) | ~8-10% |\n| \"Write a report on X\" | Writing | Similarity (top-k) | ~8-10% |\n\n### Coverage Tracking\n\nThe UI shows how much of your documents the system actually read:\n\n- Coverage percentage with color indicator (green/yellow/red)\n- Chunks analyzed vs total\n- \"Expand to ~50%\" button for deeper analysis\n\nA summary based on 8% is different from 35% — the system makes this visible.\n\n### Confidence Levels\n\n| Level | Criteria |\n|---|---|\n| High | 3+ citations |\n| Medium | 1-2 citations |\n| Low | Hedging language detected |\n| Unknown | 0 citations |\n\n### Blind Spot Detection\n\nThe system reports what it didn't see — documents with no coverage, regions (intro/middle/conclusion) that weren't sampled.\n\n### No Learning From Your Data\n\nRAG does **not** train on your documents. Files are chunked and indexed for retrieval only — the AI model is never modified. Deleting a document removes it completely.\n\n## Chat Mode\n\nSwitch to Chat mode for multi-turn conversations about your documents:\n\n- Follow-up questions that build on prior context\n- Conversation history in the sidebar (browse, resume, delete)\n- Per-message sources showing which chunks were used\n- Cumulative coverage tracking across a conversation\n- Stored locally as JSON files, never sent externally\n\n## Project Structure\n\n```\nrag_writing_assistant/\n├── backend/\n│   ├── app/\n│   │   ├── api/routes/          # FastAPI endpoints\n│   │   ├── core/                # Exceptions, logging\n│   │   ├── models/              # Pydantic models\n│   │   ├── rag/                 # Chunking, embeddings, vector store, prompts\n│   │   ├── services/            # Business logic (generation, retrieval, intent)\n│   │   ├── config.py            # Settings\n│   │   └── main.py              # FastAPI app entry point\n│   ├── tests/                   # Pytest test suite\n│   ├── data/                    # Document storage, vector indices, conversations\n│   ├── requirements.txt\n│   └── pyproject.toml\n├── frontend/\n│   ├── src/\n│   │   ├── api/                 # API client\n│   │   ├── components/          # React components\n│   │   ├── hooks/               # React Query hooks\n│   │   ├── types/               # TypeScript interfaces\n│   │   └── test/                # Test utilities\n│   ├── package.json\n│   ├── tsconfig.json\n│   └── vite.config.ts\n├── docs/                        # Screenshots\n├── CLAUDE.md                    # AI agent instructions\n├── CHANGELOG.md\n└── README.md\n```\n\n## API Reference\n\n| Endpoint | Method | Description |\n|---|---|---|\n| `/api/documents` | POST | Upload document |\n| `/api/documents` | GET | List documents |\n| `/api/documents/{id}` | GET | Get document status |\n| `/api/documents/{id}` | DELETE | Delete document |\n| `/api/generate` | POST | Generate draft |\n| `/api/generate/section` | POST | Regenerate section |\n| `/api/generate/suggestions` | POST | Generate suggested questions |\n| `/api/chat` | POST | Send chat message |\n| `/api/chat` | GET | List conversations |\n| `/api/chat/{id}` | GET | Get conversation |\n| `/api/chat/{id}` | DELETE | Delete conversation |\n| `/api/chat/{id}` | PATCH | Update conversation title |\n| `/api/health` | GET | Health check |\n\nDocument uploads are non-blocking — the endpoint returns immediately with `status: \"pending\"`, then progresses through `processing` to `ready` (or `failed`).\n\n## Development\n\n### Running Tests\n\n```bash\n# Backend (pytest)\ncd backend \u0026\u0026 pytest tests/ -v\n\n# Frontend (vitest)\ncd frontend \u0026\u0026 npm run test\n\n# Frontend type check + build\ncd frontend \u0026\u0026 npm run build\n```\n\n### Tech Stack\n\n| Layer | Technology |\n|---|---|\n| Backend | Python 3.11+, FastAPI, Pydantic |\n| Frontend | React 18, TypeScript (strict), React Query |\n| Vector DB | FAISS (local, file-based) |\n| LLM | Ollama (local inference) |\n| Embeddings | mxbai-embed-large |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgommezen%2Frag_writing_assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgommezen%2Frag_writing_assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgommezen%2Frag_writing_assistant/lists"}