exactdocs 0.1.0__py3-none-any.whl

exactdocs/_web/assets/index-CG8rwfz9.css

@@ -0,0 +1,2 @@
+/*! tailwindcss v4.3.4 | MIT License | https://tailwindcss.com */
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:block))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial;--tw-shadow:0 0 #0000;--tw-shadow-color:initial;--tw-shadow-alpha:100%;--tw-inset-shadow:0 0 #0000;--tw-inset-shadow-color:initial;--tw-inset-shadow-alpha:100%;--tw-ring-color:initial;--tw-ring-shadow:0 0 #0000;--tw-inset-ring-color:initial;--tw-inset-ring-shadow:0 0 #0000;--tw-ring-inset:initial;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-offset-shadow:0 0 #0000;--tw-outline-style:solid;--tw-translate-x:0;--tw-translate-y:0;--tw-translate-z:0;--tw-animation-delay:0s;--tw-animation-direction:normal;--tw-animation-duration:initial;--tw-animation-fill-mode:none;--tw-animation-iteration-count:1;--tw-enter-blur:0;--tw-enter-opacity:1;--tw-enter-rotate:0;--tw-enter-scale:1;--tw-enter-translate-x:0;--tw-enter-translate-y:0;--tw-exit-blur:0;--tw-exit-opacity:1;--tw-exit-rotate:0;--tw-exit-scale:1;--tw-exit-translate-x:0;--tw-exit-translate-y:0}}}@layer theme{:root,:host{--font-sans:-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";--font-mono:ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--color-white:#fff;--spacing:.25rem;--container-4xl:56rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--text-sm:.875rem;--text-sm--line-height:calc(1.25 / .875);--font-weight-medium:500;--font-weight-semibold:600;--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1);--default-font-family:var(--font-sans);--default-mono-font-family:var(--font-mono)}}@layer base{*,:after,:before,::backdrop{box-sizing:border-box;border:0 solid;margin:0;padding:0}::file-selector-button{box-sizing:border-box;border:0 solid;margin:0;padding:0}html,:host{-webkit-text-size-adjust:100%;tab-size:4;line-height:1.5;font-family:var(--default-font-family,-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");font-feature-settings:var(--default-font-feature-settings,normal);font-variation-settings:var(--default-font-variation-settings,normal);-webkit-tap-highlight-color:transparent}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:var(--default-mono-font-family,ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);font-feature-settings:var(--default-mono-font-feature-settings,normal);font-variation-settings:var(--default-mono-font-variation-settings,normal);font-size:1em}small{font-size:80%}sub,sup{vertical-align:baseline;font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}:-moz-focusring:where(:not(iframe)){outline:auto}progress{vertical-align:baseline}summary{display:list-item}ol,ul,menu{list-style:none}img,svg,video,canvas,audio,iframe,embed,object{vertical-align:middle;display:block}img,video{max-width:100%;height:auto}button,input,select,optgroup,textarea{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}:where(select:is([multiple],[size])) optgroup{font-weight:bolder}:where(select:is([multiple],[size])) optgroup option{padding-inline-start:20px}::file-selector-button{margin-inline-end:4px}::placeholder{opacity:1}@supports (not ((-webkit-appearance:-apple-pay-button))) or (contain-intrinsic-size:1px){::placeholder{color:currentColor}@supports (color:color-mix(in lab, red, red)){::placeholder{color:color-mix(in oklab, currentcolor 50%, transparent)}}}textarea{resize:vertical}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-date-and-time-value{min-height:1lh;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-datetime-edit{padding-block:0}::-webkit-datetime-edit-year-field{padding-block:0}::-webkit-datetime-edit-month-field{padding-block:0}::-webkit-datetime-edit-day-field{padding-block:0}::-webkit-datetime-edit-hour-field{padding-block:0}::-webkit-datetime-edit-minute-field{padding-block:0}::-webkit-datetime-edit-second-field{padding-block:0}::-webkit-datetime-edit-millisecond-field{padding-block:0}::-webkit-datetime-edit-meridiem-field{padding-block:0}::-webkit-calendar-picker-indicator{line-height:1}:-moz-ui-invalid{box-shadow:none}button,input:where([type=button],[type=reset],[type=submit]){appearance:button}::file-selector-button{appearance:button}::-webkit-inner-spin-button{height:auto}::-webkit-outer-spin-button{height:auto}[hidden]:where(:not([hidden=until-found])){display:none!important}*{border-color:var(--border);outline-color:var(--ring)}@supports (color:color-mix(in lab, red, red)){*{outline-color:color-mix(in oklab, var(--ring) 50%, transparent)}}body{background-color:var(--background);color:var(--foreground)}}@layer components;@layer utilities{.\@container\/card-header{container:card-header/inline-size}.relative{position:relative}.col-start-2{grid-column-start:2}.row-span-2{grid-row:span 2/span 2}.row-start-1{grid-row-start:1}.mx-auto{margin-inline:auto}.mt-4{margin-top:calc(var(--spacing) * 4)}.flex{display:flex}.grid{display:grid}.inline-flex{display:inline-flex}.table{display:table}.table-caption{display:table-caption}.table-cell{display:table-cell}.table-row{display:table-row}.h-10{height:calc(var(--spacing) * 10)}.min-h-dvh{min-height:100dvh}.w-fit{width:fit-content}.w-full{width:100%}.max-w-4xl{max-width:var(--container-4xl)}.shrink-0{flex-shrink:0}.caption-bottom{caption-side:bottom}.auto-rows-min{grid-auto-rows:min-content}.grid-rows-\[auto_auto\]{grid-template-rows:auto auto}.flex-col{flex-direction:column}.flex-wrap{flex-wrap:wrap}.items-center{align-items:center}.items-start{align-items:flex-start}.justify-center{justify-content:center}.gap-1{gap:var(--spacing)}.gap-2{gap:calc(var(--spacing) * 2)}.gap-6{gap:calc(var(--spacing) * 6)}.self-start{align-self:flex-start}.justify-self-end{justify-self:flex-end}.overflow-hidden{overflow:hidden}.overflow-x-auto{overflow-x:auto}.rounded-full{border-radius:2147483647px}.rounded-xl{border-radius:calc(var(--radius) + 4px)}.border{border-style:var(--tw-border-style);border-width:1px}.border-t{border-top-style:var(--tw-border-style);border-top-width:1px}.border-b{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.border-border{border-color:var(--border)}.border-transparent{border-color:#0000}.bg-card{background-color:var(--card)}.bg-destructive{background-color:var(--destructive)}.bg-muted\/50{background-color:var(--muted)}@supports (color:color-mix(in lab, red, red)){.bg-muted\/50{background-color:color-mix(in oklab, var(--muted) 50%, transparent)}}.bg-primary{background-color:var(--primary)}.bg-secondary{background-color:var(--secondary)}.p-2{padding:calc(var(--spacing) * 2)}.p-6{padding:calc(var(--spacing) * 6)}.px-2{padding-inline:calc(var(--spacing) * 2)}.px-6{padding-inline:calc(var(--spacing) * 6)}.py-0\.5{padding-block:calc(var(--spacing) * .5)}.py-3{padding-block:calc(var(--spacing) * 3)}.py-6{padding-block:calc(var(--spacing) * 6)}.text-left{text-align:left}.align-middle{vertical-align:middle}.text-sm{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.leading-none{--tw-leading:1;line-height:1}.font-medium{--tw-font-weight:var(--font-weight-medium);font-weight:var(--font-weight-medium)}.font-semibold{--tw-font-weight:var(--font-weight-semibold);font-weight:var(--font-weight-semibold)}.whitespace-nowrap{white-space:nowrap}.text-card-foreground{color:var(--card-foreground)}.text-foreground{color:var(--foreground)}.text-muted-foreground{color:var(--muted-foreground)}.text-primary{color:var(--primary)}.text-primary-foreground{color:var(--primary-foreground)}.text-secondary-foreground{color:var(--secondary-foreground)}.text-white{color:var(--color-white)}.underline-offset-4{text-underline-offset:4px}.shadow-sm{--tw-shadow:0 1px 3px 0 var(--tw-shadow-color,#0000001a), 0 1px 2px -1px var(--tw-shadow-color,#0000001a);box-shadow:var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow)}.outline{outline-style:var(--tw-outline-style);outline-width:1px}.transition-\[color\,box-shadow\]{transition-property:color,box-shadow;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.transition-colors{transition-property:color,background-color,border-color,outline-color,text-decoration-color,fill,stroke,--tw-gradient-from,--tw-gradient-via,--tw-gradient-to;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}@media (hover:hover){.hover\:bg-muted\/50:hover{background-color:var(--muted)}@supports (color:color-mix(in lab, red, red)){.hover\:bg-muted\/50:hover{background-color:color-mix(in oklab, var(--muted) 50%, transparent)}}}.focus-visible\:border-ring:focus-visible{border-color:var(--ring)}.focus-visible\:ring-\[3px\]:focus-visible{--tw-ring-shadow:var(--tw-ring-inset, ) 0 0 0 calc(3px + var(--tw-ring-offset-width)) var(--tw-ring-color,currentcolor);box-shadow:var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow)}.focus-visible\:ring-destructive\/20:focus-visible{--tw-ring-color:var(--destructive)}@supports (color:color-mix(in lab, red, red)){.focus-visible\:ring-destructive\/20:focus-visible{--tw-ring-color:color-mix(in oklab, var(--destructive) 20%, transparent)}}.focus-visible\:ring-ring\/50:focus-visible{--tw-ring-color:var(--ring)}@supports (color:color-mix(in lab, red, red)){.focus-visible\:ring-ring\/50:focus-visible{--tw-ring-color:color-mix(in oklab, var(--ring) 50%, transparent)}}.has-aria-expanded\:bg-muted\/50:has([aria-expanded=true]){background-color:var(--muted)}@supports (color:color-mix(in lab, red, red)){.has-aria-expanded\:bg-muted\/50:has([aria-expanded=true]){background-color:color-mix(in oklab, var(--muted) 50%, transparent)}}.has-data-\[slot\=card-action\]\:grid-cols-\[1fr_auto\]:has([data-slot=card-action]){grid-template-columns:1fr auto}.aria-invalid\:border-destructive[aria-invalid=true]{border-color:var(--destructive)}.aria-invalid\:ring-destructive\/20[aria-invalid=true]{--tw-ring-color:var(--destructive)}@supports (color:color-mix(in lab, red, red)){.aria-invalid\:ring-destructive\/20[aria-invalid=true]{--tw-ring-color:color-mix(in oklab, var(--destructive) 20%, transparent)}}.data-\[state\=selected\]\:bg-muted[data-state=selected]{background-color:var(--muted)}.dark\:bg-destructive\/60:is(.dark *){background-color:var(--destructive)}@supports (color:color-mix(in lab, red, red)){.dark\:bg-destructive\/60:is(.dark *){background-color:color-mix(in oklab, var(--destructive) 60%, transparent)}}.dark\:focus-visible\:ring-destructive\/40:is(.dark *):focus-visible{--tw-ring-color:var(--destructive)}@supports (color:color-mix(in lab, red, red)){.dark\:focus-visible\:ring-destructive\/40:is(.dark *):focus-visible{--tw-ring-color:color-mix(in oklab, var(--destructive) 40%, transparent)}}.dark\:aria-invalid\:ring-destructive\/40:is(.dark *)[aria-invalid=true]{--tw-ring-color:var(--destructive)}@supports (color:color-mix(in lab, red, red)){.dark\:aria-invalid\:ring-destructive\/40:is(.dark *)[aria-invalid=true]{--tw-ring-color:color-mix(in oklab, var(--destructive) 40%, transparent)}}.\[\&_tr\]\:border-b tr{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.\[\&_tr\:last-child\]\:border-0 tr:last-child{border-style:var(--tw-border-style);border-width:0}.\[\&\:has\(\[role\=checkbox\]\)\]\:pr-0:has([role=checkbox]){padding-right:0}.\[\.border-b\]\:pb-6.border-b{padding-bottom:calc(var(--spacing) * 6)}.\[\.border-t\]\:pt-6.border-t{padding-top:calc(var(--spacing) * 6)}.\[\&\>\[role\=checkbox\]\]\:translate-y-\[2px\]>[role=checkbox]{--tw-translate-y:2px;translate:var(--tw-translate-x) var(--tw-translate-y)}.\[\&\>svg\]\:pointer-events-none>svg{pointer-events:none}.\[\&\>svg\]\:size-3>svg{width:calc(var(--spacing) * 3);height:calc(var(--spacing) * 3)}.\[\&\>tr\]\:last\:border-b-0>tr:last-child{border-bottom-style:var(--tw-border-style);border-bottom-width:0}@media (hover:hover){a.\[a\&\]\:hover\:bg-accent:hover{background-color:var(--accent)}a.\[a\&\]\:hover\:bg-destructive\/90:hover{background-color:var(--destructive)}@supports (color:color-mix(in lab, red, red)){a.\[a\&\]\:hover\:bg-destructive\/90:hover{background-color:color-mix(in oklab, var(--destructive) 90%, transparent)}}a.\[a\&\]\:hover\:bg-primary\/90:hover{background-color:var(--primary)}@supports (color:color-mix(in lab, red, red)){a.\[a\&\]\:hover\:bg-primary\/90:hover{background-color:color-mix(in oklab, var(--primary) 90%, transparent)}}a.\[a\&\]\:hover\:bg-secondary\/90:hover{background-color:var(--secondary)}@supports (color:color-mix(in lab, red, red)){a.\[a\&\]\:hover\:bg-secondary\/90:hover{background-color:color-mix(in oklab, var(--secondary) 90%, transparent)}}a.\[a\&\]\:hover\:text-accent-foreground:hover{color:var(--accent-foreground)}a.\[a\&\]\:hover\:underline:hover{text-decoration-line:underline}}}@property --tw-animation-delay{syntax:"*";inherits:false;initial-value:0s}@property --tw-animation-direction{syntax:"*";inherits:false;initial-value:normal}@property --tw-animation-duration{syntax:"*";inherits:false}@property --tw-animation-fill-mode{syntax:"*";inherits:false;initial-value:none}@property --tw-animation-iteration-count{syntax:"*";inherits:false;initial-value:1}@property --tw-enter-blur{syntax:"*";inherits:false;initial-value:0}@property --tw-enter-opacity{syntax:"*";inherits:false;initial-value:1}@property --tw-enter-rotate{syntax:"*";inherits:false;initial-value:0}@property --tw-enter-scale{syntax:"*";inherits:false;initial-value:1}@property --tw-enter-translate-x{syntax:"*";inherits:false;initial-value:0}@property --tw-enter-translate-y{syntax:"*";inherits:false;initial-value:0}@property --tw-exit-blur{syntax:"*";inherits:false;initial-value:0}@property --tw-exit-opacity{syntax:"*";inherits:false;initial-value:1}@property --tw-exit-rotate{syntax:"*";inherits:false;initial-value:0}@property --tw-exit-scale{syntax:"*";inherits:false;initial-value:1}@property --tw-exit-translate-x{syntax:"*";inherits:false;initial-value:0}@property --tw-exit-translate-y{syntax:"*";inherits:false;initial-value:0}:root{--radius:.625rem;--background:oklch(100% 0 0);--foreground:oklch(14.5% 0 0);--card:oklch(100% 0 0);--card-foreground:oklch(14.5% 0 0);--popover:oklch(100% 0 0);--popover-foreground:oklch(14.5% 0 0);--primary:oklch(20.5% 0 0);--primary-foreground:oklch(98.5% 0 0);--secondary:oklch(97% 0 0);--secondary-foreground:oklch(20.5% 0 0);--muted:oklch(97% 0 0);--muted-foreground:oklch(55.6% 0 0);--accent:oklch(97% 0 0);--accent-foreground:oklch(20.5% 0 0);--destructive:oklch(57.7% .245 27.325);--border:oklch(92.2% 0 0);--input:oklch(92.2% 0 0);--ring:oklch(70.8% 0 0)}.dark{--background:oklch(14.5% 0 0);--foreground:oklch(98.5% 0 0);--card:oklch(20.5% 0 0);--card-foreground:oklch(98.5% 0 0);--popover:oklch(20.5% 0 0);--popover-foreground:oklch(98.5% 0 0);--primary:oklch(92.2% 0 0);--primary-foreground:oklch(20.5% 0 0);--secondary:oklch(26.9% 0 0);--secondary-foreground:oklch(98.5% 0 0);--muted:oklch(26.9% 0 0);--muted-foreground:oklch(70.8% 0 0);--accent:oklch(26.9% 0 0);--accent-foreground:oklch(98.5% 0 0);--destructive:oklch(70.4% .191 22.216);--border:oklch(100% 0 0/.1);--input:oklch(100% 0 0/.15);--ring:oklch(55.6% 0 0)}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-shadow-color{syntax:"*";inherits:false}@property --tw-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-inset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-shadow-color{syntax:"*";inherits:false}@property --tw-inset-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-ring-color{syntax:"*";inherits:false}@property --tw-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-ring-color{syntax:"*";inherits:false}@property --tw-inset-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-ring-inset{syntax:"*";inherits:false}@property --tw-ring-offset-width{syntax:"<length>";inherits:false;initial-value:0}@property --tw-ring-offset-color{syntax:"*";inherits:false;initial-value:#fff}@property --tw-ring-offset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-outline-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-translate-x{syntax:"*";inherits:false;initial-value:0}@property --tw-translate-y{syntax:"*";inherits:false;initial-value:0}@property --tw-translate-z{syntax:"*";inherits:false;initial-value:0}

exactdocs/_web/assets/routes-CCGZxbYl.js

@@ -0,0 +1 @@
+import{t as e}from"./index-B350HwjP.js";var t=e;export{t as component};

exactdocs/_web/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ExactDocs</title>
+    <script type="module" crossorigin src="/assets/index-B350HwjP.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CG8rwfz9.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

exactdocs/bootstrap/__init__.py

@@ -0,0 +1,5 @@
+"""Composition root: the only package allowed to import more than one domain.
+
+It picks adapters, wires domains to each other through ports, and builds the HTTP, MCP and CLI
+entry points.
+"""

exactdocs/bootstrap/bridges.py

@@ -0,0 +1,27 @@
+"""Adapters that connect one domain's driven port to another domain's driving port.
+
+This is how domains talk to each other without importing each other: the consumer declares a
+port in its own language, and a bridge here translates to the provider's public use case.
+"""
+
+from dataclasses import dataclass
+
+from exactdocs.catalog.dtos import GetLibraryQuery
+from exactdocs.catalog.ports.driving import GetLibrary
+from exactdocs.retrieval.models import DocTarget
+from exactdocs_kernel import NotFoundError
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogIndexedVersions:
+    """Implements ``retrieval.ports.driven.IndexedVersions`` using the catalog."""
+
+    get_library: GetLibrary
+
+    async def is_indexed(self, target: DocTarget) -> bool:
+        """Ask the catalog whether this exact version has an index."""
+        try:
+            library = await self.get_library(GetLibraryQuery(name=target.library))
+        except NotFoundError:
+            return False
+        return target.version in library.versions

exactdocs/bootstrap/cli.py

@@ -0,0 +1,48 @@
+"""``exactdocs`` command line."""
+
+import asyncio
+from typing import Annotated
+
+import uvicorn
+from cyclopts import App, Parameter
+
+from exactdocs import __version__
+from exactdocs.bootstrap.container import Container
+from exactdocs.bootstrap.http import create_app
+from exactdocs.bootstrap.mcp import build_mcp
+from exactdocs.bootstrap.settings import Settings
+
+app = App(name="exactdocs", version=__version__, help="Version-accurate docs for AI agents.")
+
+
+@app.command
+def serve(
+    *,
+    stdio: Annotated[bool, Parameter(help="Serve MCP over stdio instead of HTTP.")] = False,
+    host: str | None = None,
+    port: int | None = None,
+    reload: bool = False,
+) -> None:
+    """Run the server: web UI + REST API + MCP over HTTP, or MCP only over stdio."""
+    settings = Settings()
+    if stdio:
+        mcp = build_mcp(Container.build(settings))
+        asyncio.run(mcp.run_stdio_async(show_banner=False))
+        return
+    uvicorn.run(
+        "exactdocs.bootstrap.cli:asgi_app",
+        factory=True,
+        host=host or settings.host,
+        port=port or settings.port,
+        reload=reload,
+    )
+
+
+def asgi_app() -> object:
+    """ASGI factory used by uvicorn (also with ``--reload``)."""
+    return create_app(Container.build(Settings()))
+
+
+def main() -> None:
+    """Console-script entry point."""
+    app()

exactdocs/bootstrap/container.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass
+from typing import Self
+
+from exactdocs.bootstrap.bridges import CatalogIndexedVersions
+from exactdocs.bootstrap.settings import Settings
+from exactdocs.catalog import CatalogModule
+from exactdocs.catalog.adapters.driven.memory import InMemoryLibraryRepository
+from exactdocs.retrieval import RetrievalModule
+from exactdocs.retrieval.adapters.driven.memory import InMemoryExcerptIndex
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Container:
+    """Every domain module, wired. Built once per process."""
+
+    settings: Settings
+    catalog: CatalogModule
+    retrieval: RetrievalModule
+
+    @classmethod
+    def build(cls, settings: Settings) -> Self:
+        """Choose driven adapters and connect domains through bridges."""
+        catalog = CatalogModule.build(repository=InMemoryLibraryRepository.demo())
+        retrieval = RetrievalModule.build(
+            versions=CatalogIndexedVersions(catalog.get_library),
+            index=InMemoryExcerptIndex(),
+        )
+        return cls(settings=settings, catalog=catalog, retrieval=retrieval)

exactdocs/bootstrap/http.py

@@ -0,0 +1,90 @@
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from starlette.exceptions import HTTPException
+from starlette.responses import Response
+from starlette.routing import Route
+from starlette.types import Scope
+
+from exactdocs import __version__
+from exactdocs.bootstrap.container import Container
+from exactdocs.bootstrap.mcp import build_mcp
+from exactdocs.catalog.adapters.driving import http as catalog_http
+from exactdocs.retrieval.adapters.driving import http as retrieval_http
+from exactdocs_kernel import ConflictError, DomainError, NotFoundError, ValidationError
+
+# Built web UI, copied into the package by CI / the Docker build (see web/README.md).
+WEB_DIST = Path(__file__).parent.parent / "_web"
+
+_STATUS_BY_ERROR: dict[type[DomainError], int] = {
+    NotFoundError: 404,
+    ConflictError: 409,
+    ValidationError: 422,
+}
+
+
+class Health(BaseModel):
+    """Liveness payload."""
+
+    status: str
+    version: str
+
+
+def create_app(container: Container) -> FastAPI:
+    """Build the single HTTP service: REST API, MCP (Streamable HTTP) and the web UI."""
+    mcp_app = build_mcp(container).http_app(path="/mcp")
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncGenerator[None]:
+        async with mcp_app.lifespan(mcp_app):
+            yield
+
+    app = FastAPI(title="ExactDocs", version=__version__, lifespan=lifespan)
+    app.add_exception_handler(DomainError, _domain_error_handler)
+
+    api = APIRouter(prefix="/api")
+
+    @api.get("/health", tags=["system"])
+    async def health() -> Health:
+        return Health(status="ok", version=__version__)
+
+    v1 = APIRouter(prefix="/v1")
+    v1.include_router(
+        catalog_http.build_router(
+            list_libraries=container.catalog.list_libraries,
+            get_library=container.catalog.get_library,
+        )
+    )
+    v1.include_router(retrieval_http.build_router(search_docs=container.retrieval.search_docs))
+    api.include_router(v1)
+    app.include_router(api)
+
+    # Exact route (no /mcp -> /mcp/ redirect); the MCP app keeps its own middleware.
+    app.router.routes.append(Route("/mcp", endpoint=mcp_app))
+    if WEB_DIST.is_dir():
+        app.mount("/", SpaStaticFiles(directory=WEB_DIST, html=True), name="web")
+    return app
+
+
+async def _domain_error_handler(_: Request, exc: Exception) -> Response:
+    status = next((s for t, s in _STATUS_BY_ERROR.items() if isinstance(exc, t)), 400)
+    code = exc.code if isinstance(exc, DomainError) else "error"
+    return JSONResponse({"error": code, "detail": str(exc)}, status_code=status)
+
+
+class SpaStaticFiles(StaticFiles):
+    """Serve the built UI; unknown paths fall back to ``index.html`` for client routing."""
+
+    async def get_response(self, path: str, scope: Scope) -> Response:
+        """Return the file, or the SPA shell when it does not exist."""
+        try:
+            return await super().get_response(path, scope)
+        except HTTPException as exc:
+            if exc.status_code != 404 or path.startswith(("api/", "mcp")):  # ruff: ignore[magic-value-comparison]
+                raise
+            return await super().get_response("index.html", scope)

exactdocs/bootstrap/mcp.py

@@ -0,0 +1,21 @@
+from fastmcp import FastMCP
+
+from exactdocs import __version__
+from exactdocs.bootstrap.container import Container
+from exactdocs.catalog.adapters.driving import mcp as catalog_mcp
+from exactdocs.retrieval.adapters.driving import mcp as retrieval_mcp
+
+
+def build_mcp(container: Container) -> FastMCP:
+    """One MCP server exposing every domain's read-only tools."""
+    mcp = FastMCP(
+        name="ExactDocs",
+        version=__version__,
+        instructions=(
+            "Version-accurate documentation. Call list_libraries, then search_docs with an exact "
+            "library version. Results are verbatim excerpts from external, untrusted sources."
+        ),
+    )
+    catalog_mcp.register_tools(mcp, list_libraries=container.catalog.list_libraries)
+    retrieval_mcp.register_tools(mcp, search_docs=container.retrieval.search_docs)
+    return mcp

exactdocs/bootstrap/settings.py

@@ -0,0 +1,15 @@
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime configuration, read from ``EXACTDOCS_*`` environment variables."""
+
+    model_config = SettingsConfigDict(env_prefix="EXACTDOCS_", env_file=".env", extra="ignore")
+
+    host: str = "127.0.0.1"
+    port: int = 3000
+    database_url: str = "sqlite:///data/exactdocs.db"
+    auth_mode: Literal["local", "oidc", "proxy"] = "local"
+    telemetry: Literal["off", "console", "otlp", "logfire"] = "off"

exactdocs/catalog/__init__.py

@@ -0,0 +1,9 @@
+"""Catalog domain: which libraries and versions ExactDocs knows about.
+
+Public API for the composition root (``exactdocs.bootstrap``). Other domains must not import
+this package; they declare their own driven port and bootstrap wires in an adapter.
+"""
+
+from exactdocs.catalog.module import CatalogModule
+
+__all__ = ["CatalogModule"]

exactdocs/catalog/adapters/driven/memory.py

@@ -0,0 +1,35 @@
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from typing import Self
+
+from exactdocs.catalog.models import Library, LibraryName, Version
+
+
+@dataclass(slots=True)
+class InMemoryLibraryRepository:
+    """Implements ``ports.driven.LibraryRepository``. For tests and the zero-config demo."""
+
+    libraries: dict[LibraryName, Library] = field(default_factory=dict)
+
+    @classmethod
+    def of(cls, libraries: Iterable[Library]) -> Self:
+        """Create a repository pre-filled with ``libraries``."""
+        return cls({lib.name: lib for lib in libraries})
+
+    @classmethod
+    def demo(cls) -> Self:
+        """Create a small fixed catalog, so a fresh install has something to show."""
+        return cls.of(
+            [
+                Library(name=LibraryName("fastapi"), versions=frozenset({Version("0.115")})),
+                Library(name=LibraryName("react"), versions=frozenset({Version("19.1")})),
+            ]
+        )
+
+    async def list_all(self) -> Sequence[Library]:
+        """Return every library."""
+        return tuple(self.libraries.values())
+
+    async def get(self, name: LibraryName) -> Library | None:
+        """Return the library with this exact name, or ``None``."""
+        return self.libraries.get(name)

exactdocs/catalog/adapters/driving/http.py

@@ -0,0 +1,21 @@
+"""REST adapter for the catalog (consumed by the web UI)."""
+
+from fastapi import APIRouter
+
+from exactdocs.catalog.dtos import GetLibraryQuery, LibraryList, LibrarySummary
+from exactdocs.catalog.ports.driving import GetLibrary, ListLibraries
+
+
+def build_router(*, list_libraries: ListLibraries, get_library: GetLibrary) -> APIRouter:
+    """Expose the catalog's driving ports under ``/libraries``."""
+    router = APIRouter(prefix="/libraries", tags=["catalog"])
+
+    @router.get("")
+    async def list_all() -> LibraryList:
+        return await list_libraries()
+
+    @router.get("/{name}")
+    async def get_one(name: str) -> LibrarySummary:
+        return await get_library(GetLibraryQuery(name=name))
+
+    return router

exactdocs/catalog/adapters/driving/mcp.py

@@ -0,0 +1,18 @@
+"""MCP adapter for the catalog. All tools are read-only."""
+
+from fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from exactdocs.catalog.dtos import LibraryList
+from exactdocs.catalog.ports.driving import ListLibraries
+
+READ_ONLY = ToolAnnotations(read_only_hint=True)
+
+
+def register_tools(mcp: FastMCP, *, list_libraries: ListLibraries) -> None:
+    """Register the catalog's MCP tools on ``mcp``."""
+
+    @mcp.tool(name="list_libraries", annotations=READ_ONLY)
+    async def list_libraries_tool() -> LibraryList:
+        """List indexed libraries and their versions."""
+        return await list_libraries()

exactdocs/catalog/dtos.py

@@ -0,0 +1,42 @@
+"""Data crossing the catalog boundary (into and out of driving ports). Immutable, validated."""
+
+from collections.abc import Iterable
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from exactdocs.catalog.models import Library
+
+
+class _Dto(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class LibrarySummary(_Dto):
+    """A library and its indexed versions, sorted ascending."""
+
+    name: str
+    versions: list[str]
+
+    @classmethod
+    def from_model(cls, library: Library) -> Self:
+        """Map a domain entity to its boundary representation."""
+        return cls(name=library.name, versions=[str(v) for v in sorted(library.versions)])
+
+
+class LibraryList(_Dto):
+    """All libraries visible to the caller, sorted by name."""
+
+    libraries: list[LibrarySummary]
+
+    @classmethod
+    def from_models(cls, libraries: Iterable[Library]) -> Self:
+        """Map domain entities."""
+        ordered = sorted(libraries, key=lambda lib: lib.name)
+        return cls(libraries=[LibrarySummary.from_model(lib) for lib in ordered])
+
+
+class GetLibraryQuery(_Dto):
+    """Look up one library by its exact name."""
+
+    name: str = Field(min_length=1)

exactdocs/catalog/errors.py

@@ -0,0 +1,16 @@
+from exactdocs_kernel import NotFoundError, ValidationError
+
+
+class EmptyVersionError(ValidationError):
+    """A version label is blank."""
+
+    def __init__(self) -> None:
+        super().__init__("version must not be empty")
+
+
+class LibraryNotFoundError(NotFoundError):
+    """No library with this name is in the catalog."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"library {name!r} is not in the catalog")
+        self.name = name

exactdocs/catalog/models.py

@@ -0,0 +1,34 @@
+"""Catalog entities and value objects. Pure Python: no frameworks, no I/O."""
+
+from dataclasses import dataclass, field
+from typing import NewType
+
+from exactdocs.catalog.errors import EmptyVersionError
+
+LibraryName = NewType("LibraryName", str)
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class Version:
+    """A documentation version label exactly as published by the library (e.g. ``19.1``)."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not self.value.strip():
+            raise EmptyVersionError
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Library:
+    """A documented library and the versions that have an index."""
+
+    name: LibraryName
+    versions: frozenset[Version] = field(default_factory=frozenset)
+
+    def has_version(self, version: Version) -> bool:
+        """Version is a hard filter: only an exact match counts."""
+        return version in self.versions

exactdocs/catalog/module.py

@@ -0,0 +1,27 @@
+"""Wiring of the catalog domain: driven adapters in, driving ports out.
+
+It does not pick adapters itself; the composition root (``exactdocs.bootstrap``) passes them in.
+"""
+
+from dataclasses import dataclass
+from typing import Self
+
+from exactdocs.catalog.ports.driven import LibraryRepository
+from exactdocs.catalog.ports.driving import GetLibrary, ListLibraries
+from exactdocs.catalog.use_cases import GetLibraryUseCase, ListLibrariesUseCase
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CatalogModule:
+    """The catalog's driving ports, ready to be exposed by driving adapters."""
+
+    list_libraries: ListLibraries
+    get_library: GetLibrary
+
+    @classmethod
+    def build(cls, *, repository: LibraryRepository) -> Self:
+        """Assemble the use cases around the given driven adapters."""
+        return cls(
+            list_libraries=ListLibrariesUseCase(repository),
+            get_library=GetLibraryUseCase(repository),
+        )

exactdocs/catalog/ports/__init__.py

@@ -0,0 +1,4 @@
+from exactdocs.catalog.ports.driven import LibraryRepository
+from exactdocs.catalog.ports.driving import GetLibrary, ListLibraries
+
+__all__ = ["GetLibrary", "LibraryRepository", "ListLibraries"]

exactdocs/catalog/ports/driven.py

@@ -0,0 +1,18 @@
+"""Driven (secondary) ports: what the catalog needs from infrastructure."""
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from exactdocs.catalog.models import Library, LibraryName
+
+
+class LibraryRepository(Protocol):
+    """Persistence for catalog entries."""
+
+    async def list_all(self) -> Sequence[Library]:
+        """Return every library."""
+        ...
+
+    async def get(self, name: LibraryName) -> Library | None:
+        """Return the library with this exact name, or ``None``."""
+        ...

exactdocs/catalog/ports/driving.py

@@ -0,0 +1,21 @@
+"""Driving (primary) ports: what the outside world may ask the catalog to do."""
+
+from typing import Protocol
+
+from exactdocs.catalog.dtos import GetLibraryQuery, LibraryList, LibrarySummary
+
+
+class ListLibraries(Protocol):
+    """List every library and its indexed versions."""
+
+    async def __call__(self) -> LibraryList:
+        """Run the use case."""
+        ...
+
+
+class GetLibrary(Protocol):
+    """Fetch one library; raises ``LibraryNotFoundError`` when it is missing."""
+
+    async def __call__(self, query: GetLibraryQuery) -> LibrarySummary:
+        """Run the use case."""
+        ...

exactdocs/catalog/use_cases.py

@@ -0,0 +1,33 @@
+"""Catalog use cases. Each one satisfies a driving port structurally, without inheriting it."""
+
+from dataclasses import dataclass
+
+from exactdocs.catalog.dtos import GetLibraryQuery, LibraryList, LibrarySummary
+from exactdocs.catalog.errors import LibraryNotFoundError
+from exactdocs.catalog.models import LibraryName
+from exactdocs.catalog.ports.driven import LibraryRepository
+
+
+@dataclass(frozen=True, slots=True)
+class ListLibrariesUseCase:
+    """Implements ``ports.driving.ListLibraries``."""
+
+    repository: LibraryRepository
+
+    async def __call__(self) -> LibraryList:
+        """List every library."""
+        return LibraryList.from_models(await self.repository.list_all())
+
+
+@dataclass(frozen=True, slots=True)
+class GetLibraryUseCase:
+    """Implements ``ports.driving.GetLibrary``."""
+
+    repository: LibraryRepository
+
+    async def __call__(self, query: GetLibraryQuery) -> LibrarySummary:
+        """Fetch one library by its exact name."""
+        library = await self.repository.get(LibraryName(query.name))
+        if library is None:
+            raise LibraryNotFoundError(query.name)
+        return LibrarySummary.from_model(library)

exactdocs/retrieval/__init__.py

@@ -0,0 +1,8 @@
+"""Retrieval domain: version-filtered search that returns verbatim excerpts with sources.
+
+Public API for the composition root (``exactdocs.bootstrap``) only.
+"""
+
+from exactdocs.retrieval.module import RetrievalModule
+
+__all__ = ["RetrievalModule"]

exactdocs/retrieval/adapters/driven/memory.py

@@ -0,0 +1,26 @@
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from typing import Self
+
+from exactdocs.retrieval.models import DocTarget, Excerpt, SearchText
+
+
+@dataclass(slots=True)
+class InMemoryExcerptIndex:
+    """Implements ``ports.driven.ExcerptIndex`` with case-insensitive substring matching.
+
+    Placeholder until the SQLite (FTS5 + sqlite-vec) and pgvector adapters land.
+    """
+
+    excerpts: list[Excerpt] = field(default_factory=list)
+
+    @classmethod
+    def of(cls, excerpts: Iterable[Excerpt]) -> Self:
+        """Create an index pre-filled with ``excerpts``."""
+        return cls(list(excerpts))
+
+    async def search(self, target: DocTarget, text: SearchText, limit: int) -> Sequence[Excerpt]:
+        """Return excerpts of ``target`` that contain ``text``."""
+        needle = text.value.casefold()
+        hits = (e for e in self.excerpts if e.target == target and needle in e.text.casefold())
+        return [hit for _, hit in zip(range(limit), hits, strict=False)]