docs-kit 0.1.1__py3-none-any.whl

docs_kit/cli/commands.py

@@ -0,0 +1,542 @@
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tomllib
+from pathlib import Path
+
+import click
+import tomli_w
+
+from docs_kit.cli.help import DocsKitCommand, HELP_CONTEXT_SETTINGS, format_examples
+
+INSTALL_TARGETS = [
+    "claude-code",
+    "claude-desktop",
+    "cursor",
+    "codex",
+    "codex-desktop",
+    "codex-app",
+    "chatgpt",
+    "chatgpt-desktop",
+]
+def _get_agent_class():
+    from docs_kit.agent import DocsKitAgent
+
+    return DocsKitAgent
+
+
+def _get_config_class():
+    from docs_kit.core.config import DocsKitConfig
+
+    return DocsKitConfig
+
+
+def _get_mcp_config_class():
+    from docs_kit.core.config import McpConfig
+
+    return McpConfig
+
+
+def _get_server_runners():
+    from docs_kit.mcp.server import run_stdio, run_sse
+
+    return run_stdio, run_sse
+
+
+def _get_qdrant_client_class():
+    from qdrant_client import QdrantClient
+
+    return QdrantClient
+
+
+def _load_config(config_path: str | None):
+    DocsKitConfig = _get_config_class()
+    if config_path:
+        return DocsKitConfig.from_yaml(config_path)
+    default_yaml = Path("docs-kit.yaml")
+    if default_yaml.exists():
+        return DocsKitConfig.from_yaml(default_yaml)
+    return DocsKitConfig()
+
+
+def _describe_vector_store(config) -> str:
+    if config.vector_store.url:
+        return f"remote Qdrant at {config.vector_store.url}"
+    return f"local embedded Qdrant at {config.vector_store.local_path}"
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Create a docs-kit config file.",
+    epilog=format_examples(
+        "docs-kit init",
+        "docs-kit init --dir ./sandbox",
+    ),
+)
+@click.option("--dir", "directory", default=".", help="Target directory for the config file.")
+def init_cmd(directory: str):
+    """Initialize a docs-kit project with a config file."""
+    import yaml as _yaml
+
+    dir_path = Path(directory)
+    dir_path.mkdir(parents=True, exist_ok=True)
+    config_path = dir_path / "docs-kit.yaml"
+    if config_path.exists():
+        click.echo(f"Config already exists at {config_path}")
+        return
+    DocsKitConfig = _get_config_class()
+    config = DocsKitConfig()
+    data = config.model_dump()
+    with open(config_path, "w") as f:
+        _yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+    click.echo(f"Created config at {config_path}")
+    click.echo("No API keys required — embeddings run fully locally.")
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Ingest docs from a path or URL.",
+    epilog=format_examples(
+        "docs-kit ingest ./docs",
+        "docs-kit ingest https://docs.example.com",
+        "docs-kit ingest ./docs --recreate",
+    ),
+)
+@click.argument("path")
+@click.option("--recreate", is_flag=True, help="Recreate the collection first.")
+@click.option("--provider", default="auto", show_default=True,
+              type=click.Choice(["auto", "gitbook", "mintlify"], case_sensitive=False),
+              help="Docs platform. auto tries llms.txt then sitemap.xml.")
+@click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
+def ingest_cmd(path: str, recreate: bool, provider: str, config_path: str | None):
+    """Ingest documents from a file, directory, or URL."""
+    import logging
+    logging.basicConfig(level=logging.INFO, format="%(message)s", force=True)
+
+    config = _load_config(config_path)
+    agent = _get_agent_class()(config=config)
+
+    try:
+        if path.startswith("http://") or path.startswith("https://"):
+            click.echo(f"Fetching docs from {path}...")
+            total = agent.ingest_url(path, recreate=recreate, provider=provider if provider != "auto" else None)
+        else:
+            total = agent.ingest(path, recreate=recreate)
+        click.echo(f"Total: {total} chunks ingested")
+    except (FileNotFoundError, ValueError) as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Download GitBook docs to Markdown files.",
+    epilog=format_examples(
+        "docs-kit fetch https://docs.example.com",
+        "docs-kit fetch https://docs.example.com --output ./downloaded-docs",
+    ),
+)
+@click.argument("url")
+@click.option(
+    "--output",
+    "output_dir",
+    default="docs-kit-docs",
+    show_default=True,
+    help="Output directory for downloaded .md files.",
+)
+def fetch_cmd(url: str, output_dir: str):
+    """Download docs from a GitBook URL to local .md files."""
+    from urllib.parse import urlparse
+    from docs_kit.connectors.fetchers.gitbook import GitBookFetcher
+
+    fetcher = GitBookFetcher()
+    click.echo(f"Fetching docs from {url}...")
+    try:
+        documents = fetcher.fetch(url)
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    out_path = Path(output_dir)
+    out_path.mkdir(parents=True, exist_ok=True)
+
+    for doc in documents:
+        # Derive a filename from the source URL
+        parsed = urlparse(doc.source)
+        slug = parsed.path.strip("/").replace("/", "_") or "index"
+        filename = f"{slug}.md"
+        file_path = out_path / filename
+        file_path.write_text(doc.content, encoding="utf-8")
+        click.echo(f"  Saved {file_path}")
+
+    click.echo(f"Downloaded {len(documents)} document(s) to {output_dir}/")
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Run the MCP server.",
+    epilog=format_examples(
+        "docs-kit serve",
+        "docs-kit serve --transport sse --port 3001",
+        "docs-kit serve --config ./docs-kit.yaml",
+    ),
+)
+@click.option("--transport", "transport", default=None, help="Transport to use: stdio or sse.")
+@click.option("--port", default=None, type=int, help="SSE port override.")
+@click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
+def serve_cmd(transport: str | None, port: int | None, config_path: str | None):
+    """Start the MCP server (stdio by default, --transport sse for HTTP)."""
+    config = _load_config(config_path)
+    run_stdio, run_sse = _get_server_runners()
+
+    effective_transport = transport or config.mcp.transport
+    effective_port = port or config.mcp.port
+    effective_host = config.mcp.host
+
+    if effective_transport == "sse":
+        click.echo(f"docs-kit MCP server (SSE) on {effective_host}:{effective_port}")
+        click.echo(f"Configure your agent to connect to: http://{effective_host}:{effective_port}/sse")
+        McpConfig = _get_mcp_config_class()
+        mcp_config = McpConfig(transport="sse", host=effective_host, port=effective_port)
+        overridden = config.model_copy(update={"mcp": mcp_config})
+        run_sse(overridden)
+    else:
+        # stdio: no banner — stdout is used for the MCP protocol
+        run_stdio(config)
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Show collection stats.",
+    epilog=format_examples(
+        "docs-kit inspect",
+        "docs-kit inspect --config ./docs-kit.yaml",
+    ),
+)
+@click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
+def inspect_cmd(config_path: str | None):
+    """Show collection stats and configuration."""
+    config = _load_config(config_path)
+    agent = _get_agent_class()(config=config)
+
+    stats = agent.collection_stats()
+    click.echo(f"Collection: {config.vector_store.collection_name}")
+    click.echo(f"Exists: {stats.get('collection_exists', False)}")
+    click.echo(f"Points: {stats.get('points_count', 0)}")
+    click.echo(f"Embeddings: {config.embedding.provider} ({config.embedding.model})")
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Check config and connectivity.",
+    epilog=format_examples(
+        "docs-kit doctor",
+        "docs-kit doctor --config ./docs-kit.yaml",
+    ),
+)
+@click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
+def doctor_cmd(config_path: str | None):
+    """Check environment and connectivity."""
+    config = _load_config(config_path)
+    checks = {
+        "EMBEDDING_MODEL": os.environ.get("EMBEDDING_MODEL"),
+        "VECTOR_STORE_URL": os.environ.get("VECTOR_STORE_URL"),
+    }
+
+    for key, value in checks.items():
+        if value:
+            click.echo(f"  [OK] {key} is set")
+        else:
+            click.echo(f"  [--] {key} not set")
+
+    click.echo(f"  [OK] Vector store mode: {_describe_vector_store(config)}")
+
+    if config.vector_store.url:
+        try:
+            QdrantClient = _get_qdrant_client_class()
+            client = QdrantClient(url=config.vector_store.url, timeout=3)
+            client.get_collections()
+            click.echo(f"  [OK] Qdrant reachable at {config.vector_store.url}")
+        except Exception:
+            click.echo(f"  [--] Qdrant not reachable at {config.vector_store.url}")
+
+    resolved_config_path = Path(config_path) if config_path else Path("docs-kit.yaml")
+    if resolved_config_path.exists():
+        click.echo(f"  [OK] Config file found: {resolved_config_path}")
+    else:
+        expected = "docs-kit.yaml" if config_path is None else config_path
+        click.echo(f"  [--] No config file found at {expected} (run: docs-kit init)")
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Search ingested docs.",
+    epilog=format_examples(
+        'docs-kit query "How do I authenticate?"',
+        'docs-kit query "getting started" --limit 3',
+    ),
+)
+@click.argument("text")
+@click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
+@click.option("--limit", default=None, type=int, help="Maximum chunks to return.")
+def query_cmd(text: str, config_path: str | None, limit: int | None):
+    """Run a retrieval query against the vector store (no server required)."""
+    config = _load_config(config_path)
+    agent = _get_agent_class()(config=config)
+    chunks = agent.query(text, limit=limit)
+
+    if not chunks:
+        click.echo("No results found.")
+        sys.exit(1)
+
+    for i, chunk in enumerate(chunks, start=1):
+        preview = chunk.text[:300] + "..." if len(chunk.text) > 300 else chunk.text
+        click.echo(f"[{i}] score={chunk.score:.2f}  source={chunk.source}")
+        click.echo(preview)
+        click.echo("---")
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Remove an ingested source.",
+    epilog=format_examples(
+        "docs-kit remove https://docs.example.com/page",
+        "docs-kit remove ./docs/getting-started.md",
+    ),
+)
+@click.argument("source")
+@click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
+def remove_cmd(source: str, config_path: str | None):
+    """Remove an ingested source (URL or file path) from the knowledge base."""
+    config = _load_config(config_path)
+    agent = _get_agent_class()(config=config)
+    deleted = agent.remove_source(source)
+    if deleted:
+        click.echo(f"Removed source: {source}")
+    else:
+        click.echo(f"No data found for source: {source}", err=True)
+        sys.exit(1)
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="List ingested sources.",
+    epilog=format_examples(
+        "docs-kit list",
+        "docs-kit list --config ./docs-kit.yaml",
+    ),
+)
+@click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
+def list_cmd(config_path: str | None):
+    """List all ingested sources with their ingestion dates."""
+    config = _load_config(config_path)
+    agent = _get_agent_class()(config=config)
+    entries = agent.list_sources_with_dates()
+    if not entries:
+        click.echo("No sources ingested yet.")
+        return
+    for entry in entries:
+        click.echo(f"{entry['ingested_at']}  {entry['source']}")
+
+
+def _resolve_agent_settings_path(agent: str, project: bool = False) -> Path | None:
+    import platform
+    home = Path.home()
+    system = platform.system()
+
+    if agent == "claude-code":
+        if project:
+            return Path(".claude") / "settings.json"
+        return home / ".claude" / "settings.json"
+
+    elif agent == "claude-desktop":
+        if system == "Darwin":
+            return home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+        elif system == "Windows":
+            appdata = os.environ.get("APPDATA", str(home / "AppData" / "Roaming"))
+            return Path(appdata) / "Claude" / "claude_desktop_config.json"
+        else:  # Linux
+            return home / ".config" / "Claude" / "claude_desktop_config.json"
+
+    elif agent == "cursor":
+        if system == "Darwin":
+            return home / ".cursor" / "mcp.json"
+        elif system == "Windows":
+            appdata = os.environ.get("APPDATA", str(home / "AppData" / "Roaming"))
+            return Path(appdata) / "Cursor" / "mcp.json"
+        else:  # Linux
+            return home / ".config" / "Cursor" / "mcp.json"
+
+    elif agent in {"codex", "codex-desktop", "codex-app"}:
+        return home / ".codex" / "config.toml"
+
+    return None
+
+
+def _install_json_mcp_server(settings_path: Path, server_name: str, command: str, args: list[str]) -> None:
+    import json
+    import tempfile
+
+    if settings_path.exists():
+        with open(settings_path) as f:
+            try:
+                settings = json.load(f)
+            except json.JSONDecodeError:
+                click.echo(f"Warning: {settings_path} contains invalid JSON. Creating backup and overwriting.", err=True)
+                backup = settings_path.with_suffix(".json.bak")
+                settings_path.rename(backup)
+                settings = {}
+    else:
+        settings = {}
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if "mcpServers" not in settings:
+        settings["mcpServers"] = {}
+
+    settings["mcpServers"][server_name] = {
+        "command": command,
+        "args": args,
+    }
+
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=settings_path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(tmp_fd, "w") as f:
+            json.dump(settings, f, indent=2)
+            f.write("\n")
+        Path(tmp_path).rename(settings_path)
+    except Exception:
+        os.unlink(tmp_path)
+        raise
+
+
+def _install_codex_mcp_server(settings_path: Path, server_name: str, command: str, args: list[str]) -> None:
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if settings_path.exists():
+        with open(settings_path, "rb") as f:
+            settings = tomllib.load(f)
+    else:
+        settings = {}
+
+    settings.setdefault("mcp_servers", {})
+    settings["mcp_servers"][server_name] = {
+        "command": command,
+        "args": args,
+    }
+
+    settings_path.write_text(tomli_w.dumps(settings), encoding="utf-8")
+
+
+def _print_chatgpt_remote_mcp_instructions() -> None:
+    click.echo(
+        "ChatGPT does not use a local stdio MCP config file here. "
+        "OpenAI's current docs route ChatGPT through remote MCP apps/connectors in Settings."
+    )
+    click.echo("To use docs-kit with ChatGPT, first run a remote MCP server:")
+    click.echo("  docs-kit serve --transport sse --port 3001")
+    click.echo("Then expose that server remotely and connect it from ChatGPT Settings > Apps/Connectors.")
+    click.echo("ChatGPT custom MCP apps currently require remote MCP plus search/fetch-compatible tools.")
+    sys.exit(1)
+
+
+def _resolve_command() -> tuple[str, list[str]]:
+    """Return (command, prefix_args) to use in the MCP server config entry.
+
+    Prefers the absolute path of the docs-kit binary on PATH so the entry
+    works regardless of which directory Claude Code opens. Falls back to
+    invoking the current Python interpreter as a module, which always works
+    as long as the venv Python is accessible.
+    """
+    resolved = shutil.which("docs-kit")
+    if resolved:
+        return (str(Path(resolved).resolve()), [])
+    # Fallback: python -m docs_kit (uses __main__.py in the package)
+    return (sys.executable, ["-m", "docs_kit"])
+
+
+def _print_restart_instructions(agent: str) -> None:
+    if agent == "claude-code":
+        click.echo("  Restart Claude Code or run: /mcp in the Claude Code prompt")
+    elif agent == "claude-desktop":
+        click.echo("  Restart Claude Desktop for changes to take effect.")
+    elif agent == "cursor":
+        click.echo("  Restart Cursor for changes to take effect.")
+
+
+@click.command(
+    cls=DocsKitCommand,
+    context_settings=HELP_CONTEXT_SETTINGS,
+    short_help="Install the MCP server into an agent config.",
+    epilog=format_examples(
+        "docs-kit install claude-code",
+        "docs-kit install codex",
+        "docs-kit install claude-code --project",
+        "docs-kit install cursor --config ./docs-kit.yaml",
+        "docs-kit install chatgpt",
+    ),
+)
+@click.argument("agent", type=click.Choice(INSTALL_TARGETS, case_sensitive=False))
+@click.option("--project", is_flag=True, default=False,
+              help="Install in project-level settings (claude-code only).")
+@click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
+def install_cmd(agent: str, project: bool, config_path: str | None):
+    """Install docs-kit MCP server into an AI agent's settings or config.
+
+    AGENT must be one of: claude-code, claude-desktop, cursor, codex,
+    codex-desktop, codex-app, chatgpt, chatgpt-desktop
+    """
+    normalized_agent = agent.lower()
+
+    if normalized_agent in {"chatgpt", "chatgpt-desktop"}:
+        _print_chatgpt_remote_mcp_instructions()
+
+    settings_path = _resolve_agent_settings_path(normalized_agent, project=project)
+    if settings_path is None:
+        click.echo(f"Error: Could not determine settings path for {normalized_agent!r} on this platform.", err=True)
+        sys.exit(1)
+
+    # Resolve the binary to an absolute path so the entry works from any CWD.
+    command, prefix_args = _resolve_command()
+
+    # Resolve --config to an absolute path. If not passed, auto-discover
+    # docs-kit.yaml in the current directory. Warn if neither is found on a
+    # global install, because the server will fall back to default config and
+    # may not find the user's ingested data.
+    if config_path:
+        config_path = str(Path(config_path).resolve())
+    else:
+        default_yaml = Path("docs-kit.yaml")
+        if default_yaml.exists():
+            config_path = str(default_yaml.resolve())
+        elif not project:
+            click.echo(
+                "Warning: No docs-kit.yaml found in current directory and --config not set.\n"
+                "The MCP server will use default config and may not find your ingested data.\n"
+                "Run from your project directory or pass --config /absolute/path/to/docs-kit.yaml",
+                err=True,
+            )
+
+    args = prefix_args + ["serve"]
+    if config_path:
+        args.extend(["--config", config_path])
+
+    if normalized_agent in {"codex", "codex-desktop", "codex-app"}:
+        _install_codex_mcp_server(settings_path, "docs-kit", command, args)
+        click.echo(f"✓ Installed docs-kit MCP server into {settings_path}")
+        click.echo("  Codex CLI and the Codex IDE extension share this config.")
+        return
+
+    _install_json_mcp_server(settings_path, "docs-kit", command, args)
+    click.echo(f"✓ Installed docs-kit MCP server into {settings_path}")
+    _print_restart_instructions(normalized_agent)

docs_kit/cli/help.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import inspect
+import os
+import sys
+import textwrap
+
+import click
+
+
+TERM_WIDTH = 100
+HELP_CONTEXT_SETTINGS = {
+    "help_option_names": ["--help"],
+    "max_content_width": TERM_WIDTH,
+    "terminal_width": TERM_WIDTH,
+}
+
+
+def format_examples(*lines: str) -> str:
+    return "Examples:\n" + "\n".join(f"  {line}" for line in lines)
+
+
+class _FormattedHelpMixin:
+    _term_width = 20
+    _desc_start = 22
+    _rule_width = TERM_WIDTH
+    # FIGlet font "slant" for "docs-kit" (hardcoded; no runtime figlet dependency).
+    _banner_lines = [
+        "       __                      __   _ __ ",
+        "  ____/ /___  __________      / /__(_) /_",
+        " / __  / __ \\/ ___/ ___/_____/ //_/ / __/",
+        "/ /_/ / /_/ / /__(__  )_____/ ,< / / /_  ",
+        "\\__,_/\\____/\\___/____/     /_/|_/_/\\__/  ",
+    ]
+
+    def _color_enabled(self) -> bool:
+        if os.getenv("NO_COLOR"):
+            return False
+        if os.getenv("CLICOLOR_FORCE") not in {None, "", "0"}:
+            return True
+        if os.getenv("FORCE_COLOR") not in {None, "", "0"}:
+            return True
+        return sys.stdout.isatty()
+
+    def _style(self, ctx: click.Context, text: str, **styles: str | bool) -> str:
+        if self._color_enabled():
+            return click.style(text, **styles)
+        return text
+
+    def _rule(self, ctx: click.Context, char: str = "─") -> str:
+        text = char * self._rule_width
+        if self._color_enabled():
+            return click.style(text, fg="bright_black")
+        return text
+
+    def _write_banner(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        formatter.write(f"{self._rule(ctx)}\n")
+        for line in self._banner_lines:
+            formatter.write(f"{self._style(ctx, line, fg='magenta', bold=True)}\n")
+        tagline = "Turn docs into agent-ready context."
+        formatter.write(f"{self._style(ctx, tagline, fg='bright_black', italic=True)}\n")
+        formatter.write(f"{self._rule(ctx)}\n")
+
+    def _write_section(self, ctx: click.Context, formatter: click.HelpFormatter, heading: str) -> None:
+        formatter.write_paragraph()
+        label = f"◆ {heading}"
+        formatter.write(f"{self._style(ctx, label, fg='cyan', bold=True)}\n")
+
+    def _write_definition_rows(
+        self,
+        ctx: click.Context,
+        formatter: click.HelpFormatter,
+        rows: list[tuple[str, str]],
+    ) -> None:
+        description_width = max(20, formatter.width - self._desc_start)
+        for term, description in rows:
+            wrapped = textwrap.wrap(
+                description,
+                width=description_width,
+                break_long_words=False,
+                break_on_hyphens=False,
+            ) or [""]
+            styled_term = self._style(ctx, term.ljust(self._term_width), fg="bright_green", bold=True)
+            formatter.write(f"  {styled_term}{wrapped[0]}\n")
+            for line in wrapped[1:]:
+                formatter.write(" " * self._desc_start + f"{line}\n")
+
+    def format_help_text(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        if self.help:
+            self._write_section(ctx, formatter, "Description")
+            formatter.write_text(self._style(ctx, inspect.cleandoc(self.help), fg="white"))
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        self._write_banner(ctx, formatter)
+        formatter.write_paragraph()
+        self.format_usage(ctx, formatter)
+        self.format_help_text(ctx, formatter)
+        self.format_options(ctx, formatter)
+        if isinstance(self, click.Group):
+            self.format_commands(ctx, formatter)
+        self.format_epilog(ctx, formatter)
+
+    def format_options(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        records = []
+        for param in self.get_params(ctx):
+            record = param.get_help_record(ctx)
+            if record is not None:
+                records.append(record)
+
+        if records:
+            self._write_section(ctx, formatter, "Options")
+            self._write_definition_rows(ctx, formatter, records)
+
+    def format_epilog(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        if self.epilog:
+            formatter.write_paragraph()
+            lines = self.epilog.rstrip().splitlines()
+            if not lines:
+                return
+            formatter.write(f"{self._style(ctx, f'◆ {lines[0]}', fg='yellow', bold=True)}\n")
+            for line in lines[1:]:
+                formatter.write(f"{self._style(ctx, line, fg='bright_yellow')}\n")
+
+
+class DocsKitCommand(_FormattedHelpMixin, click.Command):
+    pass
+
+
+class DocsKitGroup(_FormattedHelpMixin, click.Group):
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        rows = []
+        for subcommand in self.list_commands(ctx):
+            command = self.get_command(ctx, subcommand)
+            if command is None or command.hidden:
+                continue
+            rows.append((subcommand, command.get_short_help_str()))
+
+        if rows:
+            self._write_section(ctx, formatter, "Commands")
+            self._write_definition_rows(ctx, formatter, rows)

docs_kit/connectors/embeddings/__init__.py

@@ -0,0 +1,3 @@
+from docs_kit.connectors.embeddings.fastembed import FastEmbedDenseEmbedding, FastEmbedSparseEmbedding
+
+__all__ = ["FastEmbedDenseEmbedding", "FastEmbedSparseEmbedding"]

docs_kit/connectors/embeddings/base.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+from typing import Protocol
+from qdrant_client.models import SparseVector
+
+class DenseEmbeddingClient(Protocol):
+    def embed(self, texts: list[str]) -> list[list[float]]: ...
+
+class SparseEmbeddingClient(Protocol):
+    def embed(self, texts: list[str]) -> list[SparseVector]: ...