[codex] Prepare Aleph v1.0.3 MLX CUDA runtime framing

[Jah-yee]

What changed

This branch prepares Aleph v1.0.3 as a small release/docs/UI framing update after upstream MLX added Linux CUDA backend support.

• bumped repo/package/web versions to 1.0.3, including lockfiles and /health
• added docs/releases/1.0.3.md and a changelog entry
• updated README, DEMO, state/research docs, and the archived hackathon plan so Aleph is described as MLX-backed rather than Apple-Silicon-only
• kept Apple Silicon as the current known maintainer path
• named Linux CUDA as an upstream MLX backend path for future local white-box expansion
• updated web UI copy from "Apple Silicon search server" to "MLX search service"
• adjusted search/preflight.py so Linux no longer fails solely for not being arm64; it now prints a Linux CUDA hardware note instead
• tightened explorer copy/i18n so hosted mode semantics and Chinese-visible status text stay aligned with the current UI language

Why

Upstream MLX added Linux CUDA backend support, but several Aleph docs and bits of UI copy still described the local white-box route as if MLX itself were Apple-Silicon-only. This patch makes the repository's runtime framing more accurate without changing Aleph's product claims, run contract, or evidence boundaries.

Impact

• no AlephRun contract changes
• no search algorithm changes
• no new dependencies or routes
• clearer and more accurate hardware/runtime language for contributors and users
• cleaner explorer wording in Chinese mode and better alignment between the hosted mode UI label and the request semantics

Validation

• npm run lint
• npm run test
• npm --workspace web run build
• git diff --check

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aleph	Ready	Preview, Comment	May 19, 2026 9:46pm
aleph-web	Ready	Preview, Comment	May 19, 2026 9:46pm

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Aleph v1.0.3 is a patch release that updates monorepo versions and clarifies local MLX platform support (Apple Silicon as maintainer path; Linux CUDA as upstream expansion), with runtime preflight adjustments, web explorer UI/localization changes, scoring exact-match short-circuits, related tests, and a metrics plan.

Changes

v1.0.3 Release Patch

Layer / File(s)	Summary
MLX/hardware framing documentation updates CHANGELOG.md, DEMO.md, README.md, docs/plans/hackathon-v0.md, docs/releases/1.0.3.md, docs/research/implementation-routes.md, docs/research/research-process.md, docs/state-of-play.md, search/requirements.txt	Changelog entry, release notes, demo, README, planning, and research docs updated to clarify that local MLX supports Apple Silicon as the known maintainer path and Linux CUDA as an upstream MLX expansion path; release notes file added.
Version bump across monorepo package.json, packages/core/package.json, packages/fixtures/package.json, packages/ui/package.json, web/package.json, web/app/health/route.ts	Root and workspace package versions bumped from 1.0.2 → 1.0.3; health endpoint response version updated.
Search preflight platform detection and requirements comments search/preflight.py, search/requirements.txt	Preflight now captures platform.system() and architecture, applies Apple Silicon gating only on macOS (Darwin), and emits a Linux hardware note; MLX dependency comments updated to include Linux CUDA backend support.
Web explorer UI localization, slider sampling, and request mode web/app/components/aleph-explorer.tsx	Slider sampling changed to snap to nearest point, mobile chrome fade delay added, English/Chinese live-search localization keys and MLX availability copy updated, footer slider label localized, and custom-search POST uses mode: 'hosted_black_box'.
Exact-match scoring and tests apps/api/aleph_api/services/scoring.py, apps/api/aleph_api/services/local_mlx_search.py, web/app/api/search/route.ts, apps/api/tests/test_scoring.py	similarity_score() returns 1.0 on exact non-empty matches after trimming; local MLX candidate fit uses measured similarity with exact-match override; new unit tests assert exact-match yields perfect score in scoring and adapter paths.
Metric and backend workflow plan docs/plans/metric-and-backend-workflow.md	New plan document added describing metric normalization, evidence labeling, backend JSON shaping, and an acceptance gate for exact-match parity across services.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• p-to-q/aleph#3: Related to changes in similarity_score() normalization and exact-match behavior in the same scoring module.
• p-to-q/aleph#6: Introduced the local_mlx_search adapter that this PR further adjusts for candidate fit computation.
• p-to-q/aleph#18: Overlaps on web/app/components/aleph-explorer.tsx UI/localization changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main purpose of the PR: preparing a release (v1.0.3) with a focus on MLX CUDA runtime framing documentation and infrastructure updates.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, covering what changed, why, and the impact of the updates across documentation, UI copy, and version bumps.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@web/app/components/aleph-explorer.tsx`:
- Around line 910-912: The Chinese out-of-band note string (rightOobNote) still
contains the English phrase "y itself"; update this to a Chinese equivalent that
matches the localization style and aligns with the existing sliderTargetSuffix
usage (e.g., replace "y itself" with the same Chinese wording used by
sliderTargetSuffix), ensuring rightOobTitle/rightOobNote remain consistent in
meaning and formatting within the aleph-explorer.tsx component.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e07369f3-3473-45e0-8fec-93ea1fe8f685

📥 Commits

Reviewing files that changed from the base of the PR and between f846549 and c05fd75.

📒 Files selected for processing (1)

• web/app/components/aleph-explorer.tsx

📜 Review details

🔇 Additional comments (1)

web/app/components/aleph-explorer.tsx (1)

35-35: LGTM!

Also applies to: 751-755, 771-772, 777-777, 783-784, 787-787, 811-816, 868-878, 894-900, 906-907, 915-915, 1772-1772, 2282-2282, 2342-2345, 2925-2925

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/api/aleph_api/services/scoring.py`:
- Around line 23-27: The current logic treats two empty normalized strings as
identical because difflib.SequenceMatcher("", "") returns 1.0; update the
function that computes similarity (the block using variables target and actual
and difflib.SequenceMatcher) to explicitly handle empty normalized inputs by
returning 0.0 when both target.strip() and output.strip() are empty, otherwise
proceed with the existing equality check (target == actual) and then fall back
to difflib.SequenceMatcher(a=target, b=actual).ratio().

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b272f72e-f9cf-4be9-87c9-3522ff2bb020

📥 Commits

Reviewing files that changed from the base of the PR and between c05fd75 and 04ac144.

📒 Files selected for processing (4)

• apps/api/aleph_api/services/scoring.py
• apps/api/tests/test_scoring.py
• docs/plans/metric-and-backend-workflow.md
• web/app/components/aleph-explorer.tsx

📜 Review details

🔇 Additional comments (12)

web/app/components/aleph-explorer.tsx (10)

35-35: LGTM!

---

347-363: LGTM!

---

635-635: LGTM!

Also applies to: 1661-1661, 1885-1885

---

748-752: LGTM!

Also applies to: 768-768, 774-774

---

808-808: LGTM!

Also applies to: 811-813, 865-865, 871-875, 891-891, 897-897, 903-904, 907-909, 912-912

---

1770-1770: LGTM!

---

2280-2280: LGTM!

---

2340-2343: LGTM!

---

2923-2923: LGTM!

---

2962-2963: LGTM!

apps/api/tests/test_scoring.py (1)

89-92: LGTM!

docs/plans/metric-and-backend-workflow.md (1)

1-73: LGTM!