Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
6de0869
test: entityNetwork ego-centrado e estatísticas do grafo nos nós/ares…
nitaibezerra Oct 21, 2026
946accc
feature: entityNetwork ego-centrado com articleCount/uniqueContentCou…
nitaibezerra Oct 21, 2026
293c934
test: relatedEntities com orderBy/minWeight/lift, stats no entity(id)…
nitaibezerra Oct 21, 2026
0740f16
feature: relatedEntities com orderBy/minWeight/lift, stats no entity(…
nitaibezerra Oct 21, 2026
5d91ef9
test: entityCoverage com dias UTC, dateFrom inclusivo e dateTo exclus…
nitaibezerra Oct 21, 2026
5c4463b
fix: entityCoverage com dias UTC, dateFrom inclusivo e dateTo exclusi…
nitaibezerra Oct 21, 2026
a1507b0
test: entityCoverage.uniqueContentCount credita cada conteúdo à prime…
nitaibezerra Oct 21, 2026
85cebd3
feature: entityCoverage.uniqueContentCount credita cada conteúdo à pr…
nitaibezerra Oct 21, 2026
81ee8c1
test: trendingThemes.topArticles com url e agencyKey (red)
nitaibezerra Oct 21, 2026
956c6c2
feature: ArticleSummary com url e agencyKey (green)
nitaibezerra Oct 21, 2026
c3b7ff8
test: Flesch pt-BR no ArticleFeatures e no agencyAnalytics (red)
nitaibezerra Oct 21, 2026
31fc767
feature: Flesch pt-BR no ArticleFeatures e no agencyAnalytics (green)
nitaibezerra Oct 21, 2026
3afb25d
docs: grafo de entidades, entityCoverage com dateTo exclusivo e depen…
nitaibezerra Oct 21, 2026
0c04368
test: ego-network não duplica nó nem aresta com par invertido em enti…
nitaibezerra Oct 21, 2026
2b5b590
fix: ego-network deduplica nós por id e arestas por par não-ordenado …
nitaibezerra Oct 21, 2026
664ef3b
refactor: entityCoverage agrega com COUNT(*) e junta news_features an…
nitaibezerra Oct 21, 2026
eb115f5
test: chave de dedup do entityCoverage isolada numa constante (red)
nitaibezerra Oct 21, 2026
dac7a38
refactor: chave de dedup do entityCoverage em _CONTENT_DEDUP_KEY_SQL …
nitaibezerra Oct 21, 2026
e249cc0
test: relatedEntities com minWeight padrão 1, retrocompatível com o p…
nitaibezerra Oct 21, 2026
dfef051
fix: relatedEntities com minWeight padrão 1, retrocompatível com o po…
nitaibezerra Oct 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion docs/datasources.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ são instanciados no `lifespan` (startup) a partir de env vars e injetados no

| Datasource | Backend | Lib | Modelo | Usado por |
|-----------|---------|-----|--------|-----------|
| `PostgresDatasource` | PostgreSQL `govbrnews` | `asyncpg` (pool) | **async** | themes, agencies, news (internal), `agencyAnalytics`, `articlesTimeline`, entidades (`entityCoverage`, `trendingEntities`) |
| `PostgresDatasource` | PostgreSQL `govbrnews` | `asyncpg` (pool) | **async** | themes, agencies, news (internal), `agencyAnalytics`, `articlesTimeline`, entidades (`entity`, `entityCoverage`, `trendingEntities`, `relatedEntities`, `entityNetwork`, `entityGraphStats`) |
| `TypesenseDatasource` | Typesense | `typesense` | **sync** | articles, search, facets |
| `TypesenseAdminDatasource` | Typesense | `typesense` | **sync** | writes (indexação, internal) |
| `FirestoreDatasource` | Firestore | `firebase-admin` | **sync** (wrapped) | clippings, subscriptions, marketplace, users |
Expand All @@ -17,6 +17,16 @@ são instanciados no `lifespan` (startup) a partir de env vars e injetados no
`async` onde a lib é síncrona. Datasource ausente no startup vira
`app.state.<ds> = None` (warning), e o resolver dependente falha em runtime.

!!! warning "Grafo de entidades depende da migração 032 do data-platform"
`entity`, `relatedEntities` e `entityNetwork` fazem LEFT JOIN em
`entity_stats` e leem `entity_edges.unique_content_count`;
`relatedEntities` e `entityGraphStats` leem `entity_graph_meta`. As três
estruturas vêm da migração 032 do data-platform: sem ela essas queries
falham (tabela/coluna inexistente). Com a migração aplicada mas antes da
primeira execução da DAG do grafo, os campos novos (`articleCount`,
`uniqueContentCount`, `uniqueContentWeight`, `lift`) ficam nulos e
`entityGraphStats` é `null`.

## Injeção por request

`get_context(request)` lê os datasources de `request.app.state` (populados pelo
Expand Down
40 changes: 40 additions & 0 deletions docs/exemplos.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,35 @@ forma mais rápida de explorar a API.
`days` é limitado a 366. Os outros painéis usam facets do Typesense e
refletem o atraso de indexação dele.

=== "Entidades"

```graphql
query Entidade($id: String!) {
entity(id: $id) { canonicalName type articleCount uniqueContentCount }
# vizinhos com associação acima do acaso (lift), sem co-menções únicas
relatedEntities(id: $id, limit: 12, orderBy: LIFT, minWeight: 2) {
canonicalId canonicalName weight uniqueContentWeight lift
}
# rede centrada: a entidade + 30 vizinhos mais fortes, com todas as arestas dela
entityNetwork(id: $id, egoCentered: true, maxNodes: 30, limit: 50) {
nodes { entityId canonicalName articleCount }
edges { src dst weight uniqueContentWeight }
}
# semana de 01/10 a 07/10 inteira: dateTo é exclusivo
entityCoverage(entityId: $id, dateFrom: "2026-10-01", dateTo: "2026-10-08", granularity: DAY) {
period agencyKey articleCount uniqueContentCount
}
entityGraphStats { totalArticles totalUniqueContent computedAt }
}
```

!!! note "Contagens de artigos × de conteúdo"
`articleCount`/`weight` contam artigos; uma nota republicada por N
órgãos conta N vezes. `uniqueContentCount`/`uniqueContentWeight` contam
conteúdos distintos (`content_hash`). No `entityCoverage`, cada
conteúdo é creditado só ao primeiro órgão que o publicou no intervalo,
então `uniqueContentCount` pode ser somado entre órgãos e períodos.

## Queries e mutations autenticadas

Exigem `Authorization: Bearer <JWT do Keycloak>`.
Expand Down Expand Up @@ -285,3 +314,14 @@ mutation Features($id: String!, $f: JSON!) { upsertFeatures(uniqueId: $id, featu
- **`cloneMarketplaceListing` retorna `Clipping!`** (precisa de selection set,
ex.: `{ id name }`) — era `Boolean!` antes de um gap-fix pré-rollout.
- **`clippings`** (não `myClippings`) é a query de listagem do usuário.
- **`entityCoverage` usa dias UTC com `dateTo` exclusivo.** Para incluir o
dia D inteiro, mande `dateTo = D + 1`. `period` vem como
`"AAAA-MM-DD 00:00:00+00"` (início do período em UTC).
- **`entityNetwork` sem `egoCentered` é a rede legada** (CTE recursiva, corte
de arestas pelo peso global): as arestas entre vizinhos podem expulsar as
da própria entidade. Para uma rede centrada, use `egoCentered: true`.
- **`relatedEntities` inclui co-menções únicas por padrão** (`minWeight: 1`,
a lista de sempre); `minWeight: 2` corta esse ruído. Já `entityNetwork`
com `egoCentered: true` usa sempre weight ≥ 2.
- **`ArticleSummary.agencyName` carrega a key** da agência (igual a
`agencyKey`), não o nome.
118 changes: 113 additions & 5 deletions docs/reference/schema.graphql
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,23 @@ type AgencyPeriodMetrics {
Fração (0 a 1) dos artigos COM rótulo de sentimento que são negativos. Null se nenhum tem.
"""
pctNegative: Float

"""
Média do Flesch pela fórmula inglesa (legado; escala distorcida para português).
"""
avgReadabilityFlesch: Float
avgWordCount: Float
topThemes: [ThemeStats!]!

"""
Média do Flesch adaptado ao português (Martins et al., 1996) dos artigos que o têm. Null quando nenhum tem.
"""
avgReadabilityFleschPtbr: Float

"""
Nº de artigos do grupo com Flesch pt-BR calculado (base de avgReadabilityFleschPtbr).
"""
readabilityFleschPtbrCount: Int
}

"""Agency statistics with article count"""
Expand Down Expand Up @@ -123,7 +137,16 @@ type ArticleFeatures {
uniqueSessions: Int
trendingScore: Float
wordCount: Int

"""
Índice de Flesch pela fórmula inglesa (legado; escala distorcida para português).
"""
readabilityFlesch: Float

"""
Índice de Flesch adaptado ao português (Martins et al., 1996): 0–100, maior = mais fácil. Null até o artigo ser recalculado.
"""
readabilityFleschPtbr: Float
}

input ArticleFilter {
Expand All @@ -149,9 +172,19 @@ enum ArticleSort {
type ArticleSummary {
uniqueId: String!
title: String!

"""
Key da agência (o mesmo valor de agencyKey, apesar do nome). Mantido por compatibilidade.
"""
agencyName: String
publishedAt: String
trendingScore: Float

"""Link do artigo no portal de origem."""
url: String

"""Key da agência (ex.: 'saude')."""
agencyKey: String
}

type ArticlesResult {
Expand Down Expand Up @@ -292,6 +325,11 @@ type EntityCoveragePoint {
articleCount: Int!
totalMentions: Int!
avgSentimentScore: Float

"""
Conteúdos distintos (content_hash) creditados a esta agência: cada conteúdo conta só para a primeira agência que o publicou no intervalo consultado, então o campo soma entre agências e períodos sem contar republicações. articleCount conta artigos.
"""
uniqueContentCount: Int!
}

type EntityFacet {
Expand All @@ -301,6 +339,15 @@ type EntityFacet {
label: String
}

"""
Totais do grafo de entidades (entity_graph_meta), recalculados pela DAG do grafo; N do lift de `relatedEntities`.
"""
type EntityGraphStats {
totalArticles: Int!
totalUniqueContent: Int!
computedAt: DateTime
}

enum EntityKind {
ORG
PER
Expand All @@ -320,13 +367,28 @@ type EntityNetworkEdge {
dst: String!
weight: Int!
kind: String!

"""
Co-menções com conteúdo distinto: republicações (mesmo content_hash) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
"""
uniqueContentWeight: Int
}

type EntityNetworkNode {
entityId: String!
canonicalName: String
type: String
wikidataId: String

"""
Artigos que mencionam a entidade (entity_stats). Null sem estatística calculada.
"""
articleCount: Int

"""
Conteúdos distintos que mencionam a entidade: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int
}

type EntityNode {
Expand All @@ -338,6 +400,16 @@ type EntityNode {
wikidataUrl: String
description: String
agencyKey: String

"""
Artigos que mencionam a entidade (entity_stats). Null sem estatística calculada.
"""
articleCount: Int

"""
Conteúdos distintos que mencionam a entidade: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int
}

type EntitySearchResult {
Expand Down Expand Up @@ -713,14 +785,19 @@ type Query {
entity(id: String!): EntityNode

"""
Entidades relacionadas a `id` (entity_id) por co-menção (Fase 6c). Lê a rede de co-menção materializada (`entity_edges`, 1-hop), retorna os vizinhos hidratados do entity_registry, ordenados por `weight` (nº de artigos em co-menção) desc, até `limit`. Retorna [] sem Postgres ou sem vizinhos. PÚBLICO.
Entidades relacionadas a `id` (entity_id) por co-menção (Fase 6c). Lê a rede de co-menção materializada (`entity_edges`, 1-hop), retorna os vizinhos hidratados do entity_registry com weight >= `minWeight` (default 1 = todos; 2 descarta co-menções únicas), ordenados por `orderBy` (default WEIGHT = nº de artigos em co-menção) desc, até `limit`. Retorna [] sem Postgres ou sem vizinhos. PÚBLICO.
"""
relatedEntities(id: String!, limit: Int! = 12, orderBy: RelatedEntityOrder! = WEIGHT, minWeight: Int! = 1): [RelatedEntity!]!

"""
Totais do grafo de entidades (entity_graph_meta): artigos e conteúdos distintos considerados e quando foram calculados. Null sem Postgres ou antes da primeira execução da DAG do grafo. PÚBLICO.
"""
relatedEntities(id: String!, limit: Int! = 12): [RelatedEntity!]!
entityGraphStats: EntityGraphStats

"""
Ego-network (nós + arestas) ao redor de `id` (entity_id) para a visualização de rede (Fase 6c). Travessia não-direcionada na rede de co-menção (`entity_edges`) via CTE recursiva até `depth` saltos (CLAMPado a no máx 2; profundidades maiores ficam para o Neo4j futuro). `limit` limita o nº de arestas (cap de tamanho do grafo). Retorna {nodes:[], edges:[]} sem Postgres. PÚBLICO.
Ego-network (nós + arestas) ao redor de `id` (entity_id) para a visualização de rede (Fase 6c). Modo legado (default): travessia não-direcionada na rede de co-menção (`entity_edges`) via CTE recursiva até `depth` saltos (CLAMPado a no máx 2; profundidades maiores ficam para o Neo4j futuro); `limit` limita o nº de arestas (cap de tamanho do grafo). `egoCentered: true`: a entidade + seus `maxNodes` (1–100) vizinhos mais fortes (weight >= 2), com TODAS as arestas da entidade; `limit` (1–500) corta só as arestas entre vizinhos (`includeNeighborEdges`); `depth` é ignorado. Retorna {nodes:[], edges:[]} sem Postgres. PÚBLICO.
"""
entityNetwork(id: String!, depth: Int! = 1, limit: Int! = 50): EntityNetwork!
entityNetwork(id: String!, depth: Int! = 1, limit: Int! = 50, egoCentered: Boolean! = false, maxNodes: Int! = 30, includeNeighborEdges: Boolean! = true): EntityNetwork!

"""
Contagem de artigos por code de tema (nivel `level`) nos ultimos `days` dias. `label` e None (o portal mapeia pela config). PUBLICO.
Expand All @@ -737,7 +814,9 @@ type Query {
"""
estimateRecorteCount(themes: [String!]!, agencies: [String!]!, keywords: [String!]!, sinceHours: Int! = 24): Int!

"""Série temporal de cobertura de uma entidade por agência"""
"""
Série temporal de cobertura de uma entidade por agência. `dateFrom`/`dateTo` (AAAA-MM-DD, opcionais) em dias UTC; dateFrom inclusivo, dateTo exclusivo: para incluir o dia D inteiro, passe dateTo = D + 1. `period` é o início do período em UTC ("AAAA-MM-DD 00:00:00+00").
"""
entityCoverage(entityId: String!, dateFrom: String = null, dateTo: String = null, granularity: Granularity! = MONTH): [EntityCoveragePoint!]!

"""Busca fuzzy de entidades por nome ou alias"""
Expand Down Expand Up @@ -782,6 +861,35 @@ type RelatedEntity {
wikidataId: String
weight: Int!
kind: String!

"""
Artigos que mencionam o vizinho (entity_stats). Null sem estatística calculada.
"""
articleCount: Int

"""
Conteúdos distintos que mencionam o vizinho: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int

"""
Co-menções com conteúdo distinto: republicações (mesmo content_hash) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
"""
uniqueContentWeight: Int

"""
weight · N / (artigos da entidade · artigos do vizinho), com N = entityGraphStats.totalArticles. > 1: co-menção acima do esperado ao acaso. Null quando falta estatística de uma das pontas ou o total do grafo.
"""
lift: Float
}

"""
Ordenação de `relatedEntities`. WEIGHT: artigos em co-menção (legado). UNIQUE_CONTENT: co-menções com conteúdo distinto (desconta republicações). LIFT: co-menção observada / esperada pela frequência das duas entidades (destaca associações específicas em vez de entidades genéricas). Valores nulos vão para o fim; desempate por weight.
"""
enum RelatedEntityOrder {
WEIGHT
UNIQUE_CONTENT
LIFT
}

type Release {
Expand Down
Loading
Loading