🤖 Digital Mate

Stop guessing. Start marketing like you have a full team.

An AI marketing assistant in Telegram that plans, creates, and analyzes — from captions to campaign strategies to performance reports. Automated tests. Defense-in-depth security. Local dashboard included.

Chat with it like a marketing colleague. It does the rest.

Tech Stack: Python 3.11+ · python-telegram-bot · OpenAI-compatible LLM · SQLite · Notion API

Why Digital Mate? · Who is this for? · Features · Demo · Quick Start · Architecture · Contributing · Roadmap

🎯 What is Digital Mate?

Digital Mate is a production-grade AI marketing assistant built for Telegram. It understands natural language marketing requests, routes them to specialized AI pipelines, and delivers actionable outputs — captions, strategies, research reports, and analytics.

No dashboard. No learning curve. Just chat.

🔥 Why Digital Mate?

Feature	ChatGPT	Generic AI Bots	Digital Mate
Marketing-specific prompts	❌ Generic	⚠️ Basic	✅ 4 specialized pillars
Multi-step workflows	❌ Single turn	❌	✅ Automatic tool chaining
Self-reflection & auto-optimization	❌	❌	✅ Quality scoring + refinement
Proactive reminders	❌	❌	✅ Weekly digests + nudges
Security hardening	⚠️ Basic	❌	✅ 510 tests, 3 guard layers
Brand voice memory	❌	⚠️ Limited	✅ Per-chat brand profiles
Open source	❌	❌	✅ MIT License
Telegram native	❌	⚠️ Some	✅ Built for Telegram

Most AI tools give you a blank chat box. Digital Mate gives you a marketing team — with memory, workflows, quality control, and security built in.

👋 Who is this for?

🧑‍💻 Solo founders — "I need marketing content but can't afford an agency."
🏪 Small business owners — "I know I should post on social media but don't know what."
🧑‍🎨 Marketing freelancers — "I need to scale my output without sacrificing quality."
🚀 Startup teams — "We need a marketing strategy but our budget is $0."

If you think in marketing terms but don't have a team to execute — Digital Mate is your team.

You: Write me 3 Instagram captions for a new coffee shop in Jakarta
Mate: 🚀 3 Caption Variations — Coffee Shop Launch
      ☕ Variation 1: Warm & Inviting — "first sip hits different..."
      🔥 Variation 2: Playful & Bold — "POV: You just found your new spot..."
      🤍 Variation 3: Minimal & Aesthetic — "Good coffee. Warm light..."

✨ Features

🖊️ Content & Copywriting

Multi-platform captions — Instagram, TikTok, Twitter/X, LinkedIn, Facebook
Hook generator — 8+ psychological hook frameworks (curiosity gap, pain point, bold claim...)
Content calendar — Weekly content plans with channel-specific scheduling
Newsletter & email — Subject lines, body copy, CTA optimization
Hashtag strategy — Mix of reach, niche, and branded hashtags

📋 Strategy & Planning

Campaign blueprints — Full funnel breakdown (awareness → conversion)
Launch playbooks — Phase-by-phase launch strategies with timelines
Marketing audits — Structured checklist-based analysis
Budget allocation — Channel mix recommendations by goal

🔎 Research & Insight

Competitor analysis — Real-time web research with structured reports
Audience personas — Data-driven persona builder with demographics + psychographics
Keyword research — Volume, difficulty, intent mapping
Trend monitoring — Industry trend identification via live web search

📊 Analytics & Reporting

Performance reports — Input raw metrics, get executive summaries
KPI frameworks — Platform-specific benchmark comparisons
What→Why→Do — Structured interpretation methodology
Action prioritization — Impact vs. effort matrix for next steps

🔄 Tool Chaining — Multi-Step Workflows

Research → Content — Search trends, then generate captions referencing real data
Research → Strategy — Competitor analysis feeds into a marketing plan
Analytics → Strategy — Interpret metrics, then recommend improvements
Strategy → Content — Marketing plan drives a content calendar
Progress streamed to user: "🔍 Searching trends... → ✍️ Writing caption..."

🎯 Goal Decomposition — Complex Plans

Automatic planning — Break "launch a product" into 2–7 concrete steps
Step-by-step execution — Each step runs the right pillar with the right data
Plan persistence — Plans survive bot restarts, resume automatically on startup
/plan command — View progress, cancel anytime with /cancelplan

✨ Self-Reflection — Auto-Optimized Output

Critic + Refiner loop — Evaluates output on hook strength, brand voice, CTA clarity
Automatic iteration — Scores < 7 trigger regeneration (up to 2 rounds)
✨ Auto-optimized indicator shown when reflection improved the output
Pillar-aware — Always runs for Content/Strategy, optional for Research, skips Analytics/General

🔔 Proactive Intelligence

Trend digests — Weekly search for trending topics in the user's industry
Content reminders — Nudge when the user hasn't posted recently
Campaign alerts — Flag when a campaign has been running long enough to review
/digest command — Trigger an on-demand trend digest

📸 Vision

Image analysis — Send screenshots, ads, or analytics dashboards
Context-aware — Vision results feed into the appropriate pillar for interpretation
Multi-format — Supports photos, documents, and image replies

🧠 Long-Term Memory

Key facts extraction — Auto-extracts 0–3 facts every 10 messages
Cross-session recall — Facts injected into future prompts for continuity
/forget command — Clear stored key facts on demand

📸 Demo

Welcome & Onboarding

AI-Powered Content Creation

Security Guard — Prompt Injection Protection

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Telegram Bot                           │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐    │
│  │  /start       │   │  /brand      │   │  /calendar   │    │
│  │  /plan        │   │  /digest     │   │  /forget     │    │
│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘    │
│         └──────────────────┼──────────────────┘             │
│                            ▼                                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              🛡️ Security Guard Layer                │    │
│  │  Input Guard:  injection | role hijack | exfil      │    │
│  │  Output Guard: leakage | hallucination markers      │    │
│  │  Brand Guard:  field sanitization | injection strip │    │
│  └─────────────────────────┬───────────────────────────┘    │
│                            ▼                                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         🧠 Intent Router + Routing Classifier       │    │
│  │  LLM classify → pillar + action                      │    │
│  │  Route decision → workflow | plan | single           │    │
│  └─────────────────────────┬───────────────────────────┘    │
│                            ▼                                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              🤖 Agent Orchestrator                  │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │    │
│  │  │ Workflow  │  │ Planner  │  │ Reflection       │  │    │
│  │  │ Engine    │  │ + Executor│  │ (Critic+Refiner) │  │    │
│  │  └──────────┘  └──────────┘  └──────────────────┘  │    │
│  └─────────────────────────┬───────────────────────────┘    │
│                            ▼                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ Content  │  │ Strategy │  │ Research │  │Analytics │    │
│  │  Pillar  │  │  Pillar  │  │  Pillar  │  │  Pillar  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│         │              │             │            │          │
│         └──────────────┼─────────────┼────────────┘          │
│                        ▼                                     │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              📦 Infrastructure Layer                 │    │
│  │  SQLite (sessions, brand, plans, key_facts, triggers)│    │
│  │  Notion │ Tavily/DuckDuckGo │ Vision │ Scheduler    │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Design Decisions

Decision	Choice	Why
LLM backend	OpenAI-compatible API	Pluggable — works with OpenAI, Anthropic, local models, any compatible endpoint
Intent routing	LLM classification + keyword fallback	Accurate semantic routing without fine-tuning
Route dispatch	Orchestrator decides: workflow, plan, or single	Same classifier output, three execution paths
Memory	SQLite + session context + key facts	Zero-dependency, no external DB needed
Prompts	`.md` template files	Easy to edit, version control, iterate without code changes
Security	Input/Output/Brand guards	Defense-in-depth against prompt injection, data leakage, role hijacking
Integrations	Notion + Web Search + Vision	Real data, not hallucinated marketing advice
Reflection	Critic + Refiner loop (max 2 rounds)	Quality gate without infinite loops
Planning	LLM planner + executor + SQLite plan store	Survives restarts, supports `/plan` and `/cancelplan`

🚀 Quick Start

One-Line Install

curl -sSL https://raw.githubusercontent.com/Yanu403/digital-mate/master/install.sh | bash

This installs Digital Mate to ~/.digital-mate/, sets up Python venv, and creates the .env config file.

Then start the dashboard:

DASHBOARD_API_KEY="$(openssl rand -hex 24)" ~/.digital-mate/bin/digital-mate serve

Or set DASHBOARD_API_KEY in .env, then run:

~/.digital-mate/bin/digital-mate serve

Open http://localhost:7749/?api_key=<your-dashboard-key> — configure your Telegram token, LLM key, and brand profile from the web UI. No terminal editing needed.

Or auto-launch after install:

curl -sSL https://raw.githubusercontent.com/Yanu403/digital-mate/master/install.sh | bash -s -- --launch

Manual Install

git clone https://github.com/Yanu403/digital-mate.git
cd digital-mate
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Configuration

Edit .env with your credentials:

# Required
TELEGRAM_BOT_TOKEN=your_bot_token
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=your_api_key
LLM_MODEL=gpt-4o

# Optional
NOTION_API_KEY=your_notion_key
SEARCH_PROVIDER=duckduckgo

Works with any OpenAI-compatible endpoint: OpenAI, Anthropic (via proxy), Groq, Together AI, local Ollama, LM Studio, vLLM, etc.

Run

# Development
python -m digital_mate

# Headless bot
digital-mate run

# Local dashboard and bot manager
digital-mate serve

🤖 Bot Commands

Command	Description
`/start`	Welcome message & quick tour
`/help`	Full command list with examples
`/brand`	Set up your brand profile (name, tone, audience, competitors)
`/calendar`	Generate a weekly content calendar
`/research`	Deep research on a topic, competitor, or trend
`/report`	Create a performance report from your metrics
`/plan`	View active plan progress or start a new goal plan
`/cancelplan`	Cancel the currently running plan
`/digest`	Trigger an on-demand trend digest
`/forget`	Clear stored key facts (long-term memory)
`/history`	View your recent conversations
`/clear`	Reset conversation context

Natural Language

Just talk to it naturally — no commands needed:

"Analyze my competitor @brandx on Instagram"
"Write a launch email for my SaaS product"
"What are the trending hashtags for fintech in Indonesia?"
"I got 15K impressions, 2.3% engagement, 45 clicks — analyze this"

🔒 Security

Digital Mate ships with a defense-in-depth security layer protecting against common LLM application attacks:

Input Guard

Blocks malicious prompts before they reach the LLM:

Attack Vector	Detection	Status
Prompt extraction	"ignore instructions", "reveal system prompt"	🛡️ Blocked
Role hijacking	"you are now DAN", "pretend you're..."	🛡️ Blocked
Data exfiltration	"send data to URL", "exfiltrate API keys"	🛡️ Blocked
Obfuscation	Base64-encoded injection, Unicode tricks	🛡️ Blocked
Harmful content	Phishing, malware, social engineering	🛡️ Blocked

Output Guard

Scans LLM responses for:

System prompt leakage
Internal configuration exposure
API key / credential fragments

Brand Profile Sanitizer

All user-provided brand fields are sanitized against:

Code block injection
XML/ChatML tag injection
Markdown separator abuse

Automated tests cover security scenarios and run in CI on supported Python versions. See tests/test_security.py.

🧪 Testing

# Install test and build tooling
pip install -r requirements-dev.txt

# Run all tests
pytest

# With the same coverage gate used by CI
pytest --cov=digital_mate --cov-report=term-missing --cov-fail-under=70

# Run specific test suite
pytest tests/test_security.py -v        # Security tests
pytest tests/test_content.py -v         # Content pillar tests
pytest tests/test_router.py -v          # Intent routing tests
pytest tests/test_orchestrator.py -v    # Orchestrator + workflow tests
pytest tests/test_planner.py -v         # Goal decomposition tests
pytest tests/test_critic.py -v          # Self-reflection critic tests
pytest tests/test_refiner.py -v         # Self-reflection refiner tests
pytest tests/test_reflection.py -v      # Reflection engine tests
pytest tests/test_triggers.py -v        # Proactive trigger tests
pytest tests/test_scheduler.py -v       # Scheduler tests
pytest tests/test_key_facts.py -v       # Long-term memory tests
pytest tests/test_feedback.py -v        # Feedback button tests

Pull requests and pushes to master run tests with coverage on Python 3.11 and 3.12, then verify the wheel and source distribution can be built.

Operations Endpoints

Endpoint	Authentication	Purpose
`GET /api/health`	Public	Liveness, application version, and timestamp
`GET /api/ready`	Public	Required configuration and SQLite availability
`GET /api/metrics`	`X-API-Key`	Aggregate LLM requests, failures, latency, in-flight calls, and provider token usage

Metrics are aggregate and process-local. They never contain prompts, responses, credentials, or user/chat identifiers. The bot writes its latest snapshot to METRICS_PATH (default data/runtime-metrics.json) so the separate dashboard process can expose it. Token counters are populated when the LLM provider returns OpenAI-compatible usage metadata. For release steps and rollback guidance, see docs/RELEASING.md.

📁 Project Structure

digital-mate/
├── digital_mate/
│   ├── AGENT.md              # Bot personality & marketing expertise
│   ├── bot.py                # Telegram handlers + security integration
│   ├── config.py             # Environment configuration
│   ├── router.py             # LLM-powered intent classification
│   ├── llm/
│   │   ├── client.py         # OpenAI-compatible async client
│   │   └── prompts.py        # Template engine (.md file loader)
│   ├── agent/
│   │   ├── orchestrator.py   # Central dispatch: workflow | plan | single
│   │   ├── workflow.py       # Workflow engine + 4 built-in workflows
│   │   ├── planner.py        # LLM goal decomposition (2–7 steps)
│   │   ├── executor.py       # Plan step execution + error recovery
│   │   ├── plan_store.py     # SQLite plan persistence (resume on restart)
│   │   ├── critic.py         # Output quality evaluator
│   │   ├── refiner.py        # Iterative output improvement
│   │   ├── reflection.py     # Reflection engine (critic + refiner loop)
│   │   ├── triggers.py       # Proactive trigger definitions + detection
│   │   └── scheduler.py      # Cron-like scheduled task runner
│   ├── pillars/
│   │   ├── base.py           # Base pillar with shared context
│   │   ├── content.py        # Content & copywriting pipeline
│   │   ├── strategy.py       # Strategy & planning pipeline
│   │   ├── research.py       # Research & insight pipeline
│   │   └── analytics.py      # Analytics & reporting pipeline
│   ├── prompts/              # Prompt templates (editable .md files)
│   │   ├── router.md         # Intent classification rules
│   │   ├── content.md        # Content generation expertise
│   │   ├── strategy.md       # Strategic planning frameworks
│   │   ├── research.md       # Research methodology
│   │   ├── analytics.md      # Analytics interpretation
│   │   ├── planner.md        # Goal decomposition prompt
│   │   └── general.md        # Chitchat / help responses
│   ├── integrations/
│   │   ├── notion_client.py  # Notion API integration
│   │   └── search.py         # Tavily / DuckDuckGo search
│   ├── memory/
│   │   ├── database.py       # SQLite async storage (schema v7)
│   │   ├── session.py        # Conversation context (last N turns)
│   │   ├── brand_profile.py  # Per-chat brand profiles
│   │   ├── key_facts.py      # Long-term memory (auto-extract every 10 msgs)
│   │   ├── response_store.py # Feedback storage (👍/👎/🔄)
│   │   └── autocalendar.py   # Auto content calendar generator
│   └── utils/
│       ├── formatting.py     # Markdown formatting for Telegram
│       ├── validators.py     # Input validation
│       ├── security.py       # Security guard layer
│       ├── keyboards.py      # Inline feedback keyboards (👍/👎/🔄)
│       └── image.py          # Vision / image processing
├── tests/                    # 510 automated tests
├── deploy/                   # Systemd service files
├── docs/
│   ├── ARCHITECTURE.md       # Architecture deep-dive
│   ├── notion-setup.md       # Notion database setup guide
│   └── screenshots/          # Demo screenshots
├── .env.example              # Configuration template
├── requirements.txt          # Python dependencies
└── LICENSE                   # MIT

⚙️ Configuration

Required

Variable	Description
`TELEGRAM_BOT_TOKEN`	Bot token from @BotFather
`LLM_BASE_URL`	OpenAI-compatible API endpoint
`LLM_API_KEY`	API key for your LLM provider
`LLM_MODEL`	Model name (e.g., `gpt-4o`, `mimo-v2.5-pro`)

Optional

Variable	Default	Description
`NOTION_API_KEY`	—	Notion integration token
`NOTION_CALENDAR_DB`	—	Content calendar database ID
`NOTION_CAMPAIGN_DB`	—	Campaign tracker database ID
`SEARCH_PROVIDER`	`duckduckgo`	Search backend (`tavily` or `duckduckgo`)
`TAVILY_API_KEY`	—	Required if using Tavily search
`MAX_HISTORY`	`10`	Conversation context window
`BOT_LANGUAGE`	`en`	Default language (`en`, `id`, `es`, `zh`, `ja`)
`LOG_LEVEL`	`INFO`	Logging verbosity

🗺️ Roadmap

✅ Phase 1 — Core

4 marketing pillars (content, strategy, research, analytics)
LLM-powered intent routing
Bilingual support (English + Indonesian)
Per-chat brand profiles
Security guard layer
Notion integration
Web search integration
105 automated tests (expanded to 510 in Phase 2)

✅ Phase 2 — Agentic Intelligence

🔜 Phase 3 — Expansion

WhatsApp Business API integration
Auto-scheduled weekly content calendars
Image generation for social posts
Analytics dashboard (web UI)
Custom training on brand voice history

🚀 Phase 4 — Platform

Team collaboration (shared brand profiles)
A/B testing suggestions with prediction
CRM integration (HubSpot, Salesforce)
Social media scheduling (direct posting)

🛠️ Development

# Install dev dependencies
pip install -r requirements.txt pytest pytest-asyncio pytest-cov

# Run with debug logging
LOG_LEVEL=DEBUG python -m digital_mate

# Format code
black digital_mate/ tests/
ruff check digital_mate/ tests/

Adding a New Pillar

Create digital_mate/pillars/yourpillar.py extending BasePillar
Write prompt template at digital_mate/prompts/yourpillar.md
Register in router's pillar map
Add tests in tests/test_yourpillar.py

Adding a New Workflow

Define the workflow in digital_mate/agent/workflow.py
Add detection logic in digital_mate/agent/orchestrator.py
Add tests in tests/test_workflow.py

🤝 Contributing

Contributions welcome! Here's how:

Fork the repo
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Good first issues

🏷️ good-first-issue — Beginner-friendly tasks
🏷️ help-wanted — Features we need help with
🏷️ documentation — Docs improvements

Development setup

git clone https://github.com/Yanu403/digital-mate.git
cd digital-mate
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install pytest pytest-asyncio pytest-cov ruff black
pytest  # Should show 510 passing

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

python-telegram-bot — Telegram Bot API wrapper
OpenAI Python SDK — LLM client
Tavily — AI-optimized web search
Notion API — Workspace integration

Built with ❤️ by Reazer

⭐ Star this repo if Digital Mate saved you time — it helps others discover the project and keeps development going.

Share on Twitter

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github/workflows		.github/workflows
bin		bin
digital_mate		digital_mate
docs		docs
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

🤖 Digital Mate

Stop guessing. Start marketing like you have a full team.

🎯 What is Digital Mate?

🔥 Why Digital Mate?

👋 Who is this for?

✨ Features

🖊️ Content & Copywriting

📋 Strategy & Planning

🔎 Research & Insight

📊 Analytics & Reporting

🔄 Tool Chaining — Multi-Step Workflows

🎯 Goal Decomposition — Complex Plans

✨ Self-Reflection — Auto-Optimized Output

🔔 Proactive Intelligence

📸 Vision

🧠 Long-Term Memory

📸 Demo

Welcome & Onboarding

AI-Powered Content Creation

Security Guard — Prompt Injection Protection

🏗️ Architecture

Design Decisions

🚀 Quick Start

One-Line Install

Manual Install

Configuration

Run

🤖 Bot Commands

Natural Language

🔒 Security

Input Guard

Output Guard

Brand Profile Sanitizer

🧪 Testing

Operations Endpoints

📁 Project Structure

⚙️ Configuration

Required

Optional

🗺️ Roadmap

✅ Phase 1 — Core

✅ Phase 2 — Agentic Intelligence

🔜 Phase 3 — Expansion

🚀 Phase 4 — Platform

🛠️ Development

Adding a New Pillar

Adding a New Workflow

🤝 Contributing

Good first issues

Development setup

📄 License

🙏 Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages