Back to the room

Pass 3 of 3 · Deep dive of PHAROSPass 1 · OverviewPass 2 · How it works

Code Observatory / Source

Choose a mode, then run it

Auto is dense, or hybrid with hints, or keyword with a warning. An explicit mode that cannot run raises ModeUnavailable.

PINNED SOURCE Copied from the repository at this commit. Source, not an execution.

PHAROS at 975a38dMIT license

Retriever.searchbackend/app/codeintel/retrieval.py, lines 204–277Open source
    def search(self, query: str, *, mode: str = "auto", k: int = 10,               filters: Filters | None = None, hints: list[str] | None = None) -> SearchOutcome:        """``hints``: identifiers or keywords the caller guesses (an agent's        ``parse_url``, ``redirect``). They feed keyword retrieval and the exact        name boost; the question alone is embedded. With hints, ``auto`` is hybrid."""        if mode not in MODES:            raise ValueError(f"mode must be one of {MODES}")        filters = filters or Filters()        warnings: list[str] = []        timings: dict[str, float] = {}        candidates: dict[str, int] = {}        hints = [h.strip() for h in (hints or []) if h and h.strip()][:20]        terms = list(dict.fromkeys(query_terms(query) + query_terms(" ".join(hints))))        named = " ".join([query, *hints])        effective = mode        dense_reason = self._dense_unavailable_reason(filters)        if mode == "auto":            if dense_reason is None:                effective = "hybrid" if hints else "dense"            else:                effective = "keyword"                warnings.append(f"dense retrieval unavailable ({dense_reason}); used keyword retrieval only")        elif mode in ("dense", "hybrid", "graph") and dense_reason is not None:            raise ModeUnavailable(mode, dense_reason)        keyword: list[tuple[str, float]] = []        dense: list[tuple[str, float]] = []        if effective in ("keyword", "hybrid", "graph"):            t = time.perf_counter()            keyword = self._keyword(terms, filters, CANDIDATES if effective != "keyword" else max(k * 3, CANDIDATES))            timings["keyword"] = (time.perf_counter() - t) * 1000            candidates["keyword"] = len(keyword)            if not terms:                warnings.append("query has no searchable terms for keyword retrieval")        if effective in ("dense", "hybrid", "graph"):            t = time.perf_counter()            try:                qvec = self.embedder.embed_query(query)  # type: ignore[union-attr]            except EmbeddingUnavailable as exc:                if mode == "auto":                    warnings.append(f"query embedding failed ({exc}); used keyword retrieval only")                    effective = "keyword"                    qvec = None                else:                    raise ModeUnavailable(mode, str(exc)) from exc            timings["embed_query"] = (time.perf_counter() - t) * 1000            if qvec is not None:                t = time.perf_counter()                dense = self._dense(qvec, filters, CANDIDATES)                timings["dense"] = (time.perf_counter() - t) * 1000                candidates["dense"] = len(dense)        t = time.perf_counter()        hits = self._fuse(effective, keyword, dense, terms, named, hints)        if effective == "graph" and hits:            hits = self._expand_graph(hits, filters)        hits = self._finalize(hits, k, wanted_roles(query))        timings["fuse"] = (time.perf_counter() - t) * 1000        t = time.perf_counter()        self._hydrate(hits)        timings["hydrate"] = (time.perf_counter() - t) * 1000        timings["total"] = sum(timings.values())        return SearchOutcome(            query=query,            mode_requested=mode,            mode_used=effective,            hits=hits,            warnings=warnings,            embedding_model=self.embedder.model_id if self.embedder else None,            timings_ms={k_: round(v, 2) for k_, v in timings.items()},            candidates=candidates,        )

Where this comes from

Commit
975a38d5d17839c26ee219295a5be6ac66b6d910
File
backend/app/codeintel/retrieval.py
Lines
204–277
Git blob
884729a39ae0b3d340ad83f75946677dcddf3791
License
MIT, © 2024–2026 Pharos Contributors. Notice

Read it on GitHub at this commit

Check it yourself

From a clone of the repository, the first command prints the blob above and the second prints these lines.

git rev-parse 975a38d:backend/app/codeintel/retrieval.py
git show 975a38d:backend/app/codeintel/retrieval.py | sed -n '204,277p'