rekipedia 0.9.3__py3-none-any.whl

rekipedia/__init__.py

@@ -0,0 +1,2 @@
+"""rekipedia — agentic repo-to-wiki knowledge store."""
+__version__ = "0.1.0"

rekipedia/__main__.py

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

rekipedia/cli/__init__.py

@@ -0,0 +1,27 @@
+"""rekipedia CLI entry point."""
+from __future__ import annotations
+
+import click
+
+from rekipedia.cli.ask import ask_cmd
+from rekipedia.cli.embed import embed_cmd
+from rekipedia.cli.export import export_cmd
+from rekipedia.cli.init import init_cmd
+from rekipedia.cli.scan import scan_cmd
+from rekipedia.cli.serve import serve_cmd
+from rekipedia.cli.update import update_cmd
+
+
+@click.group()
+@click.version_option(package_name="rekipedia")
+def main() -> None:
+    """rekipedia — agentic repo-to-wiki knowledge store."""
+
+
+main.add_command(init_cmd)
+main.add_command(scan_cmd)
+main.add_command(update_cmd)
+main.add_command(ask_cmd)
+main.add_command(embed_cmd)
+main.add_command(export_cmd)
+main.add_command(serve_cmd)

rekipedia/cli/ask.py

@@ -0,0 +1,163 @@
+"""`rekipedia ask` — interactive grounded Q&A REPL."""
+from __future__ import annotations
+
+import os
+import sys
+import threading
+from pathlib import Path
+
+import click
+import pyfiglet
+import yaml
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.spinner import Spinner
+from rich.text import Text
+
+from rekipedia.models.contracts import LLMConfig
+
+console = Console()
+
+
+def _print_banner() -> None:
+    """Print the REKIPEDIA ASCII art banner (two-line ansi_shadow layout)."""
+    try:
+        line1 = pyfiglet.figlet_format("REKI", font="ansi_shadow").rstrip("\n")
+        line2 = pyfiglet.figlet_format("PEDIA", font="ansi_shadow").rstrip("\n")
+    except pyfiglet.FontNotFound:
+        line1 = pyfiglet.figlet_format("REKI", font="standard").rstrip("\n")
+        line2 = pyfiglet.figlet_format("PEDIA", font="standard").rstrip("\n")
+    console.print(Text(line1, style="bold cyan"))
+    console.print(Text(line2, style="bold bright_cyan"))
+    console.print("  📖  [bold cyan]Repository → Wiki[/bold cyan]  ·  [dim]powered by LLM[/dim]\n")
+
+
+def _load_config(repo: Path) -> dict:
+    cfg_path = repo / ".rekipedia" / "config.yml"
+    if cfg_path.exists():
+        return yaml.safe_load(cfg_path.read_text()) or {}
+    return {}
+
+
+def _build_llm_config(repo: Path, model: str | None) -> LLMConfig:
+    cfg = _load_config(repo)
+    llm_cfg_raw = cfg.get("llm", {})
+    return LLMConfig(
+        model=os.environ.get("REKIPEDIA_MODEL") or model or llm_cfg_raw.get("model", "ollama/llama4"),
+        api_key=os.environ.get("REKIPEDIA_API_KEY") or llm_cfg_raw.get("api_key", ""),
+        base_url=os.environ.get("REKIPEDIA_BASE_URL") or llm_cfg_raw.get("base_url", ""),
+        temperature=llm_cfg_raw.get("temperature", 0.2),
+    )
+
+
+def _answer_streaming(question: str, repo: Path, output_dir: Path, llm_config: LLMConfig) -> None:
+    """Run one Q&A turn: spinner while waiting, then stream tokens."""
+    from rekipedia.orchestrator.run_ask import stream_ask  # noqa: PLC0415
+
+    # Print question header
+    console.print(Rule(style="dim"))
+    console.print(f"[bold bright_yellow]❯[/bold bright_yellow] {question}\n")
+
+    # Phase 1: spinner until first token
+    chunks_iter = None
+
+    try:
+        chunks_iter = stream_ask(
+            question=question,
+            repo_root=repo,
+            output_dir=output_dir,
+            llm_config=llm_config,
+        )
+    except (RuntimeError, Exception) as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        return
+
+    # Show spinner while waiting for first chunk
+    spinner_text = Spinner("dots", text=Text(" Searching wiki & reasoning…", style="dim"))
+    with Live(spinner_text, console=console, refresh_per_second=12, transient=True):
+        try:
+            first_chunk = next(chunks_iter)  # type: ignore[arg-type]
+        except StopIteration:
+            first_chunk = ""
+        except Exception as exc:
+            console.print(f"[bold red]LLM error:[/bold red] {exc}")
+            return
+
+    # Phase 2: stream remaining tokens to stdout
+    console.print(Rule("[bold bright_green]◆ Answer[/bold bright_green]", style="bright_green"))
+    sys.stdout.write(first_chunk)
+    sys.stdout.flush()
+    try:
+        for chunk in chunks_iter:  # type: ignore[union-attr]
+            sys.stdout.write(chunk)
+            sys.stdout.flush()
+    except Exception as exc:
+        console.print(f"\n[bold red]Stream error:[/bold red] {exc}")
+    finally:
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+
+    console.rule(style="dim")
+
+
+@click.command("ask")
+@click.option("--question", "-q", default=None, help="Single question (non-interactive mode).")
+@click.option(
+    "--repo",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Repository root (default: current directory).",
+)
+@click.option("--model", default=None, envvar="REKIPEDIA_MODEL", help="LLM model override.")
+@click.option("--output-dir", default=None, type=click.Path(path_type=Path), help="Output directory.")
+def ask_cmd(question: str | None, repo: Path, model: str | None, output_dir: Path | None) -> None:
+    """Interactive grounded Q&A about the scanned repository.
+
+    Starts a REPL loop — ask questions until you press Ctrl+C.
+    Answers are streamed in real-time from the LLM.
+
+    \b
+    Examples:
+        rekipedia ask
+        rekipedia ask --repo ./my-project
+        rekipedia ask -q "What are the entry points?"   # single-shot
+    """
+    repo = repo.resolve()
+    output_dir = (output_dir or repo / ".rekipedia").resolve()
+    llm_config = _build_llm_config(repo, model)
+
+    if question:
+        # Single-shot mode
+        _print_banner()
+        _answer_streaming(question, repo, output_dir, llm_config)
+        return
+
+    # Interactive REPL
+    _print_banner()
+
+    wiki_dir = output_dir / "wiki"
+    panel_content = (
+        f"[bold]Model[/bold]   [cyan]{llm_config.model}[/cyan]\n"
+        f"[bold]Repo[/bold]    [cyan]{repo}[/cyan]\n"
+        f"[bold]Wiki[/bold]    [cyan]{wiki_dir}/[/cyan]\n\n"
+        "[dim]Ask anything about the codebase. Type 'exit' or Ctrl+C to quit.[/dim]"
+    )
+    console.print(Panel(panel_content, title=" rekipedia ask ", border_style="cyan"))
+    console.print()
+
+    while True:
+        try:
+            user_input = console.input("\n[bold bright_yellow]❯ [/bold bright_yellow]").strip()
+        except (KeyboardInterrupt, EOFError):
+            console.print("\n[dim]── session ended ──[/dim]")
+            break
+
+        if not user_input:
+            continue
+        if user_input.lower() in ("exit", "quit", "q"):
+            console.print("\n[dim]── session ended ──[/dim]")
+            break
+
+        _answer_streaming(user_input, repo, output_dir, llm_config)

rekipedia/cli/embed.py

@@ -0,0 +1,178 @@
+"""rekipedia embed — build / refresh the RAG FAISS index for a scanned repo.
+
+Usage:
+    rekipedia embed [REPO_PATH] [--output-dir DIR] [--model MODEL] [--top-k N]
+
+Embeds all source files in REPO_PATH into a FAISS index stored under
+.rekipedia/rag/.  Requires a prior `rekipedia scan`.
+Set REKIPEDIA_EMBED_MODEL to override the embedding model (default:
+text-embedding-3-small).
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+def _check_rag_deps() -> None:
+    """Raise a friendly error if faiss-cpu / numpy are not installed."""
+    missing = []
+    try:
+        import faiss  # noqa: F401
+    except ImportError:
+        missing.append("faiss-cpu")
+    try:
+        import numpy  # noqa: F401
+    except ImportError:
+        missing.append("numpy")
+    if missing:
+        console.print(
+            f"[bold red]Missing RAG dependencies:[/] {', '.join(missing)}\n"
+            "Install them with:\n\n"
+            "  [bold]pip install rekipedia[rag][/]\n"
+            "  or: uv add 'rekipedia[rag]'\n",
+            highlight=False,
+        )
+        raise SystemExit(1)
+
+
+@click.command("embed")
+@click.argument("repo_path", default=".", type=click.Path(exists=True, file_okay=False))
+@click.option(
+    "--output-dir",
+    default=None,
+    help="Path to .rekipedia/ directory (default: REPO_PATH/.rekipedia/)",
+)
+@click.option(
+    "--model",
+    default=None,
+    envvar="REKIPEDIA_EMBED_MODEL",
+    help="Embedding model name (e.g. text-embedding-3-small). "
+    "Can also be set via REKIPEDIA_EMBED_MODEL env var.",
+)
+@click.option(
+    "--provider",
+    default=None,
+    envvar="REKIPEDIA_EMBED_PROVIDER",
+    help="Embedding provider (e.g. openai, ollama, azure). "
+    "Combined with --model as 'provider/model' for litellm routing.",
+)
+@click.option(
+    "--api-key",
+    default=None,
+    envvar="OPENAI_API_KEY",
+    help="API key for the embedding provider.",
+)
+@click.option(
+    "--base-url",
+    default=None,
+    envvar="REKIPEDIA_BASE_URL",
+    help="Custom base URL for the embedding provider.",
+)
+@click.option(
+    "--top-k",
+    default=8,
+    show_default=True,
+    help="Number of chunks returned per query (informational only; stored in meta).",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Show debug output.")
+def embed_cmd(
+    repo_path: str,
+    output_dir: str | None,
+    model: str | None,
+    provider: str | None,
+    api_key: str | None,
+    base_url: str | None,
+    top_k: int,
+    verbose: bool,
+) -> None:
+    """Build or refresh the RAG embed index for REPO_PATH."""
+    _check_rag_deps()
+    import logging  # noqa: PLC0415
+
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.WARNING)
+
+    repo = Path(repo_path).resolve()
+    out = Path(output_dir).resolve() if output_dir else repo / ".rekipedia"
+
+    if not out.exists():
+        console.print(
+            f"[red]No .rekipedia directory found at {out}.[/red]\n"
+            "Run [bold]rekipedia scan[/bold] first."
+        )
+        sys.exit(1)
+
+    # Load config.yml first, then CLI flags / env vars override
+    from rekipedia.cli.scan import _load_config  # noqa: PLC0415
+    from rekipedia.models.contracts import LLMConfig  # noqa: PLC0415
+    from rekipedia.rag.embedder import EmbedPipeline  # noqa: PLC0415
+    from rekipedia.rag.scan_meta import patch_scan_meta  # noqa: PLC0415
+
+    cfg = _load_config(repo)
+    llm_cfg = cfg.get("llm", {})
+
+    embed_model = model or llm_cfg.get("embed_model") or "text-embedding-3-small"
+    embed_provider = provider or llm_cfg.get("embed_provider", "")
+    resolved_api_key = api_key or llm_cfg.get("embed_api_key") or llm_cfg.get("api_key", "")
+    resolved_base_url = base_url or llm_cfg.get("embed_base_url") or llm_cfg.get("base_url", "")
+
+    console.print(f"[bold cyan]rekipedia embed[/bold cyan]")
+    console.print(f"  repo       : {repo}")
+    console.print(f"  output-dir : {out}")
+    if embed_provider:
+        console.print(f"  model      : {embed_provider}/{embed_model}")
+    else:
+        console.print(f"  model      : {embed_model}")
+    console.print(f"  base_url   : {resolved_base_url or '(default: api.openai.com)'}")
+    console.print(f"  api_key    : {'(set)' if resolved_api_key else '(not set)'}")
+    console.print()
+
+    llm_config = LLMConfig(
+        api_key=resolved_api_key,
+        base_url=resolved_base_url,
+        embed_model=embed_model,
+        embed_provider=embed_provider,
+        embed_api_key=resolved_api_key,
+        embed_base_url=resolved_base_url,
+    )
+
+    pipe = EmbedPipeline(out, llm_config)
+
+    from tqdm import tqdm  # noqa: PLC0415
+
+    bar = tqdm(bar_format="  {desc}", dynamic_ncols=True, leave=False)
+
+    def _progress(msg: str) -> None:
+        bar.set_description_str(msg)
+        bar.refresh()
+
+    try:
+        n = pipe.build(repo, progress_cb=_progress)
+        bar.set_description_str(f"✅ Done — {n} chunks indexed")
+        bar.refresh()
+        bar.close()
+
+        patch_scan_meta(out, embedded=True, embed_model=embed_model)
+        meta = pipe.meta()
+
+        console.print(f"\n[green]✅ FAISS index built successfully[/green]")
+        if meta:
+            console.print(f"   chunks : {meta.get('n_chunks', n)}")
+            console.print(f"   dim    : {meta.get('dim', '?')}")
+            console.print(f"   model  : {meta.get('model', embed_model)}")
+        console.print(f"\nIndex saved to [bold]{out}/rag/[/bold]")
+    except Exception as exc:
+        bar.close()
+        console.print(f"\n[red]Embed failed:[/red] {exc}")
+        if verbose:
+            import traceback  # noqa: PLC0415
+            traceback.print_exc()
+        sys.exit(1)

rekipedia/cli/export.py

@@ -0,0 +1,200 @@
+"""rekipedia export — bundle wiki pages into a portable file.
+
+Usage:
+    rekipedia export [REPO_PATH] [--format md|zip|json] [--output PATH]
+
+Formats:
+    md   (default) — single combined Markdown file (nav_order preserved)
+    zip  — zip of wiki/*.md + diagrams/*.md + exports/manifest.json
+    json — manifest.json (already exists; this re-exports with latest metadata)
+"""
+from __future__ import annotations
+
+import json
+import sys
+import zipfile
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+_FORMAT_CHOICES = click.Choice(["md", "zip", "json"], case_sensitive=False)
+
+
+@click.command("export")
+@click.argument("repo_path", default=".", type=click.Path(exists=True, file_okay=False))
+@click.option(
+    "--output-dir",
+    default=None,
+    help="Path to .rekipedia/ directory (default: REPO_PATH/.rekipedia/)",
+)
+@click.option(
+    "--format", "fmt",
+    default="md",
+    type=_FORMAT_CHOICES,
+    show_default=True,
+    help="Output format: md (single file), zip (bundle), json (manifest only).",
+)
+@click.option(
+    "--output", "-o",
+    default=None,
+    help="Destination file path. Defaults to .rekipedia/export.<ext>.",
+)
+@click.option(
+    "--title",
+    default=None,
+    help="Title for the combined Markdown document (default: repo directory name).",
+)
+def export_cmd(
+    repo_path: str,
+    output_dir: str | None,
+    fmt: str,
+    output: str | None,
+    title: str | None,
+) -> None:
+    """Export the wiki to a portable file.
+
+    \b
+    Examples:
+        rekipedia export .
+        rekipedia export . --format zip -o wiki.zip
+        rekipedia export . --format md -o WIKI.md
+    """
+    repo = Path(repo_path).resolve()
+    out_dir = Path(output_dir).resolve() if output_dir else repo / ".rekipedia"
+
+    wiki_dir = out_dir / "wiki"
+    diagrams_dir = out_dir / "diagrams"
+    manifest_path = out_dir / "exports" / "manifest.json"
+
+    if not wiki_dir.exists():
+        console.print(
+            f"[red]No wiki/ directory found at {wiki_dir}.[/red]\n"
+            "Run [bold]rekipedia scan[/bold] first."
+        )
+        sys.exit(1)
+
+    # Load manifest for nav_order + page metadata
+    nav_order: list[str] = []
+    pages_meta: dict[str, dict] = {}
+    if manifest_path.exists():
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+            nav_order = manifest.get("nav_order", [])
+            for p in manifest.get("pages", []):
+                pages_meta[p["slug"]] = p
+        except Exception:
+            pass
+
+    # Collect all wiki pages in nav order
+    all_pages = sorted(wiki_dir.glob("*.md"))
+    if nav_order:
+        # Sort by nav_order, append any not in nav_order alphabetically
+        ordered = []
+        slug_map = {p.stem: p for p in all_pages}
+        for slug in nav_order:
+            if slug in slug_map:
+                ordered.append(slug_map[slug])
+        remaining = [p for p in all_pages if p.stem not in set(nav_order)]
+        all_pages = ordered + remaining
+
+    doc_title = title or repo.name
+    fmt = fmt.lower()
+    ext = {"md": "md", "zip": "zip", "json": "json"}[fmt]
+
+    dest = Path(output) if output else out_dir / f"export.{ext}"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    if fmt == "md":
+        _export_md(all_pages, dest, doc_title, pages_meta)
+    elif fmt == "zip":
+        _export_zip(all_pages, diagrams_dir, manifest_path, dest, doc_title)
+    elif fmt == "json":
+        if not manifest_path.exists():
+            console.print("[red]No manifest.json found. Run rekipedia scan first.[/red]")
+            sys.exit(1)
+        import shutil  # noqa: PLC0415
+        shutil.copy2(manifest_path, dest)
+
+    size_kb = dest.stat().st_size / 1024
+    console.print(f"[green]✅ Exported {fmt.upper()}[/green] → [bold]{dest}[/bold] ({size_kb:.1f} KB)")
+    if fmt == "md":
+        console.print(f"   pages  : {len(all_pages)}")
+    elif fmt == "zip":
+        with zipfile.ZipFile(dest) as z:
+            console.print(f"   files  : {len(z.namelist())}")
+
+
+# ---------------------------------------------------------------------------
+# Format implementations
+# ---------------------------------------------------------------------------
+
+def _export_md(
+    pages: list[Path],
+    dest: Path,
+    title: str,
+    pages_meta: dict[str, dict],
+) -> None:
+    """Write a single combined Markdown file with a TOC."""
+    lines: list[str] = [f"# {title}\n", "\n## Table of Contents\n"]
+
+    # TOC
+    for p in pages:
+        slug = p.stem
+        meta = pages_meta.get(slug, {})
+        display_title = meta.get("title", slug.replace("-", " ").title())
+        importance = meta.get("importance", "")
+        imp_badge = f" *(importance: {importance})*" if importance else ""
+        anchor = slug.replace(" ", "-").lower()
+        lines.append(f"- [{display_title}](#{anchor}){imp_badge}\n")
+
+    lines.append("\n---\n\n")
+
+    # Pages
+    for p in pages:
+        slug = p.stem
+        meta = pages_meta.get(slug, {})
+        display_title = meta.get("title", slug.replace("-", " ").title())
+        content = p.read_text(encoding="utf-8").strip()
+
+        # Add section header with anchor
+        lines.append(f'<a id="{slug}"></a>\n\n')
+        lines.append(f"## {display_title}\n\n")
+
+        # Importance + tags badge line
+        badges: list[str] = []
+        if "importance" in meta:
+            badges.append(f"importance: **{meta['importance']}**")
+        if "section" in meta:
+            badges.append(f"section: `{meta['section']}`")
+        if "tags" in meta and meta["tags"]:
+            badges.append("tags: " + ", ".join(f"`{t}`" for t in meta["tags"]))
+        if badges:
+            lines.append("> " + " · ".join(badges) + "\n\n")
+
+        lines.append(content + "\n\n---\n\n")
+
+    dest.write_text("".join(lines), encoding="utf-8")
+
+
+def _export_zip(
+    pages: list[Path],
+    diagrams_dir: Path,
+    manifest_path: Path,
+    dest: Path,
+    title: str,
+) -> None:
+    """Bundle wiki pages + diagrams + manifest into a zip file."""
+    with zipfile.ZipFile(dest, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for p in pages:
+            zf.write(p, arcname=f"wiki/{p.name}")
+        if diagrams_dir.exists():
+            for d in sorted(diagrams_dir.glob("*.md")):
+                zf.write(d, arcname=f"diagrams/{d.name}")
+        if manifest_path.exists():
+            zf.write(manifest_path, arcname="manifest.json")
+        # Include a README pointing to the index page
+        readme = f"# {title}\n\nGenerated by rekipedia.\n\nOpen `wiki/index.md` to start reading.\n"
+        zf.writestr("README.md", readme)

rekipedia/cli/init.py

@@ -0,0 +1,83 @@
+"""`rekipedia init` command — scaffold the .rekipedia/ bundle in a repo."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+console = Console()
+
+_DEFAULT_CONFIG: dict = {
+    "version": 1,
+    "ignore": [
+        ".git",
+        "node_modules",
+        "__pycache__",
+        ".rekipedia",
+    ],
+    "languages": ["python", "typescript"],
+    "llm": {
+        "model": "ollama/llama4",
+        "api_key": "",
+        "base_url": "",
+        "temperature": 0.2,
+    },
+}
+
+_GITIGNORE_ENTRY = ".rekipedia/store.db\n"
+
+
+def run_init(repo_path: Path) -> None:
+    wiki_dir = repo_path / ".rekipedia"
+    config_path = wiki_dir / "config.yml"
+    gitignore_path = repo_path / ".gitignore"
+
+    # Create .rekipedia/ if missing
+    wiki_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write config.yml — idempotent (skip if already present)
+    if config_path.exists():
+        console.print(
+            f"[yellow]⚠[/yellow]  [bold]{config_path}[/bold] already exists — skipping."
+        )
+    else:
+        config_path.write_text(
+            yaml.dump(_DEFAULT_CONFIG, default_flow_style=False, sort_keys=False),
+            encoding="utf-8",
+        )
+        console.print(f"[green]✔[/green]  Created [bold]{config_path}[/bold]")
+
+    # Append .gitignore entry — idempotent
+    if gitignore_path.exists():
+        existing = gitignore_path.read_text(encoding="utf-8")
+        if ".rekipedia/store.db" in existing:
+            console.print(
+                "[yellow]⚠[/yellow]  .gitignore already contains .rekipedia/store.db — skipping."
+            )
+        else:
+            with gitignore_path.open("a", encoding="utf-8") as fh:
+                fh.write(_GITIGNORE_ENTRY)
+            console.print("[green]✔[/green]  Added .rekipedia/store.db to .gitignore")
+    else:
+        gitignore_path.write_text(_GITIGNORE_ENTRY, encoding="utf-8")
+        console.print("[green]✔[/green]  Created .gitignore with .rekipedia/store.db")
+
+    console.print()
+    console.print("[bold green]rekipedia initialised.[/bold green]")
+    console.print(
+        f"  Edit [cyan]{config_path}[/cyan] to choose your LLM provider/model, then run:"
+    )
+    console.print("  [bold]rekipedia scan .[/bold]")
+
+
+@click.command("init")
+@click.argument(
+    "repo",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+)
+def init_cmd(repo: Path) -> None:
+    """Initialise rekipedia in REPO (default: current directory)."""
+    run_init(repo.resolve())