UPDATE: Harmonize Dockerfile and FastAPI server with mcp implementation, add TINYSEARCH_VERSION environment variable and normalize research query function

Author: MarcellM01

Dockerfile

@@ -11,6 +11,7 @@ LABEL org.opencontainers.image.title="TinySearch" \
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     PIP_NO_CACHE_DIR=1 \
+    TINYSEARCH_VERSION=${TINYSEARCH_VERSION} \
     TINYSEARCH_MODELS_DIR=/data/models \
     PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
 

servers/fastapi_server.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import os
 import sys
 from contextlib import asynccontextmanager
 from pathlib import Path
@@ -18,6 +19,8 @@
 from services.research_config_service import (
     config_trace_path,
     load_research_config,
+    normalize_research_query,
+    research_run_kwargs,
     research_tokenizer_name,
 )
 from services.site_crawl_service import crawl_search
@@ -36,6 +39,10 @@ async def _ensure_local_bundle_for_config(config: dict[str, Any]) -> None:
     await asyncio.to_thread(ensure_onnx_bundle_sync, str(config["embedding_model"]))
 
 
+def _tinysearch_version() -> str:
+    return os.environ.get("TINYSEARCH_VERSION", "dev").strip() or "dev"
+
+
 @asynccontextmanager
 async def _lifespan(_app: FastAPI):
     cfg = load_research_config()
@@ -46,7 +53,7 @@ async def _lifespan(_app: FastAPI):
 app = FastAPI(
     title="TinySearch API",
     description="Web search, site crawl, and hybrid research endpoints.",
-    version="0.1.4",
+    version=_tinysearch_version(),
     lifespan=_lifespan,
 )
 
@@ -85,6 +92,7 @@ class ResearchRequest(BaseModel):
     chunk_max_per_source_url: int | None = Field(default=None, ge=0, le=500)
     max_concurrent_crawls: int | None = Field(default=None, ge=1, le=20)
     max_concurrent_embedding_calls: int | None = Field(default=None, ge=1, le=20)
+    pipeline_timeout_seconds: float | None = Field(default=None, gt=0)
     embedding_timeout_seconds: float | None = Field(default=None, gt=0)
     embedding_timeout_retries: int | None = Field(default=None, ge=0, le=10)
     crawl_fit_markdown_mode: str | None = None
@@ -173,94 +181,22 @@ async def site_crawl_get(
 @app.post("/research")
 async def research_endpoint(request: ResearchRequest) -> dict[str, Any]:
     config = load_research_config()
-    embedding_model = request.embedding_model or str(config["embedding_model"])
+    query = normalize_research_query(request.query)
+    overrides = request.model_dump(exclude_none=True)
+    overrides.pop("query")
+    trace_path = overrides.pop("trace_path", None)
+
+    run_kwargs = research_run_kwargs(config)
+    run_kwargs.update(overrides)
+    embedding_model = str(run_kwargs["embedding_model"])
     if normalize_embedding_backend(str(config["embedding_backend"])) == "onnx":
         from services.onnx_bundle_service import ensure_onnx_bundle_sync
 
         await asyncio.to_thread(ensure_onnx_bundle_sync, embedding_model)
     result = await agentic_run(
-        request.query,
-        search_top_k=request.search_top_k or int(config["search_top_k"]),
-        search_rrf_cutoff=request.search_rrf_cutoff
-        if request.search_rrf_cutoff is not None
-        else float(config["search_rrf_cutoff"]),
-        search_dense_weight=request.search_dense_weight
-        if request.search_dense_weight is not None
-        else float(config["search_dense_weight"]),
-        search_max_results_to_keep=request.search_max_results_to_keep
-        or int(config["search_max_results_to_keep"]),
-        chunk_rrf_cutoff=request.chunk_rrf_cutoff
-        if request.chunk_rrf_cutoff is not None
-        else float(config["chunk_rrf_cutoff"]),
-        chunk_dense_weight=request.chunk_dense_weight
-        if request.chunk_dense_weight is not None
-        else float(config["chunk_dense_weight"]),
-        chunk_max_results_to_keep=request.chunk_max_results_to_keep
-        or int(config["chunk_max_results_to_keep"]),
-        chunk_rank_oversample=request.chunk_rank_oversample
-        or int(config["chunk_rank_oversample"]),
-        chunk_dedupe_jaccard_threshold=request.chunk_dedupe_jaccard_threshold
-        if request.chunk_dedupe_jaccard_threshold is not None
-        else float(config["chunk_dedupe_jaccard_threshold"]),
-        chunk_max_per_source_url=request.chunk_max_per_source_url
-        if request.chunk_max_per_source_url is not None
-        else int(config["chunk_max_per_source_url"]),
-        max_concurrent_crawls=request.max_concurrent_crawls
-        or int(config["max_concurrent_crawls"]),
-        max_concurrent_embedding_calls=request.max_concurrent_embedding_calls
-        or int(config["max_concurrent_embedding_calls"]),
-        embedding_timeout_seconds=request.embedding_timeout_seconds
-        if request.embedding_timeout_seconds is not None
-        else float(config["embedding_timeout_seconds"]),
-        embedding_timeout_retries=request.embedding_timeout_retries
-        if request.embedding_timeout_retries is not None
-        else int(config["embedding_timeout_retries"]),
-        crawl_max_chunk_tokens=request.crawl_max_chunk_tokens
-        or int(config["crawl_max_chunk_tokens"]),
-        crawl_overlap_tokens=request.crawl_overlap_tokens
-        if request.crawl_overlap_tokens is not None
-        else int(config["crawl_overlap_tokens"]),
-        crawl_max_page_tokens=request.crawl_max_page_tokens
-        if request.crawl_max_page_tokens is not None
-        else int(config["crawl_max_page_tokens"]),
-        crawl_fit_markdown_mode=(
-            request.crawl_fit_markdown_mode
-            if request.crawl_fit_markdown_mode is not None
-            else str(config["crawl_fit_markdown_mode"])
-        ),
-        crawl_fit_min_chars=(
-            request.crawl_fit_min_chars
-            if request.crawl_fit_min_chars is not None
-            else int(config["crawl_fit_min_chars"])
-        ),
-        crawl_bm25_threshold=request.crawl_bm25_threshold
-        if request.crawl_bm25_threshold is not None
-        else float(config["crawl_bm25_threshold"]),
-        crawl_bm25_language=(
-            request.crawl_bm25_language
-            if request.crawl_bm25_language is not None
-            else str(config["crawl_bm25_language"])
-        ),
-        crawl_pruning_threshold=(
-            request.crawl_pruning_threshold
-            if request.crawl_pruning_threshold is not None
-            else float(config["crawl_pruning_threshold"])
-        ),
-        embedding_backend=str(config["embedding_backend"]),
-        embedding_model=embedding_model,
-        embedding_openai_env_file=str(config["embedding_openai_env_file"]),
-        dense_query_prefix=request.dense_query_prefix
-        if request.dense_query_prefix is not None
-        else str(config["dense_query_prefix"]),
-        dense_document_prefix=request.dense_document_prefix
-        if request.dense_document_prefix is not None
-        else str(config["dense_document_prefix"]),
-        dense_document_embed_batch_size=request.dense_document_embed_batch_size
-        if request.dense_document_embed_batch_size is not None
-        else int(config["dense_document_embed_batch_size"]),
-        blocked_domains=config["blocked_domains"],
-        encoding_name=request.encoding_name or str(config["encoding_name"]),
-        trace_path=Path(request.trace_path) if request.trace_path else config_trace_path(config),
+        query,
+        **run_kwargs,
+        trace_path=Path(trace_path) if trace_path else config_trace_path(config),
     )
     return {"answer": result.answer}
 

servers/mcp_server.py

@@ -20,6 +20,7 @@
 from services.research_config_service import (
     config_trace_path,
     load_research_config,
+    normalize_research_query,
     research_run_kwargs,
     research_tokenizer_name,
 )
@@ -156,13 +157,6 @@ def _ensure_local_bundle_for_config(config: dict[str, Any]) -> None:
     ensure_onnx_bundle_sync(str(config["embedding_model"]))
 
 
-def _validate_query(query: str) -> str:
-    query = query.strip()
-    if not query:
-        raise ValueError("query must not be empty")
-    return query
-
-
 def _log(message: str) -> None:
     print(f"[tinysearch] {message}", file=sys.stderr, flush=True)
 
@@ -198,7 +192,7 @@ def _enable_traceback_dump() -> None:
     ),
 )
 async def research(query: str) -> dict[str, Any]:
-    query = _validate_query(query)
+    query = normalize_research_query(query)
     started = time.monotonic()
     _log(f"research called query={query!r}")
     try:

services/research_config_service.py

@@ -218,6 +218,13 @@ def research_run_kwargs(config: dict[str, Any] | None = None) -> dict[str, Any]:
     return {key: config[key] for key in keys}
 
 
+def normalize_research_query(query: str) -> str:
+    query = query.strip()
+    if not query:
+        raise ValueError("query must not be empty")
+    return query
+
+
 def research_embedding_model_info(config: dict[str, Any] | None = None) -> dict[str, str]:
     config = load_research_config() if config is None else config
     backend = normalize_embedding_backend(str(config["embedding_backend"]))

tests/test_server_embedding_startup.py

@@ -1,10 +1,22 @@
 from __future__ import annotations
 
 import unittest
-from unittest.mock import patch
-
-from servers.fastapi_server import _ensure_local_bundle_for_config as ensure_fastapi_bundle
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+from servers.fastapi_server import (
+    ResearchRequest,
+    _ensure_local_bundle_for_config as ensure_fastapi_bundle,
+    _tinysearch_version,
+    research_endpoint,
+)
 from servers.mcp_server import _ensure_local_bundle_for_config as ensure_mcp_bundle
+from services.research_config_service import (
+    DEFAULT_RESEARCH_CONFIG,
+    config_trace_path,
+    normalize_research_query,
+    research_run_kwargs,
+)
 
 
 class ServerEmbeddingStartupTests(unittest.IsolatedAsyncioTestCase):
@@ -25,6 +37,68 @@ async def test_fastapi_startup_skips_openai_compatible_backend(self) -> None:
         ensure.assert_not_called()
 
 
+class FastApiResearchParityTests(unittest.IsolatedAsyncioTestCase):
+    async def test_research_uses_same_config_defaults_as_mcp(self) -> None:
+        config = dict(DEFAULT_RESEARCH_CONFIG)
+        config["embedding_backend"] = "openai_compatible"
+        run = AsyncMock(return_value=SimpleNamespace(answer="grounded prompt"))
+
+        with patch(
+            "servers.fastapi_server.load_research_config", return_value=config
+        ), patch("servers.fastapi_server.agentic_run", new=run):
+            response = await research_endpoint(ResearchRequest(query="  test query  "))
+
+        self.assertEqual(response, {"answer": "grounded prompt"})
+        run.assert_awaited_once_with(
+            "test query",
+            **research_run_kwargs(config),
+            trace_path=config_trace_path(config),
+        )
+
+    async def test_research_request_overrides_shared_defaults(self) -> None:
+        config = dict(DEFAULT_RESEARCH_CONFIG)
+        config["embedding_backend"] = "openai_compatible"
+        run = AsyncMock(return_value=SimpleNamespace(answer="grounded prompt"))
+
+        with patch(
+            "servers.fastapi_server.load_research_config", return_value=config
+        ), patch("servers.fastapi_server.agentic_run", new=run):
+            await research_endpoint(
+                ResearchRequest(
+                    query="test query",
+                    search_top_k=7,
+                    pipeline_timeout_seconds=9.5,
+                )
+            )
+
+        kwargs = run.await_args.kwargs
+        self.assertEqual(kwargs["search_top_k"], 7)
+        self.assertEqual(kwargs["pipeline_timeout_seconds"], 9.5)
+
+    async def test_research_rejects_whitespace_only_query(self) -> None:
+        with patch(
+            "servers.fastapi_server.load_research_config",
+            return_value=dict(DEFAULT_RESEARCH_CONFIG),
+        ):
+            with self.assertRaisesRegex(ValueError, "query must not be empty"):
+                await research_endpoint(ResearchRequest(query="   "))
+
+
+class ServerRuntimeMetadataTests(unittest.TestCase):
+    def test_version_comes_from_environment(self) -> None:
+        with patch.dict("os.environ", {"TINYSEARCH_VERSION": "v0.2.0"}):
+            self.assertEqual(_tinysearch_version(), "v0.2.0")
+
+    def test_version_defaults_to_dev(self) -> None:
+        with patch.dict("os.environ", {}, clear=True):
+            self.assertEqual(_tinysearch_version(), "dev")
+
+    def test_query_normalization_is_shared(self) -> None:
+        self.assertEqual(normalize_research_query("  hello  "), "hello")
+        with self.assertRaisesRegex(ValueError, "query must not be empty"):
+            normalize_research_query("  ")
+
+
 class McpEmbeddingStartupTests(unittest.TestCase):
     def test_mcp_startup_ensures_selected_local_embedding_model(self) -> None:
         cfg = {"embedding_backend": "onnx", "embedding_model": "quality"}