exactdocs 0.1.0__py3-none-any.whl

exactdocs/retrieval/adapters/driving/http.py

@@ -0,0 +1,17 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+
+from exactdocs.retrieval.dtos import SearchDocsQuery, SearchDocsResult
+from exactdocs.retrieval.ports.driving import SearchDocs
+
+
+def build_router(*, search_docs: SearchDocs) -> APIRouter:
+    """Expose retrieval under ``/search``."""
+    router = APIRouter(prefix="/search", tags=["retrieval"])
+
+    @router.get("")
+    async def search(query: Annotated[SearchDocsQuery, Query()]) -> SearchDocsResult:
+        return await search_docs(query)
+
+    return router

exactdocs/retrieval/adapters/driving/mcp.py

@@ -0,0 +1,28 @@
+"""MCP adapter for retrieval. All tools are read-only."""
+
+from typing import Annotated
+
+from fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from exactdocs.retrieval.dtos import SearchDocsQuery, SearchDocsResult
+from exactdocs.retrieval.ports.driving import SearchDocs
+
+READ_ONLY = ToolAnnotations(read_only_hint=True)
+
+
+def register_tools(mcp: FastMCP, *, search_docs: SearchDocs) -> None:
+    """Register retrieval's MCP tools on ``mcp``."""
+
+    @mcp.tool(name="search_docs", annotations=READ_ONLY)
+    async def search_docs_tool(
+        library: Annotated[str, Field(description="Library name, e.g. 'react'")],
+        version: Annotated[str, Field(description="Exact indexed version, e.g. '19.1'")],
+        query: Annotated[str, Field(description="Identifier, error message or question")],
+        limit: Annotated[int, Field(ge=1, le=50)] = 5,
+    ) -> SearchDocsResult:
+        """Search one library version. Returns verbatim excerpts with source URLs."""
+        return await search_docs(
+            SearchDocsQuery(library=library, version=version, query=query, limit=limit)
+        )

exactdocs/retrieval/dtos.py

@@ -0,0 +1,53 @@
+"""Data crossing the retrieval boundary. Immutable, validated."""
+
+from collections.abc import Iterable
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from exactdocs.retrieval.models import Excerpt
+
+
+class _Dto(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class SearchDocsQuery(_Dto):
+    """Search within exactly one library version."""
+
+    library: str = Field(min_length=1)
+    version: str = Field(min_length=1)
+    query: str = Field(min_length=1)
+    limit: int = Field(default=5, ge=1, le=50)
+
+
+class ExcerptOut(_Dto):
+    """One verbatim excerpt with its provenance."""
+
+    text: str
+    source_url: str
+    library: str
+    version: str
+    commit_sha: str | None
+
+    @classmethod
+    def from_model(cls, excerpt: Excerpt) -> Self:
+        """Map a domain value object to its boundary representation."""
+        return cls(
+            text=excerpt.text,
+            source_url=excerpt.source_url,
+            library=excerpt.target.library,
+            version=excerpt.target.version,
+            commit_sha=excerpt.commit_sha,
+        )
+
+
+class SearchDocsResult(_Dto):
+    """Excerpts ordered from most to least relevant."""
+
+    excerpts: list[ExcerptOut]
+
+    @classmethod
+    def from_models(cls, excerpts: Iterable[Excerpt]) -> Self:
+        """Map domain value objects, keeping their order."""
+        return cls(excerpts=[ExcerptOut.from_model(e) for e in excerpts])

exactdocs/retrieval/errors.py

@@ -0,0 +1,17 @@
+from exactdocs_kernel import NotFoundError, ValidationError
+
+
+class EmptySearchTextError(ValidationError):
+    """The search text is blank."""
+
+    def __init__(self) -> None:
+        super().__init__("search text must not be empty")
+
+
+class VersionNotIndexedError(NotFoundError):
+    """There is no index for this exact library version, so there is no answer."""
+
+    def __init__(self, library: str, version: str) -> None:
+        super().__init__(f"no index for {library}@{version}")
+        self.library = library
+        self.version = version

exactdocs/retrieval/models.py

@@ -0,0 +1,34 @@
+"""Retrieval value objects. Pure Python: no frameworks, no I/O."""
+
+from dataclasses import dataclass
+
+from exactdocs.retrieval.errors import EmptySearchTextError
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DocTarget:
+    """The exact library version a search is pinned to. Version is a hard filter."""
+
+    library: str
+    version: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SearchText:
+    """What the agent is looking for: an identifier, an error code or a question."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not self.value.strip():
+            raise EmptySearchTextError
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Excerpt:
+    """Original documentation text, never a summary, with where it came from."""
+
+    text: str
+    source_url: str
+    target: DocTarget
+    commit_sha: str | None = None

exactdocs/retrieval/module.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+from typing import Self
+
+from exactdocs.retrieval.ports.driven import ExcerptIndex, IndexedVersions
+from exactdocs.retrieval.ports.driving import SearchDocs
+from exactdocs.retrieval.use_cases import SearchDocsUseCase
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RetrievalModule:
+    """Retrieval's driving ports, ready to be exposed by driving adapters."""
+
+    search_docs: SearchDocs
+
+    @classmethod
+    def build(cls, *, versions: IndexedVersions, index: ExcerptIndex) -> Self:
+        """Assemble the use cases around the given driven adapters."""
+        return cls(search_docs=SearchDocsUseCase(versions, index))

exactdocs/retrieval/ports/__init__.py

@@ -0,0 +1,4 @@
+from exactdocs.retrieval.ports.driven import ExcerptIndex, IndexedVersions
+from exactdocs.retrieval.ports.driving import SearchDocs
+
+__all__ = ["ExcerptIndex", "IndexedVersions", "SearchDocs"]

exactdocs/retrieval/ports/driven.py

@@ -0,0 +1,26 @@
+"""Driven (secondary) ports of retrieval."""
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from exactdocs.retrieval.models import DocTarget, Excerpt, SearchText
+
+
+class IndexedVersions(Protocol):
+    """Which library versions have an index.
+
+    The catalog domain owns this knowledge. Retrieval states what it needs in its own terms
+    and the composition root plugs in an adapter, so neither domain imports the other.
+    """
+
+    async def is_indexed(self, target: DocTarget) -> bool:
+        """Return ``True`` only for an exact library and version match."""
+        ...
+
+
+class ExcerptIndex(Protocol):
+    """Search backend (BM25 + vectors + rerank) scoped to one library version."""
+
+    async def search(self, target: DocTarget, text: SearchText, limit: int) -> Sequence[Excerpt]:
+        """Return at most ``limit`` excerpts from ``target`` only, best first."""
+        ...

exactdocs/retrieval/ports/driving.py

@@ -0,0 +1,13 @@
+"""Driving (primary) ports of retrieval."""
+
+from typing import Protocol
+
+from exactdocs.retrieval.dtos import SearchDocsQuery, SearchDocsResult
+
+
+class SearchDocs(Protocol):
+    """Hybrid search within one library version; raises ``VersionNotIndexedError``."""
+
+    async def __call__(self, query: SearchDocsQuery) -> SearchDocsResult:
+        """Run the use case."""
+        ...

exactdocs/retrieval/use_cases.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+
+from exactdocs.retrieval.dtos import SearchDocsQuery, SearchDocsResult
+from exactdocs.retrieval.errors import VersionNotIndexedError
+from exactdocs.retrieval.models import DocTarget, SearchText
+from exactdocs.retrieval.ports.driven import ExcerptIndex, IndexedVersions
+
+
+@dataclass(frozen=True, slots=True)
+class SearchDocsUseCase:
+    """Implements ``ports.driving.SearchDocs``."""
+
+    versions: IndexedVersions
+    index: ExcerptIndex
+
+    async def __call__(self, query: SearchDocsQuery) -> SearchDocsResult:
+        """Search one exact version; never fall back to another version."""
+        target = DocTarget(library=query.library, version=query.version)
+        if not await self.versions.is_indexed(target):
+            raise VersionNotIndexedError(target.library, target.version)
+        excerpts = await self.index.search(target, SearchText(value=query.query), query.limit)
+        return SearchDocsResult.from_models(excerpts)

exactdocs-0.1.0.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.5
+Name: exactdocs
+Version: 0.1.0
+Summary: Self-hosted, version-accurate documentation for AI coding agents (MCP server).
+Project-URL: Repository, https://github.com/SirCypkowskyy/ExactDocs
+Project-URL: Issues, https://github.com/SirCypkowskyy/ExactDocs/issues
+Author: Cyprian Gburek
+License-Expression: Apache-2.0
+Keywords: ai-agents,documentation,fastmcp,mcp,rag
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: cyclopts>=4
+Requires-Dist: exactdocs-kernel==0.1.0
+Requires-Dist: fastapi>=0.120
+Requires-Dist: fastmcp>=4
+Requires-Dist: mcp>=2
+Requires-Dist: pydantic-settings>=2.11
+Requires-Dist: pydantic>=2.12
+Requires-Dist: uvicorn[standard]>=0.38
+Description-Content-Type: text/markdown
+
+# exactdocs
+
+Self-hosted, version-accurate documentation for AI coding agents: an MCP server that serves
+the right docs for the right library version, verbatim and with sources.
+
+```bash
+uvx exactdocs serve            # HTTP: web UI + MCP on http://localhost:3000
+uvx exactdocs serve --stdio    # MCP over stdio
+```
+
+See the [project README](https://github.com/SirCypkowskyy/ExactDocs) for the full documentation.

exactdocs-0.1.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+exactdocs/__init__.py,sha256=ZyWSa5dAmFbfc0TjKWhLJBcrryu1r_VmBOkF37IpkUw,154
+exactdocs/__main__.py,sha256=ssz-NB4QDdynBs1NQKemNmA7m6Qa5FBNfceppQteRJg,49
+exactdocs/_version.py,sha256=auPWjG7MmNQBtyjHzThYGqLlFuaGHu8gyxB7V7-GqvM,218
+exactdocs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exactdocs/_web/index.html,sha256=qfdyFgXtPPRcBaW1lj4kwVvq7UT4l80uZWtHY6owjSI,394
+exactdocs/_web/assets/index-B350HwjP.js,sha256=xWKuZGMqGuK7_lOFM3oaxffCYQoKzh0CHfU991MIS8Q,366751
+exactdocs/_web/assets/index-CG8rwfz9.css,sha256=foha27uzVRpwi61OcHwCGko46dODPxeFh4UlTWGJlb0,18144
+exactdocs/_web/assets/routes-CCGZxbYl.js,sha256=WYFRFl7Rr2wfuVmqL3NGVtZduzSxr6rgTlCuI15lmTw,71
+exactdocs/bootstrap/__init__.py,sha256=XG_MBkV1HgArcX61rCLHrAFFv3ShMmi-KzpqJX4neJY,192
+exactdocs/bootstrap/bridges.py,sha256=hUcvDHsCKTpMcQJBWaHIWE1tVyZ2i0ZMewR6xFugmr8,1018
+exactdocs/bootstrap/cli.py,sha256=BghXcWdv5ias-ebZPmLH46sj_nM73kJToOHzWQB9wuw,1327
+exactdocs/bootstrap/container.py,sha256=xs5UHI7IcgZiYSbrgEko9t2I9V0lpH5VAhwk7SWsnWI,1092
+exactdocs/bootstrap/http.py,sha256=Fs6E3YWovNlhbqTnaKwNxDkg70rPFAp0x3BKRzvMuho,3349
+exactdocs/bootstrap/mcp.py,sha256=EvoJiroS6fWHldTlKOM2z7qL2nIdI87cRkld7tHCX8A,858
+exactdocs/bootstrap/settings.py,sha256=8-NLbcusqgdvmL2yHvUdjdv75n_EDef8onrtTofbwT8,533
+exactdocs/catalog/__init__.py,sha256=0u3x-I9VxUub0bK5pBNyj1Zt0UmJkPZnPJ_7tD0mnvc,334
+exactdocs/catalog/dtos.py,sha256=uhcxSg_TkFTJa-NrWtD7FETGHXXRDQE9NRdKePR6EHU,1203
+exactdocs/catalog/errors.py,sha256=ClRbwoQJp5nKIWazIVcuAY_LECG0kyiuErewK_bL8R0,464
+exactdocs/catalog/models.py,sha256=neRWNCVD8g6wuLfHRkvLEhgp962OhXBqn7cCbSdAXow,974
+exactdocs/catalog/module.py,sha256=_TNrybsuFmGhIcaQkJhsROKTz4SBePAWL5rOQVGcKdg,958
+exactdocs/catalog/use_cases.py,sha256=JPN-5eqejXXHNJVdggsAxdHqoJ1ebIGALPj2gWadfFM,1159
+exactdocs/catalog/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exactdocs/catalog/adapters/driven/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exactdocs/catalog/adapters/driven/memory.py,sha256=Qn1DykuZGf4zPeaMob9QCpGFQbJ1weXroXzWp8p08Ec,1281
+exactdocs/catalog/adapters/driving/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exactdocs/catalog/adapters/driving/http.py,sha256=DJ5c8WUAEUvDKXIp37rwPAEB_y1XkyVE7153l6CYuYI,724
+exactdocs/catalog/adapters/driving/mcp.py,sha256=-lj8sCNL6NRng4Tr83zJ7LtPVsfPLQJgE1FYNCn-OVY,624
+exactdocs/catalog/ports/__init__.py,sha256=RYrj8wC8kMrVVB-gXWv_DSIG5xVW4Wb8db8UFn16Epw,195
+exactdocs/catalog/ports/driven.py,sha256=i0SXcHEC7WM-EzAyOpP3SX5ZpYjlMkicZQ_gwOgOnJY,524
+exactdocs/catalog/ports/driving.py,sha256=qVC4z64AJ7mPDsVRZNqmAOXZpTeD-fLNRIPhJb5Fc2k,597
+exactdocs/retrieval/__init__.py,sha256=OQDJF0SkGRPe9ew8hYdq3o5qBQU03kgI3O81KnwzV-M,250
+exactdocs/retrieval/dtos.py,sha256=TA4Hh9ycwJc8cn5xpEqpolqBF5kwVoAonIb_XAK6qXM,1444
+exactdocs/retrieval/errors.py,sha256=93JiMAB-w46UtYB7GGaq4jArLIstTO3SkbyCKw01dlw,549
+exactdocs/retrieval/models.py,sha256=Cr3X9WYDwH7TAtOVwpaNpep5jGzU6HoPh5nQwGveqqU,874
+exactdocs/retrieval/module.py,sha256=o7V7XnrygWGMba5meh90qWkc73Ax9fyMpFIokh_vgfs,668
+exactdocs/retrieval/use_cases.py,sha256=9rMQb9EqUYLdvPBNnScJ4v5-UhXDOHnl8M5Ve-JRjjw,974
+exactdocs/retrieval/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exactdocs/retrieval/adapters/driven/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exactdocs/retrieval/adapters/driven/memory.py,sha256=ecbyITEWQWAAIIhsc0GPWUcteO_vSyCy5ltY4IlSsLM,1016
+exactdocs/retrieval/adapters/driving/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exactdocs/retrieval/adapters/driving/http.py,sha256=LX33oSBLBqSrTsBeEenD7T7BxLjXtSPMS3u7vAlPG6s,530
+exactdocs/retrieval/adapters/driving/mcp.py,sha256=tD7k79JwWaDRNEOVK8HVUorknlS1nFcgWWMCShwQoco,1139
+exactdocs/retrieval/ports/__init__.py,sha256=Usylx_LGTpaW65iHiPGbj1TIxqo-L2yY5e3qS-T6BBU,193
+exactdocs/retrieval/ports/driven.py,sha256=_mjBPeKbGlWGB1Oo9-wHPeEXYEHQ1mAJhn5RWhwvuDQ,904
+exactdocs/retrieval/ports/driving.py,sha256=3G1OgmLEi-4dGW-H56zYWW_hGz1ZRFlxdENaG3oMhDo,381
+exactdocs-0.1.0.dist-info/METADATA,sha256=anL1Knc8rBlTiM2dWl85EJz8OzCCbMZbweu9WsiSrNQ,1275
+exactdocs-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+exactdocs-0.1.0.dist-info/entry_points.txt,sha256=OZ7OENarmXQDD7Wl163Y12c8n2DSOTVugwim-Lr0pcs,59
+exactdocs-0.1.0.dist-info/RECORD,,

exactdocs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

exactdocs-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+exactdocs = exactdocs.bootstrap.cli:main