# Examples

A project gallery of full end-to-end applications built with SIE. Each project lives in its own subdirectory. Clone it, run it, learn from it.

New to SIE? Start with the **[quickstart notebook](./quickstart.ipynb)** [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/superlinked/sie/blob/main/examples/quickstart.ipynb): encode, score, and extract in 5 minutes, then pick a project below.

## Gallery

Use this table to pick the right starting point. "Runnable" means the
example has code, sample data or data-fetch instructions, and a documented
local path. "Advanced" examples may require a custom SIE image or third-party
service keys. "External project guide" means docs-only onboarding that deep-links
to a separately maintained repository (clone and run there).

| Example | Best for | SIE primitives | Setup | Status |
|---|---|---|---|---|
| [Self-hosted product search in 5 min](./ecommerce-product-search) | Showing the fastest local product-search path with extraction, embeddings, and reranking | `extract`, `encode`, `score` | Local SIE Docker image, Python or TypeScript app | Runnable |
| [Find the best retrieval strategy for your RAG](./retrieval-ablation) | Picking a production RAG retrieval pipeline by evals on real financial documents | `encode`, `score` | SIE endpoint, Turbopuffer key, optional SIE API key for auth-enabled clusters | Runnable benchmark |
| [Rank exact primary-source passages](./rerank) | Testing a reranker on verbatim SEC, CMS, NTSB, and Supreme Court excerpts, where the closest wrong passage answers half the question | `score` | SIE endpoint with Qwen3 Reranker 4B; `fetch.py` pulls the recorded run, `score.py` reproduces the scores with no key | Runnable recorded example |
| [Extract custom entities from primary sources](./named-entity-extraction) | Changing zero-shot labels across financial, healthcare, rail-safety and legal text, with the two labels that came back empty left visible | `extract` | SIE endpoint with GLiNER multi v2.1; `fetch.py` pulls the recorded run, `score.py` reproduces the counts with no key | Runnable recorded example |
| [Extract the entity types you name, with no model to train](./custom-entity-types) | Asking for the 85 entity types of seven zero-shot NER sets and scoring exact spans against GPT-6 Luna, GPT-6 Sol, Claude Haiku 4.5, SIE Qwen3.8 27B, AWS Comprehend and spaCy, with a paired bootstrap and the price of each | `extract` | SIE server with GLiNER BioMed Large; `fetch.py` pulls the recorded run, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Answer a question from a passage, and quote the sentence you used](./chat) | Checking a generated answer for its citation, its length and whether it declines a question the passage cannot answer | `chat/completions` | SIE Cloud with Qwen3.8 27B; `fetch.py` pulls the recorded run, `score.py` reproduces the numbers with no key | Runnable recorded example |
| [Run a coding agent on SIE with OpenCode](./coding-agent-opencode) | Pointing OpenCode at a laptop server, one 80 GB GPU, a self-hosted server with an OpenRouter upstream, a self-hosted cluster or SIE Cloud, and checking the agent loop the way OpenCode drives it: streaming tool-call deltas, parallel calls, tool-result round trips, a 64K-plus prompt, a 64 KiB tool call, finish reasons, usage and the reasoning field; `session_load.py` measures how many agent sessions one endpoint holds | `chat/completions` | An SIE Cloud endpoint that lists GLM-5.3-Flash via SIE Relay, or a local server, alone or with an OpenRouter key for GLM-5.3-Flash; the laptop recipe was run on Apple Silicon with Qwen3.5-4B, the GPU and cluster recipes on one H100 with Qwen3.8-27B-FP8; `conformance.py` reports every case, `run_gate.sh` makes OpenCode fix a seeded failing test | Runnable check, laptop, one-GPU and SIE Cloud results recorded |
| [Try a local System One model](./systemone-local) | Running unchanged TypeSafe SDK code against SIE by changing its base URL, and checking every SDK call that reaches the server: each question type, state shape, `models.list()`, the async client and the error classes | `systemone` | A local `sie-server` with GLiNER2.5-Decide on CPU, or SIE Serverless; `conformance.py` reports every case | Runnable check |
| [Route requests while skipping most generation calls](./request-routing) | Assigning support, banking and assistant requests to routes with an embedding classifier and conditional generation | `encode`, `chat/completions` | SIE server with Qwen3 Embedding 4B and Qwen3.8 27B; recorded 3,000-case verification needs no API key | Runnable recorded example |
| [Send each request to a cheap or a strong LLM](./request-routing/cost) | Cutting LLM spend with a bge-m3 nearest-neighbour router that picks GPT-6 Luna or GPT-6.1 Sol per request: 38.6% less than always using GPT-6.1 Sol at 95.8% of its quality on 728 held-out requests of a pre-registered study | `encode` | SIE Serverless with bge-m3; `fetch.py` pulls the recorded study, `score.py` reproduces the held-out table with no key | Runnable recorded example |
| [Turn PDF pages into Markdown, scored on olmOCR-Bench](./document-to-markdown-olmocr) | Converting all 1,403 pages of Ai2's olmOCR-Bench with LightOnOCR-2-1B and scoring them with Ai2's own scorer, beside published Azure Document Intelligence and AWS Textract runs | `extract` | SIE Cloud with LightOnOCR-2-1B; `fetch.py` pulls the recorded run, `score.py` reproduces the scores with no key | Runnable recorded example |
| [Read receipt photos and handwriting, scored against GPT-5.4 mini](./ocr-receipts-handwriting) | Reading 600 receipt photos and handwritten notes with LightOnOCR-2-1B beside GPT-5.4 mini, PaddleOCR, Tesseract and EasyOCR, scored by exact-word recall | `extract` | SIE Cloud with LightOnOCR-2-1B; `fetch.py` pulls the recorded run, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Keep a support assistant on policy while customers push it](./support-assistant-policy) | Replaying 55 scripted support conversations, 275 attempts to talk the assistant out of five rules, against SIE and five hosted models, scored by a judge model and hand labels | `chat/completions` | SIE Cloud with Qwen3.8 27B, plus OpenAI and Anthropic keys for the other arms; `fetch.py` pulls the recorded run, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Write public status updates from internal incident reports](./incident-status-updates) | Checking a generated status update for leaked hosts, tickets, staff names and the wrong outage window | `chat/completions` | SIE Cloud with Qwen3.8 27B; `fetch.py` pulls the recorded run, `score.py` reproduces the number with no key | Runnable recorded example |
| [Build a citable graph from filing text](./knowledge-graph) | Turning SEC, NHTSA and FDA paragraphs into entities and relations with offsets, and seeing where the relations go wrong | `extract` | SIE Cloud with GLiNER2; `fetch.py` pulls the recorded run, `score.py` reproduces the counts with no key | Runnable recorded example |
| [Find the answer when a look-alike passage sits beside it](./lookalike-search) | Ranking 5,658 regulation and documentation passages for 440 frozen questions, each with a named look-alike next to its answer, against OpenAI, Voyage and Cohere; plus per-query scores on eight MTEB retrieval tasks | `encode` | SIE Cloud with Qwen3 Embedding 4B; `fetch.py` pulls the recorded vectors and rankings, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Find the passage that answers a question](./search) | Ranking 253 regulation and documentation passages full of near misses, with query-side encoding | `encode` | SIE Cloud with Arctic Embed L v2.0; `fetch.py` pulls the recorded vectors, `score.py` ranks them with no key | Runnable recorded example |
| [Pick the passage that meets every condition](./multi-vector) | Separating same-page near-duplicates with ColBERT late interaction, scored token by token | `encode` | SIE Cloud with GTE-ModernColBERT-v1; `fetch.py` pulls the recorded token vectors, `score.py` scores them with no key | Runnable recorded example |
| [Fill a JSON Schema from a messy document](./structured-output) | Reading NHTSA complaints, SEC officer filings and GSA listings into schema-valid JSON, with the two wrong fields left visible | `chat/completions` | SIE Cloud with Qwen3.8 27B; `fetch.py` pulls the recorded run, `score.py` reproduces the number with no key | Runnable recorded example |
| [Get the right values into a JSON Schema, against six hosted models](./structured-output-accuracy) | Comparing value accuracy under strict structured output on 500 Structured Output Benchmark records, scored by SOB's own scorer, and on 150 NHTSA complaints filed after every model's training data | `chat/completions` | SIE Cloud with Qwen3.8 27B, plus OpenAI and Anthropic keys for the other arms; `fetch.py` pulls the recorded run, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Route a request to the action it asks for](./classify) | Scoring held-out SNIPS requests against seven action labels, and showing what happens when the labels overlap | `extract` | SIE Cloud with GLiClass; `fetch.py` pulls the recorded run, `score.py` reproduces the number with no key | Runnable recorded example |
| [Answer several triage questions about one record, each with a probability](./typed-decisions) | Asking CVE descriptions typed pick-one and yes-or-no questions against NVD analyst gold, with a fast, a smart and an LLM lane, and the questions no model passed reported rather than shown | `extract`, `chat/completions` | Self-hosted SIE with GLiFormer, GLiClass, Laya, GLiNER2, GLiNER2.5-Decide and Qwen3 4B; `fetch.py` pulls the recorded run, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Screen harmful prompts before your model sees them](./guardrails) | Scoring SIE's Qwen3Guard 4B and GLiGuard against three LLM judges and OpenAI Moderation on 4,768 human-labelled ToxicChat and Aegis 2.0 prompts, with a paired bootstrap and the pre-registered bars | `chat/completions`, `extract` | SIE Cloud with GLiGuard, an SIE server for Qwen3Guard; `fetch.py` pulls the recorded run and both sets, `score.py` reproduces every figure with no key | Runnable recorded example |
| [Expand a query into matchable terms](./sparse) | Comparing SPLADE, which adds terms the text never used, with bge-m3 sparse, which does not | `encode` | SIE Cloud with SPLADE++ and bge-m3; `fetch.py` pulls the recorded vectors, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Mask personal data before it reaches a log, a prompt or a vendor](./redact) | Composing two PII models and scoring coverage recall on 660 documents against Presidio, OpenAI Privacy Filter and two LLM prompts, with the price of each | `extract` | SIE Cloud with GLiNER PII and NuNER Zero; `fetch.py` pulls the recorded run, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Read a full app screenshot into typed fields](./screenshot-fields) | Reproducing all 26 original field checks from one complete Kanboard task screenshot and a strict schema | `chat/completions` | SIE endpoint with Gemma 4 31B; pinned evidence and offline scoring need no API key | Runnable recorded example |
| [Read the numbers off a dashboard that has no API](./screenshot-mining) | Reading twelve Superset, Argo CD, Airflow, Kubernetes, GitLab and Jaeger screens into schema-valid JSON | `generate` | SIE Cloud with Qwen3.8 27B; `fetch.py` pulls the recorded run and the screenshots, `score.py` reproduces 328 of 335 with no key | Runnable recorded example |
| [Read a scanned form into typed fields, then check the answer](./doc-field-extraction) | Extracting typed fields from FAA, OSHA, NIST, USPS and invoice pages under a strict JSON schema, then measuring whether a second call that never sees the page is worth making | `generate`, `chat/completions` | SIE Cloud with Qwen3.8 27B; `fetch.py` pulls the recorded run and the page images, `score.py` reproduces 180 of 223 and 204 after the second call with no key | Runnable recorded example |
| [Ask a question about an image](./caption-vqa) | Putting one specific question to equipment photographs, hazmat placards, wiring drawings and analogue dials | `generate` | SIE Cloud with Qwen3.8 27B; `fetch.py` pulls the recorded run and the images, `score.py` reproduces 10 of 12 with no key | Runnable recorded example |
| [Locate every object a prompt can name in a photo](./detect) | Grounding open-vocabulary phrases to boxes on nine photos, with the two boxes it puts on the wrong object kept visible | `extract` | SIE Cloud with Grounding DINO; `fetch.py` pulls the recorded run, `score.py` reproduces the number with no key | Runnable recorded example |
| [Tag product photos with your own types, colours and materials](./image-classify) | Filling in three catalogue fields from one photo, against AWS Rekognition and four vision LLMs on 938 held-out product photos | `encode` | SIE Cloud with SigLIP so400m; `fetch.py` pulls the recorded run, `score.py` reproduces every figure with no key | Runnable recorded example |
| [Find a spoken part number in a noisy recording](./speech-to-text) | Transcribing twelve clips and searching them for the doses, figures and statute numbers that matter, the five misses kept | `extract` | SIE Cloud with Whisper large v3 turbo; `fetch.py` pulls the recorded run, `score.py` reproduces the word error rate with no key | Runnable recorded example |
| [Find the product photo a shopper describes](./image-search) | 309 shopper queries such as "grey leather sofa" over 2,573 Amazon Berkeley Objects product photos, with near misses on colour, material and type; SIE against Voyage, Cohere and GPT captions | `encode` | SigLIP so400m on the SIE server; `fetch.py` pulls the recorded run, `score.py` reproduces every figure with no key | Runnable recorded example |
| [Find the PDF page that answers a question, without parsing it to text first](./visual-document-search) | 1,816 ViDoRe v3 questions over 16,309 report, filing and slide pages: page images against Voyage, Cohere and parse-then-embed | `encode` | SIE `tomoro-colqwen3-embed-4b:compact`; `fetch.py` pulls the recorded run, `score.py` recomputes every score with no key | Runnable recorded example |
| [Search licensed images with text](./multimodal-search) | Recomputing a six-image hard-negative ranking from full SigLIP vectors | `encode` | SIE endpoint with SigLIP; standalone `uv` project | Runnable verified example |
| [Find SOTA embedding models by MTEB task](./sie-hugging-face-mteb-semantic-search) | Searching ~14K HF embedding models ranked by task-specific MTEB scores | `encode`, `score` | Backend seed script plus Vite frontend; falls back without a live SIE endpoint | Runnable |
| [Private fine-tuned compliance RAG](./regulatory-rag) | Hot-loading a domain LoRA encoder and a custom token-pruning adapter on SIE | `encode`, `score`, `extract` | Custom SIE Docker image, GPU recommended | Advanced runnable example |
| [Build a multimodal wine recommender with OCR](./wine-recommender) | Combining preference-based retrieval with OCR-driven label detection in one UI | `encode`, `score`, `extract` | Docker Compose app plus local SIE endpoint; API key optional for unauthenticated SIE | Runnable demo |
| [Build a multi-modal product classifier with embeddings](./taxonomy-classification) | Evaluating text, image, NLI, and reranking approaches for hierarchical product taxonomy classification | `encode`, `score`, `generate` | SIE endpoint, Shopify dataset prep via `uv run` scripts, standalone `uv` project | Runnable evaluation example |
| [Read a page image, then read the Markdown](./ocr-two-stage) | Measuring an OCR stage and a schema-filling stage separately, so a wrong field can be traced to the stage that lost it | `extract`, `chat/completions` | SIE Cloud with LightOnOCR-2-1B and two Qwen3 models; `fetch.py` pulls the recorded run, `score.py` reproduces the figures with no key | Runnable recorded example |
| [Swap an OCR model with one identifier change](./document-ocr) | Driving recognition (VLM-OCR), structured extraction (Donut), and zero-shot NER (GLiNER) through the same `extract` call by swapping the model ID | `extract` | Docker Compose plus Node UI, no API key required, hosted version on [Hugging Face Spaces](https://huggingface.co/spaces/superlinked/document-ocr) | Runnable demo |
| [A Stripe Link checkout with an SIE fraud-risk gate](./stripe-link-fraud) | Wiring all three SIE primitives into a pre-authorization fraud-risk gate that runs in the same round-trip as the Stripe PaymentIntent | `extract`, `encode`, `score` | Docker Compose plus Node UI; Stripe test-mode keys optional (runs in mock mode without them) | Runnable demo |
| [Vision-first document RAG](./vision-doc-rag) | Retrieving and answering questions over a multi-tenant page corpus by looking at page images (including scanned drawings) with OCR kept out of the score path | `encode`, `chat/completions`, `score` (optional) | GPU SIE deployment required: ColQwen2.5 retriever + Qwen3.5-4B answer model (runs on the generation bundle) | Runnable demo |
| [Multi-model contract review with the OpenAI Agents SDK](./contract-review-agent) | Running an OpenAI Agents SDK agent whose every model call (triage, orchestration, vision, OCR, embeddings, rerank, entity extraction, text-to-SQL, reasoning, and a safety guardrail) is served by one SIE cluster, each step on the right catalog model, with per-model observability | `generate`, `encode`, `score`, `extract` | GPU SIE deployment required; standalone `uv` project; real contracts fetched from CUAD (CC BY 4.0) | Runnable demo |
| [Turn difficult PDFs into Markdown](./document-to-markdown) | Preserving tables, reading order, headings, and form labels across real financial, academic, and government PDFs | `extract` | SIE endpoint with `docling`; `fetch.py` pulls the recorded run, `verify-run` checks 61 digests and relations offline; source PDFs fetched at run time | Runnable evaluation example |
| [Review a published flood-insurance appeal](./insurance-claims-agent) | Separating FEMA's covered stone-removal scope from excluded barge, handling, disposal, and yard costs | `extract`, `score`, `generate` | GPU SIE deployment; standalone `uv` project; bundled public FEMA appeal and policy | Runnable agent example |
| [Trace a restated filing figure](./financial-filing-agent) | Following one reported figure through an original filing, corrective notice, and restatement while preserving source status | `extract`, `encode`, `score` | SIE endpoint; standalone `uv` project; public SEC facts and saved verified evidence | Runnable agent example |
| [Reproduce CMS's L1851 documentation finding](./prior-authorization-review-agent) | Tracing a published six-month requirement against a seven-month face-to-face encounter and CMS's recoupment result | `extract`, `encode`, `score` | SIE endpoint; standalone `uv` project; exact CMS published example | Runnable agent example |
| [Reconstruct a bearing failure](./maintenance-triage-agent) | Turning the NTSB's three East Palestine detector readings into a cited temperature and alert sequence without adding a new causal claim | `extract`, `encode`, `score` | SIE endpoint; standalone `uv` project; exact NTSB illustrated report spread | Runnable agent example |
| [Make a shelf gap auditable](./retail-shelf-audit) | Detecting one empty facing, deriving its notice and shelf-label crops by geometry, then preserving OCR evidence | `extract` | GPU SIE deployment; standalone `uv` project; CC0 supermarket shelf image and recorded direct-checkpoint evidence included | Runnable evaluation example |
| [Turn threat reports into cited ATT&CK mapping suggestions](./threat-report-attck-mapper) | Mapping full reports against active ATT&CK 19.2, with a separate pinned AnnoCTR linking benchmark and analyst review for every suggestion | `generate`, `extract`, `encode`, `score` | GPU SIE deployment; standalone `uv` project; pinned MITRE ATT&CK and AnnoCTR sources | Runnable agent benchmark |
| [A behavioural gate that catches hijacked AI agents by their actions, not their credentials](./agent-action-monitor) | Judging a proposed AI agent action against that agent's own learned baseline in real time, before it reaches a downstream system | `encode`, `score`, `extract` | Docker Compose (gate + self-hosted SIE + n8n + mock downstream), no API key required | Runnable demo |
| [Find the best RAG config before you build](./rag-params-finder) | Sweeping embeddings × chunking × retrieval on your data before building a RAG app | `encode`, `score` (optional rerank) | External repo; MongoDB local or Atlas/Postgres; SIE gateway or Docker | External project guide |
| [Scan AI skills and MCP servers, then triage with SIE](./agentvetter) | Discovering and scanning AI skills/MCP servers, then optionally routing findings with Superlinked SIE | `generate` | External repo; Mock demo local; Live needs Supabase + Modal; routing needs `SIE_*` + Model Studio keys | External project guide |
| [Measure whether translation or paraphrase removes a text watermark](./watermark-robustness) | Watermarking text with a key you control, then measuring how much of the signal survives an Arabic round trip versus a paraphrase; all recorded runs readable offline | `generate`, `extract` | SIE endpoint for new transformations (hosted or local MADLAD path); standalone `uv` project; saved experiment data included | Runnable evaluation example |

For docs publishing, lead with the quickest runnable demos, then use the
benchmark and evaluation examples for deeper technical users.

## Submit your project

We welcome contributions. To add your project to the gallery:

1. **Create a subdirectory** with a short, descriptive name (e.g. `wikipedia-search/`, `pdf-rag/`)
2. **Include a README** that covers:
   - What the project does
   - How to run it (`docker compose up`, a script, etc.)
   - Which SIE features it uses (encode, score, extract, cluster, etc.)
3. **Keep it self-contained** - include a `requirements.txt` or `package.json`, a docker-compose if needed, and sample data or instructions to fetch it
4. **Open a PR** against `main`

### Recorded evidence

Examples that reproduce a number published on a task page keep their code here
and their evidence in the public HuggingFace dataset
[superlinked/sie-task-evidence](https://huggingface.co/datasets/superlinked/sie-task-evidence),
one folder per task holding task-specific evidence files and `manifest.json`. Each
example's `fetch.py` downloads that folder at a pinned dataset revision, never
`main`, so a later upload cannot change what the example scores.

The trade is deliberate: a reader cannot verify by cloning alone, and in return
nobody needs an API key or any inference spend to re-derive a published number.

### Review workflow

Maintainers apply the `coderabbit-direct` label to eligible PRs that change content under `examples/**` or the root `README.md`. The label opts the PR into CodeRabbit review and allows CodeRabbit to formally approve it once review comments are resolved and required checks pass.

Projects can be anything: a search engine, a RAG pipeline, a benchmark, a migration guide, a CLI tool. If it uses SIE, it belongs here.

## Links

- [SIE overview](../README.md)
- [API reference](https://superlinked.com/docs/reference/sdk)
- [Deployment guide](https://superlinked.com/docs/deployment/docker)
- [All models](https://superlinked.com/models)