Installation Guide¶

Detailed installation instructions for tg-note.

System Requirements¶

Required¶

Python 3.11 or 3.12 (Python 3.13 is not supported)
Poetry - Python dependency manager
Git - Version control system
Telegram Account - To create and use the bot

Optional¶

Node.js 20+ - Required for qwen_code_cli agent (recommended)
Docker - For containerized deployment

Installation Methods¶

Local InstallationDocker Installation

1. Install Python 3.11 or 3.12¶

Check your Python version:

python3 --version

Python Version

tg-note requires Python 3.11 or 3.12. Python 3.13 is not currently supported.

If you need to install Python 3.11 or 3.12:

Ubuntu/DebianmacOSWindows

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip

brew install python@3.11

Download from python.org

2. Install Poetry¶

curl -sSL https://install.python-poetry.org | python3 -

Or using pipx:

pipx install poetry

Add Poetry to your PATH (if needed):

export PATH="$HOME/.local/bin:$PATH"

3. Clone the Repository¶

git clone https://github.com/ArtyomZemlyak/tg-note.git
cd tg-note

4. Install Dependencies¶

poetry install

This creates a virtual environment and installs all required packages.

5. Verify Installation¶

poetry run python -c "from config import settings; print('Installation successful!')"

Use Docker for a reproducible setup. See detailed guides in the Deployment section.

# Build and start services
docker compose up -d --build

# (optional) Authenticate Qwen CLI inside the bot container
docker exec -it tg-note-bot bash -lc "qwen"
docker exec -it tg-note-bot bash -lc "qwen <<<'/approval-mode yolo --project'"

For service details see: Docker Deployment
For semantic search stack see: Vector Search

Optional Dependencies¶

Qwen Code CLI (Recommended for Production)¶

The Qwen Code CLI agent provides the best AI-powered processing capabilities.

1. Install Node.js 20+¶

Ubuntu/DebianmacOSWindows

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

brew install node@20

Download from nodejs.org

2. Install Qwen Code CLI¶

npm install -g @qwen-code/qwen-code@latest

3. Verify Installation¶

qwen --version

4. Authenticate¶

qwen

Follow the interactive authentication process. You'll get:

2000 free requests per day
60 requests per minute
No token limits

Learn more about Qwen Code CLI →

Post-Installation Setup¶

1. Create Configuration Files¶

# Copy example configuration
cp config.example.yaml config.yaml

2. Setup Environment Variables¶

Create a .env file:

touch .env

Add your credentials:

# Required
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Optional - For advanced features
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

Security

Never commit your .env file to version control! It's already in .gitignore, but always double-check.

3. Configure Basic Settings¶

Edit config.yaml:

# Knowledge Base
KB_PATH: ./knowledge_base
KB_GIT_ENABLED: true
KB_GIT_AUTO_PUSH: true

# Agent Type
AGENT_TYPE: "stub"  # Options: stub, autonomous, qwen_code_cli

# Logging
LOG_LEVEL: INFO
LOG_FILE: ./logs/bot.log

Full configuration guide →

Verification¶

Run Tests¶

Verify everything is working:

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src --cov-report=html

# Run specific test
poetry run pytest tests/test_tracker.py -v

Check Configuration¶

poetry run python -c "from config import settings; print(settings)"

Test Bot Connection¶

# Recommended: Use the console script
poetry run tg-note

# Or directly with Python
poetry run python main.py

You should see:

INFO - Starting tg-note bot...
INFO - Configuration validated successfully
INFO - Bot initialization completed

Directory Structure¶

After installation, your directory should look like:

tg-note/
├── config/              # Configuration modules
├── src/
│   ├── bot/            # Telegram bot
│   ├── processor/      # Message processing
│   ├── agents/         # AI agents
│   ├── knowledge_base/ # KB management
│   └── tracker/        # Processing tracker
├── tests/              # Unit tests
├── data/               # Created on first run
├── logs/               # Created on first run
├── config.yaml         # Your configuration
├── .env                # Your credentials
├── pyproject.toml      # Project metadata
├── poetry.lock         # Dependency lock file
└── main.py            # Entry point

Updating¶

To update tg-note to the latest version:

git pull origin main
poetry install

To update dependencies:

poetry update

Troubleshooting Installation¶

Poetry Not Found¶

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Make permanent
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Python Version Issues¶

# Use specific Python version with Poetry
poetry env use python3.11

# Verify
poetry run python --version

Permission Errors¶

# On Linux/macOS
sudo chown -R $USER:$USER ~/.local

# Or install without sudo
curl -sSL https://install.python-poetry.org | python3 - --user

Virtual Environment Issues¶

# Remove and recreate
poetry env remove python
poetry install

Next Steps¶

After successful installation:

Uninstallation¶

To completely remove tg-note:

# Remove virtual environment
poetry env remove python

# Remove project directory
cd ..
rm -rf tg-note

# Optionally remove Poetry
pipx uninstall poetry