Add Oracle

Add a person to your knowledge base as an Oracle — a trusted source OPYT deep-ingests (their X timeline + Substack/blog archive + GitHub) and roots trust on. This is the atom-KB "add a person" — the only one: the old vault-era add_person tool, which wrote the legacy vault and couldn't admit a Substack/blog-rooted person, is retired.

SAFE, TWO-PHASE — always preview before you ingest: • FIRST call with confirm=False (the default) → a PREVIEW. It resolves reference and returns who they are (name, bio, followers) — or, if already known, their roster entry — and writes NOTHING. Read it back to the user to confirm it's the right person. If the reference doesn't resolve you get unresolved and there's nothing to confirm. • THEN, once the user agrees, call again with confirm=True → runs the full ingest and writes to the store. Never call confirm=True without showing the preview first — the guard is against ingesting the WRONG PERSON, which no later call undoes.

reference is polymorphic: an X @handle ("@karpathy"), a Substack/blog/site URL ("https://simonwillison.net"), or a canonical_id from oracle(action='screen') (to promote a below-the-cut candidate). To add someone by NAME, YOU resolve the name → their @handle or URL first (your own knowledge / a web search), then pass that — there is no name-search endpoint.

TWO windows, asked separately, because they answer to different constraints: • x_lookback — "6mo" (default) / "1yr" / "2yr". Hard-capped at 2 years whatever you pass. ASK the user before a confirm=True; the ~6-month default silently leaves most of a prolific account's history out. For someone ALREADY on the roster, "since_last" pulls only what is new since their last pull — the cheap top-up, roughly one request for a few days' gap. Reach for it when the user says "update" or "catch up", not "add". • web_lookback — "1yr" / "2yr" / "5yr" / "all" (default). A durable archive, so it already pulls everything. Pass it only to NARROW. A single shared window would be wrong for one of the two by construction — it either over-pulls X or truncates the archive. The result echoes the windows that actually ran (including the X clamp) under lookback — TELL the user how far back you pulled.

Reading the result — do not report ingested as if it were the whole story: • ingested counts sources that actually ingested; blocked counts sources where the host stopped us (Cloudflare, a truncated archive). A blocked source wrote nothing and is retried on the next run — say so plainly ("their Substack was blocked, nothing was saved, it'll retry") rather than implying it worked. errors is the "something is wrong, worth a look" bucket. • atoms_added vs dispatched: lookback/limit bound posts ATTEMPTED, not atoms saved, so these two diverge whenever posts are paywalled or fail the quality gate. If atoms_added is much smaller, tell the user the number they actually got. • producer_failed > 0 means posts vanished mid-run — mention it; nothing else records it.

The result may ask you to do something — check for followup. A confirm=True result carries one, and acting on it is how this tool finds a person's blog / YouTube / podcasts at all. OPYT's four probes are deterministic (X bio, Substack convention, GitHub, Semantic Scholar); the open-web step is YOURS, because you have web search and OPYT would otherwise pay a second model for a worse version of it. So: run the search it describes, then call this tool AGAIN with the same reference, confirm=True, and the URLs in extra_source_urls. Send everything plausible — you do NOT need to verify ownership, because the trust graph re-checks every URL and rejects what it cannot corroborate. A URL you drop is invisible; a URL it rejects lands in needs_review.