aichat-go

Every incoming Telegram message follows this path:

1. Webhook reception — POST /webhook/{tg_api_key} received on the public HTTP server (:8080). The API key in the URL routes to the correct project bundle.
2. Gateway normalization — TelegramUpdate is converted to domain.Message with text, caption, files, and sender info extracted.
3. State loading — Chat state loaded from PostgreSQL using composite key (chat_id, project_id).
4. Command check — /start resets state and returns greeting. /debug toggles debug mode.
5. File collection — Any file attachments are accumulated into state. Files without text get an immediate acknowledgement without LLM calls.
6. Stage dispatch — Based on derived state (CurrentStage()), the message is routed to the appropriate stage handler.
7. State persist — Updated state written back to PostgreSQL.
8. Timer reset — Follow-up timer reset to step 0 for this chat.

cmd/
  bot/         # Main bot binary
    main.go     # Wiring: DB, tiered LLM, per-project bundles, HTTP server
    config.go   # JSON config loading with env var fallback
  crawler/     # Knowledge base indexer CLI
    main.go     # Subcommands: init-project, seed, add-urls, register
  cli/         # Local readline chat interface (testing)
    main.go     # Same agent pipeline, file-based CRM output

internal/
  domain/      types.go        # Stage, Message, ChatState, Lead, Block
  agent/       agent.go        # HandleMessage entrypoint
                toolagent.go    # Tool-calling loop, tool dispatch, system prompt
                commands.go     # /start, /debug
                lead_commands.go # Lead group: /prompt, /stats
                trace.go        # Per-turn trace records for debugging
  llm/         toolcaller.go               # ToolCaller interface, Block/Message types
                toolcaller_anthropic.go     # Anthropic Messages API backend
                toolcaller_openai.go        # OpenAI tools spec backend (covers OpenRouter)
                toolcaller_chain.go         # Multi-backend fallback chain
                tiered.go       # TieredClient (extract / embedding tiers)
                openai.go       # OpenAI-compatible provider (extract, embeddings)
                claude.go       # Claude provider (extract)
                embedding_adapter.go # Model-specific text formatting
  search/      hybrid.go       # Qdrant DBSF fusion (dense + BM25)
                bm25.go         # BM25Encoder, Tokenize
  db/          postgres.go     # PostgreSQL implementation
  gateway/     telegram.go     # TelegramUpdate normalization
  telegram/    client.go       # HTTP client, retry on 429
  crm/         telegram.go     # TelegramCRM: summary + history + media
  timer/       timer.go        # Scheduler, sequences, LLM classification
  metrics/     metrics.go      # Metric definitions
                llm.go          # InstrumentedLLMClient wrapper
  crawler/     pipeline.go     # Resumable 4-phase pipeline
                chunker.go      # Semantic + simple chunking
                indexer.go      # Qdrant upsert
  i18n/        i18n.go         # T(), Tf(), embedded locales
                locales/    ru.json, en.json

migrations/  001-013 (latest: 012_chat_history_blocks.sql, 013_drop_3stage_remnants.sql)
nix/         module.nix, example-configuration.nix
flake.nix    Makefile

Finished=true is written to the database before the CRM send, and LeadSent=true is written after. This prevents duplicate leads from concurrent webhook requests or timer fires reading stale state. If the bot crashes between the two persists, the timer system retries the CRM send on next fire or on restart (via chatStore.ListFinishedUnsent).

The full assistant / tool-result block sequence for each turn is stored in chat_history.blocks (JSONB). On the next turn, rebuildMessages replays these blocks back to the model so it sees its own prior tool_use and tool_result exchanges. Falls back to plain question / reply for legacy rows where blocks is empty.

When a user sends a file without text, the bot immediately acknowledges it ("Accepted! Let me know when you're done.") without calling the LLM. Files are accumulated on ChatState.Files and attached to the lead when send_lead fires.

Media files in the lead are grouped by type for clean presentation:

• Photos + Videos — sent as a media album (Telegram groups them visually)
• Documents — sent as a document album
• Voice / Video notes — sent individually (Telegram does not support albums for these)

On the first turn that mentions contact collection, the bot sends a Telegram request_contact keyboard button alongside its reply. This lets users share their phone number with one tap.

• Sent only once per conversation
• Shared contact lands in ChatState.SharedContact (not in history) for privacy
• Included in the dispatched lead

The timer scheduler runs the same tool-calling loop with a synthetic [TIMER PING] user turn. The agent decides whether to send a follow-up message or call send_lead itself. At the last interval (24h) the timer dispatches the lead unconditionally for any unresolved chat — regardless of client_status — so no lead is lost. Hot clients with contact in hand should be dispatched earlier by the agent itself (the prompt encourages send_lead after 1–2 pings when there's enough info).

When the safety-net dispatch fires and the agent never called send_lead itself, state.LeadSummary is empty. The timer then asks the agent to summarize the dialog via Agent.SummarizeForLead — a one-shot Complete call (no tools) on the summary tier (cheap mid-tier, e.g. gemma-4-26b-a4b-it). It renders the dialog as a Client/Bot transcript plus the agent’s Notes scratchpad and produces a 1–2 paragraph summary for the human reviewer, so the lead post never arrives blank.

set_state(notes="...") is the agent’s free-form text scratchpad. It replaced the earlier structured contact{method,value} + extras{...} schema. The model writes plain text, full rewrite each call — whatever it omits is lost. Conventions live in the tool description, not the schema:

name: Виктор
contact: phone +79130001234
service: оценка квартиры
city: Барнаул
date: на следующей неделе

The scratchpad is rendered into the system suffix on every turn so the model sees its own state, and it’s the input to Agent.SummarizeForLead at 24h dispatch. The flat-string shape is deliberate: weak toolcaller models (e.g. glm-5.1) drop closing braces on nested-object set_state args, which used to silently lose phone numbers and trip the tool-loop overflow guard.

After send_lead fires, the chat doesn’t go silent. The customer can keep typing for up to five more messages; each one is appended to chat_history and the existing CRM lead artifact is refreshed in place — for Telegram, editMessageText on the summary post + editMessageMedia on the chat-history .txt attachment. The summary text stays frozen, but a history updated: <ts> footer appears so the operator notices.

CRM artifact references live in a dedicated lead_dispatches table (chat_id, project_id, provider) — one row per CRM. Multi-CRM by construction: a chat dispatched to both Telegram and Bitrix gets two rows, and the post-send refresh fans UpdateLead across all of them.

Inbound messages don’t hit HandleMessage directly. Each gateway (Telegram webhook, CLI loop) calls agent.Enqueue, which persists the user message as an orphan row in chat_history (Question filled, Reply empty) and pushes onto a per-chat cheggaaa/mb queue. One worker goroutine per (chat_id, project_id) drains the queue serially.

What this gives:

• No double-dispatch race: single worker per chat — the structural fix for the goroutine race that previously stomped state and produced two CRM posts for one customer.
• Burst coalescing: messages that arrive while the worker is mid-LLM accumulate in the queue and get processed as the next batch. The model sees one combined user turn, not three sequential ones.
• Crash recovery: orphan rows that survive a process kill get picked up by the next batch — no message lost.

Replies flow back through a per-project agent.Replier callback (cmd/bot wires it to tgClient.SendMessage; cmd/cli prints to stdout). Workers exit after five minutes idle and respawn on the next message.

• Standard BM25 formula: IDF * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * dl/avgDL))
• Parameters: k1=1.5, b=0.75
• Tokenizer: Unicode-aware (Cyrillic + Latin), lowercased, split on non-letter/digit
• Persistence: vocabulary, IDF, avgDL, numDocs stored as JSONB in PostgreSQL (bm25_indexes table)
• In-memory cache: loaded from DB on first use per project, invalidated on crawler updates

• Prefix (stable, cached): engine preamble (agent.toolcaller_preamble) + project prompt1 + tools schema. Anthropic backends mark this with cache_control: ephemeral for a 90% input discount on cache hits. OpenAI / DeepSeek / GLM auto-cache long stable prefixes (~50% discount when cached_tokens > 0).
• Suffix (volatile, breaks cache): per-turn state snapshot — DeterminedURL, contact, extras, files, optional PriceURL hint, ClientStatus.

Each ToolCaller / Provider chain has independent retry and fallback:

Attempt 1 → rate-limit/transient? → backoff (1s + jitter) → retry
Attempt 2 → rate-limit/transient? → backoff (2s + jitter) → retry
Attempt 3 → rate-limit/transient? → fall through
Non-transient error? → fall through immediately
All exhausted → AllProvidersExhaustedError

Backoff formula: 2^attempt + 10% jitter, capped at 60s (or whatever the provider's Retry-After header says, if shorter). Key pool rotates API keys round-robin.

Transient classification: rate limits (429) are transient. For OpenAI-tools backends we also treat embedded errors and empty choices arrays as transient (return RateLimitError) — observed when DeepSeek/GLM upstream returns a malformed success.

Embedding Adapters

AdaptedProvider wraps the embedding provider and formats text based on mode (document vs query). Adapter selected automatically by model name. E5-instruct / Qwen3-Embedding models get Instruct: ...\nQuery: ... prefix for queries. Token limit auto-split: when a chunk exceeds the model's token limit, text is split by sentence, each half embedded recursively, and vectors averaged + L2-normalized.

new-projects/{project-name}/
  1_pages/{urlhash}.json    # single Page per URL
  2_chunks/{urlhash}.json   # []Chunk per URL
  3_embeds/{urlhash}.json   # []EmbeddedChunk per URL
  3_embeds/bm25.json        # BM25 encoder snapshot

Semantic Chunking (default)

One LLM call per page (extract tier, temp 0.1) detects natural topic boundaries. The LLM outputs anchor phrases in the format TOPIC: X | STARTS: Y. The original text is sliced at the detected boundaries, preserving the exact source text without LLM paraphrasing. Each chunk receives a topic label for embedding.

Simple Chunking (--no-llm-chunk)

Paragraph and heading-aware splitting. Text is split on double newlines and markdown headings. Short paragraphs are merged up to maxChars (default 1500). Chunks get numbered topic labels ("Part 1", "Part 2", etc.).

At index time, each chunk's text is prepended with its topic label before embedding:

Before: "Our basic plan starts at $99/month with unlimited support."
After:  "Topic: Pricing plans\n\nOur basic plan starts at $99/month with unlimited support."

The topic acts as a semantic anchor — the embedding now captures the chunk's theme, not just its surface content. A query about "costs" will match closer to a chunk anchored with "Pricing plans" even if the chunk text never mentions "costs".

Search queries do not need the topic prefix — the embedding space naturally aligns.

# Create a new project and seed immediately
bin/aichat-crawler init-project \
  --name myproject \
  --tg-api-key "123456:ABC-DEF" \
  --tg-lead-group -1001234567890 \
  --language en \
  --prompt1 "You are a sales consultant..." \
  --start-reply "Welcome! How can I help?" \
  --sitemap-url "https://example.com/sitemap.xml"

# Seed a project later (separate from creation)
bin/aichat-crawler seed \
  --project-id "uuid-from-init-output" \
  --project-name myproject \
  --sitemap-url "https://example.com/sitemap.xml"

# Add URLs to an existing project
bin/aichat-crawler add-urls \
  --project-name myproject \
  --urls "https://example.com/new-page1,https://example.com/new-page2"

# Set prompts from files
bin/aichat-crawler set \
  --project-name myproject prompt1 @prompts/prompt1.txt

1. Reset — Every incoming message resets the timer for that chat, starting the sequence from step 0.
2. Fire — Fetches fresh chat state and history. Skips if already Finished + LeadSent. Otherwise invokes the agent's tool-calling loop with a synthetic [TIMER PING] turn (Agent.GeneratePing). The agent decides what to do.
3. Last-interval safety net — At the last interval (24h) the scheduler dispatches the lead unconditionally for every unresolved chat, regardless of client_status. This is the catch-all so no lead is lost — hot clients should usually be dispatched earlier by the agent itself (the prompt nudges send_lead after 1–2 pings when contact is in hand), but if the agent never makes that call we still ship the lead at 24h with whatever was gathered.
4. Persist — Timer state is written to PostgreSQL with the next trigger time. On restart, Reload() recovers all active timers, calculating remaining delay and firing overdue ones immediately.
5. Lead retry — If a timer finds Finished=true, LeadSent=false, it retries the CRM send instead of running the agent.
6. Cancel — When a user sends a new message, the old timer is cancelled (goroutine killed + DB record updated).

Goroutine safety: Each chat/project pair gets one goroutine. A current == self identity check prevents a superseded goroutine from cleaning up a newer timer's state.

Project bundles (Telegram client, agent, CRM, KB) live in an in-memory map. New projects can be registered at runtime via two paths:

• Admin group — /project_init command creates the project, seeds KB, and registers the bundle instantly. No restart needed.
• Internal API — POST /api/register-project/{id} for CLI or external tools that seed the DB independently.

Step 1: Create a bot in BotFather, copy the token.

Step 2: Send one command in the admin project's lead group:

/project_init myproject sitemap https://example.com/sitemap.xml 123456:AAH...token

The system verifies the token, creates the project, seeds the KB, and replies with progress:

> Project "myproject" created (bot: @myproject_bot). Seeding started...
> Scraping completed: 42 pages
> Chunking completed: 156 chunks
> Embeddings completed: 156 vectors
> Upload completed: 42 pages, 156 chunks indexed
> Project "myproject" init finished!
> Test the bot: https://t.me/myproject_bot
> To create the CRM group, click:
> https://t.me/myproject_bot?startgroup=connect_myproject

Step 3: Click the deep link. Telegram opens the "create group" UI with the bot pre-added. The bot auto-detects the group and connects it as the lead group. No group ID needed — discovered automatically via the /start connect_{name} command.

Lead group commands (per project)

User chat commands

Three migrations in migrations/:

001_initial.sql

CREATE TABLE projects (
  id          UUID PRIMARY KEY,
  name        TEXT UNIQUE,
  tg_lead_group BIGINT,
  tg_api_key  TEXT UNIQUE,
  prompts     JSONB,
  language    TEXT DEFAULT 'ru'
);

CREATE TABLE chat_history (
  id          UUID PRIMARY KEY,
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  question    TEXT,
  reply       TEXT,
  dbinfo      JSONB,
  created_at  TIMESTAMPTZ
);

CREATE TABLE chat_states (
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  state       JSONB,
  PRIMARY KEY (chat_id, project_id)
);

002_bm25_index.sql

CREATE TABLE bm25_indexes (
  project_id  UUID PRIMARY KEY REFERENCES projects(id),
  vocab       JSONB,
  idf         JSONB,
  avg_dl      FLOAT,
  num_docs    INT,
  updated_at  TIMESTAMPTZ
);

003_timers.sql

CREATE TABLE timers (
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  step        INT,
  trigger_at  TIMESTAMPTZ,
  PRIMARY KEY (chat_id, project_id)
);

Key indexes

• idx_chat_history_chat_id on (chat_id, created_at) — history lookup
• idx_chat_states_project on (project_id) — project-level queries
• idx_chat_states_state_gin GIN on (state) — JSONB queries on state

type CRM interface {
    SendLead(ctx context.Context, lead domain.Lead) (string, error)
    Name() string
}

Current implementation: TelegramCRM. The interface is designed for future CRM backends (Bitrix, AmoCRM) via the MultiCRM dispatcher pattern.

services.aichat = {
  enable = true;
  configFile = "/run/secrets/aichat-config.json";
  listenAddr = ":8080";

  # Database
  enablePostgres = true;
  dbName = "aichat";
  postgresPort = 5432;

  # Qdrant
  enableQdrant = true;
  qdrantPort = 6333;
  qdrantDataDir = "/var/lib/qdrant";

  # Backup
  enableBackup = true;
  backupDir = "/var/backup/aichat";
  backupRetentionDays = 14;
};

Backup

• Daily systemd timer with RandomizedDelaySec=1h
• pg_dump + Qdrant snapshots
• 14-day retention with automatic cleanup

Secrets (sops-nix)

• Encrypted in secrets/production.yaml using age keys
• Decrypted at boot on the target machine using its SSH host key
• Keys: aichat_config (full JSON config), cloudflared_creds (tunnel credentials)

# Deploy code changes to production
make prod-deploy

# SSH tunnels for crawler access to prod DB + Qdrant
make prod-tunnel
# PostgreSQL on localhost:15432, Qdrant on localhost:16333

# Seed a project on prod (while tunnel is open)
./bin/aichat-crawler --config /tmp/config.prod-tunnel.json init-project \
  --name myproject --tg-api-key "TOKEN" --language ru \
  --no-llm-chunk --workers 1 --urls "URL1,URL2,..."

# Fetch trace files from prod
ssh root@server "cat /var/lib/aichat/traces/{chatID}/{dialogID}.log"

After the bot is running and accessible via HTTPS, register the webhook with Telegram:

curl -X POST "https://api.telegram.org/bot{TG_API_KEY}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook/{TG_API_KEY}"}'

The webhook URL must exactly match https://{host}/webhook/{tg_api_key} where tg_api_key is the bot token from the projects table. The API key in the URL routes incoming updates to the correct project bundle.

Prerequisites: Go 1.22+, PostgreSQL 16, Qdrant

# Build all binaries
make build
# produces bin/aichat-bot, bin/aichat-crawler, bin/aichat-cli

# Run migrations
make migrate DATABASE_URL="postgres://user:pass@localhost/aichat"

# Run the bot with JSON config
bin/aichat-bot --config config.prod.json

# Or with environment variables
DATABASE_URL="postgres://user:pass@localhost/aichat" \
OPENAI_API_KEYS="sk-xxx" \
bin/aichat-bot

Production uses Cloudflare Tunnel to route HTTPS traffic to the bot without exposing ports. The tunnel routes aichat.example.com to localhost:8080 on the server.

• Tunnel credentials managed via sops-nix (encrypted at rest)
• Configured in nix/production.nix
• No need for TLS certificates or reverse proxy configuration
• Telegram webhooks point to the tunnel URL

• Group LLM metrics by provider to compare provider performance and error rates
• Track aichat_agent_messages_total by stage to see funnel conversion rates (general → service_specific → final)
• Watch aichat_timer_active_sequences as a proxy for total active conversations
• Use aichat_webhook_request_duration_seconds p95 to spot slow responses (typical: 2-5s including LLM + search)
• Monitor aichat_crm_leads_total by project to track lead generation per tenant

Model identifiers use "provider/model" format. The provider name is split on the first / character and matched against the providers map.

Extract model constraint: Must return content in choices[].message.content field. Thinking/reasoning models that use a reasoning field will not work for the extract slot.

# Build all three binaries
make build        # produces bin/aichat-bot, bin/aichat-crawler, bin/aichat-cli

# Run tests
make test         # go test ./...

# Lint
make lint         # go vet ./...

# Local development services (PostgreSQL + Qdrant via Docker)
make dev-services

# Run the CLI interface for testing (no Telegram needed)
bin/aichat-cli --config config.dev.json --project myproject