0) Clone the repo 📥

git clone https://github.com/zomry1/Samuraizer.git
cd Samuraizer

1) Config 🔐

Copy .env.example to .env and fill in your values. You can also open the web UI, go to the Settings tab, and adjust settings there (provider, API keys, Ollama model names, embedding model names) before save.

cp .env.example .env

# Install Ollama CLI (platform-dependent)
# macOS
curl -fsSL https://ollama.com/install.sh | sh

# Windows
irm https://ollama.com/install.ps1 | iex

# Linux (Ubuntu/Debian)
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama service
ollama serve

# Install models
ollama pull qwen3:4b            # reasoning
ollama pull qwen3-embedding:8b  # embeddings

# Set provider in .env
LLM_PROVIDER=ollama

2) Install dependencies 📦

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -r requirements.txt

cd frontend
npm install
cd ..

3) Run backend ▶️

python server.py

4) Run frontend 🌐 (new terminal)

cd frontend
npm run dev

5) (Optional) Run Telegram bot 🤖 (new terminal)

python telegram_bot.py

The easiest way to run the full stack — one command builds and starts everything.

0) Clone the repo 📥

git clone https://github.com/zomry1/Samuraizer.git
cd Samuraizer

1) Config 🔐

cp .env.example .env
# Edit .env and fill in GEMINI_API_KEY (and any other values you need)

2) Build & run ▶️

All Docker files live in the docker/ folder. Run commands from the project root:

Gemini (cloud) — default:

docker compose -f docker/docker-compose.yml up -d

Ollama on CPU:

docker compose -f docker/docker-compose.yml --profile ollama up -d

Ollama on NVIDIA GPU:

docker compose -f docker/docker-compose.yml --profile ollama-nvidia up -d

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Ollama on AMD GPU (requires ROCm-capable GPU + amdgpu driver on Linux):

docker compose -f docker/docker-compose.yml --profile ollama-amd up -d

That's it. The frontend is at http://localhost and the API at http://localhost:8000.

Tip: When using any Ollama profile, set LLM_PROVIDER=ollama in your .env. The OLLAMA_URL is automatically set to http://ollama:11434 inside the containers — you don't need to change it.

After first start with Ollama, pull the models (use the container name matching the profile you started):

# --profile ollama
docker exec -it samuraizer-ollama-1 ollama pull qwen3:4b
docker exec -it samuraizer-ollama-1 ollama pull qwen3-embedding:8b

# --profile ollama-nvidia
docker exec -it samuraizer-ollama-nvidia-1 ollama pull qwen3:4b
docker exec -it samuraizer-ollama-nvidia-1 ollama pull qwen3-embedding:8b

# --profile ollama-amd
docker exec -it samuraizer-ollama-amd-1 ollama pull qwen3:4b
docker exec -it samuraizer-ollama-amd-1 ollama pull qwen3-embedding:8b

• Backend and frontend restart automatically on failure.
• Docker stores the database and log file under the project's data/ directory and backups under db_backups/.
• Ollama model files are stored in the ollama_data Docker volume (persists across restarts).
• The Telegram bot is disabled by default. Combine profiles to enable it alongside Ollama:

docker compose -f docker/docker-compose.yml --profile ollama-nvidia --profile bot up -d

Updating

git pull
docker compose -f docker/docker-compose.yml up -d --build

Stopping

docker compose -f docker/docker-compose.yml down

Why not youtube-transcript-api?

The original implementation used the open-source youtube-transcript-api Python library. It works well locally but has a critical limitation in practice: YouTube aggressively blocks IP addresses that make automated transcript requests, especially:

• IPs belonging to cloud providers / VPS hosts (AWS, GCP, Azure, Hetzner, etc.)
• IPs that hit the transcript endpoint too frequently

This meant that after analyzing just a handful of videos, the whole server would get blocked and every subsequent transcript fetch would fail with an IPBlocked / RequestBlocked error — completely breaking YouTube video analysis.

Current solution: transcriptapi.com

Samuraizer now uses transcriptapi.com — a third-party paid API that handles the YouTube transcript fetching on their end, routing through infrastructure that isn't blocked.

Pros:

• No IP blocks — they manage the anti-bot problem for you
• Simple REST API (GET /api/v2/youtube/transcript)
• Free tier available; credits only charged on success (HTTP 200)
• Retryable error codes (408 / 503) with clear semantics

Cons:

• Not free beyond the free tier (credit-based billing)
• External dependency — if their service is down, transcript fetching fails
• Data goes through a third party

Setup: Add to .env:

TRANSCRIPTAPI=your_key_here

Get a key at transcriptapi.com/dashboard/api-keys.

Alternatives worth considering

Best free alternative: yt-dlp — it is actively maintained, mimics real browser requests, and is unlikely to get blocked as quickly as a plain HTTP request. To switch, replace _fetch_youtube_content to shell out to yt-dlp --write-auto-sub --sub-format vtt --skip-download and parse the resulting .vtt file.

Analyze a URL

POST /analyze

Body:

{ "url": "https://github.com/owner/repo" }

Analyze a PDF

POST /analyze-pdf

Body: multipart/form-data with a file field containing a .pdf file. Streams NDJSON events in the same shape as /analyze (using the filename as the url key).

Retrieve a stored PDF

GET /entries/<id>/pdf — serves the PDF inline in the browser. GET /entries/<id>/pdf?dl=1 — serves the PDF as a file download.

List entries

GET /entries (supports filters: search, category, tag, source, list_id, read, useful)

YouTube channel subscriptions

• GET /yt-channels — list subscribed channels (id, channel_id, channel_url, name, last_checked)
• POST /yt-channels/preview — body { "url": "https://www.youtube.com/@handle" }, returns channel info + latest videos (url/title/published)
• POST /yt-channels — body { "url": "...", "name": "optional", "analyze_urls": ["https://...", ...] }; create subscription and optionally analyze selected videos
• POST /yt-channels/<id>/poll — immediate manual poll for a channel
• DELETE /yt-channels/<id> — remove subscription

Manage tags

• Tag edits happen via PATCH /entries/<id> with JSON { "tags": ["tag1","tag2"] }