Steps:
1. Each relation triple upserts its source and target entities by name and
records the directed relation. Predicates and types outside the
vocabulary accepted by relate_entities are not rejected. They are
normalized to related_to / unclassified, and the original predicate is
kept as evidence.
2. Each name in entity_hints reuses an entity already resolved in step 1,
or an existing entity of any type whose name matches (exact
case-insensitive match first, otherwise the closest search result). If
nothing is found, a new 'unclassified' entity is created.
3. The text is stored as an episode linked to every resolved entity. If
there are no entities, an 'observation' anchor entity is created
instead.
4. One 'observed' fact (the first 200 characters) is stored on the first
entity. The episode is attached as evidence for the relations and
entities this call created.
5. If trigger_cycle is true, run_cognitive_cycle is run afterwards.
Returns episode, entities (with created flags), facts, relations (with
per-triple errors) and cycle.
Example:
process_observation(
content="Pedro joined Globex as CTO",
entity_hints=["Pedro", "Globex"],
relations=[{"source": "Pedro", "source_type": "person",
"predicate": "works_for", "target": "Globex",
"target_type": "organization"}],
)
Args:
content: The observation text. It is stored in full in the episode.
source: Label for who produced the observation (e.g. 'agent', 'user', 'sensor', 'inference').
entity_hints: Optional list of entity names mentioned in the observation.
trigger_cycle: If true, run the cognitive cycle after storing.
relations: Optional list of triples {"source", "predicate", "target", optional "source_type", "target_type", "valid_from", "supersede_previous", "epistemic_status"}. The types default to 'unclassified'. The temporal fields work as in relate_entities. Set supersede_previous to true to close the previous relation of the same kind (e.g. a person changed employer).
epistemico: How the information is known, which sets its confidence ceiling: 'medido' (measured: returned by a system, reproducible; 1.0), 'reportado' (reported: told by a person or third party; 0.8) or 'inferido' (inferred: concluded by reasoning; 0.7). If given, it applies to the episode, the fact, newly created entities and any relation without its own epistemic_status. If omitted, it is guessed from the content for the episode and fact, and falls back to 'inferido'.
fuente: Optional. How you came to know this: modo ('vivido' I did or said it, 'conversado' someone told me, 'leido' a document/web/another agent/tool output, 'pensado' I inferred it), de (who said it), con (who you were with, only if not your owner), para (who you did it for), canal (e.g. 'whatsapp'), donde (repo, project, URL). Who you were with and through which agent are stamped by the server from your credential. Applied to the episode and the fact.
