Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/devapro/ai2025


https://github.com/devapro/ai2025

Last synced: 24 days ago
JSON representation

Awesome Lists containing this project

README 

          
# AI Assistant Telegram Bot



Multi-purpose AI assistant Telegram bot with two modes:

1. **Project Code Assistant** (default) - Navigate and understand codebases with documentation search and code exploration

2. **General Assistant** - Powered by OpenAI with MCP tools and RAG support



## Modes



### 🔍 Project Code Assistant Mode (Default)



The bot is configured as a **Project Code Assistant** that helps developers explore and understand codebases:



**Capabilities:**

- 📖 Search project documentation using RAG

- 🔎 Find source files by pattern (`find_file` tool)

- 📄 Read and analyze source code (`read_file` tool)

- 🏗️ Explain feature implementations

- 💡 Show real code examples from the project

- 🔗 Trace logic across multiple files



**Setup:**

1. Place your project in `project-source/` directory

2. Index documentation: `./gradlew :utils-embeds:run --args="project-source/docs embeddings.db"`

3. Set `RAG_ENABLED=true` in `.env`

4. Ask questions about your codebase!



**Example Questions:**

- "Where is authentication implemented?"

- "How does the order processing work?"

- "Show me examples of using the cache service"

- "Explain the database migration logic"



See [PROJECT_ASSISTANT_SETUP.md](PROJECT_ASSISTANT_SETUP.md) for complete setup guide.



### 💬 General Assistant Mode



Can be reconfigured as a general-purpose assistant by updating prompts in `promts/` directory.



## Core Features



- **General AI Assistant**: Answers questions on a wide range of topics using OpenAI's GPT models

- **Clear Explanations**: Provides easy-to-understand answers with examples and context

- **Practical Advice**: Offers how-to guides, recommendations, and problem-solving help

- **Performance Statistics**: Each response includes:

  - Response time (milliseconds)

  - Token usage (prompt, completion, total)

- **Optional Summaries**: Concise one-line summaries for quick understanding

- **Conversation History**: Maintains conversation context for each user

- **Markdown Formatting**: Rich formatting for clear, structured responses

- **MCP Tool Support**: Connect to external tools and data sources via Model Context Protocol

- **Docker Support**: Fully containerized deployment



## Prerequisites



- Java 21 or higher

- Gradle 8.7 or higher (or use the included Gradle Wrapper)

- OpenAI API key

- Telegram Bot token (get it from [@BotFather](https://t.me/BotFather))

- Docker and Docker Compose (for containerized deployment)



## Project Structure



```

Ai1/

├── app/                          # Main application module

│   └── src/main/kotlin/io/github/devapro/ai/

│       ├── agent/                # AI agent component

│       │   └── AiAgent.kt

│       ├── bot/                  # Telegram bot component

│       │   └── TelegramBot.kt

│       ├── repository/           # File storage component

│       │   └── FileRepository.kt

│       ├── di/                   # Dependency injection

│       │   └── AppDi.kt

│       └── App.kt                # Application entry point

├── tools/                        # Internal tools module

│   └── src/main/kotlin/io/github/devapro/ai/tools/

│       ├── impl/                 # Tool implementations

│       │   ├── FindFileTool.kt

│       │   ├── ReadFileTool.kt

│       │   ├── FolderStructureTool.kt

│       │   ├── ExploringTool.kt

│       │   └── DocumentWriterTool.kt

│       ├── rag/                  # RAG search tools

│       │   ├── RagSearchTool.kt

│       │   └── EnhancedRagSearchTool.kt

│       └── Tool.kt               # Tool interface

├── utils-embeds/                 # RAG utilities and embeddings

├── buildSrc/                     # Gradle convention plugins

├── docker/                       # Docker configuration

│   ├── Dockerfile

│   └── docker-compose.yml

├── promts/                       # Prompt templates (markdown files)

│   ├── system.md                 # System prompt for AI agent

│   └── assistant.md              # Assistant greeting

├── doc-source/                   # Documentation folder (writable by agent)

└── history/                      # User conversation history (git-ignored)

```



## Setup



### 1. Clone the repository



```bash

cd Ai1

```



### 2. Configure environment variables



Copy the example environment file and fill in your credentials:



```bash

cp .env.example .env

```



Edit `.env` and add your credentials:



```env

OPENAI_API_KEY=your_openai_api_key_here

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

```



### 3. Customize the prompts (optional)



Edit `promts/system.md` to customize the AI assistant's behavior and response style.

Edit `promts/assistant.md` to customize the initial greeting message.



## Running the Application



### Option 1: Run with Gradle



```bash

./gradlew run

```



### Option 2: Build and run the JAR



```bash

# Build the application

./gradlew build



# Run the JAR

java -jar app/build/libs/app.jar

```



### Option 3: Run with Docker Compose (Recommended)



```bash

# Build and start the container

cd docker

docker-compose up --build



# Run in detached mode

docker-compose up -d



# View logs

docker-compose logs -f



# Stop the container

docker-compose down

```



## Using the Bot



1. Start a conversation with your bot on Telegram

2. Send `/start` to initialize the bot

3. Ask any question

4. Receive a detailed answer with statistics

5. Use `/clear` to clear your conversation history

6. Use `/help` to see available commands



### Available Commands



- `/start` - Start conversation with the bot

- `/help` - Show help message with available commands

- `/clear` - Clear conversation history



### Example Interaction



**User asks:**

```

What is Python?

```



**Bot responds:**

```

Python 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.



Key features:

• Easy to learn and read

• Versatile - used for web development, data science, automation, etc.

• Large standard library and ecosystem

• Strong community support



It's an excellent choice for beginners and professionals alike.



💡 Python is a versatile, beginner-friendly programming language



---



📊 Statistics:

• Response time: 1234ms

• Tokens used: 156 (prompt: 89, completion: 67)

```



## Internal Tools



The bot comes with several built-in tools that the AI agent can use automatically:



### File Tools



**find_file** - Search for files using glob patterns

- Search by filename pattern (`*.kt`, `*Service.java`)

- Filter by directory and extension

- Configurable search depth and result limits

- Example: "Find all Kotlin test files in the project"



**read_file** - Read file contents with optional line ranges

- Read entire files or specific line ranges

- Line-numbered output for easy reference

- 10MB file size limit for safety

- Example: "Show me the contents of Main.kt"



**folder_structure** - Display directory tree structure

- Tree-style visualization with visual connectors

- Configurable depth and file display options

- Show/hide hidden files, file sizes

- Summary statistics (file count, directory count, total size)

- Example: "Show me the structure of the src folder"



**explore_files** - AI-powered file summaries

- Generate concise descriptions for multiple files at once

- Process specific files or entire folders

- Uses GPT-4o-mini for cost-effective summaries

- Filter by file extensions, control recursion depth

- Example: "Explore all Kotlin files in the agent package and summarize what they do"



**write_documentation** - Create and modify documentation

- Write new documentation files in `doc-source` folder

- Update existing documentation

- Append to existing files (useful for changelogs)

- Three modes: create, overwrite, append

- Automatic directory creation

- Security: Restricted to doc-source folder only

- Example: "Create documentation explaining how the RAG system works"



### RAG Tool



**search_documents** (optional, requires RAG setup)

- Semantic search through indexed project documentation

- Uses local embeddings via LM Studio (no API costs)

- Configurable similarity threshold and result count

- Example: "Search the documentation for authentication implementation details"



These tools work seamlessly with external MCP tools, giving the AI agent a comprehensive toolkit for code exploration and documentation tasks.



## MCP Server Integration



This bot supports the **Model Context Protocol (MCP)**, enabling the AI agent to use external tools and data sources automatically.



### What is MCP?



MCP is an open protocol that allows AI assistants to securely connect to:

- **File Systems**: Read and write files on your computer

- **Search Engines**: Search the web for current information

- **Databases**: Query databases for data

- **APIs**: Connect to any HTTP-based service

- **Custom Tools**: Build and connect your own tools



### Quick Setup



1. **Copy the example configuration:**

   ```bash

   cp mcp-config.json.example mcp-config.json

   ```



2. **Enable desired servers** by setting `"enabled": true` in the configuration



3. **Add credentials** (API keys, database connections) as needed



4. **Restart the bot** to load the MCP servers



### Example: Filesystem Server



```json

{

  "mcpServers": [

    {

      "name": "filesystem",

      "enabled": true,

      "type": "stdio",

      "command": "npx",

      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]

    }

  ]

}

```



With this configured, you can ask:

- "List the files in my Documents folder"

- "Read the contents of todo.txt"

- "Create a file called notes.md with a shopping list"



The AI will automatically use the filesystem tool when appropriate!



### Available MCP Servers



- **Filesystem**: `@modelcontextprotocol/server-filesystem`

- **Brave Search**: `@modelcontextprotocol/server-brave-search`

- **GitHub**: `@modelcontextprotocol/server-github`

- **PostgreSQL**: `@modelcontextprotocol/server-postgres`

- **Custom HTTP**: Connect to your own services



### Documentation



For detailed configuration instructions, available servers, and examples, see **[MCP_GUIDE.md](MCP_GUIDE.md)**.



### Security Note



⚠️ The `mcp-config.json` file may contain sensitive information (API keys, credentials). It is automatically excluded from version control. Never commit it to Git!



## Development



### Build the project



```bash

./gradlew build

```



### Run tests



```bash

./gradlew test

```



### Run checks (includes tests)



```bash

./gradlew check

```



### Clean build outputs



```bash

./gradlew clean

```



## Architecture



The application follows a modular architecture with clear separation of concerns:



- **DI Layer** (`di/`): Koin dependency injection configuration in `AppDi.kt`

- **Bot Component** (`bot/`): Handles Telegram API interactions and user commands

- **Agent Component** (`agent/`): Manages AI conversations using OpenAI API directly via Ktor

- **Tools Module** (`tools/`): Built-in tools for file operations, code exploration, and documentation

  - File tools: find, read, folder structure

  - Exploring tool: AI-powered file summaries

  - Documentation writer: Create/modify docs in doc-source

  - RAG tools: Semantic document search

- **Repository Component** (`repository/`): Handles file-based storage for prompts and history

- **Utils Module** (`utils-embeds/`): RAG embeddings and vector database utilities



All components are managed as singletons by Koin DI framework with automatic dependency resolution.



### Technology Stack



- **Kotlin 2.2.0**: Primary programming language

- **Koin 4.0.0**: Lightweight dependency injection framework

- **OpenAI API**: Direct integration for AI-powered responses (gpt-4o-mini with JSON mode)

- **kotlin-telegram-bot 6.3.0**: Telegram Bot API client

- **Ktor 3.3.0**: HTTP client for OpenAI API communication

- **kotlinx-coroutines**: Async/await support

- **kotlinx-serialization**: JSON serialization for API requests/responses

- **dotenv-kotlin**: Environment variable management

- **Gradle**: Build system with multi-module setup



### AI Capabilities



- **Question Answering**: Factual questions, explanations, definitions

- **How-To Guides**: Step-by-step instructions and tutorials

- **Problem Solving**: Troubleshooting and solutions

- **Recommendations**: Advice and suggestions on various topics

- **Explanations**: Breaking down complex topics into understandable parts

- **Context Awareness**: Maintains conversation history for coherent dialogues

- **Structured Output**: Returns responses as JSON with text and optional summary

- **Performance Tracking**: Displays response time and token usage statistics



## Configuration



### Environment Variables



- `OPENAI_API_KEY` (required): Your OpenAI API key

- `TELEGRAM_BOT_TOKEN` (required): Your Telegram bot token

- `PROMPTS_DIR` (optional): Directory for prompt files (default: `promts`)

- `HISTORY_DIR` (optional): Directory for history files (default: `history`)

- `PROJECT_SOURCE_DIR` (optional): Directory containing project source code for file tools (default: `project-source`)



### Conversation History



Conversation history is stored in markdown files in the `history/` directory:

- Each user gets a separate file: `user_{userId}.md`

- Files are automatically created on first message

- Use the `/clear` command to delete a user's history



## Docker Deployment



The application is fully containerized and production-ready:



### Multi-stage Build

- Stage 1: Builds the application using Gradle

- Stage 2: Creates a minimal runtime image with only the JRE



### Volumes

- `/app/history`: Mounted to persist conversation history

- `/app/promts`: Mounted to allow updating prompts without rebuilding



### Logging

- JSON file driver with rotation (max 10MB, 3 files)



## Troubleshooting



### Bot not responding



1. Check that your bot token is correct

2. Verify the bot is running: `docker-compose logs telegram-bot`

3. Ensure your OpenAI API key is valid and has credits



### Build errors



```bash

# Clean and rebuild

./gradlew clean build

```



### Docker issues



```bash

# Rebuild from scratch

docker-compose down

docker-compose build --no-cache

docker-compose up

```



## License



This project uses [Gradle](https://gradle.org/) and follows the suggested multi-module setup.



[Learn more about the Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html)



[Learn more about Gradle tasks](https://docs.gradle.org/current/userguide/command_line_interface.html#common_tasks)