A self-hosted Telegram assistant for grounded answers over private documents, with a real-estate layer for apartment search, service cards, viewing requests, and manager handoff. Python 3.12+, an in-process core/runtime, and Docker Compose sidecars.
PROJECT.md defines accepted scope; AGENTS.md defines work rules.
Linux/POSIX commands; see Local Development for PowerShell/WSL.
uv sync --frozen --extra telegram
cp .env.example .env
# Fill in credentials and configure the verified BGE model artifact.
make docker-core-up
make run-botThe default sidecar stack needs a verified BGE-M3 artifact before its image can be built.
Follow the BGE artifact instructions and
Compose guide. All modes — minimal, bot, full — render from
compose.yml + compose.dev.yml; to start only the stateful pair, run
docker compose -f compose.yml -f compose.dev.yml up -d qdrant redis, while
embeddings and data readiness still need to be supplied for the full bot.
make docker-bot-up runs the bot in Compose. PostgreSQL is an opt-in product capability.
Local configuration is the root .env, based on .env.example. pyproject.toml and uv.lock own application/Telegram dependencies.
Telegram messages reach run_assistant_request, which delegates to the procedural assistant pipeline. Retrieval/generation or a deterministic product action returns an AssistantResult. See Structure for owners and dependency boundaries.
Qdrant stores search data; BGE-M3 supplies embeddings/reranking; Redis supplies caches and coordination. PostgreSQL-backed features and manager/CRM integrations depend on their configuration and capability checks. A module's presence does not prove it is enabled.
Unified ingestion is Markdown-only, with stable file identity and idempotent writes. Removing a source file does not automatically delete its Qdrant chunks; follow the ingestion cleanup procedure.
Start with focused tests. make dev-setup installs commit and push hooks.
make test-core # Core/runtime behavior and import boundaries
make test # Core + no-service integration/smoke lane
make test-contract # Repository contracts
make candidate-check # Authoritative local delivery gateThe delivery gate includes frozen-environment checks, lint/types, formatting, deterministic
tests, and contracts. Tests explains setup and lane coverage.
make test-full is the manual full-suite gate. Live scenarios require their services and
credentials; static/unit checks do not establish live readiness.
GitHub runs the approved Candidate Gate and static/security checks. Hosted coverage is narrower than the full local delivery gate. See branch protection and the actual CI workflow.
| Task | Read |
|---|---|
| Understand product scope | PROJECT.md |
| Work on the repository | AGENTS.md |
| Find code owners and flows | Structure |
| Install, run, diagnose the environment | Local Development |
| Change deployment/profiles/ports | DOCKER.md |
| Change document ingestion | INGESTION.md |
| Choose checks | Tests |
| Perform an operational procedure | Runbooks |
| Find other maintained documents | Documentation hub |
The RAG VPS v2 proposal describes a future design. GitHub Issues own work state; ADRs own accepted rationale.
This project is licensed under the MIT License.