social-plugin 0.1.1__tar.gz

social_plugin-0.1.1/.env.example

@@ -0,0 +1,32 @@
+# =============================================================================
+# LLM Provider (set ONE of these based on your chosen provider)
+# =============================================================================
+
+# Anthropic Claude (default)
+ANTHROPIC_API_KEY=sk-ant-xxx
+
+# OpenAI GPT (alternative)
+OPENAI_API_KEY=sk-xxx
+
+# Google Gemini (alternative)
+GOOGLE_API_KEY=xxx
+
+# =============================================================================
+# Twitter/X API (Pay-Per-Use)
+# =============================================================================
+TWITTER_API_KEY=xxx
+TWITTER_API_SECRET=xxx
+TWITTER_ACCESS_TOKEN=xxx
+TWITTER_ACCESS_TOKEN_SECRET=xxx
+TWITTER_BEARER_TOKEN=xxx
+
+# LinkedIn (future auto-post)
+LINKEDIN_CLIENT_ID=xxx
+LINKEDIN_CLIENT_SECRET=xxx
+LINKEDIN_ACCESS_TOKEN=xxx
+
+# Google Docs (service account JSON path — only needed for Google Docs sources)
+GOOGLE_SERVICE_ACCOUNT_PATH=credentials/service-account.json
+
+# Slack
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/xxx/xxx

social_plugin-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nirmal Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

social_plugin-0.1.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include config/config.example.yaml
+include .env.example
+recursive-include social_plugin/templates *.yaml

social_plugin-0.1.1/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: social-plugin
+Version: 0.1.1
+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, 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).
+
+### 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 |
+| `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 |
+| `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 |
+| `reject <id> -n "reason"` | Reject with notes |
+| `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 |
+
+### 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

social_plugin-0.1.1/README.md

@@ -0,0 +1,160 @@
+# 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, 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).
+
+### 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 |
+| `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 |
+| `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 |
+| `reject <id> -n "reason"` | Reject with notes |
+| `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 |
+
+### 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

social_plugin-0.1.1/config/config.example.yaml

@@ -0,0 +1,121 @@
+# =============================================================================
+# Social Plugin — Example Configuration
+# =============================================================================
+# Copy this file to config/config.yaml and customize.
+# Secrets go in .env (see .env.example).
+
+# --- Topics ---
+# Define what you post about. Keywords are used for trend relevance scoring.
+topics:
+  primary: "Physical AI and Robotics"
+  keywords:
+    - "physical AI"
+    - "robotics"
+    - "embodied AI"
+    - "humanoid robots"
+    - "sim-to-real"
+  hashtags:
+    twitter: ["#PhysicalAI", "#Robotics", "#EmbodiedAI"]
+    linkedin: ["#PhysicalAI", "#Robotics", "#AI"]
+
+# --- Accounts ---
+# Which platforms to generate content for and posting limits.
+accounts:
+  twitter:
+    enabled: true
+    api_tier: "pay-per-use"                 # X API is pay-per-use as of 2025
+    max_posts_per_day: 1
+  linkedin:
+    enabled: true
+    auto_post: false                       # Set to true when LinkedIn Developer app is ready
+    max_posts_per_day: 1
+
+# --- Content Sources ---
+# Direct links to reference material. NOT folder-based — each source is explicit.
+sources:
+  # Google Docs — share each doc with your service account email
+  google_docs:
+    - id: "1aBcDeFgHiJkLmNoPqRsTuVwXyZ"
+      name: "Weekly AI Briefing"
+    - url: "https://docs.google.com/document/d/xxx/edit"
+      name: "Research Notes"
+
+  # Remote PDFs only (URLs) — local PDFs go in local_files
+  pdfs:
+    - url: "https://arxiv.org/pdf/xxxx.pdf"
+      name: "ArXiv Paper"
+
+  # Local files — supports txt, md, csv, pdf, doc, docx
+  local_files:
+    - path: "/Users/you/notes/ai-thoughts.md"
+    - path: "/Users/you/Documents/robotics-paper.pdf"
+      name: "Robotics Paper"
+    - path: "/Users/you/Documents/research-brief.docx"
+      name: "Research Brief"
+
+  # Media attachments for posts
+  media:
+    - path: "/Users/you/media/robot-demo.png"
+      description: "Robot manipulation demo"
+    - drive_url: "https://drive.google.com/file/d/xxx"
+      description: "Lab photo"
+
+  cache_ttl_hours: 24                     # How long cached sources are considered fresh
+
+# --- Content Generation ---
+# LLM settings for draft generation. Supports Anthropic Claude, OpenAI GPT, and Google Gemini.
+# Provider is auto-detected from model name if not set.
+generation:
+  provider: "anthropic"                   # "anthropic", "openai", or "google" (auto-detected if omitted)
+  model: "claude-sonnet-4-5-20250929"     # Anthropic: claude-sonnet-4-5-20250929, claude-opus-4-6
+                                          # OpenAI:    gpt-4o, gpt-4o-mini, o1, o3-mini
+                                          # Google:    gemini-2.0-flash, gemini-2.5-pro
+  max_tokens: 4096
+  temperature: 0.7                          # Higher = more creative, lower = more focused
+  default_tone: "informative, thought-provoking, professional"
+
+  tweet:
+    max_length: 280
+    count_per_run: 1
+    style: "concise insight with relevant hashtag"
+
+  linkedin_post:
+    max_length: 3000
+    count_per_run: 1
+    style: "thought-leadership, conversational, uses line breaks, ends with a question"
+
+# --- Content Safety ---
+# Filters applied to all generated content before saving as drafts.
+safety:
+  profanity_filter: true                   # Uses better-profanity library
+  blocked_words: []                        # Add custom words to block
+  compliance_note: "No financial advice, no medical claims"
+
+# --- Notifications ---
+notifications:
+  slack:
+    enabled: true
+    webhook_url_env: "SLACK_WEBHOOK_URL"   # Env var name containing the webhook URL
+    channel: "#social-content"
+  cli: true                                # Always show CLI output
+
+# --- Trend Discovery ---
+# RSS feeds for discovering trending topics. Google News RSS is free.
+trends:
+  rss_feeds:
+    - "https://news.google.com/rss/search?q=physical+AI+robotics"
+    - "https://news.google.com/rss/search?q=physical+AI+robotics+site:twitter.com"
+    - "https://news.google.com/rss/search?q=physical+AI+robotics+site:linkedin.com"
+    - "https://feeds.feedburner.com/IeeeSpectrum"
+  max_results: 20
+
+# --- Database ---
+database:
+  path: "data/social_plugin.db"            # SQLite file (entire state manager)
+
+# --- Logging ---
+logging:
+  level: "INFO"                            # DEBUG, INFO, WARNING, ERROR
+  file: "data/logs/social_plugin.log"
+  max_size_mb: 10
+  backup_count: 5

social_plugin-0.1.1/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "social-plugin"
+version = "0.1.1"
+description = "CLI tool for AI-powered social media content generation and publishing"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{name = "Nirmal Sharma"}]
+keywords = ["social-media", "ai", "cli", "content-generation", "twitter", "linkedin", "claude", "gpt", "gemini"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "pyyaml>=6.0",
+    "python-dotenv>=1.0",
+    "anthropic>=0.40",
+    "openai>=1.0",
+    "google-generativeai>=0.8",
+    "tweepy>=4.14",
+    "google-api-python-client>=2.100",
+    "google-auth>=2.23",
+    "google-auth-oauthlib>=1.1",
+    "feedparser>=6.0",
+    "beautifulsoup4>=4.12",
+    "httpx>=0.25",
+    "pdfplumber>=0.10",
+    "Pillow>=10.0",
+    "tenacity>=8.2",
+    "python-dateutil>=2.8",
+    "better-profanity>=0.7",
+    "slack-sdk>=3.23",
+    "python-docx>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-asyncio>=0.21",
+    "pytest-mock>=3.11",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/nirmalsharma/social-plugin"
+Repository = "https://github.com/nirmalsharma/social-plugin"
+Issues = "https://github.com/nirmalsharma/social-plugin/issues"
+
+[project.scripts]
+social-plugin = "social_plugin.cli:cli"
+
+[tool.setuptools.packages.find]
+include = ["social_plugin*"]
+
+[tool.setuptools.package-data]
+"social_plugin.templates" = ["*.yaml"]

social_plugin-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

social_plugin-0.1.1/social_plugin/__init__.py

@@ -0,0 +1,8 @@
+"""Social Plugin — AI-powered social media content generation and publishing."""
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("social-plugin")
+except Exception:
+    __version__ = "0.1.1"