{"id":50928363,"url":"https://github.com/persteenolsen/fastapi-jwt-auth-rag-one","last_synced_at":"2026-06-17T01:31:10.687Z","repository":{"id":349980522,"uuid":"1204767807","full_name":"persteenolsen/fastapi-jwt-auth-rag-one","owner":"persteenolsen","description":"Python FastAPI with JWT Auth serving RAG using LLM by Groq","archived":false,"fork":false,"pushed_at":"2026-04-08T10:29:51.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T12:20:41.258Z","etag":null,"topics":["fastapi","jwt","llm","postgresql","python","rag","vector"],"latest_commit_sha":null,"homepage":"https://fastapi-jwt-auth-rag-one.vercel.app","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/persteenolsen.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-04-08T10:07:55.000Z","updated_at":"2026-04-08T10:29:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/persteenolsen/fastapi-jwt-auth-rag-one","commit_stats":null,"previous_names":["persteenolsen/fastapi-jwt-auth-rag-one"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/persteenolsen/fastapi-jwt-auth-rag-one","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-rag-one","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-rag-one/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-rag-one/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-rag-one/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/persteenolsen","download_url":"https://codeload.github.com/persteenolsen/fastapi-jwt-auth-rag-one/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-rag-one/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34430688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"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":["fastapi","jwt","llm","postgresql","python","rag","vector"],"created_at":"2026-06-17T01:31:09.909Z","updated_at":"2026-06-17T01:31:10.669Z","avatar_url":"https://github.com/persteenolsen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python + FastAPI + JWT Auth + RAG + (Mock Embeddings Version)  \n \nA lightweight **Retrieval-Augmented Generation (RAG)** API built with **FastAPI**, designed for **learning, testing, and prototyping**.\n\nThis version uses **deterministic fake embeddings** instead of real embedding models—allowing you to test the full RAG pipeline **without external embedding APIs or costs**.\n\n---\n\n## 📌 Project Info\n\n- **Version:** 0.0.1  \n- **Python:** 3.12  \n- **Last Updated:** 15-04-2026  \n\n---\n\n## ✨ Features\n\n### 🔐 Authentication\n- JWT-based authentication (HS256)  \n- Protected endpoints with Bearer tokens  \n- Simple environment-based credentials  \n\n---\n\n### 🧠 RAG Pipeline (Fully Functional)\n- Ingest `.txt` files from URLs  \n- Chunk text with overlap  \n- Generate embeddings (**mocked**)  \n- Store vectors in PostgreSQL (`pgvector`)  \n- Retrieve relevant context for queries  \n- Generate answers with Groq LLM  \n\n---\n\n### 🧪 Fake Embeddings (Key Feature)\n- Deterministic embeddings based on text hashing  \n- 384-dimensional normalized vectors  \n- No external API calls required  \n- Perfect for:\n  - Local development  \n  - Testing pipelines  \n  - Learning RAG architecture  \n\n\u003e ⚠️ Note: These embeddings do **not understand semantics**—they only simulate the pipeline.\n\n---\n\n### 🤖 LLM Integration (Groq)\n- Model: `llama-3.1-8b-instant`  \n- Generates responses from retrieved context  \n- Temperature-controlled outputs  \n\n---\n\n### 🔎 Semantic Retrieval (Simulated)\n- Query → fake embedding  \n- Vector similarity search via `pgvector`  \n- Top-K document retrieval  \n\n---\n\n### 🗄️ Database (PostgreSQL + pgvector)\n\nStores:\n- Document content  \n- Embeddings (`VECTOR(384)`)  \n- Source URL  \n- Embedding metadata  \n- Timestamp  \n\nOptimizations:\n- `ivfflat` index  \n- Cosine similarity (`\u003c-\u003e`)  \n\n---\n\n### ⚙️ Background Processing\n- Uses FastAPI `BackgroundTasks`  \n- Async ingestion pipeline  \n- Non-blocking embedding + database insert  \n\n---\n\n### 🧪 Debugging Tools\n- `/debug/retrieve` → test retrieval without auth or LLM  \n- Console logs for retrieval inspection  \n\n---\n\n## 📡 API Endpoints\n\n| Method | Endpoint            | Description                          |\n|--------|--------------------|--------------------------------------|\n| GET    | `/`                | Health check                         |\n| POST   | `/login`           | Get JWT token                        |\n| POST   | `/ask`             | RAG question answering 🔐            |\n| POST   | `/ingest`          | Ingest `.txt` from URL 🔐            |\n| POST   | `/debug/retrieve`  | Test retrieval only                  |\n\n🔐 = Requires authentication\n\n---\n\n## ⚙️ Getting Started\n\n### 1. Clone Repository\n\n```bash\ngit clone https://github.com/your-username/your-repo.git\ncd your-repo\n```\n\n---\n\n### 2. Create Virtual Environment\n\n```bash\npython -m venv venv\n```\n\nActivate:\n\n**Windows:**\n```bash\nvenv\\Scripts\\activate\n```\n\n**Mac/Linux:**\n```bash\nsource venv/bin/activate\n```\n\n---\n\n### 3. Install Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n---\n\n## 🔑 Environment Variables\n\nCreate a `.env` file:\n\n```env\nDATABASE_URL=your_postgres_connection\nGROQ_API_KEY=your_groq_api_key\nSECRET_KEY=your_secret_key\n\nFAKE_USERNAME=admin\nFAKE_PASSWORD=password\n```\n\n---\n\n## ▶️ Run the Application\n\n```bash\nuvicorn app:app --reload\n```\n\nAvailable at:\n\n- 🌐 API: http://127.0.0.1:8000\n\n- 📄 Swagger UI: http://127.0.0.1:8000/docs  \n\n---\n\n## 🔐 Authentication Flow\n\n1. Call `/login` with credentials  \n2. Receive JWT token  \n3. Use in headers:\n\n```http\nAuthorization: Bearer \u003cyour_token\u003e\n```\n\n---\n\n## 🧠 How It Works\n\n```text\nUser Query\n   ↓\nFake Embedding (Deterministic)\n   ↓\npgvector Similarity Search\n   ↓\nTop-K Chunks\n   ↓\nGroq LLM (LLaMA 3.1)\n   ↓\nFinal Answer + Sources\n```\n\n---\n\n## 📥 Document Ingestion\n\n### `/ingest`\n- Accepts `.txt` file URLs  \n- Fetches and cleans text  \n- Splits into chunks (with overlap)  \n- Generates fake embeddings  \n- Stores in PostgreSQL  \n\n---\n\n## 🛠️ Core Components\n\n### 🔹 Chunking\n- Fixed-size chunks (default: 500 chars)  \n- Overlap: 50 chars  \n\n---\n\n### 🔹 Fake Embedding Logic\n- Seed based on text hash  \n- Generates reproducible vectors  \n- Normalized for cosine similarity  \n\n---\n\n### 🔹 Retrieval\n- Uses `embedding \u003c-\u003e query_vector`  \n- Returns top-K most similar chunks  \n\n---\n\n## 🗄️ Database Initialization\n\nOn startup:\n- Enables `pgvector` extension  \n- Creates `documents` table  \n- Builds similarity index (`ivfflat`)  \n\n---\n\n## 📌 Use Cases\n\nThis version is ideal for:\n\n- 🧪 Learning RAG systems  \n- ⚙️ Backend prototyping  \n- 💻 Local development without API costs  \n- 🔍 Debugging retrieval pipelines  \n\n---\n\n## 🚧 Limitations\n\n- ❌ No real semantic understanding (fake embeddings)  \n- ❌ Retrieval quality is not meaningful  \n- ✅ Pipeline behavior is realistic  \n\n---\n\n## 📌 Future Improvements\n\n- 🔄 Replace fake embeddings with real models (Hugging Face / OpenAI)  \n- 📊 Add monitoring/logging  \n- 🔍 Hybrid search (BM25 + vectors)  \n- 🧩 Add document formats (PDF, HTML)\n- Splitting up the app.py into seperate files and folders for improved structure  \n\n---\n\n## 📄 License\n\nMIT License  \n\n---\n\n## 🙌 Final Notes\n\nThis project demonstrates a **complete RAG architecture** without external dependencies for embeddings—making it perfect for understanding how everything fits together before scaling to production systems.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpersteenolsen%2Ffastapi-jwt-auth-rag-one","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpersteenolsen%2Ffastapi-jwt-auth-rag-one","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpersteenolsen%2Ffastapi-jwt-auth-rag-one/lists"}