> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract a source

> Estimate the cost, extract saved material through a Shape, and inspect the records and source links it produces.

Use extraction when a saved source still needs to be turned into structured
records and relationships. Extraction spends model credits.

## Before you start

* [Check the active project](/runtime/orient).
* Identify the source or collection.
* [Inspect the Shape](/runtime/choose-shape) and the record types it can produce.
* Set the maximum cost you are willing to approve.

## Ask your agent

> Estimate the cost to extract the source “Q3 customer interviews” through the
> Research Shape. Show me the source count, token count, estimated credits, and
> available balance. Wait for my approval before spending credits. After the
> run, show me the records and relationships it produced and quote the source
> passages behind representative findings.

## Steps

<Steps>
  <Step title="Confirm the source and Shape">
    The agent resolves the source, inspects the Shape, and states which record types it expects to produce.
  </Step>

  <Step title="Run the estimate">
    It performs a dry run and reports the source count, token count, estimated credits, and available balance.
  </Step>

  <Step title="Approve the paid run">
    Confirm the source set, Shape, and estimate before extraction begins.
  </Step>

  <Step title="Start once and follow the run">
    The agent starts extraction once and checks the returned run handle until it completes or fails.
  </Step>

  <Step title="Inspect the output">
    It reports the actual cost, opens representative records, and follows their source references.
  </Step>
</Steps>

## Verify

Open one extracted record and quote the source passage behind it. Also confirm
whether the run made the records live, staged them, or sent them for review.

## Troubleshooting

* **No suitable Shape:** add one from the catalog or create one before retrying.
* **Estimate is too high:** narrow the collection or stop.
* **Run is still active:** keep checking the same run; do not start another paid extraction.
* **Result says staged or pending:** report that state instead of calling the records live.
* **Record does not match the source:** decide whether the Shape or the extraction caused the mismatch before rerunning it.

<Accordion title="Tool trace">
  ```text theme={null}
  penumbra_status
  → penumbra_list_sources
  → penumbra_introspect
  → penumbra_extract({ dry_run: true })
  → approval
  → penumbra_extract(...)
  → penumbra_extract({ run }) until complete
  → penumbra_omnisearch
  → penumbra_read
  → penumbra_source_rag
  ```
</Accordion>