{"id":34623768,"url":"https://github.com/devapro/ai2025","last_synced_at":"2026-05-27T15:03:54.271Z","repository":{"id":328011684,"uuid":"1107595925","full_name":"devapro/ai2025","owner":"devapro","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-27T22:31:43.000Z","size":674,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-28T11:09:09.052Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","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/devapro.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":"2025-12-01T11:02:16.000Z","updated_at":"2026-01-14T17:38:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/devapro/ai2025","commit_stats":null,"previous_names":["devapro/ai2025"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/devapro/ai2025","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devapro%2Fai2025","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devapro%2Fai2025/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devapro%2Fai2025/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devapro%2Fai2025/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devapro","download_url":"https://codeload.github.com/devapro/ai2025/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devapro%2Fai2025/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33570993,"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-27T02:00:06.184Z","response_time":53,"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":[],"created_at":"2025-12-24T15:43:16.931Z","updated_at":"2026-05-27T15:03:54.266Z","avatar_url":"https://github.com/devapro.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Assistant Telegram Bot\n\nMulti-purpose AI assistant Telegram bot with two modes:\n1. **Project Code Assistant** (default) - Navigate and understand codebases with documentation search and code exploration\n2. **General Assistant** - Powered by OpenAI with MCP tools and RAG support\n\n## Modes\n\n### 🔍 Project Code Assistant Mode (Default)\n\nThe bot is configured as a **Project Code Assistant** that helps developers explore and understand codebases:\n\n**Capabilities:**\n- 📖 Search project documentation using RAG\n- 🔎 Find source files by pattern (`find_file` tool)\n- 📄 Read and analyze source code (`read_file` tool)\n- 🏗️ Explain feature implementations\n- 💡 Show real code examples from the project\n- 🔗 Trace logic across multiple files\n\n**Setup:**\n1. Place your project in `project-source/` directory\n2. Index documentation: `./gradlew :utils-embeds:run --args=\"project-source/docs embeddings.db\"`\n3. Set `RAG_ENABLED=true` in `.env`\n4. Ask questions about your codebase!\n\n**Example Questions:**\n- \"Where is authentication implemented?\"\n- \"How does the order processing work?\"\n- \"Show me examples of using the cache service\"\n- \"Explain the database migration logic\"\n\nSee [PROJECT_ASSISTANT_SETUP.md](PROJECT_ASSISTANT_SETUP.md) for complete setup guide.\n\n### 💬 General Assistant Mode\n\nCan be reconfigured as a general-purpose assistant by updating prompts in `promts/` directory.\n\n## Core Features\n\n- **General AI Assistant**: Answers questions on a wide range of topics using OpenAI's GPT models\n- **Clear Explanations**: Provides easy-to-understand answers with examples and context\n- **Practical Advice**: Offers how-to guides, recommendations, and problem-solving help\n- **Performance Statistics**: Each response includes:\n  - Response time (milliseconds)\n  - Token usage (prompt, completion, total)\n- **Optional Summaries**: Concise one-line summaries for quick understanding\n- **Conversation History**: Maintains conversation context for each user\n- **Markdown Formatting**: Rich formatting for clear, structured responses\n- **MCP Tool Support**: Connect to external tools and data sources via Model Context Protocol\n- **Docker Support**: Fully containerized deployment\n\n## Prerequisites\n\n- Java 21 or higher\n- Gradle 8.7 or higher (or use the included Gradle Wrapper)\n- OpenAI API key\n- Telegram Bot token (get it from [@BotFather](https://t.me/BotFather))\n- Docker and Docker Compose (for containerized deployment)\n\n## Project Structure\n\n```\nAi1/\n├── app/                          # Main application module\n│   └── src/main/kotlin/io/github/devapro/ai/\n│       ├── agent/                # AI agent component\n│       │   └── AiAgent.kt\n│       ├── bot/                  # Telegram bot component\n│       │   └── TelegramBot.kt\n│       ├── repository/           # File storage component\n│       │   └── FileRepository.kt\n│       ├── di/                   # Dependency injection\n│       │   └── AppDi.kt\n│       └── App.kt                # Application entry point\n├── tools/                        # Internal tools module\n│   └── src/main/kotlin/io/github/devapro/ai/tools/\n│       ├── impl/                 # Tool implementations\n│       │   ├── FindFileTool.kt\n│       │   ├── ReadFileTool.kt\n│       │   ├── FolderStructureTool.kt\n│       │   ├── ExploringTool.kt\n│       │   └── DocumentWriterTool.kt\n│       ├── rag/                  # RAG search tools\n│       │   ├── RagSearchTool.kt\n│       │   └── EnhancedRagSearchTool.kt\n│       └── Tool.kt               # Tool interface\n├── utils-embeds/                 # RAG utilities and embeddings\n├── buildSrc/                     # Gradle convention plugins\n├── docker/                       # Docker configuration\n│   ├── Dockerfile\n│   └── docker-compose.yml\n├── promts/                       # Prompt templates (markdown files)\n│   ├── system.md                 # System prompt for AI agent\n│   └── assistant.md              # Assistant greeting\n├── doc-source/                   # Documentation folder (writable by agent)\n└── history/                      # User conversation history (git-ignored)\n```\n\n## Setup\n\n### 1. Clone the repository\n\n```bash\ncd Ai1\n```\n\n### 2. Configure environment variables\n\nCopy the example environment file and fill in your credentials:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your credentials:\n\n```env\nOPENAI_API_KEY=your_openai_api_key_here\nTELEGRAM_BOT_TOKEN=your_telegram_bot_token_here\n```\n\n### 3. Customize the prompts (optional)\n\nEdit `promts/system.md` to customize the AI assistant's behavior and response style.\nEdit `promts/assistant.md` to customize the initial greeting message.\n\n## Running the Application\n\n### Option 1: Run with Gradle\n\n```bash\n./gradlew run\n```\n\n### Option 2: Build and run the JAR\n\n```bash\n# Build the application\n./gradlew build\n\n# Run the JAR\njava -jar app/build/libs/app.jar\n```\n\n### Option 3: Run with Docker Compose (Recommended)\n\n```bash\n# Build and start the container\ncd docker\ndocker-compose up --build\n\n# Run in detached mode\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop the container\ndocker-compose down\n```\n\n## Using the Bot\n\n1. Start a conversation with your bot on Telegram\n2. Send `/start` to initialize the bot\n3. Ask any question\n4. Receive a detailed answer with statistics\n5. Use `/clear` to clear your conversation history\n6. Use `/help` to see available commands\n\n### Available Commands\n\n- `/start` - Start conversation with the bot\n- `/help` - Show help message with available commands\n- `/clear` - Clear conversation history\n\n### Example Interaction\n\n**User asks:**\n```\nWhat is Python?\n```\n\n**Bot responds:**\n```\nPython is a high-level, interpreted programming language known for its simplicity and readability. It was created by Guido van Rossum and first released in 1991.\n\nKey features:\n• Easy to learn and read\n• Versatile - used for web development, data science, automation, etc.\n• Large standard library and ecosystem\n• Strong community support\n\nIt's an excellent choice for beginners and professionals alike.\n\n💡 Python is a versatile, beginner-friendly programming language\n\n---\n\n📊 Statistics:\n• Response time: 1234ms\n• Tokens used: 156 (prompt: 89, completion: 67)\n```\n\n## Internal Tools\n\nThe bot comes with several built-in tools that the AI agent can use automatically:\n\n### File Tools\n\n**find_file** - Search for files using glob patterns\n- Search by filename pattern (`*.kt`, `*Service.java`)\n- Filter by directory and extension\n- Configurable search depth and result limits\n- Example: \"Find all Kotlin test files in the project\"\n\n**read_file** - Read file contents with optional line ranges\n- Read entire files or specific line ranges\n- Line-numbered output for easy reference\n- 10MB file size limit for safety\n- Example: \"Show me the contents of Main.kt\"\n\n**folder_structure** - Display directory tree structure\n- Tree-style visualization with visual connectors\n- Configurable depth and file display options\n- Show/hide hidden files, file sizes\n- Summary statistics (file count, directory count, total size)\n- Example: \"Show me the structure of the src folder\"\n\n**explore_files** - AI-powered file summaries\n- Generate concise descriptions for multiple files at once\n- Process specific files or entire folders\n- Uses GPT-4o-mini for cost-effective summaries\n- Filter by file extensions, control recursion depth\n- Example: \"Explore all Kotlin files in the agent package and summarize what they do\"\n\n**write_documentation** - Create and modify documentation\n- Write new documentation files in `doc-source` folder\n- Update existing documentation\n- Append to existing files (useful for changelogs)\n- Three modes: create, overwrite, append\n- Automatic directory creation\n- Security: Restricted to doc-source folder only\n- Example: \"Create documentation explaining how the RAG system works\"\n\n### RAG Tool\n\n**search_documents** (optional, requires RAG setup)\n- Semantic search through indexed project documentation\n- Uses local embeddings via LM Studio (no API costs)\n- Configurable similarity threshold and result count\n- Example: \"Search the documentation for authentication implementation details\"\n\nThese tools work seamlessly with external MCP tools, giving the AI agent a comprehensive toolkit for code exploration and documentation tasks.\n\n## MCP Server Integration\n\nThis bot supports the **Model Context Protocol (MCP)**, enabling the AI agent to use external tools and data sources automatically.\n\n### What is MCP?\n\nMCP is an open protocol that allows AI assistants to securely connect to:\n- **File Systems**: Read and write files on your computer\n- **Search Engines**: Search the web for current information\n- **Databases**: Query databases for data\n- **APIs**: Connect to any HTTP-based service\n- **Custom Tools**: Build and connect your own tools\n\n### Quick Setup\n\n1. **Copy the example configuration:**\n   ```bash\n   cp mcp-config.json.example mcp-config.json\n   ```\n\n2. **Enable desired servers** by setting `\"enabled\": true` in the configuration\n\n3. **Add credentials** (API keys, database connections) as needed\n\n4. **Restart the bot** to load the MCP servers\n\n### Example: Filesystem Server\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"filesystem\",\n      \"enabled\": true,\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/Users/username/Documents\"]\n    }\n  ]\n}\n```\n\nWith this configured, you can ask:\n- \"List the files in my Documents folder\"\n- \"Read the contents of todo.txt\"\n- \"Create a file called notes.md with a shopping list\"\n\nThe AI will automatically use the filesystem tool when appropriate!\n\n### Available MCP Servers\n\n- **Filesystem**: `@modelcontextprotocol/server-filesystem`\n- **Brave Search**: `@modelcontextprotocol/server-brave-search`\n- **GitHub**: `@modelcontextprotocol/server-github`\n- **PostgreSQL**: `@modelcontextprotocol/server-postgres`\n- **Custom HTTP**: Connect to your own services\n\n### Documentation\n\nFor detailed configuration instructions, available servers, and examples, see **[MCP_GUIDE.md](MCP_GUIDE.md)**.\n\n### Security Note\n\n⚠️ The `mcp-config.json` file may contain sensitive information (API keys, credentials). It is automatically excluded from version control. Never commit it to Git!\n\n## Development\n\n### Build the project\n\n```bash\n./gradlew build\n```\n\n### Run tests\n\n```bash\n./gradlew test\n```\n\n### Run checks (includes tests)\n\n```bash\n./gradlew check\n```\n\n### Clean build outputs\n\n```bash\n./gradlew clean\n```\n\n## Architecture\n\nThe application follows a modular architecture with clear separation of concerns:\n\n- **DI Layer** (`di/`): Koin dependency injection configuration in `AppDi.kt`\n- **Bot Component** (`bot/`): Handles Telegram API interactions and user commands\n- **Agent Component** (`agent/`): Manages AI conversations using OpenAI API directly via Ktor\n- **Tools Module** (`tools/`): Built-in tools for file operations, code exploration, and documentation\n  - File tools: find, read, folder structure\n  - Exploring tool: AI-powered file summaries\n  - Documentation writer: Create/modify docs in doc-source\n  - RAG tools: Semantic document search\n- **Repository Component** (`repository/`): Handles file-based storage for prompts and history\n- **Utils Module** (`utils-embeds/`): RAG embeddings and vector database utilities\n\nAll components are managed as singletons by Koin DI framework with automatic dependency resolution.\n\n### Technology Stack\n\n- **Kotlin 2.2.0**: Primary programming language\n- **Koin 4.0.0**: Lightweight dependency injection framework\n- **OpenAI API**: Direct integration for AI-powered responses (gpt-4o-mini with JSON mode)\n- **kotlin-telegram-bot 6.3.0**: Telegram Bot API client\n- **Ktor 3.3.0**: HTTP client for OpenAI API communication\n- **kotlinx-coroutines**: Async/await support\n- **kotlinx-serialization**: JSON serialization for API requests/responses\n- **dotenv-kotlin**: Environment variable management\n- **Gradle**: Build system with multi-module setup\n\n### AI Capabilities\n\n- **Question Answering**: Factual questions, explanations, definitions\n- **How-To Guides**: Step-by-step instructions and tutorials\n- **Problem Solving**: Troubleshooting and solutions\n- **Recommendations**: Advice and suggestions on various topics\n- **Explanations**: Breaking down complex topics into understandable parts\n- **Context Awareness**: Maintains conversation history for coherent dialogues\n- **Structured Output**: Returns responses as JSON with text and optional summary\n- **Performance Tracking**: Displays response time and token usage statistics\n\n## Configuration\n\n### Environment Variables\n\n- `OPENAI_API_KEY` (required): Your OpenAI API key\n- `TELEGRAM_BOT_TOKEN` (required): Your Telegram bot token\n- `PROMPTS_DIR` (optional): Directory for prompt files (default: `promts`)\n- `HISTORY_DIR` (optional): Directory for history files (default: `history`)\n- `PROJECT_SOURCE_DIR` (optional): Directory containing project source code for file tools (default: `project-source`)\n\n### Conversation History\n\nConversation history is stored in markdown files in the `history/` directory:\n- Each user gets a separate file: `user_{userId}.md`\n- Files are automatically created on first message\n- Use the `/clear` command to delete a user's history\n\n## Docker Deployment\n\nThe application is fully containerized and production-ready:\n\n### Multi-stage Build\n- Stage 1: Builds the application using Gradle\n- Stage 2: Creates a minimal runtime image with only the JRE\n\n### Volumes\n- `/app/history`: Mounted to persist conversation history\n- `/app/promts`: Mounted to allow updating prompts without rebuilding\n\n### Logging\n- JSON file driver with rotation (max 10MB, 3 files)\n\n## Troubleshooting\n\n### Bot not responding\n\n1. Check that your bot token is correct\n2. Verify the bot is running: `docker-compose logs telegram-bot`\n3. Ensure your OpenAI API key is valid and has credits\n\n### Build errors\n\n```bash\n# Clean and rebuild\n./gradlew clean build\n```\n\n### Docker issues\n\n```bash\n# Rebuild from scratch\ndocker-compose down\ndocker-compose build --no-cache\ndocker-compose up\n```\n\n## License\n\nThis project uses [Gradle](https://gradle.org/) and follows the suggested multi-module setup.\n\n[Learn more about the Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html)\n\n[Learn more about Gradle tasks](https://docs.gradle.org/current/userguide/command_line_interface.html#common_tasks)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevapro%2Fai2025","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevapro%2Fai2025","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevapro%2Fai2025/lists"}