Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

4.2 KB
Raw Blame
"""`GET /api/v1/` hand-writes its endpoint list; this stops it drifting.

The PR review asked why this list is maintained by hand when FastAPI already
generates OpenAPI. The answer is that it is *curated*, not exhaustive: it
advertises the three research endpoints and deliberately omits `/health` and
the documentation route itself. Generating it from the router would either
advertise those or need a filter that drifts in the same way, and it would
change the shape of a response that external callers already parse.

So the hand-written list stays and this test removes the failure mode instead.
Two directions, because drift goes both ways:

* a documented endpoint that no longer exists sends callers at a 404;
* an endpoint added to the router but not documented is invisible to anyone
  reading the API's own documentation -- the quieter and more likely of the two,
  since adding a route is what people do and editing this dict is what they
  forget.
"""

from fastapi.routing import APIRoute

from local_deep_research.web.routers import api_v1


def _router_post_routes() -> dict[str, set[str]]:
    """{path: {methods}} for the POST routes this router actually serves."""
    found: dict[str, set[str]] = {}
    for route in api_v1.router.routes:
        if not isinstance(route, APIRoute):
            continue
        methods = {m for m in route.methods if m not in ("HEAD", "OPTIONS")}
        if "POST" in methods:
            found[route.path] = methods
    return found


def _documented() -> list[dict]:
    """The endpoint list as the route body declares it.

    Read out of the function's own return value rather than over HTTP, so this
    needs no app, no auth and no rate limiter -- and so a failure points at the
    dict rather than at the plumbing in front of it.
    """
    source_fn = api_v1.api_documentation
    # The route is wrapped by @api_rate_limit; unwrap to the authored body.
    while hasattr(source_fn, "__wrapped__"):
        source_fn = source_fn.__wrapped__
    import inspect
    import ast

    tree = ast.parse(inspect.getsource(source_fn).lstrip())
    for node in ast.walk(tree):
        if isinstance(node, ast.Return):
            payload = ast.literal_eval(node.value)
            return payload["endpoints"]
    raise AssertionError("api_documentation no longer returns a literal")


class TestTheAdvertisedEndpointsExist:
    def test_every_documented_path_is_served(self):
        served = _router_post_routes()
        missing = [
            entry["path"]
            for entry in _documented()
            if entry["path"] not in served
        ]
        assert not missing, (
            f"GET /api/v1/ advertises {missing}, which this router does not "
            "serve. Callers reading the API's own documentation would get a "
            "404. Remove the entry or restore the route."
        )

    def test_every_documented_method_matches(self):
        served = _router_post_routes()
        wrong = [
            (entry["path"], entry["method"], sorted(served[entry["path"]]))
            for entry in _documented()
            if entry["path"] in served
            and entry["method"] not in served[entry["path"]]
        ]
        assert not wrong, f"documented method does not match the route: {wrong}"


class TestNoEndpointIsUndocumented:
    def test_every_post_route_is_advertised(self):
        """The direction that actually rots: add a route, forget the dict."""
        documented = {entry["path"] for entry in _documented()}
        undocumented = sorted(set(_router_post_routes()) - documented)
        assert not undocumented, (
            f"these POST endpoints are served but not advertised by "
            f"GET /api/v1/: {undocumented}. Add them to the endpoints list in "
            "api_v1.api_documentation, including a parameters entry -- that "
            "list is the only API documentation a caller gets from the "
            "service itself."
        )

    def test_the_list_is_not_empty(self):
        """Guards the two tests above, which both pass on an empty list."""
        assert len(_documented()) >= 3, (
            "the endpoint list has shrunk below the three research endpoints; "
            "the emptier it gets the more vacuously the other tests pass"
        )