Content
# EduFlow AI Assistant
AI assistant for online learning platform EduFlow. Automatically answers student questions, provides course information, processes payments, and escalates complex queries to live instructors.
**170 tests** | **84% coverage** | **Production-Ready**
---
## Tool List
- Multi-agent system with query classification
- Support for OpenAI and YandexGPT (Protocol abstraction)
- RAG with ChromaDB for knowledge base (200+ articles)
- Integration with Bitrix24 CRM (deal statuses, contacts, history)
- Multi-channel support: Telegram + MAX Messenger (via Wappi, distinguished by profile_id)
- Structured JSON logging (PII masking)
- Protection against prompt injection, XSS, SQL injection
- Asynchronous architecture (FastAPI + asyncpg + asyncio)
- Docker + nginx + PostgreSQL 15
- GitHub Actions CI/CD (tests, security, Docker build)
---
## Architecture
```mermaid
flowchart TD
A["Incoming message\n(Telegram / MAX Messenger)"] --> B["Wappi Webhook\nchannel detection, validation,\ndeduplication, user mapping"]
B --> C["Orchestrator\nFAQ short-answer check"]
C --> D["ClassifierAgent\nrule-based + LLM classification"]
D -->|"~15%"| E["TypicalAgent\ngreeting / thanks / confirmations"]
D -->|"~50%"| F["CourseAgent\ncourse info + deal status\nfrom Bitrix24"]
D -->|"~5%"| G["PlatformAgent\ntechnical support\nRAG knowledge base"]
D -->|"~30%"| H["ESCALATE\ncomplex queries\nlive instructor"]
E --> I["Response via Wappi API"]
F --> I
G --> I
H --> I
```
### Components
| Component | Purpose |
|-----------|---------|
| **Orchestrator** | Main message routing engine |
| **ClassifierAgent** | Message type detection (rule-based + LLM fallback) |
| **TypicalAgent** | FAQ templates, greetings, confirmations |
| **CourseAgent** | Course enrollment, payment status (Bitrix24) |
| **PlatformAgent** | Platform FAQ, technical help (RAG) |
| **LLMClient** | Protocol abstraction for OpenAI/YandexGPT |
| **VectorDB** | ChromaDB with OpenAI embeddings |
| **BitrixClient** | CRM integration (deals, contacts, stages) |
| **WappiIncomingHandler** | Webhook parsing + deduplication |
| **WappiOutgoingHandler** | Message sending via Wappi API |
---
## Requirements
- Python 3.11+
- PostgreSQL 15+
- Docker & Docker Compose (for production)
- API keys: OpenAI, YandexGPT (optional), Wappi, Bitrix24
---
## Quick Start
### 1. Clone and Prepare
```bash
git clone https://github.com/your-org/ai_assistant_eduflow.git
cd ai_assistant_eduflow
python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
```
### 2. Configuration
```bash
cp deployment/.env.example .env
# Edit .env:
# - OPENAI_API_KEY or YANDEX_API_KEY (required)
# - POSTGRES_DSN (default: postgresql+asyncpg://postgres:postgres@localhost:5432/ai_assistant_eduflow)
# - WAPPI_API_TOKEN (for Telegram/WhatsApp)
# - BITRIX24_WEBHOOK_URL (for CRM integration)
```
### 3. Database
```bash
createdb ai_assistant_eduflow
alembic upgrade head
```
### 4. Run
```bash
python -m uvicorn app:app --reload
# http://localhost:8000
# http://localhost:8000/docs (Swagger UI)
# http://localhost:8000/health
```
### 5. Tests
```bash
pytest tests/ -v
pytest tests/ --cov=. --cov-report=html
```
---
## Deployment (Docker)
```bash
docker-compose -f docker-compose.prod.yml up -d
curl http://localhost/health
```
### Services
| Service | Port | Purpose |
|--------|------|---------|
| **webhook** | 8000 | FastAPI application |
| **db** | 5432 | PostgreSQL (internal) |
| **nginx** | 80, 443 | Reverse proxy + SSL |
---
## MCP Server
EduFlow provides an MCP server (Model Context Protocol) that gives AI assistants access to the knowledge base and CRM via a standard protocol.
### Quick Start
```bash
# Local run (stdio — for Claude Code / Cursor)
python -m mcp_server.server
# Docker (SSE — for network access)
docker compose -f docker-compose.prod.yml up mcp-server
```
### Connection to Claude Code
The `.mcp.json` file in the project root is automatically picked up by Claude Code:
```json
{
"mcpServers": {
"eduflow": {
"command": "python",
"args": ["-m", "mcp_server.server"]
}
}
}
```
### Available Tools
| Tool | Description |
|------|------------|
| `search_knowledge_base` | Search EduFlow knowledge base (RAG) |
| `get_deal` | Get deal information from Bitrix24 CRM |
| `find_deals_by_phone` | Find deals by phone number |
### Example Usage
```
> search_knowledge_base("How to reset password?")
1. If you forgot your password, click the 'Forgot password?'
button on the login page. You will be sent an email with a link...
2. To reset your password, you will need access to the email
address you registered with...
```
---
## LangChain Pipeline
The project contains two parallel implementations of message processing:
| Pipeline | Description | Switching |
|----------|------------|-----------|
| **Original** (default) | Proprietary orchestration, direct OpenAI API calls | `PIPELINE_MODE=original` |
| **LangChain** | LangChain Retriever + Chains, same RAG and prompts | `PIPELINE_MODE=langchain` |
Both implementations return the same `AgentResponse` — switching is transparent to clients.
---
## Langfuse Observability
Tracing LLM calls through [Langfuse](https://langfuse.com):
- **Original pipeline**: `@observe` decorators on Orchestrator, Classifier, CourseAgent, PlatformAgent
- **LangChain pipeline**: automatic CallbackHandler for all chains and retrievers
- **Dashboard**: prompts, responses, tokens, latency, cost — filtering by `pipeline` and `user_id`
```bash
LANGFUSE_ENABLED=true
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_SECRET_KEY=sk-...
```
---
## API Endpoints
### POST `/webhook/wappi` — Telegram/WhatsApp
```json
{
"message_type": "text",
"from": "+79991234567",
"body": "How to start studying the course?",
"message_id": "msg_abc123xyz",
"timestamp": 1700000000,
"chat_id": "1234567890"
}
```
### POST `/webhook/bitrix` — Bitrix24 CRM
Events: `ONCRMDEALUPDATE`, `ONCRMDEALSTAGECHANGE`, `ONCRMLEADUPDATE`
### GET `/health`
```json
{"status": "ok", "database": "connected"}
```
### GET `/stats`
```json
{"total_messages": 1542, "total_escalations": 187}
```
---
## Security
- **HMAC webhook validation** — timing-safe token comparison
- **Rate limiting** — 100 req/min per IP (slowapi)
- **Input sanitization** — XSS, SQL injection, null bytes
- **No stack trace leaks** — global exception handler
- **PII masking** — logging without phone numbers and user_id
- **Prompt injection protection** — security gates in system prompts
- **Strict typing** — pyright strict mode, zero `any`
- **Supply chain** — pip-audit + gitleaks in CI
### Environment Variables
```bash
OPENAI_API_KEY=sk-...
YANDEX_API_KEY=...
BITRIX24_WEBHOOK_URL=https://...
WAPPI_API_TOKEN=...
POSTGRES_DSN=postgresql+asyncpg://...
```
---
## Testing
170 tests, 84% coverage, TDD approach.
```bash
pytest tests/ # all
pytest tests/unit/ -v # unit
pytest tests/integration/ -v # integration
pytest tests/e2e/ -v # e2e (full pipeline)
pytest --cov=. --cov-report=term-missing # coverage
```
---
## CI/CD
| Workflow | Trigger | What it does |
|----------|---------|-----------|
| **test.yml** | Push/PR | pytest, coverage, pyright |
| **security.yml** | Push/PR | bandit, gitleaks, pip-audit |
| **docker-build.yml** | Push main | docker build + smoke test |
---
## Project Structure
```
ai_assistant_eduflow/
├── agents/ # Multi-agent system
│ ├── orchestrator.py
│ ├── classifier.py
│ ├── typical_agent.py
│ ├── course_agent.py
│ └── platform_agent.py
├── integrations/ # External services
│ ├── llm_client.py
│ ├── bitrix_client.py
│ ├── vector_db.py
│ ├── database.py
│ ├── logging.py
│ └── wappi/
│ ├── incoming.py
│ ├── outgoing.py
│ └── templates.py
├── repositories/ # Database layer
│ ├── user_mapping.py
│ ├── dialog_log.py
│ └── analytics.py
├── routers/ # FastAPI routes
│ ├── wappi.py
│ ├── bitrix.py
│ └── admin.py
├── prompts/ # LLM prompts
├── utils/ # Sanitization, validation
├── tests/ # 170 tests (unit + integration + e2e)
├── alembic/ # Database migrations
├── deployment/ # Docker, nginx, .env
├── app.py
├── config.py
├── Dockerfile
└── docker-compose.prod.yml
```
---
## Contributing
### Commit Convention
```
feat(agents): add TypicalAgent for greetings
fix(db): handle concurrent user mapping updates
refactor(orchestrator): simplify message routing
test(classifier): add edge case tests
chore(docker): update base image
```
### Workflow
1. `git checkout -b feature/my-feature`
2. Tests first (TDD), code passes all checks
3. `pytest tests/ --cov=. && ruff check . && pyright .`
4. `git push origin feature/my-feature` + PR
---
## License
MIT
