msaas-docs 0.1.0__py3-none-any.whl

docs/__init__.py

@@ -0,0 +1,34 @@
+"""Knowledge base and documentation system for SaaS products."""
+
+from docs.config import DocsConfig, get_docs, init_docs
+from docs.models import (
+    DocCategory,
+    DocPage,
+    DocSearchResult,
+    DocTree,
+    DocVersion,
+    PageStatus,
+)
+from docs.renderer import DocRenderer
+from docs.router import create_docs_router
+from docs.search import DocSearch
+from docs.service import DocsService
+from docs.store import DocsStore, InMemoryStore
+
+__all__ = [
+    "DocCategory",
+    "DocPage",
+    "DocRenderer",
+    "DocSearch",
+    "DocSearchResult",
+    "DocTree",
+    "DocVersion",
+    "DocsConfig",
+    "DocsService",
+    "DocsStore",
+    "InMemoryStore",
+    "PageStatus",
+    "create_docs_router",
+    "get_docs",
+    "init_docs",
+]

docs/config.py

@@ -0,0 +1,51 @@
+"""Global configuration and singleton access for the docs module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from docs.service import DocsService
+
+_instance: DocsService | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DocsConfig:
+    """Configuration for the docs module."""
+
+    base_path: str = "/docs"
+    enable_versioning: bool = True
+    enable_search: bool = True
+    default_locale: str = "en"
+    max_versions: int = 100
+    search_snippet_length: int = 160
+    extra: dict[str, object] = field(default_factory=dict)
+
+
+def init_docs(config: DocsConfig | None = None) -> DocsService:
+    """Initialize the global DocsService singleton."""
+    global _instance  # noqa: PLW0603
+    from docs.search import DocSearch
+    from docs.service import DocsService
+    from docs.store import InMemoryStore
+
+    cfg = config or DocsConfig()
+    store = InMemoryStore()
+    search = DocSearch(snippet_length=cfg.search_snippet_length) if cfg.enable_search else None
+    _instance = DocsService(config=cfg, store=store, search=search)
+    return _instance
+
+
+def get_docs() -> DocsService:
+    """Return the global DocsService. Raises if not initialized."""
+    if _instance is None:
+        raise RuntimeError("docs module not initialized -- call init_docs() first")
+    return _instance
+
+
+def reset_docs() -> None:
+    """Reset the global singleton (useful for tests)."""
+    global _instance  # noqa: PLW0603
+    _instance = None

docs/models.py

@@ -0,0 +1,162 @@
+"""Domain models for the docs module."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from datetime import datetime, timezone
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class PageStatus(StrEnum):
+    """Publication lifecycle status for a documentation page."""
+
+    DRAFT = "draft"
+    PUBLISHED = "published"
+    ARCHIVED = "archived"
+
+
+def _generate_id() -> str:
+    return uuid.uuid4().hex[:16]
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def slugify(text: str) -> str:
+    """Convert text to a URL-friendly slug."""
+    text = text.lower().strip()
+    text = re.sub(r"[^\w\s-]", "", text)
+    text = re.sub(r"[\s_]+", "-", text)
+    return re.sub(r"-+", "-", text).strip("-")
+
+
+# ---------------------------------------------------------------------------
+# Core models
+# ---------------------------------------------------------------------------
+
+
+class DocCategory(BaseModel):
+    """A category that groups documentation pages."""
+
+    id: str = Field(default_factory=_generate_id)
+    name: str
+    slug: str = ""
+    description: str = ""
+    order: int = 0
+    parent_id: str | None = None
+
+    def model_post_init(self, _context: object) -> None:
+        if not self.slug:
+            self.slug = slugify(self.name)
+
+
+class DocPage(BaseModel):
+    """A single documentation page."""
+
+    id: str = Field(default_factory=_generate_id)
+    slug: str = ""
+    title: str
+    content_markdown: str = ""
+    content_html: str = ""
+    parent_id: str | None = None
+    order: int = 0
+    category: str = ""
+    tags: list[str] = Field(default_factory=list)
+    author_id: str = ""
+    status: PageStatus = PageStatus.DRAFT
+    version: int = 1
+    locale: str = "en"
+    created_at: datetime = Field(default_factory=_now)
+    updated_at: datetime = Field(default_factory=_now)
+    published_at: datetime | None = None
+
+    def model_post_init(self, _context: object) -> None:
+        if not self.slug:
+            self.slug = slugify(self.title)
+
+
+class DocVersion(BaseModel):
+    """An immutable snapshot of a page at a specific version."""
+
+    page_id: str
+    version: int
+    content_markdown: str
+    author_id: str = ""
+    message: str = ""
+    created_at: datetime = Field(default_factory=_now)
+
+
+class DocSearchResult(BaseModel):
+    """A single search hit."""
+
+    page_id: str
+    title: str
+    slug: str
+    snippet: str = ""
+    score: float = 0.0
+    category: str = ""
+
+
+class DocTreeNode(BaseModel):
+    """A node in the navigation tree (page with optional children)."""
+
+    page_id: str
+    title: str
+    slug: str
+    order: int = 0
+    children: list[DocTreeNode] = Field(default_factory=list)
+
+
+class DocTree(BaseModel):
+    """Hierarchical navigation tree, optionally scoped to a category."""
+
+    category: str = ""
+    pages: list[DocTreeNode] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# API request / response helpers
+# ---------------------------------------------------------------------------
+
+
+class CreatePageRequest(BaseModel):
+    title: str
+    content_markdown: str = ""
+    category: str = ""
+    parent_id: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    author_id: str = ""
+    locale: str = "en"
+
+
+class UpdatePageRequest(BaseModel):
+    title: str | None = None
+    content_markdown: str | None = None
+    category: str | None = None
+    parent_id: str | None = None
+    tags: list[str] | None = None
+    order: int | None = None
+    locale: str | None = None
+    version_message: str = ""
+
+
+class RevertRequest(BaseModel):
+    version: int
+
+
+class CreateCategoryRequest(BaseModel):
+    name: str
+    description: str = ""
+    order: int = 0
+    parent_id: str | None = None
+
+
+class PaginatedPages(BaseModel):
+    items: list[DocPage]
+    total: int
+    page: int
+    per_page: int

docs/renderer.py

@@ -0,0 +1,247 @@
+"""Markdown-to-HTML renderer and HTML utilities.
+
+Provides a lightweight, dependency-free renderer covering the most common
+Markdown constructs: headings, paragraphs, bold, italic, inline code,
+code blocks, links, images, unordered/ordered lists, blockquotes,
+horizontal rules, and tables.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TocEntry:
+    """A single heading in a table of contents."""
+
+    level: int
+    text: str
+    anchor: str
+
+
+@dataclass
+class DocRenderer:
+    """Stateless Markdown renderer with TOC/text extraction helpers."""
+
+    heading_prefix: str = "doc-"
+    _anchor_counts: dict[str, int] = field(default_factory=dict, repr=False)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def render_markdown(self, content: str) -> str:
+        """Convert Markdown text to HTML."""
+        self._anchor_counts = {}
+        lines = content.split("\n")
+        html_parts: list[str] = []
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+
+            # Fenced code block
+            if line.strip().startswith("```"):
+                block, i = self._parse_code_block(lines, i)
+                html_parts.append(block)
+                continue
+
+            # Table
+            if i + 1 < len(lines) and re.match(r"^\|.*\|$", line.strip()) and re.match(
+                r"^\|[\s\-:|]+\|$", lines[i + 1].strip()
+            ):
+                table, i = self._parse_table(lines, i)
+                html_parts.append(table)
+                continue
+
+            # Heading
+            if m := re.match(r"^(#{1,6})\s+(.+)$", line):
+                level = len(m.group(1))
+                text = self._inline(m.group(2))
+                anchor = self._make_anchor(text)
+                html_parts.append(
+                    f'<h{level} id="{anchor}">{text}</h{level}>'
+                )
+                i += 1
+                continue
+
+            # Horizontal rule
+            if re.match(r"^(\*{3,}|-{3,}|_{3,})\s*$", line.strip()):
+                html_parts.append("<hr>")
+                i += 1
+                continue
+
+            # Blockquote
+            if line.strip().startswith(">"):
+                block, i = self._parse_blockquote(lines, i)
+                html_parts.append(block)
+                continue
+
+            # Unordered list
+            if re.match(r"^[\s]*[-*+]\s+", line):
+                block, i = self._parse_unordered_list(lines, i)
+                html_parts.append(block)
+                continue
+
+            # Ordered list
+            if re.match(r"^[\s]*\d+\.\s+", line):
+                block, i = self._parse_ordered_list(lines, i)
+                html_parts.append(block)
+                continue
+
+            # Blank line
+            if not line.strip():
+                i += 1
+                continue
+
+            # Paragraph
+            para_lines: list[str] = []
+            while i < len(lines) and lines[i].strip() and not self._is_block_start(lines, i):
+                para_lines.append(lines[i])
+                i += 1
+            html_parts.append(f"<p>{self._inline(' '.join(para_lines))}</p>")
+
+        return "\n".join(html_parts)
+
+    def extract_toc(self, rendered_html: str) -> list[TocEntry]:
+        """Extract table-of-contents entries from rendered HTML."""
+        entries: list[TocEntry] = []
+        for m in re.finditer(r'<h(\d)\s+id="([^"]+)">(.*?)</h\1>', rendered_html):
+            entries.append(
+                TocEntry(
+                    level=int(m.group(1)),
+                    text=self._strip_tags(m.group(3)),
+                    anchor=m.group(2),
+                )
+            )
+        return entries
+
+    def extract_text(self, rendered_html: str) -> str:
+        """Strip all HTML tags and return plain text for indexing."""
+        text = re.sub(r"<[^>]+>", " ", rendered_html)
+        text = html.unescape(text)
+        return re.sub(r"\s+", " ", text).strip()
+
+    # ------------------------------------------------------------------
+    # Block parsers
+    # ------------------------------------------------------------------
+
+    def _parse_code_block(self, lines: list[str], start: int) -> tuple[str, int]:
+        opening = lines[start].strip()
+        lang = opening.lstrip("`").strip()
+        i = start + 1
+        code_lines: list[str] = []
+        while i < len(lines):
+            if lines[i].strip() == "```":
+                i += 1
+                break
+            code_lines.append(html.escape(lines[i]))
+            i += 1
+        lang_attr = f' class="language-{lang}"' if lang else ""
+        code = "\n".join(code_lines)
+        return f"<pre><code{lang_attr}>{code}</code></pre>", i
+
+    def _parse_table(self, lines: list[str], start: int) -> tuple[str, int]:
+        header_cells = [c.strip() for c in lines[start].strip().strip("|").split("|")]
+        i = start + 2  # skip separator
+        rows: list[list[str]] = []
+        while i < len(lines) and re.match(r"^\|.*\|$", lines[i].strip()):
+            cells = [c.strip() for c in lines[i].strip().strip("|").split("|")]
+            rows.append(cells)
+            i += 1
+        parts = ["<table>", "<thead><tr>"]
+        for cell in header_cells:
+            parts.append(f"<th>{self._inline(cell)}</th>")
+        parts.append("</tr></thead>")
+        if rows:
+            parts.append("<tbody>")
+            for row in rows:
+                parts.append("<tr>")
+                for cell in row:
+                    parts.append(f"<td>{self._inline(cell)}</td>")
+                parts.append("</tr>")
+            parts.append("</tbody>")
+        parts.append("</table>")
+        return "".join(parts), i
+
+    def _parse_blockquote(self, lines: list[str], start: int) -> tuple[str, int]:
+        i = start
+        content_lines: list[str] = []
+        while i < len(lines) and lines[i].strip().startswith(">"):
+            content_lines.append(re.sub(r"^>\s?", "", lines[i]))
+            i += 1
+        inner = self._inline(" ".join(content_lines))
+        return f"<blockquote><p>{inner}</p></blockquote>", i
+
+    def _parse_unordered_list(self, lines: list[str], start: int) -> tuple[str, int]:
+        i = start
+        items: list[str] = []
+        while i < len(lines) and re.match(r"^[\s]*[-*+]\s+", lines[i]):
+            text = re.sub(r"^[\s]*[-*+]\s+", "", lines[i])
+            items.append(f"<li>{self._inline(text)}</li>")
+            i += 1
+        return "<ul>" + "".join(items) + "</ul>", i
+
+    def _parse_ordered_list(self, lines: list[str], start: int) -> tuple[str, int]:
+        i = start
+        items: list[str] = []
+        while i < len(lines) and re.match(r"^[\s]*\d+\.\s+", lines[i]):
+            text = re.sub(r"^[\s]*\d+\.\s+", "", lines[i])
+            items.append(f"<li>{self._inline(text)}</li>")
+            i += 1
+        return "<ol>" + "".join(items) + "</ol>", i
+
+    # ------------------------------------------------------------------
+    # Inline formatting
+    # ------------------------------------------------------------------
+
+    def _inline(self, text: str) -> str:
+        """Apply inline Markdown transformations."""
+        # Inline code (must come before bold/italic to avoid conflicts)
+        text = re.sub(r"`([^`]+)`", r"<code>\1</code>", text)
+        # Images
+        text = re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", r'<img src="\2" alt="\1">', text)
+        # Links
+        text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r'<a href="\2">\1</a>', text)
+        # Bold + italic
+        text = re.sub(r"\*\*\*(.+?)\*\*\*", r"<strong><em>\1</em></strong>", text)
+        # Bold
+        text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", text)
+        # Italic
+        text = re.sub(r"\*(.+?)\*", r"<em>\1</em>", text)
+        return text
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _is_block_start(self, lines: list[str], i: int) -> bool:
+        line = lines[i]
+        if re.match(r"^#{1,6}\s+", line):
+            return True
+        if line.strip().startswith("```"):
+            return True
+        if re.match(r"^[\s]*[-*+]\s+", line):
+            return True
+        if re.match(r"^[\s]*\d+\.\s+", line):
+            return True
+        if line.strip().startswith(">"):
+            return True
+        if re.match(r"^(\*{3,}|-{3,}|_{3,})\s*$", line.strip()):
+            return True
+        return False
+
+    def _make_anchor(self, text: str) -> str:
+        plain = self._strip_tags(text).lower()
+        slug = re.sub(r"[^\w\s-]", "", plain)
+        slug = re.sub(r"[\s]+", "-", slug).strip("-")
+        base = f"{self.heading_prefix}{slug}"
+        count = self._anchor_counts.get(base, 0)
+        self._anchor_counts[base] = count + 1
+        return base if count == 0 else f"{base}-{count}"
+
+    @staticmethod
+    def _strip_tags(text: str) -> str:
+        return re.sub(r"<[^>]+>", "", text)

docs/router.py

@@ -0,0 +1,153 @@
+"""FastAPI router factory for the docs module."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docs.config import get_docs
+from docs.models import (
+    CreateCategoryRequest,
+    CreatePageRequest,
+    DocCategory,
+    DocPage,
+    DocSearchResult,
+    DocTree,
+    DocVersion,
+    PaginatedPages,
+    RevertRequest,
+    UpdatePageRequest,
+)
+from errors import BusinessLogicError, NotFoundError
+from api_core.responses import ApiResponse, PaginatedResponse
+
+if TYPE_CHECKING:
+    pass
+
+
+def create_docs_router():  # noqa: ANN201 -- avoids hard dep on fastapi at import time
+    """Create and return a FastAPI APIRouter for the docs module."""
+    from fastapi import APIRouter, Query
+
+    router = APIRouter(prefix="/docs", tags=["docs"])
+
+    # ------------------------------------------------------------------
+    # Pages
+    # ------------------------------------------------------------------
+
+    @router.post("/pages", response_model=DocPage, status_code=201)
+    async def create_page(body: CreatePageRequest) -> DocPage:
+        svc = get_docs()
+        return await svc.create_page(
+            title=body.title,
+            content_markdown=body.content_markdown,
+            category=body.category,
+            parent_id=body.parent_id,
+            tags=body.tags,
+            author_id=body.author_id,
+            locale=body.locale,
+        )
+
+    @router.get("/pages", response_model=PaginatedPages)
+    async def list_pages(
+        category: str | None = Query(None),
+        status: str | None = Query(None),
+        page: int = Query(1, ge=1),
+        per_page: int = Query(20, ge=1, le=100),
+    ) -> PaginatedPages:
+        svc = get_docs()
+        from docs.models import PageStatus
+
+        page_status = PageStatus(status) if status else None
+        return await svc.list_pages(
+            category=category, status=page_status, page=page, per_page=per_page
+        )
+
+    @router.get("/pages/{slug}", response_model=DocPage)
+    async def get_page(slug: str) -> DocPage:
+        svc = get_docs()
+        result = await svc.get_page(slug)
+        if result is None:
+            raise NotFoundError("Page not found")
+        return result
+
+    @router.put("/pages/{page_id}", response_model=DocPage)
+    async def update_page(page_id: str, body: UpdatePageRequest) -> DocPage:
+        svc = get_docs()
+        fields = body.model_dump(exclude_none=True)
+        try:
+            return await svc.update_page(page_id, **fields)
+        except ValueError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    @router.post("/pages/{page_id}/publish", response_model=DocPage)
+    async def publish_page(page_id: str) -> DocPage:
+        svc = get_docs()
+        try:
+            return await svc.publish(page_id)
+        except ValueError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    @router.post("/pages/{page_id}/archive", response_model=DocPage)
+    async def archive_page(page_id: str) -> DocPage:
+        svc = get_docs()
+        try:
+            return await svc.archive(page_id)
+        except ValueError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    @router.get("/pages/{page_id}/versions", response_model=list[DocVersion])
+    async def get_versions(page_id: str) -> list[DocVersion]:
+        svc = get_docs()
+        return await svc.get_versions(page_id)
+
+    @router.post("/pages/{page_id}/revert", response_model=DocPage)
+    async def revert_page(page_id: str, body: RevertRequest) -> DocPage:
+        svc = get_docs()
+        try:
+            return await svc.revert(page_id, body.version)
+        except ValueError as exc:
+            raise NotFoundError(str(exc)) from exc
+
+    # ------------------------------------------------------------------
+    # Tree
+    # ------------------------------------------------------------------
+
+    @router.get("/tree", response_model=DocTree)
+    async def get_tree(category: str | None = Query(None)) -> DocTree:
+        svc = get_docs()
+        return await svc.get_tree(category=category)
+
+    # ------------------------------------------------------------------
+    # Categories
+    # ------------------------------------------------------------------
+
+    @router.get("/categories", response_model=list[DocCategory])
+    async def list_categories() -> list[DocCategory]:
+        svc = get_docs()
+        return await svc.list_categories()
+
+    @router.post("/categories", response_model=DocCategory, status_code=201)
+    async def create_category(body: CreateCategoryRequest) -> DocCategory:
+        svc = get_docs()
+        return await svc.create_category(
+            name=body.name,
+            description=body.description,
+            order=body.order,
+            parent_id=body.parent_id,
+        )
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    @router.get("/search", response_model=list[DocSearchResult])
+    async def search_docs(
+        q: str = Query(..., min_length=1),
+        limit: int = Query(20, ge=1, le=100),
+    ) -> list[DocSearchResult]:
+        svc = get_docs()
+        if svc.search is None:
+            raise BusinessLogicError("Search not enabled")
+        return svc.search.search(q, limit=limit)
+
+    return router

docs/search.py

@@ -0,0 +1,159 @@
+"""In-memory full-text search with BM25-lite scoring."""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+
+from docs.models import DocPage, DocSearchResult
+from docs.renderer import DocRenderer
+
+
+def _tokenize(text: str) -> list[str]:
+    """Split text into lowercase word tokens."""
+    return [w for w in re.findall(r"[a-z0-9]+", text.lower()) if len(w) > 1]
+
+
+@dataclass
+class _IndexedDoc:
+    """Metadata stored per indexed document."""
+
+    page_id: str
+    title: str
+    slug: str
+    category: str
+    tokens: list[str]
+    token_count: int
+    text: str
+
+
+@dataclass
+class DocSearch:
+    """In-memory inverted index with BM25-lite scoring."""
+
+    snippet_length: int = 160
+    _k1: float = 1.5
+    _b: float = 0.75
+    _documents: dict[str, _IndexedDoc] = field(default_factory=dict, repr=False)
+    _inverted: dict[str, set[str]] = field(default_factory=dict, repr=False)
+    _avg_dl: float = field(default=0.0, repr=False)
+    _renderer: DocRenderer = field(default_factory=DocRenderer, repr=False)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def index_page(self, page: DocPage) -> None:
+        """Add or update a page in the search index."""
+        self.remove_page(page.id)
+
+        rendered = self._renderer.render_markdown(page.content_markdown)
+        plain_text = self._renderer.extract_text(rendered)
+        full_text = f"{page.title} {' '.join(page.tags)} {plain_text}"
+        tokens = _tokenize(full_text)
+
+        doc = _IndexedDoc(
+            page_id=page.id,
+            title=page.title,
+            slug=page.slug,
+            category=page.category,
+            tokens=tokens,
+            token_count=len(tokens),
+            text=plain_text,
+        )
+        self._documents[page.id] = doc
+
+        for token in set(tokens):
+            self._inverted.setdefault(token, set()).add(page.id)
+
+        self._recalc_avg_dl()
+
+    def remove_page(self, page_id: str) -> None:
+        """Remove a page from the index."""
+        doc = self._documents.pop(page_id, None)
+        if doc is None:
+            return
+        for token in set(doc.tokens):
+            posting = self._inverted.get(token)
+            if posting:
+                posting.discard(page_id)
+                if not posting:
+                    del self._inverted[token]
+        self._recalc_avg_dl()
+
+    def search(self, query: str, *, limit: int = 20) -> list[DocSearchResult]:
+        """Search indexed pages, returning results sorted by BM25 score."""
+        query_tokens = _tokenize(query)
+        if not query_tokens:
+            return []
+
+        scores: dict[str, float] = {}
+        n = len(self._documents)
+        if n == 0:
+            return []
+
+        for token in query_tokens:
+            posting = self._inverted.get(token)
+            if not posting:
+                continue
+            df = len(posting)
+            idf = math.log((n - df + 0.5) / (df + 0.5) + 1.0)
+            for page_id in posting:
+                doc = self._documents[page_id]
+                tf = doc.tokens.count(token)
+                dl = doc.token_count
+                avg_dl = self._avg_dl or 1.0
+                numerator = tf * (self._k1 + 1)
+                denominator = tf + self._k1 * (1 - self._b + self._b * dl / avg_dl)
+                scores[page_id] = scores.get(page_id, 0.0) + idf * numerator / denominator
+
+        ranked = sorted(scores.items(), key=lambda x: x[1], reverse=True)[:limit]
+        results: list[DocSearchResult] = []
+        for page_id, score in ranked:
+            doc = self._documents[page_id]
+            snippet = self._build_snippet(doc.text, query_tokens)
+            results.append(
+                DocSearchResult(
+                    page_id=doc.page_id,
+                    title=doc.title,
+                    slug=doc.slug,
+                    snippet=snippet,
+                    score=round(score, 4),
+                    category=doc.category,
+                )
+            )
+        return results
+
+    @property
+    def document_count(self) -> int:
+        return len(self._documents)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _recalc_avg_dl(self) -> None:
+        docs = self._documents.values()
+        self._avg_dl = sum(d.token_count for d in docs) / max(len(self._documents), 1)
+
+    def _build_snippet(self, text: str, query_tokens: list[str]) -> str:
+        """Extract a snippet around the first query token match."""
+        lower = text.lower()
+        best_pos = len(text)
+        for token in query_tokens:
+            pos = lower.find(token)
+            if pos != -1 and pos < best_pos:
+                best_pos = pos
+
+        if best_pos == len(text):
+            return text[: self.snippet_length]
+
+        start = max(0, best_pos - 40)
+        end = start + self.snippet_length
+        snippet = text[start:end]
+        if start > 0:
+            snippet = "..." + snippet
+        if end < len(text):
+            snippet = snippet + "..."
+        return snippet

docs/service.py

@@ -0,0 +1,232 @@
+"""Business logic layer for the docs module."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from docs.config import DocsConfig
+from docs.models import (
+    DocCategory,
+    DocPage,
+    DocTree,
+    DocTreeNode,
+    DocVersion,
+    PageStatus,
+    PaginatedPages,
+    slugify,
+)
+from docs.renderer import DocRenderer
+from docs.search import DocSearch
+from docs.store import DocsStore
+from errors import NotFoundError, ValidationError
+
+
+class DocsService:
+    """Orchestrates page CRUD, versioning, search, and rendering."""
+
+    def __init__(
+        self,
+        *,
+        config: DocsConfig,
+        store: DocsStore,
+        search: DocSearch | None = None,
+    ) -> None:
+        self.config = config
+        self.store = store
+        self.search = search
+        self.renderer = DocRenderer()
+
+    # ------------------------------------------------------------------
+    # Pages
+    # ------------------------------------------------------------------
+
+    async def create_page(
+        self,
+        title: str,
+        content_markdown: str = "",
+        category: str = "",
+        *,
+        parent_id: str | None = None,
+        tags: list[str] | None = None,
+        author_id: str = "",
+        locale: str | None = None,
+    ) -> DocPage:
+        rendered = self.renderer.render_markdown(content_markdown)
+        page = DocPage(
+            title=title,
+            content_markdown=content_markdown,
+            content_html=rendered,
+            category=category,
+            parent_id=parent_id,
+            tags=tags or [],
+            author_id=author_id,
+            locale=locale or self.config.default_locale,
+        )
+        saved = await self.store.save_page(page)
+
+        if self.config.enable_versioning:
+            await self._save_version(saved, message="Initial version")
+
+        if self.search:
+            self.search.index_page(saved)
+
+        return saved
+
+    async def update_page(self, page_id: str, /, **fields: object) -> DocPage:
+        page = await self.store.get_page_by_id(page_id)
+        if page is None:
+            raise NotFoundError(f"Page not found: {page_id}")
+
+        version_message = str(fields.pop("version_message", ""))
+
+        for key, value in fields.items():
+            if value is not None and hasattr(page, key):
+                setattr(page, key, value)
+
+        if "title" in fields and fields["title"] is not None:
+            page.slug = slugify(str(fields["title"]))
+
+        if "content_markdown" in fields and fields["content_markdown"] is not None:
+            page.content_html = self.renderer.render_markdown(page.content_markdown)
+
+        page.version += 1
+        page.updated_at = datetime.now(timezone.utc)
+        saved = await self.store.save_page(page)
+
+        if self.config.enable_versioning:
+            await self._save_version(saved, message=version_message)
+
+        if self.search:
+            self.search.index_page(saved)
+
+        return saved
+
+    async def publish(self, page_id: str) -> DocPage:
+        page = await self.store.get_page_by_id(page_id)
+        if page is None:
+            raise NotFoundError(f"Page not found: {page_id}")
+        page.status = PageStatus.PUBLISHED
+        page.published_at = datetime.now(timezone.utc)
+        page.updated_at = datetime.now(timezone.utc)
+        return await self.store.save_page(page)
+
+    async def archive(self, page_id: str) -> DocPage:
+        page = await self.store.get_page_by_id(page_id)
+        if page is None:
+            raise NotFoundError(f"Page not found: {page_id}")
+        page.status = PageStatus.ARCHIVED
+        page.updated_at = datetime.now(timezone.utc)
+        saved = await self.store.save_page(page)
+
+        if self.search:
+            self.search.remove_page(page_id)
+
+        return saved
+
+    async def get_page(self, page_id_or_slug: str) -> DocPage | None:
+        page = await self.store.get_page_by_id(page_id_or_slug)
+        if page:
+            return page
+        return await self.store.get_page_by_slug(page_id_or_slug)
+
+    async def list_pages(
+        self,
+        *,
+        category: str | None = None,
+        status: PageStatus | None = None,
+        page: int = 1,
+        per_page: int = 20,
+    ) -> PaginatedPages:
+        items, total = await self.store.list_pages(
+            category=category, status=status, page=page, per_page=per_page
+        )
+        return PaginatedPages(items=items, total=total, page=page, per_page=per_page)
+
+    # ------------------------------------------------------------------
+    # Versioning
+    # ------------------------------------------------------------------
+
+    async def get_versions(self, page_id: str) -> list[DocVersion]:
+        return await self.store.get_versions(page_id)
+
+    async def revert(self, page_id: str, version: int) -> DocPage:
+        target = await self.store.get_version(page_id, version)
+        if target is None:
+            raise NotFoundError(f"Version {version} not found for page {page_id}")
+        return await self.update_page(
+            page_id,
+            content_markdown=target.content_markdown,
+            version_message=f"Reverted to version {version}",
+        )
+
+    # ------------------------------------------------------------------
+    # Ordering
+    # ------------------------------------------------------------------
+
+    async def reorder(self, page_id: str, new_order: int) -> DocPage:
+        return await self.update_page(page_id, order=new_order, version_message="Reordered")
+
+    # ------------------------------------------------------------------
+    # Navigation tree
+    # ------------------------------------------------------------------
+
+    async def get_tree(self, category: str | None = None) -> DocTree:
+        pages, _ = await self.store.list_pages(
+            category=category, status=PageStatus.PUBLISHED, per_page=10_000
+        )
+        nodes_by_id: dict[str, DocTreeNode] = {}
+        for p in pages:
+            nodes_by_id[p.id] = DocTreeNode(
+                page_id=p.id, title=p.title, slug=p.slug, order=p.order
+            )
+
+        roots: list[DocTreeNode] = []
+        for p in pages:
+            node = nodes_by_id[p.id]
+            if p.parent_id and p.parent_id in nodes_by_id:
+                nodes_by_id[p.parent_id].children.append(node)
+            else:
+                roots.append(node)
+
+        def sort_nodes(nodes: list[DocTreeNode]) -> None:
+            nodes.sort(key=lambda n: n.order)
+            for n in nodes:
+                sort_nodes(n.children)
+
+        sort_nodes(roots)
+        return DocTree(category=category or "", pages=roots)
+
+    # ------------------------------------------------------------------
+    # Categories
+    # ------------------------------------------------------------------
+
+    async def create_category(
+        self,
+        name: str,
+        *,
+        description: str = "",
+        order: int = 0,
+        parent_id: str | None = None,
+    ) -> DocCategory:
+        cat = DocCategory(name=name, description=description, order=order, parent_id=parent_id)
+        return await self.store.save_category(cat)
+
+    async def list_categories(self) -> list[DocCategory]:
+        return await self.store.list_categories()
+
+    async def get_category(self, category_id: str) -> DocCategory | None:
+        return await self.store.get_category_by_id(category_id)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    async def _save_version(self, page: DocPage, *, message: str = "") -> DocVersion:
+        version = DocVersion(
+            page_id=page.id,
+            version=page.version,
+            content_markdown=page.content_markdown,
+            author_id=page.author_id,
+            message=message,
+        )
+        return await self.store.save_version(version)

docs/store.py

@@ -0,0 +1,153 @@
+"""Persistence abstraction and in-memory implementation."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from copy import deepcopy
+
+from docs.models import (
+    DocCategory,
+    DocPage,
+    DocVersion,
+    PageStatus,
+)
+
+
+class DocsStore(ABC):
+    """Abstract base class for docs persistence."""
+
+    # -- pages ---------------------------------------------------------------
+
+    @abstractmethod
+    async def save_page(self, page: DocPage) -> DocPage: ...
+
+    @abstractmethod
+    async def get_page_by_id(self, page_id: str) -> DocPage | None: ...
+
+    @abstractmethod
+    async def get_page_by_slug(self, slug: str) -> DocPage | None: ...
+
+    @abstractmethod
+    async def list_pages(
+        self,
+        *,
+        category: str | None = None,
+        status: PageStatus | None = None,
+        parent_id: str | None = None,
+        page: int = 1,
+        per_page: int = 20,
+    ) -> tuple[list[DocPage], int]: ...
+
+    @abstractmethod
+    async def delete_page(self, page_id: str) -> bool: ...
+
+    # -- categories ----------------------------------------------------------
+
+    @abstractmethod
+    async def save_category(self, category: DocCategory) -> DocCategory: ...
+
+    @abstractmethod
+    async def get_category_by_id(self, category_id: str) -> DocCategory | None: ...
+
+    @abstractmethod
+    async def get_category_by_slug(self, slug: str) -> DocCategory | None: ...
+
+    @abstractmethod
+    async def list_categories(self) -> list[DocCategory]: ...
+
+    # -- versions ------------------------------------------------------------
+
+    @abstractmethod
+    async def save_version(self, version: DocVersion) -> DocVersion: ...
+
+    @abstractmethod
+    async def get_versions(self, page_id: str) -> list[DocVersion]: ...
+
+    @abstractmethod
+    async def get_version(self, page_id: str, version: int) -> DocVersion | None: ...
+
+
+class InMemoryStore(DocsStore):
+    """Thread-safe, dict-backed implementation for testing and lightweight use."""
+
+    def __init__(self) -> None:
+        self._pages: dict[str, DocPage] = {}
+        self._categories: dict[str, DocCategory] = {}
+        self._versions: dict[str, list[DocVersion]] = {}
+
+    # -- pages ---------------------------------------------------------------
+
+    async def save_page(self, page: DocPage) -> DocPage:
+        self._pages[page.id] = deepcopy(page)
+        return deepcopy(page)
+
+    async def get_page_by_id(self, page_id: str) -> DocPage | None:
+        page = self._pages.get(page_id)
+        return deepcopy(page) if page else None
+
+    async def get_page_by_slug(self, slug: str) -> DocPage | None:
+        for page in self._pages.values():
+            if page.slug == slug:
+                return deepcopy(page)
+        return None
+
+    async def list_pages(
+        self,
+        *,
+        category: str | None = None,
+        status: PageStatus | None = None,
+        parent_id: str | None = None,
+        page: int = 1,
+        per_page: int = 20,
+    ) -> tuple[list[DocPage], int]:
+        filtered = list(self._pages.values())
+        if category is not None:
+            filtered = [p for p in filtered if p.category == category]
+        if status is not None:
+            filtered = [p for p in filtered if p.status == status]
+        if parent_id is not None:
+            filtered = [p for p in filtered if p.parent_id == parent_id]
+        filtered.sort(key=lambda p: (p.order, p.created_at))
+        total = len(filtered)
+        start = (page - 1) * per_page
+        end = start + per_page
+        return [deepcopy(p) for p in filtered[start:end]], total
+
+    async def delete_page(self, page_id: str) -> bool:
+        return self._pages.pop(page_id, None) is not None
+
+    # -- categories ----------------------------------------------------------
+
+    async def save_category(self, category: DocCategory) -> DocCategory:
+        self._categories[category.id] = deepcopy(category)
+        return deepcopy(category)
+
+    async def get_category_by_id(self, category_id: str) -> DocCategory | None:
+        cat = self._categories.get(category_id)
+        return deepcopy(cat) if cat else None
+
+    async def get_category_by_slug(self, slug: str) -> DocCategory | None:
+        for cat in self._categories.values():
+            if cat.slug == slug:
+                return deepcopy(cat)
+        return None
+
+    async def list_categories(self) -> list[DocCategory]:
+        cats = sorted(self._categories.values(), key=lambda c: (c.order, c.name))
+        return [deepcopy(c) for c in cats]
+
+    # -- versions ------------------------------------------------------------
+
+    async def save_version(self, version: DocVersion) -> DocVersion:
+        self._versions.setdefault(version.page_id, []).append(deepcopy(version))
+        return deepcopy(version)
+
+    async def get_versions(self, page_id: str) -> list[DocVersion]:
+        versions = self._versions.get(page_id, [])
+        return [deepcopy(v) for v in sorted(versions, key=lambda v: v.version, reverse=True)]
+
+    async def get_version(self, page_id: str, version: int) -> DocVersion | None:
+        for v in self._versions.get(page_id, []):
+            if v.version == version:
+                return deepcopy(v)
+        return None

msaas_docs-0.1.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: msaas-docs
+Version: 0.1.0
+Summary: Knowledge base and documentation system for SaaS products
+Requires-Python: >=3.12
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110.0; extra == 'fastapi'

msaas_docs-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+docs/__init__.py,sha256=3L_bpn0jJPmCcRwCheQm8B9T_Lm98_U4wfIyBDiyPgY,739
+docs/config.py,sha256=Da5btnLcX3NpR4qtjp0qLF8CcpyASiQWu46-NiZhHPs,1532
+docs/models.py,sha256=dmLx27Uu-q26DcuQy8WRtD_FBjKX18yj4OmEQCgXNN4,3880
+docs/renderer.py,sha256=81koPdYk2jML0HISZ7jc8UFCwxuh82j0o81ArupaIdI,9073
+docs/router.py,sha256=2QUFCOR_qLfwtZOti1e0iY5gCVzi0DeKlKoOMhEw_sc,5324
+docs/search.py,sha256=hdqjZF0brqHeqjVmY9rG3McUI2BSX8VcGl8mC1uFjMs,5242
+docs/service.py,sha256=yedmJjUrLMSSYOPPLSmV5k1ht35FRovvkmgxB-JnOVo,7914
+docs/store.py,sha256=f07Mtswg6LYtoRCH-GlK_ZFkBNCBX_ye4JnFzCiyP44,5223
+msaas_docs-0.1.0.dist-info/METADATA,sha256=5FJlMmzbl0goONQRsRYqARQculG_uVcd8PQMpqUq0Rc,555
+msaas_docs-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+msaas_docs-0.1.0.dist-info/RECORD,,

msaas_docs-0.1.0.dist-info/WHEEL

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