{"id":28996765,"url":"https://github.com/hunkim/solar-search-vercel","last_synced_at":"2025-06-25T05:11:28.491Z","repository":{"id":296716161,"uuid":"994243974","full_name":"hunkim/solar-search-vercel","owner":"hunkim","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-21T18:14:15.000Z","size":118,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T18:21:45.351Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://solar-search-vercel.vercel.app","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/hunkim.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}},"created_at":"2025-06-01T14:32:01.000Z","updated_at":"2025-06-21T18:14:18.000Z","dependencies_parsed_at":"2025-06-03T06:19:13.299Z","dependency_job_id":null,"html_url":"https://github.com/hunkim/solar-search-vercel","commit_stats":null,"previous_names":["hunkim/solar-search-vercel"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hunkim/solar-search-vercel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fsolar-search-vercel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fsolar-search-vercel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fsolar-search-vercel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fsolar-search-vercel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hunkim","download_url":"https://codeload.github.com/hunkim/solar-search-vercel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fsolar-search-vercel/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261808072,"owners_count":23212694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-06-25T05:11:27.766Z","updated_at":"2025-06-25T05:11:28.465Z","avatar_url":"https://github.com/hunkim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram Bot with Solar API\n\nA Telegram bot powered by Solar Pro Preview LLM from Upstage with web search grounding capabilities.\n\n## Features\n\n- 🤖 Telegram bot with webhook support (Vercel-ready)\n- 🔍 Web search grounding using Tavily API\n- ☀️ Solar Pro Preview LLM for intelligent responses\n- 📚 Automatic citation and source formatting\n- 👥 Group chat support with @mention detection\n- 🎨 Rich text formatting with HTML support\n- ⚡ Real-time streaming responses\n\n## Setup\n\n### 1. Install Dependencies\n\n```bash\n# Install all dependencies\npip install -r requirements.txt\n```\n\n### 2. Set Environment Variables\n\nCreate a `.env.local` file in the project root:\n\n```bash\n# Telegram Bot Configuration\nTELEGRAM_BOT_TOKEN=your_telegram_bot_token_here\n\n# Upstage API Configuration  \nUPSTAGE_API_KEY=your_upstage_api_key_here\n\n# Tavily Search API (for grounding)\nTAVILY_API_KEY=your_tavily_api_key_here\n```\n\n\u003e **That's it!** The webhook URL is automatically detected from your deployment.\n\n### 3. Getting API Keys\n\n**Telegram Bot Token:**\n1. Chat with [@BotFather](https://t.me/botfather) on Telegram\n2. Create a new bot using `/newbot`\n3. Copy the bot token\n\n**Upstage API Key:**\n1. Sign up at [Upstage Console](https://console.upstage.ai)\n2. Navigate to API Keys section\n3. Create a new API key\n\n**Tavily API Key:**\n1. Sign up at [Tavily](https://tavily.com)\n2. Get your API key from the dashboard\n\n### Advanced Configuration (Optional)\n\n**Custom Webhook URL Override:**\nIf you need to use a custom domain instead of your deployment URL, you can set:\n```bash\nWEBHOOK_URL=https://your-custom-domain.com\n```\n\nThis is only needed for advanced use cases like custom domains or proxy setups.\n\n### 4. Deploy to Vercel\n\n```bash\n# Deploy to Vercel\nvercel --prod\n\n# Set environment variables in Vercel dashboard\n# Go to your project settings and add the environment variables\n```\n\n### 5. Set Webhook\n\nAfter deployment, simply visit your webhook setup URL - **no configuration needed**!\n\n```bash\n# Just visit this URL in your browser or use curl\nhttps://your-vercel-app.vercel.app/set_webhook\n```\n\n**That's it!** Your bot is now ready to receive messages.\n\n## Local Development\n\n### Run the FastAPI Server\n\n```bash\n# Development mode with auto-reload\nuvicorn main:app --host 0.0.0.0 --port 8000 --reload\n```\n\nThe API will be available at `http://localhost:8000`\n\n### Testing Locally with ngrok\n\nFor local development, you can use ngrok to expose your local server:\n\n```bash\n# Install ngrok and expose port 8000\nngrok http 8000\n\n# Visit the ngrok URL + /set_webhook \n# Example: https://abc123.ngrok.io/set_webhook\n```\n\n## Bot Features\n\n### Commands\n\n- `/start` - Welcome message and bot introduction\n- `/help` - Display help information and available commands\n\n### Text Processing\n\nThe bot processes any text message and:\n1. Uses Tavily API to search for relevant information\n2. Sends the search results to Solar Pro Preview LLM\n3. Generates a comprehensive response with citations\n4. Formats the response with proper HTML markup\n5. Sends citations as a separate message with clickable links\n\n### Group Chat Support\n\n- Bot responds only when mentioned with `@botname`\n- Automatically detects group chats vs private chats\n- Strips bot mentions from questions for cleaner processing\n\n## API Endpoints\n\n### `GET /`\nWelcome message with available endpoints.\n\n### `POST /webhook`\nTelegram webhook endpoint for receiving updates.\n\n### `POST /set_webhook`\nSet the webhook URL for the Telegram bot. **Auto-detects your deployment URL** if no custom URL provided.\n\n**Simple Usage (auto-detection):**\n```bash\ncurl -X POST \"https://your-domain.com/set_webhook\"\n```\n\n**Advanced Usage (custom URL):**\n```json\n{\n  \"webhook_url\": \"https://your-custom-domain.com\"\n}\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"webhook_url\": \"https://your-domain.com/webhook\",\n  \"message\": \"Webhook set successfully! Your bot is now ready to receive messages.\"\n}\n```\n\n### `GET /health`\nHealth check endpoint showing configuration status.\n\n**Response:**\n```json\n{\n  \"status\": \"healthy\",\n  \"telegram_token_configured\": true,\n  \"upstage_api_key_configured\": true,\n  \"webhook_url\": \"https://your-domain.com\",\n  \"service\": \"Telegram Bot API\"\n}\n```\n\n## Usage Examples\n\n### Chat with the Bot\n\n1. Start a chat with your bot on Telegram\n2. Send `/start` to begin\n3. Ask any question: \"What's the weather in Seoul?\"\n4. The bot will search the web and provide an answer with sources\n\n### Group Chat Usage\n\n1. Add the bot to a group\n2. Mention the bot: \"@yourbotname What's the latest news about AI?\"\n3. The bot will respond with search results and citations\n\n## Text Formatting Features\n\nThe bot supports rich text formatting:\n\n- **Bold text** with `**text**`\n- *Italic text* with `*text*`\n- `Code snippets` with backticks\n- ```Code blocks``` with triple backticks\n- [Links](url) with markdown syntax\n- Numbered and bulleted lists\n- Automatic citation formatting\n\n## Architecture\n\n- **FastAPI**: Web framework for webhook handling\n- **python-telegram-bot**: Telegram Bot API wrapper\n- **Solar API**: LLM for generating responses\n- **Tavily API**: Web search for grounding\n- **Vercel**: Serverless deployment platform\n\n## Troubleshooting\n\n### Webhook Issues\n\nCheck webhook status:\n```bash\ncurl \"https://api.telegram.org/bot\u003cYOUR_BOT_TOKEN\u003e/getWebhookInfo\"\n```\n\nDelete webhook:\n```bash\ncurl \"https://api.telegram.org/bot\u003cYOUR_BOT_TOKEN\u003e/deleteWebhook\"\n```\n\n### Environment Variables\n\nVerify all required environment variables are set:\n```bash\ncurl \"https://your-vercel-app.vercel.app/health\"\n```\n\n### Bot Not Responding\n\n1. Check the webhook is set correctly\n2. Verify environment variables in Vercel\n3. Check the logs in Vercel dashboard\n4. Ensure the bot token is valid\n\n## Development\n\n### File Structure\n\n- `main.py` - FastAPI application with Telegram webhook handling\n- `solar.py` - Solar API client with search grounding\n- `telegram_bot.py` - Original polling-based bot (reference)\n- `requirements.txt` - Python dependencies\n- `vercel.json` - Vercel deployment configuration\n\n### Running Tests\n\n```bash\n# Test the API endpoints\ncurl \"http://localhost:8000/health\"\n\n# Test webhook handling (with mock data)\ncurl -X POST \"http://localhost:8000/webhook\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"update_id\": 1, \"message\": {\"message_id\": 1, \"chat\": {\"id\": 123}, \"text\": \"/start\"}}'\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunkim%2Fsolar-search-vercel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhunkim%2Fsolar-search-vercel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunkim%2Fsolar-search-vercel/lists"}