revit-api-docs 0.1.0__py3-none-any.whl

revit_api_docs/__init__.py

@@ -0,0 +1,18 @@
+"""revit-api-docs: Revit API reference search for MCP hosts.
+
+An optional companion to revit-bridge for models that do not know the Revit
+API well. It answers two questions over a local copy of the Revit 2026 API
+reference (27,596 entries) and the SDK samples: "which API do I call?" and
+"how does the SDK use it?". The data set is downloaded from a GitHub Release
+on first run; the package never talks to Revit.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("revit-api-docs")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

revit_api_docs/__main__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+
+from revit_api_docs.server import main
+
+if __name__ == "__main__":
+    sys.exit(main())

revit_api_docs/config.py

@@ -0,0 +1,115 @@
+"""Configuration: bundled defaults plus environment overrides.
+
+The MCP server needs no config file. `load_config()` reads the packaged
+`default_config.yaml` (or the file named by `REVIT_API_DOCS_CONFIG`) and then
+applies the `REVIT_API_DOCS_*` environment variables documented in the README.
+The dict keeps the shape the retriever and the pipeline tools expect
+(`embedding.models.<provider>`, `llm.models.<provider>`, `rerank`, `retrieval`,
+`sdk`); API keys are looked up by the environment variable named in
+`api_key_env`, never stored in the dict.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ENV_CONFIG = "REVIT_API_DOCS_CONFIG"
+ENV_EMBEDDING_API_KEY = "REVIT_API_DOCS_EMBEDDING_API_KEY"
+ENV_EMBEDDING_BASE_URL = "REVIT_API_DOCS_EMBEDDING_BASE_URL"
+ENV_EMBEDDING_MODEL = "REVIT_API_DOCS_EMBEDDING_MODEL"
+ENV_EMBEDDING_PROVIDER = "REVIT_API_DOCS_EMBEDDING_PROVIDER"
+
+# Keys tried, in order, when REVIT_API_DOCS_EMBEDDING_API_KEY is unset.
+EMBEDDING_KEY_FALLBACKS = ("OPENROUTER_API_KEY",)
+
+_DEFAULT_CONFIG = Path(__file__).with_name("default_config.yaml")
+
+
+def load_config(config_path: str | os.PathLike[str] | None = None) -> dict[str, Any]:
+    """Load the YAML config and apply environment overrides."""
+    path = Path(config_path or os.getenv(ENV_CONFIG) or _DEFAULT_CONFIG)
+    with open(path, "r", encoding="utf-8") as f:
+        config = yaml.safe_load(f) or {}
+    apply_env_overrides(config, os.environ)
+    return config
+
+
+def apply_env_overrides(config: dict[str, Any], env: os._Environ[str] | dict[str, str]) -> None:
+    """Mutate `config` in place from REVIT_API_DOCS_* variables."""
+    emb = config.setdefault("embedding", {})
+    provider = env.get(ENV_EMBEDDING_PROVIDER) or emb.get("provider", "openai")
+    emb["provider"] = provider
+    model_cfg = emb.setdefault("models", {}).setdefault(provider, {})
+
+    if env.get(ENV_EMBEDDING_MODEL):
+        model_cfg["model"] = env[ENV_EMBEDDING_MODEL]
+    if env.get(ENV_EMBEDDING_BASE_URL) and provider == "openai":
+        model_cfg["base_url"] = env[ENV_EMBEDDING_BASE_URL]
+
+    # Resolve which variable holds the embedding key so the provider can read it.
+    if provider == "openai":
+        if env.get(ENV_EMBEDDING_API_KEY):
+            model_cfg["api_key_env"] = ENV_EMBEDDING_API_KEY
+        else:
+            for name in EMBEDDING_KEY_FALLBACKS:
+                if env.get(name):
+                    model_cfg["api_key_env"] = name
+                    break
+            else:
+                model_cfg.setdefault("api_key_env", ENV_EMBEDDING_API_KEY)
+
+
+def load_dotenv(root: str | Path | None = None) -> None:
+    """Read `.env` in `root` (default: current directory) into os.environ.
+
+    Existing variables are not overwritten. Used by the pipeline tools; the
+    MCP server relies on the host's environment only.
+    """
+    env = Path(root or Path.cwd()) / ".env"
+    if not env.exists():
+        return
+    for line in env.read_text(encoding="utf-8", errors="ignore").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+
+
+def get_api_key(env_name: str) -> str:
+    """Return the key held by `env_name`, or raise ValueError when unset."""
+    key = os.getenv(env_name, "")
+    if not key:
+        raise ValueError(f"environment variable {env_name} is not set")
+    return key
+
+
+_config: dict[str, Any] | None = None
+
+
+def get_config() -> dict[str, Any]:
+    """Process-wide config singleton (first call loads it)."""
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config
+
+
+def get_proxy_url() -> str | None:
+    """Proxy URL from HTTPS_PROXY/HTTP_PROXY, else from the config, else None."""
+    from_env = (
+        os.getenv("HTTPS_PROXY") or os.getenv("HTTP_PROXY")
+        or os.getenv("https_proxy") or os.getenv("http_proxy")
+    )
+    if from_env:
+        return from_env
+    try:
+        proxy_cfg = get_config().get("proxy", {})
+    except FileNotFoundError:
+        return None
+    if proxy_cfg.get("enabled"):
+        return proxy_cfg.get("https") or proxy_cfg.get("http") or None
+    return None

revit_api_docs/data.py

@@ -0,0 +1,320 @@
+"""Data set location and first-run download.
+
+The API reference (SQLite) and the vector stores (ChromaDB directories) are
+not in the wheel; they come from the GitHub Release `v1.0-data` of this
+repository. `ensure_data()` downloads whatever is missing into the data
+directory, verifies each file against the SHA-256 recorded below, unpacks the
+tarballs and writes `manifest.json`.
+
+Data directory (override with REVIT_API_DOCS_DATA_DIR):
+    Windows  %LOCALAPPDATA%/revit-api-docs
+    macOS    ~/Library/Application Support/revit-api-docs
+    Linux    $XDG_DATA_HOME/revit-api-docs  (default ~/.local/share)
+
+Layout inside it (same as the old repository's data/ tree, so an existing
+copy can be pointed at directly):
+    sqlite/revit_api.db
+    sqlite/revit_sdk.db
+    chromadb/chromadb_api/
+    chromadb/chromadb_code/
+    manifest.json
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import shutil
+import sys
+import tarfile
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterable
+
+import httpx
+
+log = logging.getLogger("revit_api_docs.data")
+
+ENV_DATA_DIR = "REVIT_API_DOCS_DATA_DIR"
+ENV_RELEASE_URL = "REVIT_API_DOCS_RELEASE_URL"
+
+RELEASE_TAG = "v1.0-data"
+RELEASE_URL = f"https://github.com/revitbridge/revit-api-docs/releases/download/{RELEASE_TAG}"
+
+ProgressFn = Callable[[str, int, int], None]
+
+
+@dataclass(frozen=True)
+class Artifact:
+    """One release asset: where it lands and how to check it."""
+
+    name: str
+    sha256: str
+    size: int
+    target: str          # path inside the data dir (file, or directory for tarballs)
+    extract: bool = False
+
+
+ARTIFACTS: tuple[Artifact, ...] = (
+    Artifact("revit_api.db", "38f78297b11b5fb4aa8a0c609e2a0535b5d2f6770ea895c8468742e6d4a7bf72",
+             33_611_776, "sqlite/revit_api.db"),
+    Artifact("revit_sdk.db", "f381f392485cd4910b2b826062414b5331c29f165269412ebb59569dd176e474",
+             954_368, "sqlite/revit_sdk.db"),
+    Artifact("chromadb_api.tar.gz", "2db7c2fafa45defb1cc56522c5c5455741549d42d56bbec918a93554c4b15c73",
+             299_124_932, "chromadb/chromadb_api", extract=True),
+    Artifact("chromadb_code.tar.gz", "3ee38a4e44e4b41154faeafd431c830ca54275d2738897971e5780cb493118ad",
+             1_792_184, "chromadb/chromadb_code", extract=True),
+)
+
+TOTAL_DOWNLOAD_BYTES = sum(a.size for a in ARTIFACTS)
+
+
+@dataclass(frozen=True)
+class DataPaths:
+    root: Path
+    api_db: Path
+    sdk_db: Path
+    chromadb_api: Path
+    chromadb_code: Path
+    manifest: Path
+
+
+def default_data_dir() -> Path:
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        base = str(Path.home() / "Library" / "Application Support")
+    else:
+        base = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return Path(base) / "revit-api-docs"
+
+
+def data_dir() -> Path:
+    env = os.environ.get(ENV_DATA_DIR)
+    return Path(env).expanduser() if env else default_data_dir()
+
+
+def release_url() -> str:
+    return os.environ.get(ENV_RELEASE_URL, RELEASE_URL).rstrip("/")
+
+
+def paths(root: Path | None = None) -> DataPaths:
+    root = Path(root) if root is not None else data_dir()
+    return DataPaths(
+        root=root,
+        api_db=root / "sqlite" / "revit_api.db",
+        sdk_db=root / "sqlite" / "revit_sdk.db",
+        chromadb_api=root / "chromadb" / "chromadb_api",
+        chromadb_code=root / "chromadb" / "chromadb_code",
+        manifest=root / "manifest.json",
+    )
+
+
+def _installed(root: Path, art: Artifact) -> bool:
+    target = root / art.target
+    if art.extract:
+        return (target / "chroma.sqlite3").is_file()
+    return target.is_file()
+
+
+def unexpected_sizes(root: Path) -> list[tuple[Artifact, int]]:
+    """Present files whose size differs from the release asset (hand-copied
+    or built locally). They are used as they are, never replaced."""
+    out = []
+    for art in ARTIFACTS:
+        if art.extract:
+            continue
+        target = root / art.target
+        if target.is_file():
+            size = target.stat().st_size
+            if size != art.size:
+                out.append((art, size))
+    return out
+
+
+def read_manifest(root: Path) -> dict | None:
+    p = root / "manifest.json"
+    if not p.is_file():
+        return None
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def missing(root: Path | None = None) -> list[Artifact]:
+    """Artifacts that must be downloaded: the absent ones.
+
+    An existing file is never replaced, whatever its size (a hand-copied tree
+    may hold a different build; see unexpected_sizes). The one exception is a
+    manifest written by this installer for another release, which marks the
+    whole tree stale.
+    """
+    root = Path(root) if root is not None else data_dir()
+    manifest = read_manifest(root)
+    if manifest is not None and manifest.get("release") != RELEASE_TAG:
+        return list(ARTIFACTS)
+    return [a for a in ARTIFACTS if not _installed(root, a)]
+
+
+def is_ready(root: Path | None = None) -> bool:
+    return not missing(root)
+
+
+def sha256_file(path: Path, chunk: int = 1 << 20) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            block = f.read(chunk)
+            if not block:
+                break
+            h.update(block)
+    return h.hexdigest()
+
+
+def download_file(url: str, dest: Path, expected_size: int,
+                  progress: ProgressFn | None = None, name: str = "",
+                  timeout: float = 60.0) -> None:
+    """Stream `url` to `dest`, resuming a partial `dest` with a Range request."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    have = dest.stat().st_size if dest.exists() else 0
+    if have > expected_size:
+        dest.unlink()
+        have = 0
+    if have == expected_size:
+        return  # a previous run finished the download but not the checks
+    headers = {"Range": f"bytes={have}-"} if have else {}
+    mode = "ab" if have else "wb"
+
+    with httpx.Client(follow_redirects=True, timeout=timeout) as client:
+        with client.stream("GET", url, headers=headers) as resp:
+            if have and resp.status_code == 200:
+                # Server ignored the range: start over.
+                have, mode = 0, "wb"
+            elif resp.status_code not in (200, 206):
+                resp.raise_for_status()
+            done = have
+            last_report = time.monotonic()
+            with open(dest, mode) as out:
+                for chunk in resp.iter_bytes(1 << 20):
+                    out.write(chunk)
+                    done += len(chunk)
+                    now = time.monotonic()
+                    if progress and (now - last_report >= 1.0 or done >= expected_size):
+                        progress(name or dest.name, done, expected_size)
+                        last_report = now
+    if progress:
+        progress(name or dest.name, dest.stat().st_size, expected_size)
+
+
+def _extract_tarball(archive: Path, target: Path) -> None:
+    """Unpack `archive` (which holds one top-level directory) to `target`."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = Path(tempfile.mkdtemp(prefix=f".{target.name}-", dir=target.parent))
+    try:
+        with tarfile.open(archive, "r:gz") as tar:
+            try:
+                tar.extractall(tmp, filter="data")
+            except TypeError:  # Python < 3.11.4 without the filter argument
+                tar.extractall(tmp)
+        entries = [p for p in tmp.iterdir()]
+        src = entries[0] if len(entries) == 1 and entries[0].is_dir() else tmp
+        if target.exists():
+            shutil.rmtree(target)
+        shutil.move(str(src), str(target))
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def install_artifact(art: Artifact, root: Path, progress: ProgressFn | None = None) -> None:
+    """Download one artifact, verify it and put it in place."""
+    url = f"{release_url()}/{art.name}"
+    part = root / "downloads" / f"{art.name}.part"
+    log.info("downloading %s (%.1f MB) from %s", art.name, art.size / 1e6, url)
+    download_file(url, part, art.size, progress=progress, name=art.name)
+
+    digest = sha256_file(part)
+    if digest != art.sha256:
+        part.unlink(missing_ok=True)
+        raise RuntimeError(
+            f"{art.name}: SHA-256 mismatch (got {digest[:16]}..., expected "
+            f"{art.sha256[:16]}...); the partial download was discarded, run again"
+        )
+
+    target = root / art.target
+    if art.extract:
+        _extract_tarball(part, target)
+        part.unlink(missing_ok=True)
+    else:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(part, target)
+
+
+def describe_artifact(root: Path, art: Artifact, installed: bool) -> dict:
+    """Manifest entry for one artifact, honest about what was checked.
+
+    `installed` means this run downloaded and hash-checked it. Anything else
+    was already in `root`: a file is hashed now and counts as verified only
+    when it matches the release; an unpacked directory has nothing to hash
+    against and is recorded as trusted.
+    """
+    entry: dict = {"target": art.target, "release_sha256": art.sha256, "release_size": art.size}
+    target = root / art.target
+    if installed:
+        entry.update(sha256=art.sha256, size=art.size, verified=True)
+    elif art.extract:
+        entry.update(verified=False, trusted=(target / "chroma.sqlite3").is_file())
+    elif target.is_file():
+        digest = sha256_file(target)
+        verified = digest == art.sha256
+        entry.update(sha256=digest, size=target.stat().st_size, verified=verified)
+        if not verified:
+            entry["trusted"] = True
+    else:
+        entry.update(verified=False, trusted=False)
+    return entry
+
+
+def write_manifest(root: Path, installed: Iterable[str] = ()) -> None:
+    """Record the tree under `root`; `installed` names the artifacts this run
+    downloaded and verified (see describe_artifact for the rest)."""
+    root.mkdir(parents=True, exist_ok=True)
+    done = set(installed)
+    manifest = {
+        "release": RELEASE_TAG,
+        "source": release_url(),
+        "installed_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "files": {a.name: describe_artifact(root, a, a.name in done) for a in ARTIFACTS},
+    }
+    (root / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+
+def ensure_data(root: Path | None = None, progress: ProgressFn | None = None) -> DataPaths:
+    """Make sure every artifact is installed under `root`; return its paths."""
+    p = paths(root)
+    todo = missing(p.root)
+    for art, size in unexpected_sizes(p.root):
+        log.warning("%s: existing file is %d bytes, the %s release file is %d; using it as is "
+                    "(delete it to re-download)", p.root / art.target, size, RELEASE_TAG, art.size)
+    if todo:
+        p.root.mkdir(parents=True, exist_ok=True)
+        for art in todo:
+            install_artifact(art, p.root, progress=progress)
+        write_manifest(p.root, installed=[a.name for a in todo])
+        trusted = [n for n, e in read_manifest(p.root)["files"].items() if e.get("trusted")]
+        if trusted:
+            log.warning("manifest written with unverified pre-existing files: %s", ", ".join(trusted))
+        shutil.rmtree(p.root / "downloads", ignore_errors=True)
+    elif read_manifest(p.root) is None:
+        log.info("using existing data in %s (no manifest)", p.root)
+    return p
+
+
+def stderr_progress(name: str, done: int, total: int) -> None:
+    """Default progress reporter: one line per step, never on stdout."""
+    pct = 100 * done // total if total else 0
+    print(f"revit-api-docs: {name} {done / 1e6:.1f}/{total / 1e6:.1f} MB ({pct}%)",
+          file=sys.stderr, flush=True)

revit_api_docs/default_config.yaml

@@ -0,0 +1,85 @@
+# Bundled defaults for revit-api-docs.
+#
+# The MCP server needs no config file: everything a user may change comes from
+# environment variables (see README, "Configure"), which config.py layers on
+# top of this file. The offline pipeline tools (pipeline/ in the repository)
+# may point REVIT_API_DOCS_CONFIG at a copy of this file with edited llm/sdk
+# sections. API keys are never written here, only the environment variable
+# that holds them.
+
+revit_version: "2026"
+
+# HTTP proxy for outbound API calls (HTTPS_PROXY / HTTP_PROXY take precedence).
+proxy:
+  enabled: false
+  http: ""
+  https: ""
+
+openrouter:
+  base_url: "https://openrouter.ai/api/v1"
+  api_key_env: "OPENROUTER_API_KEY"
+
+# --- LLM (pipeline tools and optional query rewriting only) ---
+llm:
+  provider: "claude"
+  models:
+    claude:
+      model: "anthropic/claude-sonnet-4.6"
+      api_key_env: "OPENROUTER_API_KEY"
+      base_url: "https://openrouter.ai/api/v1"
+    gemini:
+      model: "google/gemini-3-flash-preview"
+      api_key_env: "OPENROUTER_API_KEY"
+      base_url: "https://openrouter.ai/api/v1"
+    gemini_flash:
+      model: "google/gemini-3-flash-preview"
+      api_key_env: "OPENROUTER_API_KEY"
+      base_url: "https://openrouter.ai/api/v1"
+    deepseek:
+      model: "deepseek/deepseek-chat-v3-0324"
+      api_key_env: "OPENROUTER_API_KEY"
+      base_url: "https://openrouter.ai/api/v1"
+  temperature: 0.3
+  max_tokens: 16384
+
+# --- Embedding (query time) ---
+# The shipped vector store was built with openai/text-embedding-3-large
+# (3072 dimensions) through OpenRouter. Queries must use the same model or
+# vector search returns noise; keyword search works without any key.
+embedding:
+  provider: "openai"
+  models:
+    openai:
+      model: "openai/text-embedding-3-large"
+      dimension: 3072
+      api_key_env: "REVIT_API_DOCS_EMBEDDING_API_KEY"
+      base_url: "https://openrouter.ai/api/v1"
+    google:
+      model: "text-embedding-004"
+      dimension: 768
+      api_key_env: "GOOGLE_API_KEY"
+
+# --- Rerank (optional; Cohere native REST API, skipped without the key) ---
+rerank:
+  enabled: true
+  provider: "cohere"
+  models:
+    cohere:
+      model: "rerank-v3.5"
+      api_key_env: "COHERE_API_KEY"
+
+# --- Retrieval ---
+retrieval:
+  api:
+    top_k: 30          # candidates fetched before rerank
+    rerank_top_n: 15   # default number returned
+  code:
+    top_k: 5
+    rerank_top_n: 3
+
+# --- SDK sample extraction (pipeline/sdk_parser) ---
+sdk:
+  stage1_provider: "gemini_flash"   # README parsing (cheap + fast)
+  stage2_provider: "claude"         # golden code generation (quality)
+  num_workers_phase1: 10
+  num_workers_phase2: 5

revit_api_docs/embedder/__init__.py

@@ -0,0 +1 @@
+"""Query-time embedding providers (the offline batch embedder lives in pipeline/)."""

revit_api_docs/embedder/providers/__init__.py

@@ -0,0 +1,25 @@
+"""Embedding provider factory: builds the provider named in config["embedding"]."""
+from .base import BaseEmbedding
+
+
+def create_embedding(config: dict) -> BaseEmbedding:
+    """Create the embedding provider selected by the config."""
+    provider = config["embedding"]["provider"]
+    model_config = config["embedding"]["models"][provider]
+
+    if provider == "google":
+        from .google import GoogleEmbedding
+        return GoogleEmbedding(**model_config)
+
+    elif provider == "openai":
+        from .openai import OpenAIEmbedding
+        return OpenAIEmbedding(**model_config)
+
+    elif provider == "local_hf":
+        raise NotImplementedError("local HuggingFace embedding is not implemented")
+
+    elif provider == "zhipu":
+        raise NotImplementedError("zhipu embedding is not implemented")
+
+    else:
+        raise ValueError(f"unsupported embedding provider: {provider}")

revit_api_docs/embedder/providers/base.py

@@ -0,0 +1,28 @@
+"""Abstract base for embedding providers (OpenAI-compatible, Google)."""
+from abc import ABC, abstractmethod
+
+
+class BaseEmbedding(ABC):
+    """Uniform embedding interface."""
+
+    @property
+    @abstractmethod
+    def model_name(self) -> str:
+        """Model name, recorded in the index meta.json."""
+        pass
+
+    @property
+    @abstractmethod
+    def dimension(self) -> int:
+        """Vector dimension."""
+        pass
+
+    @abstractmethod
+    def embed_texts(self, texts: list[str]) -> list[list[float]]:
+        """Embed a batch of texts."""
+        pass
+
+    @abstractmethod
+    def embed_query(self, query: str) -> list[float]:
+        """Embed a single query."""
+        pass

revit_api_docs/embedder/providers/google.py

@@ -0,0 +1,36 @@
+"""Google embedding provider (google-genai SDK; optional `pipeline` extra)."""
+from .base import BaseEmbedding
+from ...config import get_api_key
+
+
+class GoogleEmbedding(BaseEmbedding):
+
+    def __init__(self, model: str = "text-embedding-004", dimension: int = 768, api_key_env: str = "GOOGLE_API_KEY"):
+        from google import genai
+        self._model = model
+        self._dimension = dimension
+        self._client = genai.Client(api_key=get_api_key(api_key_env))
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    @property
+    def dimension(self) -> int:
+        return self._dimension
+
+    def embed_texts(self, texts: list[str]) -> list[list[float]]:
+        """Batch embedding (the Google API accepts batches)."""
+        result = self._client.models.embed_content(
+            model=self._model,
+            contents=texts,
+        )
+        return [e.values for e in result.embeddings]
+
+    def embed_query(self, query: str) -> list[float]:
+        """Embed a single query."""
+        result = self._client.models.embed_content(
+            model=self._model,
+            contents=[query],
+        )
+        return result.embeddings[0].values