smartrag 0.0.1__tar.gz

smartrag-0.0.1/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs / tooling
+.venv/
+venv/
+.env
+.uv/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+
+# Local secrets (API key stores written by the CLI)
+api_keys.json
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

smartrag-0.0.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: smartrag
+Version: 0.0.1
+Summary: A knowledge source any agent can use: search returns evidence with citations, the agent writes the answer.
+Project-URL: Homepage, https://github.com/gotoai/smartrag
+Project-URL: Repository, https://github.com/gotoai/smartrag
+Project-URL: Issues, https://github.com/gotoai/smartrag/issues
+Author: GOTOAI
+Keywords: agents,embeddings,mcp,rag,retrieval,search
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: dev
+Requires-Dist: httpx2>=2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Smart RAG
+
+A knowledge source any agent can use. **Search returns evidence** (snippets, stable ids,
+citations); the agent, or a person at the search box, writes the answer.
+
+Status: **skeleton** (0.0.1). The query-plane Web API is complete as a contract and runs on an
+in-memory demo engine. The real index (PostgreSQL + pgvector + PGroonga, embeddings from
+OumiGo's `/v1/embeddings`), ingestion and the admin CLI are still to come.
+
+## Run
+
+```sh
+uv venv --python 3.12 && uv pip install -e '.[dev]'
+.venv/bin/smartrag serve --demo --no-auth          # http://127.0.0.1:8710/docs
+curl -s 'http://127.0.0.1:8710/v1/search?q=有給休暇の繰り越し' | python3 -m json.tool
+.venv/bin/pytest
+```
+
+`--no-auth` is refused unless the server binds a loopback address. Otherwise clients send
+`Authorization: Bearer <key>`, checked against the hashed key file `SMARTRAG_API_KEYS_FILE`:
+
+```json
+[{"key_id": "ui-search", "sha256": "<sha256 of the key>", "role": "reader", "delegate": true}]
+```
+
+## Web API (query plane)
+
+| Method & path | Purpose |
+|---|---|
+| `GET /v1/sources` | What is indexed, filterable fields, freshness (no URIs, no credentials) |
+| `POST /v1/search` | Natural-language search: snippets, ids, citations; filters, cursors, facets |
+| `GET /v1/search?q=` | The same for the search box: one result per document, bookmarkable |
+| `GET /v1/chunks/{chunk_id}` | Read with `scope=chunk\|neighbors\|section\|document`, paged by `max_chars` |
+| `GET /v1/documents/{doc_id}` | Metadata and outline; text in pages with `include=text` |
+| `POST /v1/feedback` | `click` / `relevant` / `irrelevant` for a `query_id` |
+| `GET /healthz`, `/readyz`, `/version` | Ops (no auth) |
+
+- Errors always look like `{"error": {"code", "message", "details"}}`.
+- A chunk from an older document version returns `410 chunk_superseded`, with the current version.
+- `X-SmartRAG-On-Behalf-Of: <user>` names the end user (keys with `delegate` only).
+
+Admin operations (sources, sync, jobs, index, query logs, API keys, eval) are **not** part of
+the Web API by design: they run through the `smartrag` CLI on the operator host, and the
+query server holds no source credentials.
+
+## Layout
+
+```
+src/smartrag/
+  models.py        request/response schemas (the contract)
+  errors.py        errors with stable codes
+  paging.py        opaque cursors bound to their request
+  engine/          RetrievalEngine protocol; in-memory engine + demo corpus
+  api/             FastAPI app: query routes, ops routes, auth, error shape
+  cli/             `smartrag serve` (admin commands to come)
+```

smartrag-0.0.1/README.md

@@ -0,0 +1,56 @@
+# Smart RAG
+
+A knowledge source any agent can use. **Search returns evidence** (snippets, stable ids,
+citations); the agent, or a person at the search box, writes the answer.
+
+Status: **skeleton** (0.0.1). The query-plane Web API is complete as a contract and runs on an
+in-memory demo engine. The real index (PostgreSQL + pgvector + PGroonga, embeddings from
+OumiGo's `/v1/embeddings`), ingestion and the admin CLI are still to come.
+
+## Run
+
+```sh
+uv venv --python 3.12 && uv pip install -e '.[dev]'
+.venv/bin/smartrag serve --demo --no-auth          # http://127.0.0.1:8710/docs
+curl -s 'http://127.0.0.1:8710/v1/search?q=有給休暇の繰り越し' | python3 -m json.tool
+.venv/bin/pytest
+```
+
+`--no-auth` is refused unless the server binds a loopback address. Otherwise clients send
+`Authorization: Bearer <key>`, checked against the hashed key file `SMARTRAG_API_KEYS_FILE`:
+
+```json
+[{"key_id": "ui-search", "sha256": "<sha256 of the key>", "role": "reader", "delegate": true}]
+```
+
+## Web API (query plane)
+
+| Method & path | Purpose |
+|---|---|
+| `GET /v1/sources` | What is indexed, filterable fields, freshness (no URIs, no credentials) |
+| `POST /v1/search` | Natural-language search: snippets, ids, citations; filters, cursors, facets |
+| `GET /v1/search?q=` | The same for the search box: one result per document, bookmarkable |
+| `GET /v1/chunks/{chunk_id}` | Read with `scope=chunk\|neighbors\|section\|document`, paged by `max_chars` |
+| `GET /v1/documents/{doc_id}` | Metadata and outline; text in pages with `include=text` |
+| `POST /v1/feedback` | `click` / `relevant` / `irrelevant` for a `query_id` |
+| `GET /healthz`, `/readyz`, `/version` | Ops (no auth) |
+
+- Errors always look like `{"error": {"code", "message", "details"}}`.
+- A chunk from an older document version returns `410 chunk_superseded`, with the current version.
+- `X-SmartRAG-On-Behalf-Of: <user>` names the end user (keys with `delegate` only).
+
+Admin operations (sources, sync, jobs, index, query logs, API keys, eval) are **not** part of
+the Web API by design: they run through the `smartrag` CLI on the operator host, and the
+query server holds no source credentials.
+
+## Layout
+
+```
+src/smartrag/
+  models.py        request/response schemas (the contract)
+  errors.py        errors with stable codes
+  paging.py        opaque cursors bound to their request
+  engine/          RetrievalEngine protocol; in-memory engine + demo corpus
+  api/             FastAPI app: query routes, ops routes, auth, error shape
+  cli/             `smartrag serve` (admin commands to come)
+```

smartrag-0.0.1/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "smartrag"
+dynamic = ["version"]
+description = "A knowledge source any agent can use: search returns evidence with citations, the agent writes the answer."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "GOTOAI" }]
+keywords = ["rag", "retrieval", "search", "agents", "mcp", "embeddings"]
+# TODO: choose the licence (open framework vs commercial implementation) and add
+# `license = "..."` + `license-files = ["LICENSE"]`.
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "pydantic>=2",
+    "pydantic-settings>=2",
+    "fastapi>=0.110",    # the query-plane Web API
+    "uvicorn>=0.29",
+    "typer>=0.12",       # single CLI: serve now; admin commands (source, jobs, apikey, ...) later
+]
+
+[project.urls]
+Homepage = "https://github.com/gotoai/smartrag"
+Repository = "https://github.com/gotoai/smartrag"
+Issues = "https://github.com/gotoai/smartrag/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "httpx2>=2",         # FastAPI's TestClient (Starlette deprecated plain httpx for it)
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+smartrag = "smartrag.cli.main:main"
+
+[tool.hatch.version]
+path = "src/smartrag/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/smartrag"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint.flake8-bugbear]
+# FastAPI / typer declare parameters through calls in defaults; that is their idiom.
+extend-immutable-calls = [
+    "fastapi.Depends", "fastapi.Query", "fastapi.Path", "fastapi.Header", "typer.Option",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

smartrag-0.0.1/src/smartrag/__about__.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version (read by hatch at build time)."""
+
+__version__ = "0.0.1"

smartrag-0.0.1/src/smartrag/__init__.py

@@ -0,0 +1,10 @@
+"""Smart RAG — a knowledge source any agent can use.
+
+Search returns evidence (snippets, stable ids, citations); the agent, or a person at the
+search box, writes the answer. See `smartrag.api` for the query-plane Web API and
+`smartrag.engine` for the retrieval-engine seam behind it.
+"""
+
+from smartrag.__about__ import __version__
+
+__all__ = ["__version__"]

smartrag-0.0.1/src/smartrag/__main__.py

@@ -0,0 +1,3 @@
+from smartrag.cli.main import main
+
+main()

smartrag-0.0.1/src/smartrag/api/__init__.py

@@ -0,0 +1,5 @@
+"""The query-plane Web API (endpoints 1–6 and ops)."""
+
+from smartrag.api.app import create_app
+
+__all__ = ["create_app"]

smartrag-0.0.1/src/smartrag/api/app.py

@@ -0,0 +1,42 @@
+"""Build the query-plane FastAPI app around a `RetrievalEngine`."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from smartrag.__about__ import __version__
+from smartrag.api import ops, query
+from smartrag.api.auth import FileKeyStore, KeyStore
+from smartrag.api.errors import install_error_handlers
+from smartrag.engine.base import RetrievalEngine
+from smartrag.settings import Settings
+
+
+def create_app(
+    engine: RetrievalEngine,
+    settings: Settings | None = None,
+    key_store: KeyStore | None = None,
+) -> FastAPI:
+    """The Smart RAG Web API (query plane only).
+
+    Auth: `key_store` if given, else the hashed key file `settings.api_keys_file`. With
+    neither, the app refuses to start unless `settings.auth_disabled` is set — an
+    unauthenticated server is never the silent default.
+    """
+    settings = settings or Settings()
+    if key_store is None and not settings.auth_disabled:
+        if settings.api_keys_file is None:
+            raise ValueError("no API keys configured: set SMARTRAG_API_KEYS_FILE "
+                             "(or auth_disabled for local development)")
+        key_store = FileKeyStore(settings.api_keys_file)
+
+    app = FastAPI(title="Smart RAG", version=__version__,
+                  description="Search returns evidence with citations; the agent writes "
+                              "the answer.")
+    app.state.engine = engine
+    app.state.settings = settings
+    app.state.key_store = None if settings.auth_disabled else key_store
+    install_error_handlers(app)
+    app.include_router(query.router)
+    app.include_router(ops.router)
+    return app

smartrag-0.0.1/src/smartrag/api/auth.py

@@ -0,0 +1,115 @@
+"""API-key authentication and the end-user identity slot.
+
+Clients send `Authorization: Bearer <api key>`. Keys are stored hashed (SHA-256) in a
+JSON file that the CLI writes, so the query server never holds a plaintext key:
+
+    [{"key_id": "ui-search", "sha256": "<hex>", "role": "reader", "delegate": true}]
+
+The file is re-read when it changes, so a key issued or revoked by the CLI takes effect
+without restarting the server.
+
+`X-SmartRAG-On-Behalf-Of: <user id>` names the end user an agent or UI acts for
+(CommonRAG P2). Only keys with `delegate: true` may send it; v1 logs it and passes it to
+the engine, and document permissions will use it later.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Protocol
+
+from fastapi import Header, Request
+
+from smartrag.engine.base import RequestContext
+from smartrag.errors import Forbidden, Unauthorized
+
+log = logging.getLogger("smartrag.api.auth")
+
+ON_BEHALF_OF_HEADER = "X-SmartRAG-On-Behalf-Of"
+
+Role = Literal["reader", "admin"]
+
+
+@dataclass(frozen=True)
+class Principal:
+    key_id: str
+    role: Role
+    delegate: bool = False
+
+
+ANONYMOUS = Principal(key_id="anonymous", role="reader", delegate=True)
+
+
+def hash_key(key: str) -> str:
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+class KeyStore(Protocol):
+    def authenticate(self, key: str) -> Principal | None: ...
+
+
+class FileKeyStore:
+    """Hashed keys from a JSON file, reloaded when the file's mtime changes."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+        self._lock = threading.Lock()
+        self._mtime: float | None = None
+        self._entries: list[tuple[str, Principal]] = []
+        self._reload()
+
+    def _reload(self) -> None:
+        mtime = self.path.stat().st_mtime
+        if mtime == self._mtime:
+            return
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+            entries = [(str(e["sha256"]).lower(),
+                        Principal(key_id=str(e["key_id"]), role=e.get("role", "reader"),
+                                  delegate=bool(e.get("delegate", False))))
+                       for e in raw]
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            raise ValueError(f"invalid API key file {self.path}: {exc}") from exc
+        self._entries, self._mtime = entries, mtime
+        log.info("loaded %d API keys from %s", len(entries), self.path)
+
+    def authenticate(self, key: str) -> Principal | None:
+        with self._lock:
+            try:
+                self._reload()
+            except (OSError, ValueError):
+                log.exception("cannot reload %s; keeping the previous keys", self.path)
+        digest = hash_key(key)
+        match = None
+        for stored, principal in self._entries:  # compare all: no early exit on timing
+            if hmac.compare_digest(stored, digest):
+                match = principal
+        return match
+
+
+async def request_context(
+    request: Request,
+    authorization: str | None = Header(default=None),
+    on_behalf_of: str | None = Header(default=None, alias=ON_BEHALF_OF_HEADER),
+) -> RequestContext:
+    """FastAPI dependency: authenticate the caller and build the engine's context."""
+    store: KeyStore | None = request.app.state.key_store
+    if store is None:  # auth disabled (development)
+        principal = ANONYMOUS
+    else:
+        scheme, _, key = (authorization or "").partition(" ")
+        if scheme.lower() != "bearer" or not key.strip():
+            raise Unauthorized("an API key is required: Authorization: Bearer <key>")
+        found = store.authenticate(key.strip())
+        if found is None:
+            raise Unauthorized("the API key is not valid")
+        principal = found
+    if on_behalf_of is not None and not principal.delegate:
+        raise Forbidden(f"this API key may not act on behalf of users ({ON_BEHALF_OF_HEADER})")
+    return RequestContext(key_id=principal.key_id, on_behalf_of=on_behalf_of or None)

smartrag-0.0.1/src/smartrag/api/errors.py

@@ -0,0 +1,57 @@
+"""One error shape for every failure: `{"error": {"code", "message", "details"}}`.
+
+Validation errors are `400 invalid_request` (not FastAPI's default 422), unknown paths
+`404 not_found`, and unexpected exceptions `500 internal_error` with a generic message
+(the traceback goes to the log, never to the client).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from smartrag.errors import EmbedderUnavailable, SmartRAGError, Unauthorized
+
+log = logging.getLogger("smartrag.api")
+
+_HTTP_CODES = {404: "not_found", 405: "method_not_allowed"}
+
+
+def error_response(status: int, code: str, message: str,
+                   details: dict[str, Any] | None = None,
+                   headers: dict[str, str] | None = None) -> JSONResponse:
+    body = {"error": {"code": code, "message": message, "details": details or {}}}
+    return JSONResponse(body, status_code=status, headers=headers)
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    @app.exception_handler(SmartRAGError)
+    async def _smartrag_error(_: Request, exc: SmartRAGError) -> JSONResponse:
+        headers = None
+        if isinstance(exc, Unauthorized):
+            headers = {"WWW-Authenticate": "Bearer"}
+        elif isinstance(exc, EmbedderUnavailable) and exc.retry_after:
+            headers = {"Retry-After": str(exc.retry_after)}
+        return error_response(exc.status, exc.code, exc.message, exc.details, headers)
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation_error(_: Request, exc: RequestValidationError) -> JSONResponse:
+        errors = [{"loc": list(e.get("loc", ())), "msg": e.get("msg", ""),
+                   "type": e.get("type", "")} for e in exc.errors()]
+        return error_response(400, "invalid_request", "the request is not valid",
+                              {"errors": errors})
+
+    @app.exception_handler(StarletteHTTPException)
+    async def _http_error(_: Request, exc: StarletteHTTPException) -> JSONResponse:
+        code = _HTTP_CODES.get(exc.status_code, "http_error")
+        return error_response(exc.status_code, code, str(exc.detail))
+
+    @app.exception_handler(Exception)
+    async def _unexpected(request: Request, exc: Exception) -> JSONResponse:
+        log.exception("unhandled error on %s %s", request.method, request.url.path)
+        return error_response(500, "internal_error", "an internal error occurred")

smartrag-0.0.1/src/smartrag/api/ops.py

@@ -0,0 +1,39 @@
+"""Ops endpoints (13), unauthenticated so probes and load balancers can call them.
+
+    GET /healthz   liveness: the process answers
+    GET /readyz    readiness: the index and the embedder can serve (503 otherwise)
+    GET /version   package and API version
+
+They reveal no data: `/readyz` reports check names and short details only.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+from smartrag.__about__ import __version__
+from smartrag.models import ReadinessResponse, VersionResponse
+
+router = APIRouter()
+
+
+@router.get("/healthz")
+async def healthz() -> dict[str, str]:
+    """liveness"""
+    return {"status": "ok"}
+
+
+@router.get("/readyz", response_model=ReadinessResponse,
+            responses={503: {"model": ReadinessResponse}})
+async def readyz(request: Request) -> JSONResponse:
+    """readiness of the index and the embedder"""
+    readiness: ReadinessResponse = await request.app.state.engine.readiness()
+    return JSONResponse(readiness.model_dump(mode="json"),
+                        status_code=200 if readiness.ready else 503)
+
+
+@router.get("/version", response_model=VersionResponse)
+async def version() -> VersionResponse:
+    """package and API version"""
+    return VersionResponse(version=__version__)

smartrag-0.0.1/src/smartrag/api/query.py

@@ -0,0 +1,154 @@
+"""Query-plane endpoints 1–6: the only operations agents, the UI and MCP get.
+
+    GET  /v1/sources               describe_sources
+    POST /v1/search                search (canonical form)
+    GET  /v1/search?q=             search for the search box (bookmarkable URLs)
+    GET  /v1/chunks/{chunk_id}     read: chunk -> neighbours -> section -> document
+    GET  /v1/documents/{doc_id}    metadata, outline, text in pages
+    POST /v1/feedback              click / relevant / irrelevant
+
+Admin operations (sources, sync, jobs, index, query logs, API keys) are not here by
+design: they run through the CLI on the operator host.
+
+Every search is logged with its `query_id` (the server-side query log, CommonRAG P3),
+so a wrong answer can be traced to retrieval or to the agent.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import uuid
+from typing import Literal
+
+from fastapi import APIRouter, Depends, Path, Query, Request
+
+from smartrag.api.auth import request_context
+from smartrag.engine.base import RequestContext, RetrievalEngine
+from smartrag.models import (
+    DocumentResponse,
+    FeedbackRequest,
+    FeedbackResponse,
+    ReadResponse,
+    ReadScope,
+    SearchFilters,
+    SearchRequest,
+    SearchResponse,
+    SourcesResponse,
+)
+from smartrag.paging import encode_cursor, search_binding
+
+log = logging.getLogger("smartrag.query")
+
+router = APIRouter(prefix="/v1", dependencies=[Depends(request_context)])
+
+
+def _engine(request: Request) -> RetrievalEngine:
+    return request.app.state.engine
+
+
+def _document_link(request: Request, doc_id: str, page: int | None) -> str:
+    base = request.app.state.settings.public_base_url or str(request.base_url)
+    link = f"{base.rstrip('/')}/v1/documents/{doc_id}"
+    return f"{link}?page={page}" if page is not None else link
+
+
+@router.get("/sources", response_model=SourcesResponse, response_model_exclude_none=True)
+async def describe_sources(
+    request: Request, ctx: RequestContext = Depends(request_context)
+) -> SourcesResponse:
+    """what is indexed, which fields can be filtered, and how fresh it is"""
+    return await _engine(request).describe_sources(ctx)
+
+
+@router.post("/search", response_model=SearchResponse, response_model_exclude_none=True)
+async def search(
+    body: SearchRequest, request: Request, ctx: RequestContext = Depends(request_context)
+) -> SearchResponse:
+    """search with a natural-language query; returns evidence with citations"""
+    return await _search(body, request, ctx)
+
+
+@router.get("/search", response_model=SearchResponse, response_model_exclude_none=True)
+async def search_get(
+    request: Request,
+    q: str = Query(min_length=1, max_length=2000),
+    source: list[str] | None = Query(default=None),
+    type: list[str] | None = Query(default=None),  # the URL's own name
+    limit: int = Query(default=10, ge=1, le=50),
+    page: int = Query(default=1, ge=1, le=100),
+    ctx: RequestContext = Depends(request_context),
+) -> SearchResponse:
+    """search for the search box: one result per document, highlights on"""
+    filters = SearchFilters(source_id=source, file_type=type) if (source or type) else None
+    body = SearchRequest(query=q, filters=filters, limit=limit, group_by="document",
+                         include=["highlights"])
+    if page > 1:
+        body.cursor = encode_cursor((page - 1) * limit, search_binding(body))
+    return await _search(body, request, ctx)
+
+
+async def _search(body: SearchRequest, request: Request, ctx: RequestContext) -> SearchResponse:
+    query_id = f"q_{uuid.uuid4().hex}"
+    started = time.perf_counter()
+    response = await _engine(request).search(body, ctx, query_id)
+    response.took_ms = round((time.perf_counter() - started) * 1000)
+    for result in response.results:
+        result.citation.link = _document_link(request, result.doc_id, result.citation.page)
+    log.info("search %s", json.dumps({
+        "query_id": query_id,
+        "key_id": ctx.key_id,
+        "on_behalf_of": ctx.on_behalf_of,
+        "query": body.query,
+        "filters": body.filters.model_dump(mode="json", exclude_none=True)
+        if body.filters else None,
+        "mode": body.mode,
+        "group_by": body.group_by,
+        "results": [r.chunk_id for r in response.results],
+        "took_ms": response.took_ms,
+    }, ensure_ascii=False))
+    return response
+
+
+@router.get("/chunks/{chunk_id}", response_model=ReadResponse, response_model_exclude_none=True)
+async def read_chunk(
+    request: Request,
+    chunk_id: str = Path(max_length=200),
+    scope: ReadScope = "chunk",
+    window: int = Query(default=1, ge=0, le=5),
+    max_chars: int = Query(default=8000, ge=500, le=50000),
+    cursor: str | None = None,
+    ctx: RequestContext = Depends(request_context),
+) -> ReadResponse:
+    """read a chunk, widened to its neighbours, section or whole document"""
+    response = await _engine(request).read_chunk(chunk_id, scope, window, max_chars, cursor, ctx)
+    response.citation.link = _document_link(request, response.doc_id, response.citation.page)
+    return response
+
+
+@router.get("/documents/{doc_id}", response_model=DocumentResponse,
+            response_model_exclude_none=True)
+async def get_document(
+    request: Request,
+    doc_id: str = Path(max_length=100),
+    include: list[Literal["text"]] = Query(default=[]),
+    section: str | None = Query(default=None, max_length=50),
+    max_chars: int = Query(default=8000, ge=500, le=50000),
+    cursor: str | None = None,
+    ctx: RequestContext = Depends(request_context),
+) -> DocumentResponse:
+    """document metadata and outline; text in pages with include=text"""
+    response = await _engine(request).get_document(
+        doc_id, "text" in include, section, max_chars, cursor, ctx)
+    response.link = _document_link(request, response.doc_id, None)
+    return response
+
+
+@router.post("/feedback", status_code=202, response_model=FeedbackResponse)
+async def feedback(
+    body: FeedbackRequest, request: Request, ctx: RequestContext = Depends(request_context)
+) -> FeedbackResponse:
+    """record whether a result was clicked, relevant or irrelevant"""
+    await _engine(request).record_feedback(body, ctx)
+    return FeedbackResponse()