search_nodes

Category: knowledge
Access: read
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Searches the knowledge graph by free text and packs the best evidence per entity under a wire budget. Returns ranked entities with short observation windows plus an accounting block describing coverage and calibration.

Arguments

Required: query.

Optional: budget, project.

query. Note: Free text; a blank query lists the first 50 entities by name instead of matching.
budget. Note: Wire-character budget for packing (default 16000); over-budget entities stop the pack and report truncated.
project. Note: Accepted but currently unused on this path: it does not narrow or boost the ranking.

Result

JSON object with entities (name, entityType, observations as evidence windows, project when set, _evidence_status), the echoed query, and _accounting (entities_considered, entities_returned, observations_returned, truncated, budget_wire_chars, wire_chars, status, degraded, jump when measurable, refills, query_status, meaningful_terms, stopword_list).

Boundaries

Candidates, one-hop neighbours, and observations are all gated to the caller's project grants; foreign content never enters the pool or the expansion. Operates only inside the caller's profile boundary.

Lifecycle / side effects

Pure read of live content with scope-gated one-hop expansion. A best-effort access note is recorded alongside the read and never affects the returned content.

Errors

Missing or non-string query is rejected by validation. Unknown arguments and bad types are rejected (strict validator).

Example

{
  "budget": 16000,
  "query": "same-day print"
}

Result shape:

{
  "_accounting": {
    "entities_considered": 1,
    "entities_returned": 1,
    "observations_returned": 1,
    "status": "OK",
    "truncated": false
  },
  "entities": [
    {
      "_evidence_status": "found",
      "entityType": "vendor",
      "name": "Acme Print",
      "observations": [
        "Now offers same-day turnaround."
      ]
    }
  ],
  "query": "same-day print"
}