Skip to main content
Concept · core

Use when

You list the entities that cite a File, check where an entity came from, or build a packet of passages and entities for one question.

Looking for something else?

Finding passages for a question (card Search). Choosing what a client sees, and saving a definition (card View). Changing an entity (card Entity).

​
For

Context reads the Graph and the Files together. It answers two kinds of question. The first is what the project knows and from which Files. Explore and entity answer it. The second is what to put in front of an agent for one question. Compile and materialize answer it. Explore lists entities, the most recently changed first, each with the Files its citations name. Entity shows one entity with its properties, its citations and the relationships that touch it. A definition is a purpose and a scope. Compile checks a definition against the project’s Shapes and keeps nothing. Materialize runs a question inside the definition. It returns a packet of passages, entities and relationships, with warnings, a token budget and text that is ready to give to an agent. Context only reads. It changes no File and no entity. A packet is a reading at one moment. Only the published version of a saved definition keeps a packet receipt, and the packet receipt never changes (card View). Context does not tell you that a source went stale. An entity keeps citing a replaced version or a trashed File, and nothing in Context marks it. You compare each citation with its File yourself (recipe find-stale-entities).

​
Use when

  • You need every entity that cites a File.
  • You need to see which Files, versions and passages one entity came from.
  • You need one packet of passages and entities to give to an agent.
  • You need to compare what a question returned at two moments.

​
Not this

  • Finding passages for a question, with no entities: use card Search.
  • Choosing what a client or a Brain can see: use card View.
  • Changing an entity or its citations: use card Entity and card Workspace.

​
Rules

  1. context.1 Explore lists entities, not passages. penumbra context explore lists the entities that match your words and filters, the most recently changed first. It filters by Shape, entity type, relationship type, File and date. Enforced: a page holds 1 to 200 entities, and a --limit outside that range is refused with invalid_option. Your job: read the next page with the --cursor value of the next: line, until no such line shows.
  2. context.2 A File filter finds an entity through the citations of its current revision. --file-id may repeat. It matches a citation on any version of the File. Your job: an entity whose citations wait for confirmation, or that has none, is not found by this filter. Check those apart (card citations-to-confirm).
  3. context.3 Context does not say whether a cited File is trashed, purged or replaced. A citation gives the File ID, the version ID, the content digest and the passage ID. Nothing marks a trashed File or an older version. Explore lists at most 32 citations for each entity, and its text names only the Files. Your job: read the IDs with --json or with penumbra context entity. Read the state of each File with penumbra files list --all, and its current version with penumbra files versions. Then compare.
  4. context.4 penumbra context entity <entity-id> shows the properties, the citations of the current revision and the relationships. Enforced: a page holds 1 to 100 relationships, and a --relationship-limit outside that range is refused with invalid_option. Your job: read more relationships with --relationship-cursor. A relationship shows no citations here.
  5. context.5 Compile checks a definition and keeps nothing. A definition is a purpose of 1 to 1,024 characters and a scope. A scope lists Files, collections, entities, Shapes, entity types and relationship types. An empty scope is the whole project. Enforced: a Shape or type that the project does not have is refused with shape_scope_unavailable, entity_type_scope_unavailable or relationship_type_scope_unavailable. A File in the scope that is trashed, purged or unreadable is refused with file_not_found or file_scope_unavailable.
  6. context.6 A scope names Files, never versions. A File in a scope is read at its current version each time. Your job: after a replace, a packet made before it holds the old text and a new packet holds the new text. The definition needs no change.
  7. context.7 penumbra context materialize "<question>" returns one packet for one question. It holds up to 20 passages from Files search, up to 20 entities, up to 20 relationships, and the passages that those entities cite. --mode is lexical, hybrid or semantic, and the default is hybrid. Your job: read the line of the packet that starts with “files searched:”. It shows the mode that ran and how many File versions are ready for search by meaning. Use lexical when the question needs exact words.
  8. context.8 A packet fits a token budget. --max-tokens runs from 512 to 32768, and the default is 4000. Enforced: a budget too small for the material is refused with context_budget_too_small. Your job: when the budget cuts material, the packet says truncated and warns with graph_token_budget_exhausted or evidence_token_budget_exhausted. A cut can remove a passage that supports an entity that the packet still holds. Then the packet also warns with evidence_support_omitted and names up to 10 passages. Raise the budget or narrow the scope before you rely on the packet.
  9. context.9 A passage that an entity cites comes from the version that its citation names, which may not be the current version. Your job: read the version= ID on each passage line against the File’s current version. A citation that Penumbra cannot open is left out, and the packet warns with graph_evidence_unavailable. The entity stays in the packet without that source.
  10. context.10 --context <file> reuses a compilation saved with penumbra context compile --out <file>. Enforced: if the project’s Shapes or the definition changed since, materialize is refused with context_compilation_changed. Compile again. A file that is not a saved compilation is refused with invalid_context_input.
  11. context.11 Only penumbra context slice materialize keeps a packet receipt. penumbra context materialize keeps nothing. A packet receipt holds the exact packet, and neither one changes later. Your job: materialize again for today’s answer. penumbra context receipt <receipt-id> --packet shows the old packet. penumbra context diff receipts <left-id> <right-id> shows what changed between two.
  12. context.12 penumbra context slice materialize takes a --request-id. Enforced: the same ID with the same question returns the first receipt and makes no second one. The same ID with another question is refused with idempotency_conflict. Your job: after a lost reply, run it again with the same ID (problem reply-lost).
  13. context.13 Context commands do not wait for approval. Enforced: explore, entity, compile, materialize and penumbra context slice materialize run at once. Penumbra holds only the publication of a saved definition that a key or a connected agent makes (card View).
  14. context.14 Access limited to a View cannot compile or materialize on its own definition. Enforced: the refusal is view_operation_unavailable, and that access materializes the View’s published version instead (card view).
  15. context.15 A scope that names exact entities searches no relationships. Your job: read the compile warning relationships_omitted_under_exact_node_scope, and name relationship types in the scope when you need relationships.

​
Failure signs

  • Entities cite a version that a new edition replaced: problem entities-cite-replaced-version.
  • An entity’s only citations point to a trashed File: problem entity-rests-on-trashed-file.
  • You need the entities of one exact version: problem what-cites-this-version.
  • You need every entity that rests on an old version or a trashed File: recipe find-stale-entities.
  • A packet warns graph_evidence_unavailable: rule context.9.
  • Materialize is refused with context_compilation_changed: rule context.10.
  • Compile is refused with file_not_found or file_scope_unavailable: a File in the scope is trashed, purged or unreadable (rule context.5).
  • An entity you know is missing from the entities of its File: rule context.2.

​
Doors

​
The CLI word

The CLI calls a View a Slice and an entity a node.

​
HTTP reference

​
Keep going

File · Passage and citation · Entity · Search · View · Entities still cite a replaced version · An entity rests on a trashed File · No lookup finds the entities of one version · Find entities that rest on an old version or a trashed File