Referencia de Tipos de Dados¶

Esta pagina documenta todas as dataclasses, enums e tipos de resultado usados nos pipelines de escrita, leitura e jobs de background que nao sao cobertos na Referencia da API principal.

Tipos do Write Pipeline¶

InputType¶

class InputType(str, Enum)

Tipos de classificacao de texto de entrada, determinados por heuristicas em classify_input().

Valor	Descricao
`SHORT`	Menos de 500 caracteres.
`MEDIUM`	500-2000 caracteres, nao estruturado.
`LONG`	Mais de 2000 caracteres, nao estruturado.
`STRUCTURED`	Mais de 500 caracteres com headers, bullets ou tabelas.

ExtractionMode¶

class ExtractionMode(str, Enum)

Valor	Descricao
`SINGLE_SHOT`	Chamada unica de LLM para extracao.
`CHUNKED`	Entrada e dividida em chunks, cada um processado separadamente.

InputClassification¶

@dataclass
class InputClassification

Resultado de classify_input(). Veja API do Write Pipeline para referencia completa dos campos.

ExtractionStrategy¶

@dataclass
class ExtractionStrategy

Resultado de select_strategy(). Veja API do Write Pipeline para referencia completa dos campos.

CorrectionResult¶

@dataclass
class CorrectionResult

Resultado da deteccao de correcoes.

Campo	Tipo	Padrao	Descricao
`corrections_detected`	`int`	`0`	Numero de correcoes encontradas.
`corrected_keys`	`list[str]`	`[]`	Chaves de atributo que foram corrigidas.
`facts_corrected_ids`	`list[str]`	`[]`	IDs dos fatos antigos que foram corrigidos.

Tipos do Read Pipeline¶

ExpandedQuery¶

@dataclass
class ExpandedQuery

Resultado da expansao de query (entity priming).

Campo	Tipo	Descricao
`primed_entities`	`list[str]`	Entity keys descobertas via alias + KG priming.
`temporal_range`	`tuple[datetime, datetime] \| None`	Faixa de datas resolvida.
`expanded_terms`	`list[str]`	Termos de contexto adicionais dos fatos das entidades.

PatternQuery¶

@dataclass
class PatternQuery

Uma query baseada em padrao para matching de sinal de keyword.

Campo	Tipo	Padrao	Descricao
`entity_pattern`	`str`	--	Padrao SQL LIKE para matching de entity_key.
`attribute_filter`	`str \| None`	`None`	Filtro opcional de chave de atributo.

RetrievalPlan¶

@dataclass
class RetrievalPlan

Saida do retrieval agent (planner deterministico). Veja API do Read Pipeline para referencia completa dos campos.

GraphRetrievalResult¶

@dataclass
class GraphRetrievalResult

Resultado do retrieval baseado em grafo BFS de 2 saltos.

Campo	Tipo	Padrao	Descricao
`facts`	`list[dict[str, Any]]`	`[]`	Dicts de fatos pontuados com `source="graph"`.
`neighbor_keys`	`list[str]`	`[]`	Entity keys descobertas via BFS.
`edges_traversed`	`int`	`0`	Total de arestas examinadas durante BFS.
`edges`	`list[dict[str, Any]]`	`[]`	Dicts de arestas deduplicadas com nomes de exibicao.

SpreadingActivationResult¶

@dataclass
class SpreadingActivationResult

Resultado da expansao por spreading activation.

Campo	Tipo	Padrao	Descricao
`candidates`	`list[RetrievalCandidate]`	`[]`	Candidatos expandidos dos saltos 1-2.
`meta_observations`	`list[Any]`	`[]`	Meta-observacoes relevantes referenciando fatos semente.
`entities_explored`	`list[str]`	`[]`	Entity keys exploradas durante spreading.
`clusters_explored`	`list[str]`	`[]`	Cluster IDs explorados durante spreading.
`hop1_count`	`int`	`0`	Numero de fatos encontrados no salto 1.
`hop2_count`	`int`	`0`	Numero de fatos encontrados no salto 2.
`kg_relationships_explored`	`int`	`0`	Numero de relacionamentos KG percorridos.

CompressedContext¶

@dataclass
class CompressedContext

Resultado da compressao de contexto (camadas hot/warm/cold).

Campo	Tipo	Padrao	Descricao
`context_text`	`str`	`""`	String de contexto final pronta para prompt.
`hot_count`	`int`	`0`	Numero de fatos na camada hot (Tier 1).
`warm_count`	`int`	`0`	Numero de fatos na camada warm (Tier 2).
`cold_count`	`int`	`0`	Numero de itens na camada cold (Tier 3).
`total_tokens`	`int`	`0`	Contagem estimada de tokens do context_text.

EmotionalTrendsResult¶

@dataclass
class EmotionalTrendsResult

Resultado da materializacao de tendencias emocionais.

Campo	Tipo	Padrao	Descricao
`emotion_counts`	`dict[str, int]`	`{}`	Mapeamento de emocao para contagem de ocorrencias.
`trend_direction`	`str`	`"stable"`	`"increasing"`, `"decreasing"` ou `"stable"`.
`dominant_emotion`	`str \| None`	`None`	Emocao mais frequente.
`trigger_keywords`	`list[str]`	`[]`	Top keywords de eventos de alta intensidade.
`avg_intensity`	`float`	`0.0`	Intensidade emocional media.
`dominant_intensity`	`float`	`0.0`	Intensidade media da emocao dominante.
`dominant_energy`	`str`	`"medium"`	Nivel de energia predominante.
`events_analyzed`	`int`	`0`	Numero de eventos analisados.
`observation_created`	`bool`	`False`	Se uma meta-observacao foi criada/atualizada.
`observation_id`	`str \| None`	`None`	ID da observacao criada/atualizada.

DirectiveBlock¶

@dataclass
class DirectiveBlock

Resultado da geracao de diretivas (memoria procedimental).

Campo	Tipo	Padrao	Descricao
`text`	`str`	`""`	Bloco de instrucoes comportamentais coeso.
`directive_count`	`int`	`0`	Numero de diretivas ativas usadas.
`cache_hit`	`bool`	`False`	Se foi servido do cache.

ContradictionResult¶

@dataclass
class ContradictionResult

Resultado da verificacao de contradicao entre diretivas.

Campo	Tipo	Padrao	Descricao
`has_contradiction`	`bool`	`False`	Se uma contradicao foi encontrada.
`conflicting_directive`	`str \| None`	`None`	Titulo da diretiva conflitante.
`resolution`	`str \| None`	`None`	Explicacao da resolucao.

Tipos de Resultado de Background Jobs¶

ClusteringResult¶

@dataclass
class ClusteringResult

Resultado do clustering de fatos.

Campo	Tipo	Padrao	Descricao
`clusters_created`	`int`	`0`	Numero de novos clusters criados.
`clusters_reinforced`	`int`	`0`	Numero de clusters existentes atualizados.
`summaries_generated`	`int`	`0`	Numero de sumarios de cluster gerados via LLM.
`facts_assigned`	`int`	`0`	Numero de fatos atribuidos a clusters.

CommunityDetectionResult¶

@dataclass
class CommunityDetectionResult

Resultado da deteccao de comunidades cross-entity.

Campo	Tipo	Padrao	Descricao
`communities_created`	`int`	`0`	Novas observacoes de comunidade criadas.
`communities_reinforced`	`int`	`0`	Observacoes de comunidade existentes reforcadas.
`clusters_in_communities`	`int`	`0`	Total de clusters atribuidos a comunidades.
`skipped`	`bool`	`False`	Se a deteccao foi pulada.
`skip_reason`	`str \| None`	`None`	Motivo de ter sido pulada.

ConsolidationResult¶

@dataclass
class ConsolidationResult

Resultado da consolidacao L2/L3.

Campo	Tipo	Padrao	Descricao
`events_processed`	`int`	`0`	Numero de eventos analisados.
`observations_created`	`int`	`0`	Novas meta-observacoes criadas.
`observations_reinforced`	`int`	`0`	Observacoes existentes reforcadas.
`skipped`	`bool`	`False`	Se a consolidacao foi pulada.
`skip_reason`	`str \| None`	`None`	Motivo de ter sido pulada.

MemifyResult¶

@dataclass
class MemifyResult

Resultado do pipeline memify (scoring de vitalidade, marcacao de obsolescencia, gerenciamento de arestas).

Campo	Tipo	Padrao	Descricao
`facts_scored`	`int`	`0`	Numero de fatos pontuados por vitalidade.
`facts_marked_stale`	`int`	`0`	Numero de fatos marcados como obsoletos.
`edges_reinforced`	`int`	`0`	Numero de arestas KG reforcadas.
`merges_executed`	`int`	`0`	Numero de merges de entidade executados.

EntityImportanceResult¶

@dataclass
class EntityImportanceResult

Resultado do scoring de importancia de entidades (sleep-time compute).

Campo	Tipo	Padrao	Descricao
`entities_scored`	`int`	`0`	Numero de entidades pontuadas.
`top_entities`	`list[tuple[str, float]]`	`[]`	Top entidades por score (pares chave, score).

SummaryRefreshResult¶

@dataclass
class SummaryRefreshResult

Resultado da atualizacao de sumarios de entidades (sleep-time compute).

Campo	Tipo	Padrao	Descricao
`summaries_refreshed`	`int`	`0`	Numero de sumarios gerados.
`summaries_skipped`	`int`	`0`	Numero de entidades puladas.

Funcoes de Background¶

tag_event_emotion¶

Infere emocao, intensidade e energia a partir de texto de evento via LLM.

async def tag_event_emotion(
    event_text: str,
    llm: LLMProvider,
) -> dict[str, Any] | None

Parametro	Tipo	Descricao
`event_text`	`str`	Texto para analisar.
`llm`	`LLMProvider`	Provider de LLM injetado.

Retorna: Dict com chaves emotion, intensity, energy, ou None em caso de falha.

from arandu.background import tag_event_emotion

result = await tag_event_emotion("Estou muito feliz hoje!", llm)
# {"emotion": "joy", "intensity": 0.85, "energy": "high"}

Modelos de Banco de Dados¶

Os modelos SQLAlchemy abaixo definem a camada de persistencia. Eles vivem em arandu.models e sao uteis para queries avancadas executadas diretamente contra o banco de dados.

erDiagram
    MemoryEvent ||--o{ MemoryFact : "source_event_id"
    MemoryFact ||--o{ MemoryFactEntityLink : "fact_id"
    MemoryFact ||--o| MemoryCluster : "cluster_id"
    MemoryFact ||--o| MemoryFact : "supersedes_fact_id"
    MemoryEntity ||--o{ MemoryEntityAlias : "canonical_entity_key"
    MemoryEntity ||--o{ MemoryFactEntityLink : "entity_key"
    MemoryEntity ||--o{ MemoryEntityRelationship : "source/target"
    MemoryEntityRelationship ||--o| MemoryFact : "evidence_fact_id"
    MemoryFact }o--o| MemoryAttributeRegistry : "attribute_key"
    MemoryIntention }o--|| MemoryEvent : "agent_id"
    SessionObservation }o--|| MemoryEvent : "agent_id"

    MemoryEvent {
        UUID id PK
        Text agent_id
        DateTime occurred_at
        Text text
        Vector embedding_vec
    }
    MemoryFact {
        UUID id PK
        Text agent_id
        String entity_key
        Text fact_text
        Float confidence
        DateTime valid_from
        DateTime valid_to
        Vector embedding_vec
    }
    MemoryEntity {
        UUID id PK
        Text agent_id
        String canonical_key UK
        String display_name
        String entity_type
        Text summary_text
        Float importance_score
    }
    MemoryFactEntityLink {
        UUID id PK
        UUID fact_id FK
        String entity_key
        Boolean is_primary
        Text agent_id
    }
    MemoryEntityRelationship {
        UUID id PK
        Text agent_id
        String source_entity_key
        String target_entity_key
        String rel_type
        Float strength
        UUID evidence_fact_id FK
    }
    MemoryEntityAlias {
        UUID id PK
        Text agent_id
        String alias UK
        String canonical_entity_key
    }
    MemoryCluster {
        UUID id PK
        Text agent_id
        String label
        Text summary_text
        Vector embedding_vec
    }
    MemoryMetaObservation {
        UUID id PK
        Text agent_id
        String observation_type
        Text text
        Float confidence
    }
    MemoryAttributeRegistry {
        UUID id PK
        String key UK
        String status
        String value_type
        Integer seen_count
    }
    MemoryIntention {
        UUID id PK
        Text agent_id
        String trigger_type
        Text trigger_condition
        Text intended_action
        String status
    }
    SessionObservation {
        UUID id PK
        Text agent_id
        Text content
        String topic
        Boolean is_active
    }

MemoryFact¶

Ledger de fatos versionados - armazena fatos estruturados com janelas de validade.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`entity_type`	`String`	Tipo da entidade (ex: `"person"`).
`entity_key`	`String`	Chave canonica da entidade (ex: `"person:ana"`).
`entity_name`	`String?`	Nome legivel da entidade.
`attribute_key`	`String?`	Chave do atributo (ex: `"occupation"`).
`fact_text`	`Text`	Fato em linguagem natural.
`category`	`String(50)?`	Categoria do fato.
`confidence`	`Float`	Score de confianca (padrao 0.8).
`importance`	`Float`	Score de importancia (padrao 0.5).
`is_sensitive`	`Boolean`	Se o fato contem dados sensiveis.
`valid_from`	`DateTime`	Inicio da janela de validade.
`valid_to`	`DateTime?`	Fim da validade (`NULL` = ativo atualmente).
`ttl_days`	`Integer?`	Time-to-live opcional em dias.
`source_event_id`	`UUID?`	FK para `MemoryEvent`.
`supersedes_fact_id`	`UUID?`	ID do fato que este substitui.
`embedding_vec`	`Vector(1536)`	Embedding pgvector para busca semantica.
`vitality_score`	`Float?`	Score de vitalidade do sleep-time.
`is_stale`	`Boolean`	Se foi marcado como obsoleto pelo memify.
`cluster_id`	`UUID?`	FK para `MemoryCluster`.
`value_json`	`JSONB?`	Valor estruturado (JSON) para o atributo.
`needs_confirmation`	`Boolean`	Se o fato requer confirmacao do usuario.
`last_confirmed_at`	`DateTime?`	Quando o fato foi confirmado pela ultima vez pelo usuario.
`times_retrieved`	`Integer`	Quantas vezes este fato foi recuperado.
`last_retrieved_at`	`DateTime?`	Quando o fato foi recuperado pela ultima vez.
`user_correction_count`	`Integer`	Numero de vezes que o usuario corrigiu este fato.
`source_context`	`String(512)?`	Contexto da fonte da entrada original.
`agent_annotation`	`Text?`	Anotacao de texto livre adicionada pelo agente.
`embedding`	`JSONB?`	Embedding bruto como JSON (fallback nao-pgvector).
`search_vector`	`TSVECTOR`	Coluna de indice de busca full-text.
`created_at`	`DateTime`	Timestamp de criacao do registro.
`ingested_at`	`DateTime`	Timestamp de ingestao bi-temporal.
`invalidated_at`	`DateTime?`	Quando o fato foi invalidado (bi-temporal).

MemoryEntity¶

No de entidade de primeira classe no knowledge graph.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`canonical_key`	`String(128)`	Chave canonica unica (ex: `"person:ana"`).
`display_name`	`String(256)?`	Nome de exibicao legivel.
`entity_type`	`String(32)`	Tipo (`"person"`, `"organization"`, etc.).
`summary_text`	`Text?`	Sumario da entidade gerado por LLM.
`embedding_vec`	`Vector(1536)`	Embedding da entidade.
`fact_count`	`Integer`	Numero de fatos vinculados.
`importance_score`	`Float?`	Score de importancia do sleep-time.
`is_active`	`Boolean`	Se a entidade esta ativa.
`first_seen_at`	`DateTime`	Quando a entidade foi observada pela primeira vez.
`last_seen_at`	`DateTime`	Quando a entidade foi observada pela ultima vez.
`summary_refreshed_at`	`DateTime?`	Quando o sumario da entidade foi atualizado pela ultima vez.
`created_at`	`DateTime`	Timestamp de criacao do registro.

Constraint unica: (agent_id, canonical_key).

MemoryEntityAlias¶

Mapeia nomes de alias para chaves canonicas de entidade para resolucao de entidades.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`alias`	`String`	Texto do alias (ex: `"Ana"`).
`canonical_entity_key`	`String`	Chave canonica de destino.
`canonical_entity_type`	`String`	Tipo da entidade de destino.
`created_at`	`DateTime`	Timestamp de criacao do registro.

Constraint unica: (agent_id, alias).

MemoryEntityRelationship¶

Aresta direcionada entre duas entidades no knowledge graph.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`source_entity_key`	`String(128)`	Chave canonica da entidade de origem.
`target_entity_key`	`String(128)`	Chave canonica da entidade de destino.
`rel_type`	`String(64)`	Tipo de relacionamento (ex: `"works_at"`, `"mentored_by"`).
`strength`	`Float`	Forca da aresta (padrao 0.8).
`evidence_fact_id`	`UUID?`	FK para o fato que evidencia esta aresta.
`provenance`	`String(16)`	Como a aresta foi criada (`"rule"`, `"llm"`).
`valid_from`	`DateTime`	Inicio da validade.
`valid_to`	`DateTime?`	Fim da validade (`NULL` = ativa).
`created_at`	`DateTime`	Timestamp de criacao do registro.
`updated_at`	`DateTime`	Timestamp da ultima atualizacao.
`last_used_at`	`DateTime?`	Quando o relacionamento foi usado pela ultima vez em retrieval.
`invalidated_at`	`DateTime?`	Quando o relacionamento foi invalidado.

Constraint unica: (agent_id, source_entity_key, target_entity_key, rel_type).

Tipos de Relacionamento Dinamicos¶

O campo rel_type aceita qualquer string curta e descritiva em snake_case - nao e restrito a um conjunto fixo. O pipeline de extracao instrui o LLM a escolher o tipo mais descritivo para cada relacionamento.

Tipos comuns (usados como exemplos no prompt de extracao, nao como restricoes):

works_at, manages, reports_to, family_of, friend_of, partner_of, owns, lives_in, member_of, studies_at, works_with

O LLM tambem pode produzir tipos como mentored_by, inspired_by, competed_with, ou qualquer outro tipo descritivo.

Normalizacao: Todos os tipos de relacionamento sao normalizados via normalize_rel_type() antes da persistencia:

Lowercase + underscores (ex: "Mentored By" → "mentored_by")
Aliases conhecidos sao mapeados para tipos comuns (ex: "boss" → "reports_to", "spouse" → "partner_of")
Tipos desconhecidos passam apos sanitizacao

O set CANONICAL_REL_TYPES em arandu.constants esta disponivel como referencia para consumers que queiram filtrar por tipos conhecidos, mas nao e usado como filtro de validacao.

Veja Vinculação de Evidência e Cascata de Invalidação para como relacionamentos são vinculados a fatos e automaticamente limpos quando fatos mudam.

MemoryEvent¶

Log imutavel de eventos - armazena todas as mensagens do usuario com embeddings.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`occurred_at`	`DateTime`	Quando o evento aconteceu.
`text`	`Text`	Conteudo textual do evento.
`source`	`String`	Origem (padrao `"api"`).
`importance`	`Float`	Score de importancia (padrao 0.5).
`embedding_vec`	`Vector(1536)`	Embedding do evento para retrieval.
`embedding`	`JSONB?`	Embedding bruto como JSON (fallback nao-pgvector).
`trace_json`	`JSONB?`	Metadados de trace/debug do evento.
`created_at`	`DateTime`	Timestamp de criacao do registro.
`emotion_primary`	`String(32)?`	Label de emocao primaria.
`emotion_intensity`	`Float?`	Intensidade da emocao (0-1).
`energy_level`	`String(16)?`	Nivel de energia (`"low"`, `"medium"`, `"high"`).

MemoryCluster¶

Cluster semantico agrupando fatos relacionados para contexto mais rico.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`label`	`String(128)`	Label do cluster.
`summary_text`	`Text?`	Sumario do cluster gerado por LLM.
`cluster_type`	`String(32)`	Tipo do cluster (padrao `"auto"`).
`fact_count`	`Integer`	Numero de fatos no cluster.
`importance`	`Float`	Importancia do cluster (padrao 0.5).
`embedding_vec`	`Vector(1536)`	Embedding do cluster.
`is_active`	`Boolean`	Se o cluster esta ativo.
`last_updated_at`	`DateTime`	Quando o cluster foi atualizado pela ultima vez.
`created_at`	`DateTime`	Timestamp de criacao do registro.

MemoryMetaObservation¶

Meta-observacoes derivadas da consolidacao - padroes, insights, tendencias.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`observation_type`	`String(32)`	Tipo (`"pattern"`, `"trend"`, `"community"`, etc.).
`title`	`String(256)`	Titulo curto.
`text`	`Text`	Texto completo da observacao.
`supporting_event_ids`	`JSONB`	Lista de UUIDs de eventos de suporte.
`supporting_fact_ids`	`JSONB`	Lista de UUIDs de fatos de suporte.
`confidence`	`Float`	Confianca (padrao 0.7).
`importance`	`Float`	Importancia (padrao 0.5).
`times_reinforced`	`Integer`	Quantas vezes esta observacao foi reforcada.
`is_active`	`Boolean`	Se a observacao esta ativa.
`embedding_vec`	`Vector(1536)`	Embedding da observacao.
`first_detected_at`	`DateTime`	Quando a observacao foi detectada pela primeira vez.
`last_reinforced_at`	`DateTime`	Quando a observacao foi reforcada pela ultima vez.
`created_at`	`DateTime`	Timestamp de criacao do registro.

MemoryFactEntityLink¶

Tabela de referencia cruzada linkando cada fato a TODAS as entidades que ele menciona - habilita retrieval cross-entity sem duplicacao de fatos.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`fact_id`	`UUID`	FK para `MemoryFact`.
`entity_key`	`String`	Chave canonica da entidade (ex: `"person:clara_rezende"`).
`is_primary`	`Boolean`	Se esta entidade e o subject primario do fato.
`agent_id`	`Text`	ID do usuario.

Constraint unico: (fact_id, entity_key).

Indices: (agent_id, entity_key) para retrieval, (fact_id) para cascade deletes.

MemoryAttributeRegistry¶

Registro para gerenciamento de chaves de atributo - rastreia chaves propostas vs ativas.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`key`	`String(64)`	Chave de atributo unica.
`status`	`String(20)`	`"proposed"` ou `"active"`.
`value_type`	`String(20)`	Tipo de valor esperado (padrao `"string"`).
`conflict_policy`	`String(20)`	Como lidar com conflitos (padrao `"supersede"`).
`ttl_days`	`Integer?`	TTL padrao opcional para fatos com esta chave.
`seen_count`	`Integer`	Quantas vezes esta chave foi vista.
`proposed_by`	`String(20)`	Quem propos a chave (`"llm"`, `"user"`).
`reason`	`Text?`	Por que a chave foi proposta.
`first_seen_at`	`DateTime`	Quando a chave de atributo foi vista pela primeira vez.
`last_seen_at`	`DateTime`	Quando a chave de atributo foi vista pela ultima vez.
`example_raw_key`	`String(128)?`	Exemplo da chave bruta antes da normalizacao.
`created_at`	`DateTime`	Timestamp de criacao do registro.
`updated_at`	`DateTime?`	Timestamp da ultima atualizacao.

MemoryIntention¶

Memoria prospectiva -- intencoes futuras com triggers baseados em tempo ou evento.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`trigger_type`	`String(16)`	Tipo de trigger (`"time"`, `"event"`, etc.).
`trigger_condition`	`Text`	Descricao em linguagem natural da condicao de trigger.
`intended_action`	`Text`	O que o agente deve fazer quando ativado.
`due_date`	`DateTime?`	Data limite opcional para triggers baseados em tempo.
`status`	`String(16)`	Status (`"pending"`, `"triggered"`, `"fulfilled"`, `"expired"`). Padrao `"pending"`.
`trigger_embedding_vec`	`Vector(1536)`	Embedding da condicao de trigger para matching semantico.
`source_context`	`String(32)?`	Identificador de contexto da fonte.
`outcome_note`	`Text?`	Nota sobre o resultado apos cumprimento.
`created_at`	`DateTime`	Timestamp de criacao do registro.
`triggered_at`	`DateTime?`	Quando a intencao foi ativada.
`fulfilled_at`	`DateTime?`	Quando a intencao foi cumprida.

SessionObservation¶

Observacoes de sessao persistentes criadas pelo Observer LLM -- captura contexto intra-sessao que persiste entre turnos.

Coluna	Tipo	Descricao
`id`	`UUID`	Chave primaria.
`agent_id`	`Text`	ID do agente proprietario (qualquer string: UUID, slug, numerico, etc.).
`content`	`Text`	Conteudo textual da observacao.
`topic`	`String(64)?`	Tag de topico para a observacao.
`entities_mentioned`	`JSONB`	Lista de entity keys mencionadas na observacao.
`created_at`	`DateTime`	Timestamp de criacao do registro.
`referenced_at`	`DateTime?`	Quando a observacao foi referenciada pela ultima vez.
`relative_offset`	`String(64)?`	Descritor de offset temporal relativo (ex: `"2 messages ago"`).
`source_message_ids`	`JSONB`	Lista de IDs de mensagens de origem desta observacao.
`is_active`	`Boolean`	Se a observacao esta ativa.
`merged_into_id`	`UUID?`	ID da observacao na qual esta foi mergeada.
`emotion_label`	`String(32)?`	Label de emocao detectada para o contexto de sessao.
`embedding_vec`	`Vector(1536)`	Embedding da observacao para retrieval semantico.