postpilot 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. postpilot-0.1.0/.env.example +36 -0
  2. postpilot-0.1.0/.github/workflows/ci.yml +34 -0
  3. postpilot-0.1.0/.github/workflows/publish.yml +74 -0
  4. postpilot-0.1.0/.gitignore +45 -0
  5. postpilot-0.1.0/Dockerfile +22 -0
  6. postpilot-0.1.0/PKG-INFO +306 -0
  7. postpilot-0.1.0/README.md +280 -0
  8. postpilot-0.1.0/docker-compose.yml +15 -0
  9. postpilot-0.1.0/docs/ARCHITECTURE.md +236 -0
  10. postpilot-0.1.0/docs/DEVELOPMENT_FLOW.md +118 -0
  11. postpilot-0.1.0/docs/PRD.md +154 -0
  12. postpilot-0.1.0/docs/TESTING.md +74 -0
  13. postpilot-0.1.0/pyproject.toml +49 -0
  14. postpilot-0.1.0/render.yaml +31 -0
  15. postpilot-0.1.0/src/postpilot/__init__.py +6 -0
  16. postpilot-0.1.0/src/postpilot/ai/__init__.py +1 -0
  17. postpilot-0.1.0/src/postpilot/ai/base.py +23 -0
  18. postpilot-0.1.0/src/postpilot/ai/gemini.py +46 -0
  19. postpilot-0.1.0/src/postpilot/ai/groq.py +59 -0
  20. postpilot-0.1.0/src/postpilot/ai/ollama.py +42 -0
  21. postpilot-0.1.0/src/postpilot/ai/router.py +45 -0
  22. postpilot-0.1.0/src/postpilot/cli.py +93 -0
  23. postpilot-0.1.0/src/postpilot/commands/__init__.py +31 -0
  24. postpilot-0.1.0/src/postpilot/commands/autopilot_cmd.py +102 -0
  25. postpilot-0.1.0/src/postpilot/commands/config_cmd.py +65 -0
  26. postpilot-0.1.0/src/postpilot/commands/dna_cmd.py +126 -0
  27. postpilot-0.1.0/src/postpilot/commands/doctor_cmd.py +67 -0
  28. postpilot-0.1.0/src/postpilot/commands/drafts_cmd.py +71 -0
  29. postpilot-0.1.0/src/postpilot/commands/generate_cmd.py +45 -0
  30. postpilot-0.1.0/src/postpilot/commands/init_cmd.py +45 -0
  31. postpilot-0.1.0/src/postpilot/commands/publish_cmd.py +45 -0
  32. postpilot-0.1.0/src/postpilot/commands/queue_cmd.py +44 -0
  33. postpilot-0.1.0/src/postpilot/commands/schedule_cmd.py +47 -0
  34. postpilot-0.1.0/src/postpilot/commands/status_cmd.py +56 -0
  35. postpilot-0.1.0/src/postpilot/daemon.py +131 -0
  36. postpilot-0.1.0/src/postpilot/database/__init__.py +1 -0
  37. postpilot-0.1.0/src/postpilot/database/db.py +32 -0
  38. postpilot-0.1.0/src/postpilot/database/models.py +173 -0
  39. postpilot-0.1.0/src/postpilot/database/repositories.py +243 -0
  40. postpilot-0.1.0/src/postpilot/dna/__init__.py +3 -0
  41. postpilot-0.1.0/src/postpilot/dna/analyzer.py +79 -0
  42. postpilot-0.1.0/src/postpilot/dna/collector.py +106 -0
  43. postpilot-0.1.0/src/postpilot/dna/generator.py +64 -0
  44. postpilot-0.1.0/src/postpilot/main.py +15 -0
  45. postpilot-0.1.0/src/postpilot/publishers/__init__.py +1 -0
  46. postpilot-0.1.0/src/postpilot/publishers/base.py +28 -0
  47. postpilot-0.1.0/src/postpilot/publishers/manual.py +36 -0
  48. postpilot-0.1.0/src/postpilot/publishers/x_publisher.py +156 -0
  49. postpilot-0.1.0/src/postpilot/scheduler/__init__.py +1 -0
  50. postpilot-0.1.0/src/postpilot/scheduler/hourly_delivery.py +120 -0
  51. postpilot-0.1.0/src/postpilot/scheduler/worker.py +81 -0
  52. postpilot-0.1.0/src/postpilot/services/__init__.py +1 -0
  53. postpilot-0.1.0/src/postpilot/services/autopilot.py +119 -0
  54. postpilot-0.1.0/src/postpilot/services/content.py +48 -0
  55. postpilot-0.1.0/src/postpilot/services/dna.py +129 -0
  56. postpilot-0.1.0/src/postpilot/services/publishing.py +60 -0
  57. postpilot-0.1.0/src/postpilot/telegram/__init__.py +7 -0
  58. postpilot-0.1.0/src/postpilot/telegram/bot.py +94 -0
  59. postpilot-0.1.0/src/postpilot/telegram/handlers.py +541 -0
  60. postpilot-0.1.0/src/postpilot/telegram/keyboards.py +95 -0
  61. postpilot-0.1.0/src/postpilot/telegram/security.py +21 -0
  62. postpilot-0.1.0/src/postpilot/utils/__init__.py +1 -0
  63. postpilot-0.1.0/src/postpilot/utils/config.py +85 -0
  64. postpilot-0.1.0/tests/__init__.py +3 -0
  65. postpilot-0.1.0/tests/conftest.py +20 -0
  66. postpilot-0.1.0/tests/test_ai.py +36 -0
  67. postpilot-0.1.0/tests/test_autopilot.py +36 -0
  68. postpilot-0.1.0/tests/test_content.py +23 -0
  69. postpilot-0.1.0/tests/test_dna.py +81 -0
  70. postpilot-0.1.0/tests/test_publishing.py +30 -0
  71. postpilot-0.1.0/tests/test_queue.py +22 -0
  72. postpilot-0.1.0/tests/test_scheduler.py +22 -0
  73. postpilot-0.1.0/tests/test_telegram.py +29 -0
@@ -0,0 +1,36 @@
1
+ # -----------------------------------------------------------------------------
2
+ # PostPilot Configuration
3
+ # -----------------------------------------------------------------------------
4
+
5
+ # AI Providers (Free tiers / Local available)
6
+ GROQ_API_KEY=
7
+ GEMINI_API_KEY=
8
+ OLLAMA_BASE_URL=http://localhost:11434
9
+ OLLAMA_MODEL=llama3:8b
10
+ DEFAULT_AI_PROVIDER=groq
11
+
12
+ # Telegram Bot Interface
13
+ TELEGRAM_BOT_TOKEN=
14
+ TELEGRAM_OWNER_ID=
15
+
16
+ # X (Twitter) Official API v2 (Optional - For Paid API Mode)
17
+ X_API_KEY=
18
+ X_API_SECRET=
19
+ X_ACCESS_TOKEN=
20
+ X_ACCESS_TOKEN_SECRET=
21
+ X_CLIENT_ID=
22
+ X_CLIENT_SECRET=
23
+
24
+ # Publishing & Automation Defaults
25
+ # DEFAULT_PUBLISH_METHOD: 'manual' (100% Free, Zero Ban Risk) or 'x_api' (Paid Official API)
26
+ DEFAULT_PUBLISH_METHOD=manual
27
+ # DEFAULT_PUBLISH_MODE: 'approval' (User approves each post) or 'autopilot'
28
+ DEFAULT_PUBLISH_MODE=approval
29
+
30
+ # Scheduling & Localization
31
+ TIMEZONE=Africa/Lagos
32
+ MAX_POSTS_PER_DAY=3
33
+
34
+ # Database & Storage
35
+ POSTPILOT_DB_PATH=postpilot.db
36
+ LOG_LEVEL=INFO
@@ -0,0 +1,34 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [ master ]
6
+ pull_request:
7
+ branches: [ master ]
8
+
9
+ jobs:
10
+ test:
11
+ name: Run Unit & Integration Tests
12
+ runs-on: ubuntu-latest
13
+ strategy:
14
+ matrix:
15
+ python-version: ["3.11", "3.12"]
16
+
17
+ steps:
18
+ - name: Checkout code
19
+ uses: actions/checkout@v4
20
+
21
+ - name: Set up Python ${{ matrix.python-version }}
22
+ uses: actions/setup-python@v5
23
+ with:
24
+ python-version: ${{ matrix.python-version }}
25
+ cache: "pip"
26
+
27
+ - name: Install dependencies
28
+ run: |
29
+ python -m pip install --upgrade pip
30
+ pip install -e ".[dev]"
31
+
32
+ - name: Run Pytest
33
+ run: |
34
+ pytest
@@ -0,0 +1,74 @@
1
+ name: Publish to PyPI πŸ“¦
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ test:
10
+ name: Run Test Suite
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - name: Checkout code
14
+ uses: actions/checkout@v4
15
+
16
+ - name: Set up Python 3.11
17
+ uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.11"
20
+ cache: "pip"
21
+
22
+ - name: Install dependencies
23
+ run: |
24
+ python -m pip install --upgrade pip
25
+ pip install -e ".[dev]"
26
+
27
+ - name: Run Pytest
28
+ run: |
29
+ pytest
30
+
31
+ build:
32
+ name: Build distribution πŸ“¦
33
+ needs: [test]
34
+ runs-on: ubuntu-latest
35
+ steps:
36
+ - name: Checkout code
37
+ uses: actions/checkout@v4
38
+
39
+ - name: Set up Python 3.11
40
+ uses: actions/setup-python@v5
41
+ with:
42
+ python-version: "3.11"
43
+
44
+ - name: Install build tools
45
+ run: python -m pip install --upgrade pip build
46
+
47
+ - name: Build sdist and wheel
48
+ run: python -m build
49
+
50
+ - name: Store distribution packages
51
+ uses: actions/upload-artifact@v4
52
+ with:
53
+ name: python-package-distributions
54
+ path: dist/
55
+
56
+ publish-to-pypi:
57
+ name: Publish to PyPI πŸš€
58
+ needs: [build]
59
+ runs-on: ubuntu-latest
60
+ environment:
61
+ name: pypi
62
+ url: https://pypi.org/p/postpilot
63
+ permissions:
64
+ id-token: write # Mandatory for PyPI Trusted Publishing (OIDC)
65
+ contents: read
66
+ steps:
67
+ - name: Download distribution packages
68
+ uses: actions/download-artifact@v4
69
+ with:
70
+ name: python-package-distributions
71
+ path: dist/
72
+
73
+ - name: Publish package distributions to PyPI
74
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,45 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+ .Python
7
+ env/
8
+ venv/
9
+ .venv/
10
+ build/
11
+ develop-eggs/
12
+ dist/
13
+ downloads/
14
+ eggs/
15
+ .eggs/
16
+ lib/
17
+ lib64/
18
+ parts/
19
+ sdist/
20
+ var/
21
+ wheels/
22
+ *.egg-info/
23
+ .installed.cfg
24
+ *.egg
25
+
26
+ # Database & Local State
27
+ *.db
28
+ *.sqlite
29
+ *.sqlite3
30
+ postpilot.db
31
+
32
+ # Secrets & Environment
33
+ .env
34
+ .env.local
35
+
36
+ # Testing & Coverage
37
+ .pytest_cache/
38
+ .coverage
39
+ htmlcov/
40
+
41
+ # IDE & OS
42
+ .vscode/
43
+ .idea/
44
+ .DS_Store
45
+ Thumbs.db
@@ -0,0 +1,22 @@
1
+ FROM python:3.11-slim
2
+
3
+ WORKDIR /app
4
+
5
+ # Install system dependencies
6
+ RUN apt-get update && apt-get install -y --no-install-recommends \
7
+ gcc \
8
+ && rm -rf /var/lib/apt/lists/*
9
+
10
+ # Copy project files
11
+ COPY pyproject.toml README.md ./
12
+ COPY src/ ./src/
13
+
14
+ # Install dependencies in editable mode
15
+ RUN pip install --no-cache-dir -e .
16
+
17
+ # Environment variables
18
+ ENV PYTHONUNBUFFERED=1 \
19
+ PYTHONPATH=/app/src
20
+
21
+ # Default entrypoint runs unified daemon (Scheduler + Telegram + HTTP check)
22
+ CMD ["python", "-m", "postpilot.daemon"]
@@ -0,0 +1,306 @@
1
+ Metadata-Version: 2.5
2
+ Name: postpilot
3
+ Version: 0.1.0
4
+ Summary: Personal AI-powered content management and publishing assistant for X (Twitter)
5
+ Author: DevFiend
6
+ Requires-Python: >=3.11
7
+ Requires-Dist: aiosqlite>=0.20.0
8
+ Requires-Dist: apscheduler>=3.10.4
9
+ Requires-Dist: httpx>=0.27.0
10
+ Requires-Dist: pydantic-settings>=2.2.0
11
+ Requires-Dist: pydantic>=2.7.0
12
+ Requires-Dist: pyperclip>=1.8.2
13
+ Requires-Dist: python-dotenv>=1.0.1
14
+ Requires-Dist: python-telegram-bot>=21.0.1
15
+ Requires-Dist: pytz>=2024.1
16
+ Requires-Dist: rich>=13.7.0
17
+ Requires-Dist: sqlalchemy>=2.0.29
18
+ Requires-Dist: typer[all]>=0.12.0
19
+ Provides-Extra: dev
20
+ Requires-Dist: pytest-asyncio>=0.23.6; extra == 'dev'
21
+ Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
22
+ Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
23
+ Requires-Dist: pytest>=8.1.0; extra == 'dev'
24
+ Requires-Dist: ruff>=0.4.0; extra == 'dev'
25
+ Description-Content-Type: text/markdown
26
+
27
+ <div align="center">
28
+
29
+ # πŸš€ PostPilot (X-PostPilot)
30
+
31
+ ### *Your Personal AI Content Management & Publishing Copilot for X (Twitter).*
32
+ **One Engine. Dual Interfaces (CLI + Telegram). 100% $0-First & Ban-Proof.**
33
+
34
+ [![PyPI Version](https://img.shields.io/pypi/v/postpilot.svg?style=for-the-badge&color=blue)](https://pypi.org/project/postpilot/)
35
+ [![GitHub Release](https://img.shields.io/github/v/release/devFiend/X-PostPilot?style=for-the-badge&color=blue)](https://github.com/devFiend/X-PostPilot/releases)
36
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
37
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
38
+ [![Architecture: Clean](https://img.shields.io/badge/Architecture-Clean%20%2F%20Modular-green.svg?style=for-the-badge)]()
39
+ [![Tests: Passing](https://img.shields.io/badge/Tests-15%2F15%20Passed-brightgreen.svg?style=for-the-badge)]()
40
+ [![Cost: $0-First](https://img.shields.io/badge/Cost-%240--First-success.svg?style=for-the-badge)]()
41
+
42
+ <br/>
43
+
44
+ > πŸ’‘ **The Reality:** Standard social tools either lock you into \$30-\$100/mo subscriptions, require expensive pay-per-use X API credits (\$0.015/post or \$0.20/link post), or use unofficial browser scrapers that get your personal account banned.
45
+ > **PostPilot fixes this.** It lets you brainstorm, draft, review, schedule, and publish high-impact X content using **free AI quotas (Groq / Gemini / local Ollama)**, a crash-proof local scheduler, and a private Telegram control room β€” with **zero required API fees**.
46
+
47
+ ---
48
+
49
+ [Features](#-key-features) β€’
50
+ [Architecture](#-system-architecture) β€’
51
+ [Quickstart](#-60-second-quickstart) β€’
52
+ [Telegram Setup](#-linking-your-telegram-bot) β€’
53
+ [TweetDNA Intelligence](#-tweetdna-creator-intelligence) β€’
54
+ [CLI Cheatsheet](#-cli-cheatsheet) β€’
55
+ [Deploy to Render](#-deploying-to-render-247-hosting) β€’
56
+ [Documentation](#-deep-documentation) β€’
57
+ [License](#-license)
58
+
59
+ </div>
60
+
61
+ ---
62
+
63
+ ## πŸ”₯ Key Features
64
+
65
+ ### 🧠 Multi-Provider AI Brain ($0-First)
66
+ - **Groq (Default):** Generates high-velocity, scroll-stopping post variants in $<2$ seconds using LLaMA-3 / GPT-OSS models.
67
+ - **Google Gemini:** Deep content planning and long-form breakdown using Gemini's generous free tier.
68
+ - **Ollama:** 100% private, offline generation with zero internet reliance.
69
+ - **Strict Guardrails:** Built-in validator guarantees every post stays strictly under 280 characters with no corporate fluff or repetitive buzzwords.
70
+
71
+ ### 🧬 TweetDNA Creator Intelligence & Style Cloning
72
+ - **Anonymous Public Tweet Scraping ($0 Ban-Proof):** Scrapes recent public tweets from creators you admire (`@levelsio`, `@swyx`, `@shl`, `@karpathy`) without using your personal account or paid APIs.
73
+ - **4-Layer DNA Extraction:** Deconstructs Content Pillars, Tweet Formats, Writing Rhythm, and Hook Formulas.
74
+ - **Multi-Creator Synthesis:** Blends the best traits of 5-10 creators into original content tailored to your niche.
75
+
76
+ ### ⏰ Hourly Content Delivery (8:00 AM – 11:59 PM)
77
+ - Automatically delivers **4–5 fresh post cards every hour** directly to your Telegram chat during active hours.
78
+ - Each card comes with a **`[πŸš€ Post to X Now (Auto-Approves)]`** button that opens the pre-filled X composer on your phone in 1 tap!
79
+ - On-demand requests anytime: `/ideas [count]` or `/inspire @creator [count]`.
80
+
81
+ ### 🎭 CreatorDNA Content Profiling
82
+ - Generates posts that sound like **you**, not a boilerplate corporate bot.
83
+ - Configurable content pillars (e.g., *Software Engineering, AI Tools, Building in Public*), voice guidelines, and excluded phrases.
84
+
85
+ ### πŸ›‘οΈ $0 Dual-Mode Publishing (Zero Ban Risk)
86
+ - **Method A: Manual Handoff ($0 Cost - Recommended):**
87
+ When a scheduled post is due, PostPilot copies the post to your system clipboard and delivers a pre-formatted push notification to your phone via Telegram with a one-tap link to X's official web compose intent. No X API fees, zero chance of account suspension.
88
+ - **Method B: Official X API v2 (Optional):**
89
+ Supports OAuth 1.0a User-Context authentication for full programmatic publishing when official credits are available. Automatically falls back to manual handoff if credits run out.
90
+
91
+ ### πŸ“± Private Telegram Remote Control
92
+ - Single-user authenticated bot locked to your personal `TELEGRAM_OWNER_ID`.
93
+ - Generate, inspect, approve, reject, and schedule posts directly from your phone while on the go.
94
+
95
+ ### ⚑ Autopilot with Emergency Kill-Switch
96
+ - Rotates content pillars throughout the day.
97
+ - Supports **Assisted Autopilot** (drafts content automatically and pings you on Telegram for one-tap approval) and **Autonomous Autopilot** (auto-schedules directly).
98
+ - Instant emergency pause button (`postpilot autopilot pause` or Telegram `/pause`).
99
+
100
+ ---
101
+
102
+ ## πŸ›οΈ System Architecture
103
+
104
+ PostPilot is built on a clean, decoupled modular architecture: **"One Engine, Multiple Interfaces."**
105
+
106
+ ```
107
+ +-------------------------------------------------------------------------+
108
+ | INTERFACES |
109
+ | |
110
+ | +---------------------------+ +--------------------------+ |
111
+ | | Typer CLI | | Telegram Bot Engine | |
112
+ | | (Rich terminal UI) | | (Long-polling, Inline KB)| |
113
+ | +-------------+-------------+ +------------+-------------+ |
114
+ +--------------------|--------------------------------|-------------------+
115
+ | |
116
+ +---------------+----------------+
117
+ |
118
+ +------------------------------------v------------------------------------+
119
+ | APPLICATION SERVICES |
120
+ | |
121
+ | +-------------------+ +-------------------+ +-------------------+ |
122
+ | | ContentService | | DraftService | | QueueService | |
123
+ | +-------------------+ +-------------------+ +-------------------+ |
124
+ | | ApprovalService | | SchedulingService | | DNAService | |
125
+ | +-------------------+ +-------------------+ +-------------------+ |
126
+ | | AutopilotService | | PublishingService | |
127
+ | +-------------------+ +------------------------------------------+ |
128
+ +--------------------|-------------------|--------------------|-----------+
129
+ | | |
130
+ +---------------+ | +---------------+
131
+ | | |
132
+ +----v-----------------+ +----------v----------+ +------------------v---+
133
+ | AI & TWEETDNA LAYER | | PUBLISHING LAYER | | DATA & SCHEDULER |
134
+ | | | | | |
135
+ | +------------------+ | | +-----------------+ | | +------------------+ |
136
+ | | TweetDNAAnalyzer | | | | BasePublisher | | | | APScheduler | |
137
+ | +------------------+ | | +--------+--------+ | | | (Hourly Drops) | |
138
+ | | TweetDNAGenerator| | | | | | +------------------+ |
139
+ | +------------------+ | | +-----+----+ | | | SQLite Store | |
140
+ | | AIRouter (Groq/ | | | +--v----+ +---v---+ | | +------------------+ |
141
+ | | Gemini/Ollama) | | | |Manual | |X API | | | | SQLAlchemy Repos | |
142
+ | +------------------+ | | |Handoff| | v2 | | | | (postpilot.db) | |
143
+ +----------------------+ +---------+ +-------+ + +----------------------+
144
+ ```
145
+
146
+ ---
147
+
148
+ ## ⚑ 60-Second Quickstart
149
+
150
+ ### 1. Installation
151
+
152
+ **Option A: Install directly via PyPI (Recommended)**
153
+ ```bash
154
+ pip install postpilot
155
+ ```
156
+
157
+ **Option B: Clone for local development**
158
+ ```bash
159
+ git clone https://github.com/devFiend/X-PostPilot.git
160
+ cd X-PostPilot
161
+ python -m venv .venv
162
+
163
+ # Activate on Windows:
164
+ .venv\Scripts\activate
165
+
166
+ # Activate on macOS/Linux:
167
+ source .venv/bin/activate
168
+
169
+ # Install in editable mode
170
+ pip install -e .
171
+ ```
172
+
173
+ ### 3. Configure environment
174
+ Copy `.env.example` to `.env`:
175
+ ```bash
176
+ cp .env.example .env
177
+ ```
178
+ Open `.env` and add your free [Groq API Key](https://console.groq.com/keys):
179
+ ```env
180
+ GROQ_API_KEY=gsk_your_free_key_here
181
+ ```
182
+
183
+ ### 4. Verify system with Doctor
184
+ ```bash
185
+ python -m postpilot.cli doctor
186
+ ```
187
+
188
+ ---
189
+
190
+ ## 🧬 TweetDNA Creator Intelligence
191
+
192
+ Reverse-engineer how your favorite creators write and synthesize their styles into your niche:
193
+
194
+ ### Track a Creator (CLI or Telegram)
195
+ ```bash
196
+ postpilot dna track @levelsio
197
+ postpilot dna track @swyx
198
+ ```
199
+ In Telegram, simply send:
200
+ ```text
201
+ /track @levelsio
202
+ ```
203
+ PostPilot anonymously scrapes their recent public tweets, extracts their **Tone, Hook Patterns, and Writing Frameworks**, and adds them to your active creator intelligence pool!
204
+
205
+ ### Generate Posts From Your Creator Pool
206
+ ```bash
207
+ # Generate 4 on-demand posts across your tracked creators
208
+ postpilot dna ideas --count 4
209
+ ```
210
+ In Telegram:
211
+ - `/ideas 2` β€” Returns 2 on-demand post cards.
212
+ - `/inspire @levelsio 2` β€” Drafts 2 posts specifically mimicking `@levelsio`'s voice.
213
+ - `/creators` β€” Lists all creators in your active intelligence pool.
214
+
215
+ ---
216
+
217
+ ## πŸ€– Linking Your Telegram Bot
218
+
219
+ Manage your queue and approve posts from your couch in **under 2 minutes**:
220
+
221
+ 1. **Create Bot:** Search for [@BotFather](https://t.me/BotFather) on Telegram $\rightarrow$ send `/newbot` $\rightarrow$ copy your **API Token**.
222
+ 2. **Get Your User ID:** Search for [@userinfobot](https://t.me/userinfobot) on Telegram $\rightarrow$ click start $\rightarrow$ copy your numerical **ID**.
223
+ 3. **Save to `.env`:**
224
+ ```env
225
+ TELEGRAM_BOT_TOKEN=7123456789:AAFlM_...
226
+ TELEGRAM_OWNER_ID=123456789
227
+ ```
228
+ 4. **Launch Bot:**
229
+ ```bash
230
+ python -m postpilot.cli telegram
231
+ ```
232
+ 5. Open your bot in Telegram and send `/track @levelsio` or `/ideas`.
233
+
234
+ ---
235
+
236
+ ## ☁️ Deploying to Render (24/7 Hosting)
237
+
238
+ PostPilot includes native Render support (`render.yaml` Blueprint) so your Telegram Bot and Hourly Drops run **24/7 in the cloud for free**:
239
+
240
+ 1. Push this repository to your GitHub.
241
+ 2. Log into **[Render.com](https://render.com/)**.
242
+ 3. Click **New +** $\rightarrow$ **Blueprint**.
243
+ 4. Connect your `X-PostPilot` repository.
244
+ 5. Render will detect `render.yaml`. Fill in your environment variables:
245
+ - `GROQ_API_KEY`: your free Groq key
246
+ - `TELEGRAM_BOT_TOKEN`: your BotFather token
247
+ - `TELEGRAM_OWNER_ID`: your numerical Telegram ID
248
+ 6. Click **Apply**. Render will build and deploy PostPilot with automatic health checks!
249
+
250
+ ---
251
+
252
+ ## πŸ’» CLI Cheatsheet
253
+
254
+ | Command | Description | Example |
255
+ |---|---|---|
256
+ | `postpilot start` | Run unified daemon (Scheduler + Telegram + Health Check) | `postpilot start` |
257
+ | `postpilot doctor` | Run diagnostic check on AI keys, DB, and Telegram | `postpilot doctor` |
258
+ | `postpilot dna track` | Track and analyze a creator's Content DNA | `postpilot dna track @levelsio` |
259
+ | `postpilot dna list` | List all tracked creators in intelligence pool | `postpilot dna list` |
260
+ | `postpilot dna ideas` | Generate posts synthesized from creator pool | `postpilot dna ideas --count 4` |
261
+ | `postpilot generate` | Generate multiple post options with AI | `postpilot generate -t "Clean Architecture" -c 3` |
262
+ | `postpilot drafts` | Browse all saved drafts | `postpilot drafts` |
263
+ | `postpilot approve` | Approve a draft for scheduling | `postpilot approve 1` |
264
+ | `postpilot schedule` | Schedule an approved post | `postpilot schedule 1 --at "2026-11-25 18:30"` |
265
+ | `postpilot queue` | View pending scheduled posts | `postpilot queue` |
266
+ | `postpilot publish` | Dispatch post (copies text & opens compose link) | `postpilot publish 1` |
267
+ | `postpilot run` | Run background scheduler worker loop | `postpilot run` |
268
+ | `postpilot telegram` | Run Telegram bot long-polling daemon | `postpilot telegram` |
269
+ | `postpilot autopilot` | Manage autopilot states & cycles | `postpilot autopilot run-cycle` |
270
+
271
+ ---
272
+
273
+ ## πŸ“š Deep Documentation
274
+
275
+ Comprehensive architectural design, specifications, and test documentation:
276
+ - πŸ“– **[Product Requirements Document (PRD)](docs/PRD.md):** Vision, functional scope, personas, and platform policies.
277
+ - πŸ“ **[System Architecture](docs/ARCHITECTURE.md):** Clean architecture layers, database schemas (ERD), and sequence diagrams.
278
+ - πŸ—ΊοΈ **[2-Phase Development Flow](docs/DEVELOPMENT_FLOW.md):** Full implementation roadmap and milestone verification.
279
+ - πŸ§ͺ **[Testing Strategy](docs/TESTING.md):** Test suite design, invariant testing, and mocking guide.
280
+
281
+ ---
282
+
283
+ ## πŸ§ͺ Testing
284
+
285
+ PostPilot includes a complete test suite covering AI parsing, TweetDNA extraction, database repositories, state machine invariants, scheduler recovery, and security firewalls:
286
+
287
+ ```bash
288
+ # Run full test suite
289
+ python -m pytest
290
+
291
+ # Run with verbose output
292
+ python -m pytest -v
293
+ ```
294
+
295
+ ---
296
+
297
+ ## πŸ“„ License
298
+
299
+ Distributed under the MIT License. See `LICENSE` for more information.
300
+
301
+ ---
302
+
303
+ <div align="center">
304
+ <b>Built with ❀️ by <a href="https://github.com/devFiend">DevFiend</a></b><br/>
305
+ <i>Give this repository a ⭐ if it helps your content workflow!</i>
306
+ </div>