TagKy (build)

Minimal runnable package for TagKy.

Quick start

# 1) Install deps
pnpm i   # or: npm i / yarn install

# 2) Create local env
cp ./.env.example ./.env.local
# then edit ./.env.local (PUBLIC_KEY, SEED_PHRASE, ...)

# 3) Run orchestrator
node start.js

# 4) Optional: Web monitor (in another terminal)
node web-monitor.js

Web monitor: http://localhost:${WEB_MONITOR_PORT:-3001}

What is TagKy?

• Purpose: TagKy is a bot that automatically tags posts with 1–3 relevant keywords.
• Platform: Publishes tags via the Pubky protocol and @synonymdev/pubky client.
• LLM: Uses a local/remote Ollama model (configurable) to extract concise keywords.
• Dashboard: Includes a real‑time web monitor to visualize stats and activity.

High-level flow

1. Fetcher (fetcher.js): listens to notifications/mentions and enqueues jobs in SQLite.
2. Worker (worker.js): calls Ollama to generate 1–3 keywords and updates job state.
3. Publisher (publisher.js): publishes tags to Pubky for the target post/user.
4. Web Monitor (web-monitor.js): live dashboard for stats, errors and recent activity.
5. Orchestrator (start.js): starts and supervises the fetcher/worker/publisher.

Overview

• Node.js ES modules.
• Centralized env loader: lib/load-env.js.
• Local-only env: ./.env.local (ignored).

Setup

1. Install deps

pnpm i   # or: npm i / yarn install

2. Configure env

cp ./.env.example ./.env.local
# edit ./.env.local with your keys (PUBLIC_KEY, SEED_PHRASE, ...)

Run

• Orchestrator (spawns fetcher/worker/publisher)

node start.js

• Web monitor (dashboard)

node web-monitor.js

Scripts

• fetcher.js: pulls notifications and enqueues jobs.
• worker.js: generates keywords (LLM) and updates jobs.
• publisher.js: publishes tags via Pubky API.
• init-queue-db.js: initializes SQLite schema (auto-run by start.js when needed).

Architecture details

• Database: local SQLite (queue.db) for jobs, tags and metrics.
• Env management: lib/load-env.js loads ./.env.local (preferred) without overriding existing process.env.
• Tagging rules: prompt enforces 1–3 keywords, semicolon-separated, spaces replaced by hyphens.
• Resilience: worker/publisher log errors and keep job state for retries/analysis.

Environment

Key variables (set in ./.env.local):

• PUBLIC_KEY (required)
• SEED_PHRASE or MNEMONIC (required)
• NEXUS_API_URL, OLLAMA_URL, OLLAMA_MODEL
• TAGKY_* intervals, flags, and messages
• WEB_MONITOR_PORT

Note: Docker usage belongs to the monorepo root; this sub-repo is for the runnable build only.

Changelog

• 2025-08-21
  • Add Quick start section.
  • Docker Compose updated to build directly from GitHub dev branch.
  • Fix: prevent duplicate replies on container restart (idempotency in fetcher.js).
  • Feature: skip tagging for empty-content posts (reposts) in fetcher.js and worker.js.
  • Change: after /tag on, mark recent posts as processed to only tag future posts.