Skip to content

Architecture Decision Records

ADRs capture significant, hard-to-reverse decisions for Tachyone. Once Accepted, an ADR is not edited in place to change its decision — supersede it with a new ADR instead.

Index

ADR Title Status Date
ADR-0001 Use the Jev /v1/systemone protocol as a drop-in contract Accepted 2026-09-24
ADR-0002 Pluggable backend with phased LLM → encoder strategy Accepted 2026-09-24
ADR-0003 Python 3.12 + uv for environment and packaging Accepted 2026-09-24
ADR-0004 Local-first, offline-capable core Accepted 2026-09-24
ADR-0005 Encoder backend trained with RLCD proper-scoring calibration Accepted 2026-09-24
ADR-0006 Apache-2.0 license and opt-out telemetry Accepted 2026-09-24
ADR-0007 Multilingual from Phase 3 via mmBERT-base Accepted 2026-09-24
ADR-0008 LLM backend: OpenAI-compatible surface with injectable transport Accepted 2026-09-24
ADR-0009 Extension endpoints mirror the canonical wire response Accepted 2026-09-24
ADR-0010 Weights fetched from the Hugging Face Hub on demand and cached locally Accepted 2026-09-24
ADR-0011 No telemetry; opt-out variables reserved Accepted 2026-09-24
ADR-0012 Ship the ONNX backend before the TileLang fast path Accepted 2026-09-24
ADR-0013 Rename the project from jeba to Tachyone Accepted 2026-09-26

Implementation notes (post-acceptance)

Accepted ADRs are not edited in place. Where the implementation and the original wording have drifted, the divergence is recorded here.

Naming: the project was renamed jeba → Tachyone (see ADR-0013). ADR-0001..ADR-0012 and the released sections of CHANGELOG.md keep the original name — they record what was decided and shipped at the time. Everywhere else, jeba/JEBA_* means tachyone/TACHYONE_*.

  • ADR-0004 — default backend. The decision says the project would "default to the local encoder backend once available (M3)". That switch was never made: src/tachyone/config.py still ships DEFAULT_BACKEND = "llm", so the default path calls an OpenAI-compatible provider and needs TACHYONE_LLM_* credentials. For a local, key-free run use --backend encoder (or TACHYONE_BACKEND=encoder) or the model-free --backend fake. Flipping the default is an open behaviour change, not a documentation fix — raise it before doing it.
  • ADR-0010 — prefetch. The decision names a jeba download subcommand (the CLI's name at the time). It was never implemented: tachyone is a single flag-based command (src/tachyone/cli.py) with no subcommands. The working equivalents today are hf download <repo> --local-dir <TACHYONE_MODELS_DIR> or one warm-up prediction (uv run tachyone --predict --backend encoder "<any text>"), after which TACHYONE_OFFLINE=1 serves from cache.
  • ADR-0002 — OD-1. The "still open (OD-1)" note predates ADR-0008, which resolved it.
  • ADR-0010 — HF_HUB_OFFLINE. The ADR describes offline mode as "honoring HF_HUB_OFFLINE". Tachyone itself never reads or sets it — grep -r HF_HUB_OFFLINE src/ is empty. What TACHYONE_OFFLINE=1 actually does is pass local_files_only=True to every huggingface_hub call. Exporting HF_HUB_OFFLINE=1 still works, because the library reads that variable on its own (huggingface_hub/constants.py), but it is not a tachyone-controlled switch. For a documented, tachyone-level guarantee use TACHYONE_OFFLINE=1; see docs/huggingface.md for the prefetch step offline installs need first.

Template

# ADR-NNNN: Title

**Status:** Proposed | Accepted | Superseded by ADR-XXXX | Deprecated
**Date:** YYYY-MM-DD

## Context

What is the issue we are facing? What forces are at play?

## Decision

What we decided, stated as a fact.

## Consequences

**Positive:** ...
**Negative:** ...
**Neutral / follow-ups:** ...

## Alternatives Considered

- **Option A** — why rejected.
- **Option B** — why rejected.

## Related

- Links to requirements, docs, or other ADRs.