revit-api-docs 0.1.0__tar.gz → 0.3.0__tar.gz

revit_api_docs-0.3.0/CHANGELOG.md

@@ -0,0 +1,263 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-10-26
+
+Vector hits now come back as the entries they describe and count also
+without a reranker; reranking picks its provider from the keys that are set.
+The data set `v1.1-data` adds constructor and interface member pages, and its
+vector store lines up with the SQLite rows.
+
+**Upgrading from 0.2.0** (`uvx --refresh revit-api-docs`): on the first start the server replaces an installed
+`v1.0-data` (its `manifest.json` names the old release) with `v1.1-data`, a
+download of 267 MB (all four files); a data directory without a
+manifest (a hand-copied tree) is used as it is. With an embedding key and a
+tree that still holds `v1.0-data`, the first vector query logs the warning
+`vector_store_misaligned`: its record ids do not line up with the SQLite rows,
+and hits are matched by entry name. Without any key nothing changes beyond the
+new entries. Reranker choice: with only `COHERE_API_KEY` set Cohere still
+reranks; with `TYPESAFE_API_KEY` set Jev now reranks without
+`REVIT_API_DOCS_RERANK_PROVIDER=jev` (set the provider to `cohere` to keep
+Cohere).
+
+### Added
+
+- Data set `v1.1-data` (`RELEASE_TAG`; the download URL and SHA-256 list in
+  `data.py` follow it): the 27,596 entries of `v1.0-data` are kept unchanged
+  under the same ids, and 1,266 pages of the same reference are appended
+  (ids 27,597-28,862): 1,040 constructor pages (`XYZ(Double, Double, Double)
+  Constructor`, `Transaction(Document, String) Constructor`, overload lists)
+  and 226 members whose C# signature has no `public`, mostly interface
+  members (`IExternalEventHandler.Execute`, `IConnector.Origin`,
+  `IFailuresPreprocessor.PreprocessFailures`) and explicit interface
+  implementations. 28,862 entries in all. Source: `RevitAPI.chm` of the
+  Revit 2026.3 SDK, whose pages are the same set as the Revit 2026 reference
+  the first release was built from. The API vector store is rebuilt from the
+  new SQLite with the same model (`text-embedding-3-large`, 3072 dimensions):
+  one record per row and every record id is its row id, so the first vector
+  query no longer logs `vector_store_misaligned` (`download` reports
+  `aligned`). The SDK files (`revit_sdk.db`, `chromadb_code.tar.gz`) are the
+  `v1.0-data` ones.
+- The vector documents are now `name : summary` (`v1.0-data` embedded mostly
+  the entry name alone: 21,952 of its 28,863 records); on the 223 test
+  queries this raised fused nDCG@5 without a reranker from 0.610 to 0.647
+  (task requests 0.438 to 0.459) and left it with Jev at 0.842 against 0.846
+  (task requests 0.778 against 0.794).
+- `pipeline/build_data_v1_1.py` (sdist only): builds `v1.1-data` from the
+  `v1.0-data` SQLite and the CHM pages: appends the pages the base lacks
+  (pages whose name is in the base under another `full_id`, or whose content
+  is a base row's under a name the v1.0 rewrite changed, are listed and not
+  appended), runs the quality agent on the new rows only, re-embeds every
+  row, packages the four release files with `SHA256SUMS.txt` and checks the
+  vector store against the rows without an API call.
+
+### Fixed
+
+- Vector search returned unrelated entries. The vector store of the
+  `v1.0-data` release numbers its 28,863 API records independently of the
+  27,596 rows of `revit_api.db` (2 ids name the same entry in both), and hits
+  were looked up by record id. A hit is now matched to the row whose entry
+  name equals the record's `name` metadata (the row with the record's own id
+  when it carries that name; among rows sharing a name the one with the
+  record's `full_id` or `info`, else the lowest id). 27,591 records (95.6%)
+  reach 27,512 rows (99.7%); records without a row are dropped. The SDK sample
+  store's ids match its rows, and matching by project name keeps them. The
+  name map is built on the first vector query and kept in memory.
+- Consistency probe: on the first vector query 50 records of each vector
+  collection are compared with SQLite. When fewer than 90% of the sampled ids
+  name the same entry as the row with that id, the warning
+  `vector_store_misaligned` is logged and hits are matched by name (`v1.0-data`:
+  0/50 ids, 49/50 names). When fewer than 50% of the sampled names are found
+  either, vector search is off for the process and keyword search answers
+  alone. `revit-api-docs download` prints the check for the installed data set.
+- A second retriever in the same process could not open the vector store
+  ("An instance of Chroma already exists ... with different settings"): each
+  ChromaDB client now gets its own `Settings` object.
+
+### Changed
+
+- Hybrid ranking by reciprocal rank fusion: the vector hits and the BM25 hits,
+  `retrieval.api.top_k` (30) of each, are fused with score = sum of
+  1 / (60 + rank), and the best 30 go to the reranker; without a reranker they
+  are cut to `top_k`. On equal scores a keyword hit comes first. Before, the
+  two lists were merged by distances on different scales, so without a
+  reranker vector-only hits never reached the top 5, and up to 60 candidates
+  went to the reranker. Without an embedding key the BM25 order and results
+  are unchanged. On 223 English test queries without reranking (measured on
+  `v1.1-data`): nDCG@5 0.557 with BM25 alone, 0.647 fused, and 0.355 -> 0.459
+  on the 113 multi-step task requests, whose answer is among the top 30 for
+  82% instead of 72% of them.
+- The default rerank provider is `auto`: Jev when `TYPESAFE_API_KEY` is set,
+  otherwise Cohere when `COHERE_API_KEY` is set, otherwise none.
+  `REVIT_API_DOCS_RERANK_PROVIDER` (now `auto`, `jev`, `cohere` or `none`)
+  still wins, and the `Rerank:` line names the provider that ran. README:
+  Jev is the recommended reranker, Cohere optional and the fallback for Jev.
+- Cohere requests time out after 20 s instead of 10 s (the same as Jev); 10 s
+  cut off about 1% of calls.
+- `search_revit_api` and `get_code_examples` are unchanged: names,
+  parameters and the first output line. The tool description now counts
+  28,862 entries.
+- CHM parser (`pipeline/api_parser/parse_chm.py`): `parse_single_html` and
+  `parse_all_api_html` take `keep_constructors` (default `False`, the old
+  behaviour); the C# signature no longer has to contain `public` (interface
+  members such as `void Execute(UIApplication app)` were skipped as a whole
+  page); a page with neither a signature nor a members table is still
+  skipped.
+- `pipeline.embedder.embed.embed_api_data(..., resume=False,
+  document_template="NS")`: with `resume=True` the collection is kept and
+  only missing row ids are embedded; `document_template` picks the embedded
+  text per API row (`NS` `name : summary`, the default and the `v1.1-data`
+  store; `FS` `full_id : summary`, the earlier behaviour; `N` the entry name)
+  and is recorded in `meta.json`. `pipeline/build_data_v1_1.py
+  --document-template` passes it on (default `NS`).
+
+## [0.2.0] - 2026-10-26
+
+Better candidates without any key, and an opt-in relevance check: BM25 keyword
+search over an SQLite FTS5 index, optional Jev reranking with a calibrated
+relevance per entry and abstention, a streamable HTTP transport, and curated
+development-environment notes.
+
+**Upgrading from 0.1.0** (`uvx --refresh revit-api-docs`): the first search
+builds `sqlite/revit_api_fts.db` (an FTS5 index, 11.8 MB) next to the data set
+in under a second. `search_revit_api` output starts with `Rerank: <reranker>;
+data set: Revit 2026`. Abstention is new and opt-in:
+`REVIT_API_DOCS_MIN_RELEVANCE` (Jev only) only decides whether to abstain and
+drops no entry; the abstention line does not claim that the member is missing.
+
+### Added
+
+- Jev rerank provider (TypeSafe System One, `POST https://api.typesafe.ai/v1/systemone`,
+  one `noul` question per candidate): `REVIT_API_DOCS_RERANK_PROVIDER=jev` with
+  `TYPESAFE_API_KEY`. Up to 30 candidates per request, 2 requests in flight,
+  2 retries with backoff on 429/529/5xx/timeouts, 20 s timeout. A failed or
+  unconfigured Jev call falls back to Cohere (when `COHERE_API_KEY` is set) or
+  to no reranking.
+- `search_revit_api` output starts with the reranker that ran
+  (`Rerank: jev | cohere | none`, plus `(unavailable: jev)` after a fallback);
+  Jev-ranked entries carry `Relevance: 0.00-1.00`.
+- Abstention: with Jev and `REVIT_API_DOCS_MIN_RELEVANCE`, when no entry
+  reaches the threshold the output starts with "No entry in the Revit 2026
+  data set scored high enough for this query (best relevance x < y)" followed
+  by the low-scoring candidates. Other providers never abstain.
+- Streamable HTTP transport: `revit-api-docs serve --transport http --host
+  127.0.0.1 --port 8765` (endpoint `/mcp`); stdio remains the default. A
+  non-loopback `--host` logs a warning: there is no built-in authentication.
+- Development-environment notes: a curated English corpus shipped with the
+  package (`environment.yaml`: target framework, SDK, manifest, reference
+  packages for Revit 2024-2027, each with a release range and a source URL),
+  matched by keywords. `search_revit_api` appends up to five matching notes,
+  also while the data set is still downloading and without any key;
+  `revit-api-docs environment [query] [--revit 2027]` prints them. The
+  `jev-data-handling` note points at TypeSafe's data processing terms.
+- Retrieval regression fixture `tests/fixtures/retrieval_queries.yaml`: 60
+  English queries with verified gold rows in the v1.0-data reference (50
+  answerable, 10 not). `tests/test_bm25_recall.py` runs them against the
+  shipped data set when it is installed: gold in the BM25 top 30 for at least
+  44 of 50 (measured 45), hit@5 at least 36 of 50 (measured 38), and a
+  non-empty candidate list for every unanswerable query. No network.
+- A second regression fixture, `tests/fixtures/retrieval_queries_v2.yaml`: 60
+  more English queries (40 answerable, 20 not, 9 of those next to a real API,
+  such as a class name used as a member or a misspelling), none shared with
+  the first set. `tests/test_bm25_recall.py` runs both sets;
+  for this one: gold in the BM25 top 30 for at least 33 of 40 (measured 34),
+  hit@5 at least 25 of 40 (measured 27), and candidates for at least 19 of the
+  20 unanswerable queries (measured 19).
+- `close()` on the rerank providers releases their HTTP client.
+- README: when to turn on Jev (`REVIT_API_DOCS_RERANK_PROVIDER=jev` with a
+  TypeSafe key; nDCG@5 0.675 -> 0.871 on the test queries, about $0.23 per
+  1,000 queries), what a `REVIT_API_DOCS_MIN_RELEVANCE` of 0.15 filters and
+  what it does not, and why not 0.5. Defaults are unchanged.
+
+### Changed
+
+- The `Rerank:` line also names the data set the entries come from: `Rerank:
+  <provider>[ (unavailable: ...)]; data set: Revit <version>`, the version
+  taken from the configuration (`revit_version`, 2026 for the v1.0-data
+  release). It stays the first line, or the second after an abstention line,
+  so an answer can cite the data set version next to a result; the tool
+  description and the server instructions say so. The `Rerank:` prefix is
+  unchanged.
+- `REVIT_API_DOCS_MIN_RELEVANCE` only decides whether to abstain. When at
+  least one entry reaches it, the entries below it are no longer dropped:
+  every reranked entry comes back (up to `top_k`) with its `Relevance`, so a
+  correct entry scored just under the threshold stays in the list. Abstention
+  itself, and the output format, are unchanged.
+- README and the `jev-rerank-provider` environment note describe the
+  threshold as a relevance filter: at 0.15 it filters out clearly unrelated
+  queries (not about Revit, types the data set does not have) and abstains
+  on about 2.5% of the queries that have an answer, but it cannot spot a
+  misspelt or misplaced member name, for which the closest real API usually
+  comes first and a compile check decides. "No entry scored high enough" is
+  described as "nothing relevant, or worded differently", not as "the member
+  does not exist"; the README no longer says the value is being validated.
+- The rerank HTTP clients (Jev and Cohere) keep idle connections open for 5
+  minutes (`keepalive_expiry=300`; httpx closes them after 5 s), so a query
+  after a pause can reuse the connection instead of setting up TLS again.
+  The other connection limits stay at httpx's defaults.
+- Keyword search over the API reference ranks with BM25 on an SQLite FTS5
+  index instead of LIKE substring scoring. The index is a separate file,
+  `sqlite/revit_api_fts.db` next to `revit_api.db` (which is never written),
+  built on first use in under a second and rebuilt when the source database's
+  SHA-256 or the index format changes; the installer neither downloads nor
+  flags it. Identifiers also match by their camel-case parts, so misspelt or
+  unknown names (`FiltredElementColector`) get candidates instead of "No API
+  entries found". Without vector search the keyword search now hands the
+  reranker `retrieval.api.top_k` (30) candidates instead of the requested
+  count; with vector search it adds the requested count, as before. A Python
+  whose sqlite3 lacks FTS5 keeps the LIKE scorer and logs one warning.
+- The Jev and Cohere rerank providers keep one HTTP client per instance, and
+  with it the open connection, instead of building one per call. Against the
+  hosted Jev API a Jev-reranked `search_revit_api` call took about 2.1 s
+  before (10 candidates); now the first call of a process takes about 2.3 s
+  and later ones about 0.4 s (30 candidates).
+- The abstention line no longer claims the class or member may not exist: it
+  says that no entry scored high enough and that either the member is absent
+  from this version or the data set has it under a different name or wording.
+  The tool description and server instructions say the same. A low best score
+  cannot tell a missing member from one the candidate search did not bring up.
+- The embedding providers look up their API key before importing the SDK, so
+  keyword-only runs (no key) no longer import `openai`; `search` starts about
+  2 s faster.
+- `search` and `download` log plain `logger: message` lines to stderr at
+  WARNING (`-v` for INFO), with `httpx` request lines hidden; the MCP server's
+  logging is unchanged. The index/content mismatch of the shipped data set is
+  logged at INFO instead of WARNING.
+- Download progress: on a terminal the line is redrawn in place; in host logs
+  and pipes one line per 10% instead of one per second.
+- Tool descriptions and the server instructions state that queries are English
+  only.
+- The Cohere reranker shares a provider interface with Jev; its requests and
+  its fall-back-to-input-order behaviour are unchanged.
+
+## [0.1.0] - 2026-09-20
+
+First release, split out of the `revit-api-rag` repository (working-tree copy,
+no git history).
+
+### Added
+
+- MCP server `revit-api-docs` (stdio) with two read-only tools:
+  `search_revit_api(query, top_k)` and `get_code_examples(query, top_k)`.
+- Data set as GitHub Release `v1.0-data` (Revit 2026 API reference SQLite,
+  SDK samples SQLite, two ChromaDB indexes); downloaded on first run into the
+  per-user data directory, SHA-256 verified, resumable. `REVIT_API_DOCS_DATA_DIR`
+  overrides the location; `revit-api-docs download` prefetches.
+- Keyword search over SQLite works with no API key; an OpenAI-compatible
+  embedding key adds vector search, `COHERE_API_KEY` adds reranking. Embedding
+  or rerank failures fall back to keyword search instead of erroring.
+- CLI: `serve` (default), `download`, `search <query> [--examples] [--top-k]`.
+- Offline data pipeline (`pipeline/`, `uv sync --extra pipeline`) from the old
+  repository, importing the package's shared retriever, LLM client and prompts.
+- CI (tests + build on Linux/Windows, Python 3.11/3.13) and PyPI Trusted
+  Publishing on version tags.
+
+[Unreleased]: https://github.com/revitbridge/revit-api-docs/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/revitbridge/revit-api-docs/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/revitbridge/revit-api-docs/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/revitbridge/revit-api-docs/releases/tag/v0.1.0

revit_api_docs-0.3.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: revit-api-docs
+Version: 0.3.0
+Summary: Revit API reference search for MCP hosts: local semantic + keyword lookup over the Revit 2026 API docs and SDK samples
+Project-URL: Homepage, https://github.com/revitbridge/revit-api-docs
+Project-URL: Issues, https://github.com/revitbridge/revit-api-docs/issues
+Project-URL: Changelog, https://github.com/revitbridge/revit-api-docs/blob/main/CHANGELOG.md
+Project-URL: Data, https://github.com/revitbridge/revit-api-docs/releases/tag/v1.1-data
+Author: revitbridge
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-docs,bim,mcp,rag,revit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: chromadb<2,>=1
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2
+Requires-Dist: openai<3,>=1
+Requires-Dist: pyyaml>=6
+Provides-Extra: pipeline
+Requires-Dist: beautifulsoup4>=4.12; extra == 'pipeline'
+Requires-Dist: google-genai>=1; extra == 'pipeline'
+Requires-Dist: tqdm>=4.66; extra == 'pipeline'
+Requires-Dist: tree-sitter-c-sharp>=0.20; extra == 'pipeline'
+Requires-Dist: tree-sitter>=0.20; extra == 'pipeline'
+Description-Content-Type: text/markdown
+
+# revit-api-docs
+
+Revit API reference search as an MCP server: two read-only tools over a local
+copy of the Revit 2026 API documentation (28,862 classes, constructors,
+methods, properties and enums) and the official SDK samples (153 projects).
+
+**Optional.** It exists for models that do not know the Revit API well. If
+your model already writes correct Revit code, you do not need it;
+[revit-bridge](https://github.com/revitbridge/revit-bridge) works without it.
+It never talks to Revit and it never calls a model itself.
+
+Queries are **English only**: the corpus is the English API reference. A host
+model that talks to its user in another language rewrites the request into
+English API names or English task keywords before calling a tool.
+
+## Install
+
+Prerequisites: Python 3.11+ with [`uv`](https://docs.astral.sh/uv/) (for
+`uvx`), about 700 MB of disk for the data set, network for the first run.
+
+**Claude Desktop** — `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "revit-api-docs": {
+      "command": "uvx",
+      "args": ["revit-api-docs"]
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```bash
+claude mcp add revit-api-docs -- uvx revit-api-docs
+```
+
+**Any MCP client** — run `uvx revit-api-docs` as a stdio server.
+
+**Any MCP client over HTTP** — run the server with the MCP streamable HTTP
+transport and point the client at `/mcp`:
+
+```bash
+uvx revit-api-docs serve --transport http --host 127.0.0.1 --port 8765
+```
+
+```json
+{
+  "mcpServers": {
+    "revit-api-docs": {
+      "type": "http",
+      "url": "http://127.0.0.1:8765/mcp"
+    }
+  }
+}
+```
+
+(Claude Code: `claude mcp add --transport http revit-api-docs http://127.0.0.1:8765/mcp`.)
+stdio stays the default. The HTTP transport has no built-in authentication:
+keep it on a loopback address, or put it behind a reverse proxy that
+authenticates; the server logs a warning when `--host` is not a loopback
+address.
+
+On the first start the server downloads the data set (267 MB, four files) from
+this repository's [`v1.1-data` release](https://github.com/revitbridge/revit-api-docs/releases/tag/v1.1-data)
+into `%LOCALAPPDATA%\revit-api-docs` (Windows) or `~/.local/share/revit-api-docs`
+(Linux; `~/Library/Application Support/revit-api-docs` on macOS), verifies each
+file's SHA-256 and unpacks the vector stores. Tool calls made while that runs
+return a short progress message instead of results. To do it ahead of time:
+
+```bash
+uvx revit-api-docs download
+```
+
+From a checkout: `uv sync` then `uv run revit-api-docs`.
+
+## Use
+
+Two tools, both read-only:
+
+- `search_revit_api(query, top_k=10)` — API entries with signature, parameters
+  and remarks. Query with an API name (`Wall.Create`,
+  `FilteredElementCollector OfCategory`) or a short task (`create floor from
+  boundary`). The first line names the reranker that ordered the entries
+  (`jev`, `cohere` or `none`) and the data set they come from, for example
+  `Rerank: none; data set: Revit 2026`; after an abstention line it is the
+  second line. Development-environment questions (`target framework for
+  Revit 2027 add-in`) also get up to five curated environment notes
+  (framework, SDK, manifest, reference packages per Revit release, each with
+  its source); these ship with the package and work before the data set is
+  installed and without any key.
+- `get_code_examples(query, top_k=3)` — C# from the SDK samples that use the
+  matching APIs, with the project name and the APIs each sample touches.
+
+Without any API key the server answers from keyword search over the SQLite
+reference: BM25 over a full-text index of entry names, IDs, summaries and
+signatures, where identifiers also match by their camel-case parts, so a
+misspelt or unknown name still gets candidates. The index (11.8 MB) is built
+next to the data set on first use (under a second). With an embedding key it
+adds semantic search over the vector store and fuses the two rankings by rank,
+which helps most with task descriptions that do not name the API. With a
+TypeSafe key it reranks the candidates with Jev, which returns a calibrated
+relevance per entry; with only a Cohere key it reranks with Cohere. With a Jev
+threshold set and no entry reaching it, the output starts with an abstention
+line and then lists the candidates with their relevance, for reference. See
+Configure.
+
+Try it from a terminal (installs the data set if needed):
+
+```bash
+uvx revit-api-docs search "Wall.Create"
+uvx revit-api-docs search "rotate element around axis" --examples
+uvx revit-api-docs environment --revit 2027          # environment notes, no data set needed
+uvx revit-api-docs environment "target framework"   # notes a query matches
+```
+
+## Configure
+
+All settings are environment variables; there is no config file to edit.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `REVIT_API_DOCS_DATA_DIR` | `%LOCALAPPDATA%\revit-api-docs` (Windows), `~/.local/share/revit-api-docs` (Linux), `~/Library/Application Support/revit-api-docs` (macOS) | Where the data set lives. An existing tree with `sqlite/` and `chromadb/` from the old `revit-api-rag` checkout works as is |
+| `REVIT_API_DOCS_EMBEDDING_API_KEY` | *(unset)* | Key for the embedding endpoint; turns on semantic (vector) search. `OPENROUTER_API_KEY` is used when this is unset |
+| `REVIT_API_DOCS_EMBEDDING_BASE_URL` | `https://openrouter.ai/api/v1` | Any OpenAI-compatible `/embeddings` endpoint |
+| `REVIT_API_DOCS_EMBEDDING_MODEL` | `openai/text-embedding-3-large` | Must produce the same 3072-dimensional space the shipped vectors were built with (`text-embedding-3-large`); another model makes vector search return noise |
+| `TYPESAFE_API_KEY` | *(unset)* | Key for TypeSafe System One (Jev), the recommended reranker: with the default provider `auto` setting this key is enough. At most 30 candidates per request, 2 requests in flight, 2 retries, 20 s timeout |
+| `COHERE_API_KEY` | *(unset)* | Optional. Cohere `rerank-v3.5` (native REST API, 20 s timeout): reranks when it is the only rerank key set, and is the fallback for a failed Jev call when both are set |
+| `REVIT_API_DOCS_RERANK_PROVIDER` | `auto` | `auto`, `jev`, `cohere` or `none`. `auto` reranks with Jev when `TYPESAFE_API_KEY` is set, otherwise with Cohere when `COHERE_API_KEY` is set, otherwise not at all; an explicit value wins. With Jev, a failed or unconfigured call falls back to Cohere when `COHERE_API_KEY` is set, otherwise to no reranking; the first output line says which one ran |
+| `REVIT_API_DOCS_JEV_MODEL` | `jev-latest` | Jev model or alias; pin a version such as `jev-1.14.0` for reproducible results |
+| `REVIT_API_DOCS_MIN_RELEVANCE` | *(unset)* | Probability 0-1 (`retrieval.api.min_relevance`). Only honoured while Jev ranks the results, and it only decides whether to abstain: no entry is dropped, every result keeps its `Relevance` line. When no entry reaches it, `search_revit_api` starts with "No entry in the Revit 2026 data set scored high enough for this query", notes that the member may be absent from this version or listed under a different name or wording, and lists the low-scoring candidates for reference. No effect with Cohere or without reranking. See "Reranking with Jev" below |
+| `REVIT_API_DOCS_RELEASE_URL` | this repository's `v1.1-data` release | Mirror for the data files; the SHA-256 checks still apply |
+| `HTTPS_PROXY` / `HTTP_PROXY` | *(unset)* | Proxy for the embedding and rerank calls |
+
+Pass them through the `env` block of your MCP host's server entry.
+
+Recommended setup: a `TYPESAFE_API_KEY` (Jev reranking), plus an embedding key
+when requests describe multi-step tasks rather than name APIs. Without any key
+the server runs on BM25 keyword search alone.
+
+**Reranking with Jev.** Jev is the recommended reranker, and the default
+provider (`auto`) uses it whenever `TYPESAFE_API_KEY` is set. Cohere is
+optional: `auto` uses it when only `COHERE_API_KEY` is set, and with both keys
+it is the fallback for a failed Jev call. Measured on `v1.0-data`: on 60
+English test queries (50 with a known answer) over the keyword (BM25)
+candidates, with no embedding key, Jev raised nDCG@5 from 0.675 to 0.871 and
+never turned a correct top-5 answer into a miss. On 223 further queries over
+the same candidates Jev reached an nDCG@5 of 0.788 against Cohere's 0.674. Input tokens cost about $0.23 per 1,000
+queries; Cohere bills $2 per 1,000 searches.
+`REVIT_API_DOCS_MIN_RELEVANCE` stays unset by default. Set to 0.15 it filters
+out clearly unrelated queries (questions that are not about Revit, types this
+data set does not have), abstaining on about 2.5% of the queries that do have
+an answer (measured on `v1.0-data`). It cannot spot a misspelt or misplaced
+member name: such a query usually gets the closest real API as the first
+result, to be confirmed with a compile check. **Do not use 0.5**: it
+abstained on 14% of the queries that have an answer. What TypeSafe keeps: see the `jev-data-handling` note
+(`uvx revit-api-docs environment typesafe`).
+
+**Vector search.** An embedding key (`REVIT_API_DOCS_EMBEDDING_API_KEY`, or
+`OPENROUTER_API_KEY`) turns it on; each query then costs one embedding request
+(about 0.9 s). The vector hits and the BM25 hits, 30 of each, are fused by
+reciprocal rank (score = sum of 1 / (60 + rank)) and the best 30 go to the
+reranker; without a reranker they are cut to `top_k`. On 223 English test
+queries without reranking (measured on `v1.1-data`), fusion raises nDCG@5
+from 0.557 (BM25 alone) to 0.647, and on the 113 of them that describe a
+multi-step task from 0.355 to 0.459, with an answer among the top 30 for 82%
+of those instead of 72%. Each
+vector hit is matched to its entry by name. On the first vector query the
+server samples 50 records of each vector collection: when the record ids do
+not line up with the rows it logs the warning `vector_store_misaligned` and
+keeps matching by name (the older `v1.0-data` vector store numbers its records
+differently from the rows of `revit_api.db`; `v1.1-data` is aligned and logs
+nothing); when the names are not found either, it turns vector search off
+until the server restarts and answers from keyword search. `revit-api-docs download`
+prints the same check for the installed data set.
+
+Privacy: with an embedding, Cohere or TypeSafe key the query text and the
+candidate API entries (public documentation) are sent to that provider. Keep
+queries to API names and generic task descriptions, in English.
+
+Data set (`v1.1-data`): the API reference comes from `RevitAPI.chm` of the
+Revit 2026.3 SDK (the same pages as the Revit 2026 reference) and includes
+constructor pages and interface members such as
+`IExternalEventHandler.Execute`: 28,862 entries, of which the 27,596 of
+`v1.0-data` are unchanged under the same ids. The SDK samples (153 projects)
+come from the Revit 2026 SDK. The SQLite databases and ChromaDB indexes were
+built with the pipeline in `pipeline/` (`uv sync --extra pipeline`; needs the
+CHM, the SDK and OpenRouter/Cohere keys in the environment). `v1.1-data` was
+built from `v1.0-data` with `uv run python -m pipeline.build_data_v1_1
+--html-dir <CHM html dir> --base-db <v1.0-data dir>/sqlite/revit_api.db`, which
+appends the pages `v1.0-data` lacked and rebuilds the API vector store so that
+every record id is its row id. The server does not need any of that.
+
+Development:
+
+```bash
+uv sync
+uv run pytest
+uv build
+uvx --from . revit-api-docs search "Wall.Create"
+```
+
+License: MIT. Issues and discussion: <https://github.com/revitbridge/revit-api-docs/issues>.