Copykar Project Memory & Agent Guidelines

1. Project Overview & Architecture

Copykar is an automated content ingestion, AI rewriting, admin curation, and paced publishing fleet for Telegram channels and websites.

Key Components:

Collector Service (services/collector.py): Telethon Userbot client monitoring source Telegram channels, downloading media to MEDIA_DIR, extracting subjects/tags, performing semantic deduplication, and sending raw review cards to the admin review channel.
Website Collector Service (services/website_collector.py & services/website_analyzer.py): Automated HTTP crawler for web sources. Uses AI to analyze site DOM/API structures with user-specified custom extraction needs (custom_instructions), discovering data endpoints and extracting new articles.
AI Processing Pipeline (core/llm.py & services/ai_processor.py):
- Multi-provider resilient chain (OpenAI, Gemini, AGY CLI / local bridge on host.docker.internal:8088).
- Automatic fallback upon rate limits, errors, or timeouts.
- Multimodal Vision: Handles image analysis along with text.
- Target Channel Context Ingestion: Injects the last N published messages from the target channel into the AI prompt to preserve tone, style, and narrative continuity.
- Semantic Deduplication: Evaluates topic tags and content similarity with previous posts.
Admin Bot Panel (services/admin_bot.py): Telethon Bot account providing interactive management and instant review cards with 5 primary category hubs.
Publisher Service (services/publisher.py): Paced target delivery worker consuming queues with configurable intervals, sleep schedules, and FIFO/Random dispatch order.
Database & Persistence (db/database.py, db/models.py, db/repository.py): PostgreSQL with asyncpg, automatic migrations, and JSONB post tracking. Redis for queue management.
Observability (core/metrics.py): Prometheus metrics server on port 8008 + Grafana dashboards.

2. Interaction & Workflow Rules

English Correction Rule: Every user prompt must be corrected at the very top of each reply in the exact ASCII box format (┌ ─ ┐ │ └ ┘).
No AI Attribution: Never mention AI, LLM, Gemini, Claude, Antigravity, or model names in commit messages, comments, PRs, or user-facing code.
Minimal Changes: Smallest possible diff to achieve the goal. Do not refactor untouched code.
Git Workflow:
- One logical change per commit.
- Stage files strictly by name (never git add .).
- Never commit .env, credentials, secrets, or temporary dumps.
- Never create or switch branches unless explicitly requested.

3. Project Invariants & Domain Standards

The bot interface is strictly organized into 5 category hubs:

Copy (مدیریت محتوا): Unreviewed posts queue (/pending), unified add source/target hub (/add), and channel topic categories (/categories).
AI (تنظیمات هوش مصنوعی): Provider profiles, model selection, vision toggle, reasoning effort, fallback chain configuration, connectivity tests, and processing logs.
Bots (کانال‌ها و ربات‌ها): Source Telegram channels (/sources), Target Telegram channels (/targets), Source websites (/websites), and collector userbot authentication (/request_code).
System (مدیریت سیستم): Emergency fleet pause/resume (/pause, /resume), dynamic release notes (/changes), and comprehensive documentation (/help).
Monitor (مانیتورینگ و آمار): Live queue & channel throughput statistics (/stats), unresolved error log review & bulk-fix (/errors), and Grafana time-range graphs.

3.2 Release Notes Delivery & Environment Configuration

Always use app .env file: Always read bot credentials (BOT_TOKEN), admin IDs (ADMIN_USER_IDS), and configurations directly from /projects/telegram-bots/copykar/.env.
Never save release notes to a static file: Do not create or keep RELEASE_NOTES.md on disk.
Dynamic Generation: Always generate release notes dynamically strictly describing the changes of the current commit.
Direct Admin DMs Only: Always dispatch release notes via the Telegram bot directly to admin private DMs (ADMIN_USER_IDS) using the .env configuration (and proxy http://127.0.0.1:10809 if needed), never to any public or review channel.

3.3 Target Channel Context History

Target channels support injecting recent published history (context_message_count) into AI rewriting prompts.
History is queried via PostgreSQL JSONB array query against published_to matching {"target_id": target.id}, sorted chronologically (oldest to newest).

3.4 Multimodal Vision & AGY Bridge

When images are present, payload is structured with {"type": "text", "text": ...} and {"type": "image_url", ...}.
The host-side AGY bridge (agy_bridge.py on port 8088) decodes image base64 into temporary files and executes the CLI with multimodal parameters.

3.5 Button Permissions & Channel Callbacks

Inline callbacks on review cards (sel_trg:, rej:, del_msg:) check is_admin(event.sender_id) against ADMIN_USER_IDS.
The bot must have Administrator privileges in the review channel with permissions to edit and delete messages.

3.6 Self-Contained Project Memory

Always record, update, and maintain all rules, architecture notes, domain standards, and operational memories about this project inside its own folder (AGENTS.md and GEMINI.md).
This ensures any developer or collaborator receiving this repository has immediate, self-contained access to the project's memory and guidelines.

3.7 Persistent Data Storage Layout (`./data/`)

All service persistent data volumes are centralized within the project's ./data/ directory (git-ignored):

data/postgres/: PostgreSQL database files. Uses monitoring/postgres/libfakestat_musl.so for Docker Desktop virtiofs permission compatibility.
data/redis/: Redis RDB persistence and cache data.
data/app/: Downloaded Telegram media and cached files.
data/sessions/: Telethon SQLite session files for userbot and bot accounts.
data/prometheus/: Prometheus metric time-series database.
data/grafana/: Grafana dashboards and SQLite database.
data/pgadmin/: pgAdmin configuration and query history.

6.3 KiB Raw Blame History