This reverts commit 10966beb40019c5c983e55b81e55fdeb30dbae35.
Wedgecheck
Wedgecheck turns a product URL or a one-line description into a sourced market/competitive brief: real search-volume/complaint signal, named real competitors with pricing where findable, their common gaps, and a specific positioning gap — every claim cited to a real source URL, never invented.
The research and citation engine is entirely gpt-researcher (Apache-2.0). Wedgecheck's own code only does two things:
app/product_input.py— turns a URL into real extracted text (plain HTTP- HTML parsing, no LLM) so "what is this product" never hallucinates.
app/brief.py— builds the research query, retries the research pass if the retriever comes back with zero sources (see below), and refuses to hand back an unsourced report.
Why the retry logic exists
gpt-researcher fires several sub-queries concurrently. The free
duckduckgo retriever (ddgs) has no retry of its own and silently turns
any error into an empty result list — which can come back as zero
sources for the whole report, with no exception raised anywhere. Left
unchecked this produces a confident, detailed, fully invented report with
"Sources (0)" quietly sitting at the bottom — the exact failure this
product exists to prevent.
This is usually the free retriever's own low recall on a given phrasing,
not a rate limit — retrying the identical query rarely helps (confirmed
live: the same description failed with zero sources on every attempt,
reproduced deterministically across separate sessions). Rephrasing the
description, or setting RETRIEVER=tavily, actually helps; waiting and
resubmitting the same text usually doesn't.
generate_market_brief() retries the full research pass (a fresh
GPTResearcher, so a fresh retriever session) with backoff whenever a pass
comes back with zero source URLs, and raises WedgecheckResearchError
instead of returning an unsourced MarketBrief if every attempt still comes
back empty. Tunable via env: WEDGECHECK_RESEARCH_MAX_ATTEMPTS (default 3),
WEDGECHECK_RESEARCH_RETRY_BACKOFF_SECONDS (default 4).
Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Set at minimum an OpenAI-compatible chat-completions endpoint:
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://openrouter.ai/api/v1 # or any OpenAI-compatible gateway
No paid retriever key is required — RETRIEVER defaults to duckduckgo
(free, no key). For more reliable results than the free retriever, set
RETRIEVER=tavily and TAVILY_API_KEY=....
Two more knobs, both passed straight through to gpt-researcher's own
MAX_SUBTOPICS/LANGUAGE config: WEDGECHECK_MAX_SUBTOPICS (default 3)
caps how many subtopics a report breaks into; WEDGECHECK_REPORT_LANGUAGE
(default english) is the language the whole report (not just the query)
is written in — e.g. WEDGECHECK_REPORT_LANGUAGE=spanish produces a real
Spanish-language brief, cited sources and all.
Fully free self-host (no paid key at all)
Production (wedgecheck.ereboslab.com) runs with no paid LLM key —
OPENAI_BASE_URL points at this portfolio's own free Cloudflare Workers AI
relay instead of OpenRouter/OpenAI:
export OPENAI_API_KEY=<the relay's low-value AI_RELAY_KEY>
export OPENAI_BASE_URL=https://ai-relay.subasiarhan3.workers.dev/v1
export EMBEDDING=custom:bge # relay's /v1/embeddings route (Workers AI bge-base-en-v1.5)
export WEDGECHECK_NON_STREAMING_LLM=1
Two things make this work that are easy to miss if you swap in a different minimal relay:
- The relay always answers a flat JSON body even when the request says
"stream": true(no real SSE). gpt-researcher's report writer always requests streaming, so withoutWEDGECHECK_NON_STREAMING_LLM=1(app/llm_compat.py) you'll seeNo generation chunks were returned. - gpt-researcher's embedding step defaults to a paid
openai:text-embedding-3-small.EMBEDDING=custom:bgeroutes it at the relay's/v1/embeddingsroute instead, so the image never needs torch/sentence-transformers.
Usage
CLI:
python cli.py --url https://example.com
python cli.py --description "A hosted Postgres backend for indie SaaS teams"
Writes <slug>.md and <slug>.json under ./output/.
Web app:
uvicorn app.main:app --reload
GET / — single-form UI. POST /api/brief — JSON API
({"url": "..."} or {"description": "..."}). GET /healthz — health check.
Every completed brief (web form or /api/brief) is persisted to a local
SQLite DB (app/store.py, path via WEDGECHECK_DB_PATH, default
./data/wedgecheck.db) so it isn't lost after one request/session:
GET /b/{id}— a shareable permalink for one completed report. The/api/briefJSON response now includesidandpermalink_url. Permalinks are public by id (no auth) — seeapp/store.py's docstring for why that's the right tradeoff here.GET /history— a browser's own past briefs, scoped to an anonymous session cookie (wedgecheck_session, no account system). Linked from every page's nav.
In Docker, mount a volume at /app/data or these survive only until the
next container recreate.
POST / and POST /api/brief are rate-limited per client IP — each one is a
real 60–120s research pass against the shared LLM relay, so an unlimited
public endpoint is a real abuse/cost vector, not a hypothetical one. Default:
3 requests per 10 minutes per IP, both tunable
(WEDGECHECK_RATE_LIMIT_MAX_REQUESTS, WEDGECHECK_RATE_LIMIT_WINDOW_SECONDS).
Exceeding it returns 429 with a Retry-After header (JSON for the API, a
friendly banner for the form).
The IP used for that limit is the raw socket peer by default — X-Forwarded- For is only honored when the immediate connecting peer is listed in
WEDGECHECK_TRUSTED_PROXY_IPS (comma-separated, empty/unset by default).
Trusting that header unconditionally (the old behavior) let any direct
connection — including another container on the same shared products-net
docker network, bypassing Caddy entirely — self-assign a fresh rate-limit
bucket per request just by setting its own header, a complete bypass of the
limiter. See app/rate_limit.py for the full writeup and how to set this in
production (confirm Caddy's actual peer address as seen inside the
container, typically the docker bridge gateway, not 127.0.0.1).
The url fetch (web form or /api/brief) also enforces a response-size
cap, independent of the SSRF checks: a URL can resolve to a perfectly
public address and still serve an unbounded body, which would otherwise be
buffered in full into this single-worker container's memory. Default 5MB,
tunable via WEDGECHECK_MAX_FETCH_BYTES; enforced against both the
declared Content-Length and the real streamed byte count, so a missing
or lying header can't bypass it. See app/ssrf_guard.py.
Both url and description (web form or /api/brief) are length-capped
before either is used for anything — the rate limiter above only bounds
how many requests a client can make, not how large one is, and an
oversized description would still be handed straight to gpt-researcher
(real compute/token spend on the shared LLM relay) and persisted to
sqlite forever. Defaults: 2048 chars for url, 4000 chars for
description, tunable via WEDGECHECK_MAX_URL_CHARS /
WEDGECHECK_MAX_DESCRIPTION_CHARS. See app/product_input.py.
The raw HTTP request body itself (POST / and POST /api/brief) is also
capped, independent of the field-length check above — that check only runs
after FastAPI has already buffered and parsed the entire body (so an
oversized hidden/extra JSON field, or a body sent with no Content-Length
at all via chunked transfer, would still be read fully into memory first).
Default 64KiB, tunable via WEDGECHECK_MAX_REQUEST_BYTES; enforced against
both the declared Content-Length (fast path, zero bytes read) and the
real streamed byte count (so a missing or lying header can't bypass it
either), same two-layer pattern as the url-fetch cap above. Hitting this on
POST / renders the same in-page HTML error banner every other error on
that route does (rate limit, SSRF, length cap, a failed research pass);
POST /api/brief still gets the plain JSON 413 it always did. See
app/body_limit.py and main.py's _html_aware_http_exception_handler.
Status
Live at https://wedgecheck.ereboslab.com (Docker on the Oracle box,
/opt/infra-box/stacks/wedgecheck). Verified end-to-end against the real
code path, not a mock: the retry/fail-loud logic in app/brief.py has been
exercised live, repeatedly, and correctly discards an LLM-written report
whenever the free duckduckgo retriever comes back with zero real sources
on every attempt (raising WedgecheckResearchError) rather than ever
serving a confidently-written but unsourced brief.
A full success case (non-zero source_urls, no exception) depends on the
free duckduckgo/ddgs retriever actually returning results for the given
query at request time, which it does not always do. See
~/products/plans/wedgecheck.md for the live evidence and what's still
worth doing about retriever reliability (e.g. RETRIEVER=tavily).