Metadata-Version: 2.4
Name: social-plugin
Version: 0.2.4
Summary: CLI tool for AI-powered social media content generation and publishing
Author: Nirmal Sharma
License-Expression: MIT
Project-URL: Homepage, https://github.com/nirmalsharma/social-plugin
Project-URL: Repository, https://github.com/nirmalsharma/social-plugin
Project-URL: Issues, https://github.com/nirmalsharma/social-plugin/issues
Keywords: social-media,ai,cli,content-generation,twitter,linkedin,claude,gpt,gemini
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: anthropic>=0.40
Requires-Dist: openai>=1.0
Requires-Dist: google-generativeai>=0.8
Requires-Dist: tweepy>=4.14
Requires-Dist: google-api-python-client>=2.100
Requires-Dist: google-auth>=2.23
Requires-Dist: google-auth-oauthlib>=1.1
Requires-Dist: feedparser>=6.0
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: httpx>=0.25
Requires-Dist: pdfplumber>=0.10
Requires-Dist: Pillow>=10.0
Requires-Dist: tenacity>=8.2
Requires-Dist: python-dateutil>=2.8
Requires-Dist: better-profanity>=0.7
Requires-Dist: slack-sdk>=3.23
Requires-Dist: python-docx>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-mock>=3.11; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Social Plugin

AI-powered CLI tool for social media content generation and publishing, focused on Physical AI & Robotics.

Discovers trending topics via RSS feeds, reads reference content from local files/Google Docs/PDFs, uses AI to generate tweet and LinkedIn post drafts, and posts approved content.

## Quick Start

**macOS / Linux:**
```bash
pipx install social-plugin
social-plugin init
```

**Windows (PowerShell):**
```powershell
pipx install social-plugin
social-plugin init
```

The `init` wizard walks you through choosing an AI provider, entering API keys, setting your local docs folder, and configuring your topics.

## Prerequisites

You need an API key from at least one provider:

| Provider | Get API Key | Models |
|----------|-------------|--------|
| **Anthropic** | [console.anthropic.com](https://console.anthropic.com/) | `claude-sonnet-4-5-20250929`, `claude-opus-4-6` |
| **OpenAI** | [platform.openai.com](https://platform.openai.com/) | `gpt-4o`, `gpt-4o-mini`, `o1`, `o3-mini` |
| **Google** | [aistudio.google.com](https://aistudio.google.com/) | `gemini-2.0-flash`, `gemini-2.5-pro` |

For posting to Twitter/X, you also need API keys from [developer.x.com](https://developer.x.com/).

## Manual Install (from source)

```bash
git clone https://github.com/nirmalsharma/social-plugin.git
cd social-plugin
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp config/config.example.yaml config/config.yaml
cp .env.example .env
# Edit .env with your API keys
social-plugin --help
```

## Configuration

After running `social-plugin init`, config is stored in:

- **macOS:** `~/Library/Application Support/social-plugin/config.yaml`
- **Linux:** `~/.config/social-plugin/config.yaml`
- **Windows:** `%APPDATA%\social-plugin\config.yaml`

If running from the repo directory, `./config/config.yaml` takes priority (development mode).

### Upgrading

When upgrading to a new version, run `init --upgrade` to add any new config sections while keeping all your existing settings:

```bash
pipx upgrade social-plugin
social-plugin init --upgrade
```

This creates a backup (`config.yaml.bak`), then merges new defaults into your config. Your provider, model, topics, hashtags, and all other customizations are preserved.

### Multi-Provider Config

```yaml
generation:
  provider: "anthropic"           # "anthropic", "openai", or "google"
  model: "claude-sonnet-4-5-20250929"  # or "gpt-4o", "gemini-2.0-flash"
  max_tokens: 4096
  temperature: 0.7
```

Provider is auto-detected from the model name if not set. Set the matching env var:

- `ANTHROPIC_API_KEY` for Claude models
- `OPENAI_API_KEY` for GPT/o1/o3 models
- `GOOGLE_API_KEY` for Gemini models

## Usage

### Typical Workflow

```bash
social-plugin fetch-trends       # 1. Get latest trending topics
social-plugin fetch-sources      # 2. Read local docs/PDFs
social-plugin generate           # 3. Generate AI drafts
social-plugin drafts             # 4. Review pending drafts
social-plugin approve <id>       # 5. Approve a draft
social-plugin post --id <id>     # 6. Post to Twitter/LinkedIn
```

Or run steps 1-3 in one command:

```bash
social-plugin run-all
```

### All Commands

| Command | Description |
|---------|-------------|
| `init` | Interactive setup wizard |
| `init --upgrade` | Upgrade existing config with new defaults (preserves your settings) |
| `config --show` | Show config paths and active provider |
| `fetch-trends` | Fetch trending topics from RSS feeds |
| `fetch-sources` | Read configured Google Docs, PDFs, local files |
| `generate` | Generate 1 tweet + 1 LinkedIn draft |
| `generate --dry-run` | Preview without saving |
| `list --last 10` | List last N drafts ordered by date |
| `drafts` | List pending drafts |
| `drafts --status all` | List all drafts |
| `show <id>` | Full draft details |
| `review <id>` | Interactive review (approve/edit/regen/reject) |
| `approve <id>` | Approve for posting (also accepts failed drafts) |
| `approve <id> -n "what you liked"` | Approve with positive feedback (improves future content) |
| `reject <id> -n "reason"` | Reject with reason (required) |
| `delete <id>` | Delete a draft permanently |
| `edit <id>` | Open in $EDITOR |
| `regen <id> -t "casual"` | Regenerate with new tone |
| `post --id <id>` | Post specific draft |
| `post --all-approved` | Post all approved drafts |
| `run-all` | Full pipeline: trends + sources + generate |
| `stats` | Analytics dashboard |
| `history --days 30` | Content history |
| `expire` | Expire old pending drafts |
| `auth-check` | Verify API credentials |

### Content Generation Quality

Generated content benefits from several quality features:

- **Fully config-driven** — topic, hashtags, tone all from `config.yaml`; no hardcoded values in prompts
- **User rules (DO's/DON'Ts)** — persistent content rules the AI follows during generation (e.g. "never use clickbait"); sensible defaults built-in
- **Style examples (few-shot)** — paste 2-3 posts you like in config; the AI mimics your voice and structure
- **Feedback loop** — rejection reasons and approval notes are fed back to the LLM to improve future content
- **Long-form X/Twitter posts** — 280 chars by default; set `x_premium: true` in config for long-form posts up to 25,000 chars
- **Reliable tweet posting** — auto-drops appended hashtags if over character limit; auto-regenerates via LLM if still over; falls back to manual `regen` suggestion if no LLM available (no truncation)
- **Auto-retry on over-limit** — generator retries once with a stricter constraint if a tweet exceeds the character limit
- **Source URL references** — when referencing articles or research, generated posts include clickable source URLs
- **Freshness-aware** — avoids repeating content across runs by checking the last 15 drafts / 10 days of history (not just today)
- **Meaningful rewrites** — `review` choice 3 (add context) and `regen` produce genuinely different posts, not minor rewordings
- **Source warnings** — warns when no reference documents are available, suggests adding docs for richer content
- **X.com + Twitter feed support** — trend discovery works with both x.com and twitter.com RSS feeds
- **Source-first generation** — reference documents drive content; trends provide context, not headlines
- **Garbled PDF detection** — warns when a PDF has unreadable fonts and suggests saving as `.txt` instead

### Draft Lifecycle

```
PENDING → approve → APPROVED → post → POSTED
  ↓         ↑                    ↓
reject   regen(tone)           FAILED
  ↓
REJECTED
  ↓
expire (7 days) → EXPIRED
```

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest tests/ -v
```

### Install from TestPyPI

To test a pre-release build before it goes to PyPI:

```bash
pipx install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ social-plugin
```

### Publishing

CI publishes automatically on tag push via GitHub Actions:

```bash
git tag v0.1.0
git push --tags
```

This triggers: **build** → **TestPyPI** → **PyPI** (sequential, OIDC trusted publishing).

## License

MIT
