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
| Option | What it does |
|---|---|
--mode agent|fixed | agent (default) lets the investigator fill evidence gaps; fixed uses query templates only. |
--max-credits N | Caps the SerpApi credits this scan may spend (default 45). |
--cutoff YYYY-MM-DD | Reads evidence as of this date. By default it is the date printed on the prospectus. |
--now | Reads evidence up to today instead. |
--jsonl | Prints 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
| Command | What 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. |
/cases | Lists the recorded cases. |
/card | Shows 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. |
/trace | What caused what in the last scan. |
/comment | Drafts a neutral public-comment letter from the lines that didn't match. You send it; Quaoar never does. |
/mode agent|fixed | How evidence gaps are filled in the next scan. |
/budget <n> | Credit cap for the next live scan. |
/credits | Searches left per key and the cache hit rate. |
Command line
| Command | What it does |
|---|---|
quaoar | Opens 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 doctor | Checks keys, model access and the ledger without spending credits. |
quaoar ledger stats|verify | Credits by engine and key, cache hit rate; verifies stored responses. |
quaoar keys status | Searches left on each SerpApi key. |
quaoar serve | Runs the replay-only web API. |
quaoar mcp | Runs the MCP server over stdio. |
Reading the card
| Status | Meaning |
|---|---|
| checks out | Public evidence agrees with the prospectus. |
| doesn't match | Public evidence disagrees, and the source is shown. It is a reason to look closer, not a conclusion. |
| couldn't find | No 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
| Rule | Check | Doesn't match when |
|---|---|---|
VX-02 | Vendor | Shown as couldn't find when the vendor isn't on company-registry pages, or has no company form in its name. |
VX-03 | Vendor | The quote is 100 times or more the vendor's paid-up capital. |
VX-04 | Vendor | The 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-05 | Vendor | Its Google Maps listing is marked permanently closed. |
VX-06 | Vendor | Court or SEBI pages naming the vendor are dated on or before the prospectus. |
SV-02 | Premises | The registered office, factory or warehouse is closed on Google Maps. |
SV-04 | Premises | A factory or warehouse is listed on Maps as a residential place. |
BK-04 | Lead manager | A SEBI order names the merchant banker before the prospectus date. |
BK-05 | Lead manager | A SEBI order names a company in the banker's past-issues table. |
LT-03 | Litigation | Court or SEBI matters naming the issuer turn up beyond those the prospectus discloses. |
NW-01 | News | Dated 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
| Tool | What it does |
|---|---|
list_replays | Recorded cases, no keys needed. |
replay_card | The card of a recorded case. |
ask_card | A cited answer about a recorded case or a saved scan. |
scan_prospectus | A live check of a local PDF or https URL (uses credits). |
saved_card | The card of a scan run earlier on this machine. |
draft_comment | A neutral public-comment letter from the lines that didn't match. |
ledger_stats | Credits 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
- As of the prospectus date. Evidence is read as of the date printed on the prospectus, so later news can't change the card. Registry and Maps pages show today's state; strict before-listing evidence relies on dated news, orders and court records.
- Untrusted text. Text from PDFs and search results is cleaned of control characters and bidi tricks. Personal identifiers are masked before anything reaches the model, and injection-shaped text is flagged.
- Every line has a source. Each source keeps its URL, date, engine and SerpApi search id, so anyone can repeat the check.
- Keys stay local. Keys live in your
.env, are redacted from every log and replay, and the public website holds none.
How it uses SerpApi
| Engine | Used for |
|---|---|
| DuckDuckGo (site-restricted) | Company-registry pages, SEBI orders, Indian Kanoon and IBBI records |
| Google Maps | Vendor and premises listings, open or closed, place type |
| Google News | Dated coverage before the prospectus date |
| YouTube | Promotion volume, shown as context only |
| General 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
- Small evaluation. One known case in two versions (Trafiksol) and thirteen ordinary companies with a completed card, from three audits; no accuracy claim is made. Control audit · 2026 survey · Coverage test.
- Analyst. Offline, 40 of 40 questions cited the expected line or said plainly the card had none; with the live model, 23 of 24. Analyst audit.
- A screen, not a verdict. The 100× vendor-capital rule was fixed before any control was scanned. Real small suppliers can quote large amounts too.
- Couldn't find is not a finding. It is never counted against a company.
Facts with sources. Not investment advice.