RAGify / README.md
Fakhir1's picture
Set python_version to 3.10 and add pyaudioop for audioop compatibility
eabdac7
|
Raw History Blame Contribute Delete
6.38 kB
---
title: RAGify
emoji: ✳️
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: "4.44.1"
python_version: "3.10"
app_file: app.py
app_port: 7860
pinned: false
short_description: Ask files, web pages and data. Inspect every source.
---
# Northstar · Private Knowledge Assistant
A complete, deployable **no-signup AI product demo** for a software-house portfolio. Built with a custom responsive interface, FastAPI, Groq, source retrieval, OCR and read-only data tools. Designed to deploy as a Hugging Face Docker Space and embed on your website.
**This is real AI integration, not a prerecorded chatbot.** Configure a Groq key to get answers about sample data or a visitor's own sources. No credentials are included.
## Start here
1. Follow [Hugging Face deployment instructions](docs/DEPLOYMENT.md).
2. Add `GROQ_API_KEY` as a Space secret.
3. Load the sample workspace and ask a suggested question.
## Included
| Feature | Implementation |
|---|---|
| Product interface | Responsive sidebar, source manager, chat, source inspector, settings, desktop/mobile layouts |
| Real AI | Groq planning and streamed answers, follow-up context, honest provider error states |
| Documents | PDF, DOCX, TXT/MD, JPG/PNG; local Tesseract OCR for scans |
| Citations | PDF pages; DOCX paragraphs/tables; text line ranges; exact webpage URLs |
| Web pages | Public HTML/text, one page or up to 10 linked pages on the same site |
| Uploaded data | SQLite and CSV; CSV becomes a queryable `uploaded_data` table |
| Remote SQL | PostgreSQL, MySQL/MariaDB, SQL Server connectors; operator-approved hosts and dedicated read-only credentials |
| MongoDB | Approved-host connection with bounded find/filter/projection/sort queries; no aggregation pipeline |
| Combined questions | Document retrieval plus database query in the same answer |
| Results | Exact executed query, bounded table, numeric bar chart where appropriate, CSV export |
| Privacy controls | Separate random-cookie sessions, processing consent, idle cleanup, source deletion, clear workspace |
| Safety controls | SQL AST checks, function/table allowlists, SQLite query-only mode, time/row limits, public-URL DNS pinning, escaped model output |
| Sample workspace | Fictional strategy, handbook, support review, sales, support, inventory and invoices |
| Delivery | Dockerfile, pinned requirements, tests, setup guide, architecture and security notes |
## Sample questions and verifiable answers
- **Did we achieve the October 2026 revenue target?** Actual revenue: USD 165,000; document target: USD 180,000; shortfall: USD 15,000 (8.33%).
- **How many support tickets did we get each week in October 2026?** 312, 368, 551, 409, 325. Week 3 to Week 5 fell 41.02%. The review records an association with an update, not proven causation.
- **How much leave can carry over?** Up to 5 days, expiring March 31.
- **Which products have more open orders than stock?** Beacon: 72 orders vs 48 in stock, a 24-unit shortfall.
- **Which invoices are more than 60 days overdue?** INV-1041 and INV-1042, totaling 22,700.
Sample data dates are explicit and fixed. It is never represented as live company data or the current calendar month.
## Project map
```text
backend/app.py API, session isolation, ingestion and streamed orchestration
backend/ai.py Groq planner and grounded answer prompts
backend/core.py Extraction, retrieval, local database and SQL validation
backend/web_sources.py Bounded public-page fetch and SSRF defenses
backend/remote_db.py Optional approved-host SQL and MongoDB connectors
static/ Custom interface (no frontend build step or CDN dependency)
tests/ Core, API, isolation, SQL, URL and browser tests
examples/ Sample files, CSV and SQLite for upload testing
Dockerfile Hugging Face / local container
.env.example Configuration template, no secrets
requirements.txt Runtime dependency pins
requirements-dev.txt Test/browser dependencies
```
## Intentional scope and limits
This is a session-based public product demo, **not an enterprise account/billing service**. It has no signup, organization management, persistent account storage, SSO, billing, background indexing, audit ledger or formal compliance certification. Those are outside the requested no-signup deployment.
Private sources are separated between sessions, but relevant excerpts, schema, questions and bounded results are sent to **Groq**. Calling the UI “private” does not mean the model runs locally. Hosting this container on your own server still uses Groq for inference.
Retrieval uses local word/character TF-IDF plus an LLM-generated search query; it requires no embedding downloads. It is good for lightweight demos but not a substitute for a production semantic/vector retrieval stack over millions of documents. AI citations point to real supplied excerpts; automated checks detect missing/unknown citation IDs but cannot prove every generated statement is correct.
File limits: 15 MB each; 80 PDF pages including at most 10 scanned pages; 20 sources; 600,000 extracted characters per document and 1.5 million per session. CSV: 50,000 rows and 60 columns. Databases: 30 tables/collections with up to 60 columns described per table. Query output: 200 rows maximum; provider context uses a smaller bounded subset and reports truncation. Web ingestion does not execute JavaScript or authenticate.
Remote connectors are included but require your own reachable database and read-only account. MongoDB does not support aggregation in this version. SQL functions outside the conservative allowlist are intentionally blocked. Charts are deterministic from actual results; categorical labels plus numeric values generate a bar chart, otherwise the table remains available.
## Validation
```bash
pip install -r requirements-dev.txt
python -m pytest -q
```
See [validation notes](docs/VALIDATION.md) for exact checks and external-service limitations. See [architecture and privacy](docs/ARCHITECTURE.md) before opening the demo to visitors.
## Branding
Change the product name and agency attribution in `static/index.html`; colors live in `static/style.css` under `:root`; update `static/favicon.svg` and the README metadata. This package is branded **Northstar by GenZab Technology** as an editable default.