Skip to content

setup_guide.md

Latest commit

 

History

History
125 lines (86 loc) · 7.95 KB

setup_guide.md

File metadata and controls

125 lines (86 loc) · 7.95 KB
Raw

Setup guide

Documentation index · Configuration reference · Operations

This guide runs ThinkMate from a local checkout. For containers, use the Docker instructions.

Prerequisites

Component Requirement
Python 3.14; .python-version pins 3.14.8 for development and Docker.
uv and Git Install uv and Git.
Telegram A bot account and token issued by BotFather.
MongoDB A reachable database, local or hosted; this repository does not start one for you.
LLM A reachable OpenAI-compatible endpoint, its credential if required, and a supported model ID.

Run commands from the repository root. Use one polling process per Telegram bot token.

1. Get the code and dependencies

git clone https://github.com/TechShreyash/ThinkMate.git
cd ThinkMate
uv python install
uv sync --locked

uv uses the project's Python pin and lockfile. Docker installs runtime packages from the same uv.lock; requirements.txt is a generated locked export that also includes the test packages. You do not need to activate a virtual environment when using uv run. See uv's project guide for the environment/lockfile workflow.

For development and tests, include the optional extra:

uv sync --locked --extra dev

If the pinned Python download fails, check uv's version and whether that Python release is available for your platform. Do not silently replace the project's pin while diagnosing setup.

2. Register a Telegram bot

Open BotFather, send /newbot, choose a display name and a username ending in bot, and save the token. Keep it out of commits, screenshots, and shared logs.

Create the local configuration:

cp .env.example .env

On PowerShell:

Copy-Item .env.example .env

Set TELEGRAM_BOT_TOKEN in .env. The application loads .env from the repository root; environment variables already set in the process take precedence. See app/config.py.

3. Configure MongoDB and the LLM

Edit these settings, replacing the placeholders:

TELEGRAM_BOT_TOKEN=replace-with-botfather-token
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=thinkmate_db
LLM_BASE_URL=http://localhost:1234/v1
LLM_API_KEY=replace-with-your-provider-key-or-local-placeholder
LLM_CHAT_MODEL=replace-with-a-chat-model-your-server-serves
LLM_EXTRACTION_MODEL=
LLM_CHAT_FALLBACK_MODEL=
LLM_EXTRACTION_FALLBACK_MODEL=
LLM_CHAT_REASONING_EFFORT=
LLM_EXTRACTION_REASONING_EFFORT=
LLM_CHAT_FALLBACK_REASONING_EFFORT=
LLM_EXTRACTION_FALLBACK_REASONING_EFFORT=
LLM_STRUCTURED_MODE=json_object
ADMIN_USER_IDS=replace-with-your-numeric-telegram-user-id
  • MongoDB must be running and accessible from the bot process. For a hosted database, configure authentication, network access, and TLS as required by that service.
  • Use exact model IDs exposed by your endpoint. LLM_CHAT_MODEL serves replies and check-ins; LLM_EXTRACTION_MODEL serves extraction, compression, and consolidation. Blank extraction model uses the resolved chat model; blank chat model uses the legacy LLM_MODEL (default gpt-4o). The template's gpt-4o-mini extraction model is an example override. Models used for structured calls must support those requests.
  • Set LLM_CHAT_FALLBACK_MODEL and LLM_EXTRACTION_FALLBACK_MODEL if you want each path to try another model after primary failure. Blank disables fallback; a fallback identical to its primary is skipped. All models share the configured endpoint and credential.
  • Set reasoning separately with LLM_CHAT_REASONING_EFFORT, LLM_EXTRACTION_REASONING_EFFORT, LLM_CHAT_FALLBACK_REASONING_EFFORT, and LLM_EXTRACTION_FALLBACK_REASONING_EFFORT. Accepted values are none, minimal, low, medium, high, xhigh, and max, with whitespace/case normalized. Blank omits the request field and uses the provider default; explicit none sends that value. Check support for each model/provider; reasoning does not inherit between these four settings.
  • LLM_BASE_URL is the API base, usually including /v1, not the complete /chat/completions URL. Local LM Studio commonly uses http://localhost:1234/v1; Ollama's documented compatible base is http://localhost:11434/v1. Check the endpoint's actual configuration.
  • json_object is the default structured mode. An endpoint exposing a compatible URL is not proof that its model supports every request field; inspect LLM integration when choosing or troubleshooting a provider.
  • ADMIN_USER_IDS is a comma-separated list of numeric Telegram user IDs. Blank means any private-chat user can access health/metrics. Invalid entries are ignored, so verify the value carefully.

Ollama's compatibility reference describes its supported endpoint and JSON mode. A local LLM avoids sending prompts to a hosted inference provider, but Telegram remains part of the communication path.

4. Decide engagement and logging settings

The copied template enables consolidation and proactive check-ins. For a first test, you can disable proactive outreach:

PROACTIVE_INTERVAL_SECS=0

Users can also use /checkins off. Proactive quiet hours are UTC, with defaults of 16:00–02:00 UTC, corresponding to 21:30–07:30 in India.

If you configure LOGS_CHANNEL_ID, grant the bot permission to send messages and documents there. Operational forwarding can include extracted memory updates and reset backups; choose recipients accordingly. Leave FORWARD_DIAGNOSTICS=False unless you need routing traces. See observability.

All environment configuration is read at import/startup. Restart after changing .env or command settings. Editing the persona file is the exception; see persona customization.

5. Start and verify

uv run --locked main.py

Startup pings MongoDB, initializes audit indexes, restores persisted metrics, prepares schedulers and command menus, and begins Telegram long polling. A MongoDB failure stops startup. A persona path problem logs a warning and uses fallback behavior rather than failing startup.

Verify progressively:

  1. Open your bot's private chat and send /start. This checks Telegram delivery and profile initialization; the welcome message is static.
  2. Send a short ordinary text message. Wait for batching and model generation, and confirm a conversational reply.
  3. Send a memorable detail, then continue chatting. Extraction runs only after its buffer threshold and enough older entries are available; memory need not appear after the first message.
  4. Use /profile in the private chat to inspect memory. Use /health from your configured operator account to check MongoDB readiness; it does not probe the LLM endpoint.

Use Ctrl+C to stop. See operations for the shutdown limits.

6. Optional group setup

Add the bot to a test group and begin with an explicit @username mention or reply to its message. For ordinary group chatter and ambient participation, the bot must actually receive those messages. Telegram privacy mode limits visibility; use BotFather's /setprivacy if full group visibility is intended. Telegram documents that a privacy-mode change requires re-adding the bot, and group admin bots receive all messages. See Telegram privacy mode.

Read group behavior before enabling shared use: prompts include the current speaker's personal profile, and personal commands are not all restricted to private chats.

If something fails, use the troubleshooting table. The full configuration reference covers tuning after the initial conversation works.