stage_candidates
Stage extracted people, interactions, relationships, groups, and memberships as structured candidates for import. Use after extracting from notes or transcripts.
Instructions
Stage agent-extracted people, interactions, records, relationships, groups, and memberships.
Candidate types are person, interaction, affiliation, fact, observation, trait,
relationship, group, and group_membership.
Use this after extracting concise candidates from user-provided notes, meeting transcripts, or other
agent-visible text. Distinguish what was stated (fact), what happened in this source (observation),
and what you inferred (trait, which requires an explicit confidence and a concise evidence_note).
Relationship candidates carry batch-local from_ref/to_ref and are ordinary-disclosure only: omit a
relationship the user would consider sensitive or restricted rather than staging it.
References are batch-local; raw notes and source text must not be included in candidate fields. A
request using observation, trait, or relationship is bounded to 500 candidates, a 128-character
source, 1 MiB of candidate JSON, and 8 KiB per string.
A fact or affiliation may record who asserted it in an optional stated_by of at most 256
characters: a person, a document, or a role. Attribution is not verification. A CV saying someone is
analytical is that person's own claim about themselves, so stage it as a fact whose value says so and
whose stated_by names them, never as an inferred trait. stated_by is separate from source, which
names the process that wrote the row, and from source_kind below, which receipts the artifact read.
Omit it when the attribution is unknown rather than guessing at a speaker.
A trait may name the records it was drawn from. Give a supporting observation or interaction any
short evidence_ref label of your own and list those labels in the trait's evidence_refs; use
evidence_ids for records already stored. Evidence must be about the trait's own person, and one trait
cites at most 32 references and ids combined, each at most 256 characters.
A shared context is two candidates, never one. A group names an identified class, cohort, team,
department, club, household, or community and carries a batch-local ref; a group_membership places
one person_ref in one group_ref with a role, and requires a batch that passes source_kind, so a
group committed in an earlier call can still be named. Group names never merge: staging looks nothing up
by name, so committing a group candidate creates a new group unless you pass group_id — resolve an
existing group with find_groups first and pass the id it returns. Record dates only where the source
gave them. Absent dates stay absent and mean unknown, never "still going": temporal_basis is unknown
without dates, period with them, and ongoing only when you set it because the source said so. Do not
invent a year, a class number, or a yearly placement per grade; a confirmation that people stayed
together records the people and the extent that were confirmed, and nothing more. "My classmate" with no
identified group is a relationship, not an invented group.
source_kind optionally records an import receipt for this batch. It is a machine category such as
meeting_transcript, at most 128 characters of letters, digits, ., _, -, or / — never a person,
a title, or a description; put any human wording in label instead. If you can compute a SHA-256 over
the exact source artifact, pass it as content_digest (64 lowercase hex characters) so re-importing that
same source can be detected; without one, no duplicate detection is promised. extraction_fingerprint
is optional and should be omitted unless you have explicit, bounded configuration semantics for it.
None of these fields may carry source text.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| source | Yes | ||
| candidates | Yes | ||
| source_kind | No | ||
| content_digest | No | ||
| external_source_id | No | ||
| extraction_fingerprint | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||