Architecture · LikeC4
NLS Fine-tune (SciX)
Translates natural language to ADS search queries (hybrid pipeline + fine-tuned model) and the data/training/eval machinery behind it
The whole picture
System landscape
The system in context, then opened up into its containers.
NLS Fine-tune (SciX) — system landscape
index
NLS Fine-tune — containers (built vs planned)
nlsSystemTranslates natural language to ADS search queries (hybrid pipeline + fine-tuned model) and the data/training/eval machinery behind it
Risks & open questions
risks
Planned & research work
plannedInside each box
Containers & components
Each part decomposed into the components that implement it. Every box links to its source in the interactive explorer.
NLS inference server — routing & runtime
serverContainerdocker/server.py — OpenAI-compatible /v1/chat/completions consumed by nectar; routes pipeline-first, model-fallback
Hybrid NER pipeline — components
pipelineContainerdomains/scix — deterministic NER → few-shot retrieval → template assembly → constraint; guaranteed-valid ADS syntax in ~5ms
Dataset generation agent — 10-stage pipeline
dataPrepContainerdataset_agent — a resumable 10-stage pipeline that turns vocabulary sources + templates into validated NL→query training pairs
Evaluation harness — benchmark & semantic-overlap
evalContainerTwo harnesses: benchmark (exact-match / field / operator / syntax) and semantic-overlap (ADS result-set Jaccard / P@N / R@N)
Review API — services & routers
apiContainerFastAPI backend for the playground / dataset browser / evaluation viewer. RISK: prompts and labels still say "Sourcegraph" in places — leftover from the pre-ADS origin and not fully re-skinned for ADS
How it runs
Walkthrough flows
Dynamic views — the narrative spine of the system, step by step.
Walkthrough — translate a query at runtime
translateFlowNectar calls the OpenAI-compatible endpoint. The pipeline runs first (~5ms, guaranteed-valid syntax); the model is reached only when pipeline confidence falls below PIPELINE_CONFIDENCE_THRESHOLD. Routing is logged for the flywheel.
Walkthrough — build the training dataset
buildDatasetThree sources merge into the training set: synthetic pairs from vocabulary catalogs, real query-log pairs with Claude-generated NL, and the hand-curated gold seed. Every candidate passes local-syntax and ADS-API validation before the 90/10 split.
Walkthrough — fine-tune & publish the model
trainFlowTraining runs off-machine on Colab. The train split is uploaded, a LoRA adapter is fit on Qwen3-1.7B (~90 min on A100), and the adapter is pushed to HuggingFace where the inference server loads it on first start.
Walkthrough — evaluate translation quality
evalFlowTwo lenses. Benchmark scores exact-match / field / operator / syntax offline. Semantic-overlap runs each query against the live ADS API and compares result-set bibcodes (Jaccard / P@N / R@N) — the PRD target metric. Curators read the runs in the UI.
Where it runs
Deployment
What runs where, and the process & data boundaries between the pieces.
Deployment — where each piece runs
deploymentExplore it live
The figures above are static exports. The interactive explorer lets you pan, zoom, follow relationships, and jump from any box to the source.