TrendsAGI Python SDK

Official Python access to TrendsAGI paid-media intelligence and operational resilience.

Install:

python -m pip install --upgrade trendsagi

Python 3.8+ is supported. Configure TRENDSAGI_API_KEY with your own TrendsAGI API key. A PyPI publishing token is not a TrendsAGI API key.

Paid media: inspect an actual trend

import os
from trendsagi import TrendsAGIClient

client = TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"], timeout=20)
trends = client.get_trends(limit=5)
if not trends.trends:
    print("No trends available in this window.")
else:
    trend = next((item for item in trends.trends if item.id is not None), None)
    if trend is not None:
        insight = client.get_ai_insights(trend.id)
        print(insight if insight else "No cached insight yet.")

This example reads cached data. Insight generation is a separate queued operation subject to your entitlement and usage limits. Recommendation scores using evidence_completeness_v1 measure available evidence, not campaign uplift or event probability.

Google, Meta, TikTok and LinkedIn executors remain BYOC: credentials stay in your runtime. Start with dry_run=True and strict_mode=True. Inspect the preview before explicitly executing a change. See the integration guide for required account identifiers and provider permissions.

Resilience — Beta

The resilience methods require the existing crisis-functionality entitlement. An API key does not bypass subscription access, ownership checks or usage accounting.

import os
from pathlib import Path
from trendsagi import TrendsAGIClient

client = TrendsAGIClient(os.environ["TRENDSAGI_API_KEY"], timeout=20)
events = client.get_crisis_events(status="all", time_range="7d")
if not events.events:
    print("No matching events. Review your location and keyword interests.")
else:
    event = client.get_crisis_evidence(events.events[0].id)
    print(event.title, event.freshness, event.review_status)
    for source in event.source_refs:
        print(source.source_id, source.observed_at, source.source_url)
    for limitation in event.limitations:
        print("Limitation:", limitation)
    Path("evidence.html").write_text(
        client.export_crisis_event(event.id, format="html"), encoding="utf-8"
    )

HTML exports are dated, self-contained evidence snapshots. They work offline but do not perform offline AI inference or update offline.

To opt into official-source matching, set a location using set_resilience_location("Nottinghamshire") and maintain an active keyword interest such as flood. Both must match. An empty location disables matching. Inspect get_resilience_sources() for availability and coverage.

After reviewing evidence, append a human assessment explicitly:

reviewed = client.review_crisis_event(
    event.id,
    assessment="unconfirmed",
    rationale="The source reports an event; impact on our operation is not established.",
    evidence_version=event.evidence_version,
)

Assessments are unconfirmed, supported or disputed. A changed evidence version returns HTTP 409; refresh before reviewing again. Reviews preserve history and are separate from acknowledge/archive/reopen actions.

Official sources initially cover Environment Agency flood warnings in England and USGS global magnitude 4.5+ earthquakes. Social signals and heuristic severity do not establish an incident. One publisher is not independent corroboration.

Errors and compatibility

from trendsagi import exceptions

try:
    sources = client.get_resilience_sources()
except exceptions.AuthorizationError:
    print("This account lacks the necessary entitlement.")
except exceptions.ConflictError:
    print("Refresh the evidence before recording a review.")
except exceptions.RateLimitError:
    print("Respect the usage limit and retry later.")
except exceptions.CapabilityUnavailableError:
    print("This capability is unavailable; do not poll indefinitely.")
except exceptions.TrendsAGIError as error:
    print(type(error).__name__)

The default HTTP timeout is 20 seconds and is configurable. Rate-limit retries are opt-in and bounded. New event fields are optional; legacy responses without evidence remain readable. CapabilityUnavailableError retains compatibility with MaintenanceError, and authorization errors remain APIError subclasses.

The legacy financial-data method remains for compatibility but its backend capability is unavailable. It is not an active product feature.

JavaScript / TypeScript

Use standard HTTPS with X-API-Key; there is no maintained npm SDK represented by this release. Tested examples are in examples/resilience.mjs. Never ship account API keys in public browser code.

Deployment and data

This SDK does not establish UK-only hosting, security certification, defence accreditation or permission to redistribute source content. Consult the current privacy, security, and source licensing information. Preserve tenant isolation and source restrictions when exporting.

Development

python -m unittest discover -s tests -v
python -m build
python -m twine check dist/*

See CHANGELOG.md for release changes. Supported API methods and known unavailable capabilities are recorded in the contract audit.

Release files for trendsagi 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trendsagi 0.10.0
File	Size	Uploaded
trendsagi-0.10.0.tar.gz	38.1 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for trendsagi 0.10.0
File	Interpreter	ABI	Platform	Reset
trendsagi-0.10.0-py3-none-any.whl 34.6 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 72.7 kB

Release files / trendsagi-0.10.0.tar.gz

Download URL	trendsagi-0.10.0.tar.gz
Size	38.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`080aef4661fd63a33572260c76305c91b25993659ee12c954f8ef6e8bfdfa3b8`
BLAKE2b-256 checksum How to use checksums	`b555c3c2fe8af61477dbd5129ad40218cfa4f40d1b3b57ed84367ce55f7983d2`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.6`

Release files / trendsagi-0.10.0-py3-none-any.whl

Download URL	trendsagi-0.10.0-py3-none-any.whl
Size	34.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cc57d318568221c685609ab0b0b3a8ae7daaaca526ba414f747c28418937d4d1`
BLAKE2b-256 checksum How to use checksums	`4e26e9656ea1258376cb84367aeac17d3a2c3ddff5b82e2c1f2b85887f34efab`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.6`