Skip to content

feat(demos): Mixpeek managed backend for visual web search - #53

Open
esteininger wants to merge 4 commits into
StarTrail-org:mainfrom
esteininger:feat/mixpeek-managed-backend
Open

esteininger wants to merge 4 commits into
StarTrail-org:mainfrom
esteininger:feat/mixpeek-managed-backend

Conversation

@esteininger

Copy link
Copy Markdown

Summary

Adds demos/mixpeek/ — a managed alternative to the local PixelRAG pipeline using Mixpeek as the backend. No local GPU, no FAISS, no Playwright setup needed.

Pipeline mapping

PixelRAG stage Local pipeline Mixpeek equivalent
pixelshot (render) Playwright CDP, screenshot tiles web_scraper extractor (render_strategy: auto)
pixelrag chunk Split tiles into 1024px strips Semantic chunking (chunk_strategy: paragraphs)
pixelrag embed Qwen3-VL 2B on local GPU E5-Large (text 1024D) + SigLIP (visual 768D) + DINOv2 (structure 768D)
pixelrag build-index FAISS IVFFlat Managed vector store
pixelrag serve FastAPI search API Retriever endpoint

What's included

  • web_search.py: End-to-end CLI script. Creates a throwaway namespace (auto-expires), uploads a seed URL, crawls with the web_scraper extractor, builds a retriever, and runs a search query. Supports configurable crawl depth, max pages, crawl mode (deterministic/semantic), and render strategy.
  • README.md: Quickstart, full pipeline comparison, and guidance on when to use managed vs local.

Usage

pip install requests
export MIXPEEK_API_KEY=sk_...   # free key at studio.mixpeek.com

python demos/mixpeek/web_search.py \
    --url https://docs.example.com \
    --query "authentication" \
    --max-depth 2 --max-pages 50

Tested

Ran against the live Mixpeek API — returns ranked results with scores and source URLs. Namespaces auto-expire so no cleanup needed.

Adds demos/mixpeek/ — a managed alternative to the local PixelRAG
pipeline. Uses Mixpeek's web_scraper extractor to handle rendering,
embedding, indexing, and serving without local GPU or FAISS.

- web_search.py: end-to-end CLI script (namespace → bucket → collection
  → batch → retriever → search) with configurable crawl params
- README.md: quickstart, pipeline mapping table, and when-to-use guide

Tested against the live Mixpeek API — returns results with scores.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@vercel

vercel Bot commented Jun 20, 2026

Copy link
Copy Markdown

@esteininger is attempting to deploy a commit to the andylizf's projects Team on Vercel.

A member of the Team first needs to authorize it.

@andylizf

Copy link
Copy Markdown
Contributor

Thanks for putting this together. The code is clean and self-contained (new demos/mixpeek/ dir, nothing else touched), so the merge risk is near zero.

That said, we want to think about whether adding a managed/commercial backend demo fits the project's positioning — PixelRAG's core thesis is self-hosted native-multimodal retrieval, and this demo replaces that stack with a third-party service. We'll discuss internally and get back to you.

In the meantime: CI would need ruff check --fix && ruff format (unused import json + formatting), but those are trivial.

@ASuresh0524

Copy link
Copy Markdown
Collaborator

@esteininger — picking this up after far too long. Four months of silence here is on us, not you, and I want to be straight about where it actually stands.

The hold was never the code. andylizf's review said the merge risk is near zero (new demos/mixpeek/ only, nothing else touched), and that's still true — it merges cleanly onto today's main. The hold was the positioning question: whether a managed, commercial backend demo fits a project whose thesis is self-hosted native-multimodal retrieval, with "we'll discuss internally and get back to you." Nobody got back to you.

That question has since been answered in practice, which is the part that makes keeping this open unfair. #175 landed last week — demos/parallel_search/, same shape as yours, a third-party hosted search service, contributed by someone who works there. #191 is open now with demos/keenable_search/ in the same form. So the de facto policy is that vendor demos are acceptable in demos/, while this PR has been held four months on the concern that they aren't.

Either this merges on the same basis #175 did, or there's a distinction between them that we should state plainly so you and the other contributors know the rule. I don't think the distinction can be "managed service" — #175 is one too.

@andylizf @yichuan-w this needs a yes/no rather than another month. My read: the honest options are to merge it, or to write down a demos/ policy that explains why #175 qualifies and this doesn't — and if it's the latter, close this with that reason rather than leaving it open.

One technical note either way, so it's not a surprise: the Vercel deploy check is still unauthorized ("a member of the Team first needs to authorize it"), so this has never had a green run. That needs a maintainer click regardless of the decision.

🤖 Generated with Claude Code

@ASuresh0524

Copy link
Copy Markdown
Collaborator

Housekeeping while the positioning question is still open, so this isn't sitting on stale information when it gets answered.

Merged main in and pushed. The branch was 95 commits behind and its CI run had aged out of GitHub's retention, which is why it showed no checks at all — not a failure, just nothing to show. The merge is clean, and andylizf's read holds up: against current main this reduces to exactly two new files under demos/mixpeek/, nothing else touched.

One thing to fix whichever way the decision goes. #209 removes the demos/ exclusion from lint. Under that wider scope this file doesn't pass:

demos/mixpeek/web_search.py:26:8: F401 [*] `json` imported but unused
demos/mixpeek/web_search.py:322:11: F541 [*] f-string without any placeholders

plus a ruff format pass (create_retriever's signature fits on one line, and the argparse block rewraps). Both lint errors are --fix-able. It passes today only because demos/ is excluded, so this isn't something you did wrong — the goalposts are moving under you.

@esteininger — the open question is still the one andylizf raised about where managed/commercial backends sit in the project, not your code. I'm drafting a written policy for that class of PR so this stops being decided ad hoc, and you'll get a straight answer against it rather than more silence.

ASuresh0524 and others added 2 commits November 17, 2026 00:29
StarTrail-org#209 removed `demos` from the ruff exclude list, so this file is now linted.
It was written while demos/ was excluded, so this is the goalposts moving,
not a defect in the PR:

    demos/mixpeek/web_search.py:26:8: F401 `json` imported but unused
    demos/mixpeek/web_search.py:322:11: F541 f-string without any placeholders

Both auto-fixed, plus a `ruff format` pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ASuresh0524

Copy link
Copy Markdown
Collaborator

Status update — this is now green and mergeable, and the only thing left on it is a decision no amount of code review settles.

What I changed: merged current main in (CI had never run here; the original workflow run had aged out of retention) and fixed the lint errors that appeared when #209 removed demos/ from the ruff exclude list. That was the goalposts moving under you, not a defect in the PR. Against current main: ruff check and ruff format --check clean, and the change is still confined to its own directory.

What is left: the positioning question @andylizf raised — whether a managed/commercial backend demo belongs in this repo — has never been answered, and it is the only thing holding this. There is precedent in both directions: #175 merged a vendor demo into demos/, and #192 established a deliberately restrictive policy for hosted readers in eval/. demos/ has no written policy at all, which is the actual gap.

I have drafted one for @ASuresh0524 and @andylizf to settle, proposing the bar be about upkeep rather than commerce: the demo has to show something about PixelRAG rather than just the vendor, stay self-contained, pass lint, and carry a named owner and a Last verified date, with removal after 30 days of being broken not treated as a negotiation.

You will get a yes or a no against that, not more silence. Apologies that it has taken this long to get to a straight answer.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants