smartrag 0.0.1__py3-none-any.whl

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/__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/__main__.py

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

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/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/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/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/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/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()

smartrag/cli/main.py

@@ -0,0 +1,78 @@
+"""The `smartrag` CLI.
+
+Now: `serve` (the query-plane Web API) and `version`. Admin commands — `source`, `jobs`,
+`docs`, `index`, `logs`, `apikey`, `eval` — will be added here: by design, admin runs
+through the CLI on the operator host, never through the Web API.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+from pathlib import Path
+
+import typer
+
+from smartrag.__about__ import __version__
+
+app = typer.Typer(help="Smart RAG: a knowledge source any agent can use.",
+                  no_args_is_help=True, add_completion=False)
+
+
+def _is_loopback(host: str) -> bool:
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+@app.command()
+def serve(
+    host: str = typer.Option(None, help="Bind address [default: $SMARTRAG_HOST or 127.0.0.1]"),
+    port: int = typer.Option(None, help="Port [default: $SMARTRAG_PORT or 8710]"),
+    api_keys_file: Path = typer.Option(None, help="Hashed API key file "
+                                                  "[default: $SMARTRAG_API_KEYS_FILE]"),
+    demo: bool = typer.Option(False, help="Serve the built-in in-memory demo corpus."),
+    no_auth: bool = typer.Option(False, help="Disable API keys (loopback only, development)."),
+    log_level: str = typer.Option("info"),
+) -> None:
+    """Run the query-plane Web API."""
+    import uvicorn
+
+    from smartrag.api import create_app
+    from smartrag.engine import demo_engine
+    from smartrag.settings import Settings
+
+    overrides = {k: v for k, v in {"host": host, "port": port,
+                                   "api_keys_file": api_keys_file}.items() if v is not None}
+    if no_auth:
+        overrides["auth_disabled"] = True
+    settings = Settings(**overrides)
+    if settings.auth_disabled and not _is_loopback(settings.host):
+        raise typer.BadParameter(f"--no-auth is only allowed on a loopback address, not "
+                                 f"{settings.host}", param_hint="--no-auth")
+    if not demo:
+        # TODO: build the PostgreSQL engine from settings once the index exists.
+        typer.echo("smartrag: no index backend is implemented yet; run with --demo", err=True)
+        raise typer.Exit(2)
+
+    logging.basicConfig(level=log_level.upper(),
+                        format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    try:
+        web_app = create_app(demo_engine(), settings)
+    except ValueError as exc:
+        typer.echo(f"smartrag: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    uvicorn.run(web_app, host=settings.host, port=settings.port, log_level=log_level)
+
+
+@app.command()
+def version() -> None:
+    """Print the version."""
+    typer.echo(__version__)
+
+
+def main() -> None:
+    app()

smartrag/engine/__init__.py

@@ -0,0 +1,7 @@
+"""Retrieval engines behind the query-plane API."""
+
+from smartrag.engine.base import RequestContext, RetrievalEngine
+from smartrag.engine.demo import demo_engine
+from smartrag.engine.memory import InMemoryEngine
+
+__all__ = ["InMemoryEngine", "RequestContext", "RetrievalEngine", "demo_engine"]

smartrag/engine/base.py

@@ -0,0 +1,78 @@
+"""The retrieval-engine seam: what the query-plane API needs from an index.
+
+The Web API depends only on this protocol. The v1 engine (PostgreSQL + pgvector +
+PGroonga, query embeddings from OumiGo's `/v1/embeddings`) and the in-memory demo engine
+both implement it, so the API never changes when the engine does.
+
+Every call receives a `RequestContext`: who is calling (the API key) and, optionally, on
+whose behalf (the end user, CommonRAG P2). v1 engines only log `on_behalf_of`; document
+permissions will use it later without an interface change.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from smartrag.models import (
+    DocumentResponse,
+    FeedbackRequest,
+    ReadinessResponse,
+    ReadResponse,
+    ReadScope,
+    SearchRequest,
+    SearchResponse,
+    SourcesResponse,
+)
+
+
+@dataclass(frozen=True)
+class RequestContext:
+    key_id: str
+    on_behalf_of: str | None = None
+
+
+class RetrievalEngine(Protocol):
+    async def describe_sources(self, ctx: RequestContext) -> SourcesResponse:
+        """What is indexed, which fields can be filtered, how fresh it is."""
+        ...
+
+    async def search(
+        self, request: SearchRequest, ctx: RequestContext, query_id: str
+    ) -> SearchResponse:
+        """Ranked evidence for a natural-language query. `query_id` is issued by the
+        API; the engine records it so feedback can refer to this search."""
+        ...
+
+    async def read_chunk(
+        self,
+        chunk_id: str,
+        scope: ReadScope,
+        window: int,
+        max_chars: int,
+        cursor: str | None,
+        ctx: RequestContext,
+    ) -> ReadResponse:
+        """A chunk widened to `scope`. Raises `NotFound`, or `ChunkSuperseded` for a
+        chunk of an older document version."""
+        ...
+
+    async def get_document(
+        self,
+        doc_id: str,
+        include_text: bool,
+        section: str | None,
+        max_chars: int,
+        cursor: str | None,
+        ctx: RequestContext,
+    ) -> DocumentResponse:
+        """Document metadata and outline; text (paged) with `include_text`."""
+        ...
+
+    async def record_feedback(self, feedback: FeedbackRequest, ctx: RequestContext) -> None:
+        """Store a relevance signal. Raises `NotFound` for an unknown `query_id`."""
+        ...
+
+    async def readiness(self) -> ReadinessResponse:
+        """Whether the index and the embedder can serve queries."""
+        ...

smartrag/engine/demo.py

@@ -0,0 +1,69 @@
+"""A small demo corpus: company rules and an expense manual (Japanese), a product README
+(English), across two sources. Used by `smartrag serve --demo` and the API tests."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from smartrag.engine.memory import Chunk, Document, InMemoryEngine, Source
+
+_SYNCED = datetime(2026, 11, 8, 3, 0, tzinfo=timezone.utc)
+
+
+def demo_engine() -> InMemoryEngine:
+    leave = ("第5章 休暇", "第22条 年次有給休暇")
+    return InMemoryEngine(
+        sources=[
+            Source("nas-kitei", "社内規程", "smb", _SYNCED),
+            Source("s3-manuals", "製品マニュアル", "s3", _SYNCED),
+        ],
+        documents=[
+            Document(
+                source_id="nas-kitei",
+                path="就業規則/就業規則.pdf",
+                title="就業規則",
+                file_type="pdf",
+                version=3,
+                modified_at=datetime(2026, 4, 1, tzinfo=timezone.utc),
+                chunks=[
+                    Chunk("年次有給休暇は、入社後6か月間継続勤務し、所定労働日の8割以上出勤した"
+                          "従業員に10日付与する。", leave, 14),
+                    Chunk("年次有給休暇は、翌年度に限り最大20日まで繰り越すことができる。"
+                          "繰り越した休暇は、当年度に付与された休暇より先に取得したものとみなす。",
+                          leave, 14),
+                    Chunk("従業員が結婚するときは5日、配偶者が出産するときは3日の特別休暇を与える。",
+                          ("第5章 休暇", "第23条 特別休暇"), 15),
+                    Chunk("従業員は、会社の許可を得た場合に限り、副業を行うことができる。",
+                          ("第6章 服務", "第30条 副業"), 18),
+                ],
+            ),
+            Document(
+                source_id="nas-kitei",
+                path="経理/経費精算マニュアル.docx",
+                title="経費精算マニュアル",
+                file_type="docx",
+                version=1,
+                modified_at=datetime(2025, 10, 15, tzinfo=timezone.utc),
+                chunks=[
+                    Chunk("経費は発生から30日以内に経費精算システムで申請する。"
+                          "領収書の画像を必ず添付すること。", ("1. 申請の流れ",)),
+                    Chunk("出張の交通費は最も経済的な経路で計算する。"
+                          "新幹線のグリーン車は部長以上に限り利用できる。", ("2. 交通費",)),
+                ],
+            ),
+            Document(
+                source_id="s3-manuals",
+                path="gotobox/README.md",
+                title="GotoBox Quick Start",
+                file_type="md",
+                version=2,
+                modified_at=datetime(2026, 9, 1, tzinfo=timezone.utc),
+                chunks=[
+                    Chunk("GotoBox connects to your file server and indexes documents "
+                          "every night at 3:00.", ("Quick Start",)),
+                    Chunk("If indexing fails, check that the service account can read the "
+                          "shared folder.", ("Quick Start", "Troubleshooting")),
+                ],
+            ),
+        ],
+    )