DEV Community: Prosper Otemuyiwa

How to Use Jev: A practical guide to TypeSafe's System One model

Prosper Otemuyiwa — Thu, 17 Sep 2026 12:24:54 +0000

Jev is a frontier AI model from TypeSafe AI that returns typed, probabilistic decisions instead of generated text. You send program state plus typed questions; it answers all of them in one parallel pass in 70 to 500 milliseconds, at $0.042 per million input tokens with output free. It launched September 15, 2026 with $40M led by DCVC, built by Diogo Almeida, who co-invented RLHF and InstructGPT at OpenAI.

This is the practical guide: setup, the three primitives, five patterns worth stealing, the failure modes that will bite you, and what people shipped in the first 48 hours.

TypeSafe AI calls Jev, this class of model System One, after Kahneman's fast, intuitive thinking. The bet is that most decisions inside software are System 1 judgments ("which bucket is this?", "is this urgent?") and we have been renting System 2 to make them.

	Jev	Frontier LLMs
End-to-end latency	70ms to 500ms	3s to 329s
Input price	$0.042 / MTok	$0.20 to $10 / MTok
Output price	free	~5x input
Structured-output errors	0% (by construction)	0.58% to 45.5%

Caveat up front, and I come back to it at the end: those are TypeSafe's own numbers, self-run and unreproduced.

Setup

Get a key from console.typesafe.ai/settings/keys (early access is waitlisted) or from Vercel AI gateway and export it:

export TYPESAFE_API_KEY="sk-..."

Python (3.10+):

pip install typesafe-sdk
# or: uv add typesafe-sdk

JavaScript/TypeScript (Node 20+):

npm install @typesafe-ai/sdk

Both SDKs read TYPESAFE_API_KEY from the environment and default to jev-latest. There is one endpoint, POST https://api.typesafe.ai/v1/systemone, if you would rather call it directly.

The three primitives

The whole API is three question types. That is not a limitation you route around, it is the design.

Choice: one option from a set

Choice(
    instructions="Which team should handle this",
    criteria={
        "billing":   "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales":     "Pricing or account questions",
    },
)

Returns .choice, .probabilities (one per option), and .confidence. Takes up to 255 options, each costing a few tokens, so pass the full list of teams or categories rather than a shortlist. Add an explicit other option so the model can say nothing fits instead of picking the closest wrong thing.

Score: a position on a spectrum

Score(
    instructions="How frustrated the customer appears",
    criteria=[
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language",
    ],
)

Two to ten ordered levels, described in words. Returns .score as a position that can land between levels (1.035), plus .probabilities and .confidence. The level index comes from array order, so level 0 is the first entry.

Noul: yes or no, as a probability

Noul(instructions="The message conveys urgency or time-sensitivity")

Returns .noul, a single number from 0 to 1: the probability the answer is yes. No confidence field, because the number already is the belief.

Putting it together

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()

response = client.system_one(
    state={
        "ticket": {
            "subject": "Duplicate charge",
            "messages": [
                {"from": "customer",
                 "text": "I was charged twice for order A-104. Please refund the duplicate."},
            ],
        },
        "order": {"id": "A-104", "charges": [
            {"amount_usd": 49, "status": "captured"},
            {"amount_usd": 49, "status": "captured"},
        ]},
        "refund_policy": "Duplicate charges are eligible for a refund.",
    },
    questions={
        "department":       Choice(instructions="Which team should handle this",
                                   criteria={"billing": "Payment or subscription issues",
                                             "technical": "Bugs or integration problems",
                                             "sales": "Pricing or account questions"}),
        "frustration":      Score(instructions="How frustrated the customer appears",
                                  criteria=["Calm, just stating facts",
                                            "Frustrated but civil",
                                            "Very angry, strong language"]),
        "refund_requested": Noul(instructions="The customer is explicitly asking for a refund"),
        "policy_supports":  Noul(instructions="The stated refund policy covers this situation"),
    },
)

dept = response.answers["department"]
print(dept.choice, dept.confidence)
print(response.answers["frustration"].score)
print(response.answers["refund_requested"].noul)

The same in TypeScript:

import { choice, noul, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();

const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: "Payment or subscription issues",
      technical: "Bugs or integration problems",
      other: "Anything else",
    }),
    urgent: noul("The message conveys urgency"),
  },
});

console.log(response.answers.category.choice);  // types inferred from your questions

State is whatever you need it to be

A string, a JSON object, or an array of text. Use an object when there is more than one piece of context.

state = "My card was charged twice."                               # simple
state = {"message": "...", "order_id": "A-104"}                    # named fields
state = ["Hi", "My customer number is TS1337.", "Charged twice."]   # a conversation

Text only. No images, audio or video. Transcribe or caption first.

Context limits work differently from an LLM, because state is ingested once and questions run in parallel over it:

64k tokens for state and all questions together
32k tokens for state plus the single longest question

Five patterns worth stealing

Pattern 1: speculative fan-out

Questions are evaluated in parallel, so a tenth question costs tokens but almost no time. This inverts the usual instinct to make a cheap call first and a follow-up only if needed. Ask everything up front and let code decide what was relevant.

response = client.system_one(
    state=ticket,
    questions={
        "category":       Choice(instructions="Broad category of this ticket",
                                 criteria={"bug_report": "Something is broken or erroring",
                                           "billing": "Charges, invoices, refunds",
                                           "feature_request": "Asking for new functionality",
                                           "account": "Login, permissions, security"}),
        # only meaningful if it IS a bug report. Ask anyway.
        "bug_severity":   Score(instructions="How severe is the reported issue",
                                criteria=["Cosmetic; no impact",
                                          "Degraded feature; workaround exists",
                                          "Blocking; no workaround"]),
        "has_repro":      Noul(instructions="The user describes steps to reproduce"),
        # only meaningful if it IS billing. Ask anyway.
        "refund_wanted":  Noul(instructions="The user explicitly asks for a refund or credit"),
        "frustration":    Score(instructions="How frustrated the user appears",
                                criteria=["Calm", "Frustrated but civil", "Very angry"]),
    },
)

cat = response.answers["category"]

if cat.choice == "bug_report":
    if response.answers["bug_severity"].score > 1.5 and response.answers["has_repro"].noul > 0.6:
        escalate_to_engineering(ticket_id, severity="high")
    else:
        add_to_bug_backlog(ticket_id)
elif cat.choice == "billing" and response.answers["refund_wanted"].noul > 0.7:
    start_refund_flow(ticket_id)

TypeSafe's cookbook runs a 13-question regulatory briefing over a long Wikipedia article and reports that batching every question into one call is 12.2x cheaper and 10.0x faster with identical answers, versus asking one at a time.

Pattern 2: Confidence-gated routing

This is the one that changes your architecture. Jev is trained with RLCD (Reinforcement Learning for Calibrated Decisions), which optimises probabilities against outcomes rather than human preference. Confidence is therefore meaningful in aggregate: higher confidence really does mean higher accuracy.

So stop writing one threshold for the whole system. Write one per action, scaled to what being wrong costs.

action = response.answers["intent"]

if action.confidence < 0.5:
    route_to_human(user_message)                  # floor: genuinely unsure

elif action.choice == "check_balance":
    show_balance(account_id)                      # read-only, low bar

elif action.choice == "approve_transfer":
    if action.confidence > 0.85:                  # moves money, high bar
        approve_transfer(account_id)
    else:
        ask_user_to_confirm("Approve this transfer?")

else:
    route_to_human(user_message)

You also get the raw .probabilities if TypeSafe's confidence statistic is not the measure you want. A flat distribution means the options were not distinguishable from the state you gave it, which is frequently a signal that your criteria are wrong rather than that the model is confused.

Pattern 3: composite scoring

Break a fuzzy judgment into independent dimensions, score each atomically, and combine with weights you control. This beats asking "how good is this candidate," which hides several judgments inside one answer.

response = client.system_one(
    state=resume_text,
    questions={
        "python_depth":    Score(instructions="Depth of Python experience shown",
                                 criteria=["None mentioned", "Mentioned, no detail",
                                           "Used in projects", "Primary language",
                                           "Deep expertise: architecture, performance"]),
        "team_leadership": Score(instructions="Experience leading engineering teams",
                                 criteria=["None", "Informal mentorship", "Led a small team",
                                           "Managed direct reports", "Managed multiple teams"]),
        "system_design":   Score(instructions="Experience designing distributed systems",
                                 criteria=["None mentioned", "Contributed to discussions",
                                           "Designed components", "Owned a system's architecture",
                                           "Designed at scale across domains"]),
    },
)

a = response.answers
composite = (
    0.40 * (a["python_depth"].score / 4) +
    0.25 * (a["team_leadership"].score / 4) +
    0.35 * (a["system_design"].score / 4)
)

Re-weighting is now a code change, not a re-prompt. You can A/B it.

Pattern 4: The Cascade

Jev is not a replacement for Opus 5 or GPT-5.6. It is the thing that decides which requests deserve one.

def handle(message):
    r = client.system_one(
        state=message,
        questions={
            "intent":     Choice(instructions="Primary intent of this message",
                                 criteria={"order_status": "Asking about an existing order",
                                           "product_question": "Asking about a product",
                                           "return_exchange": "Wants to return or exchange",
                                           "complaint": "Unhappy, wants resolution"}),
            "complexity": Score(instructions="How complex is this to resolve",
                                criteria=["Simple lookup or standard procedure",
                                          "Requires judgment or multiple steps",
                                          "Unusual edge case, escalation needed"]),
        },
    )
    intent, complexity = r.answers["intent"], r.answers["complexity"]

    if intent.confidence < 0.5:
        return route_to_human(message)

    if intent.choice == "order_status":
        return lookup_order(message)                      # pure code, no LLM at all
    if intent.choice == "product_question":
        return handle_with_llm(message, PRODUCT_SPECIALIST)
    if intent.choice == "return_exchange":
        return handle_with_llm(message, RETURNS_SPECIALIST)
    if intent.choice == "complaint":
        if complexity.score > 1 or complexity.confidence < 0.5:
            return route_to_human(message)
        return handle_with_llm(message, COMPLAINT_RESOLUTION)

One branch never touches a model. Two load different specialists. One escalates.

On a million tickets, using TypeSafe's per-case figures, that is roughly $6,480 instead of $30,400, with around 800,000 answered in under half a second instead of ten.

Pattern 5: Retrieve, then judge

There is a step in that cascade Jev does not perform, and it sets the ceiling on everything after it.

Jev has no knowledge of the world beyond the state you hand it. It cannot look anything up. And the jaggedness page is blunt that accuracy falls as state fills with material the question does not need: "retrieve and filter in code first, and send only the fields the question needs."

Read those together and the consequence is sharp. Whatever assembles the state decides what Jev is allowed to know. Pad it and you lose accuracy to context rot. Ground it in a weak source and Jev returns a well-calibrated judgment about bad material, because the state is the only world it has.

So the full pattern is two layers: fetch precisely, then judge cheaply.

from valyu import Valyu
from typesafe_sdk import Noul, Score, TypeSafeClient

valyu = Valyu()          # reads VALYU_API_KEY
jev = TypeSafeClient()   # reads TYPESAFE_API_KEY

# 1. Retrieval: primary sources, filtered before anything reaches the model.
hits = valyu.search(
    "GLP-1 receptor agonists cardiovascular outcomes",
    included_sources=["valyu/valyu-pubmed", "valyu/valyu-arxiv"],
    start_date="2024-01-01",
    max_num_results=20,
    relevance_threshold=0.5,
)

# 2. Judgment: one bounded call per paper, roughly $0.0004 each.
shortlist = []
for paper in hits.results:
    verdict = jev.system_one(
        state={"title": paper.title, "source": paper.url, "content": paper.content},
        questions={
            "is_rct": Noul(
                instructions="This paper reports a randomised controlled trial"),
            "reports_mace": Noul(
                instructions="The paper reports major adverse cardiovascular events as an outcome"),
            "evidence_strength": Score(
                instructions="How strong is the causal evidence presented",
                criteria=["Anecdotal or preclinical",
                          "Observational",
                          "Single randomised trial",
                          "Meta-analysis of randomised trials"],
            ),
        },
    )
    a = verdict.answers
    if a["is_rct"].noul > 0.7 and a["evidence_strength"].score > 1.5:
        shortlist.append((paper, a["evidence_strength"].confidence))

Twenty papers screened on four dimensions for well under a cent, against primary literature rather than whatever a general crawl surfaced.

This generalises past literature review. It is the same shape as TypeSafe's own RAG passage classification and citation check cookbooks: retrieve wide, then use a Noul per passage to filter for relevance before anything expensive sees it. At $0.042/MTok with free output, the filter costs less than the context window it saves.

What people shipped in the first 48 hours

Jev launched September 15. So treat these as launch-week artefacts, not production case studies, and note that all figures are self-reported by their authors. Be discretionary in your adoption.

1,018 research papers classified for $0.08

1kpapers.com by Hassan El Mghari (thread)

The clearest demonstration of the economics, because it runs a generative model and a decision model in the same pipeline and shows the bill for each:

Summarise 1,018 papers with DeepSeek V4 Flash
Send title + summary + 24 candidate topics to Jev
Classify with one Choice
Visualise

Summaries: $3.99. Classifications: $0.08. Median end-to-end latency 256ms per paper.

"I think this is where things are heading: different models for different parts of the workflow, instead of using one model for everything."

He also notes he is running evals on the Jev classifications before replacing the existing ones, which is the right instinct and the one most launch-week demos skip.

A browser agent that books a flight in 7.1 seconds

browser-use/jev-ultrafast · 641 stars · Python

Gregor Zunic (Browser Use) built a browser agent with a dynamic, indexed action space. Each observation turns the page into a numbered element table. One Jev request picks both the operation (CLICK, TYPE_TEXT, SELECT, SCROLL, WAIT, DONE, BLOCKED) and its target. A small LLM runs only when the operation is TYPE_TEXT.

Zürich to London on real Google Flights in 7.1 seconds, $0.0039, page loads included.

The design trick is speculative fan-out applied to actions: click, type and select targets are all asked in the same round trip, and only the one matching the chosen operation executes. Two decisions, one network call.

Computer use at $0.0002 per step

awlevin/typesafe-computer-use

Drives a Mac toward a plain-English goal without sending screenshots to a large model. OCR reads the screen, Jev picks the next action, a writing model is called only for free text.

	Jev	Opus 5 (bare screenshot)
Cost per decision	$0.0002	$0.032
Cost per 12-step task	$0.003	$0.40 to $0.90
Model latency	0.13 to 0.38s	5.2s
End-to-end step	~1.5s	~5.5s

The author's caveat is the most useful line in the repo: the frontier model read event dates off the pixels and compared them unaided, while the classifier needed explicit date parsing built around it. "Every piece of reasoning the frontier model does for free has to be rebuilt here as deterministic state."

A market maker deciding every ~300ms block

jarrodwatts/jev-trader

One decision per Monad block. Jev reads the Kuru MON-USDC order book and answers buy or sell; the bot posts a post-only limit order one tick inside the touch, so it earns the spread instead of paying it. Reported model latency in the event stream is around 81ms, and the hot loop makes exactly two RPC round trips to fit the block budget. Ships with a dry-run mode using real book data and simulated fills.

An autonomous drone with judgment at 2.5Hz

RomanSlack/jev-drone

Worth studying for how carefully it puts Jev in its place:

Rate	Layer	Owner
500 Hz	Geometric flight controller	Code
50 Hz	Guidance and safety reflex	Code, always owns safety
15 Hz	Camera to symbolic scene	Classical CV
~2.5 Hz	Tactical judgment	Jev, advisory only

Classical CV compresses depth and segmentation into range sectors, obstacle height and target bearing. Jev answers three questions in one call: a Choice over manoeuvres, a Score for risk, a Noul for whether the target is genuinely lost or briefly occluded. As the README says, Jev "cannot be the perception layer, and it cannot run at control rate."

Others worth a look

fhshaik/typesafe-mario (73★) plays Super Mario Bros from emulator RAM translated to object-centric JSON. No screenshots.
devagrawal09/jev-review (48★) is a staged code reviewer: Noul risk matrix, then Choice/Score file profiles, evidence selection, severity, conditional routing.
TheoLeeCJ/openjev (166★) reads typed option probabilities off a 4B open model's logits in one forward pass. It is explicit that it reproduces the interface pattern, not Jev's model or training.
phyous/tsai-sc has Jev complete the first StarCraft shareware mission across 421 decisions, with a verification report.
AbdelStark/awesome-typesafe indexes the ecosystem and labels which results rest on private data or single runs.

The pattern across every one of these: keep the loop, the safety and the arithmetic in ordinary code, and use Jev for the narrow judgment in the middle that code finds hard to phrase.

The failure modes (read this before you ship)

TypeSafe publishes a page called "jaggedness" listing what jev-1.13 is bad at. It is unusually honest for a launch and it will save you a week.

It reads literally. Jev answers the question you wrote, not the one you meant. Negations, scoping words and implied conditions land at face value. The tell: you look at a wrong answer and catch yourself explaining what you really meant. That explanation is the missing half of your instruction.

It is not a calculator. It does not count reliably, and error grows with the size of the thing counted. Iterate in code and ask one Noul per item:

result = client.system_one(
    {"items": items},
    {f"item_{i}": Noul(instructions=f"Is `items[{i}]` the name of a fruit?")
     for i in range(len(items))},
)
count = sum(result.nouls[f"item_{i}"].noul > 0.5 for i in range(len(items)))

Dates are text to it, not ordered quantities. Which date came first, how far apart, whether one falls in a window: all unreliable. Extraction is judgment, so use a Choice over enumerated months and days with an explicit "not stated" option. Assembly and ordering are arithmetic, so keep them in code.

Context rot is real. Accuracy falls as state fills with material the question does not need. Retrieve and filter first.

State is not treated as hostile. Text engineered to argue for its own classification can move the answer. If you put user-controlled content into state, that is your threat model to handle. Test it.

Contradictory instructions and criteria confuse it. A Noul where true maps to "no" will underperform. Treat criteria as an extension of the instruction.

It does not generate. No text, no code, no summaries. If you need a value extracted from free text, get candidates with a regex or a generative model and let Jev pick.

The meta-rule from their docs, which is good design advice generally:

Avoid asking the model something code can compute exactly. Avoid hiding several judgments inside one question.

Operational notes

Rate limits for jev-1.13 are 250,000 tokens/second and 1,200 requests/minute. Over either returns 429. Both SDKs retry with exponential backoff and honour retry-after. TypeSafe warns these limits are moving without notice while GPU capacity lands.

Pin your version if you tune thresholds. jev-latest currently resolves to jev-1.13.0 and will move when a new release ships, which can change answers under you. The response's model field reports the versioned ID that answered, so log it.

client = TypeSafeClient(model="jev-1.13.0")   # pin

Billing is input-only. Output tokens are free, which is why speculative fan-out is cheap and why adding options to a Choice costs almost nothing.

There is an agent skill if you build with a coding agent:

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai
# or, for other agents:
npx skills add typesafe-ai/skills --skill typesafe-ai

The honest scorecard

On TypeSafe's four-workflow evaluation, Jev scores 67.8%, level with GPT-5.6 Terra (67.9%), behind Sol (74.1%) and Opus 5 (73.1%), at roughly 1/200th the cost and 1/50th the latency.

The line that lands hardest: Claude Sonnet 5 scores exactly 67.8% too, at 293x the cost per case and 195x the latency.

Four things to hold onto:

That column is not accuracy. There is no ground truth. TypeSafe builds consensus labels by averaging GPT-6 Astra and Claude Fable 5.1 at high thinking, then scores everyone against those. It measures agreement with two frontier models, which is why neither appears in the results. TypeSafe says this biases toward OpenAI and Anthropic.
It is self-run. TypeSafe designed the workflows, built the harness, ran it. No independent reproduction exists. Evaluate on your own traffic.
"Cannot hallucinate" is narrower than it sounds. Jev cannot return an invalid value. It can return the wrong valid one. The 0% is asserted, not measured: "Our number is not empirical. Schema matching is guaranteed, thus we can confidently add 0% into the plots." The 45.5% comparison is a single outlier (Haiku 4.5); most models sit between 0.58% and 13.2%.
The price may move. TypeSafe cannot prove it is not subsidised, though it says it expects the price to fall rather than rise.

When I would actually use this

Yes: routing and triage, moderation, relevance filtering before an expensive context window, scoring or guardrailing LLM output, tagging at volumes that were previously uneconomic, anything sub-second inside a request handler.

No: generating anything, arithmetic or counting or date math, decisions needing a written rationale for an auditor, one-off complex reasoning, genuinely open answer spaces.

The useful mental shift is that this is not a cheaper LLM. It is a different primitive: a function call that happens to be intelligent, returns a type, and tells you how much to trust it. Once you have that, a lot of code that exists only to survive string output stops needing to exist.

FAQ

What is Jev? A frontier model that returns typed, probabilistic decisions instead of text, in 70 to 500ms.

How much does it cost? $0.042 per million input tokens, output free. About $0.0004 per case on TypeSafe's benchmark.

Can it hallucinate? It cannot return a value outside your schema. It can return the wrong valid value.

Can it write code or prose? No. Not trained to generate text at all.

What are Choice, Score and Noul? The three question types: one-of-N (up to 255), a position on a 2 to 10 level scale, and a yes/no probability.

How do I get access? Waitlisted early access at typesafe.ai; keys at console.typesafe.ai.

Should I replace my LLM? No. Cascade: Jev classifies and routes cheaply, code handles what it can, a frontier model takes the hard minority.

Global Fail Map: An open-source map of failed companies, cancelled megaprojects, and dead tech.

Prosper Otemuyiwa — Fri, 11 Sep 2026 16:24:52 +0000

Quick answer: Global Fail Map is a free, open-source research app that maps failed companies, cancelled megaprojects, abandoned inventions, terminated science programs, and futures that never arrived. It ships with 200 curated stories, custom map markers for different failure categories, sourced Markdown reports, random discovery, and live Valyu DeepResearch for new places or ideas. Try it or fork it.

We built Global Fail Map because we wanted a better way to study ambitious failures.

This is a startup-postmortem theater and not "10 lessons from Theranos". This is not a motivational thread pretending every dead company died from one neat cause.

I wanted the map. Failure is easier to understand when it has coordinates and real people behind it.

What does Global Fail Map do?

Global Fail Map gives you a globe covered in documented attempts that did not reach their intended future.

The first version ships with 200 curated stories across five categories:

Companies
Megaprojects
Science
Technology
Visions

Each category has its own marker symbol and companies do not look like bridges. Science does not look like planned cities. Clusters get their own symbol too, because a group of seven stories should not pretend to be one random case.

Click a marker and you get the short version. Open the report and you get the longer version with citations.

The point is simple: if someone spent years and millions, or billions, discovering that a plan did not work, we should not throw away the evidence.

Why this is useful

Most builders study winners all their lives. Understandable but winners are easier to sell, to write about, and to compress into a clean story.

If you are actually building something, the failures are often more useful.

Concorde is not just a plane story. It is a unit economics story.

Fordlandia is not just an odd Henry Ford story. It is a lesson in ignoring local systems.

Theranos is not just fraud. It is what happens when verification becomes socially expensive inside an organization.

The Texas supercollider, the Superconducting Super Collider, is not just a cancelled science project. It is a reminder that science still needs political durability.

Juicero is a hardware margin, distribution, and necessity problem wearing a very expensive shell.

Global Fail Map shows you what broke, where, and what survived?

Who should use it?

Use Global Fail Map if you are:

A founder studying why companies die before you copy a playbook from the winners
A developer interested in dead platforms, abandoned hardware, and weird infrastructure
A journalist looking for sourced starting points instead of recycled summaries
A student or teacher looking for better case studies
A researcher studying technology, infrastructure, science, planning, or economic history
A policy analyst trying to understand how public projects get stuck
A curious person who enjoys falling into very expensive rabbit holes

You do not need to be a coder but if you do code, the repo is there.

What happens when you click a marker?

Every atlas entry has structured metadata:

Title
Subtitle
Location
Country
Coordinates
Category
Status
Period
Summary
Lesson
Report path
Source links

The report goes deeper. It explains what was attempted, why it mattered, what changed, what evidence supports the ending, what is uncertain, and what remained afterwards.

Some failures leave ruins, court records, and patents. Some leave safety rules and successor projects, while some leave nothing but a domain name and a bankruptcy docket.

The Five Categories

Companies: dissolved companies, bankrupt firms, discontinued corporate programs, dead platforms, and business models that did not survive contact with the market.
Megaprojects: cancelled railways, unfinished airports, ghost metros, dams, ports, bridges, energy projects, new capitals, and public works that got trapped between money, politics, land, and engineering.
Science: terminated trials, withdrawn claims, medical failures, research scandals, and large scientific programs that ended because evidence, safety, cost, or governance broke the plan.
Technology: abandoned inventions, discontinued devices, dead computing platforms, failed vehicle programs, unreleased products, and technical bets that did not become the future.
Visions: utopian settlements, planned cities, charter city proposals, speculative districts, and grand designs that looked better in the model than in the world.

Why the map markers matter

I did not want a generic pin map. Generic pins make every story feel the same. A failed airline, a cancelled dam, a dead clinical trial, and an abandoned planned city need different visual language.

So the app uses custom marker symbols. A company marker reads differently from an infrastructure marker. Science, technology, and vision cases have their own shapes. Dense areas group into clusters so you can explore without visual noise.

The marker system is small, but it changes the feeling of the app. It turns a list of failures into an atlas.

The part I love the most is: the Random story Feature

Search is there when you know what you want. Random story is there when you don't want to type and just explore fast!

Press it and the app throws you into the archive. One click might land on a failed airship company. The next might land on a cancelled nuclear plant, a ghost metro, a dead social network, or a futuristic city that never became more than a promise.

This is the feature that makes the app feel less like a database and more like a museum with trapdoors.

The research mode

The pre-built 200 stories are not the whole idea. The app also gives you the ability to run on live deepresearch.

Search for a place, project, company, or idea. Choose the effort level. Let it run. The app tracks progress and gives you a sourced report when it is done.

Examples:

"Cancelled smart-city projects in Africa"
"Failed electric vehicle startups in California"
"Abandoned nuclear projects in Eastern Europe"
"Dead social networks in Asia"
"Unrealized capital city projects"

That makes Global Fail Map both an archive and a research workflow.

How this is different from a chatbot

Sometimes a chatbot is the right tool. If you need a fast explanation of Concorde, ask a chatbot.

But a chatbot does not give you a globe. It does not let you browse by marker type and also does not keep a curated atlas of 200 sourced cases. It does not treat location as part of the evidence.

Here is the comparison:

Need	Chatbot	Global Fail Map
Quick explanation	Yes	Yes
Geographic browsing	No	Yes
Category-specific markers	No	Yes
Curated failure archive	No	Yes
Source-backed reports	Sometimes	Yes
Random discovery	Not really	Yes
Fresh deep research	Sometimes	Yes, through Valyu

Use a chatbot for orientation. Use Global Fail Map when the geography and evidence matter.

Tech stack

The app is built with:

Next.js 15 App Router
React 19
Tailwind CSS
Mapbox GL JS with globe projection
Zustand
react-markdown and remark-gfm
zod
Valyu DeepResearch API
Vercel Analytics

The bundled data lives in src/data/examples.json. Cached reports live in public/reports.

The curation pipeline lives under scripts/ and includes validation, draft generation, and merge scripts.

Running it locally

Clone the repo:

git clone https://github.com/yorkeccak/global-fail-map.git
cd global-fail-map
pnpm install

Create an environment file:

cp .env.example .env.local

Set the basics:

NEXT_PUBLIC_APP_MODE=self-hosted
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk_your_public_token
VALYU_API_KEY=valyu_your_api_key

Run it:

pnpm dev

Open http://localhost:3000.

How the bundled reports work

Each bundled report is a cached Markdown file. The app does not need to regenerate those on every page load.

The story metadata and source list live in src/data/examples.json. The readable report body lives under public/reports.

There is also a curation workflow for adding more cases safely:

npx tsx scripts/check-curated.ts scripts/curated/africa.json
npx tsx scripts/build-entries.ts
npx tsx scripts/merge-entries.ts

The merge step guards against duplicate IDs, malformed entries, missing coordinates, weak lessons, and missing sources.

This matters because a map like this gets bad quickly if the data discipline slips.

Good First stories to open

If you want to understand the range of the app, try these:

Fordlandia
Concorde
Theranos
Juicero
Project Cybersyn
The Texas supercollider, the Superconducting Super Collider
N-1 lunar rocket
Ryugyong Hotel
New Harmony
The Line

They are different kinds of failure, which is the point.

Some are technical. Some are political. Some are financial. Some are cultural. Some are evidence failures. Some are coordination failures. Some were bad ideas. Some were good ideas wrapped in bad assumptions.

Frequently asked questions

What is Global Fail Map?

Global Fail Map is an open-source research atlas that maps failed companies, cancelled megaprojects, abandoned inventions, terminated science programs, and unrealized visions. Each marker links to a sourced story and report.

Is it open source?

Yes. The repository is on GitHub.

What is included in the first release?

The bundled atlas includes 200 curated stories across companies, megaprojects, science, technology, and visions.

Does it use AI?

The app includes live research through Valyu DeepResearch. The bundled atlas itself is curated and cached into structured data plus Markdown reports.

Can I self-host it?

Yes. You need Node.js, pnpm, a Mapbox public token, and a Valyu API key if you want live research.

Can I add more failures?

Yes. The repo includes scripts for checking curated entries, building draft entries, and merging them into the atlas.

Why study failed projects?

Because failed projects show constraints that success stories hide: financing, law, geography, safety, culture, trust, timing, and demand.

Where can I try it?

Try the hosted app or fork the code.

The thing I hope people do with it

I don't want Global Fail Map to make people less ambitious. In fact, I desire the opposite.

The kind that checks old ruins before pouring new concrete. That reads the trial record before believing the pitch and studies demand before building hardware. The kind that asks whether politics, land, financing, safety, and trust are part of the technical system.

If you are building something serious, use the map first. Maybe your idea is new or even older than you think.

Either way, the failures are waiting to teach you.

25+ GPT-6 Astra Creations Every Developer Should See And How to Enrich them with Real World Datasets

Prosper Otemuyiwa — Mon, 07 Sep 2026 11:27:50 +0000

TL;DR: The best GPT-6 Astra examples so far are not simple chatbots. They are playable games, 3D worlds, CAD workflows, Blender experiments, computer-use demos, model-routing tools, and agent orchestration projects. The next step is grounding those creations with real data. That is where Valyu fits: Astra can build the interface or agent loop, while Valyu supplies cited search, research, web content, academic, financial, medical, geospatial, and other datasets.

What is GPT-6 Astra?

GPT-6 Astra is OpenAI’s frontier model for difficult end-to-end work, including coding, tool use, browsing, computer-use workflows, long-context tasks, and professional automation.

The public model ID used in examples is gpt-6-astra.

Useful starting points:

This article focuses on public creations and showcases connected to GPT-6 Astra. It intentionally excludes unrelated Astra results such as Astra DB, AstraZeneca, WordPress Astra themes, and Google Project Astra.

Selection Criteria

I don't want AI-slop, so these were the things I considered:

public demo, repo, creator post, or credible discussion
concrete artifact, not just a vague claim
technically or visually interesting
runnable where possible
no empty repos
no SEO repost farms
no unrelated “Astra” projects

Added Confidence labels to differentiate:

High: public repo and/or live demo with a matching creator/project trail.
Medium: credible public demo, creator post, or repo, but not fully reproducible from the article alone.
Low: thin signal only. I excluded those from the main list.

Best GPT-6 Astra Creations and Showcases

#	Project	Type	Repo	Demo / Evidence	Confidence
1	GPT-6 Astra One-Shot Games	Browser games	GitHub	Melon game, Mosswing	High
2	Red Alert 2 Browser Recreation	Browser RTS	GitHub	Live demo	High
3	Astra Plays GTA Vice City	Computer-use / game agent	GitHub	Creator post	High
4	NULLSPACE	Game project	GitHub	Live site	High
5	Holographic 3D Cards	Blender / Three.js tooling	GitHub	Gallery	High
6	GPTBlender Floor Plan to 3D Model	3D workflow	GitHub	Walkthrough	High
7	Universe Duel	Browser game	—	Live demo, creator post	Medium
8	Elderwood Realms	Multiplayer browser world	—	Live demo, creator post	Medium
9	Rogue Arena Prototype	Game prototype	—	Live demo, creator post	Medium
10	Verdant Forest	3D web scene	—	Live demo, creator post	Medium
11	Seoul 3D Atlas	3D city atlas	—	Live demo, creator post	Medium
12	Walk Through Van Gogh	Interactive 3D world	—	Live demo, creator post	Medium
13	3D Anatomy Site	Educational 3D UI	—	Showcase post	Medium
14	3D Game From Scratch	Game demo	—	Showcase post	Medium
15	Runtime-Generated Trains in Three.js	Procedural 3D	—	Showcase post	Medium
16	Zillow Listing to 3D Promo Video	Real-estate / video workflow	—	Showcase post	Medium
17	Drawing a Portrait in Canva	Computer-use design demo	—	Showcase post	Medium
18	House Photo to Full 3D Model	3D reconstruction	—	Showcase post	Medium
19	Steam Train Blender Build	Blender asset creation	—	Showcase post	Medium
20	KiCad PCB Layout	Electronics / CAD	—	Showcase post	Medium
21	Interactive V8 Engine	Technical visualization	—	Showcase post	Medium
22	Hangzhou in Three.js	3D city scene	—	Showcase post	Medium
23	Robot Arm Control	Robotics / control	—	Showcase post	Medium
24	Agentic CAD Workflow	CAD agent workflow	—	Showcase post	Medium
25	Video Generation Showcase	Creative video workflow	—	Showcase post	Medium

Why These Examples Stand Out

The strongest Astra examples are interesting because they require coordination across multiple layers:

Games need physics, controls, state, rendering, rules, and feel.
3D worlds need spatial reasoning, visual hierarchy, performance, and interaction.
CAD and PCB examples need precision and domain constraints.
Blender workflows need stateful tool use, not just code output.
Computer-use demos require the model to operate real interfaces.
Agent orchestration projects test planning, delegation, routing, and verification.

A static landing page no longer proves much. A playable RTS, a 3D city, a PCB layout, or an agent controlling a game is a more meaningful test.

Useful GPT-6 Astra Tooling and Infrastructure

These are not all “wow” demos, but they are useful if you want to build with Astra.

Project	Repo / Link	Why it matters	Confidence
awesome-gpt-6-astra	https://github.com/Anil-matcha/awesome-gpt-6-astra	Curated index of Astra use cases, prompts, integrations, evaluations, and safety notes	High
MagicCreator Astra Gallery	https://magiccreator.ai/astra	Visual gallery of Astra demos and live links; verify individual entries before citing them separately	Medium
OpenAI Relay for Cursor	https://github.com/coreprocess/openai-relay-for-cursor	Practical relay for Cursor-style workflows	Medium
Astra Advisor	https://github.com/DannyMac180/astra-advisor	Advisor/orchestration-style project	Medium
Task Model Router	https://github.com/LunarXuan/task-model-router	Model-routing experiment for choosing when to use Astra	Medium
Dual Model MCP	https://github.com/Firnschnee/dual-model-mcp	Side-by-side model query harness using MCP	Medium
GPT-6 Astra 100 HTML Files	https://github.com/MiaAI-Lab/GPT-6-Astra-100-HTML-Files	Collection of generated HTML artifacts	Medium

The Missing Piece: Better Data

Many Astra demos prove that the model can create the shell:

a game
a dashboard
a 3D city
a 3D anatomy app
a real-estate promo
an agent workflow
a creative coding tool

But a shell is not a product. To become useful, these creations need grounded data: current facts, citations, structured datasets, research sources, financial filings, academic literature, geospatial data, medical references, patents, life sciences, news, and more.

That is where Valyu fits.

Relevant Valyu APIs:

Valyu API	What it does	Best use case
Search API	`POST /v1/search`	Finds information across web, academic, financial, news, and proprietary sources
Contents API	`POST /v1/contents`	Extracts clean LLM-ready content from URLs
Answer API	`POST /v1/answer`	Produces grounded answers with citations
DeepResearch API	`POST /v1/deepresearch/tasks`	Runs deeper multi-step research tasks
Datasources API	`GET /v1/datasources`, `GET /v1/datasources/categories`, `GET /v1/datasources/search`	Discovers available datasets

Valyu sources span academic, finance/company data, healthcare, Env & Geo, compliance, and web. Examples listed by Valyu include arXiv, bioRxiv, ChemRxiv, PubMed, SEC filings, earnings, stocks, ETFs, ClinicalTrials, DailyMed, PubChem, Open Targets, weather, air quality, disaster sources, sanctions lists, and public web content. Exact availability can change, so agents should confirm source IDs through the Datasources API before hard-coding them.

How Valyu Can Enrich Astra Creations

1. 3D Anatomy Apps

An Astra-generated anatomy app can use Valyu to pull from medical and scientific sources such as PubMed, ClinicalTrials.gov, DailyMed, ICD, PubChem, and Open Targets.

Instead of placeholder labels, the app can show sourced explanations, drug references, condition summaries, and citations.

2. Financial Dashboards

Astra can build the dashboard. Valyu can provide SEC filings, earnings data, stock data, ETF data, commodities, macroeconomic sources, and company research.

That turns a generated finance UI into something closer to a real research product.

3. 3D City Atlases

For demos like Seoul 3D Atlas or Hangzhou in Three.js, Valyu can add weather, air quality, disaster feeds, geocoding, local web context, environmental overlays, and news signals.

The result is not just a pretty map. It becomes a live information interface.

4. Real-Estate Demos

For a Zillow-style 3D promo workflow, Valyu can enrich the output with neighborhood information, weather, air quality, local amenities, risk signals, public web context, and market context.

Astra builds the experience. Valyu grounds the content.

5. Game Worlds

For games and interactive worlds, Valyu can help generate historically grounded settings, climate-informed environments, cultural references, local myths, geography, and current events.

This is how generated game worlds stop feeling generic.

6. Research Assistants

For agentic workflows, Valyu’s DeepResearch API can produce cited reports instead of shallow summaries.

This is useful for scientific research, market research, competitive research, policy analysis, technical literature reviews, and diligence workflows.

Agent Pattern: Astra Builds, Valyu Grounds

The pattern is simple:

Astra creates the app, simulation, game, workflow, or agent.
The agent decides what data it needs.
The agent calls Valyu Search, Contents, Answer, or DeepResearch.
Astra uses the cited results to update the creation.
The app preserves sources instead of hallucinating facts.

Here is a simplified TypeScript-style sketch. It is illustrative, not copy-paste SDK code: it omits x-api-key headers, uses a generic post() helper, and uses a placeholder astra.generate() function.

const valyuTools = {
  search: async (query: string) => {
    return post("https://api.valyu.ai/v1/search", {
      query,
      search_type: "all",
      max_num_results: 10
    });
  },

  contents: async (urls: string[]) => {
    return post("https://api.valyu.ai/v1/contents", {
      urls,
      response_length: "medium",
      extract_effort: "high"
    });
  },

  answer: async (query: string) => {
    return post("https://api.valyu.ai/v1/answer", {
      query
    });
  },

  deepResearch: async (query: string) => {
    return post("https://api.valyu.ai/v1/deepresearch/tasks", {
      query,
      mode: "standard",
      output_formats: ["markdown"]
    });
  }
};

async function enrichAstraCreation(goal: string) {
  const researchPlan = await astra.generate({
    model: "gpt-6-astra",
    input: `
      We are enriching this generated app or demo:

      ${goal}

      Decide whether you need quick search, URL extraction,
      cited answer synthesis, or deep research.

      Return:
      - the best Valyu tool to call
      - the query
      - why that data is needed
    `
  });

  const data = await valyuTools.answer(researchPlan.query);

  return astra.generate({
    model: "gpt-6-astra",
    input: `
      Improve the creation using this cited Valyu data.

      Rules:
      - preserve citations
      - do not invent facts
      - separate sourced facts from generated content
      - keep the UI/game/world coherent

      Goal:
      ${goal}

      Valyu data:
      ${JSON.stringify(data)}
    `
  });
}

Example Prompt: Build a Real World Data Enriched 3D City Atlas

Build a 3D city atlas of Seoul.

Use Valyu to gather:
- current weather
- air quality
- district-level context
- local transport information
- recent public events
- relevant environmental signals

Then create a layered 3D interface where users can toggle:
- weather
- transit
- air quality
- local events
- neighborhood summaries

Every factual panel must include sources.

Example Prompt: Build a Real World Data Enriched Anatomy Explorer

Build a 3D anatomy explorer for the cardiovascular system.

Use Valyu to retrieve:
- PubMed references
- clinical trial context
- drug information from DailyMed
- ICD condition mappings
- plain-English medical explanations

The app should include:
- 3D organ visualization
- sourced condition explanations
- drug references
- citations
- a disclaimer that it is educational, not medical advice

Example Prompt: Build a Real World Data Enriched Real-Estate Experience

Turn this property listing into a 3D interactive promo.

Use Valyu to enrich it with:
- neighborhood context
- weather
- air quality
- local amenities
- disaster or climate risk signals
- local market context

Create:
- a 3D property tour
- a neighborhood summary
- sourced local context cards
- a buyer-facing PDF summary

Best Astra + Valyu App Ideas

If I were building from this trend, I would skip generic chatbots and build one of these:

A cited 3D anatomy explorer
A filing-aware investor dashboard
A live city intelligence atlas
A property research agent
A scientific literature visualizer
A patent landscape explorer
A game world builder grounded in geography and history
A robotics/CAD research assistant
A climate-aware real-estate explorer
A medical education simulator with citations

The common pattern: Astra handles the interface and orchestration; Valyu handles the grounded data layer.

FAQ

What are the best GPT-6 Astra demos?

The strongest public examples I found are GPT-6 Astra One-Shot Games, Red Alert 2 Browser Recreation, Astra Plays GTA Vice City, NULLSPACE, Holographic 3D Cards, GPTBlender floor-plan modeling, Universe Duel, Walk Through Van Gogh, Seoul 3D Atlas, and the KiCad PCB layout showcase.

Are all GPT-6 Astra demos open source?

No. Some of the best examples are live demos or creator posts without GitHub repos. Where a repo exists, I included it. Where it does not, I labeled the item as a demo or social showcase rather than a runnable project.

Why not list 100 GPT-6 Astra creations?

Because I could not verify 100 high-quality examples without including weak or unrelated results. A smaller, cleaner list is more useful than a padded roundup.

How can developers use Valyu with GPT-6 Astra?

Developers can expose Valyu APIs as tools to an Astra-powered agent. The agent can call Valyu Search for source discovery, Contents for URL extraction, Answer for cited synthesis, DeepResearch for longer reports, and Datasources to discover available datasets.

What kinds of Astra apps benefit most from Valyu?

The best fits are apps that need grounded data: 3D atlases, financial dashboards, medical/anatomy explorers, real-estate tools, research assistants, patent explorers, and world building systems.

Final Takeaway

The best GPT-6 Astra examples are not chatbots. They are playable browser games, 3D worlds, CAD workflows, Blender experiments, computer-use demos, model-routing tools, and agent orchestration projects.

But the next wave should be more grounded.

Astra can create the interface. Valyu can provide the real-world data.

That is how impressive demos become useful products.

The Best Academic Search API for Humans and AI Agents in 2026

Prosper Otemuyiwa — Wed, 02 Sep 2026 16:54:08 +0000

Quick answer: the best academic search API for AI agents in 2026 is Valyu, because it is the only one that returns the passage from a paper and its metadata in a single call, date-bounded and cited. OpenAlex (480M works) and Semantic Scholar (214M papers) are the citation graphs, Europe PMC is the open access full text source, and Consensus is the answer layer for humans.

The map, in one screen

Start here: Valyu is #1 for agents. The other four are specialists you route to for one job: a citation edge, an author graph, a full text XML file, a claim-level answer.

Valyu is the only one that returns retrieval and paper content in the same call. The actual passage from a specific paper, alongside preprints, clinical trials and biomedical records, date-bounded and traced to the primary source. That is the one thing an agent doing a real literature review needs, so it leads. The rest are ranked by how cleanly they slot in behind it.

Bibliographic APIs answer questions about papers. Only a retrieval layer answers questions about what the papers say.

If you are building an AI agent that reasons over scientific literature, you will end up needing more than one API: bibliographic metadata, citation graphs, preprints, peer-reviewed full text and clinical evidence.

The classic scholarly APIs (OpenAlex, Semantic Scholar) are excellent at records. They hand your agent a DOI, an abstract, a citation count and a link. Then your agent has to fetch, parse and chunk the actual paper, and half the time it hits a paywall. Primary sources like Europe PMC give you real text, but only for the slice of the literature that is open. Answer layers like Consensus do the synthesis for you, on their terms.

The short version: a domain-grounded academic layer like Valyu does both retrieval and paper content in a single call, so it anchors the stack. The other four are specialists you route to behind it. I have built a few research agents this way now. What I would like to see next is patents and people data folded into the same academic paper search.

Here is the map.

What does an AI research agent actually need from an academic API?

Most academic API roundups rank on corpus size and whether the free tier is generous. For an agent, the criteria are different:

Full text, not abstracts. An abstract tells you a paper exists. It does not tell you the sample size, the ablation, or which baseline they compared against. Agents that reason on abstracts hallucinate methods.
Chunked and retrievable. Does the paper come back as the relevant passage with a DOI attached, or as a 40-page PDF link your agent has to fetch, OCR and split?
Date bounding. Can you cap results at a date so a "state of the art as of March 2025" claim does not quietly absorb a paper published last week?
Citation structure. Some questions are retrieval questions (what did they find). Others are graph questions (who cited this, and did anyone fail to replicate it). Different APIs, and most stacks conflate them.
Access reality. Roughly half the literature that matters is paywalled. An API that returns metadata for papers your agent can never read is a lead generator, not a research tool.
Latency and chaining. A real literature question fans out into 10 to 20 sub-queries. A 1 request per second rate limit is not a minor inconvenience, it is an architecture constraint.
Agent integration. Is there a tool wrapper, an MCP endpoint, a clean REST call, or do you glue it yourself?

Keep those in mind, because they are where most "academic API" choices quietly fail for agents.

1. Valyu: why it ranks first for AI agents

An agent doing real research needs both in the same call: the specific passage from a specific paper, and the structured metadata around it (DOI, authors, citation, citation count, publication date), bounded by date and traced to the primary source. Valyu is the API purpose-built for that seam, which is why it tops the list.

It is a Search and DeepResearch API where you can pin the agent to arXiv, PubMed, bioRxiv, medRxiv, ChemRxiv, clinical trials and patents, or leave it open across all of them, and get chunked, tagged, date-filterable results back.

import { paperSearch, bioSearch, patentSearch } from "@valyu/ai-sdk";

// One tool for the literature, one for clinical and biomedical, one for IP
const tools = {
  paperSearch: paperSearch({ maxNumResults: 10 }),  // arXiv, PubMed, bioRxiv, medRxiv
  bioSearch: bioSearch({ maxNumResults: 8 }),       // trials, FDA labels, ChEMBL, Open Targets
  patentSearch: patentSearch(),                     // USPTO, prior art
};

Or as a plain REST call, scoped to specific datasets with a point-in-time bound:

curl -X POST https://api.valyu.ai/v1/search \
  -H "x-api-key: $VALYU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "CRISPR base editing off-target effects in primary human cells",
    "included_sources": ["valyu/valyu-pubmed", "valyu/valyu-biorxiv"],
    "start_date": "2024-01-01",
    "end_date": "2026-06-30",
    "response_length": "large",
    "max_num_results": 10
  }'

Two things in that call do the heavy lifting. response_length: "large" is the difference between an abstract and the methods and results your agent actually needs to reason over. start_date and end_date are what stop a survey agent from quietly citing a paper that did not exist when the question was framed.

Results come back with the metadata a citation needs already attached:

{
  "title": "Transformer Architecture for Protein Folding Prediction",
  "authors": ["Jane Smith", "John Doe"],
  "citation": "Smith, J., Doe, J. (2024). Nature Biotechnology, 42(3), 123-135",
  "citation_count": 45,
  "doi": "10.1038/s41587-024-12345",
  "publication_date": "2024-03-15",
  "content": "Detailed research content...",
  "source": "valyu/valyu-arxiv"
}

When one retrieval is not enough

DeepResearch is a multi-step task that fans out, reads and synthesises across sources. You kick one off and wait() on it, so a long investigation does not block your agent:

import { Valyu } from "valyu-js";

const valyu = new Valyu(process.env.VALYU_API_KEY);

// Kick off a multi-step research task
const task = await valyu.deepresearch.create({
  query: "What is the current evidence base for GLP-1 agonists in " +
         "non-diabetic obesity, and where do the trials disagree?",
  mode: "heavy",   // fast | standard | heavy | max
});

const report = await valyu.deepresearch.wait(task.deepresearch_id);
if (report.status === "completed") {
  console.log(report.output);   // cited markdown (or a PDF via outputFormats)
  console.log(report.sources);  // the primary sources it traced
}

The report comes back as cited markdown, traced to the same primary sources the search tools pull from, so the deep-research path and the single-call path share one grounding layer. That matters more in science than in most domains: if your literature review and your quick lookup disagree because they hit different indexes, you cannot trust either.

To get your agent to reach for this on its own, wrap it as a tool whose description draws a hard line between "look something up" and "go investigate this":

import { tool } from "ai";
import { z } from "zod";
import { Valyu } from "valyu-js";

const valyu = new Valyu(process.env.VALYU_API_KEY);

export const literatureReview = tool({
  description:
    "Run a deep, multi-step literature investigation and return one cited report. " +
    "Use this when the question needs synthesis across many papers, preprints and " +
    "trials (e.g. 'summarise the evidence for X and where the studies disagree'), " +
    "or when the answer depends on comparing methods across studies. " +
    "Do NOT use it to find a single paper, look up a DOI, or check a citation count " +
    "- use paperSearch for those; this runs for minutes and costs more. " +
    "Returns cited markdown plus sources.",
  inputSchema: z.object({
    query: z.string().describe("The full research question, in plain English."),
  }),
  execute: async ({ query }) => {
    const task = await valyu.deepresearch.create({ query, mode: "standard" });
    const report = await valyu.deepresearch.wait(task.deepresearch_id);
    return { report: report.output, sources: report.sources };
  },
});

The Do NOT line is doing the real work. Without an explicit boundary, models over-call the slow tool on trivial questions and under-call it on the hard ones.

Match the mode to the loop. There are four:

Mode	Runtime	Rough cost
`fast`	~5 minutes	~$0.10
`standard` (default)	10 to 20 minutes	~$0.50
`heavy`	30 to 90 minutes	~$2.50
`max`	up to a few hours	~$15

The old lite mode is deprecated and maps to standard. For anything above standard, skip wait() and pass a webhookUrl to create() so the finished report POSTs back and the agent stays responsive. The webhook_secret comes back only once, on create.

Note: the snippets use Vercel AI SDK v5 (inputSchema). On v4 the field is parameters.

2. OpenAlex: is it still free in 2026?

Not entirely, and this is the biggest change in the academic API landscape this year.

OpenAlex is the open replacement for Microsoft Academic Graph, and the best free bibliographic index in existence: 480 million works, plus authors, institutions, venues and concepts, all linked. If your question is about the shape of a literature rather than its content, this is where you go.

curl "https://api.openalex.org/works\
?search=graph+neural+networks+molecular+property\
&filter=from_publication_date:2025-01-01\
&api_key=$OPENALEX_KEY"

The graph is the product. You can walk from a paper to its authors to their institutions to everything else that institution has published on a topic, in a handful of calls, without a licensing conversation.

The pricing change: as of 13 February 2026, keys are mandatory and usage beyond a daily allowance is priced. Single-work lookups by DOI or ID stay free, and the bulk data download remains free.

3. Semantic Scholar: what are the rate limits?

The introductory rate limit on an individual API key is 1 request per second across all endpoints. Higher limits are granted only after a review. That is the number that decides whether Semantic Scholar can sit on your critical path. It usually cannot.

Allen Institute for AI's academic graph holds 214 million papers, 2.49 billion citations and 79 million authors, plus the extras that make it more useful to an agent than a raw index: TLDR summaries, SPECTER2 embeddings, and influential-citation counts that separate a real intellectual debt from a drive-by reference.

curl -H "x-api-key: $S2_API_KEY" \
  "https://api.semanticscholar.org/graph/v1/paper/search\
?query=retrieval%20augmented%20generation\
&fields=title,abstract,tldr,citationCount,openAccessPdf"

That openAccessPdf field is the single most useful field on this list, because it tells your agent whether it can actually read the thing before it wastes a fetch. It comes back with a URL, an OA status colour and a licence note, so you can gate retrieval on licence rather than hope. Pair it with the separate Recommendations API and you have a decent "papers like this one" loop for free.

4. Europe PMC: how do you get open access full text?

Two calls. Search, then fetch the XML by PMCID.

Europe PMC is PubMed's more agent-friendly cousin. It holds about 48.8 million records, of which roughly 12.1 million have full text in Europe PMC and about 8.1 million are open access, plus 1.2 million preprints and grant metadata, in one REST API that speaks JSON and does not make you do the ESearch then EFetch dance.

curl "https://www.ebi.ac.uk/europepmc/webservices/rest/search\
?query=CRISPR%20AND%20SRC:PPR&format=json&pageSize=25"

# then, for anything in the open access subset
curl "https://www.ebi.ac.uk/europepmc/webservices/rest/PMC1234567/fullTextXML"

The SRC:PPR filter in that first call scopes to preprints, which matters because PubMed only indexes preprints reporting NIH-funded research, through the NIH Preprint Pilot. Everything else is absent, and in fast-moving biology the preprint is where the finding lands first.

Both calls above are live as written: the search returns 13,552 hits for that CRISPR query, and the second returns JATS XML.

5. Consensus: should you build on it, or on Elicit?

Neither, if you are building an agent you control. Both, if you are a human doing a literature review this afternoon.

Consensus sits one level above the APIs and does the synthesis for you: a search engine over 220M+ papers that returns claim-level answers with study metadata, sample sizes and journal quality signals, rather than a list of links. It has a REST API, and API plus MCP usage draw on one monthly pool of calls tied to your subscription tier, with overage at $0.10 per call. Higher-volume API access is quoted rather than self-serve.

It belongs on this list for two reasons. First, if your users are researchers, this is the bar. When someone asks your agent "does creatine improve cognition" they are comparing your answer to the one Consensus gives them, with its yes/no/mixed meter and its study quality badges. Second, for a human doing early-stage literature work it is genuinely faster than building anything.

One pool feeds both doors. And the reason you would still build your own: the pipeline is theirs, not yours.

How to choose: route by question type

Do not pick one. Route by question type.

Your agent's question	Route to	Why
"What did the paper actually find or measure?"	Valyu	Returns the passage plus DOI, authors and date in one call
"Summarise the evidence and where studies disagree"	Valyu DeepResearch	Multi-step fan-out, one cited report, same grounding layer
"Who cited this, and did anyone replicate it?"	OpenAlex or Semantic Scholar	Citation edges and author graphs, not content
"What has this lab or institution published?"	OpenAlex	Works, authors, institutions and venues are linked
"Can my agent legally read this paper?"	Semantic Scholar (`openAccessPdf`)	OA status and licence before you spend a fetch
"Give me the full JATS XML of this biomedical paper"	Europe PMC	Free, open, two calls, includes preprints via `SRC:PPR`
"I am a human and I need an answer in 30 seconds"	Consensus	Claim-level answers with study quality signals
"arXiv and PubMed together, one schema"	Valyu	One query interface, shared date filtering, one result shape

The rule of thumb I have landed on:

Bibliographic APIs for questions about papers, domain-grounded retrieval for questions about what the papers say, and answer layers for humans in a hurry.

Most real research agents need at least the first two. The engineering that actually matters is not picking a winner, it is routing between them cleanly instead of forcing one API to do a job it was never built for.

Valyu is also shipping more on their roadmap. Adding a graph to make the existing search more powerful might happen sooner than later.

The most common failure I see is an agent wired to OpenAlex or Semantic Scholar alone, producing confident summaries built entirely from abstracts. It reads well. It is frequently wrong about methods, and it has no way to know it is wrong. Add a retrieval layer that returns the text, and most of that class of error disappears.

FAQ

What is the best academic search API for AI agents?

For an agent doing real research, the decisive capability is returning retrieval and paper content in one call: the passage from the paper plus its DOI, authors and citation count, date-bounded and cited, which in this case is Valyu. OpenAlex, Semantic Scholar, Europe PMC and Consensus are each strong at one narrower job, and you route to them behind it.

Can I just use one API for a research agent?

Usually not, but Valyu gets you closest. It covers preprints, peer-reviewed literature, biomedical and clinical evidence, and patents through a single retrieval interface with date filtering. You will still want OpenAlex or Semantic Scholar if your question is genuinely about the citation graph rather than the science, and Europe PMC is a useful free fallback for open access biomedical full text.

What is the difference between a bibliographic API and a domain-grounded academic API?

A bibliographic API (OpenAlex, Semantic Scholar) returns records: title, authors, DOI, citation count, maybe an abstract. It is a catalogue. A domain-grounded academic API is scoped to scholarly primary sources and returns chunked, date-filterable content traced back to the paper itself. One tells you the paper exists. The other tells you what is in it.

Do academic APIs support date bounding for reproducible research?

This varies, and it is easy to get wrong. Valyu lets you bound results with start_date and end_date, so an agent answering "what was the state of the art in early 2025" cannot leak a paper from last month into the answer. OpenAlex and Semantic Scholar support publication-date filters on metadata. Where most stacks leak is on the retrieval side: the metadata is filtered but the retrieved text is not.

Are these APIs free?

Mostly, with real caveats in 2026. Europe PMC is free and open. Semantic Scholar is free with a 1 request per second key. OpenAlex changed in February 2026: keys are now required and usage beyond a daily allowance is priced. Consensus gates its API behind a paid plan, with calls shared against your MCP usage. Valyu gives you $10 in free credits to start, $20 with a work email.

Which academic APIs are free in 2026?

Europe PMC is free and open. Semantic Scholar is free with a key, capped at 1 request per second. OpenAlex changed on 13 February 2026: keys are now mandatory and usage beyond $1 a day is priced, though single-work lookups by DOI or ID stay free and bulk data download remains free. Consensus gates its API behind a paid plan, with calls shared against your MCP usage. Valyu gives you $10 in free credits, $20 with a work email.

What is the best API for searching arXiv and PubMed together?

Valyu, because both sit behind one query interface with shared date filtering and a single result schema. Querying them directly means two very different APIs: arXiv speaks Atom XML with a roughly one-request-per-three-seconds limit, and PubMed requires the two-step ESearch then EFetch pattern and returns abstracts rather than full text.

How much does Valyu cost to try?

Valyu gives you $10 in free credits at platform.valyu.ai, or $20 if you sign up with a work email, no credit card required. Enough to point it at a literature you already know well and inspect the citations. That is the fastest way to feel the difference between a link to a paper and the paper itself.

OpenAlex vs Valyu: A Feature-by-Feature Research Platform Comparison

Prosper Otemuyiwa — Fri, 28 Aug 2026 19:03:47 +0000

OpenAlex and Valyu solve similar research problems. Valyu is a search and DeepResearch API built for AI agents, built for retrieving full-text evidence with attached citations across academic literature, scientific research, papers, and specialist sources in a single call. OpenAlex is an open scholarly metadata graph of more than 322 million works, built for bibliometric discovery, citation analysis, and structured queries across works, authors, institutions, and topics.

Quick answer

Valyu gives you usage-based semantic retrieval of full-text passages with structured citations across academic literature, scientific research, papers, journals and specialist sources in a single call for both humans and AI agents. OpenAlex gives you an open scholarly graph of 322 million-plus works with structured metadata, filters, authors, institutions, topics, and citation relationships

What content can OpenAlex index?

OpenAlex indexes scholarly works as a connected graph. A "work" is any scholarly document: a journal article, conference paper, book or book chapter, dataset, dissertation, or preprint.

Works are split across two corpora, which is worth knowing before you compare headline numbers. The core is the curated catalogue and it is what every query returns by default: a live call to api.openalex.org/works in August 2026 gives 322,147,582 works. An expansion layer adds a rawer 165,253,218 records, mostly datasets and single-repository entries, and corpus=all returns both for 487,400,800. Every "320 million" figure you see quoted, including the one in this article, is the core.

The graph connects works to authors, sources (journals, conference proceedings, repositories), institutions, topics, keywords, funders, awards, and publishers. Bibliographic coverage is assembled from upstream indexes including Crossref, PubMed, DataCite, DOAJ, and arXiv.

The search parameter for works matches across title, abstract, and fulltext, and the fulltext.search filter covers the same three fields.

Separately, OpenAlex maintains a content archive of cached full text: 50M+ PDFs (roughly 250 TB) and ~43M TEI XML files parsed by Grobid. Filtering on has_content.pdf:true returns 52,407,611 works, every one of them open access. Retrieval runs through a separate content API at $0.01 per file, which is about 100 files a day on the free $1 budget.

OpenAlex does not provide full text for paywalled or subscription-only publications. It returns metadata and links to locations where full text may be available, and what you can actually retrieve depends on the open-access status of each work.

What content can Valyu index?

Valyu indexes roughly 40 million academic papers alongside web results, financial market data, and licensed and specialist collections. The academic sources break down as:

Source	Coverage	Update frequency
PubMed	37M+ papers	Monthly
arXiv	2.5M+ papers	Monthly
bioRxiv	250K+ papers	Monthly
medRxiv	80K+ papers	Monthly
chemRxiv	30K+ papers	Monthly

Licensed Wiley collections cover finance journals and finance books (quantitative finance, risk, investment theory) on a monthly cycle, and Wiley Health & Life Sciences journals (medicine, nursing, pharmacology, allied health) quarterly.

Beyond academic content, the index covers clinical trials from ClinicalTrials.gov (500K+, real-time), USPTO patents (8M+, weekly), EPO patents (4M+, weekly), FDA drug labels (150K+, real-time) and others.

Valyu does not provide full text for every indexed publication. Full-text retrieval covers open-access content and sources where access has been licensed, and licensed content carries usage restrictions.

How do the web interfaces compare?

The Valyu platform provides a search playground that queries across source categories and returns title, URL, content, and structured citations. Because retrieval is semantic, an exact-title query matches by meaning rather than string equality, which returns the target work plus related material rather than a single row.

The OpenAlex interface presents a search box and filter options. Boolean operators (AND, OR, NOT) must be capitalised, and quotation marks give you phrase matching. Author searches run through the /authors endpoint, and citation searching runs through citation filters.

Feature comparison

Feature	OpenAlex	Valyu
Corpus size	322M core works, 487M including the expansion layer	~40M academic papers, plus web, financial, and specialist sources
API base URL	`api.openalex.org`	`api.valyu.ai`
Authentication	Optional free key ($0.10/day without, $1/day with)	`x-api-key` header, required
Query type	Keyword, Boolean, phrase, proximity, wildcard, semantic	Semantic full-text retrieval
Max query size	~4 KB URL	Not a documented constraint
Filters	Structured entity filters across all endpoints	`search_type`, `included_sources`, `excluded_sources`, `source_biases`, `relevance_threshold`, `start_date`, `end_date`, `category`, `country_code`, `max_num_results`, `max_price`
Pagination	`page` / `per-page` (max 100), 10,000-result ceiling, cursor paging beyond	`max_num_results`
Response fields	Selectable via `select`; full metadata schema	title, url, content, relevance_score, citations
Citations	Citation graph: `cited_by_count`, references, related works	`doi`, `authors`, `citation`, `citation_count`, `references` on academic results
Full text	52.4M works with a cached PDF, all open access	Open-access papers plus licensed collections
Web search	Not included	Included
Financial data	Not included	75 exchanges, structured JSON
Free tier	$1/day of API usage with a free key	$10 in credits, $20 with a work email

Freshness, access rights, coverage gaps, and pricing

Freshness. OpenAlex updates continuously from its upstream indexes. Valyu’s indexes daily, monthly and quarterly. If your workflow depends on a paper published last week, Valyu will surface it faster.

Access rights. OpenAlex provides metadata for all indexed works and full text only for open-access ones. Valyu provides full text for open-access papers plus licensed collections where access has been secured. Both operate inside publisher restrictions.

Coverage gaps. OpenAlex’s 322 million core works are bibliographic records, not 322 million retrievable full texts: 52.4 million carry a cached PDF. Valyu’s roughly 40 million academic papers are a fraction of OpenAlex’s record count but gives full-text depth.

Which workflows fit each service?

Valyu fits full-text evidence retrieval and multi-source search:

AI agent retrieval with structured citations
Cross-domain research spanning papers, web content, and financial data
Full-text passage extraction from open-access PubMed and arXiv content
Specialist retrieval from SEC filings, clinical trials, patents, and regulatory documents
RAG pipelines needing clean, cited content
Scientific and academic deepresearch

OpenAlex fits structured metadata discovery and citation graph analysis:

Bibliometric analysis across authors, institutions, and topics
Citation tracking and reference mining
Systematic review screening by publication year, type, or venue
Large-scale metadata extraction via cursor paging or the bulk snapshot
Open-access identification and location linking

When do OpenAlex and Valyu work together?

The combined pipeline uses OpenAlex for discovery and Valyu for evidence retrieval:

Query OpenAlex for works matching a topic, author, or publication window using filters and search parameters.
Extract DOIs, titles, and metadata from the results. Single-entity lookups by DOI are free, so this stage costs almost nothing.
Use Valyu to retrieve full-text passages and structured citations for those works or related content.
Combine OpenAlex's citation graph with Valyu's retrieved passages to build evidence-backed output.

An agent can move across domains in a single run: OpenAlex establishes which works matter and how they connect, Valyu pulls the text that supports a claim. Discovery and retrieval are handled by services designed for each, rather than one tool doing both adequately.

What the same query returns from each in Practice

The two services return different object types for identical input, which is the clearest way to see the design split.

A topic search for "melanoma immunotherapy" on OpenAlex returns work records: titles, citation counts, author and institution links, topic assignments. The same query on Valyu returns full-text passages with citations attached to each one.

The same query on Valyu returns full-text passages with citations attached to each one.

An exact-title search on OpenAlex uses the search parameter or a title filter and resolves to the record. On Valyu, semantic matching returns the target work alongside related content, because it is matching meaning rather than a string.

An author search on OpenAlex uses the dedicated /authors endpoint with affiliation and output data. Valyu has no equivalent author endpoint; author filtering depends on metadata in the indexed source.

A supporting-evidence search on OpenAlex returns related works through the citation graph. Valyu returns passages that address the query directly.

This is a difference in design goal, not in quality. OpenAlex is built for graph discovery. Valyu is built for evidence retrieval.

How do the APIs compare on query syntax and filters?

OpenAlex is a REST API at api.openalex.org. Every entity type is an endpoint: /works, /authors, /sources, /institutions, /topics, /keywords, /funders and more, each supporting list, filter, search, sort, and group operations.

Query syntax supports phrase matching with quotes, proximity search via ~N ("climate change"~5 finds the terms within five words of each other), and unstemmed exact matching plus wildcards through search.exact (machin* matches machine, machines, machinery, with a three-character minimum before the wildcard). Maximum URL length is approximately 4 KB; longer queries return a 400, and the documented fix is to split the Boolean query and combine the returned IDs client-side.

Semantic search is generally available as its own method, priced the same as keyword search, capped at 2,000 characters of input, rate limited to 1 request per second, and returning at most 50 results.

Pagination uses page and per-page, where 100 is the supported maximum (200 is deprecated legacy behaviour). Basic paging reaches only the first 10,000 results, since page * per_page must not exceed 10,000. Cursor paging (cursor=*, then follow next_cursor) goes deeper, and for genuinely bulk work the docs point you at the OpenAlex snapshot instead.

An API key is not required. You can make basic queries with no key at all, at $0.10 of usage per day; a free key raises that 10x to $1 per day. The key travels as ?api_key=KEY or an Authorization: Bearer KEY header, and both work identically.

Valyu is a REST API authenticated with an x-api-key header, with Python, TypeScript, and Rust (alpha) SDKs.

import os
from valyu import Valyu

valyu = Valyu(api_key=os.environ["VALYU_API_KEY"])

response = valyu.search(
    "Phase 3 melanoma immunotherapy trials",
    search_type="proprietary",
    included_sources=["valyu/valyu-pubmed", "valyu/valyu-clinical-trials"],
    start_date="2024-01-01",
    max_num_results=10,
    max_price=20,
)

for result in response.results:
    print(result.title, result.url)
    print(result.content)

search_type takes four values: all (web plus proprietary, with an LLM router picking sources), web, proprietary, and news. Alongside it the endpoint documents included_sources, excluded_sources, source_biases (soft-rank any source from -5 to +5 instead of filtering it out), max_num_results, max_price, relevance_threshold, start_date, end_date, category, country_code, response_length, and is_tool_call. included_sources accepts dataset ids, bare domains, presets (academic, finance, patent, legal, medical, health, genomics, chemistry, physics, politics, transportation, cybersecurity, compliance, environment, automotive, pulse), and saved collection:<name> groups.

Beyond search, the API surface includes Contents, Answer (grounded answers with citations), and DeepResearch (an autonomous agent with fast, standard, heavy, and max modes producing cited reports and xlsx/docx/pptx/pdf/csv deliverables).

Results carry title, URL, content, source, and relevance_score. Academic results add doi, authors, citation, citation_count, and references, plus abstract and figures where the source provides them. The whole shape is built for LLM context windows.

FAQ

Does OpenAlex require an API key?

No. You can make basic queries with no key at all. A free key raises your daily budget 10x, from $0.10 to $1, and is passed either as ?api_key=KEY or an Authorization: Bearer KEY header.

Does Valyu provide full text for all indexed papers?

Valyu provides full text for open-access papers from PubMed, arXiv, bioRxiv, medRxiv, and chemRxiv, plus licensed Wiley finance and Health & Life Sciences collections. Licensed content carries usage restrictions.

How current is each index?

OpenAlex updates continuously from Crossref, PubMed, DataCite, DOAJ, and arXiv. Valyu refreshes academic sources monthly, SEC filings daily, and clinical trials, drug labels, and market data in real time.

Does Valyu include web search?

Yes. Web search costs $1.50 per 1,000 results. Setting search_type to all queries web and proprietary sources in one call, with a router selecting sources; web, proprietary, and news narrow it.

Can I use both in the same pipeline?

Yes, and free DOI lookups on OpenAlex make it cheap. OpenAlex identifies works by topic, author, or citation relationship, and Valyu retrieves full-text passages and citations for them.

How much does Valyu cost to start?

$10 in free credits with no credit card, or $20 with a work email. Credits work across every source type. Keys come from platform.valyu.ai.

Do preprints count as peer-reviewed papers?

No. Preprints from arXiv, bioRxiv, medRxiv, and chemRxiv are not peer-reviewed, and both services index them alongside peer-reviewed articles. Filter on source or publication type when evidence quality matters.

Semantic Scholar vs Valyu: Which Research API Should Your Agent Call?

Prosper Otemuyiwa — Fri, 28 Aug 2026 13:39:03 +0000

If you are building a research agent, the first real decision you make is what comes back from the retrieval call. A paper record, or the paragraph inside the paper that answers the question. Those are different products, and picking the wrong one shows up three weeks later as a RAG pipeline you did not plan to build.

Valyu is a search and DeepResearch API that retrieves full text with structured citations across academic, clinical, scientific, patents & regulatory sources. Semantic Scholar is an academic search engine and metadata API from the Allen Institute for AI.

Quick answer

Pick Valyu when the unit of work is a passage of evidence: search inside papers at query time, pull a clinical trial protocol and an FDA label alongside the literature, get a cited answer or a full multi-step report without operating your own retrieval stack.

Pick Semantic Scholar when the unit of work is a record: find papers by topic, walk a citation graph, rank by influence, pull author profiles, get recommendations. It is free, the corpus is enormous, and nothing else gives you that citation graph as cleanly.

The short version in code:

# Valyu returns the text that answers the question, with the citation attached
{"title": "...", "content": "In the phase 3 cohort (n=847), median PFS was...",
 "citation": {"doi": "10.1056/...", "authors": [...], "fragment": "#:~:text=median%20PFS"}}

# Semantic Scholar returns records you then have to go and read
{"paperId": "649def34...", "title": "...", "abstract": "...", "citationCount": 1893}

What can Semantic Scholar index?

The Semantic Scholar Academic Graph covers 214 million papers, 2.49 billion citations, and 79 million authors. Coverage spans every field, assembled from publisher feeds, preprint servers, and web crawling.

The API is organised as three services:

Service	What it does
Academic Graph	Paper search, bulk search, title match, autocomplete, snippet search, paper details, batch lookup, citations, references, author search
Recommendations	Papers similar to one paper, or to a positive/negative example set
Datasets	Bulk corpus downloads, including S2ORC

Full text is not a query-time product here. It lives in S2ORC: 8 million-plus full-text papers, alongside 81 million paper nodes and 73 million abstracts, distributed as a bulk download. There is also a snippet search endpoint over open-access papers, which returns short extracts rather than the retrieval-depth passages a RAG pipeline usually wants.

So: metadata and abstracts at query time, full text as a corpus you host yourself.

What can Valyu index?

Valyu full-text-indexes roughly 4 million open-access papers, plus licensed journal content:

Source	Full-text coverage
PubMed	2.5M+
arXiv	1M+
bioRxiv	350K+
medRxiv	80K+
ChemRxiv	8K+

PubMed's complete 37 million-record abstract corpus is available as an opt-in via include_abstracts. More on that flag below, because it is the single most commonly misreported detail about this API.

Beyond the literature, the index covers ClinicalTrials.gov (500K+ trials), FDA drug labels from DailyMed (150K+), SEC filings (3M+), USPTO patents (8M+) and EPO patents (6M+) with full text and figures, plus genomics and chemistry sources. One query can span several of those at once, which is the part that matters if your agent needs to go from a mechanism in a paper to the trial testing it to the label of the approved drug.

Round 1: Finding papers

Both do discovery. Here is Semantic Scholar, rewritten from the docs example as something you would actually put in an agent rather than an interactive prompt loop:

import os
import requests

S2_BASE = "https://api.semanticscholar.org"
HEADERS = {"X-API-KEY": os.environ["S2_API_KEY"]}


def search_papers(query: str, limit: int = 10):
    r = requests.get(
        f"{S2_BASE}/graph/v1/paper/search",
        headers=HEADERS,
        params={
            "query": query,
            "limit": limit,
            "fields": "title,abstract,year,citationCount,externalIds,url",
        },
        timeout=30,
    )
    r.raise_for_status()
    return r.json().get("data", [])


def recommendations(paper_id: str, limit: int = 10):
    r = requests.get(
        f"{S2_BASE}/recommendations/v1/papers/forpaper/{paper_id}",
        headers=HEADERS,
        params={"fields": "title,year,citationCount,url", "limit": limit},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["recommendedPapers"]


for p in search_papers("chimeric antigen receptor T cell exhaustion"):
    print(f"{p['citationCount']:>6}  {p['year']}  {p['title']}")

The fields parameter is the thing to learn first. Ask for nothing and you get almost nothing back, and every extra field is a join on their side, so keep the list tight.

For anything above a few thousand results, use bulk search with its continuation token instead of paging the relevance endpoint:

import json
import requests

url = "https://api.semanticscholar.org/graph/v1/paper/search/bulk"
params = {"query": "(cold -temperature) | flu", "fields": "title,year", "year": "2023-"}

retrieved = 0
with open("papers.jsonl", "a") as f:
    while True:
        r = requests.get(url, params=params, timeout=60).json()
        for paper in r.get("data", []):
            print(json.dumps(paper), file=f)
        retrieved += len(r.get("data", []))
        if "token" not in r:
            break
        params["token"] = r["token"]

print(f"Retrieved {retrieved} papers")

Note the query syntax on the bulk endpoint: | is OR, a leading - negates, and parentheses group. It is not the same syntax as the relevance search endpoint, which trips people up.

Valyu does discovery too, over a smaller but full-text index:

import os
from valyu import Valyu

# Reads VALYU_API_KEY from the environment when no key is passed
valyu = Valyu(api_key=os.environ["VALYU_API_KEY"])

response = valyu.search(
    "Phase 3 melanoma immunotherapy trials",
    search_type="proprietary",
    included_sources=["valyu/valyu-pubmed", "valyu/valyu-clinical-trials"],
    max_num_results=15,
    response_length="large",  # full methodology and results, not just abstracts
)

for result in response.results:
    print(result.title, result.url)
    # content is str | list | dict; structured sources return objects
    print(result.content)

There are TypeScript and Rust SDKs if Python is not your stack, and the REST endpoints are there if you would rather not add a dependency at all.

Round 2: Getting the actual full text

Semantic Scholar. To search inside papers you download S2ORC, chunk it, embed it, store it, and query your own index. That is a real pipeline: object storage, an embedding job, a vector database, and a refresh strategy when the corpus updates. Perfectly reasonable if you want control over chunking and embeddings, and genuinely the right call for some teams. It is just not a thing you get from an API call.

Valyu. Full text is the default return value:

response = valyu.search(
    "mechanisms of acquired resistance to KRAS G12C inhibitors",
    search_type="proprietary",
    included_sources=["valyu/valyu-pubmed"],
    max_num_results=10,
    response_length="large",
)

for r in response.results:
    print(r.title)
    print(r.content[:500])          # relevant full-text chunks, not the abstract
    print(r.citation.doi, r.citation.fragment)  # fragment deep-links the passage

The fragment field is worth calling out separately. It is a text-fragment deep link to the exact cited passage, so a reviewer can click a citation in your agent's output and land on the sentence rather than the paper. If anyone is ever going to audit what your agent claimed, that field is the difference between "reviewable" and "take my word for it".

The `include_abstracts` Gotcha

Default: PubMed search returns papers for which full text is available, giving you the abstract plus the most relevant chunks of full text.
include_abstracts=true: expands the search to PubMed's complete 37 million-record abstract corpus, where papers without full text return their abstract only.

Full-text-first is the default. The complete abstract corpus is the opt-in. If you have read the opposite somewhere, that is the error.

# Deep evidence, narrower net (default)
valyu.search(query, included_sources=["valyu/valyu-pubmed"])

# Wide net, shallower evidence for the papers that lack full text
valyu.search(query, included_sources=["valyu/valyu-pubmed"], include_abstracts=True)

Use the default for evidence synthesis. Flip the flag for coverage sweeps and systematic-review-style screening, where missing a paper is worse than only having its abstract.

Round 3: Synthesis

The Semantic Scholar API has no answer-generation endpoint. Ai2 does ship Ai2 Scholar QA separately: an open-source cited-synthesis system over 11 million-plus full-text papers and 100 million-plus abstracts, available as a Docker app, an async API, or a Python package. You bring your own Semantic Scholar, Anthropic, and OpenAI keys, and you host it. It is a good piece of software. It is also infrastructure you now operate.

Valyu ships synthesis as managed API surface. The Answer API returns a cited answer in one call. DeepResearch runs autonomous multi-step investigation: planning, searching, extraction, fact verification, and report writing.

import os
from valyu import Valyu

valyu = Valyu(api_key=os.environ["VALYU_API_KEY"])

task = valyu.deepresearch.create(
    query=(
        "What is the current evidence that GLP-1 receptor agonists reduce "
        "major adverse cardiovascular events in patients without diabetes? "
        "Cover trial design, effect sizes, and where the evidence conflicts."
    ),
    mode="standard",
    search={
        "search_type": "proprietary",
        "included_sources": ["academic"],  # arXiv, PubMed, bioRxiv/medRxiv, ChemRxiv
        "start_date": "2021-01-01",
    },
    research_strategy=(
        "Prioritise randomised controlled trials and systematic reviews over "
        "observational studies. Separate primary endpoints from secondary and "
        "post-hoc analyses. Flag any conflicting or null results explicitly."
    ),
    report_format=(
        "Structured review with: evidence summary table (trial, n, population, "
        "endpoint, effect size, CI), narrative synthesis, conflicting findings, "
        "and evidence gaps."
    ),
    output_formats=["markdown", "pdf"],
)

result = valyu.deepresearch.wait(task.deepresearch_id)

if result.status == "completed":
    print(result.output)
    print("cost:", result.cost)
    for s in result.sources:
        print(f"{s.title} | {s.doi or s.url}{s.fragment or ''}")

research_strategy and report_format are the two parameters that do the most work. They are where you encode the methodology a domain expert would apply, and they are the difference between a report you can hand to someone and a wall of summarised abstracts.

Point it at a single dataset when you know exactly where the evidence lives, and ask for a spreadsheet instead of prose:

task = valyu.deepresearch.create(
    query=(
        "Summarise reported mechanisms of acquired resistance to KRAS G12C "
        "inhibitors in non-small-cell lung cancer, with supporting evidence "
        "for each mechanism."
    ),
    mode="fast",
    search={
        "search_type": "proprietary",
        "included_sources": ["valyu/valyu-pubmed"],
        "start_date": "2022-01-01",
    },
    deliverables=["xlsx"],           # mechanism-by-evidence table
    tools={"code_execution": True},  # required for xlsx/pptx/docx
)

DeepResearch also supports webhooks and human-in-the-loop checkpoints, which is what you want when a run takes minutes rather than milliseconds and you do not want to hold a request open.

Rate limits and cost, the part that bites in production

Valyu is usage-based, priced per thousand results by source type, with max_price as a per-query spend cap. Sources priced above the cap are excluded and the response returns a 206 partial-success warning rather than a surprise on the invoice. Free credits are available to start, $10 without a card and $20 with a work email.

Semantic Scholar is free, which is good. The limits are the catch, and they are widely misread:

Unauthenticated: 1,000 requests per second shared collectively across every unauthenticated user on the planet, with additional throttling under heavy use. That number looks generous and is not yours.
With an API key: a dedicated 1 request per second across all endpoints. Higher rates are available following review.

One request per second is a hard ceiling on any fan-out design. Batch endpoints and bulk search exist precisely because of it, and you should build around them from day one rather than discovering the limit in production.

Feature comparison

Feature	Semantic Scholar	Valyu
Base URL	`api.semanticscholar.org`	`api.valyu.ai`
Auth	Optional key; key gives dedicated quota	`x-api-key`, required
Corpus size	214M papers, 2.49B citations, 79M authors	~4M full-text papers, 37M PubMed abstracts opt-in, plus non-academic sources
Full text at query time	No (S2ORC bulk download, plus a snippet endpoint)	Yes, default for PubMed and arXiv
Citation graph traversal	Yes, first class	No dedicated graph endpoints
Author profiles	Yes, `/author` endpoints	No dedicated author endpoint
Recommendations	Yes, dedicated service	No
Cited answer generation	Not in the API (Ai2 Scholar QA is separate and self-hosted)	Answer API
Multi-step research agent	No	DeepResearch, plus templated Workflows
Deliverables	JSON	JSON, markdown, PDF, xlsx, docx, pptx, csv
Provenance	IDs, DOIs, citation counts	Title, URL, DOI, venue, authors, plus passage-level `fragment` links
Rate limit	1 req/s with a key; 1,000 req/s shared unauthenticated	Usage-based, `max_price` per-query cap

Which workflows fit each

Semantic Scholar fits work where the graph is the point:

Bibliometrics and influence ranking
Forward and backward citation chasing
Building a candidate set for a systematic review
Author disambiguation and profile lookups
Recommendation and "more like this" features
Any offline corpus work where a bulk download beats an API

Valyu fits work where the evidence is the point:

Humans and Agents that need to quote and cite, not just link
Cross-domain runs spanning literature, trials, labels, and filings
RAG without owning a RAG stack
Recurring literature reviews and competitive or regulatory monitoring
Any output a human will audit, thanks to passage-level provenance

What the same query returns from each

Identical input, different object types, which is the clearest way to see the design split.

A topic search for "melanoma immunotherapy" on Semantic Scholar returns paper records: titles, abstracts, citation counts, author links, external IDs. The same query on Valyu returns full-text passages with citations attached to each one.

Ask "which papers cite this one" and Semantic Scholar answers directly through /paper/{id}/citations. Valyu has no equivalent, because it is not a graph.

Ask "what does the evidence say about X" and Valyu answers with passages, or with a cited answer if you call the Answer API. Semantic Scholar returns candidate records for you to go and read.

This is a difference in design goal, not in quality. One is built for graph discovery. The other is built for evidence retrieval.

Integrations

Semantic Scholar is a REST API returning JSON, with community client libraries in most languages. That is the whole integration story, and for many teams it is enough.

Valyu ships a hosted MCP server, a CLI, a Claude Code plugin, agent skills, and framework integrations for the Vercel AI SDK, LangChain, LlamaIndex, AWS Bedrock AgentCore, and n8n, plus tool definitions for Anthropic, OpenAI, and Google. If you are wiring retrieval into an existing agent framework, that is usually a config change rather than a client to write.

For a sense of scale in production: RevisionDojo uses Valyu to deliver academic research to more than 450,000 students, integrating the JavaScript SDK and the Valyu AI SDK across search, citation discovery, and structured literature reviews for IB Extended Essays.

FAQ

Does Semantic Scholar give me full text?

Not at query time. Full text ships as the S2ORC bulk dataset, 8 million-plus full-text papers alongside 81 million paper nodes and 73 million abstracts, which you download and index yourself. There is also a snippet search endpoint over open-access papers that returns short extracts.

Does Semantic Scholar offer answer generation?

Not in the API. Ai2 separately ships Ai2 Scholar QA, an open-source cited-synthesis system over 11 million-plus full-text papers and 100 million-plus abstracts, available as a Docker app, async API, or Python package. It requires your own Semantic Scholar, Anthropic, and OpenAI keys, and you host it.

Does Valyu return abstracts for every PubMed record by default?

No, and this is commonly stated backwards. PubMed search defaults to papers with full text available, returning the abstract plus relevant full-text chunks. Set include_abstracts=true to expand to the complete 37 million-record abstract corpus, where papers without full text return their abstract.

How many academic papers does Valyu index?

Roughly 4 million full-text open-access papers: PubMed 2.5M, arXiv 1M, bioRxiv 350K, medRxiv 80K, ChemRxiv 8K, plus licensed journal content. PubMed's complete 37 million-record abstract corpus is available via include_abstracts.

What is the difference between Search, Answer, DeepResearch, and Workflows?

Search returns structured results. Contents extracts clean content from URLs. Answer adds cited answer generation on top of search. DeepResearch runs autonomous multi-step investigation with file deliverables. Workflows are templated, versioned DeepResearch runs for repeatable work.

Does Valyu cover clinical trials outside the United States?

Coverage currently centres on US trials and FDA-approved drugs, with 24 to 48 hour update delays on trial data.

Can I use both in the same pipeline?

Yes, and it is usually the right answer. Semantic Scholar identifies which works matter through the citation graph, and Valyu retrieves the full-text passages that support specific claims. See the code above.

Do preprints count as peer-reviewed papers?

No. Preprints from arXiv, bioRxiv, medRxiv, and ChemRxiv are not peer-reviewed, and both services index them alongside peer-reviewed articles. Filter on source or publication type when evidence quality matters.

Investment Research APIs in 2026: 7 DeepResearch Workflows for Deal Teams

Prosper Otemuyiwa — Wed, 26 Aug 2026 17:25:27 +0000

An investment research API gives you the same access to financial information that an analyst gets from a terminal, a filings database, and a browser, except it returns structured, cited output that another program can consume. Many stop at retrieval: you ask for a ticker's fundamentals, you get fundamentals. The harder problem is the work that happens after retrieval, when someone has to read forty sources, reconcile them, and produce a document a director or CIO will put in front of a client or use to make a multi-million pound decision.

The second half is what deep research APIs automate. This article covers seven workflows that run in production today on the Valyu Search and DeepResearch APIs. All of them are built for investment research and banking deal teams, all invocable with a single call and a company name, with every result traced back to the primary source.

TL;DR: the seven workflows

#	Workflow	`workflow_id`	What it answers
1	Company Profile	`ib-company-profile`	What does this company do, how does it make money, what happened recently?
2	Comparable Companies	`ib-comps-analysis`	Who are the real peers, what are they trading at, why does each belong?
3	Precedent Transactions	`ib-precedent-transactions`	What has been paid for assets like this, and under what circumstances?
4	DCF Valuation Reference	`ib-dcf-reference`	What assumptions should a DCF use, and what does the market imply?
5	LBO Screening Analysis	`ib-lbo-screen`	Could a sponsor buy this, and would the returns work?
6	Buyer & Investor List	`ib-buyer-list`	Who would buy this, and why would each one care?
7	Strategic Alternatives Review	`ib-strategic-alternatives`	What paths are available, and what does each one cost?

What is an investment research API?

Teams use investment research APIs to build equity research tools, power AI agents, run screening pipelines, and replace manual data collection.

They fall into three categories, and the distinction matters more than any vendor comparison:

A market data API answers "what is NVDA's EV/EBITDA."
A web data API answers "what does this specific 10-K say."
A research API answers "build me a defensible peer set for NVDA and explain why each comp belongs in it," a question with no single endpoint behind it.

Many production stacks use all three.

The gap between those question types is measurable. Across 4.2 million queries logged through the Valyu DeepResearch API, a single user-facing research question expands, on average, into 11 to 19 sub-queries. An investment thesis request expands into 14 to 22. A market data API serves one of those sub-queries in milliseconds. A research API is the thing that decides which nineteen to ask, runs them, and reconciles the answers.

The seven workflows below sit in the third layer and assume you already have the first two.

The 7 investment research workflows (DeepResearch)

These are ordered the way a deal team actually builds a pitch. Profile first, valuation next, then the strategic layer on top.

1. Company Profile

The question it answers: What does this company actually do, how does it make money, and what has happened to it recently?

Every deal document starts here, which makes it one of the most repeated tasks on any deal team. Someone needs a clean business overview, segment breakdown, revenue composition, management summary, and recent developments assembled from filings, transcripts, and news, with sources attached.

task = valyu.deepresearch.create(
    workflow_id="ib-company-profile",
    workflow_params={"company": "NVIDIA (NVDA)"},
    output_formats=["markdown", "pdf"],
    deliverables=["docx"],
)

result = valyu.deepresearch.wait(task.deepresearch_id)

What comes back: A structured pitch book profile covering business description, segment and geographic revenue split, financial summary, competitive positioning, and a recent-developments timeline. Every claim cites its source.

When to use it: Pitch prep, first-call decks, target screening, onboarding a new coverage name. It is the entry point most teams run first, and the input to most of the others.

2. Comparable Companies

The question it answers: Who are the real peers, what are they trading at, and why does each one belong in the set?

Comps are where analyst judgment and grunt work collide. Pulling multiples is trivial. Defending the peer set is not, and that is the part that gets challenged in a client meeting.

task = valyu.deepresearch.create(
    workflow_id="ib-comps-analysis",
    workflow_params={"company": "Datadog (DDOG)"},
    deliverables=["xlsx"],
    tools={"code_execution": {"enabled": True, "max_calls": 5}},
)

Enabling code_execution matters here. The agent computes the multiples and statistics rather than reproducing numbers it read somewhere, which removes a whole class of transcription error.

What comes back: A peer set with trading multiples (EV/Revenue, EV/EBITDA, P/E), the selection rationale for each name, and summary statistics across the set. The xlsx deliverable drops straight into a model.

When to use it: Valuation sections, fairness work, any time you need a peer set you can defend line by line.

3. Precedent Transactions

The question it answers: What has been paid for assets like this, and what were the circumstances?

Precedent transaction analysis is unusually painful to automate with conventional tools, because deal terms are scattered across press releases, merger proxies, and trade press. Multiples paid are frequently not stated and have to be derived.

task = valyu.deepresearch.create(
    workflow_id="ib-precedent-transactions",
    workflow_params={"sector": "Enterprise search and observability software"},
    search={"start_date": "2019-01-01"},
    deliverables=["xlsx"],
)

The input here is a sub-sector, not a ticker: "Vertical SaaS for healthcare", "Defense electronics", "Specialty insurance brokers". Narrow enough to define a deal set, broad enough that a deal set exists.

The search.start_date parameter is doing real work. Precedents from a different rate environment are actively misleading, and constraining the window is usually the right call. Read it as a bound on which documents get retrieved rather than on which deal dates reach the output: a 2019 floor will still surface a 2015 transaction if a recent source discusses it.

What comes back: A transaction table with acquirer, target, date, deal value, multiples paid, and the strategic context of each deal.

When to use it: Sell-side positioning, board valuation discussions, establishing a defensible premium range.

4. DCF Valuation Reference

The question it answers: What assumptions should a DCF on this company actually use, and what does the market imply?

This workflow does not replace your model. It builds the reference layer underneath it, the assumption set you would otherwise spend a day sourcing and defending.

task = valyu.deepresearch.create(
    workflow_id="ib-dcf-reference",
    workflow_params={"company": "Airbnb (ABNB)"},
    tools={"code_execution": True, "charts": True},
    deliverables=["xlsx"],
)

What comes back: Revenue growth and margin assumptions with sourcing, a WACC build with component inputs, terminal value approaches, and sensitivity ranges. Charts if you enable them.

When to use it: Before you build the model, and again when someone challenges an assumption and you need the provenance.

5. LBO Screening Analysis

The question it answers: Could a sponsor actually buy this, and would the returns work?

A fast structural read on whether a target is financeable. Debt capacity against cash flow, likely structure, sponsor fit, and whether the returns clear a hurdle without heroic assumptions.

task = valyu.deepresearch.create(
    workflow_id="ib-lbo-screen",
    workflow_params={"company": "Ziff Davis (ZD)"},
    tools={"code_execution": {"enabled": True, "max_calls": 8}},
    deliverables=["xlsx"],
)

What comes back: Debt capacity analysis, indicative capital structure, cash flow coverage, sponsor fit assessment, and a returns feasibility view.

When to use it: Sponsor coverage, take-private screening, deciding whether a name is worth full diligence.

6. Buyer & Investor List

The question it answers: Who would buy this, and what is the specific reason each one would care?

Buyer lists are where generic AI output fails most visibly. "Large technology companies" is not a buyer list. A useful one names specific acquirers and articulates the strategic logic per name: adjacency, gap being filled, precedent for similar deals, and capacity to pay.

Its target is free text rather than a ticker, which matches how a sell-side mandate usually arrives. The client is private, so you describe the asset (profitability, scale, category) and the buyer universe follows from that profile rather than from a name.

task = valyu.deepresearch.create(
    workflow_id="ib-buyer-list",
    workflow_params={"target": "A profitable $200M ARR HR-tech SaaS"},
    deliverables=["xlsx", "pptx"],
)

What comes back: Segmented strategic and financial buyer universe with per-buyer rationale, acquisition history, and capacity assessment. The pptx deliverable is built for the sell-side kickoff deck.

When to use it: Sell-side mandates, pitch materials, board discussions about who the natural acquirers are.

7. Strategic Alternatives Review

The question it answers: What are all the paths available to this company, and what does each one cost?

The only heavy mode workflow in the set, running close to 40 minutes at $2.60 against $0.50 for a standard run. The extra depth goes into evaluating sale, IPO, recapitalisation, and standalone paths, then comparing them against each other rather than assessing any one in isolation.

Mode is defined by the workflow itself, so you do not pass it. ib-strategic-alternatives runs heavy by default.

task = valyu.deepresearch.create(
    workflow_id="ib-strategic-alternatives",
    workflow_params={"company": "Peloton (PTON)"},
    previous_reports=[profile_task_id, comps_task_id],
    deliverables=["docx", "pptx"],
)

The parameter worth noting is previous_reports. It chains earlier workflow output into this one, so the strategic review reasons from the profile and comps you already ran instead of rediscovering them. It accepts up to three prior task IDs.

What comes back: Each alternative assessed with valuation implications, execution risk, timing, and stakeholder considerations, plus a comparative recommendation.

When to use it: Board advisory, activist defence, any mandate that begins with "what are our options."

Checking a run before you pay for it

This is the workflow where it pays to look before you spend. At close to forty minutes it is the longest run in the set, and the failure mode you care about is not a bad answer. It is a good answer to a question you did not ask.

workflows.preview() resolves a workflow against your parameters and returns exactly what would run, without starting a task and without spending anything.

preview = valyu.workflows.preview(
    "ib-strategic-alternatives",
    workflow_params={"company": "Peloton (PTON)"},
)

print(preview.resolved.mode)              # "heavy" - budget accordingly
print(preview.resolved.input)             # the fully substituted prompt
print(preview.resolved.research_strategy) # sources and methodology
print(preview.resolved.report_format)     # structure of the output
print(preview.resolved.deliverables)      # files that will be produced

resolved is a ResolvedWorkflowTemplate with six fields: input, research_strategy, report_format, deliverables, mode, and tools. For the strategic alternatives review that surfaces mode: "heavy" and a docx plus xlsx pair, which is what determines the cost in time and money.

Preview also validates. Pass a parameter the workflow does not define and it fails immediately, rather than at task creation:

valyu.workflows.preview("ib-buyer-list", workflow_params={"company": "Confluent (CFLT)"})
# success: False | error: 2 validation errors    <- key is "target", not "company"

valyu.workflows.preview("ib-buyer-list", workflow_params={"target": "Confluent (CFLT)"})
# success: True

Because preview costs nothing and returns instantly, it is the one control that composes with a parallel batch, which is where the next section picks it up.

Production patterns

Constrain sources deliberately. search.search_type accepts all, web, or proprietary. For workflows that must not cite blog speculation, restrict to proprietary. source_biases lets you weight sources from -5 to +5 rather than excluding them outright, which is usually the better instrument.

Pin versions in production, float in staging. Workflows are in beta and templates improve. Pin workflow_version anywhere a parser depends on the shape of the output.

Preview before you spend. workflows.preview() is free, instant, and catches a malformed parameter set before it becomes a billed run. Make it the default pre-flight in any pipeline. It is the cheapest control you have over a process that otherwise runs for half an hour before telling you anything.

Inspect the template, do not guess at it. workflows.get(slug) returns the typed variables, so you can check the parameter name and whether it is required before wiring anything up. preview() goes further and shows the resolved mode, which is what tells you whether to budget twelve minutes or forty.

detail = valyu.workflows.get("ib-strategic-alternatives")
for variable in detail.workflow.variables:
    print(variable.key, variable.required)

check = valyu.workflows.preview(
    "ib-strategic-alternatives",
    workflow_params={"company": "Peloton (PTON)"},
)
print(check.resolved.mode)           # heavy - budget accordingly
print(check.resolved.deliverables)

Track long runs by status, not by blocking. deepresearch.status(task_id) returns a DeepResearchStatus: queued, running, completed, failed, and cancelled, plus paused and awaiting_input if you have enabled a checkpoint, alongside the cost and the generated deliverables. Tag each task with metadata at creation and you can reconcile a whole batch afterwards without holding six threads open.

Structured output for pipelines. Pass a JSON Schema object in output_formats when the consumer is a database or dashboard rather than a person. Use deliverables when the consumer is a banker who wants an XLSX.

Chaining them: the full pitch-book pass

The workflows are individually useful and considerably more useful composed. A complete first-pass pitch book on a single target:

import concurrent.futures

COMPANY = "Snowflake (SNOW)"

# Each workflow declares its own variable key - comps and buyer list take
# "target", precedent transactions takes "sector".
FOUNDATION = [
    ("ib-company-profile",        {"company": COMPANY}),
    ("ib-comps-analysis",         {"target":  COMPANY}),
    ("ib-precedent-transactions", {"sector":  "Cloud data warehousing and analytics"}),
    ("ib-dcf-reference",          {"company": COMPANY}),
    ("ib-lbo-screen",             {"company": COMPANY}),
    ("ib-buyer-list",             {"target":  COMPANY}),
]

def run(item):
    slug, params = item
    task = valyu.deepresearch.create(
        workflow_id=slug,
        workflow_params=params,
        workflow_version=1,
        deliverables=["xlsx"],
        metadata={"deal": "project-frost", "slug": slug},
    )
    return valyu.deepresearch.wait(task.deepresearch_id)

# Free pre-flight: validate every parameter set before anything is billed
for slug, params in FOUNDATION:
    check = valyu.workflows.preview(slug, workflow_params=params)
    if not check.success:
        raise ValueError(f"{slug}: {check.error}")

results, failed = [], {}
with concurrent.futures.ThreadPoolExecutor(max_workers=6) as pool:
    pending = {pool.submit(run, item): item[0] for item in FOUNDATION}
    for future in concurrent.futures.as_completed(pending):
        try:
            results.append(future.result())
        except Exception as exc:   # keep the five that worked
            failed[pending[future]] = exc

# Strategic review reasons over everything above
strategic = valyu.deepresearch.create(
    workflow_id="ib-strategic-alternatives",
    workflow_params={"company": COMPANY},
    previous_reports=[r.deepresearch_id for r in results][:3],
    deliverables=["docx", "pptx"],
)

On a recent full pass against Snowflake, the six parallel standard runs completed in 26 minutes, the fastest at 12, the slowest two at 25 and 26, since the batch only finishes when its slowest member does. The heavy strategic review added a further 39. Total wall clock was a little over an hour, total cost $5.80, and the output was seven cited documents in formats a deal team already works in.

Budget by the slowest workflow rather than the average. If you need a faster first look, run the foundation six and start reading those while the strategic review finishes. Nothing downstream blocks on it except the review itself.

Note workflow_version=1 pinned explicitly, and metadata tagging every task with a deal code. Both are small habits that pay for themselves the first time you need to audit what produced a number.

Collect results with as_completed rather than pool.map. map re-raises the first exception when you iterate it, so a single failed run discards the five that succeeded, after you have already paid for them and waited 26 minutes. Gathering failures into a dict instead lets you retry the one that broke.

What changes for deal teams

The honest framing is not that these workflows replace analysts. They collapse the retrieval and first-draft phase of work that currently occupies the first days of every mandate.

We have the numbers on what that phase costs. Looking at six months of financial query traffic across 4.2 million API queries, a single investment thesis run resolves in about 75 minutes of agent time at roughly $50, against 14 to 18 analyst hours for the equivalent output, work a junior analyst would take three to five days to produce.

The seven workflows in this article are the productised version of that same pattern, scoped tighter. The same dataset shows where this is already concentrated. Traditional research (investment theses, filings, and transcripts) accounts for 57% of query volume, and 74% of sell-side queries fall into that bucket. These are not speculative use cases. They are the majority of what financial research traffic already looks like.

The analyst's job moves to where it should have been: challenging the peer set, pressure-testing assumptions, and forming the view. The workflows handle the part that was never judgment in the first place.

Frequently asked questions

What are the three types of investment research API?

Market data APIs return structured numeric series. Web data APIs return raw page content. Research APIs return synthesised, cited analysis built from many sources. Most production stacks use all three, because each answers a question the other two cannot.

How is a deep research API different from a market data API?

A market data API answers questions with a schema behind them, like a ticker's EV/EBITDA, in milliseconds. A deep research API answers questions with no single endpoint behind them, like building a defensible peer set with rationale, by running multi-step research across many sources over several minutes.

What are the 7 investment banking workflows in Valyu?

Company Profile, Comparable Companies, Precedent Transactions, DCF Valuation Reference, LBO Screening Analysis, Buyer & Investor List, and Strategic Alternatives Review.

Can I create my own workflows?

Yes. Custom workflows are defined with a slug, title, and version containing a prompt, research strategy, report format, and typed variables with key, label, and required fields. They appear in workflows.list() alongside the Valyu-published catalogue.

How do I discover available workflows programmatically?

Call valyu.workflows.list(scope="valyu", vertical="investment-banking"). The scope filter selects between Valyu-published and your organisation's own workflows; vertical filters by industry category.

What output formats are supported?

output_formats accepts markdown, pdf, or a JSON Schema object for structured output. deliverables generates files in csv, xlsx, pptx, docx, or pdf. Structured output suits pipelines; deliverables suit humans.

Are the outputs cited?

Yes. Every claim carries citations to source documents, which is what makes the output usable in regulated and client-facing contexts rather than only for internal exploration.

Can workflows build on each other?

Yes. previous_reports accepts up to three prior task IDs, so a downstream workflow reasons from earlier output rather than rediscovering it. Chaining the profile and comps into the strategic alternatives review is the common pattern.

How do I keep output stable as workflows improve?

Pin workflow_version in production. Version 1 continues returning the same structure after the template is revised, so downstream parsers do not break when a prompt improves.

Literature-in-the-Loop: Citation-Grounded Triage for AI Protein Design

Prosper Otemuyiwa — Wed, 26 Aug 2026 11:31:00 +0000

Quick answer: Lab-in-the-loop protein and antibody design generates tens of thousands of candidates per cycle but tests a few hundred. What lab-in-the-loop needs is literature-in-the-loop: a citation-grounded evidence-ranking step between generation and assay selection that retrieves published structures, affinities, homologous sequences, and negative results to rerank candidates, while reserving explicit capacity for novel designs.

The gap between what gets generated and what gets tested

The scale of the mismatch is documented. In Genentech/Prescient Design's lab-in-the-loop antibody design system, the generative methods "may produce up to 30,000 designs per lead molecule" in a single round. Across four rounds, four clinically relevant targets (EGFR, IL-6, HER2, and OSM), and ten lead molecules, more than 1,800 unique antibody variants were actually designed, synthesised, and tested.

Averaged out, that is roughly 45 variants assayed per lead molecule per round against a generation ceiling of 30,000. That gap is closer to three orders of magnitude than two. Every candidate that occupies an assay slot displaces another. Which means the ranking function that fills the queue is one of the highest-leverage components in the entire pipeline, and it is usually built from model-internal signals alone.

Published lab-in-the-loop systems do not describe a literature-based evidence-ranking step between generation and assay selection. Candidates are ranked on model confidence, predicted structure quality, and predicted binding. These three signals answer fundamentally different questions. When they are treated as interchangeable, candidates with strong prior literature support can be deprioritised relative to novel designs that happen to score well under a model's internal metric.

Lab-in-the-loop needs literature-in-the-loop: a triage layer that retrieves published structural, sequence, and affinity data to rerank candidates before wet-lab slots are allocated. Not as a veto gate that eliminates novel binders, but as a layer that enriches the assay queue with evidence-supported candidates while reserving explicit capacity for genuinely novel architectures.

Why ranking breaks when signals are treated as interchangeable

The standard design-to-assay loop works like this: a generative model proposes a batch of sequences, each annotated with predicted properties, and a ranking system selects which candidates to synthesise and test.

The Prescient/Genentech system annotates generated designs with predicted expression, binding affinity, and non-specificity. Worth being precise about how those labels are constructed, because it is the crux of the problem. From the paper:

All properties have associated binary labels (e.g., 1:1 binding to target antigen is or is not detected by SPR at a fixed concentration) modeled by binary classifiers, and expression yield and binding affinity are modeled as scalars.

So binding ground truth is a binary readout from SPR at a single fixed concentration, alongside scalar regressors for yield and affinity. That is a perfectly reasonable experimental design. The problem arises downstream, when teams treat these heterogeneous predictions as interchangeable proxies for "this candidate will work."

pLDDT measures structural self-consistency, not binding

pLDDT (predicted Local Distance Difference Test) is AlphaFold2's per-residue confidence score, ranging from 0 to 100, estimating agreement between predicted Cα positions and the unknown true structure. Scores above 90 indicate accuracy comparable to experimentally determined structures; 70 to 90 is generally sufficient for backbone prediction; below 70 requires careful interpretation. AlphaFold's own guidance is that long regions below 50 "should not be interpreted" as structure at all, but read as a prediction of disorder.

A model can place every residue with high pLDDT and still produce a loop conformation at the paratope, or an interface geometry, that is incompatible with binding. High pLDDT means the model agrees with itself.

Predicted binding is a weak classifier, and there is a number for it

Predicted binding, whether from docking, interface energy calculations, or specialised classifiers, attempts to estimate the likelihood or strength of an interaction. This is a separate question from structural confidence, and current metrics are not good at it.

The Adaptyv EGFR binder design competition analysis (Cotet et al., 2025) evaluated structure-prediction confidence scores against experimental outcomes across the competition's characterised designs. ipTM (interface predicted TM-score) achieved an AUROC of 0.64 for binding classification. The authors concluded these metrics were "insufficiently predictive of true experimental binding probability or affinity."

An AUROC of 0.64 sits modestly above the random baseline of 0.5. It carries real signal. It is not a defensible sole selection criterion for a resource as expensive as an assay slot.

Model confidence measures the model, not reality

Log-likelihood, pLDDT of the designed structure, or a classifier output on a held-out validation set measures the model's internal consistency and its agreement with its training distribution, not its agreement with physical reality.

Treating these three as interchangeable creates two failure modes:

High-confidence-but-physically-wrong candidates consume assay slots.
Candidates with lower model confidence but strong prior literature support get deprioritised in favour of novel designs that score well on a model-internal metric.

The second failure mode is the expensive one, because it is invisible. Nobody logs the binder you never tested.

Where literature-in-the-loop triage sits

The triage step belongs between candidate generation and assay queue assembly: after the generative model has produced a batch, before wet-lab slots are allocated.

It is not a replacement for the model's own ranking. It is a re-ranking layer that supplements model outputs with external evidence the model did not see at training time or could not fully encode.

For each candidate, the triage step should produce an evidence packet containing:

Target biology context: published mechanism, expression pattern, and known functional domains of the target antigen, with source citations.
Epitope and accessibility evidence: known linear or conformational epitopes, structural surface accessibility from experimental or predicted structures, and published epitope mapping data.
Homologous sequence evidence: closest known antibody or protein sequences by CDR similarity, framework identity, or full-chain alignment, with sequence identity percentages and source references.
Known structures: PDB entries for the target, for antibodies against the same target, and for the candidate's predicted fold, with resolution and method noted.
Measured affinities: published KD, IC50, Ki, or EC50 values for antibodies or proteins against the same target or epitope, with assay type and conditions recorded.
Negative and conflicting results: published reports of non-binding, cross-reactivity, aggregation, or failed expression for related sequences, flagged separately from positive evidence.
Source quality and uncertainty: per evidence item, peer-reviewed vs. preprint, assay type (SPR, BLI, ELISA, cell-based), measurement reproducibility, and whether the result has been independently confirmed.

The packet should be machine-readable for automated reranking and human-readable for review of ambiguous cases.

Here is a concrete retrieval step for one candidate, using the Valyu TypeScript SDK:

import { Valyu } from "valyu-js";

const valyu = new Valyu(process.env.VALYU_API_KEY!);

// search(query, options): query is positional, options are camelCase.
const literatureResponse = await valyu.search(
  "anti-HER2 antibody CDR-H3 binding affinity epitope SPR",
  {
    searchType: "proprietary",
    includedSources: ["valyu/valyu-pubmed", "valyu/valyu-biorxiv"],
    maxNumResults: 15,
    startDate: "2015-01-01", // plain hyphens; YYYY-MM-DD is validated
  },
);

// Each result carries a primary source URL, a source identifier, and a
// relevance score. The triage layer joins these items with sequence and
// structural evidence before reranking the candidate.
const evidencePacket = literatureResponse.results.map((r) => ({
  title: r.title,
  url: r.url,
  source: r.source,
  relevance: r.relevance_score,
  excerpt: r.content,
}));

Which evidence should influence ranking, and how to represent uncertainty

Not all evidence carries equal weight. A high-affinity SPR measurement for a homologous antibody against the same epitope is a fundamentally different kind of claim than a qualitative ELISA binding report for a distantly related sequence. The ranking system must encode this hierarchy explicitly.

Target biology establishes functional context: whether the target is a receptor with a known active site, a shed antigen, or a membrane protein with restricted epitope accessibility. This constrains which epitopes are plausible and which design strategies have precedent.

Epitope accessibility determines whether a binder can physically reach its target. A structurally buried epitope on the native conformation may not be accessible in vivo. Published epitope mapping (alanine scanning, hydrogen–deuterium exchange, cryo-EM reconstructions) provides direct evidence of which surface patches are exposed.

Homologous sequences offer the strongest signal for novel candidates. If a generated CDR-H3 shares significant similarity with a known binder against the same target, that is a positive signal; similarity to a known non-binder, or to a binder against an unrelated target, is a cautionary one. Similarity is most informative at the CDR level, where variation most directly relates to binding, rather than at the framework level where germline similarity is common and uninformative.

Known structures provide geometric constraints. If a PDB structure of an antibody–target complex exists, the paratope–epitope interface geometry is known, and a candidate predicted to occupy a similar geometry has structural precedent. Resolution matters: higher-resolution structures provide stronger geometric evidence.

Measured affinities provide quantitative anchors. ChEMBL 37 (prepared 1 May 2026) contains 2,921,148 distinct compounds, 24,527,044 activities across 1,970,438 assays, and 18,552 targets. Critically, ChEMBL classifies assay data into Binding (B), Functional (F), ADME (A), Toxicity (T), and Physicochemical (P) types, plus Unclassified (U), so a KD from a binding assay is machine-distinguishable from a functional cell-based readout.

That distinction is the whole point. A retrieval step for measured affinities must keep the source identifier and assay type attached to every measurement, so the ranking function never treats a ChEMBL KD and a qualitative PubMed observation as the same kind of evidence:

const affinityResponse = await valyu.search(
  "HER2 antibody KD IC50 Ki binding affinity assay",
  {
    searchType: "proprietary",
    includedSources: ["valyu/valyu-chembl", "valyu/valyu-pubmed"],
    maxNumResults: 25,
  },
);

// Literature writes affinities in two orders. Matching only one of them
// silently drops most of the corpus. "KD = 5 nM" is far more common in
// prose than "5 nM (KD)".
const LABEL = String.raw`K[Dd]|IC50|EC50|K[Ii]`;
const VALUE = String.raw`(\d+(?:\.\d+)?)\s*(pM|nM|µM|uM|mM)`;

const labelFirst = new RegExp(`(${LABEL})\\s*(?:=|≈|~|:|of)?\\s*${VALUE}`, "g");
const valueFirst = new RegExp(`${VALUE}\\s*\\(?(${LABEL})\\)?`, "g");

const measurements = affinityResponse.results.flatMap((r) => {
  // content is `string | object | any[]`. Structured records (data_type
  // === "structured") arrive as objects and should be read as fields;
  // regex is only for the unstructured prose path.
  if (typeof r.content !== "string") return [];

  const fromLabelFirst = [...r.content.matchAll(labelFirst)].map((m) => ({
    assayType: m[1].toUpperCase(),
    value: parseFloat(m[2]),
    unit: m[3],
  }));

  const fromValueFirst = [...r.content.matchAll(valueFirst)].map((m) => ({
    assayType: m[3].toUpperCase(),
    value: parseFloat(m[1]),
    unit: m[2],
  }));

  return [...fromLabelFirst, ...fromValueFirst].map((m) => ({
    ...m,
    sourceUrl: r.url,
    sourceId: r.source,      // log this once to confirm the exact string
    relevance: r.relevance_score,
  }));
});

const chemblMeasurements = measurements.filter(
  (m) => m.sourceId === "valyu/valyu-chembl",
);
const literatureMeasurements = measurements.filter(
  (m) => m.sourceId === "valyu/valyu-pubmed",
);

ChEMBL returns structured bioactivity records; PubMed hits are frequently qualitative. Keeping the source identifier explicit is part of representing uncertainty. If a query returns no measurements at all, that coverage gap is itself a first-class output, not something to bury inside an averaged confidence score.

How evidence reranks without becoming a hard gate

The central risk of literature-in-the-loop triage is that it degenerates into a novelty penalty: candidates with no prior literature support get systematically deprioritised, and the assay queue fills with minor variants of known binders. This is the exploration-versus-exploitation problem in active learning, applied to wet-lab selection.

Three mechanisms prevent the collapse.

1. An explicit exploration budget. Reserve a meaningful fraction of assay slots for candidates the evidence step scores as low-evidence but the generative model scores as high-confidence or high-novelty. Label them as exploration candidates and track them separately. The budget structurally prevents the ranking system from optimising purely for prior support.

2. A novelty-conditional scoring function. Rather than ranking all candidates on a single evidence score, compute a conditional one: for candidates with close literature analogues, weight evidence heavily; for candidates in sparsely populated regions of sequence or structure space, weight evidence lightly and lean on model confidence and structural plausibility. The function should be transparent and auditable, not a black-box reranker.

3. Human review for ambiguous cases. Flag candidates where evidence conflicts, where the closest homolog is a known non-binder, or where the epitope is disputed in the literature. A computational biologist or antibody engineer with the full evidence packet can make a judgment that automated ranking cannot. This is not a failure of automation. It is an acknowledgment that some decisions require domain expertise no ranking function fully encodes.

The output is a reranked queue with three tiers: evidence-supported, exploration, and flagged for human review. Assay slots are allocated across tiers according to the exploration budget, not purely by score.

A transparent retrospective protocol

The value of literature-in-the-loop triage can be assessed retrospectively using a public antibody lineage with a documented history of measured affinities and validation outcomes.

The anti-HER2 lineage suits this well. The murine monoclonal 4D5 was described in Hudziak et al., 1989 (Mol Cell Biol) and humanized onto a consensus human IgG1 framework to produce trastuzumab in Carter et al., 1992. The lineage continues through trastuzumab-based antibody–drug conjugates (ado-trastuzumab emtansine and trastuzumab deruxtecan), which retain the 4D5-derived variable domains.

One clarification that matters for this protocol: pertuzumab is not in the 4D5 lineage. It is rhuMAb 2C4, derived from a separate murine parent antibody and binding a distinct epitope on HER2 domain II (the dimerization arm), where trastuzumab binds domain IV. It is a same-target, different-lineage antibody. In a protocol whose ranking turns on CDR-level sequence homology, conflating the two would produce meaningless results. Treat it as a useful negative control for homology-based ranking instead: a clinically successful anti-HER2 antibody that CDR similarity to 4D5 should not, and does not, predict.

The protocol:

Define the candidate set. Assemble a panel representing the known lineage (the parent antibody, intermediate variants described in the literature, clinical candidates) plus computationally generated decoys or variants absent from the historical record.
Set a historical evidence cutoff. Choose a date preceding the clinical disclosure of later-generation antibodies in the lineage, and retrieve only literature and bioactivity data published before it. This simulates what the triage system would have known at that point.
Run blinded ranking. Apply the evidence-ranking pipeline to the full panel using only pre-cutoff evidence. The system does not know which candidates are the clinically successful antibodies and which are decoys.
Compare against measured-affinity labels. Using post-cutoff literature, retrieve measured affinities and validation outcomes for each candidate, and compare the evidence-based ranking to experimental outcomes.
Report three metrics. Candidates deprioritised: how many known binders the system would have placed below the assay cutoff. Enrichment among survivors: whether the evidence-supported tier contains a higher fraction of true binders than the full panel. False rejection of a real binder: whether any clinically validated antibody would have been deprioritised, and why.

The historical cutoff maps directly onto the endDate parameter:

const evidenceBeforeCutoff = await valyu.search(
  "HER2 antibody trastuzumab 4D5 affinity structure PDB",
  {
    searchType: "proprietary",
    includedSources: ["valyu/valyu-pubmed", "valyu/valyu-chembl"],
    maxNumResults: 20,
    endDate: "2010-12-31", // simulate pre-disclosure state
  },
);

One caveat worth stating plainly: date filtering operates on the publication date attached to the indexed document. For literature that maps cleanly. For curated database records, the deposit date and the date of the underlying experiment can differ, so a strict cutoff is an approximation of historical knowledge, not a perfect reconstruction of it.

This protocol is a proposal, not a completed experiment. I have not run it, and no candidate counts, enrichment rates, or false-negative rates should be read as findings. Its value is in being specifiable and auditable in advance, and in surfacing its own coverage gaps. A retrospective built only on PubMed and ChEMBL would systematically underestimate negative evidence, because failed binders are underpublished. That biases the analysis toward overestimating support for candidates whose failures never made it into print.

The infrastructure this requires

The triage step needs something most lab-in-the-loop systems were not designed around: on-demand retrieval of structured, auditable literature and bioactivity data, callable at candidate-selection time, with every result traceable to a primary source.

Three capabilities.

Semantic search over biomedical literature. PubMed comprises more than 40 million citations of biomedical literature, updated daily by the NLM. Note that not every citation carries an abstract (coverage is uneven, especially for older records), and PubMed does not host full text, though it links out where available. A query for "anti-HER2 antibody CDR-H3 affinity" should return relevant studies with metadata and links. Valyu's PubMed index covers 37M+ papers and supports natural-language queries structured around candidate features such as target name, epitope description, or CDR sequence motif, rather than requiring hand-built Boolean strings. Its index refreshes monthly, which is fine for a design-cycle cadence and worth knowing if you need same-week publications.

Structured bioactivity retrieval. ChEMBL's 24.5M activities across 18,552 targets cover IC50, Ki, KD, EC50, functional potencies, and ADMET properties. That is the upstream database's full scale, and any given retrieval layer indexes some subset of it, so check the coverage figures for whichever provider you use rather than assuming parity. The retrieval system has to query across multiple dimensions and return structured records rather than free text. Valyu's search results carry a data_type of "structured" or "unstructured", so a caller can branch on it rather than regexing everything and hoping.

Provenance and auditability. Every evidence item must carry a traceable link to its primary source: the PubMed PMID, the ChEMBL assay ID, the PDB entry, the UniProt accession. When a candidate is reranked because a homologous antibody has a published KD, the ranking record must include the assay type, source identifiers, and measurement conditions. This audit trail is what lets a human reviewer verify evidence during ambiguous-case review, and what makes retrospective analysis of ranking decisions possible at all.

Valyu is one implementation of this shape: ChEMBL bioactivity data and 37M+ PubMed papers behind a natural-language semantic search API. The critical requirement is not a specific vendor. It is the ability to retrieve structured, cited evidence programmatically, at the speed of candidate selection, with enough coverage of both positive and negative published results to be worth trusting.

And the infrastructure has to be honest about its limits. PubMed abstracts and ChEMBL records do not capture every experimental detail, and they capture almost no unpublished data. The evidence-ranking system should represent coverage uncertainty as a first-class output rather than burying it inside a single confidence score.

FAQ

Why is a design-to-assay loop incomplete when model confidence, predicted structure quality, and predicted binding are treated as interchangeable?

Model confidence measures the internal consistency of the generative model. pLDDT measures per-residue structural prediction confidence. Predicted binding estimates the likelihood of an interaction, and does it weakly: ipTM scored an AUROC of 0.64 in the Adaptyv EGFR competition analysis. Each answers a different question. Treating them as one signal lets a candidate with high pLDDT and poor predicted binding rank above one with moderate structural confidence and strong published precedent against the same epitope.

Where should literature-in-the-loop triage sit, and what should it produce?

Between generative candidate production and assay queue assembly. For each candidate it produces an evidence packet: target biology context with citations, epitope and accessibility data, homologous sequence alignments with identity percentages, known PDB structures with resolution and method, measured affinities with assay type and conditions, negative and conflicting results, and per-item source quality metadata.

How should source quality and uncertainty be represented?

Per evidence item, not per candidate: peer-reviewed vs. preprint, assay type (SPR, BLI, ELISA, cell-based), measurement reproducibility, and whether conditions match the intended assay. Per-candidate uncertainty should then capture the ratio of supportive to cautionary evidence, the spread of measured affinities for related binders, and the degree of novelty relative to the closest known sequence or structure. Zero retrieved evidence is a distinct state from conflicting evidence, and the two should never collapse into the same score.

How does evidence rerank candidates without becoming a hard gate that removes novel binders?

An explicit exploration budget reserving assay slots for low-evidence, high-novelty candidates; a novelty-conditional scoring function that weights evidence heavily only where close analogues exist; and human review for conflicting or disputed cases. The output is a three-tier queue (evidence-supported, exploration, flagged), with slots allocated across tiers rather than purely by score.

What retrospective protocol could validate this on a public lineage?

Assemble a panel of known lineage sequences and generated decoys, set a historical evidence cutoff preceding later-generation disclosures, run blinded evidence-based ranking on pre-cutoff data only, compare against post-cutoff measured-affinity labels, and report candidates deprioritised, enrichment among evidence-supported survivors, and any false rejection of a real binder. This is a proposed protocol. It has not been run, and nothing here should be read as a result.

Can literature-in-the-loop triage replace wet-lab validation?

No. Literature evidence informs prioritisation. It cannot confirm that a specific generated candidate binds its target, expresses at usable levels, or meets developability criteria. Wet-lab validation remains the only source of ground truth for a novel candidate. Triage changes which candidates are tested first, not whether they are tested.

AI Agents in Finance: From Cited Reports to Finished Deliverables

Prosper Otemuyiwa — Mon, 24 Aug 2026 14:40:22 +0000

Most AI research agents are graded on their prose. Analysts are graded on what lands in the model, the memo and the deck.

This post covers a large update driven entirely by watching how people actually used it on our Finance open source app.

Finance is open source.

TL;DR

23 curated deep research workflows across investment banking, private equity, hedge funds and GTM — each with a depth chip, a runtime estimate, and deliverable badges stated before you spend a credit.
The app now reads your freeform query and pre-fills the deliverables picker with the format it implies. Conservative, visible, editable, and it never blocks your run.
Generated files moved to the top of the report, above the body.
Every claim resolves to a clickable primary source.
It's open source on github and live at finance.valyu.ai

The Missing Deliverable

Ask a junior analyst for "a peer comps table for Alphabet vs Microsoft and Meta as an Excel spreadsheet" and you get a spreadsheet.

Ask most AI research tools the same thing and you get a beautifully written essay — sometimes with formatted tables — about peer comparables, followed by silence on where the downloadable file should be.

That silence is the missing mile. Every leaderboard measures retrieval accuracy, citation quality and reasoning depth. Very few measure whether the thing you asked for arrived in a form you could open.

Which workflows ship today

Workflows are organised by vertical, because a hedge fund analyst and a GTM lead are not looking for the same artifact. The catalogue currently holds 23 templates across four domains:

Investment banking — company profiles, IC memos, comparables
Private equity — commercial due diligence, market maps
Hedge funds — thesis work, screening
GTM — account intelligence briefings

A fifth lens, Popular, sits first and cuts across all four, surfacing the most-used templates.

Each card carries three signals before you commit a credit:

Signal	What it tells you
Depth chip	Fast, Standard or Heavy. A depth knob, not a speed knob — even Fast runs for minutes.
Runtime estimate	4–8 min for an Account Intelligence Briefing; 7–12 for a Company Profile; 10–25 for an IC Memo, Market Map or Commercial Due Diligence.
Deliverable badges	`DOC` · `XLS` · `PPT` — what you get at the end, stated up front.

Pick one and you get an auto-generated form. The variables come from the workflow definition itself, so a template that needs a company gets a company field with real ticker examples, and a template that needs a thesis gets a textarea instead of a single-line input.

The agent now reads your query

Alongside the templated workflows there's a freeform research box. Type anything, pick a depth, hit enter, get a cited report.

A deliverables picker sat under that box: pick a format, describe the contents, get a file. It worked perfectly. It also required you to know it was there.

So what happens when someone doesn't know which format is right, or simply forgets to open it? Finance now runs a small model over your settled query and pre-fills the picker with a format and description drawn from the query itself.

Type the peer comps request, pause for a moment, and the panel opens on its own with an Excel row already filled in:

What it infers, and when it stays quiet

The design constraint was that inference must never make things worse than the old manual flow.

It suggests, it does not decide. Suggestions appear in an open panel, badged, before launch. Every one is editable and deletable. Nothing is attached without being shown to you first.
It fails open. No API key, a timeout, or a malformed response all resolve to "no suggestions" — your research launches exactly as it did before, with nothing visible going wrong.
It is schema-bound. The response is strictly validated; a bare-array answer is rejected rather than guessed at.
It caps out at five deliverables per run across .xlsx, .pptx, .docx, .csv and .pdf.

Deliverables now lead the report

Small in the diff, large in practice.

Generated files used to render last — below the full report body and the chart gallery. On a report running to several thousand words, the spreadsheet you asked for sat several screens down, past every table and footnote.

They now sit directly under the title, above the collapsed activity feed and the body.

The reasoning is straightforward: the file is often why a finished report gets opened at all. Charts stayed where they were, because they illustrate the analysis and read alongside it.

Why every claim carries its source

Templated workflow or freeform query, the output is cited inline. Claims resolve to favicon pills you can click through to sec.gov, finance.yahoo.com, nvidianews.nvidia.com, and whatever else the research actually touched.

The reasoning isn't hidden either. Every run keeps an activity feed — the model's plan, the searches it ran, the sources it found, the code it executed — live while it runs, collapsed by default once it finishes.

For financial research this isn't a nice-to-have. A number you cannot trace is a number you cannot put in a memo.

Three lessons for anyone building finance agents

The deliverables picker was fully functional the entire time. It produced excellent spreadsheets. Its problem was that reaching them required a user to know it existed, open it, choose a format, and write a good description — four steps of friction guarding a capability they had already described, in plain English, one input box above.

1. Grade your agent on the artifact, not the prose. If an analyst has to retype your output into Excel, the run finished at 80%.

2. Inference belongs where users already speak. If people describe a control in natural language before failing to find it, that control is a candidate for inference. Show what you inferred, let them change it, never let it block the run.

3. Provenance is the product. Depth of reasoning is worth nothing if the number cannot be traced to a filing with a date on it.

The query already contained the answer. All that was missing was something small, cheap and conservative to read it.

Try it

Open finance.valyu.ai and run a workflow on a name your team already knows well. Compare it against what you would have produced manually.

Check the citations. Do they resolve to the actual filing, or to an article about it?

Then type a query that names a file, like peer comps for GOOGL, MSFT and META as an Excel spreadsheet, and watch the panel open before you hit enter.

Finance runs on the same Search and DeepResearch APIs your own agents can call. Grab a key at platform.valyu.ai — $10 in free credits, $20 with a work email, no card — and see the full coverage at docs.valyu.ai.

FAQ

What is an AI agent in finance?
One that plans and executes a multi-step research task — deciding which sub-questions to ask, fanning out across filings, market data and news, cross-checking what it finds, and returning a synthesised, cited output. It differs from a single search call, which answers one question against one index, and from a chatbot, which has no persistent task or artifact.

What is a deep research workflow?
A versioned, parameterised research template that runs as an async task and returns a cited report plus downloadable files. The methodology, source strategy and section structure are fixed; the inputs — company, thesis, category — are variables anyone on the team can fill in.

Does the app decide what files to generate on its own?
No, it suggests. Suggestions appear in an open panel, badged, before you launch, and you can edit or delete every one. Nothing is attached without being shown to you first.

What happens if the suggestion model is unavailable?
Nothing visible. The feature fails open — no key, a timeout, or a bad response all resolve to "no suggestions," and your research launches exactly as before.

Which model does the deliverable extraction?
gpt-5.6-luna by default, overridable with the DELIVERABLE_SUGGEST_MODEL environment variable. Whatever you pick must support strict structured outputs, since the response is schema-validated and a bare-array answer is rejected. Without an OPENAI_API_KEY the extractor stays off.

How long does a deep research run take?
Depth is the knob, not speed. Estimates range from 4–8 minutes for an Account Intelligence Briefing to 10–25 for a Market Map, IC Memo or Commercial Due Diligence. Runs continue server-side if you navigate away — pick them up again from Reports.

What file formats can it produce?
Excel (.xlsx), PowerPoint (.pptx), Word (.docx), CSV and PDF, up to five per run. Office formats are produced through code execution, which the app enables automatically when you request one. Every run produces a PDF regardless.

Can I run this without a Valyu account?
Not on finance.valyu.ai — that needs a signup. But it's open source, so you can deploy it yourself by switching the mode to self-hosted in the env variables.

Can I build my own workflow?
You can build workflows on the Valyu platform, and the app links you there. Note that the in-app browser currently requests the curated catalogue only (scope=valyu), so custom templates won't appear in the domain lenses yet.

Give Your AI Agent a Scientist's Library. a Science MCP Server

Prosper Otemuyiwa — Mon, 24 Aug 2026 13:29:29 +0000

Most "research agent" demos are searching abstracts and calling it literature review. The abstract tells you a Phase 3 melanoma immunotherapy trial hit its endpoint. It does not tell you the imaging protocol used to assess tumour response that lives in the methods section, or a supplementary table, or a figure caption.

This walks through wiring a hosted science MCP server into your AI agent, scoping it to actual scientific collections, and running a controlled before-and-after test where exactly one variable changes.

Valyu is a search API built for AI agents: one endpoint over biomedical literature, clinical trial registries, patents, financial filings and the open web, returning full text and structured metadata with resolvable identifiers rather than a list of links to go click.

TL;DR

The hosted MCP server is a plain HTTP endpoint. No local process, no Node, no mcp-remote.
The MCP tools take query and max_num_results and nothing else. No source filtering. If you need scoped retrieval, you need the REST API or an SDK — not the MCP client.
Scope with included_sources in the API, then check result.source on every hit.
include_abstracts=True widens PubMed to the whole abstract corpus; the default restricts to papers with available full text.
Every claim gets a resolvable identifier. The API returns result.doi — read it, don't prompt for it.

What you need

A Valyu API key from platform.valyu.ai — $10 in free credits, $20 if you sign up with a work email, no card
Claude Desktop, Cursor, or any MCP client
Python 3 and pip install valyu for the API examples

No Node.js. The hosted server is remote HTTP.

Connecting the MCP server

The endpoint is:

https://mcp.valyu.ai/mcp?valyuApiKey=YOUR_API_KEY

Auth rides in the query string. You can cap spend per session by appending &maxPrice=50.

Claude Desktop / claude.ai — go to claude.ai/settings/connectors → Add custom connector → paste the URL.

Open in Cursor

What the server exposes

Eleven tools, not one :

Tool	Arguments	Use
`valyu_search`	`query`, `max_num_results`, `fast_mode`	Web search returning full page content
`valyu_academic_search`	`query`, `max_num_results`	Full text across arXiv, PubMed, bioRxiv, medRxiv
`valyu_bio_search`	`query`, `max_num_results`	PubMed, clinical trials, FDA labels, bioRxiv, medRxiv, ChEMBL, PubChem, DrugBank, Open Targets, NPI Registry, WHO ICD
`valyu_patents`	`query`, `max_num_results`	Patent documents — claims, abstracts, inventors, filings
`valyu_contents`	`urls`	Extract content from up to 10 URLs
`valyu_datasources`	`category`	Enumerate the 36+ datasets at runtime

Plus valyu_financial_search, valyu_sec_search (adds response_length), valyu_company_research (company, sections), valyu_economics_search and valyu_datasources_categories.

Scoping your sources

(API and SDK only — see the constraint above.)

Sources are addressed two ways through included_sources: presets (curated bundles) and dataset IDs (individual collections).

Presets: academic, finance, patent, health, genomics, chemistry, physics, legal, politics, transportation, pulse, cybersecurity, environment, automotive, compliance, medical.

Watch the preset boundaries — this bites people. academic covers literature and preprints only:

Dataset ID	Preset	Coverage
`valyu/valyu-pubmed`	academic	37M+ open-access biomedical papers, monthly
`valyu/valyu-arxiv`	academic	Physics, CS, maths, quant finance, economics
`valyu/valyu-biorxiv`	academic	250K+ life-sciences preprints
`valyu/valyu-medrxiv`	academic	80K+ clinical/health preprints
`valyu/valyu-chemrxiv`	academic	30K+ chemistry preprints
`valyu/valyu-clinical-trials`	health	500K+ ClinicalTrials.gov studies, real-time
`valyu/valyu-drug-labels`	health	150K+ FDA labels via DailyMed
`valyu/valyu-patents`	patent	8M+ USPTO filings, full text and figures
`valyu/valyu-patents-epo`	patent	4M+ European filings from 1978
`valyu/valyu-chembl`	chemistry	2.5M+ bioactive compounds
`valyu/valyu-pubchem`	chemistry	100M+ compounds
`valyu/valyu-open-targets`	chemistry	60K+ drug targets

valyu_bio_search additionally reaches DrugBank, the NPI Registry and WHO ICD codes, which aren't broken out as dataset IDs in the datasources guide.

Clinical trials are not in academic. If you scope a trial question to the academic preset you will get papers about trials, not registry records. Use health, or name valyu/valyu-clinical-trials directly.

from valyu import Valyu

valyu = Valyu(api_key="YOUR_API_KEY")  # or set VALYU_API_KEY

response = valyu.search(
    "Phase 3 melanoma immunotherapy trials",
    search_type="proprietary",          # all | web | proprietary | news
    included_sources=["valyu/valyu-pubmed"],
    max_num_results=10,
)

for result in response.results:
    print(result.title)
    print(result.source)          # check this
    print(result.doi)
    print(result.content)

Then check the results. Every SearchResult carries a source field. After each search, confirm each result came from a collection you declared. If something arrives from elsewhere, treat the output as unscoped and rerun tighter. Filtering narrows the search; it is not a guarantee of exclusion.

Note excluded_sources accepts dataset IDs and domains but not presets.

The before-and-after test

Here's the part worth running, with one honest caveat up front.

By default (include_abstracts=False), PubMed search is restricted to papers that have available full text. Setting include_abstracts=True expands the search to PubMed's complete abstract corpus and returns document-level abstracts.

So this is not a clean single-variable A/B. Two things change at once: the corpus gets bigger, and the returned granularity drops to abstract level. It's still the sharpest comparison the API gives you, but describe it accurately — you are comparing full-text-only retrieval against broad abstract-level retrieval, not "the same search with and without full text."

1. Pick a question the abstract can't answer

You want a detail that lives in the methods, a figure caption, or a supplement:

What imaging protocol did the trial use for tumour response assessment?

2. Run it abstract-only

abstract_run = valyu.search(
    "Phase 3 melanoma immunotherapy tumour response assessment imaging protocol",
    search_type="proprietary",
    included_sources=["valyu/valyu-pubmed"],
    include_abstracts=True,      # widen to the full PubMed abstract corpus
    max_num_results=10,
)

This has to run in Python, not through the MCP client. No MCP tool accepts include_abstracts — see the section above. Save the output verbatim. This is your baseline.

3. Run it with full text

fulltext_run = valyu.search(
    "Phase 3 melanoma immunotherapy tumour response assessment imaging protocol",
    search_type="proprietary",
    included_sources=["valyu/valyu-pubmed"],
    include_abstracts=False,     # default — papers with available full text only
    max_num_results=10,
)

Identical query, identical source, identical result count. Save that too.

4. Compare

Put them side by side. Does the abstract-only answer contain the imaging protocol? Does the full-text one?

If full text surfaces evidence abstract-only missed, you have a controlled result — for this query, this index, and this date.

Things not to do with it:

Don't generalise to "abstract-only retrieval is unreliable." You tested one query against one index.
One run is a demonstration, not a benchmark.
PubMed full text is open access only. If your topic is dominated by paywalled journals, the full-text run has less to work with and the comparison says more about OA coverage than about retrieval depth.
Don't publish until you've independently opened the paper and confirmed the detail is where you say it is.

Recording the run

Four things, or nobody can reproduce it: the exact call parameters, the full verbatim output, the source list, and the correction.

{
  "query": "<identical query string used in both runs>",
  "shared_params": {
    "search_type": "proprietary",
    "included_sources": ["valyu/valyu-pubmed"],
    "max_num_results": 10
  },
  "run_abstract_only": {
    "include_abstracts": true,
    "output": "<full output, verbatim>",
    "sources_returned": ["<result.source values>"]
  },
  "run_full_text": {
    "include_abstracts": false,
    "output": "<full output, verbatim>",
    "sources_returned": ["<result.source values>"]
  },
  "run_date": "<YYYY-MM-DD>",
  "correction": {
    "missed_by_abstract": "<what was missing>",
    "found_in_full_text": "<what full-text surfaced>",
    "source_doi": "<result.doi>",
    "location": "<methods / figure caption / supplement>"
  }
}

Record the date — PubMed syncs monthly and trials update in real time, so the same call will drift.

Citation rules that scientists actually use

Every claim links to a resolvable identifier. This is the line between a science agent and a chatbot with a search tool.

Source type	Identifier	Resolves at
Journal articles	DOI	`https://doi.org/<doi>`
Preprints (bioRxiv, medRxiv, ChemRxiv)	DOI	`https://doi.org/<doi>`
Clinical trials	NCT number	`https://clinicaltrials.gov/study/<nct>`
US patents	USPTO patent number	USPTO patent search portal

You don't have to parse these out of prose — SearchResult exposes doi, citation, authors, publication_date, citation_count and source as structured fields. Read them directly rather than asking the model to extract them.

Do not demand a DOI for everything. Trials and patents have their own registries, and a prompt that insists on DOIs produces fabricated ones.

For every factual claim, cite a resolvable identifier: a DOI for journal
articles, an NCT number for clinical trials, or a patent number for patents.
If the result has no identifier, give the URL and state that the claim is
unverified. Never construct an identifier that was not returned.

Combining literature, trials and patents

Three scoped searches, correct preset for each:

from valyu import Valyu

valyu = Valyu(api_key="YOUR_API_KEY")

# Literature — academic preset
lit = valyu.search(
    "PD-1 inhibitor combination therapy melanoma",
    search_type="proprietary",
    included_sources=["academic"],
)

# Clinical trials — registry records live in health, NOT academic
trials = valyu.search(
    "PD-1 inhibitor melanoma Phase 3",
    search_type="proprietary",
    included_sources=["valyu/valyu-clinical-trials"],
)

# Patents — USPTO full text and figures
patents = valyu.search(
    "PD-1 antibody immunotherapy",
    search_type="proprietary",
    included_sources=["valyu/valyu-patents"],
)

DOIs for the literature, NCT numbers for the trials, patent numbers for the patents.

Valyu's DeepResearch (POST /v1/deepresearch/tasks) spans the same catalogue asynchronously. It can reach across domains in one task, but verify the returned sources match your intended scope before treating the output as complete.

Six checks to keep the agent honest

Source provenance — read result.source on every result. If it isn't a collection you declared, the run is unscoped.

Identifier resolution — verify the cited identifier actually resolves before presenting the claim. DOI at doi.org, NCT at clinicaltrials.gov, patent through USPTO. Doesn't resolve → unverified.

Full-text availability — PubMed full text is open access only, and include_abstracts=True means you got abstracts instead of full text. Have the agent state which mode it ran in. An agent reasoning over an abstract as though it read the paper is the failure this whole post is about.

Preprint status — bioRxiv, medRxiv and ChemRxiv are not peer-reviewed. Label them as preprints, with server name and DOI, so the reader can judge evidence level.

Citation entailment — when the agent says a source supports a statement, confirm the passage is actually in the returned content. If it cites a figure, confirm the figure came back.

Missing assets — figures, tables and supplements are not retrievable from every source. valyu/valyu-patents is the one dataset documented as carrying full text and figures; don't assume that generalises to the preprint servers. If an asset isn't there, the agent says so rather than substituting.

Access and copyright limits

Retrieval is not a redistribution licence. The Valyu Acceptable Use Policy applies across all APIs, datasets, models and indexes. You must not:

Reproduce or redistribute copyrighted content
Access content behind paywalls or access controls
Store or display publisher content in ways licensing doesn't allow
Extract, store or manipulate full-text articles from licensed sources
Rebuild, replicate or simulate any Valyu corpus, dataset, index or scoring
Join outputs to reassemble source materials
Scrape or bulk download via high-volume search queries

The contents endpoint is your responsibility. Per the AUP: "You — not Valyu — are the party responsible for ensuring that your use of the Contents endpoint in connection with any given URL is lawful and authorised." Before submitting a URL, review the target's terms and acceptable use policy, and confirm automated extraction isn't prohibited by robots.txt, X-Robots-Tag headers or <meta name="robots"> directives.

In practice: the agent reads and reasons over retrieved content in-session and does not store it for redistribution. And retrieved research is not a substitute for professional medical advice, or for a human reading the primary source.

Checklist

[ ] MCP endpoint connected and tools listed in the client
[ ] Reproducibility runs done via API/SDK, not the MCP client
[ ] included_sources set, with the right preset for the source type
[ ] Both runs use identical query, sources and max_num_results
[ ] Only include_abstracts differs between the two runs, and the writeup says the corpus widened too
[ ] Full output saved verbatim, plus run date
[ ] result.source checked on every result
[ ] Every claim linked to a returned doi, NCT number or patent number
[ ] Preprints labelled as preprints
[ ] Conclusion scoped to this query and index only
[ ] No stored or redistributed licensed full text
[ ] No URL sent to /v1/contents without checking terms and robots directives
[ ] Retrieved research not presented as medical advice

FAQ

How do I run the same question through both abstract-only and full-content workflows?
In Python, not through MCP — no MCP tool exposes include_abstracts. Issue the identical query twice against valyu/valyu-pubmed, once with include_abstracts=True and once with the default False, keeping search_type, included_sources and max_num_results fixed. Save both outputs verbatim.

Can I restrict my Claude Desktop agent to just PubMed?
No. MCP search tools accept only query and max_num_results. Your scope control is which tool the agent picks. For real source pinning, call the API directly.

What makes a good test question?
One where the decisive detail sits outside the abstract — imaging protocols, assay conditions, eligibility subtleties. "What imaging protocol did the Phase 3 melanoma immunotherapy trial use for tumour response assessment?" works because that lives in methods or a supplement.

Why did my clinical trial search return papers instead of registry records?
You almost certainly scoped to the academic preset. Clinical trials live in health — use included_sources=["valyu/valyu-clinical-trials"].

How should the agent cite results without DOIs?
NCT number for trials, patent number for patents. If none exists, the URL plus an explicit note that the claim is unverified. Read result.doi rather than having the model extract it.

Building Multi-Agent Research Systems using Vercel AI SDK

Prosper Otemuyiwa — Fri, 13 Mar 2026 13:26:08 +0000

There are many ways to build apps and systems. In today’s AI-native world, the possibilities are endless.

Now imagine you’re tasked with building a multi-agent research system, with one key requirement: don’t over-engineer it.

KISS — Keep It Simple, Stupid.

This is the scenario given to you:

"A friend asked me to pull together everything on Eli Lilly's Q4 results, any ongoing GLP-1 trials they've filed recently, and how the financial press was covering it. Build a multi-agent research system that handles that so you can go accomplish 10 other things while the system gets you the result."

Now, let’s break this down:

Pull together everything on Eli Lilly’s Q4 results
Identify any GLP-1 trials they’ve filed recently
See how the financial press has been covering it

When broken down like this, it’s simply three queries across three completely different domains: SEC filings, clinical trials, and live news.

Three different tools, three different contexts and then stitching it all together manually at the end. It’s similar to the "15-tab" problem.

And it gets worse when you’re building an AI app. You often end up maintaining a research pipeline that’s just a collection of disconnected scripts, held together by copy-paste.

The Architecture

We have three different contexts, so three domains. We'll use the Vercel AI SDK to handle all three domains in parallel.

One query, three specialist agents running simultaneously, and a single synthesized response. With the @valyu/ai-sdk package, plugging in domain-specific data sources takes just one import—no manual tool definitions required.

This is the architecture: the Orchestrator–Worker pattern.

One orchestrator agent understands the query, dispatches the right specialists in parallel, and synthesizes the results. Each specialist has its own tool suite and domain expertise

The tools come from @valyu/ai-sdk, a package that provides ready-made Vercel AI SDK tools backed by Valyu's search API. No manual tool() definitions, no Zod schemas for parameters, no custom execute functions.

Import the tool, drop it into your tools object, done.

Why Parallel Dispatch Matters

Sequential agents are the wrong default for research workloads. Each specialist takes 4-6 seconds.

Three in sequence is 15+ seconds. Three specialists running simultaneously gets you results in the time it takes the slowest one to finish.

Data Flow: From Query to Report

For a query like "What's Eli Lilly's financial position and do their GLP-1 trials support the revenue projections?":

Setup

Install Nextjs and then add the following packages...

pnpm add ai @ai-sdk/anthropic @valyu/ai-sdk @ai-sdk/react zod valyu-js

Create .env.local:

ANTHROPIC_API_KEY=your_key_here
VALYU_API_KEY=your_key_here

Grab your Anthropic and Valyu API keys.

Both keys are read from environment automatically. @valyu/ai-sdk picks up VALYU_API_KEY without any explicit configuration.

Project structure:

research-nexus/
├── src/
│   ├── agents/
│   │   ├── financial-analyst.ts   # Financial analyst
│   │   ├── scientist.ts  # Scientist
│   │   ├── journalist.ts          # Journalist
│   │   └── orchestrator.ts        # Query router + synthesizer
│   └── app/
│       └── api/
│           └── chat/
│               └── route.ts       # Next.js API route
└── package.json

No lib/ or tools/ directories. The tools come pre-built.

The Specialist Agents

Each specialist is a ToolLoopAgent with domain-specific tools from @valyu/ai-sdk. The agent loop lets the model chain multiple tool calls before returning. Searching SEC filings, then cross-referencing earnings, then adding macro context, all within a single agent invocation.

Financial Analyst

import { ToolLoopAgent } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { secSearch, financeSearch, economicsSearch } from "@valyu/ai-sdk";

export const financialAnalystAgent = new ToolLoopAgent({
  model: anthropic("claude-haiku-4-5-20251001"),
  instructions: `You are a senior financial analyst specializing in SEC filings, market data, and economic research.

Your capabilities:
- Search and analyze SEC filings (10-K, 10-Q, 8-K, proxy statements)
- Look up financial data including stock prices, earnings, income statements
- Research economic indicators and macro data

When responding:
- Always cite the specific filing type and date
- Present financial figures clearly with proper formatting
- Highlight key risks, trends, and material changes
- Compare metrics across periods when relevant
- Be precise about numbers — never approximate when exact data is available`,
  tools: {
    secSearch: secSearch({ maxNumResults: 3, responseLength: "short" }),
    financeSearch: financeSearch({ maxNumResults: 3, responseLength: "short" }),
    economicsSearch: economicsSearch({ maxNumResults: 3, responseLength: "short" }),
  },
});

financial-analyst.ts

Scientist

import { ToolLoopAgent } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { bioSearch, paperSearch } from "@valyu/ai-sdk";

export const medicalResearcherAgent = new ToolLoopAgent({
  model: anthropic("claude-haiku-4-5-20251001"),
  instructions: `You are a medical and life sciences research specialist with expertise in clinical trials, drug discovery, and biomedical literature.

Your capabilities:
- Search clinical trial databases for trial status, results, and endpoints
- Look up FDA drug labels, approvals, and safety information
- Research biomedical literature from PubMed, bioRxiv, and medRxiv
- Analyze academic papers on drugs, therapies, and medical devices

When responding:
- Always cite trial IDs (NCT numbers), DOIs, or publication references
- Clearly distinguish between preliminary and peer-reviewed findings
- Note the phase of clinical trials and their primary endpoints
- Flag any safety concerns or adverse events mentioned in the data
- Use proper medical terminology but explain it when needed`,
  tools: {
    bioSearch: bioSearch({ maxNumResults: 3, responseLength: "short" }),
    paperSearch: paperSearch({ maxNumResults: 3, responseLength: "short" }),
  },
});

scientist.ts

Journalist

import { ToolLoopAgent } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { webSearch } from "@valyu/ai-sdk";

export const journalistAgent = new ToolLoopAgent({
  model: anthropic("claude-haiku-4-5-20251001"),
  instructions: `You are an investigative journalist and news analyst with access to real-time web sources.

Your capabilities:
- Search the web for breaking news and current events
- Find and cross-reference multiple news sources on a topic
- Track developing stories and provide timeline context
- Research background on people, organizations, and events

When responding:
- Always attribute information to specific sources
- Present multiple perspectives when covering controversial topics
- Distinguish between confirmed facts and unverified reports
- Provide publication dates so readers know how current the information is
- Summarize key points clearly, then provide supporting details`,
  tools: {
    webSearch: webSearch({ maxNumResults: 5, responseLength: "short" }),
  },
});

journalist.ts

Three agents, three imports from @valyu/ai-sdk, zero custom tool definitions.

The Orchestrator

The orchestrator handles query classification, parallel dispatch, and synthesis.

import { ToolLoopAgent, tool, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";
import { financialAnalystAgent } from "./financial-analyst";
import { scientistAgent } from "./scientist";
import { journalistAgent } from "./journalist";

const financialAnalystTool = tool({
  description:
    "Delegate to the Financial Analyst agent for SEC filings, stock data, earnings reports, economic indicators, and financial analysis.",
  inputSchema: z.object({
    task: z.string().describe("The financial research task to complete"),
  }),
  execute: async ({ task }, { abortSignal }) => {
    const result = await financialAnalystAgent.generate({
      prompt: task,
      abortSignal,
    });
    return result.text;
  },
});

const scientistTool = tool({
  description:
    "Delegate to the Scientist agent for clinical trials, drug information, FDA data, biomedical papers, and life sciences research.",
  inputSchema: z.object({
    task: z.string().describe("The medical/life sciences research task to complete"),
  }),
  execute: async ({ task }, { abortSignal }) => {
    const result = await scientistAgent.generate({
      prompt: task,
      abortSignal,
    });
    return result.text;
  },
});

const journalistTool = tool({
  description:
    "Delegate to the Journalist agent for real-time news, current events, breaking stories, and web-based research on any topic.",
  inputSchema: z.object({
    task: z.string().describe("The news/research task to complete"),
  }),
  execute: async ({ task }, { abortSignal }) => {
    const result = await journalistAgent.generate({
      prompt: task,
      abortSignal,
    });
    return result.text;
  },
});

export const orchestratorAgent = new ToolLoopAgent({
  model: anthropic("claude-haiku-4-5-20251001"),
  instructions: `You are a research orchestrator that routes queries to specialized agents.

You have three specialist agents available:
1. **Financial Analyst** — SEC filings, stock data, earnings, financial statements, economic data
2. **Scientist** — Clinical trials, drug discovery, FDA data, biomedical papers
3. **Journalist** — Real-time news, current events, web research

Your job:
- Analyze the user's query and delegate to the right specialist(s)
- For questions that span multiple domains, call multiple agents
- Synthesize results from multiple agents into a coherent response
- If a query doesn't fit any specialist, answer it yourself
- Always be clear about which sources informed your response`,
  tools: {
    financialAnalyst: financialAnalystTool,
    scientist: scientistTool,
    journalist: journalistTool,
  },
  stopWhen: stepCountIs(10),
});

The orchestrator agent acts as a smart router. It receives the user's query, analyzes what domains it touches, and delegates work to the right specialist(s).

It doesn't do the research itself. Instead, it calls one or more sub-agents as tools:

Financial Analyst for SEC/market data,
Scientist for clinical trials and biomedical literature,
Journalist for real-time news.

For cross-domain questions like "How does Eli Lilly's GLP-1 pipeline affect their stock outlook?", it calls multiple specialists in sequence.

Sub-Agents as Tools. Each specialist is a ToolLoopAgent wrapped in a tool() call, which makes it callable by the orchestrator just like any other function.

When invoked, the sub-agent runs its own independent loop, calling Valyu search tools (like secSearch or bioSearch), reading the results, and synthesizing a response.

The sub-agent's final text is returned to the orchestrator as the tool's output.

Loop Control. The stopWhen: stepCountIs(10) on the orchestrator caps it at 10 loop iterations to prevent runaway execution. The sub-agents use the default limit of 20 steps. Within those bounds, each agent is free to make multiple tool calls. For example, the Financial Analyst might search SEC filings first, then cross-reference with earnings data, all within a single invocation before returning its findings.

The API Route

// app/api/chat/route.ts
import { createAgentUIStreamResponse } from "ai";
import { orchestratorAgent } from "@/agents/orchestrator";

export async function POST(request: Request) {
  const { messages } = await request.json();

  return createAgentUIStreamResponse({
    agent: orchestratorAgent,
    uiMessages: messages,
  });
}

For the sake of keeping this post short, here’s the repo: multi-agent-research-sys.

You’ll find all the UI pages there. Clone the project and run it locally to explore the full setup.

Running it

pnpm dev

Output:

User entered query

Result shows up

What `@valyu/ai-sdk` Provides

The package ships ten tools that cover the major research verticals:

Tool	Data Sources
`secSearch()`	SEC 10-K, 10-Q, 8-K filings, EDGAR full-text
`financeSearch()`	Stocks, earnings, balance sheets, insider trades, dividends
`economicsSearch()`	FRED, BLS, World Bank, US government spending
`bioSearch()`	ClinicalTrials.gov, DrugBank, ChEMBL, FDA labels, Open Targets
`paperSearch()`	PubMed, arXiv, bioRxiv, medRxiv, academic publishers
`webSearch()`	Real-time web, news, general content
`patentSearch()`	USPTO, global patent databases
`companyResearch()`	Comprehensive company intelligence
`datasources()`	List available data sources
`datasourcesCategories()`	List available categories

Each tool accepts optional configuration: maxNumResults, relevanceThreshold, includedSources for source-level filtering. All read VALYU_API_KEY from the environment by default.

The difference from web only search matters most for the financial and biomedical agents.

A web search for "Eli Lilly 10-K 2024 risk factors" returns SEO articles about the filing. secSearch() returns the actual filing text.
A web search for "tirzepatide Phase 3 results" returns health news coverage. bioSearch() returns the ClinicalTrials.gov entries and DrugBank compound data.
That's primary source access vs secondary commentary. A meaningful difference for research quality.

Extending the System

Adding a fourth specialist (patents, legal, government) requires:

One agent file importing the relevant @valyu/ai-sdk tools
Adding the new agent to the orchestrator

Ten specialists in parallel takes the same wall-clock time as three.

The full code is on GitHub. Clone, run and explore!

Get a Valyu API key at platform.valyu.ai. $10 free credit, no credit card required.

Perplexity Sonar Alternatives for Developers (2026)

Prosper Otemuyiwa — Tue, 10 Mar 2026 12:13:15 +0000

Quick Answer: The best alternatives to Perplexity Sonar for developers are Valyu (for specialised data access + web search + benchmark-leading accuracy), Linkup (for simple web search with predictable pricing), and Tavily (for LangChain/LlamaIndex-integrated RAG).

For Sonar Deep Research specifically, Valyu's DeepResearch API is the only alternative that matches multi-step research with citations while also accessing full-text SEC filings, PubMed, and academic sources that Sonar cannot reach.

I've been building search-grounded AI apps long enough to have a mental list of the API switches that felt obvious in hindsight. Switching off Perplexity Sonar is near the top.

The Sonar API is a capable product. I'm not here to trash it. But if you've been running a production app on Sonar and you've hit the reliability ceiling, the throttling wall, or the "this thing only knows about public web pages" limit, you're not alone, and there are real alternatives now.

This article covers what Perplexity Sonar actually is (the full product family, not just the consumer chatbot), the documented reasons developers switch, and the concrete alternatives for each use case, including a dedicated section on Sonar Deep Research specifically.

What Perplexity Sonar Actually Is

First: Sonar is Perplexity's API product, not the consumer app.

"Perplexity" and "Sonar" are distinct things. Searching for Perplexity alternatives usually returns lists of consumer chatbots (ChatGPT, Claude, etc.). That's the wrong category if you're building as a developer.

The Sonar API family has five models:

Model	Primary Use	Pricing
sonar	Lightweight Q&A, high-volume	$5/1,000 requests
sonar-pro	Deeper content understanding	$8/1,000 requests + tokens
sonar-reasoning-pro	Enhanced multi-step reasoning	$2/M input, $8/M output
sonar-deep-research	Exhaustive multi-step research reports	$2/M input, $8/M output + $5/1,000 searches + $3/M reasoning tokens

sonar-deep-research runs autonomous multi-step research, searches the web multiple times, reasons over what it finds, produces a comprehensive report. Available via Perplexity API and OpenRouter.

The pricing for Deep Research compounds fast. A request that triggers 30 searches costs $0.15 in search fees alone, before tokens.

Why Developers Are Switching

These are documented complaints from /r/perplexity_ai, /r/AI_Agents, and developer comparisons, not personal opinions.

Reliability. One developer documented 20+ daily API outages with the Perplexity status page showing green the entire time. For a production app, that's not workable. The common workaround is building fallback logic, which defeats the point of paying for a managed API.

Intentional throttling. Linkup documented this in their own comparison: Sonar's API accuracy appears deliberately capped to avoid creating a competitive consumer product. Perplexity's primary business is a consumer chatbot. The API is secondary. The engineering priorities show.

The architecture problem. Sonar uses a /chat/completions endpoint, the same pattern as LLM chat APIs. Every API call forces a full text generation. If you only want source URLs for a RAG pipeline, you still pay for a generated answer. For developers who want to control the generation step themselves (use Claude or GPT-4 for generation, use search just for retrieval), this creates a wasteful and expensive architecture.

Linkup measured this...The unpredictability in output token length (ranging from 4 to 340,000 tokens) makes cost-per-query essentially impossible to forecast.

Web-only. This is the hard ceiling. Sonar searches the public web. That's it. No SEC filings, no PubMed, no academic journals, no ChEMBL compound databases, no FRED economic data. If you're building financial analysis tools, biomedical research assistants, or anything that requires authoritative data that lives behind institutional barriers, Sonar hits a wall.

The $5 Pro plan trap. Many developers sign up for Perplexity Pro at $20/month expecting meaningful API access. The Pro plan includes $5/month in API credits. That's roughly 1,000 standard queries at low search depth. A heavy testing session can burn through it in hours.

Alternatives for Standard Sonar Use Cases

Valyu DeepSearch API

The most differentiated option in this category, specifically because it goes beyond web search.

Valyu's DeepSearch API gives you a single endpoint that searches the public web AND 36+ specialised data sources; SEC 10-K, 10-Q, 13F, 13D, 13G filings with full-text search, PubMed and bioRxiv research papers, ChEMBL bioactive compounds, academic journals, FRED and BLS economic data, clinical trials, patent databases.

For developers building anything that needs financial data, biomedical research, academic content, or economic indicators, this is the alternative that actually solves the problem. Sonar doesn't provide reliable data in many of these areas.

On raw web search accuracy, Valyu benchmarks at 79% on FreshQA (600 time-sensitive queries) versus Sonar's architecture which relies on Perplexity's indexed web.

On finance-specific questions, Valyu scores 73% vs Google's 55%.

from valyu import Valyu

client = Valyu(api_key="your-api-key")

# Search web + SEC filings + economic data in one call
response = client.search(
    query="What risk factors did Apple disclose in their most recent 10-K?",
    search_type="all", # web + proprietary
    max_num_results=10
)

print(response)

The MCP server integration means it drops into Claude Desktop, Cursor, and other MCP-compatible tools with zero additional code. Native Vercel AI SDK and LangChain integrations exist.

Platform: platform.valyu.ai | Docs: docs.valyu.ai | Free $10 credit on signup.

Best for: Developers who need specialised data (financial, biomedical, academic, economic) or who want benchmark-leading accuracy on time-sensitive and domain-specific queries.

Linkup

Linkup's pitch is architectural clarity. They expose a dedicated /search endpoint with an outputType parameter, you specify whether you want search_results (clean JSON of sources), answer (generated text), or structured (custom JSON schema). This is fundamentally different from Sonar's chat completion approach.

Pricing is transparent and flat: standard search at €5/1,000 queries, deep search at €50/1,000 queries. No token variability. On SimpleQA benchmarks, Linkup hit 91% vs Sonar's 77.3%.

The one limitation: Linkup is web-only. No specialised data access.

Best for: Developers who want predictable pricing and architectural control over the search/generation split.

Tavily

They are one of the most commonly used search APIs in the LangChain/LlamaIndex ecosystem. Tavily's biggest advantage is installation friction: if you're building a LangChain agent, Tavily is a one-liner. The free tier (1,000 credits/month) is generous enough for development.

Performance is solid. Pricing: $0.008/credit pay-as-you-go, Monthly plans start around $30/month for ~4,000 credits.

Best for: RAG pipelines built on LangChain or LlamaIndex where developer experience and quick integration matter more than maximum accuracy.

Alternatives for Sonar Deep Research Specifically

sonar-deep-research occupies a specific niche: multi-step autonomous research that produces comprehensive reports, not just answers. The use case is different from standard search. You're asking it to do what a human researcher would do over an hour, not just answer a question.

The key question is what you actually need from a deep research API:

Multi-step search execution (runs multiple queries, synthesizes results)
Citations and source references in the output
Access to authoritative data sources, not just indexed web pages
Structured output or webhook support for long-running tasks

On criteria 1, 2, and 3, Valyu's DeepResearch API is the only alternative that matches sonar-deep-research functionally while expanding what it can do.

# Valyu DeepResearch - multi-step autonomous research
# with access to SEC filings, PubMed, academic journals

from valyu import Valyu

client = Valyu(api_key="YOUR_API_KEY")

# Create an async DeepResearch task
task = client.deepresearch.create(
    query="Analyze the financial health of Tesla based on recent SEC filings and analyst sentiment",
    mode="standard",  # also supports: "fast", "heavy", "max"
    output_formats=["markdown"],
    search={
        "search_type": "proprietary",
        "included_sources": ["finance", "academic"]
    }
)

if task.success:
    print(f"Task created: {task.deepresearch_id}")

    # Wait for completion with progress updates
    result = client.deepresearch.wait(
        task.deepresearch_id,
        on_progress=lambda s: print(f"Status: {s.status}")
    )

    if result.status == "completed":
        print(result.output) # markdown report
        print(result.sources)  # cited sources with URLs
        print(result.cost) # fixed task cost

The difference that matters for serious use cases: when Sonar Deep Research researches "clinical trial outcomes for GLP-1 receptor agonists," it's searching whatever's publicly indexed on the web. When Valyu DeepResearch does the same query, it's searching PubMed, ClinicalTrials.gov, FDA drug labels, ChEMBL, and Open Target where the actual source databases where this research lives.

For financial research: Valyu reads the actual 10-K filings, earnings transcripts, and insider trading data. Sonar reads articles about those filings.

Pricing comparison for deep research:

Product	Per Request Cost	Data Sources	Output
Sonar Deep Research	$2/M input + $8/M output + $5/1,000 searches + $3/M reasoning tokens	Public web only	Markdown report
Valyu DeepResearch (fast)	$0.10	Web + 36+ specialised sources	Markdown, PDF, JSON
Valyu DeepResearch (standard)	~$1-3	Web + 36+ specialised sources	Markdown, PDF, JSON
Valyu DeepResearch (max)	$15.00	Web + 36+ specialised sources	Markdown, PDF, JSON, Excel

Valyu also supports webhooks (for async long-running tasks), file analysis, and follow-up instructions, features the Sonar Deep Research endpoint doesn't offer.

Head-to-Head Comparison Table

	Perplexity Sonar	Valyu DeepSearch	Linkup	Tavily
Web search	Yes	Yes	Yes	Yes
Proprietary data	No	36+ sources	No	No
FreshQA accuracy	Not published	79%	Not published	Not published
SimpleQA accuracy	77–86%	94%	91%	Not published
Dedicated search endpoint	No (/chat only)	Yes	Yes	Yes
MCP integration	No	Yes	No	No
LangChain integration	Limited	Yes	Yes	Yes (native)
Webhooks	No	Yes (DeepResearch)	No	No
Predictable pricing	No (token-variable)	Yes	Yes	Yes
Deep research mode	Yes (sonar-deep-research)	Yes (DeepResearch API)	Yes (deep search)	No
Entry price (web search)	$5/1,000 requests	Free $10 credit	€5/1,000 queries	Free 1k credits/mo

Which Alternative for Which Use Case

Building a RAG pipeline on LangChain/LlamaIndex?
Start with Tavily. It's the path of least resistance and performs well. If you hit accuracy issues or need data beyond the public web, move to Valyu.

Building anything that touches financial data?
Valyu. SEC filings, earnings data, stock prices, FRED economic data, balance sheets, insider trading, all in one API call. No other search API comes close for this use case.

Building biomedical or clinical research tools?
Valyu. PubMed, bioRxiv, ClinicalTrials.gov, ChEMBL, DrugBank, Open Targets, FDA drug labels. The Bio app (310 GitHub stars) is a live demo of what's possible.

Need multi-step autonomous research (replacing sonar-deep-research)?
Valyu DeepResearch API. It's the only deep research API that combines multi-step synthesis with access to authoritative specialised databases, plus structured output formats and webhook support.

Pure web search with transparent pricing, no specialised data needed?
Linkup for pricing predictability.

A Note on What Sonar Does Well

Sonar has strong developer documentation, an OpenAI-compatible API format that makes migration easy, and solid performance for general web Q&A tasks. The sonar-reasoning-pro model is genuinely useful for chain-of-thought web-grounded reasoning.

The limitations documented here are real, but they're architectural constraints that come from being a secondary product of a consumer AI company, most likely not signs of bad engineering. If your use case is pure web Q&A at scale and you're happy with the public web as your data universe, Sonar is a viable choice.

The alternatives above exist for when those constraints become blockers.

FAQ

What is the best alternative to Perplexity Sonar API?
Valyu DeepSearch for developers who need specialised data access (finance, biomedical, academic) or benchmark-leading accuracy. Linkup for predictable pricing and architectural control. Tavily for the fastest LangChain/LlamaIndex integration.

What is the best alternative to Perplexity Sonar Deep Research?
Valyu's DeepResearch API is the only alternative that matches sonar-deep-research on multi-step research synthesis while also accessing SEC filings, PubMed, academic journals, and clinical trial data that Sonar cannot reach.

Is Perplexity Sonar web-only?
Yes. All Sonar models (Sonar, Sonar Pro, Sonar Reasoning, Sonar Reasoning Pro, Sonar Deep Research) search only the public web and Perplexity's index. They have no access to SEC filings, academic databases, clinical trials, or other specialised data sources.

Why is Sonar API unreliable?
Perplexity's primary product is a consumer chatbot. The API is a secondary product. Developer forums document 20+ daily outages with no reflection on the official status page. The API capacity and reliability engineering reflects these priorities.

Does Perplexity Sonar have an MCP integration?
Yes. Sonar offers a Model Context Protocol server. Valyu also does. It can be added to Claude Desktop, Cursor, and other MCP-compatible environments with one command: npx skills add valyuAI/skills.

How does sonar-deep-research pricing work?
Sonar Deep Research charges $2/million input tokens, $8/million output tokens, $5 per 1,000 searches (a single request might trigger 30 searches = $0.15 in search fees alone), and $3/million reasoning tokens. The total cost per request is hard to predict and can range significantly based on query complexity.