Metadata-Version: 2.4
Name: agentshub-ai
Version: 0.1.0
Summary: A collection of reusable AI agents for trend research, news analysis, and content intelligence. Each agent runs standalone (MCP server) or together through an orchestrator.
License-Expression: MIT
Project-URL: Homepage, https://github.com/ilarumk/agentshub
Project-URL: Issues, https://github.com/ilarumk/agentshub/issues
Keywords: agents,multi-agent,mcp,orchestration,bigquery,trends
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: google-cloud-bigquery>=3.0.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: mcp>=0.9.0
Requires-Dist: feedparser>=6.0.0
Provides-Extra: instagram
Requires-Dist: httpx>=0.27.0; extra == "instagram"
Provides-Extra: seo
Requires-Dist: google-api-python-client>=2.0.0; extra == "seo"
Provides-Extra: all
Requires-Dist: httpx>=0.27.0; extra == "all"
Requires-Dist: google-api-python-client>=2.0.0; extra == "all"

# agentshub

A collection of AI agents for trend research, news analysis, and content intelligence. Each agent can run standalone (as an MCP server) or together through an orchestrator that routes queries to the right agents automatically.

## Agents

| Agent | Data Source | What it does | Standalone MCP |
|---|---|---|---|
| `rising_search` | BigQuery Google Trends | Nationally rising + popular search terms across 210 US DMAs | `standalone/rising_search_mcp.py` |
| `news_trending` | Google News RSS | Trending articles by topic with full article body fetching | `standalone/news_trending_mcp.py` |
| `social_trends` | 10 marketing blogs | Trend extraction from Sprout Social, Hootsuite, Later, etc. Spawns sub-agent for structured extraction | `standalone/social_trends_mcp.py` |
| `wikipedia_spike` | Wikipedia Pageview API | Detects pageview spikes — leading indicator for cultural trends | `standalone/wikipedia_spike_mcp.py` |
| `youtube_shorts` | YouTube Data API | Trending videos by topic, filterable to shorts (<60s) | `standalone/youtube_shorts_mcp.py` |
| `instagram_trends` | Apify Instagram Scraper | Discovers viral Instagram content by topic — hashtags, hooks, engagement patterns | `standalone/instagram_trends_mcp.py` |
| `search_console` | Google Search Console API | Top queries, impressions, CTR, position. Identifies quick-win SEO opportunities | `standalone/search_console_mcp.py` |
| `bbc_news` | BigQuery BBC News | Searches BBC News articles by topic — titles, descriptions, body previews | `standalone/bbc_news_mcp.py` |
| `patent_search` | BigQuery Google Patents | Searches 90M+ patents by keyword — filings, assignees, velocity, countries | `standalone/patent_search_mcp.py` |
| `bigquery_analyst` | Any BigQuery public dataset | Runs SQL queries or inspects table schemas. SELECT only. | `standalone/bigquery_analyst_mcp.py` |
| `site_security` | Public HTTP requests | Scans websites for security issues — SSL, headers, WordPress vulns, exposed files. Grades A-F. | `standalone/site_security_mcp.py` |

### Example: site_security agent

```
> scan the security of example-shop.com

agents firing:
  → site_security(url='https://www.example-shop.com')
  [21:22:10] Scanning https://www.example-shop.com
  [21:22:11]   ✓ SSL valid, expires 2026-06-20 (68 days)
  [21:22:14] Checking security headers...
  [21:22:14]   0/7 headers present, 7 missing
  [21:22:14] Checking for WordPress...
  [21:22:16]   ⚠ EXPOSED: /wp-content/debug.log
  [21:22:20] Scan complete: 0 critical, 8 warnings, 1 info
  [21:22:20] Grade: C

Key findings:
  ✓ SSL valid (Let's Encrypt, 68 days remaining)
  ✓ HTTPS redirect working
  ✗ 7/7 security headers missing (HSTS, CSP, X-Frame-Options, etc.)
  ✗ Server header exposes software version
  ✗ /wp-content/debug.log publicly accessible
```

## Quick start

```bash
# Clone and setup
git clone https://github.com/yourusername/agentshub.git
cd agentshub
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Add your keys
cp .env.example .env
# Edit .env with your GOOGLE_CLOUD_PROJECT, OPENAI_API_KEY, etc.

# Run the interactive chat (supervisor routes to agents automatically)
python chat.py
```

## Three ways to use

### 1. Interactive chat — supervisor decides which agents to call
```bash
python chat.py

> what's trending in AI advertising this week?
# → fires rising_search + news_trending + social_trends automatically
```

### 2. Parallel demo — sequential vs parallel with timing
```bash
python demo.py
# → runs 3 agents sequential, then parallel, shows speedup
```

### 3. Standalone MCP — use one agent from Claude Code
```bash
# Register a single agent
claude mcp add rising-search python standalone/rising_search_mcp.py

# Or register all agents at once
claude mcp add agentshub python -m agentshub.mcp_server
```

## Architecture

```
User query
    │
    ▼
Orchestrator / Supervisor (GPT-4o-mini)
    │ reads query → decides which agents to call
    │
    ├─→ rising_search     [BigQuery — no LLM]
    ├─→ news_trending     [RSS + web fetch — no LLM]
    ├─→ social_trends     [10 blogs + sub-agent GPT-4o-mini]
    ├─→ wikipedia_spike   [Pageview API — no LLM]
    ├─→ youtube_shorts    [YouTube API — no LLM]
    ├─→ instagram_trends  [Apify — no LLM]
    ├─→ search_console    [GSC API — no LLM]
    ├─→ bbc_news          [BigQuery — no LLM]
    ├─→ patent_search     [BigQuery — no LLM]
    ├─→ bigquery_analyst  [BigQuery — any dataset, any SQL]
    └─→ site_security    [HTTP checks — no auth needed]
    │
    ▼
Synthesizer (GPT-4o-mini) → final response
```

## Adding a new agent

1. Create `agentshub/agents/your_agent.py` with a `run(**kwargs) -> dict` function
2. Add entry to `REGISTRY` in `agentshub/agents/__init__.py`
3. (Optional) Create `standalone/your_agent_mcp.py` for standalone use
4. The orchestrator, chat, and MCP server pick it up automatically

## Stack

- **Orchestration**: Custom fan-out/fan-in with ThreadPoolExecutor
- **Supervisor**: GPT-4o-mini via OpenAI function calling
- **Data agents**: BigQuery, Google News RSS, Wikipedia API, YouTube API
- **Sub-agent extraction**: GPT-4o-mini for structured trend extraction
- **MCP**: Model Context Protocol for standalone agent access
- **Web fetch**: Parallel article fetching with blocking/paywall handling

## Requirements

- Python 3.11+
- Google Cloud project with BigQuery access (for rising_search)
- OpenAI API key (for supervisor + social_trends sub-agent)
- YouTube API key (for youtube_shorts, optional)
- Apify API token (for instagram_trends, optional)
- Google Search Console access (for search_console, optional)
