{"id":44816978,"url":"https://github.com/gerifield/hairy-botter","last_synced_at":"2026-05-02T03:13:58.485Z","repository":{"id":293469051,"uuid":"983317864","full_name":"Gerifield/hAIry-botter","owner":"Gerifield","description":"✨ Smart bots everywhere, let's have some magic ✨","archived":false,"fork":false,"pushed_at":"2026-03-24T23:23:18.000Z","size":5741,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-25T21:46:22.019Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gerifield.png","metadata":{"files":{"readme":"README.md","changelog":"history-gemini/.gitkeep","contributing":null,"funding":null,"license":"LICENSE","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":"2025-05-14T07:51:29.000Z","updated_at":"2026-03-24T23:23:20.000Z","dependencies_parsed_at":"2025-06-13T00:29:58.368Z","dependency_job_id":"e2a5839b-87a1-4ae7-be0f-968858ea2a9c","html_url":"https://github.com/Gerifield/hAIry-botter","commit_stats":null,"previous_names":["gerifield/hairy-botter"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/Gerifield/hAIry-botter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gerifield%2FhAIry-botter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gerifield%2FhAIry-botter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gerifield%2FhAIry-botter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gerifield%2FhAIry-botter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gerifield","download_url":"https://codeload.github.com/Gerifield/hAIry-botter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gerifield%2FhAIry-botter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: 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":["hacktoberfest"],"created_at":"2026-02-16T18:37:45.310Z","updated_at":"2026-04-02T00:02:02.603Z","avatar_url":"https://github.com/Gerifield.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://github.com/user-attachments/assets/10e49300-eb17-41a3-b8c9-affd399c8810\" width=\"250\" /\u003e\n\n# hAIry Botter 🪄 ✨\n\n**A flexible, HTTP-based AI Chatbot Server powered by Gemini via Firebase Genkit.**\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/yourusername/hairy-botter)](https://goreportcard.com/report/github.com/yourusername/hairy-botter)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Powered By Gemini](https://img.shields.io/badge/AI-Gemini-blue)](https://deepmind.google/technologies/gemini/)\n\n\u003c/div\u003e\n\n---\n\n## 📖 Overview\n\n**hAIry Botter** is a lightweight, backend-agnostic AI server designed to decouple the AI logic from the frontend. Inspired by the [WhatsApp Python Chatbot](https://github.com/YonkoSam/whatsapp-python-chatbot), this project aims to be more flexible by offering a simple HTTP API that supports history, context, and external tools.\n\nWhether you are building a CLI, a Telegram bot, or a web interface, you just need to make a simple HTTP call to hAIry Botter to get started.\n\n## ✨ Features\n\n* 🧠 **Genkit Powered:** Uses [Firebase Genkit](https://firebase.google.com/docs/genkit) as the AI framework, backed by Google Gemini models. Swapping providers (Vertex AI, Ollama, etc.) requires only a plugin change.\n* 🔌 **MCP Support:** Implements the **Model Context Protocol** to call external servers/functions via Genkit's MCP plugin (includes example implementation).\n* 💾 **Smart History:** Session-based history storage (`history-gemini` folder) with optional auto-summarization to save context window.\n* 📚 **RAG Capable:** Built-in Retrieval-Augmented Generation. Drop text documents into the `bot-context` folder to chat with your data.\n* 🎭 **Custom Personality:** Configurable system prompt via `personality.txt`.\n* 🖼️ **Multi-modal:** Native support for Image and PDF inputs.\n* 🚀 **Ready-to-use Clients:** Includes CLI, Telegram, and Facebook Messenger clients.\n\n---\n\n## 🚀 Quick Start\n\n### Option 1: Docker (Recommended)\n\nThe easiest way to get up and running is via Docker Compose.\n\n1.  Copy `.env.example` to `.env`.\n2.  Set your `GEMINI_API_KEY` in the file.\n3.  Run the stack:\n\n```bash\ndocker-compose up\n```\n\n### Option 2: Running from Source\n\n**Prerequisites:** Go installed on your machine.\n\n1.  Set the required environment variable:\n    ```bash\n    export GEMINI_API_KEY=\"your_api_key_here\"\n    ```\n2.  Run the server:\n    ```bash\n    go run cmd/server-bot/main.go\n    ```\n\n---\n\n## ⚙️ Configuration\n\nYou can configure the server using Environment Variables.\n\n| Variable | Description | Default | Required |\n| :--- | :--- | :--- | :---: |\n| `GEMINI_API_KEY` | Your Google Gemini API access key. | - | ✅ |\n| `ADDR` | Server listen address. | `:8080` | ❌ |\n| `GEMINI_MODEL` | The specific model version to use. | `gemini-flash-latest` | ❌ |\n| `MCP_SERVERS` | Comma-separated list of MCP HTTP stream servers (e.g., `http://localhost:8081/mcp`). | - | ❌ |\n| `GEMINI_SEARCH_DISABLED` | Set to `true` or `1` to disable Google Search grounding. Search is **enabled by default**. | `false` | ❌ |\n| `HISTORY_SUMMARY` | Message count trigger for history summarization (`0` to disable). | `20` | ❌ |\n| `LOG_LEVEL` | Logging verbosity (`debug`, `info`, `warn`, `error`). | `info` | ❌ |\n| `CORS_ALLOWED_ORIGIN` | CORS allowed origin header. | `*` | ❌ |\n| `CORS_ALLOWED_METHODS` | CORS allowed methods header. | `POST, OPTIONS` | ❌ |\n| `CORS_ALLOWED_HEADERS` | CORS allowed headers header. | `Content-Type, X-User-ID` | ❌ |\n\n\u003e **Note on MCP:** You cannot use the same function name across different MCP servers. Since functions are mapped to clients, duplicate names will override previous ones.\n\n\u003e **Note on Search + MCP:** Google Search grounding and MCP tools can now be used **simultaneously**. On Gemini 3.0 models, both are active at the same time — the model can call your MCP tools and ground responses in live search results within the same conversation. To opt out of search, set `GEMINI_SEARCH_DISABLED=true`.\n\n---\n\n## 📡 API Usage\n\nThe server exposes a simple HTTP endpoint.\n\n### 1. New Conversation (No Session)\nIf you don't provide a User ID, the server generates a new session and returns it in a cookie.\n\n```bash\ncurl -v -X POST http://127.0.0.1:8080/message \\\n  -d \"message=Hi there\"\n```\n\n### 2. Continued Conversation (With Session)\nTo maintain history, pass the `sessionID` cookie returned from the first call.\n\n```bash\ncurl -v -X POST \\\n  -H \"Cookie: sessionID=MGVQOSOZWPMKWAJBQN5KWFR3DF\" \\\n  http://127.0.0.1:8080/message \\\n  -d \"message=Hi again\"\n```\n\n### 3. Using a Custom User ID\nIf your frontend manages users, pass the ID via header.\n\n```bash\ncurl -v -X POST \\\n  -H \"X-User-ID: unique-user-123\" \\\n  http://127.0.0.1:8080/message \\\n  -d \"message=Hi there\"\n```\n\n### 4. Multi-modal (Images \u0026 PDFs)\nSend files using `multipart/form-data`.\n\n```bash\ncurl -v -X POST \\\n  -F \"message=What is on this image?\" \\\n  -F \"payload=@local_image.jpg\" \\\n  http://127.0.0.1:8080/message\n```\n\n---\n\n## 📱 Included Clients\n\nThis repo comes with ready-made clients to demonstrate capabilities.\n\n### 🖥️ CLI Client\nAn interactive terminal chat.\n\n```bash\n# Optional: Set SERVER_URL if not using localhost:8080\ngo run cmd/client-cli/main.go\n```\n![cli-client](examples/client-cli-demo.svg)\n\n### ✈️ Telegram Bot\nRequires a Bot Token from BotFather.\n\n```bash\nexport BOT_TOKEN=\"your_telegram_token\"\n# Optional: restrict access to specific usernames\nexport USERNAME_LIMITS=\"user1,user2\" \n\ngo run cmd/client-telegram/main.go\n```\n*Tip: Captions on images are treated as the prompt.*\n\n### 💬 Facebook Messenger\nRequires a configured Facebook App/Page.\n\n**Env Variables:**\n* `ACCESS_TOKEN`, `VERIFY_TOKEN`, `APP_SECRET` (Required)\n* `ADDR` (Default: `:8082`)\n* `AI_SERVICE` (Default: `http://127.0.0.1:8080`)\n\n```bash\ngo run cmd/client-fb-messenger/main.go\n```\n*Tip: Use `ngrok http 8082` to expose this to Facebook for local testing.*\n\n---\n\n## 🎭 Personality\n\nThe bot's system prompt is loaded from a `personality.txt` file in the working directory. It is plain text — just write your system prompt directly, no JSON wrapping needed.\n\n```\nYou are a helpful assistant named hAIry. Be concise and friendly.\n```\n\n\u003e **Note:** Previous versions used `personality.json` with a JSON structure. This file must be migrated to plain text.\n\n---\n\n## 💾 History Compatibility\n\nHistory files are stored in the `history-gemini/` folder as JSON. After the migration from the raw `genai` SDK to Firebase Genkit, the internal message format changed (`parts` → `content`). **Old history files are not compatible** and should be deleted or the folder cleared before upgrading.\n\n---\n\n## 🛠️ Skills MCP Server\n\nThe repo includes a dedicated MCP (Model Context Protocol) server designed to give the AI agent autonomous access to a sandboxed environment. This allows the AI to run commands, edit code, and modify files—similar to how tools like OpenDevin or OpenClaw work.\n\n**Features \u0026 Tools:**\n- `execute_command`: Execute arbitrary shell commands in the container.\n- `list_files`: List files and directories within a given path.\n- `read_file`: Read the contents of a specific file.\n- `write_file`: Write or overwrite the contents of a file.\n\n**Running the Skills Server:**\nTo run the full stack with the Skills MCP Server enabled, use the dedicated compose file:\n\n```bash\ndocker-compose -f docker-compose-skill.yml up\n```\n\n**Docker Environment:**\nThe Skills MCP Server runs in an Alpine Linux Docker container. This means the AI has access to a real shell and can use package managers like `apk` to install additional applications dynamically if it needs them to accomplish a task.\n*(Note: Since it is a container, installed applications and environment changes are not persistent between restarts unless explicitly mounted).*\n\n---\n\n## ⚠️ Important Notes\n\n\u003e **Security Warning:** Please do not run this server on the public internet without additional authentication. It is intended as an internal helper tool. Public exposure could lead to excessive API usage and costs. Furthermore, running the **Skills MCP Server** gives the AI the ability to execute arbitrary shell commands inside its container. Do not expose this environment or grant it access to sensitive host directories.\n\n\u003e **💡 Pro Tip:** When using the **Skills MCP Server**, you can drop text files explaining specific \"skills\" or commands into the RAG `bot-context/` folder. These files become part of the prompt, teaching the AI exactly how to use specific CLI tools or project structures!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerifield%2Fhairy-botter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgerifield%2Fhairy-botter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerifield%2Fhairy-botter/lists"}