query

Args:
    question: Natural-language question. Optional since: omit it
        and set structural claim filters (or an aggregate / the predicate
        listing) for the deterministic modes — no embedding, no LLM call.
    tags: Subtree-expanded tag filters, repeatable.
    subject_id: Restrict to particles about this subject.
    min_confidence: Minimum confidence value (0.0–1.0).
    top_k: Number of particles to retrieve (1–200).
    audience: "GENERAL" | "EXPERT" | "REGULATORY".
    summary: When ``True``, each hit in ``particles`` is reduced to
        ``{id, content, confidence, effective_confidence,
        subject_ids}`` — provenance, tags, properties, and
        embeddings are dropped. The NL ``answer`` string and
        coverage gaps are unchanged. Use this when the agent only
        needs to surface the answer and pick particles to
        ``particle_show`` later. Default ``False`` preserves the
        full ``QueryResponse`` shape for backward compatibility.
    as_of: ISO-8601 past instant (a bare date means start of that
        day, UTC): answer what the store believed at T.
        Retired hits carry an ``as_of_notes`` entry (current status,
        retirement instant + basis, and the superseding belief);
        ``as_of_excluded_undatable`` discloses retirements the store
        cannot date. A future instant is rejected.
    during_start: With ``during_end``, a window of world time (ISO-8601
        dates, inclusive; either may be omitted for an open end): answer
        about what began in, or was in force during, that period.
        The window prefilters the candidate set before ranking;
        with no question it returns the claims in date order, each with a
        ``window_hits`` reading (``BEGAN``, ``IN_FORCE``, ``HELD_AT``,
        ``WITHIN``). A retired claim is admitted for the period it held,
        marked with its retirement and its close. Reads ``valid_from``;
        ``window_coverage`` discloses the undated and unkinded claims the
        window could not judge. Resolve the anchor first ("when did the
        user move?"), then ask with dates: the anchor step is the caller's.
    during_end: The inclusive end date of the window; see ``during_start``.
    on: The point form: what held or happened on this date (ISO-8601).
        Alternative to ``during_start`` / ``during_end``.
    predicate: Structural filter — claims whose predicate term
        equals this string (case-insensitive, exact: a CURIE and its
        expanded IRI are different strings; discover terms with
        ``list_predicates``). With a question it prefilters the semantic
        candidate set; without one it selects the deterministic listing.
    object_eq: Claims whose object equals this value (typed comparison
        when both sides normalize — numbers and ISO dates — else
        case-insensitive text).
    object_gt: Claims whose object is greater than this number or ISO
        date; claims whose object would not normalize are excluded and
        disclosed in ``claim_coverage.not_normalizable_excluded``.
    object_lt: Claims whose object is less than this number or ISO date
        (same normalization and disclosure as ``object_gt``).
    object_contains: Claims whose object contains this substring
        (case-insensitive; every term kind).
    count: Deterministic aggregate — the number of matching claims with
        their effective-confidence distribution. Rejects a simultaneous
        question.
    group_by: Deterministic aggregate — bucket matching claims by
        "subject", "predicate", or "object" with per-bucket counts and
        confidence distribution. Rejects a simultaneous question.
    min_effective_confidence: Explicit confidence floor for the aggregate
        modes; excluded rows are disclosed. There is no default floor.
    list_predicates: List the distinct predicate terms with kind and
        claim count (``predicate_vocabulary`` in the response) — the
        discovery surface for the exact-string predicate filter.
    all_projects: On a server bound to one project, read the whole
        store instead of that project's view. The result says so. No effect
        on an unbound server.
    grounded: Compose a grounded answer: every sentence ends
        with the ids of the retrieved particles it rests on (``[p-1a2b3c4d]``,
        the form ``particle_show`` accepts), or with ``[inference]`` (the
        model's own inference over cited claims) or ``[background]`` (from
        nothing in the store). Cited ids are checked against the retrieved
        set; a sentence with no valid citation and no label is
        ``[unattributed]``. Nothing is dropped and nothing is stored.
        ``answer_attribution`` carries the per-sentence labels and full
        cited ids. Omit to use the server's ``query.grounded_answers``.

Returns:
    The full ``QueryResponse`` as JSON — answer string plus the
    ranked particles, effective confidences, coverage gaps, and
    any truncation warning. A structural call returns rows
    or counts, not generated prose: the deterministic listing fills
    ``particles`` ordered by effective confidence, the aggregates fill
    ``structural_aggregate``, the vocabulary listing fills
    ``predicate_vocabulary``, and every structural result carries
    ``claim_coverage`` (the annotated-fraction footer plus the
    non-normalizable exclusion disclosure). Each particle's ``contested`` key is
    the id of an open INCONSISTENCY referencing it,
    else null; the composed contested badge rides
    beside it — the response-level ``contested`` list carries one
    badge (fired bases + drill-downs) or null per ranked particle,
    and with ``summary=True`` each slim hit carries
    ``contested_bases`` (the fired basis labels, else null) beside
    its ``contested`` id. When ``summary=True``, each particle
    entry is a small dict instead of the full Pydantic model.