Metadata-Version: 2.4
Name: trendsagi
Version: 0.16.0
Summary: Official TrendsAGI Python client: real-time trend intelligence for paid media targeting and timing, with AI agent tools, an MCP server, WebMCP support, and a Grok/Claude/Cursor plugin.
Author-email: TrendsAGI <contact@trendsagi.com>
License: MIT License
        
        Copyright (c) [2025] [TrendsAGI]
        
        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.
Project-URL: Homepage, https://trendsagi.com
Project-URL: Documentation, https://trendsagi.com/api-docs
Project-URL: Source, https://github.com/TrendsAGI/TrendsAGI
Project-URL: Bug Tracker, https://github.com/TrendsAGI/TrendsAGI/issues
Keywords: trends,trend detection,trending topics,social listening,real-time data,ai agents,mcp,model context protocol,llm tools,function calling,marketing,campaign optimization,paid media,ad targeting,api client,grok,grok plugin,chatgpt connector,claude plugin,webmcp,browser agents
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: pydantic>=2.0
Requires-Dist: websockets>=10.0
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.2; python_version >= "3.10" and extra == "mcp"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Dynamic: license-file

# TrendsAGI

[![PyPI Version](https://img.shields.io/pypi/v/trendsagi.svg)](https://pypi.org/project/trendsagi/)
[![Python Versions](https://img.shields.io/pypi/pyversions/trendsagi.svg)](https://pypi.org/project/trendsagi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Real-time trend intelligence for your code and your AI agents: what is trending on social platforms right now, with measured volume, velocity and growth, AI insights on why each topic is moving, evidence-backed recommendations, crisis alerts and watchlists. Paid media and growth teams use it to target what is rising, time spend to the trend curve and brief creative on measured demand.

| | |
| --- | --- |
| **Python client** | `TrendsAGIClient`, a typed REST client |
| **Agent tools** | `TrendsAGITools` for OpenAI, Claude, LangChain and WebMCP |
| **Hosted MCP server** | `https://api.trendsagi.com/mcp` for Claude, ChatGPT, Grok, Cursor and Gemini CLI |
| **Browser agents (WebMCP)** | Signed in to app.trendsagi.com, your browser's agent gets the same tools ([`webmcp/`](webmcp/)) |
| **Local MCP server** | `trendsagi mcp`, the same tools over stdio |
| **Plugins** | Claude, Grok and Cursor plugin in [`plugins/trendsagi`](plugins/trendsagi), Gemini CLI extension at the repo root |
| **Ad execution** | Executors that preview, then apply, Google, Meta, TikTok and LinkedIn ad changes from your own infrastructure |

## Install

```bash
pip install trendsagi            # client + agent tools
pip install "trendsagi[mcp]"     # adds the local MCP server (Python 3.10+)
```

Create an API key under Profile > API Keys at [app.trendsagi.com](https://app.trendsagi.com) and export it:

```bash
export TRENDSAGI_API_KEY="your_api_key"
```

## Quickstart

```python
import os
from trendsagi import TrendsAGIClient

client = TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"])

# Fastest-moving Technology topics right now
trends = client.get_trends(category="Technology", sort_by="velocity", limit=5)
for trend in trends.trends:
    print(trend.id, trend.name, trend.volume)

# Why is the top one moving?
insight = client.get_ai_insights(trends.trends[0].id)
if insight:
    print(insight.sentiment_summary, insight.key_themes)
```

## Use TrendsAGI in your AI assistant (no install)

Add the hosted MCP server, sign in to TrendsAGI and approve the connection:

| Assistant | Setup |
| --- | --- |
| Claude | Open [TrendsAGI in the Claude directory](https://claude.ai/directory/trendsagi), or Settings > Connectors > Add custom connector with the URL below |
| Claude Code | `claude mcp add --transport http trendsagi https://api.trendsagi.com/mcp`, or `/plugin marketplace add TrendsAGI/TrendsAGI` then `/plugin install trendsagi@trendsagi` |
| ChatGPT | Add a custom connector with the URL below |
| Grok | Install the TrendsAGI plugin, or add the URL as a remote MCP server |
| Cursor | `{ "mcpServers": { "trendsagi": { "url": "https://api.trendsagi.com/mcp" } } }` |
| Gemini CLI | `gemini extensions install https://github.com/TrendsAGI/TrendsAGI` |

```text
https://api.trendsagi.com/mcp
```

Then ask *"What is accelerating fastest in Technology this week, and who should I target with it?"* The hosted tools are read-only, and each call counts as one API request. Each connection gets its own key, listed as "AI connector: <assistant>" under Profile > API Keys; delete it to disconnect. Clients without OAuth can send an API key as `Authorization: Bearer <key>`. Guide: [trendsagi.com/mcp](https://trendsagi.com/mcp).

## Use TrendsAGI from your browser's agent (WebMCP)

[WebMCP](https://webmachinelearning.github.io/webmcp/) lets a web page hand tools to the AI agent built into the browser (Chrome and Edge in origin trials, ChatGPT desktop, Brave Leo). While you are signed in to [app.trendsagi.com](https://app.trendsagi.com), the app registers TrendsAGI's read-only tools with `document.modelContext`, so the agent uses them with your session: no connector or API key, and calls count as app use rather than API usage. trendsagi.com offers public tools (docs search, trend reports, plans and the free calculators) to every visitor.

To put TrendsAGI tools on **your own** site, register them in your page and run them on your server, which keeps the API key:

```python
tools = TrendsAGITools(TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"]))

tools.webmcp()                     # serve to your page: name, description, inputSchema, annotations
tools.call("list_trends", args)    # run the call your page forwards
```

[`webmcp/`](webmcp/) has the browser module and a FastAPI server. Guide: [trendsagi.com/webmcp](https://trendsagi.com/webmcp).

## Agent tools

One registry, every format. The tools are **read-only by default**; `add_to_watchlist` and `update_recommendation` appear only with `allow_writes=True` (or `trendsagi mcp --allow-writes`).

| Tool | What the agent gets |
| --- | --- |
| `list_trends` | Trending topics by category or phrase, sorted by velocity, growth or volume |
| `list_trend_categories` | Valid category names |
| `search_trend_insights` | Trends and insights matching a theme |
| `get_trend` / `get_trend_analytics` | One trend and its volume time series |
| `get_trend_ai_insights` | Summary, key themes, sentiment, audience, marketing angles |
| `list_recommendations` | Evidence-backed actions with a decision brief |
| `list_crisis_events` | Reputation and crisis events for monitored topics |
| `list_watchlist` / `get_api_usage` | Watched topics and remaining daily quota |
| `read_data_schema` / `execute_sql` | Read-only SQL for questions that need filters, joins or aggregation |
| `find_capability` | Whether TrendsAGI can do a task, and which tool or app page does it |

### OpenAI

```python
import json, os
from openai import OpenAI
from trendsagi import TrendsAGIClient, TrendsAGITools

tools = TrendsAGITools(TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"]))
openai = OpenAI()
messages = [{"role": "user", "content": "Find a fast-rising Technology trend and suggest a campaign angle."}]

while True:
    reply = openai.chat.completions.create(model="gpt-5-mini", messages=messages, tools=tools.openai())
    message = reply.choices[0].message
    messages.append(message)
    if not message.tool_calls:
        print(message.content)
        break
    for call in message.tool_calls:
        result = tools.call(call.function.name, call.function.arguments)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
```

### Claude, LangChain and others

```python
tools.anthropic()         # Anthropic Messages API tools=
tools.openai_responses()  # OpenAI Responses API tools=
tools.langchain()         # LangChain StructuredTools (pip install "trendsagi[langchain]")
tools.webmcp()            # WebMCP descriptors for document.modelContext.registerTool
```

With Claude, pass `tools=tools.anthropic()` and answer each `tool_use` block with `{"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(tools.call(block.name, block.input))}`. `tools.call` never raises: errors come back as `{"error": ...}` so the model can read a rate limit or a bad argument and recover.

### Local MCP server

```bash
pip install "trendsagi[mcp]"
claude mcp add trendsagi --env TRENDSAGI_API_KEY=your_api_key -- trendsagi mcp
```

Or in any MCP client's JSON config (Claude Desktop, Cursor, VS Code):

```json
{ "mcpServers": { "trendsagi": { "command": "trendsagi-mcp", "env": { "TRENDSAGI_API_KEY": "your_api_key" } } } }
```

## Query with SQL

For answers no single endpoint returns, such as growth by category or the trends that match a watchlist:

```python
schema = client.get_data_schema()   # tables, columns, rules, examples
result = client.execute_sql(
    """
    SELECT category, count(*) AS trends, round(avg(growth_pct)::numeric, 1) AS avg_growth_pct
    FROM trends
    WHERE last_seen_at > now() - interval '7 days' AND growth_pct IS NOT NULL
    GROUP BY category ORDER BY avg_growth_pct DESC
    """,
    max_rows=20,
)
print(result["columns"], result["rows"])
```

Tables: `trends`, `trend_snapshots` (90 days of readings), `trend_categories`, `trend_insights`, `watchlist`, `recommendations` and `crisis_events`; the last three only contain your own account's rows. Queries are one validated `SELECT`, run read-only for at most 5 seconds, and count as one API request. A refused query raises `exceptions.QueryError` with a `code` (such as `unknown_table` or `timeout`), plus `hint` and `position` when known.

## Recommendations with decision briefs

```python
recommendations = client.get_recommendations(match_user_interests=True, priority="high", sort="priority", limit=10)
for rec in recommendations.recommendations:
    brief = rec.decision_brief
    if brief and brief.actionable:
        print(rec.title, brief.why_now, brief.next_steps[:1])
```

Each brief explains why an action is timely, the measured signals behind it and concrete next steps. Its confidence score measures evidence completeness, not the chance of success; use `actionable` and `data_quality` to hold back when signals are stale or incomplete.

## Ad execution in your own infrastructure

`GoogleAdsExecutor`, `MetaAdsExecutor`, `TikTokAdsExecutor` and `LinkedInAdsExecutor` take credentials at runtime, use deterministic idempotency keys, and support dry-run previews and strict validation:

```python
from trendsagi.integrations import GoogleAdsExecutor

insight = client.get_ai_insights(trend_id)  # the trend you decided to act on
google = GoogleAdsExecutor({
    "access_token": os.environ["GOOGLE_ADS_ACCESS_TOKEN"],
    "developer_token": os.environ["GOOGLE_ADS_DEVELOPER_TOKEN"],
})
preview = google.apply_targeting(insight, customer_id="1234567890", campaign_id="9876543210", dry_run=True, strict_mode=True)
print(preview.response)  # inspect before any real change
```

See [`INTEGRATIONS_BYOC.md`](INTEGRATIONS_BYOC.md) for every executor.

## Errors

```python
from trendsagi import exceptions

try:
    client.get_trends(limit=5)
except exceptions.RateLimitError:
    ...  # back off and retry
except exceptions.AuthenticationError:
    ...  # invalid or revoked key
```

## CLI

```bash
trendsagi mcp [--allow-writes]                          # MCP server over stdio
trendsagi scaffold --type docker --output ./runner      # executor runner template
trendsagi scaffold --type terraform --output ./infra    # infrastructure template
```

## Plans and limits

The free Developer plan includes one API key and 100 API calls a day; Advantage, Scale and Enterprise raise the daily limit and add keys and team features. Calls above the daily allowance are billed as overage. See [pricing](https://trendsagi.com/subscription).

## Links

- [API documentation](https://trendsagi.com/api-docs) and [endpoint reference](https://trendsagi.com/api-docs/reference)
- [MCP server guide](https://trendsagi.com/mcp) and [WebMCP guide](https://trendsagi.com/webmcp)
- [Changelog](CHANGELOG.md)
- Support: [trendsagi.com/contact](https://trendsagi.com/contact) or contact@trendsagi.com

## License

MIT. See [LICENSE](LICENSE).
