{"id":47713469,"url":"https://github.com/levelupbm/frank-bot","last_synced_at":"2026-04-04T20:01:25.765Z","repository":{"id":347905669,"uuid":"1195066764","full_name":"LevelUpBM/frank-bot","owner":"LevelUpBM","description":"Frank Bot — RAG-powered AI assistant for any business. Built on ChromaDB + Claude. Drop in your docs, ask Frank anything.","archived":false,"fork":false,"pushed_at":"2026-03-30T00:57:16.000Z","size":38,"stargazers_count":16,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T20:02:36.864Z","etag":null,"topics":["anthropic","document-qa","enterprise-ai","flask","hr-automation","llm","python","rag","self-hosted"],"latest_commit_sha":null,"homepage":"https://frankbot.lvlup.au/","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/LevelUpBM.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-03-29T07:03:27.000Z","updated_at":"2026-04-03T05:43:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LevelUpBM/frank-bot","commit_stats":null,"previous_names":["levelupbm/frank-bot"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/LevelUpBM/frank-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LevelUpBM%2Ffrank-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LevelUpBM%2Ffrank-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LevelUpBM%2Ffrank-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LevelUpBM%2Ffrank-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LevelUpBM","download_url":"https://codeload.github.com/LevelUpBM/frank-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LevelUpBM%2Ffrank-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31411654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T19:29:44.979Z","status":"ssl_error","status_checked_at":"2026-04-04T19:29:11.535Z","response_time":60,"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":["anthropic","document-qa","enterprise-ai","flask","hr-automation","llm","python","rag","self-hosted"],"created_at":"2026-04-02T18:42:51.106Z","updated_at":"2026-04-04T20:01:25.727Z","avatar_url":"https://github.com/LevelUpBM.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Frank Bot 🤖\n\n**RAG-powered AI assistant for any business. Drop in your documents. Ask Frank anything.**\n\nFrank is a production-ready AI chatbot platform built on:\n- **ChromaDB** — local vector store, no external embedding API needed\n- **Claude (Anthropic)** — LLM backend\n- **Flask** — lightweight Python web server\n- **Sentence Transformers** — local embeddings (all-MiniLM-L6-v2)\n\nThe client supplies their own Anthropic API key. Their documents never leave their server.\n\n\u003cimg width=\"2852\" height=\"1378\" alt=\"image\" src=\"https://github.com/user-attachments/assets/d30302b4-4735-4380-ac2a-3b962e4a0172\" /\u003e\n\n---\n\n## How It Works\n\n```\nClient uploads docs (PDF/DOCX/TXT)\n         ↓\nFrank chunks + embeds them into ChromaDB (local, self-hosted)\n         ↓\nUser asks a question in the chat UI\n         ↓\nRAG engine retrieves top-k relevant chunks\n         ↓\nClaude answers using only the retrieved context\n         ↓\nGrounded, document-based response — no hallucination\n```\n\u003cimg width=\"2805\" height=\"1342\" alt=\"image\" src=\"https://github.com/user-attachments/assets/21b62283-50f2-4adb-b70b-a1cd448df542\" /\u003e\n\n---\n\n## Architecture\n\n```\nfrank-bot/\n├── run_bot.py              # Universal entrypoint (systemd / Docker)\n├── shared/\n│   ├── frank_bot.py        # FrankBot class — Flask app, all endpoints, chat UI\n│   ├── rag_engine.py       # ChromaDB RAG store — chunk, embed, retrieve, build context\n│   └── bot_config.py       # BotConfig schema — tier limits, add-ons, env loading\n├── clients/\n│   └── vertical_prompts.py # 12 industry-tuned prompt personalities (Layer 1/2/3 system)\n├── examples/\n│   └── demo_config.json    # Example bot config\n└── docs/\n    └── SETUP.md            # Deployment guide\n```\n\u003cimg width=\"2742\" height=\"1235\" alt=\"image\" src=\"https://github.com/user-attachments/assets/bc305a9a-6cee-41e5-915e-38bcaf1811b4\" /\u003e\n\n---\n\n## Vertical Personalities\n\nFrank ships with tuned system prompts for 12 industry verticals:\n\n| Vertical | Description |\n|---|---|\n| 💼 HR \u0026 Workplace | Any industry — policy, entitlements, Fair Work |\n| ⛏️ Resources \u0026 Mining | FIFO, WHS, EBA, site safety |\n| 🏗️ Construction | SWMS, white card, subcontractors, EBA |\n| 🏥 Aged Care | SIRS, Quality Standards, SCHADS Award |\n| 🏛️ Local Government | Governance, LG Award, PID, procurement |\n| ⚕️ Healthcare | AHPRA, NSQHS, scope of practice |\n| 🎓 Education | Child Safe, mandatory reporting, ASQA |\n| 📊 Finance \u0026 Professional | AFS licence, AML/CTF, AFCA |\n| 📋 Project Management | Document retrieval, scope, risk, workstreams |\n| 🦺 Safety \u0026 WHS | Notifiable incidents, permits, PCBU duties |\n| 🏗️ Building \u0026 Architecture | NCC, DA/CC, drawing interpretation |\n| 🔧 Custom | Fully custom — define your own personality |\n\nEach vertical uses a layered prompt architecture:\n- **Layer 1** — Universal security, confidentiality, distress protocols (always on)\n- **Layer 2** — Vertical personality and domain knowledge (swappable)\n- **Layer 3** — Client-specific custom instructions (additive only)\n\n---\n\n## Quick Start\n\n### 1. Install dependencies\n\n```bash\npip install flask anthropic chromadb pdfplumber pypdf python-docx sentence-transformers\n```\n\n### 2. Configure your bot\n\n```bash\ncp examples/demo_config.json /opt/frankbot/config.json\n# Edit config.json — set company_name, vertical, bot_id\n```\n\n### 3. Set your API key\n\n```bash\nexport LLM_API_KEY=sk-ant-...\n```\n\n### 4. Run\n\n```bash\npython run_bot.py\n# → http://localhost:8080\n```\n\n---\n\n## Configuration\n\nAll config lives in `config.json` (or environment variables).\n\n```json\n{\n  \"bot_id\": \"acme-hr\",\n  \"bot_name\": \"Frank\",\n  \"company_name\": \"Acme Resources\",\n  \"vertical\": \"hr_resources\",\n  \"tier\": \"professional\",\n  \"llm_provider\": \"anthropic\",\n  \"llm_model\": \"claude-haiku-4-5\",\n  \"rag_enabled\": true,\n  \"rag_top_k\": 15,\n  \"max_docs\": 30,\n  \"max_doc_size_mb\": 10,\n  \"forms_enabled\": true,\n  \"port\": 8080\n}\n```\n\n### Tiers\n\n| Tier | Max Docs | Max Doc Size | Forms |\n|---|---|---|---|\n| Starter | 10 | 5 MB | 1 |\n| Professional | 30 | 10 MB | 3 |\n| Enterprise | 100 | 20 MB | 5 |\n\n---\n\n## RAG Engine\n\nThe core of Frank is `shared/rag_engine.py`:\n\n```python\nfrom shared.rag_engine import FrankRAGStore\n\nstore = FrankRAGStore(bot_id=\"acme-hr\", persist_dir=\"/opt/frankbot/chroma\")\n\n# Index a document\nstore.index_document(\"Leave Policy\", leave_policy_text)\n\n# Retrieve relevant chunks\nchunks = store.retrieve(\"how much annual leave do I get?\", top_k=5)\n\n# Build context string for injection into system prompt\ncontext = store.build_context(\"how much annual leave do I get?\")\n```\n\n### Key features\n\n- **Local embeddings** — sentence-transformers, no external API\n- **Query expansion** — Claude Haiku generates 4 alternative phrasings, merged results\n- **Source boost** — named documents in queries guaranteed to be retrieved\n- **Clean re-index** — re-uploading a document replaces all its chunks atomically\n- **Overlap chunking** — 400-word chunks with 80-word overlap, paragraph-aware\n\n---\n\n## Prompt Architecture\n\n```python\nfrom clients.vertical_prompts import get_vertical_personality, get_layer1_always\n\n# Build system prompt\nsystem = f\"\"\"\n{get_vertical_personality(\"hr_resources\")}\n\n## Your organisation\nCompany: Acme Resources\nCustom instructions: Always refer to the EBA for pay questions.\n\n{get_layer1_always()}\n\n## Context from documents:\n{context}\n\"\"\"\n```\n\nLayer 1 is injected **last** — it always takes precedence over custom instructions.\n\n---\n\n## Deployment\n\nFrank is designed to run as a systemd service on a Linux VM:\n\n```ini\n[Unit]\nDescription=Frank Bot — Acme Resources\nAfter=network.target\n\n[Service]\nWorkingDirectory=/opt/frankbot/app\nExecStart=/opt/frankbot/venv/bin/python3 run_bot.py\nRestart=always\nEnvironmentFile=/opt/frankbot/.env\n\n[Install]\nWantedBy=multi-user.target\n```\n\nOne droplet per client. Each bot is isolated — documents, ChromaDB store, and API keys never shared.\n\n---\n\n## Built by\n\n[LevelUp](https://lvlup.au) — AI systems for Australian workplaces.\n\nFrank is deployed across HR, construction, mining, aged care, and local government organisations.\n\n---\n\n## Licence\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevelupbm%2Ffrank-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flevelupbm%2Ffrank-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevelupbm%2Ffrank-bot/lists"}