Skip to main content
Troubleshooting · extraction

Use when

A File got a new version and the Graph lacks what the new text says. Or an answer from the Graph disagrees with search.

Looking for something else?

Entities that still cite the old version and need checking (problem Entities still cite a replaced version). A new edition uploaded as a separate File (problem A new edition is a separate File).

​
Signs

  • penumbra files versions <file> shows a newer version marked current.
  • A fact that only the new text states is missing from the Graph, and penumbra files search "<phrase>" finds it in the File.
  • penumbra context explore --file-id <file-id> --json lists entities whose citations name older version IDs, and none names the current version.
  • No workspace holds an extraction of that File that you started for the new version.

​
Why it happens

Uploading, replacing or syncing a File makes a version and processes it. Nothing in that path starts an extraction. An extraction costs AI credits and fills a workspace for review, so a person or an agent starts it on purpose. Search reads the current version, so search is up to date when processing ends. The Graph is not. It holds the entities that earlier extractions and edits put there, and each one cites the version it was read from.

​
What Penumbra does

By itself:
  • Makes the new version current and searchable when processing ends.
  • Starts no extraction when a version is uploaded or replaced.
  • Reads each File’s current version when an extraction starts, and notes the exact version it read.
  • Shows the Files and versions an extraction would read before it starts, with penumbra extractions plan.
You must:
  • Find out whether the current version was ever extracted.
  • Start the extraction on the new version, and review it before you submit it.
Not handled:
  • No signal on a File that says its current version has no extraction.
  • Only an item with the same Shape type and name as exactly one live entity becomes updates existing. Every other repeat stays new (problem extraction-duplicates-existing-entity).

​
Do

  1. Read the current version: penumbra files versions <file>. Note the version ID on the current: line.
  2. Read the versions the Graph cites: penumbra context explore --file-id <file-id> --json. If an entity cites the current version, something already read it. If none does, go on.
  3. Look for an extraction that waits for review: penumbra graph workspace list. Open the workspace that holds it before you start another one, so you do not extract the same version twice.
  4. Set the source date of the new version before you extract (card rule file.5). An extraction copies the date when it starts.
  5. See what the extraction would read: penumbra extractions plan --file-id <file-id> --shape "<shape>". Check that the version is the current one.
  6. Extract: recipe extract-files. An API key or a connected agent waits for approval (problem change-waits-for-approval).
  7. Before you submit, search the Graph for each proposed entity and use the entity that exists (problem extraction-duplicates-existing-entity).
  8. Deal with the entities that cite the old version (problem entities-cite-replaced-version).

​
Don’t

  • Don’t answer from the Graph alone after a replace. Search shows the new text, and the Graph may still show the old facts.
  • Don’t extract again to “refresh” the same version. It reads the same text and spends credits again. The one exception is a source date that you set after the first run (problem file-has-no-source-date). Then extract again, and expect updates existing. Read time on those entities after the submit (problem entity-time-lost-after-edit).
  • Don’t submit the extraction as it is. It can propose entities that the Graph already holds.

​
Check

  • penumbra context explore --file-id <file-id> --json lists an entity that cites the current version ID, or the person has decided that nothing in the new version belongs in the Graph.
  • Every entity that cited the old version is refreshed, or the person has decided to keep it.
Card rules file.5 and file.7. Recipes new-edition, extract-files and find-stale-entities. Problems entities-cite-replaced-version and extraction-duplicates-existing-entity.

​
Keep going

File · Entity · Extraction · Context · Bring in a new edition of a document · Extract entities from Files · Entities still cite a replaced version · Find entities that rest on an old version or a trashed File