Ingest a document into the graph

Upload source material, extract it through a shape, and read the typed entities it produces.

This is the core loop Penumbra gives you out of the box: take unstructured material, coerce it into typed graph structure through a shape, and read the result back with full provenance to the source.

register a source ──▶ extract through a shape ──▶ review the delta ──▶ read entities

Prerequisites: a client and a shape that exists in your project to extract through. List shapes with pb.shapes.list().

1. Register the source

   Register the material so it can be extracted. The returned id is what you extract and read against.

   const source = await pb.sources.register({
     type: "document",
     name: "Acme MSA.pdf",
     // ...source reference or content, per your upload flow
   });
   
2. Extract through a shape (staged)

   Extraction coerces the source into entities and relationships that match the shape. Stage it with apply: false so you can review before it lands.

   const receipt = await pb.extract({
     source: { id: source.id },
     shapeId: "shp_contract_terms",
     apply: false,
   });
   
   console.log(receipt.status, receipt.deltaId); // "staged", "..."
   

   The same source can be extracted through different shapes to surface different structure. The shape is the lens you read the material with.

3. Review the delta

   Extraction stages a delta. Plan it to see what applying it would add to the graph.

   const plan = await pb.deltas.plan(receipt.deltaId);
   console.log(plan);
   
4. Apply

   Commit the delta when the plan looks right.

   await pb.deltas.apply(receipt.deltaId);
   
5. Read what landed

   From the source, read exactly the entities it grounds, with counts per shape.

   const entities = await pb.sources.entities(source.id);
   const stats = await pb.sources.entityStats(source.id);
   
   console.log(stats);
   

What you have now

The document is no longer opaque text. It is typed entities in a governed graph, each tracing back to the source it came from. You can search them, check whether they are fit to act on, and project them out to other formats.

Sources reference

Every pb.sources method.

Semantic git

How staging, planning, applying, and reverting work.