--- 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.