Installation Guide¶

Detailed installation instructions for tg-note.

System Requirements¶

Required¶

Python 3.11 or higher
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+¶

Check your Python version:

python3 --version

If you need to install Python 3.11+:

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!')"

Coming Soon

Docker support is planned for future releases.

For now, please use the local installation method.

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¶

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