hypermotion 1.0.0__tar.gz

hypermotion-1.0.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: hypermotion
+Version: 1.0.0
+Summary: Multi-Agent Autonomous Content Research, Scriptwriting, SEO & Facebook Growth Engine
+Author: sayeeddesignerz-creator
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sayeeddesignerz-creator/Hyper-Motion
+Project-URL: Repository, https://github.com/sayeeddesignerz-creator/Hyper-Motion
+Project-URL: Issues, https://github.com/sayeeddesignerz-creator/Hyper-Motion/issues
+Keywords: ai,automation,content-generation,facebook,seo,multi-agent,fastapi,social-media,growth-engine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi<1.0.0,>=0.111.0
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Requires-Dist: pydantic-settings<3.0.0,>=2.3.0
+Requires-Dist: pyyaml<7.0.0,>=6.0.0
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: python-dotenv<2.0.0,>=1.0.0
+Requires-Dist: sse-starlette<3.0.0,>=2.0.0
+Requires-Dist: google-genai<2.0.0,>=1.0.0
+Requires-Dist: openai<2.0.0,>=1.30.0
+Requires-Dist: feedparser<7.0.0,>=6.0.0
+Requires-Dist: pytrends<5.0.0,>=4.9.0
+Requires-Dist: rapidfuzz<4.0.0,>=3.9.0
+Requires-Dist: tenacity<10.0.0,>=8.3.0
+Requires-Dist: aiosqlite<1.0.0,>=0.20.0
+Requires-Dist: apscheduler<4.0.0,>=3.10.4
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == "dev"
+Requires-Dist: pytest-httpx<1.0.0,>=0.30.0; extra == "dev"
+
+<div align="center">
+
+# ⚡ Hyper Motion
+
+**Multi-Agent Autonomous Content Research · Scriptwriting · SEO · Facebook Growth Engine**
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.111%2B-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
+[![License](https://img.shields.io/badge/License-MIT-purple?style=for-the-badge)](LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-Hyper--Motion-181717?style=for-the-badge&logo=github)](https://github.com/sayeeddesignerz-creator/Hyper-Motion)
+
+</div>
+
+---
+
+## 🚀 Install in One Command
+
+```bash
+pip install hypermotion
+```
+
+> Requires **Python 3.10+**. A virtual environment is strongly recommended.
+
+---
+
+## ⚙️ Quick Start
+
+### 1 — Install
+
+```bash
+pip install hypermotion
+```
+
+### 2 — Initialize a fresh workspace
+
+```bash
+# Creates .env template + empty data/output dirs — nothing from anyone else
+hypermotion init
+```
+
+Or into a specific folder:
+
+```bash
+hypermotion init ./my-hypermotion
+cd my-hypermotion
+```
+
+### 3 — Add your API keys
+
+Edit the generated `.env` file:
+
+```env
+# Minimum required — pick at least one LLM provider
+GEMINI_API_KEY=your-gemini-key-here
+
+# Optional extras (adds fallback & image generation)
+OPENAI_API_KEY=
+OPENROUTER_API_KEY=
+
+# Facebook Growth Engine (sandbox mode works without these)
+FACEBOOK_PAGE_ID=
+FACEBOOK_PAGE_ACCESS_TOKEN=
+```
+
+> 🔒 `.env` is listed in `.gitignore` — it is **never** committed or shared.
+
+### 4 — Start the server
+
+```bash
+hypermotion start
+```
+
+Open **[http://localhost:8500](http://localhost:8500)** — Mission Control loads instantly.
+
+---
+
+## 🧩 CLI Reference
+
+| Command | Description |
+|---|---|
+| `hypermotion init` | Scaffold a clean workspace (fresh `.env`, empty dirs) |
+| `hypermotion init ./path --force` | Re-scaffold, overwriting existing files |
+| `hypermotion start` | Start the FastAPI server |
+| `hypermotion start --dir ./path` | Start from a specific project directory |
+| `hypermotion version` | Print version |
+
+---
+
+## 🛡️ Fresh Install Guarantee
+
+Every `hypermotion init` creates:
+
+```
+your-project/
+├── .env                ← YOUR keys only (generated from template)
+├── .gitignore          ← Secrets & output excluded automatically
+├── data/               ← Empty — YOUR runtime DB only
+├── output/             ← Empty — YOUR generated media only
+│   ├── facebook_media/
+│   └── quizzes/
+├── .cache/             ← Empty — YOUR cache only
+└── config/             ← Empty — YOUR YAML config only
+```
+
+**No API keys, images, databases, or any data from other users is ever included.**
+
+---
+
+## 🔋 What's Inside
+
+| Capability | Details |
+|---|---|
+| **Trend Radar** | Google Trends · Google News RSS · Reddit Hot · YouTube Trending |
+| **Fact-Checking Lab** | Claim extraction · Web consensus scoring · Evidence citations |
+| **Script Forge** | Second-by-second scripts · B-roll cues · CTAs |
+| **SEO Matrix** | 4 A/B title variants · 200+ word descriptions · Tags & hashtags |
+| **Facebook Engine** | Feed posts · Stories · Reels · AI visuals · Live publishing |
+| **LLM Gateway** | Gemini → OmniRoute → OpenAI → OpenRouter (auto-fallback) |
+| **Autonomous Scheduler** | Runs every N minutes, hands-free 24/7 |
+| **Mission Control UI** | Dark glassmorphic dashboard at `localhost:8500` |
+
+---
+
+## 🔌 Optional: OmniRoute (Local AI Proxy)
+
+Pool multiple API keys and route them intelligently:
+
+```bash
+npm install -g omniroute
+omniroute
+```
+
+Then in `.env`:
+
+```env
+OMNIROUTE_BASE_URL=http://localhost:20128/v1
+OMNIROUTE_API_KEY=your-omniroute-key
+OMNIROUTE_MODEL=auto
+```
+
+---
+
+## 🛠️ Manual / Development Setup
+
+```bash
+git clone https://github.com/sayeeddesignerz-creator/Hyper-Motion.git
+cd Hyper-Motion
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/bin/activate     # macOS/Linux
+pip install -e ".[dev]"
+hypermotion init
+hypermotion start
+```
+
+Run tests:
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## ⚠️ Security
+
+- **Never commit `.env`** — it is excluded by `.gitignore`
+- All output (`data/`, `output/`) is local to your machine
+- Facebook tokens are stored only in your `.env` — not logged or transmitted anywhere except the Meta Graph API
+- Rotate any API key that was accidentally exposed
+
+---
+
+## 📄 License
+
+MIT © [sayeeddesignerz-creator](https://github.com/sayeeddesignerz-creator)

hypermotion-1.0.0/README.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# ⚡ Hyper Motion
+
+**Multi-Agent Autonomous Content Research · Scriptwriting · SEO · Facebook Growth Engine**
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.111%2B-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
+[![License](https://img.shields.io/badge/License-MIT-purple?style=for-the-badge)](LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-Hyper--Motion-181717?style=for-the-badge&logo=github)](https://github.com/sayeeddesignerz-creator/Hyper-Motion)
+
+</div>
+
+---
+
+## 🚀 Install in One Command
+
+```bash
+pip install hypermotion
+```
+
+> Requires **Python 3.10+**. A virtual environment is strongly recommended.
+
+---
+
+## ⚙️ Quick Start
+
+### 1 — Install
+
+```bash
+pip install hypermotion
+```
+
+### 2 — Initialize a fresh workspace
+
+```bash
+# Creates .env template + empty data/output dirs — nothing from anyone else
+hypermotion init
+```
+
+Or into a specific folder:
+
+```bash
+hypermotion init ./my-hypermotion
+cd my-hypermotion
+```
+
+### 3 — Add your API keys
+
+Edit the generated `.env` file:
+
+```env
+# Minimum required — pick at least one LLM provider
+GEMINI_API_KEY=your-gemini-key-here
+
+# Optional extras (adds fallback & image generation)
+OPENAI_API_KEY=
+OPENROUTER_API_KEY=
+
+# Facebook Growth Engine (sandbox mode works without these)
+FACEBOOK_PAGE_ID=
+FACEBOOK_PAGE_ACCESS_TOKEN=
+```
+
+> 🔒 `.env` is listed in `.gitignore` — it is **never** committed or shared.
+
+### 4 — Start the server
+
+```bash
+hypermotion start
+```
+
+Open **[http://localhost:8500](http://localhost:8500)** — Mission Control loads instantly.
+
+---
+
+## 🧩 CLI Reference
+
+| Command | Description |
+|---|---|
+| `hypermotion init` | Scaffold a clean workspace (fresh `.env`, empty dirs) |
+| `hypermotion init ./path --force` | Re-scaffold, overwriting existing files |
+| `hypermotion start` | Start the FastAPI server |
+| `hypermotion start --dir ./path` | Start from a specific project directory |
+| `hypermotion version` | Print version |
+
+---
+
+## 🛡️ Fresh Install Guarantee
+
+Every `hypermotion init` creates:
+
+```
+your-project/
+├── .env                ← YOUR keys only (generated from template)
+├── .gitignore          ← Secrets & output excluded automatically
+├── data/               ← Empty — YOUR runtime DB only
+├── output/             ← Empty — YOUR generated media only
+│   ├── facebook_media/
+│   └── quizzes/
+├── .cache/             ← Empty — YOUR cache only
+└── config/             ← Empty — YOUR YAML config only
+```
+
+**No API keys, images, databases, or any data from other users is ever included.**
+
+---
+
+## 🔋 What's Inside
+
+| Capability | Details |
+|---|---|
+| **Trend Radar** | Google Trends · Google News RSS · Reddit Hot · YouTube Trending |
+| **Fact-Checking Lab** | Claim extraction · Web consensus scoring · Evidence citations |
+| **Script Forge** | Second-by-second scripts · B-roll cues · CTAs |
+| **SEO Matrix** | 4 A/B title variants · 200+ word descriptions · Tags & hashtags |
+| **Facebook Engine** | Feed posts · Stories · Reels · AI visuals · Live publishing |
+| **LLM Gateway** | Gemini → OmniRoute → OpenAI → OpenRouter (auto-fallback) |
+| **Autonomous Scheduler** | Runs every N minutes, hands-free 24/7 |
+| **Mission Control UI** | Dark glassmorphic dashboard at `localhost:8500` |
+
+---
+
+## 🔌 Optional: OmniRoute (Local AI Proxy)
+
+Pool multiple API keys and route them intelligently:
+
+```bash
+npm install -g omniroute
+omniroute
+```
+
+Then in `.env`:
+
+```env
+OMNIROUTE_BASE_URL=http://localhost:20128/v1
+OMNIROUTE_API_KEY=your-omniroute-key
+OMNIROUTE_MODEL=auto
+```
+
+---
+
+## 🛠️ Manual / Development Setup
+
+```bash
+git clone https://github.com/sayeeddesignerz-creator/Hyper-Motion.git
+cd Hyper-Motion
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/bin/activate     # macOS/Linux
+pip install -e ".[dev]"
+hypermotion init
+hypermotion start
+```
+
+Run tests:
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## ⚠️ Security
+
+- **Never commit `.env`** — it is excluded by `.gitignore`
+- All output (`data/`, `output/`) is local to your machine
+- Facebook tokens are stored only in your `.env` — not logged or transmitted anywhere except the Meta Graph API
+- Rotate any API key that was accidentally exposed
+
+---
+
+## 📄 License
+
+MIT © [sayeeddesignerz-creator](https://github.com/sayeeddesignerz-creator)

hypermotion-1.0.0/app/agents/__init__.py

@@ -0,0 +1,26 @@
+"""
+Agents package exports.
+"""
+from app.agents.base import BaseAgent
+from app.agents.trend_hunter import TrendHunterAgent
+from app.agents.fact_checker import FactCheckerAgent
+from app.agents.strategist import StrategistAgent
+from app.agents.script_forge import ScriptForgeAgent
+from app.agents.seo_optimizer import SEOOptimizerAgent
+from app.agents.audience_miner import AudienceMinerAgent
+from app.agents.learner import LearnerAgent
+from app.agents.facebook_growth_agent import FacebookGrowthAgent
+from app.agents.facebook_content_agent import FacebookContentAgent
+
+__all__ = [
+    "BaseAgent",
+    "TrendHunterAgent",
+    "FactCheckerAgent",
+    "StrategistAgent",
+    "ScriptForgeAgent",
+    "SEOOptimizerAgent",
+    "AudienceMinerAgent",
+    "LearnerAgent",
+    "FacebookGrowthAgent",
+    "FacebookContentAgent"
+]

hypermotion-1.0.0/app/agents/audience_miner.py

@@ -0,0 +1,63 @@
+"""
+Audience Miner Agent — mines viewer comments, extracts content ideas, and drafts high-engagement responses.
+"""
+from __future__ import annotations
+
+import uuid
+from typing import List, Dict, Any
+
+from app.agents.base import BaseAgent
+from app.models import AudienceInsight
+
+AUDIENCE_PROMPT = """You are an Audience Intelligence & Community Management Specialist.
+Topic / Video: {topic}
+Comments Sample:
+{comments_sample}
+
+Analyze the audience reaction:
+1. Overall sentiment ("positive", "skeptical", "inquisitive", "mixed")
+2. Extract top 3 new video/content ideas suggested by viewers
+3. Extract top 3 recurring viewer questions or confusions
+4. Draft 2 thoughtful, engaging creator replies that spark further conversation.
+
+Return JSON:
+{{
+  "sentiment": "mixed",
+  "extracted_ideas": ["Topic idea 1", "Topic idea 2", "Topic idea 3"],
+  "viewer_questions": ["Question 1?", "Question 2?", "Question 3?"],
+  "draft_replies": [
+    {{"comment": "Is this actually viable?", "reply": "Great question! While the early tests are promising..."}},
+    {{"comment": "Wait, did they test this on humans?", "reply": "Currently still in peer-reviewed trials, but..."}}
+  ]
+}}
+"""
+
+class AudienceMinerAgent(BaseAgent):
+    def __init__(self, gateway=None):
+        super().__init__("AudienceMiner", gateway)
+
+    async def analyze_community(self, topic: str, comments: List[str]) -> AudienceInsight:
+        self.logger.info(f"Mining audience insights for: '{topic}'")
+        sample_text = "\n".join([f"- {c}" for c in comments[:10]]) if comments else "- What happens next with this tech?\n- Is this actually real or just marketing hype?"
+
+        prompt = AUDIENCE_PROMPT.format(topic=topic, comments_sample=sample_text)
+        try:
+            res = await self.gateway.generate_json(prompt, system_instruction="You are an audience engagement expert.")
+            return AudienceInsight(
+                id=str(uuid.uuid4())[:8],
+                topic_or_video=topic,
+                sentiment=res.get("sentiment", "inquisitive"),
+                extracted_ideas=res.get("extracted_ideas", [f"Future implications of {topic}"]),
+                viewer_questions=res.get("viewer_questions", ["How soon will this be available?"]),
+                draft_replies=res.get("draft_replies", [])
+            )
+        except Exception as e:
+            self.logger.warning(f"Audience mining failed: {e}")
+            return AudienceInsight(
+                id=str(uuid.uuid4())[:8],
+                topic_or_video=topic,
+                sentiment="inquisitive",
+                extracted_ideas=[f"Part 2: Deep dive into {topic}"],
+                viewer_questions=["What is the real timeline?"],
+                draft_replies=[]
+            )

hypermotion-1.0.0/app/agents/base.py

@@ -0,0 +1,16 @@
+"""
+Base Agent class for Ultimate Content Agent.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+from app.llm.gateway import LLMGateway
+from app.config import get_settings
+
+class BaseAgent:
+    def __init__(self, name: str, gateway: Optional[LLMGateway] = None):
+        self.name = name
+        self.logger = logging.getLogger(f"Agent.{name}")
+        self.gateway = gateway or LLMGateway()
+        self.settings = get_settings()

hypermotion-1.0.0/app/agents/engagement_agent.py

@@ -0,0 +1,107 @@
+"""
+Engagement Agent — auto-replies to Facebook post comments and Messenger inbox messages.
+Uses the LLM Gateway to generate contextual, on-brand replies.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from app.agents.base import BaseAgent
+from app.llm.gateway import LLMGateway
+from app.config import get_settings
+
+logger = logging.getLogger("Agent.Engagement")
+
+REPLY_SYSTEM_PROMPT = """You are the social media manager for a Facebook Page.
+Your job is to craft short, warm, and engaging replies to comments and Messenger messages.
+
+Rules:
+- Keep replies under 3 sentences.
+- Sound human, conversational, and positive — never robotic.
+- If a comment is a question, answer it helpfully.
+- If it's praise, thank them genuinely and encourage engagement (follow, share, etc).
+- If it's criticism, respond calmly and professionally.
+- Match the language of the commenter (if they write in another language, reply in that language).
+- Never mention that you are an AI.
+- End with a soft CTA when relevant (e.g. "Stay tuned for more!" or "Drop your thoughts below 👇").
+
+Page context:
+- Page Name: {page_name}
+- Page Niche: {niche}
+- Tone: {tone}
+"""
+
+
+class EngagementAgent(BaseAgent):
+    def __init__(self, gateway: Optional[LLMGateway] = None):
+        super().__init__("Engagement", gateway)
+        self.settings = get_settings()
+
+    async def generate_comment_reply(
+        self,
+        comment_text: str,
+        post_context: str = "",
+        commenter_name: str = "there",
+    ) -> str:
+        """Generate an AI reply to a Facebook comment."""
+        channel = self.settings.channel
+        system = REPLY_SYSTEM_PROMPT.format(
+            page_name=channel.name,
+            niche=channel.niche,
+            tone=channel.tone.style,
+        )
+        user_prompt = (
+            f"Post context: {post_context[:200] if post_context else 'General page post'}\n"
+            f"Commenter ({commenter_name}) wrote: \"{comment_text}\"\n\n"
+            "Write a concise, friendly reply to this comment."
+        )
+        try:
+            reply = await self.gateway.generate_text(
+                prompt=user_prompt,
+                system_instruction=system,
+                temperature=0.7,
+                max_tokens=300,
+                agent_name="engagement",
+            )
+            logger.info(f"Generated comment reply for: {comment_text[:60]!r}")
+            raw_reply = reply.strip().strip('"')
+            # If the reply does not start with the commenter's name, prefix it so Facebook triggers a push notification
+            if commenter_name and commenter_name.lower() not in ("there", "someone", "unknown", ""):
+                if not raw_reply.lower().startswith(f"@{commenter_name.lower()}") and not raw_reply.lower().startswith(commenter_name.lower()):
+                    return f"@{commenter_name} {raw_reply}"
+            return raw_reply
+        except Exception as e:
+            logger.error(f"Failed to generate comment reply: {e}")
+            prefix = f"@{commenter_name} " if commenter_name and commenter_name.lower() not in ("there", "someone") else ""
+            return f"{prefix}Thanks for your comment! Keep practicing and stay tuned for more! 🚀"
+
+    async def generate_messenger_reply(
+        self,
+        message_text: str,
+        sender_name: str = "there",
+    ) -> str:
+        """Generate an AI reply to a Messenger inbox message."""
+        channel = self.settings.channel
+        system = REPLY_SYSTEM_PROMPT.format(
+            page_name=channel.name,
+            niche=channel.niche,
+            tone=channel.tone.style,
+        )
+        user_prompt = (
+            f"Messenger message from {sender_name}: \"{message_text}\"\n\n"
+            "Write a helpful, friendly reply to this message."
+        )
+        try:
+            reply = await self.gateway.generate_text(
+                prompt=user_prompt,
+                system_instruction=system,
+                temperature=0.7,
+                max_tokens=300,
+                agent_name="engagement",
+            )
+            logger.info(f"Generated Messenger reply for: {message_text[:60]!r}")
+            return reply.strip().strip('"')
+        except Exception as e:
+            logger.error(f"Failed to generate Messenger reply: {e}")
+            return f"Hi {sender_name}! Thanks for reaching out. We will get back to you shortly!"