Graph recipes

Search finds a passage. The graph tells you what that passage is connected to — who else says it, what it belongs to, what sits between it and something else. Six calls, each replacing a loop an agent would otherwise run by hand.

export UNLOB_API_KEY=ulb_...
alias unlob='curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com'

Every one of these takes a passage id (id) from a search hit, or an entity or topic string.

Before you assert: corroborate

unlob /corroborate -d id='https://example.com/article:0'

Returns the distinct hosts carrying this story, grouped and ranked by authority, with independent_sources counting them and merged_duplicates counting the copies folded into the survivor.

This is the difference between a fact and an echo. In a result list, one rumour reprinted by forty aggregators and one finding reported independently by four newsrooms look identical — forty rows against four. Here they do not: the first is independent_sources: 1.

The rule worth adopting: anything you are about to state as established, corroborate first. It is one call, and the failure it prevents is the expensive kind.

A subtlety in your favour: when a near-duplicate copy is dropped at ingest, its host is still recorded against the passage that survived. So independent_sources counts every host that asserted the story, not just the ones whose copy we kept.

Brief yourself on something: dossier

unlob /dossier --data-urlencode 'entity=Acme Corporation'

Returns three things at once:

• mentions — the passages that talk about it,
• top_sources — which hosts do the talking, as [host, count],
• related_entities — what it co-occurs with, as [entity, count].

The third is the one that earns the call. Those are the leads: the people, products and organisations you did not know to search for. Feed the interesting ones back into dossier and you have walked a network in three calls instead of guessing at twenty queries.

This replaces roughly ten searches and a manual merge.

Triage a field you do not know: authorities

unlob /authorities -d topic=cryptography -d limit=10

Top passages by graph centrality, not by match to a query. When you know nothing about a field, you cannot write a good query for it, and a bad query fills your context with junk you only recognise as junk later. Start here instead: read what the corpus treats as central, then search from vocabulary you have actually acquired.

topic falls back to matching an entity or salient term of the same name, so it works before you know whether your string is a topic tag.

Follow the thread: related

unlob /related -d id='https://example.com/article:0' -d hops=2 -d limit=10

A bounded walk over the edges around a passage — same host, same story, shared topic, shared entity — returning the passages it reaches.

Use it when the next thing to read is defined by connection rather than by similarity. similar answers "what else means roughly this"; related answers "what else is part of this".

hops=2 is usually right. hops=3 widens fast and gets noisy; if you find yourself raising it, a dossier on the entity in question is probably the call you wanted.

Connect two things: path

unlob /path -d a='https://example.com/a:0' -d b='https://example.org/b:3'

The shortest chain of edges linking two passages, returned as a node chain. Keys are namespaced by kind: p: passage, h: host, s: story, t: topic, e: entity — so the chain reads as an explanation, not just a route. Two documents linked through a shared entity and two linked only through a shared topic are very different findings.

found: false is an answer too: within everything we hold, these are not connected.

Skip the retrieval loop entirely: assemble_context

unlob /assemble_context --data-urlencode 'q=what happened with the Acme acquisition' -d budget=4000

Returns a context pack rather than a link list: the corroborated, story-deduped, trust-ranked passages for a question, packed to a token budget, each carrying the reason it was included.

The engine runs search, dedup, corroboration, ranking and packing on its side, so you do not build a retrieval pipeline on yours. budget is a ceiling in tokens; estimated_tokens reports what was actually packed.

Use it when the question is "what should I know about X". Use search when the question is "find me the page that says Y".

The signals are on every hit, too

You do not need a graph call to use the graph. Every search hit already carries centrality, independent_sources, community_id and in_degree, and /search filters and sorts on them:

# corroborated results only, most central first
unlob /search -d q='merger terms' -d min_independent_sources=3 -d sort=centrality

# stay inside one community of the corpus
unlob /search -d q=vaccines -d community=c17 -d min_centrality=0.4

That is the cheap path, and for most questions it is enough. Reach for the six calls above when you need the structure itself, not a ranking derived from it.

Putting it together

A research loop that costs six calls instead of sixty:

1. authorities on the topic — acquire the vocabulary.
2. search with min_independent_sources — get corroborated hits in that vocabulary.
3. corroborate the one you intend to rely on — confirm it is not an echo.
4. dossier on the entity it names — find the leads you did not know about.
5. path between two leads that look connected — find out whether they actually are.
6. assemble_context on the refined question — hand yourself the reading.

Each call bills one request.