QUAOAR

Built by Philip Simon Derock
for the SerpApi India Hackathon 2026

Docs

Quaoar docs

Quaoar reads an SME IPO prospectus, pulls out the claims that can be checked against the outside world, and checks each one through SerpApi. The result is a card: every line says checks out, doesn't match or couldn't find, with the source behind it. It never gives a verdict on the company and never gives investment advice.

Install

One line on macOS or Linux. It installs uv first if you don't have it, then the quaoar command (Python 3.13 is fetched if needed).

curl -fsSL quaoar.philipsimonderock.com/install | sh

The same script, straight from GitHub:

curl -fsSL https://raw.githubusercontent.com/simon-derock/quaoar/main/install.sh | sh

Already have uv:

uv tool install git+https://github.com/simon-derock/quaoar

Try it once without installing anything:

uvx --from git+https://github.com/simon-derock/quaoar quaoar replay trafiksol

From source, for development:

git clone https://github.com/simon-derock/quaoar && cd quaoar
uv sync
uv run quaoar

Quick start

No API keys are needed to watch a recorded check and ask about it.

$ quaoar
› /replay trafiksol          watch the recorded Trafiksol check
› /proof 2                   the source behind line 2: page, date, SerpApi search id
› why was this flagged?      the analyst answers, citing card lines
› /cases                     every recorded case

New to IPOs? Type hi, what is an SME IPO or where do I get a prospectus. Plain answers are built in, in English and basic Hinglish.

Scan a prospectus

A live scan needs a SerpApi key and a Cohere key. Put them in a .env file in the folder you run Quaoar from:

SERPAPI_API_KEYS=your-serpapi-key
COHERE_API_KEYS=your-cohere-key

Then check the setup without spending credits, and scan:

quaoar doctor
quaoar scan path/to/red-herring-prospectus.pdf
quaoar scan https://www.sebi.gov.in/.../prospectus.pdf
OptionWhat it does
--mode agent|fixedagent (default) lets the investigator fill evidence gaps; fixed uses query templates only.
--max-credits NCaps the SerpApi credits this scan may spend (default 45).
--cutoff YYYY-MM-DDReads evidence as of this date. By default it is the date printed on the prospectus.
--nowReads evidence up to today instead.
--jsonlPrints the raw event stream.

A fresh scan costs about 12 to 37 searches. Repeating it costs nothing: every search and model read is kept in a local ledger. Exchange sites (NSE, BSE) forbid automated downloads, so Quaoar refuses their links; save the PDF yourself or use the lead manager's website. For the version an investor sees while the issue is open, scan the red herring prospectus (RHP).

Terminal commands

CommandWhat it does
/scan <pdf|url>Scans a prospectus; a path or URL typed on its own does the same.
/replay <name>Plays a recorded case with no keys.
/casesLists the recorded cases.
/cardShows the last card again.
/proof <n>The evidence behind line n: URL, date, engine, SerpApi search id.
/ask <question>Asks the analyst about the card. Any open question with a card on screen does the same.
/traceWhat caused what in the last scan.
/commentDrafts a neutral public-comment letter from the lines that didn't match. You send it; Quaoar never does.
/mode agent|fixedHow evidence gaps are filled in the next scan.
/budget <n>Credit cap for the next live scan.
/creditsSearches left per key and the cache hit rate.

Command line

CommandWhat it does
quaoarOpens the interactive terminal.
quaoar scan <pdf|url>Runs a check and saves the card under ~/.quaoar/scans.
quaoar ask <case|scan-id> "<question>"Asks the analyst about a recorded case or a saved scan.
quaoar replay <case>Plays a recorded case.
quaoar card <scan-id>Prints a saved card.
quaoar comment <scan-id>Drafts the public-comment letter.
quaoar diff <earlier> <later>Compares two versions of a prospectus (draft, red herring, final). Reads claims only, no searches.
quaoar doctorChecks keys, model access and the ledger without spending credits.
quaoar ledger stats|verifyCredits by engine and key, cache hit rate; verifies stored responses.
quaoar keys statusSearches left on each SerpApi key.
quaoar serveRuns the replay-only web API.
quaoar mcpRuns the MCP server over stdio.

Reading the card

StatusMeaning
checks outPublic evidence agrees with the prospectus.
doesn't matchPublic evidence disagrees, and the source is shown. It is a reason to look closer, not a conclusion.
couldn't findNo public evidence turned up. Small private firms often barely appear online, so this is common and is never counted against a company.

Statuses come only from fixed rules, never from a language model. The card counts the three kinds and gives no overall score.

Checks and rules

RuleCheckDoesn't match when
VX-02VendorShown as couldn't find when the vendor isn't on company-registry pages, or has no company form in its name.
VX-03VendorThe quote is 100 times or more the vendor's paid-up capital.
VX-04VendorThe registry lists the vendor as struck off, dormant, dissolved or in liquidation, or its last balance sheet is over 18 months older than the prospectus.
VX-05VendorIts Google Maps listing is marked permanently closed.
VX-06VendorCourt or SEBI pages naming the vendor are dated on or before the prospectus.
SV-02PremisesThe registered office, factory or warehouse is closed on Google Maps.
SV-04PremisesA factory or warehouse is listed on Maps as a residential place.
BK-04Lead managerA SEBI order names the merchant banker before the prospectus date.
BK-05Lead managerA SEBI order names a company in the banker's past-issues table.
LT-03LitigationCourt or SEBI matters naming the issuer turn up beyond those the prospectus discloses.
NW-01NewsDated news before the prospectus mentions SEBI action, a complaint or a trading halt.

Promotion volume (YouTube videos, news articles) is shown as context and never counted. A person's name alone is never enough to match a record, and cards never name individuals.

AI agents

Two PydanticAI agents on Cohere. Both gather and explain evidence; fixed rules set every status, and code checks everything an agent says before anyone sees it.

The Investigator

Runs during a scan when a fixed search comes back empty. It plans which evidence gap to close next and rewords the search: the registry city, the CIN, the name without its legal suffix. It may run at most 8 searches, spend 6 credits and make 10 model requests per investigation. It hands over the gaps it closed and the ones still open; the rules then read only the evidence.

The Analyst

Answers questions about a finished card. A retrieval step marks the lines related to the question; the model reads lines for free and runs a follow-up search only when no line covers the subject, at most 3 searches and 3 credits per question. Its answer is shown only if every cited line or result exists, every number appears in a cited source, and the wording and advice guards pass. Otherwise the card-only answer is shown. Advice and instruction-shaped questions get fixed replies without a model call.

$ quaoar ask trafiksol "why was this flagged?"
Line 2 doesn't match: the vendor named for the IPO money quoted ₹17.70 crore, while
registry pages show its paid-up capital as ₹1 lakh, 1,770 times smaller.
  line 2 · instafinancials.com (search 6ac7fe400e285d07c1e956d5)
answered by the analyst agent

In both, the model chooses search terms only; code builds each query, adds the site allowlist, and sends it through the same cache, key pool and credit budget as every other search. Web text is marked as untrusted data, and every trace is stored, so asking again replays it with no model call.

From your own agent

claude mcp add quaoar -- uvx --from git+https://github.com/simon-derock/quaoar quaoar mcp
ToolWhat it does
list_replaysRecorded cases, no keys needed.
replay_cardThe card of a recorded case.
ask_cardA cited answer about a recorded case or a saved scan.
scan_prospectusA live check of a local PDF or https URL (uses credits).
saved_cardThe card of a scan run earlier on this machine.
draft_commentA neutral public-comment letter from the lines that didn't match.
ledger_statsCredits by engine and key, and the cache hit rate.

The skill file skills/quaoar/SKILL.md in the repository holds the playbooks and the language rules for agents.

Evidence and privacy

How it uses SerpApi

EngineUsed for
DuckDuckGo (site-restricted)Company-registry pages, SEBI orders, Indian Kanoon and IBBI records
Google MapsVendor and premises listings, open or closed, place type
Google NewsDated coverage before the prospectus date
YouTubePromotion volume, shown as context only
GoogleGeneral web, the agents' last resort

Every search goes through one client with a query guard, a cache, a credit budget and key rotation. Site-restricted searches use DuckDuckGo because, in a probe, Google returned off-site results for site: queries.

Limits and evaluation

Facts with sources. Not investment advice.