feature: resolver trendingEntities — entidades NER em alta

docs/reference/schema.graphql

@@ -3,6 +3,19 @@ type Agency {
   label: String!
 }
 
+type AgencyPeriodMetrics {
+  period: String!
+  agencyKey: String!
+  agencyName: String
+  articleCount: Int!
+  avgSentimentScore: Float
+  pctPositive: Float
+  pctNegative: Float
+  avgReadabilityFlesch: Float
+  avgWordCount: Float
+  topThemes: [ThemeStats!]!
+}
+
 """Agency statistics with article count"""
 type AgencyStats {
   name: String!
@@ -115,6 +128,14 @@ enum ArticleSort {
   VIEWS
 }
 
+type ArticleSummary {
+  uniqueId: String!
+  title: String!
+  agencyName: String
+  publishedAt: String
+  trendingScore: Float
+}
+
 type ArticlesResult {
   articles: [Article!]!
   page: Int!
@@ -246,13 +267,31 @@ input DeliveryChannelsInput {
   webhook: Boolean! = false
 }
 
+type EntityCoveragePoint {
+  period: String!
+  agencyKey: String!
+  agencyName: String
+  articleCount: Int!
+  totalMentions: Int!
+  avgSentimentScore: Float
+}
+
 type EntityFacet {
   value: String!
   count: Int!
   entityId: String
   label: String
 }
 
+enum EntityKind {
+  ORG
+  PER
+  LOC
+  EVENT
+  POLICY
+  LAW
+}
+
 type EntityNetwork {
   nodes: [EntityNetworkNode!]!
   edges: [EntityNetworkEdge!]!
@@ -283,6 +322,19 @@ type EntityNode {
   agencyKey: String
 }
 
+type EntitySearchResult {
+  entityId: String!
+  canonicalName: String!
+  type: String!
+  description: String
+  wikidataUrl: String
+  agencyKey: String
+  aliases: [String!]!
+  articleCount: Int!
+  confidence: Float!
+  matchType: String!
+}
+
 type EntityType {
   text: String!
   type: String!
@@ -322,6 +374,12 @@ type FollowedListing {
   followedAt: DateTime
 }
 
+enum Granularity {
+  DAY
+  WEEK
+  MONTH
+}
+
 type IntegrityCandidateType {
   uniqueId: String!
   url: String!
@@ -373,6 +431,13 @@ type MarketplaceRecorte {
   keywords: [String!]!
 }
 
+enum MetricType {
+  VOLUME
+  SENTIMENT
+  READABILITY
+  THEMES
+}
+
 type Mutation {
   """Cria um novo clipping"""
   createClipping(input: ClippingInput!): Clipping!
@@ -521,6 +586,12 @@ type Query {
   """Daily article counts for the given date range"""
   articlesTimeline(range: DateRange!): [DailyCount!]!
 
+  """Métricas de publicação por agência e período"""
+  agencyAnalytics(agencies: [String!]!, dateFrom: String!, dateTo: String!, granularity: Granularity! = MONTH, metrics: [MetricType!] = null): [AgencyPeriodMetrics!]!
+
+  """Temas em crescimento comparando janela recente com baseline histórico"""
+  trendingThemes(windowDays: Int! = 7, baselineDays: Int! = 28, minArticles: Int! = 3, growthThreshold: Float! = 1.5, agencyKey: String = null, limit: Int! = 10): [TrendingThemeResult!]!
+
   """
   Lista todos os clippings do usuario autenticado (autorados + inscritos)
   """
@@ -624,6 +695,15 @@ type Query {
   Estima quantos artigos um recorte capturaria nas ultimas `sinceHours` horas. Replica `lib/estimate-recorte-count.ts`: filtro = themes OR-levels + agencies OR'd + published_at >= now-sinceHours; para keywords, conta por keyword (q em title,summary) e retorna o MAX; sem keywords, uma unica contagem. Substitui o mock `clippingEstimate`. PUBLICO.
   """
   estimateRecorteCount(themes: [String!]!, agencies: [String!]!, keywords: [String!]!, sinceHours: Int! = 24): Int!
+
+  """Série temporal de cobertura de uma entidade por agência"""
+  entityCoverage(entityId: String!, dateFrom: String = null, dateTo: String = null, granularity: Granularity! = MONTH): [EntityCoveragePoint!]!
+
+  """Busca fuzzy de entidades por nome ou alias"""
+  entitySearch(query: String!, entityType: EntityKind = null, limit: Int! = 5): [EntitySearchResult!]!
+
+  """Entidades NER com maior crescimento de cobertura (pré-computado)"""
+  trendingEntities(limit: Int! = 10): [TrendingEntityResult!]!
 }
 
 type Recorte {
@@ -716,6 +796,26 @@ type ThemeStats {
   count: Int!
 }
 
+type TrendingEntityResult {
+  entityId: String!
+  canonicalName: String!
+  type: String!
+  trendingScore: Float!
+  volumeRatio: Float!
+  windowCount: Int!
+  windowAgencies: Int!
+  computedAt: String
+}
+
+type TrendingThemeResult {
+  themeLabel: String!
+  themeCode: String
+  windowCount: Int!
+  baselineDailyAvg: Float!
+  growthScore: Float!
+  topArticles: [ArticleSummary!]!
+}
+
 type TypesenseDocRecordType {
   uniqueId: String!
   title: String!

docs/reference/schema.md

@@ -14,6 +14,19 @@ type Agency {
   label: String!
 }
 
+type AgencyPeriodMetrics {
+  period: String!
+  agencyKey: String!
+  agencyName: String
+  articleCount: Int!
+  avgSentimentScore: Float
+  pctPositive: Float
+  pctNegative: Float
+  avgReadabilityFlesch: Float
+  avgWordCount: Float
+  topThemes: [ThemeStats!]!
+}
+
 """Agency statistics with article count"""
 type AgencyStats {
   name: String!
@@ -126,6 +139,14 @@ enum ArticleSort {
   VIEWS
 }
 
+type ArticleSummary {
+  uniqueId: String!
+  title: String!
+  agencyName: String
+  publishedAt: String
+  trendingScore: Float
+}
+
 type ArticlesResult {
   articles: [Article!]!
   page: Int!
@@ -257,13 +278,31 @@ input DeliveryChannelsInput {
   webhook: Boolean! = false
 }
 
+type EntityCoveragePoint {
+  period: String!
+  agencyKey: String!
+  agencyName: String
+  articleCount: Int!
+  totalMentions: Int!
+  avgSentimentScore: Float
+}
+
 type EntityFacet {
   value: String!
   count: Int!
   entityId: String
   label: String
 }
 
+enum EntityKind {
+  ORG
+  PER
+  LOC
+  EVENT
+  POLICY
+  LAW
+}
+
 type EntityNetwork {
   nodes: [EntityNetworkNode!]!
   edges: [EntityNetworkEdge!]!
@@ -294,6 +333,19 @@ type EntityNode {
   agencyKey: String
 }
 
+type EntitySearchResult {
+  entityId: String!
+  canonicalName: String!
+  type: String!
+  description: String
+  wikidataUrl: String
+  agencyKey: String
+  aliases: [String!]!
+  articleCount: Int!
+  confidence: Float!
+  matchType: String!
+}
+
 type EntityType {
   text: String!
   type: String!
@@ -333,6 +385,12 @@ type FollowedListing {
   followedAt: DateTime
 }
 
+enum Granularity {
+  DAY
+  WEEK
+  MONTH
+}
+
 type IntegrityCandidateType {
   uniqueId: String!
   url: String!
@@ -384,6 +442,13 @@ type MarketplaceRecorte {
   keywords: [String!]!
 }
 
+enum MetricType {
+  VOLUME
+  SENTIMENT
+  READABILITY
+  THEMES
+}
+
 type Mutation {
   """Cria um novo clipping"""
   createClipping(input: ClippingInput!): Clipping!
@@ -532,6 +597,12 @@ type Query {
   """Daily article counts for the given date range"""
   articlesTimeline(range: DateRange!): [DailyCount!]!
 
+  """Métricas de publicação por agência e período"""
+  agencyAnalytics(agencies: [String!]!, dateFrom: String!, dateTo: String!, granularity: Granularity! = MONTH, metrics: [MetricType!] = null): [AgencyPeriodMetrics!]!
+
+  """Temas em crescimento comparando janela recente com baseline histórico"""
+  trendingThemes(windowDays: Int! = 7, baselineDays: Int! = 28, minArticles: Int! = 3, growthThreshold: Float! = 1.5, agencyKey: String = null, limit: Int! = 10): [TrendingThemeResult!]!
+
   """
   Lista todos os clippings do usuario autenticado (autorados + inscritos)
   """
@@ -635,6 +706,15 @@ type Query {
   Estima quantos artigos um recorte capturaria nas ultimas `sinceHours` horas. Replica `lib/estimate-recorte-count.ts`: filtro = themes OR-levels + agencies OR'd + published_at >= now-sinceHours; para keywords, conta por keyword (q em title,summary) e retorna o MAX; sem keywords, uma unica contagem. Substitui o mock `clippingEstimate`. PUBLICO.
   """
   estimateRecorteCount(themes: [String!]!, agencies: [String!]!, keywords: [String!]!, sinceHours: Int! = 24): Int!
+
+  """Série temporal de cobertura de uma entidade por agência"""
+  entityCoverage(entityId: String!, dateFrom: String = null, dateTo: String = null, granularity: Granularity! = MONTH): [EntityCoveragePoint!]!
+
+  """Busca fuzzy de entidades por nome ou alias"""
+  entitySearch(query: String!, entityType: EntityKind = null, limit: Int! = 5): [EntitySearchResult!]!
+
+  """Entidades NER com maior crescimento de cobertura (pré-computado)"""
+  trendingEntities(limit: Int! = 10): [TrendingEntityResult!]!
 }
 
 type Recorte {
@@ -727,6 +807,26 @@ type ThemeStats {
   count: Int!
 }
 
+type TrendingEntityResult {
+  entityId: String!
+  canonicalName: String!
+  type: String!
+  trendingScore: Float!
+  volumeRatio: Float!
+  windowCount: Int!
+  windowAgencies: Int!
+  computedAt: String
+}
+
+type TrendingThemeResult {
+  themeLabel: String!
+  themeCode: String
+  windowCount: Int!
+  baselineDailyAvg: Float!
+  growthScore: Float!
+  topArticles: [ArticleSummary!]!
+}
+
 type TypesenseDocRecordType {
   uniqueId: String!
   title: String!

src/graphql_api/datasources/postgres.py

@@ -409,6 +409,16 @@ class TypesenseDocRecord(NewsRecord):
 """
 
 
+_TRENDING_ENTITIES_SQL = """
+    SELECT entity_id, canonical_name, type,
+           trending_score, volume_ratio, window_count, window_agencies,
+           computed_at::text
+    FROM entity_trending_scores
+    ORDER BY trending_score DESC
+    LIMIT $1
+"""
+
+
 def _row_to_news_record(row: dict) -> NewsRecord:
     tags = row.get("tags") or []
     if isinstance(tags, str):
@@ -916,3 +926,9 @@ async def entity_search(
                     row["aliases"] = []
             results.append(row)
         return results
+
+    async def get_trending_entities(self, limit: int = 10) -> list[dict]:
+        """Retorna entidades NER com maior trending score (pré-computado pelo DAG)."""
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(_TRENDING_ENTITIES_SQL, limit)
+        return [dict(r) for r in rows]