> For the complete documentation index, see [llms.txt](https://oodlz-ai-studio.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oodlz-ai-studio.gitbook.io/docs/outbound-agents/awareness/1-topics.md).

# 1. Topics

Discovers, scores, and deduplicates \~200 candidate topics per month — competitor-validated, multi-market, balanced across categories, ready for approval.

> **A scored, deduplicated, multi-market content calendar — ready to approve, every month.**

Most AI tools take "give me blog topic ideas" and return 10 generic suggestions in 3 seconds. The Oodlz Topics producer runs a different problem entirely: discovers the brand's actual content competitors, queries real ranked keywords against live SEO data, generates a parallel set of emotional psychological topics, scores each candidate on a composite formula, deduplicates against the brand's full content history, and writes the prioritised calendar to Airtable for approval — every month, autonomously.

## What You Get

* A monthly content calendar of approximately 200 scored topics, ready for approval.
* Real ranked keywords behind every SEO-driven topic — not AI imagination.
* Multi-market discovery across USA, UK, Australia where applicable, with market-correct search volumes.
* 2 parallel topic engines — keyword-validated topics from competitors plus emotionally-driven topics from psychological seeds.
* Composite scoring (Appeal + Rankability + Volume) labelling each topic Hot, Warm, or Cold.
* Semantic deduplication against the brand's existing topic library so the same idea never reappears.
* Category-balanced calendar — no single topic type dominates the mix.

## How It Works

Each month the producer rediscovers the brand's content competitors via live web search, then queries DataForSEO for up to 500 real ranked keywords per competitor anchored to proven search demand. Smart TLD detection routes country-code domains (`.co.uk`, `.com.au`) to market-specific calls and generic domains to a global call — avoiding wasted API calls without losing data.

2 loops run in parallel. Loop 1 extracts competitor-validated keyword topics — what people are already searching for and competitors are already ranking on. Loop 2 generates psychologically-driven emotional topics — pain, aspiration, life moments, social comparison, fear, curiosity — at the second-order layer (the private shame, longing, or dread underneath the surface feeling), calibrated to the brand's specific audience portrait, not a generic consumer description.

Both loops feed the same pipeline. AI semantic clustering removes near-identical titles. A category-balance pass enforces a 20% cap per category. Composite scoring runs against 3 factors: Appeal (50%) + Rankability (30%) + Volume and Trend (20%). Each topic is labelled Hot, Warm, or Cold. Final candidates pass AI semantic deduplication against the brand's entire existing topic library before being written to the approval queue.

## Quality Baked In

* Real organic keyword difficulty from `ranked_keywords` — never AdWords advertiser-competition (the corrupting metric in most AI content tools).
* Smart TLD detection — country-code domains get market-specific queries, generic domains get a global query, no wasted calls.
* 20% category cap enforced before scoring — no single topic type can dominate the calendar.
* 3-factor composite scoring — Appeal weighted highest because volume without click-worthiness is wasted ink.
* AI semantic deduplication against the brand's full topic history — "How to save money on food" and "Ways to cut your grocery bill" are recognised as the same topic.
* Headlines compressed to a maximum of 10 words in Title Case for emotional topics — written to make readers feel seen, not informed.

## Inputs

* Brand profile fields — competitor seed list, audience portrait, market list, brand exclusions, prohibited language, content categories.
* Existing topic library in Airtable — read-only, used for semantic deduplication.
* DataForSEO and live web search credentials.

## Outputs

* New topic records written to the workspace as Pending Review, scored, market-tagged, category-balanced.
* Run log entry with discovery counts, dedup counts, write counts, and any failures.

## Cadence And Volume

Runs monthly on schedule (or on-demand from the workspace). Produces approximately 200 candidate topics per run — trimmed from a much larger raw discovery set. Per-run cost under $2.

## What This Replaces

* The senior content strategist who manually pulls competitor keywords, writes briefs, and curates a balanced calendar — a 2–3 day job, every month.
* The AI content tool that hallucinates 10 topics with no SEO data behind any of them.
* The keyword tool that returns 50,000 candidates with no relevance filtering, no brand alignment, no scoring.
* The content calendar that quietly degrades into the same 8 topics rewritten 12 different ways.

One producer, real data, scored against the right factors, deduped against history — every month, autonomously.

***

*This was built. No agent ships this out of the box.*