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:

  1. app/product_input.py — turns a URL into real extracted text (plain HTTP
    • HTML parsing, no LLM) so "what is this product" never hallucinates.
  2. 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 without WEDGECHECK_NON_STREAMING_LLM=1 (app/llm_compat.py) you'll see No generation chunks were returned.
  • gpt-researcher's embedding step defaults to a paid openai:text-embedding-3-small. EMBEDDING=custom:bge routes it at the relay's /v1/embeddings route 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/brief JSON response now includes id and permalink_url. Permalinks are public by id (no auth) — see app/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).

Description
Sourced market/competitive brief generator built on gpt-researcher
Readme 126 KiB
Languages
Python 94.7%
HTML 4.1%
Dockerfile 1.2%