{"id":50314919,"url":"https://github.com/miclaldogan/bantz","last_synced_at":"2026-05-28T23:03:53.415Z","repository":{"id":334741681,"uuid":"1142511078","full_name":"miclaldogan/bantz","owner":"miclaldogan","description":"Local-first AI assistant for Linux — LLM-powered tool orchestration with calendar, email, browser automation. 3B router + Gemini finalizer, privacy-first.","archived":false,"fork":false,"pushed_at":"2026-02-18T17:55:22.000Z","size":16348,"stargazers_count":0,"open_issues_count":30,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2026-02-18T18:26:30.920Z","etag":null,"topics":["ai-assistant","browser-automation","gemini","gmail","google-calendar","jarvis","linux","llm","local-assistant","local-first","natural-language-processing","privacy-first","python","qwen","tool-orchestration","turkish","vllm"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/miclaldogan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap-v1.md","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-26T14:05:55.000Z","updated_at":"2026-02-18T16:03:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/miclaldogan/bantz","commit_stats":null,"previous_names":["miclaldogan/bantz"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/miclaldogan/bantz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miclaldogan%2Fbantz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miclaldogan%2Fbantz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miclaldogan%2Fbantz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miclaldogan%2Fbantz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/miclaldogan","download_url":"https://codeload.github.com/miclaldogan/bantz/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miclaldogan%2Fbantz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33629562,"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-05-28T02:00:06.440Z","response_time":99,"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":["ai-assistant","browser-automation","gemini","gmail","google-calendar","jarvis","linux","llm","local-assistant","local-first","natural-language-processing","privacy-first","python","qwen","tool-orchestration","turkish","vllm"],"created_at":"2026-05-28T23:03:53.304Z","updated_at":"2026-05-28T23:03:53.398Z","avatar_url":"https://github.com/miclaldogan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/bantz.png\" alt=\"Bantz\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eBantz\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLocal-first AI assistant for Linux — tools, not just chat.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#what-is-bantz\"\u003eWhat is Bantz?\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#hud-overlay\"\u003eHUD Overlay\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Python 3.10+\" src=\"https://img.shields.io/badge/python-3.10%2B-blue?logo=python\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Ollama\" src=\"https://img.shields.io/badge/Ollama-qwen2.5--coder:7b-black?logo=ollama\" /\u003e\n  \u003cimg alt=\"Gemini Flash\" src=\"https://img.shields.io/badge/Gemini-2.0_Flash-4285F4?logo=google\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Electron\" src=\"https://img.shields.io/badge/Electron-HUD_Overlay-47848F?logo=electron\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"SQLite\" src=\"https://img.shields.io/badge/SQLite-IngestStore-003B57?logo=sqlite\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Proprietary-lightgrey\" /\u003e\n  \u003cimg alt=\"Open Issues\" src=\"https://img.shields.io/github/issues/miclaldogan/bantz?color=orange\" /\u003e\n\u003c/p\u003e\n\n---\n\n## What is Bantz?\n\nBantz is a **local-first AI assistant** that runs on your Linux desktop and actually *does things* — manages your calendar, reads your email, controls your browser, runs system commands, and more. It connects a fast local LLM (Ollama) with 76+ registered tools through a structured brain pipeline.\n\nUnlike cloud-only assistants, Bantz keeps your data local. Unlike chatbots, Bantz executes real actions with a confirmation firewall for anything destructive.\n\n**Current direction:** We're building toward a *smarter* assistant — better reasoning, persistent memory, observable tool execution, and a live data platform. The goal is an AI that genuinely understands your context across sessions, not just responds to one-off prompts.\n\n### Key Capabilities\n\n| Area | What it does | Backend |\n|:-----|:-------------|:--------|\n| **Calendar** | Create, update, cancel events; find free slots; natural date parsing | Google Calendar API |\n| **Email** | List inbox, read, draft, reply, send with confirmation; real-time briefing cards | Gmail API + IngestStore |\n| **Classroom** | List courses, assignments, enrollment via link; OAuth scope dialog | Google Classroom API |\n| **Contacts** | Lookup, manage Google Contacts | Google People API |\n| **Web Search** | Real-time search, page extraction | Chromium extension |\n| **Weather** | Current weather \u0026 forecast for any city | wttr.in |\n| **Browser** | Open URLs, extract page content, tab management | Chromium extension + WebSocket |\n| **System** | Screenshot, clipboard, notifications, app launch, disk info | D-Bus + native |\n| **Terminal** | Execute commands in a sandboxed environment | Subprocess with guardrails |\n| **Phone Calls** | Manage call actions (Linux audio/phone integrations) | system tools |\n| **PDF** | Text extraction and summarization from local files | pdfminer |\n| **HUD Overlay** | Always-on-top transparent desktop UI — news, inbox, calendar, system, GitHub | Electron |\n| **Data Sync** | Gmail / Calendar / Classroom → SQLite with TTL, fingerprint dedup, auto-scheduler | IngestStore + SyncScheduler |\n| **Voice** | Wake word → ASR → IPC bridge → TTS word-boundary sync | Faster Whisper + Piper |\n\n### How it works (30-second version)\n\n```\nYou say something → PreRouter classifies intent → LLM Router picks tools\n→ Tools execute (with confirmation if destructive) → Finalizer writes the response\n```\n\nThe router runs locally via Ollama (~50 ms). When the task needs polished writing or complex reasoning, a tiered quality gate escalates to Gemini 2.0 Flash.\n\n---\n\n## Project Status\n\n\u003e **Bantz is in active early development.** The repo was started in January 2026 and is evolving rapidly. Expect breaking changes, incomplete features, and rough edges. We're building in the open — contributions and feedback are welcome.\n\n| Milestone | Status |\n|:----------|:-------|\n| Core brain pipeline (route → execute → finalize) | ✅ Shipped (v0.2.0) |\n| 76+ tools across 14 categories | ✅ Shipped |\n| Google Calendar + Gmail golden paths | ✅ Shipped |\n| Confirmation firewall for destructive ops | ✅ Shipped |\n| LanguageBridge (TR↔EN translation layer) | ✅ Shipped |\n| Data platform — IngestStore + TTL cache | ✅ Shipped |\n| Data sync scheduler — Gmail/Calendar/Classroom | ✅ Shipped |\n| Electron HUD overlay + IPC pipeline | ✅ Shipped |\n| Voice mode — wake word + ASR + TTS sync | ✅ Shipped |\n| Google Classroom integration + OAuth UI | ✅ Shipped |\n| PDF extraction \u0026 summarization | ✅ Shipped |\n| Startup briefing — real Gmail cards to InboxPanel | ✅ Shipped |\n| Observability — structured run/tool/artifact DB | 🔄 Planned (#1290) |\n| Graph memory — persistent cross-session context | 🔄 Planned (#1289) |\n\n---\n\n## Quickstart\n\n### Prerequisites\n\n- **Linux** (Ubuntu 22.04+ recommended)\n- **Python 3.10+**\n- **Node.js 18+** (for the HUD overlay)\n- **Ollama** installed and running ([install guide](https://ollama.com/download))\n\n### 1. Install Ollama \u0026 pull the router model\n\n```bash\ncurl -fsSL https://ollama.com/install.sh | sh\nollama pull qwen2.5-coder:7b\n```\n\n### 2. Clone \u0026 install Bantz\n\n```bash\ngit clone https://github.com/miclaldogan/bantz.git\ncd bantz\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[all]\"\n```\n\n### 3. Configure\n\n```bash\ncp config/bantz-env.example ~/.config/bantz/env\n```\n\nMinimum required in `~/.config/bantz/env`:\n\n```bash\n# Local LLM (Ollama)\nBANTZ_OLLAMA_MODEL=\"qwen2.5-coder:7b\"\n\n# Optional: Gemini for quality-tier finalization\nBANTZ_CLOUD_ENABLED=true\nGEMINI_API_KEY=your_key_here\nBANTZ_GEMINI_MODEL=gemini-2.0-flash\n```\n\n### 4. Run\n\n```bash\n# System health check\npython3 -m bantz doctor\n\n# Interactive assistant (starts daemon + Unix socket)\npython3 -m bantz --serve\n\n# Single command\npython3 -m bantz --once \"what meetings do I have today?\"\n\n# Start HUD overlay (separate terminal)\ncd bantz-overlay \u0026\u0026 npm install \u0026\u0026 npm start\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eGoogle OAuth setup (Calendar, Gmail, Classroom)\u003c/summary\u003e\n\n1. Place your Google Cloud OAuth client secret at `~/.config/bantz/google/client_secret.json`\n2. Authenticate:\n\n   ```bash\n   bantz google auth calendar --write\n   bantz google auth gmail --scope readonly\n   bantz google auth classroom\n   ```\n\nFull guide: [docs/setup/google-oauth.md](docs/setup/google-oauth.md)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eOptional: Enable Gemini for polished responses\u003c/summary\u003e\n\nFor high-quality email drafts, long summaries, and better prose:\n\n```bash\nBANTZ_CLOUD_ENABLED=true\nGEMINI_API_KEY=your_key_here\nBANTZ_GEMINI_MODEL=gemini-2.0-flash\n```\n\nSee [docs/secrets-hygiene.md](docs/secrets-hygiene.md) for key management best practices.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall as systemd service (auto-start)\u003c/summary\u003e\n\n```bash\nbash scripts/install_services.sh\nsystemctl --user enable --now bantz.service\n```\n\nThe HUD overlay auto-starts via XDG autostart when `BANTZ_OVERLAY_AUTOSTART=true`.\n\n\u003c/details\u003e\n\n---\n\n## Architecture\n\n```\n┌────────────────────────────────────────────────────────────────────┐\n│                            BANTZ                                   │\n│                                                                    │\n│  ┌─────────────┐   ┌────────────────┐   ┌──────────────────────┐  │\n│  │  Electron   │   │   CLI /         │   │  Chromium Extension  │  │\n│  │  HUD Overlay│   │ python3 -m bantz│   │  (bantz-extension)   │  │\n│  └──────┬──────┘   └───────┬─────────┘   └──────────┬───────────┘  │\n│         │   Unix IPC       │                         │              │\n│         └──────────────────┼─────────────────────────┘              │\n│                            ▼                                        │\n│                  ┌─────────────────┐                                │\n│                  │   BantzServer   │   Unix socket + FastAPI :8088   │\n│                  └────────┬────────┘                                │\n│                           ▼                                         │\n│  ┌───────────────────────────────────────────────────────────────┐  │\n│  │                    Brain Pipeline                             │  │\n│  │                                                               │  │\n│  │  PreRouter ──► LLM Router ──► Tool Executor                  │  │\n│  │  (fast bypass)  (Ollama,       (76+ tools,                   │  │\n│  │                  ~50ms)         confirmation firewall)         │  │\n│  │                      │                    │                   │  │\n│  │                      ▼                    ▼                   │  │\n│  │               Quality Gate ──► Tiered Finalizer               │  │\n│  │               (complexity ×    Fast: local Ollama             │  │\n│  │                writing ×       Quality: Gemini Flash           │  │\n│  │                risk score)     Draft: template                │  │\n│  └───────────────────────────────────────────────────────────────┘  │\n│                                                                     │\n│  ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐  │\n│  │ Calendar  │ │  Gmail   │ │Classroom │ │  Browser │ │System  │  │\n│  │  Tools    │ │  Tools   │ │  OAuth   │ │  Tools   │ │ Tools  │  │\n│  └───────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘  │\n│                                                                     │\n│  ┌───────────────────────────────────────────────────────────────┐  │\n│  │          Data Layer — SQLite (IngestStore + SyncScheduler)    │  │\n│  │  Gmail ──► EPHEMERAL (24h)   │  Calendar ──► EPHEMERAL (24h) │  │\n│  │  Classroom ──► SESSION (7d)  │  Contacts ──► PERSISTENT      │  │\n│  └───────────────────────────────────────────────────────────────┘  │\n└─────────────────────────────────────────────────────────────────────┘\n        │                                          │\n        ▼                                          ▼\n  ┌───────────┐                            ┌───────────┐\n  │  Ollama   │  qwen2.5-coder:7b          │  Gemini   │  2.0 Flash\n  │  (local)  │  router + fast-tier         │  (cloud)  │  quality-tier\n  └───────────┘                            └───────────┘\n```\n\n### Pipeline Flow\n\n1. **Input** arrives from CLI, HUD overlay, browser extension, or voice\n2. **PreRouter** classifies intent — greetings and simple queries bypass the LLM entirely\n3. **LLM Router** (qwen2.5-coder:7b via Ollama) generates a structured JSON plan: route, intent, slots, tool_plan\n4. **JSON Repair** fixes common small-model mistakes — wrong enums, type mismatches, truncated output\n5. **Tool Executor** runs planned tools through the confirmation firewall (destructive ops require approval)\n6. **Quality Gate** scores the response need: `0.35×complexity + 0.45×writing + 0.20×risk`\n7. **Tiered Finalizer** picks the right backend:\n   - **Quality tier** → Gemini 2.0 Flash (polished prose, complex reasoning)\n   - **Fast tier** → local LLM (sub-200ms, good enough for simple replies)\n   - **Draft tier** → deterministic template (no LLM call needed)\n\n### Key Design Decisions\n\n| Decision | Rationale |\n|:---------|:----------|\n| **Local-first** | Your data stays on your machine. Cloud (Gemini) is opt-in for quality. |\n| **Tool-centric** | The assistant's value comes from *doing things*, not generating text. |\n| **Tiered finalization** | Not every response needs a cloud call. Smart routing saves latency and cost. |\n| **Confirmation firewall** | Destructive operations (delete, shutdown, send) always require explicit approval. |\n| **LanguageBridge** | Transparent TR↔EN translation so the English-trained model works natively with any language input. |\n| **JSON repair at every layer** | Small models produce imperfect JSON. Deterministic + LLM-based repair catches it. |\n| **IngestStore TTL cache** | Google data (Gmail, Calendar, Classroom) synced locally to SQLite — tools query local cache, not the API every time. |\n\n### LLM Router Benchmarks\n\nBenchmarked on **RTX 4050 Laptop GPU (6 GB VRAM)**. Models receive an enriched English system prompt with explicit RULES block and must return a structured JSON routing decision across 10 test queries (calendar, gmail, system, smalltalk, news intents). Input is always English — LanguageBridge translates TR→EN before the model sees it.\n\n\u003e ⚠️ Results are from a 10-query micro-benchmark on the specific prompt/intent set used, not a broad held-out evaluation.\n\n#### Current Setup — Enriched Prompt, Ollama Only (full GPU)\n\n| Model | Params | Quant | Cold Start | Warm Latency | Throughput | Routing (10 q) | Thinking |\n|:------|:-------|:------|:-----------|:-------------|:-----------|:---------------|:---------|\n| **qwen2.5-coder:7b** ⭐ | 7B | Q4_K_M | 3.6s | **0.34s** | **35.5 t/s** | 10/10 | — |\n| **qwen2.5:7b** | 7B | Q4_K_M | 3.1s | **0.36s** | **35.0 t/s** | 10/10 | — |\n| **nanbeige4.1-3B** 🧠 | 3.9B | Q8_0 | 4.2s | **0.46s** | **40.6 t/s** | 10/10 | ✅ |\n| **gpt-oss:20b** | 20B | Q4_K_M | 6.9s | 4.71s | 10.9 t/s | 10/10 | — |\n\n\u003e **Key Findings:**\n\u003e - **Enriched RULES prompt** was the main differentiator — models went from 6-8/10 to 10/10 on this test set.\n\u003e - **Freeing vLLM's 2.75 GB VRAM → 3× throughput boost** for all Ollama models (e.g., qwen2.5-coder: 11 → 35 t/s).\n\u003e - **qwen2.5-coder:7b** ⭐ chosen as production router: best warm latency (0.34s) + good throughput.\n\n---\n\n## HUD Overlay\n\nThe **bantz-overlay** is an always-on-top transparent Electron desktop UI. It connects to the Bantz daemon via Unix IPC and renders live assistant output directly on your desktop.\n\n### Panels\n\n| Panel | What it shows |\n|:------|:--------------|\n| **Particle Sphere** | Interactive 3D sphere — idle/listening/processing state |\n| **Inbox Panel** | Gmail messages from daemon briefing (last 5, unread highlighted); calendar events; system alerts |\n| **News Feed** | Live news cards with images from the proactive news service |\n| **Daily Tasks** | Calendar events for today, sourced from Google Calendar sync |\n| **System Status** | CPU, RAM, disk, uptime — live metrics terminal panel |\n| **GitHub Feed** | GitHub activity, pull requests, notifications |\n| **Clock Panel** | Live clock with timezone awareness |\n| **Typewriter** | Token-by-token speech output — real-time assistant response |\n| **Reasoning Chain** | Shows the assistant's active thought steps |\n| **Text Input** | Floating draggable text input — send queries from the overlay |\n| **Phone Call Overlay** | In-call UI for active phone call actions |\n\n### Startup Briefing\n\nOn daemon start, the overlay boots a sequenced briefing:\n\n1. **Greeting** — time-aware hello\n2. **News cards** — top headlines with images\n3. **Calendar cards** — today's events\n4. **Weather card** — current conditions\n5. **System metrics card** — CPU/RAM/disk snapshot\n6. **Mail cards** — last 5 Gmail messages (sender, subject, unread status) from IngestStore\n\n### Google Auth HUD Badge\n\nA persistent badge in the overlay corner shows Google service connection state — connected (green), disconnected (grey), or pending (amber). Clicking the badge triggers re-authentication for any disconnected scope.\n\n---\n\n## Roadmap\n\nBantz is evolving toward a **GAIA-inspired intelligent platform** — not just a tool executor, but an assistant with persistent memory, observable behavior, and proactive capabilities.\n\n### Master Plan → [#1300](https://github.com/miclaldogan/bantz/issues/1300)\n\n**Phase A — Data Platform**\n\n| EPIC | What | Status |\n|:-----|:-----|:-------|\n| [#1288](https://github.com/miclaldogan/bantz/issues/1288) | Ingest Store — TTL cache + fingerprint dedup | ✅ Done |\n| [#1466](https://github.com/miclaldogan/bantz/issues/1466) | Gmail + Calendar + Classroom → IngestStore ingestion pipeline | ✅ Done |\n| [#1469](https://github.com/miclaldogan/bantz/issues/1469) | Startup briefing — real Gmail data to InboxPanel | ✅ Done |\n| [#1290](https://github.com/miclaldogan/bantz/issues/1290) | Observability — runs, tool calls, artifacts DB | 🔄 Next |\n| [#1291](https://github.com/miclaldogan/bantz/issues/1291) | Policy Engine v2 — risk tiers, param editing, redaction | 🔄 Planned |\n| [#1297](https://github.com/miclaldogan/bantz/issues/1297) | Event Bus — async pub/sub internal messaging | 🔄 Planned |\n| [#1298](https://github.com/miclaldogan/bantz/issues/1298) | Graceful Degradation — circuit breaker + fallback | 🔄 Planned |\n| [#1289](https://github.com/miclaldogan/bantz/issues/1289) | Graph Memory — persistent cross-session context | 🔄 Planned |\n\n**Phase B — Intelligence Layer**\n\n| EPIC | What |\n|:-----|:-----|\n| [#1293](https://github.com/miclaldogan/bantz/issues/1293) | Proactive Secretary — daily briefs, signals, suggestions |\n| [#1295](https://github.com/miclaldogan/bantz/issues/1295) | PC Agent + Coding Agent — sandbox execution |\n| [#1292](https://github.com/miclaldogan/bantz/issues/1292) | Google Suite Super-Connector — unified OAuth, Contacts/Tasks/Keep |\n| [#1294](https://github.com/miclaldogan/bantz/issues/1294) | Controlled Messaging — read → draft → confirm → send |\n\n**Phase C — Extended Capabilities**\n\n| EPIC | What |\n|:-----|:-----|\n| [#1296](https://github.com/miclaldogan/bantz/issues/1296) | Music Control — Spotify/local player integration |\n| [#1299](https://github.com/miclaldogan/bantz/issues/1299) | Future Skills — finance, file search, travel, health |\n\n---\n\n## Project Structure\n\n```\nbantz/\n├── src/bantz/               # Main Python package (python3 -m bantz)\n│   ├── __main__.py          # Entry point → cli.py\n│   ├── cli.py               # Interactive \u0026 single-shot CLI\n│   ├── server.py            # Unix socket daemon + startup briefing (BantzServer)\n│   ├── daemon.py            # Systemd-friendly daemon wrapper\n│   ├── api/                 # FastAPI REST server (port 8088)\n│   │\n│   ├── brain/               # Orchestrator, router, finalizer, quality gating\n│   ├── llm/                 # LLM clients: Ollama + Gemini, tiered scoring\n│   ├── router/              # Intent router: schemas, prompts, handlers\n│   ├── tools/               # 76+ tools (calendar, gmail, browser, system, pdf…)\n│   │\n│   ├── data/                # Data platform\n│   │   ├── ingest_store.py  # SQLite TTL cache with fingerprint dedup\n│   │   ├── ingest_bridge.py # Bridge: sync results → IngestStore\n│   │   ├── run_tracker.py   # Run/tool call tracking\n│   │   ├── graph_store.py   # Graph memory backend\n│   │   └── sync/            # Sync schedulers: gmail_sync, calendar_sync, news_sync\n│   │\n│   ├── services/            # Background services\n│   │   ├── daily_briefing.py    # Startup briefing builder\n│   │   ├── startup_hook.py      # Briefing orchestration hook\n│   │   ├── news_service.py      # Proactive news aggregation\n│   │   └── time_context.py      # Time-aware context helper\n│   │\n│   ├── google/              # Google APIs: Calendar, Gmail, OAuth, Contacts\n│   ├── connectors/google/   # Unified Google auth manager + Classroom connector\n│   │\n│   ├── memory/              # Session + persistent memory (SQLite)\n│   ├── policy/              # Permission engine, confirmation firewall\n│   ├── voice/               # ASR, TTS, wake word (Faster Whisper + Piper)\n│   ├── browser/             # Browser automation bridge (WebSocket)\n│   ├── i18n/                # LanguageBridge: transparent TR↔EN translation\n│   └── privacy/             # PII redaction\n│\n├── bantz-overlay/           # Electron HUD overlay (always-on-top transparent UI)\n│   └── src/renderer/\n│       ├── renderer.js      # IPC dispatcher, briefing handler, panel routing\n│       └── components/      # inbox-panel, news-feed, github-feed, sphere, tts-sync…\n│\n├── bantz-extension/         # Chromium browser extension\n├── bantz-browser/           # Browser companion app\n│\n├── tests/                   # Test suite (pytest + pytest-asyncio)\n├── scripts/                 # Smoke tests, e2e, install helpers\n├── config/                  # Env templates, model settings, policies, YAML configs\n├── docs/                    # Architecture docs, setup guides, roadmap\n│\n├── _legacy/                 # Archived: vLLM backend, old demo/bench scripts\n│\n└── pyproject.toml           # Package config (hatchling)\n```\n\n### How to Start\n\n```bash\n# Start the daemon (Unix socket + FastAPI on :8088)\npython3 -m bantz --serve\n\n# Single command\npython3 -m bantz --once \"bugün hangi toplantılarım var?\"\n\n# System check\npython3 -m bantz doctor\n\n# Start HUD overlay (requires Node.js 18+)\ncd bantz-overlay \u0026\u0026 npm install \u0026\u0026 npm start\n```\n\n---\n\n## Testing\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run all unit tests\npytest tests/ -v\n\n# Golden path E2E tests (calendar + inbox flows)\npytest tests/ -v --run-golden-path\n\n# Regression tests (top recurring bugs)\npytest tests/ -v --run-regression\n\n# Integration tests (requires running Ollama)\npytest tests/ -v --run-integration\n```\n\n### Test Coverage\n\n| Area | Description |\n|:-----|:------------|\n| Golden Path E2E | Calendar + inbox end-to-end flows, failure modes |\n| Regression Suite | Turkish anaphora, context overflow, unicode edge cases |\n| JSON Repair | 58 golden tests for markdown fencing, truncation, type errors |\n| Tiered Scoring | Quality gating with complexity/writing/risk scoring |\n| Orchestrator | Multi-turn conversation, tool execution, error recovery |\n| Confirmation Firewall | Destructive operation blocking and risk classification |\n| Router Schemas | Pydantic validation, enum repair, type coercion |\n| IngestStore Sync | Gmail/Calendar/Classroom → SQLite ingestion pipeline (issue #1466) |\n| Classroom OAuth UI | Classroom dialog + scope indicator components (issue #1467) |\n| Google Auth HUD Badge | Connection state indicator component (issue #1468) |\n| Gmail Briefing Cards | Startup briefing mail cards — AC1-AC3 coverage (issue #1469) |\n| Overlay Components | news-image-popup, renderer contract tests, IPC golden path |\n\n---\n\n## Contributing\n\nWe're building Bantz in the open and welcome contributions. The project is young — there's plenty of room to make an impact.\n\n### Getting Started\n\n```bash\ngit clone https://github.com/miclaldogan/bantz.git\ncd bantz\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[all]\"\npytest tests/ -v --tb=short\n```\n\n### Development Workflow\n\n- All PRs target the `dev` branch\n- Branch naming: `feat/123-description`, `fix/123-description`, `chore/123-description`\n- Commit format: `type(scope): description` ([Conventional Commits](https://www.conventionalcommits.org/))\n- See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide\n\n### PR Quality Gates\n\nEvery pull request goes through automated checks:\n\n| Check | What it does |\n|:------|:-------------|\n| **Ruff lint** | Style + import order (diff-based, only changed files) |\n| **pytest** | Full test suite must pass |\n| **Bandit SAST** | Security scan for common vulnerabilities |\n| **Safety** | Dependency CVE check |\n| **CodeRabbit** | AI-powered code review with project-aware context |\n| **Copilot Review** | Automated review following project conventions |\n\n---\n\n## Documentation\n\n| Document | Description |\n|:---------|:------------|\n| [docs/architecture.md](docs/architecture.md) | System architecture and pipeline flow |\n| [docs/setup/google-oauth.md](docs/setup/google-oauth.md) | Google Calendar, Gmail \u0026 Classroom OAuth setup |\n| [docs/confirmation-firewall.md](docs/confirmation-firewall.md) | Security firewall for destructive operations |\n| [docs/gemini-hybrid-orchestrator.md](docs/gemini-hybrid-orchestrator.md) | Hybrid local/cloud architecture |\n| [docs/secrets-hygiene.md](docs/secrets-hygiene.md) | API key and secrets best practices |\n| [docs/tool-catalog.md](docs/tool-catalog.md) | Complete tool reference (76 tools) |\n| [docs/data-platform-schema.md](docs/data-platform-schema.md) | IngestStore schema, TTL classes, sync scheduler |\n| [docs/voice-pipeline-e2e.md](docs/voice-pipeline-e2e.md) | End-to-end voice pipeline: ASR → IPC → TTS |\n| [docs/golden-paths.md](docs/golden-paths.md) | Calendar + inbox golden path flows |\n| [CHANGELOG.md](CHANGELOG.md) | Release notes |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines |\n| [SECURITY.md](SECURITY.md) | Security policy |\n\n---\n\n## License\n\nProprietary. Copyright © 2024–2026 Mıcıl Aldoğan. All Rights Reserved.\n\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiclaldogan%2Fbantz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiclaldogan%2Fbantz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiclaldogan%2Fbantz/lists"}