Polish consulting assistant portfolio

.dockerignore

@@ -0,0 +1,14 @@
+.git
+.github
+.venv
+.env
+.env.*
+!.env.example
+.idea
+.pytest_cache
+__pycache__
+*.py[cod]
+.DS_Store
+chroma_db
+sync_state.json
+docs/assets/*.gif

.env.example

@@ -0,0 +1,16 @@
+# Copy this file to .env and fill in real values locally.
+# Never commit .env with secrets or private workspace IDs.
+
+OPENAI_API_KEY=your_openai_api_key
+TELEGRAMBOT_API_KEY=your_telegram_bot_token
+NOTION_API_KEY=your_notion_integration_secret
+NOTION_DATABASE_ID=your_notion_database_id
+
+# Optional proxy for OpenAI/HTTP clients.
+PROXY_URL=
+
+# Local persistence and collection names.
+CHROMA_PATH=./chroma_db
+BUSINESS_CASES_COLLECTION=business_cases
+MEMORY_COLLECTION=conversation_memory
+SYNC_STATE_FILE=sync_state.json

.github/workflows/tests.yml → .github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Tests
+name: CI
 
 on:
   push:
@@ -23,7 +23,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -r requirements-dev.txt
 
       - name: Run automated tests
         run: python -m pytest -q

.gitignore

@@ -1,5 +1,7 @@
 .venv/
 .env
+.env.*
+!.env.example
 __pycache__/
 .pytest_cache/
 *.py[cod]

Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["python", "telegram_bot.py"]

README.md

@@ -1,103 +1,256 @@
-# Consulting Assistant
+# AI Consulting Assistant
 
-AI-консультант в формате Telegram-бота для бизнес-задач, связанных с внедрением искусственного интеллекта. Бот умеет вести обычный чат, запускать многоагентный сценарий бизнес-консультации, сохранять новые бизнес-кейсы в Notion и искать сохраненные кейсы через локальную RAG-базу знаний на ChromaDB.
+**RU summary:** Telegram AI-ассистент для бизнес-консультаций по внедрению AI. Проект объединяет multi-agent workflow на CrewAI, RAG-поиск по кейсам в ChromaDB, синхронизацию кейсов из Notion, память диалогов и обработку голосовых сообщений через Whisper.
 
-## Что Умеет Проект
+## Overview
 
-- Предоставляет Telegram-интерфейс с режимами чата, бизнес-консультации, помощи и сохранения кейсов.
-- Использует CrewAI-сценарий с агентами исследователя, консультанта и критика для вопросов по бизнес-консалтингу.
-- Ищет AI-бизнес-кейсы, сохраненные в ChromaDB, через `rag_tool.py`.
-- Хранит память диалогов в ChromaDB через `memory.py`.
-- Сохраняет структурированные бизнес-кейсы в Notion через `scribe.py`.
-- Синхронизирует бизнес-кейсы из Notion в ChromaDB через Notion-to-Chroma скрипты.
+AI Consulting Assistant is a Telegram-based portfolio project that demonstrates how an LLM application can support business consulting workflows around AI adoption. The bot can answer regular chat questions, run a structured multi-agent consultation, search a local business-case knowledge base with RAG, save new cases to Notion, and keep lightweight conversation memory.
 
-## Основные Файлы
+The project is intentionally MVP-sized, but it includes production-oriented building blocks: environment-based configuration, Docker support, CI, automated tests with mocks, local persistent ChromaDB storage, and clear documentation.
 
-- `telegram_bot.py` - точка входа Telegram-бота, меню, команды и обработка сообщений.
-- `orchestrator.py` - маршрутизация сообщений между обычным чатом и режимом бизнес-консультации.
-- `agents.py` - настройка агентов и вспомогательная логика.
-- `rag_tool.py` - инструмент поиска бизнес-кейсов в ChromaDB.
-- `memory.py` - сохранение и поиск памяти диалогов.
-- `scribe.py` - создание новых страниц с бизнес-кейсами в Notion.
-- `notion_to_chromadb.py` - полная пересборка базы ChromaDB из Notion.
-- `sync_notion_to_chromadb.py` - инкрементальная синхронизация Notion -> ChromaDB.
-- `digest.py` - логика генерации дайджеста.
-- `main.py` - минимальный стартовый файл с загрузкой переменных окружения.
-- `requirements.txt` - зависимости Python.
+## Problem
 
-## Переменные Окружения
+Small teams exploring AI adoption often ask broad questions such as "How can we automate support?" or "Are there real examples of AI agents in sales?" A useful assistant should not only generate generic recommendations; it should ground answers in reusable cases, expose risks, and let the team grow its own knowledge base over time.
 
-Создайте локальный файл `.env` в корне проекта. Не коммитьте его в Git.
+This project addresses that workflow with:
 
-Обязательные переменные:
+- a Telegram interface for quick access;
+- business consultation mode with Researcher, Consultant, and Critic agents;
+- RAG search over curated business cases;
+- Notion as a lightweight case-management backend;
+- local ChromaDB for embeddings and retrieval.
 
-```env
-OPENAI_API_KEY=your_openai_key
-TELEGRAMBOT_API_KEY=your_telegram_bot_token
-NOTION_API_KEY=your_notion_integration_secret
-PROXY_URL=optional_proxy_url
+## Key Features
+
+- **Telegram bot UX:** main menu, chat mode, business consultation mode, save-case flow, help/info screens.
+- **Multi-agent consultation:** CrewAI Researcher, Consultant, and Critic agents collaborate on business AI questions.
+- **RAG knowledge base:** `ChromaRAGTool` retrieves AI business cases from ChromaDB using OpenAI embeddings.
+- **Notion case storage:** structured case creation through the Notion API.
+- **Notion -> ChromaDB sync:** full rebuild and incremental sync scripts keep RAG data fresh.
+- **Conversation memory:** previous user turns are stored and retrieved from ChromaDB.
+- **Voice input:** Telegram voice messages are transcribed with Whisper before being routed to chat or consultation mode.
+- **Photo analysis in chat mode:** image messages can be sent to the OpenAI vision-capable chat endpoint.
+- **Tests and CI:** pytest suite with fakes/mocks, plus GitHub Actions.
+- **Dockerized runtime:** Dockerfile and Compose setup with a ChromaDB volume.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    U["Telegram User"] --> B["Telegram Bot<br/>telegram_bot.py"]
+    B --> O["Orchestrator<br/>orchestrator.py"]
+    O --> C["Chat Mode<br/>direct OpenAI response"]
+    O --> K["Consultation Mode<br/>CrewAI workflow"]
+    B --> S["Save Case Mode<br/>scribe.py"]
+    S --> N["Notion Database"]
+    O --> M["Conversation Memory<br/>memory.py"]
+    M --> DB["ChromaDB"]
+```
+
+```mermaid
+flowchart LR
+    Q["Business Question"] --> R["Researcher Agent"]
+    R --> T["Business Cases Search<br/>rag_tool.py"]
+    T --> V["ChromaDB<br/>business_cases"]
+    V --> R
+    R --> A["Consultant Agent"]
+    A --> C["Critic Agent"]
+    C --> F["Final Telegram Answer"]
+```
+
+More details are available in [docs/architecture.md](docs/architecture.md).
+
+## Multi-Agent Workflow
+
+The consultation mode is designed as a three-step review loop:
+
+1. **Researcher** searches the RAG knowledge base for relevant business cases, implementation patterns, tools, and outcomes.
+2. **Consultant** turns the retrieved context into a practical recommendation with suggested architecture, expected results, and next steps.
+3. **Critic** reviews the recommendation for missing evidence, implementation risks, hidden costs, data readiness, and compliance concerns.
+
+This structure is intentionally more conservative than a single prompt because it separates retrieval, recommendation, and risk review.
+
+## RAG Pipeline
+
+Business cases are stored in Notion and synchronized into a local ChromaDB collection:
+
+```mermaid
+flowchart LR
+    N["Notion DB<br/>business cases"] --> SY["Sync scripts<br/>notion_to_chromadb.py<br/>sync_notion_to_chromadb.py"]
+    SY --> E["OpenAI Embeddings<br/>text-embedding-3-small"]
+    E --> C["ChromaDB<br/>business_cases collection"]
+    C --> R["RAG Search<br/>rag_tool.py"]
+    R --> A["CrewAI Researcher"]
 ```
 
-## Установка
+See [docs/rag_pipeline.md](docs/rag_pipeline.md) for implementation notes.
+
+## Notion Integration
+
+The bot can save a new business case from Telegram into Notion using `scribe.py`. A case includes title, category, use case, tools, summary, implementation details, pros, cons, source, and date.
+
+Notion synchronization is handled by:
+
+- `notion_to_chromadb.py` for a full rebuild of the `business_cases` ChromaDB collection;
+- `sync_notion_to_chromadb.py` for incremental sync based on Notion `last_edited_time`.
+
+The Notion database id is configured through `NOTION_DATABASE_ID` and is not committed to the repository.
+
+## Voice Input via Whisper
+
+Telegram voice messages are downloaded as audio files, transcribed with Whisper, and then routed through the selected mode:
+
+- chat mode sends the transcript to direct chat;
+- consultation mode sends it to the multi-agent workflow;
+- auto mode chooses based on keywords.
+
+The voice path is kept inside `telegram_bot.py`, while pure helper logic is tested separately.
+
+## Tech Stack
+
+- Python 3.11
+- python-telegram-bot
+- OpenAI API: chat, embeddings, Whisper transcription
+- CrewAI
+- ChromaDB
+- Notion API
+- pytest and pytest-asyncio
+- Docker and Docker Compose
+- GitHub Actions CI
+
+## Demo
+
+The repository includes mock demo screenshots based on the implemented Telegram bot flows. They are not live Telegram screenshots and do not use real tokens.
+
+> UI flow mock based on implemented bot flows.
+
+| Main menu | Consultation mode |
+|---|---|
+| ![Main menu mock](docs/assets/main_menu.png) | ![Consultation mock](docs/assets/business_consultation.png) |
+
+| RAG result | Save case | Voice transcription |
+|---|---|---|
+| ![RAG result mock](docs/assets/rag_result.png) | ![Notion save mock](docs/assets/notion_save_case.png) | ![Voice flow mock](docs/assets/voice_transcription.png) |
+
+Optional flow GIF:
+
+![Mock flow GIF](docs/assets/demo_flow.gif)
+
+Demo prompts are listed in [docs/demo_queries.md](docs/demo_queries.md).
+
+## Setup
+
+Clone the repository and create a virtual environment:
 
 ```bash
+git clone https://github.com/grinegor/consulting-assistant.git
+cd consulting-assistant
 python -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
+pip install -r requirements-dev.txt
 ```
 
-## Запуск Бота
+Create local environment variables:
+
+```bash
+cp .env.example .env
+```
+
+Fill in `.env`:
+
+```env
+OPENAI_API_KEY=your_openai_api_key
+TELEGRAMBOT_API_KEY=your_telegram_bot_token
+NOTION_API_KEY=your_notion_integration_secret
+NOTION_DATABASE_ID=your_notion_database_id
+CHROMA_PATH=./chroma_db
+BUSINESS_CASES_COLLECTION=business_cases
+MEMORY_COLLECTION=conversation_memory
+```
+
+Run the bot:
 
 ```bash
 python telegram_bot.py
 ```
 
-## Синхронизация Кейсов Из Notion В ChromaDB
+Sync Notion cases into ChromaDB:
 
-Полная пересборка коллекции `business_cases`:
+```bash
+python sync_notion_to_chromadb.py
+```
+
+For a full rebuild:
 
 ```bash
 python notion_to_chromadb.py
 ```
 
-Инкрементальная синхронизация обновленных страниц Notion:
+## Docker Setup
+
+Build and run the Telegram bot service:
 
 ```bash
-python sync_notion_to_chromadb.py
+docker compose up --build
 ```
 
-## Тестирование
+The Compose setup:
 
-В проекте есть автоматические тесты для основной логики бота, синхронизации Notion/ChromaDB, форматирования RAG-ответов, создания Notion payload через Scribe и eval-проверок маршрутизации. Внешние сервисы, включая Telegram, Notion, OpenAI, ChromaDB и CrewAI, замоканы в тестах, поэтому suite запускается без реальных API-вызовов и секретов.
+- reads secrets and ids from `.env`;
+- mounts `./chroma_db` into the container for local ChromaDB persistence;
+- runs `python telegram_bot.py`.
 
-Запустить все тесты:
+Stop the service:
 
 ```bash
-python -m pytest -q
+docker compose down
 ```
 
-Запустить только легкие eval-проверки маршрутизации:
+## Tests
+
+Run the full test suite:
 
 ```bash
-python -m pytest -q -m eval
+pytest
+```
+
+Run the compact CI-style command:
+
+```bash
+python -m pytest -q
 ```
 
-Запустить только локальные stress/boundary проверки:
+Run eval and stress subsets:
 
 ```bash
+python -m pytest -q -m eval
 python -m pytest -q -m stress
 ```
 
-Проверить компиляцию Python-файлов проекта:
+Compile-check project files:
 
 ```bash
 python -m compileall -q telegram_bot.py scribe.py agents.py digest.py main.py memory.py notion_to_chromadb.py orchestrator.py rag_tool.py sync_notion_to_chromadb.py tests
 ```
 
-GitHub Actions автоматически запускает тесты и compile-check при push и pull request в ветку `main`.
+Tests use mocks/fakes instead of real Telegram, OpenAI, Notion, CrewAI, or ChromaDB calls.
+
+## Roadmap
+
+- Add a web dashboard for reviewing synced cases and retrieval quality.
+- Add scheduled Notion synchronization.
+- Add structured observability for agent runs and retrieval traces.
+- Add richer eval datasets for consultation quality and risk coverage.
+- Add deployment manifests for a small cloud VM or container platform.
+
+## Known Limitations
 
-## Заметки
+- MVP-grade local deployment, not a production SaaS backend.
+- ChromaDB is local by default and should be backed up or replaced for production.
+- No enterprise auth, RBAC, tenant isolation, or audit log yet.
+- No production monitoring, alerting, or tracing yet.
+- Telegram markdown output may require extra escaping for arbitrary model output.
+- Notion schema expectations are currently encoded in the sync scripts.
 
-- `.env`, `.venv`, `.idea` и локальные файлы `chroma_db` намеренно игнорируются Git.
-- Локальная база ChromaDB является runtime-данными и должна пересоздаваться или синхронизироваться локально.
-- API-ключи и токены бота нужно хранить только в `.env` или в переменных окружения deployment-среды.
+More detail is documented in [docs/limitations.md](docs/limitations.md).

docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  bot:
+    build: .
+    environment:
+      OPENAI_API_KEY: ${OPENAI_API_KEY:?OPENAI_API_KEY is required}
+      TELEGRAMBOT_API_KEY: ${TELEGRAMBOT_API_KEY:?TELEGRAMBOT_API_KEY is required}
+      NOTION_API_KEY: ${NOTION_API_KEY:?NOTION_API_KEY is required}
+      NOTION_DATABASE_ID: ${NOTION_DATABASE_ID:?NOTION_DATABASE_ID is required}
+      PROXY_URL: ${PROXY_URL:-}
+      CHROMA_PATH: /app/chroma_db
+      BUSINESS_CASES_COLLECTION: ${BUSINESS_CASES_COLLECTION:-business_cases}
+      MEMORY_COLLECTION: ${MEMORY_COLLECTION:-conversation_memory}
+      SYNC_STATE_FILE: ${SYNC_STATE_FILE:-sync_state.json}
+    volumes:
+      - ./chroma_db:/app/chroma_db
+    restart: unless-stopped