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.
- postpilot-0.1.0/.env.example +36 -0
- postpilot-0.1.0/.github/workflows/ci.yml +34 -0
- postpilot-0.1.0/.github/workflows/publish.yml +74 -0
- postpilot-0.1.0/.gitignore +45 -0
- postpilot-0.1.0/Dockerfile +22 -0
- postpilot-0.1.0/PKG-INFO +306 -0
- postpilot-0.1.0/README.md +280 -0
- postpilot-0.1.0/docker-compose.yml +15 -0
- postpilot-0.1.0/docs/ARCHITECTURE.md +236 -0
- postpilot-0.1.0/docs/DEVELOPMENT_FLOW.md +118 -0
- postpilot-0.1.0/docs/PRD.md +154 -0
- postpilot-0.1.0/docs/TESTING.md +74 -0
- postpilot-0.1.0/pyproject.toml +49 -0
- postpilot-0.1.0/render.yaml +31 -0
- postpilot-0.1.0/src/postpilot/__init__.py +6 -0
- postpilot-0.1.0/src/postpilot/ai/__init__.py +1 -0
- postpilot-0.1.0/src/postpilot/ai/base.py +23 -0
- postpilot-0.1.0/src/postpilot/ai/gemini.py +46 -0
- postpilot-0.1.0/src/postpilot/ai/groq.py +59 -0
- postpilot-0.1.0/src/postpilot/ai/ollama.py +42 -0
- postpilot-0.1.0/src/postpilot/ai/router.py +45 -0
- postpilot-0.1.0/src/postpilot/cli.py +93 -0
- postpilot-0.1.0/src/postpilot/commands/__init__.py +31 -0
- postpilot-0.1.0/src/postpilot/commands/autopilot_cmd.py +102 -0
- postpilot-0.1.0/src/postpilot/commands/config_cmd.py +65 -0
- postpilot-0.1.0/src/postpilot/commands/dna_cmd.py +126 -0
- postpilot-0.1.0/src/postpilot/commands/doctor_cmd.py +67 -0
- postpilot-0.1.0/src/postpilot/commands/drafts_cmd.py +71 -0
- postpilot-0.1.0/src/postpilot/commands/generate_cmd.py +45 -0
- postpilot-0.1.0/src/postpilot/commands/init_cmd.py +45 -0
- postpilot-0.1.0/src/postpilot/commands/publish_cmd.py +45 -0
- postpilot-0.1.0/src/postpilot/commands/queue_cmd.py +44 -0
- postpilot-0.1.0/src/postpilot/commands/schedule_cmd.py +47 -0
- postpilot-0.1.0/src/postpilot/commands/status_cmd.py +56 -0
- postpilot-0.1.0/src/postpilot/daemon.py +131 -0
- postpilot-0.1.0/src/postpilot/database/__init__.py +1 -0
- postpilot-0.1.0/src/postpilot/database/db.py +32 -0
- postpilot-0.1.0/src/postpilot/database/models.py +173 -0
- postpilot-0.1.0/src/postpilot/database/repositories.py +243 -0
- postpilot-0.1.0/src/postpilot/dna/__init__.py +3 -0
- postpilot-0.1.0/src/postpilot/dna/analyzer.py +79 -0
- postpilot-0.1.0/src/postpilot/dna/collector.py +106 -0
- postpilot-0.1.0/src/postpilot/dna/generator.py +64 -0
- postpilot-0.1.0/src/postpilot/main.py +15 -0
- postpilot-0.1.0/src/postpilot/publishers/__init__.py +1 -0
- postpilot-0.1.0/src/postpilot/publishers/base.py +28 -0
- postpilot-0.1.0/src/postpilot/publishers/manual.py +36 -0
- postpilot-0.1.0/src/postpilot/publishers/x_publisher.py +156 -0
- postpilot-0.1.0/src/postpilot/scheduler/__init__.py +1 -0
- postpilot-0.1.0/src/postpilot/scheduler/hourly_delivery.py +120 -0
- postpilot-0.1.0/src/postpilot/scheduler/worker.py +81 -0
- postpilot-0.1.0/src/postpilot/services/__init__.py +1 -0
- postpilot-0.1.0/src/postpilot/services/autopilot.py +119 -0
- postpilot-0.1.0/src/postpilot/services/content.py +48 -0
- postpilot-0.1.0/src/postpilot/services/dna.py +129 -0
- postpilot-0.1.0/src/postpilot/services/publishing.py +60 -0
- postpilot-0.1.0/src/postpilot/telegram/__init__.py +7 -0
- postpilot-0.1.0/src/postpilot/telegram/bot.py +94 -0
- postpilot-0.1.0/src/postpilot/telegram/handlers.py +541 -0
- postpilot-0.1.0/src/postpilot/telegram/keyboards.py +95 -0
- postpilot-0.1.0/src/postpilot/telegram/security.py +21 -0
- postpilot-0.1.0/src/postpilot/utils/__init__.py +1 -0
- postpilot-0.1.0/src/postpilot/utils/config.py +85 -0
- postpilot-0.1.0/tests/__init__.py +3 -0
- postpilot-0.1.0/tests/conftest.py +20 -0
- postpilot-0.1.0/tests/test_ai.py +36 -0
- postpilot-0.1.0/tests/test_autopilot.py +36 -0
- postpilot-0.1.0/tests/test_content.py +23 -0
- postpilot-0.1.0/tests/test_dna.py +81 -0
- postpilot-0.1.0/tests/test_publishing.py +30 -0
- postpilot-0.1.0/tests/test_queue.py +22 -0
- postpilot-0.1.0/tests/test_scheduler.py +22 -0
- 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"]
|
postpilot-0.1.0/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/postpilot/)
|
|
35
|
+
[](https://github.com/devFiend/X-PostPilot/releases)
|
|
36
|
+
[](https://www.python.org/)
|
|
37
|
+
[](https://opensource.org/licenses/MIT)
|
|
38
|
+
[]()
|
|
39
|
+
[]()
|
|
40
|
+
[]()
|
|
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>
|