Quickstart

Run the paths that are ready today: read the ontology, search, capture an entity, recall memory, and check decision quality.

This walks the surfaces that are ready to use right now. Everything except the last write step is read-only, and the write stages without committing, so you can run the whole thing safely against a live project.

Prerequisite: a client with an API key, from the installation step.

import { createPenumbra } from "@penumbra-systems/platform";

const pb = createPenumbra({ apiKey: process.env.PENUMBRA_API_KEY! });

1. Read the ontology

   See the typed frameworks the project is built on, so you know what the graph can hold.

   const ontology = await pb.ontology({ format: "markdown" });
   console.log(ontology.markdown || ontology.content);
   
2. Search

   Retrieve across entities and sources. include controls what comes back.

   const hits = await pb.search("pricing objections from enterprise deals", {
     include: ["entities", "chunks"],
     limit: 10,
   });
   console.log(hits.results);
   
3. Capture an entity (staged)

   Writes stage through a governed delta. Pass apply: false to stage without committing, which is the right default while you test. The receipt tells you the delta to inspect.

   const receipt = await pb.capture({
     type: "Insight",
     properties: {
       content: "Enterprise buyers stall on procurement, not price.",
     },
     apply: false, // staged, not committed
   });
   
   console.log(receipt.status, receipt.deltaId); // "staged", "..."
   

   When you are ready to commit, drop apply: false (or call pb.deltas.apply(receipt.deltaId)).

4. Recall memory

   Read domain-typed memory back as a graph object you can render.

   const memory = await pb.memory.recall({
     query: "what should be known before continuing?",
     limit: 5,
   });
   console.log(memory.toMarkdown());
   
5. Check decision quality

   Before acting, ask whether a region of the graph is good enough for the purpose at hand. A verdict is a disposition plus a list of findings, never a confidence score.

   const verdict = await pb.dq.check({
     subject: { type: "Account", id: "acme" },
     purpose: "send a renewal proposal",
   });
   
   if (!verdict.safeToAct) {
     console.log(verdict.explain());
     console.log(pb.dq.repair(verdict)); // suggested remediation steps
   }
   

Where to go next

SDK reference

Every method, with options and return shapes.

Decision quality

How pb.dq verdicts and findings work.