intentic-ike 0.2.0__py3-none-any.whl

ike/__init__.py

@@ -0,0 +1,3 @@
+"""intentic Knowledge Engine — context-efficient knowledge serving for AI agents."""
+
+__version__ = "0.1.0"

ike/__main__.py

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

ike/cli.py

@@ -0,0 +1,56 @@
+"""ike CLI — dynamic command loading from ike/commands/.
+
+Each *_cmd.py in ike/commands/ exports a Click command as `cmd`.
+Commands are auto-discovered at CLI startup.
+"""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+
+import click
+
+from .core.engine import Engine
+
+
+class DynamicGroup(click.Group):
+    """Click group that auto-discovers commands from ike/commands/*_cmd.py."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._load_commands()
+
+    def _load_commands(self) -> None:
+        commands_dir = Path(__file__).parent / "commands"
+        if not commands_dir.exists():
+            return
+        for f in sorted(commands_dir.glob("*_cmd.py")):
+            name = f.stem.removesuffix("_cmd").replace("_", "-")
+            try:
+                mod = importlib.import_module(f"ike.commands.{f.stem}")
+                if hasattr(mod, "cmd"):
+                    self.add_command(mod.cmd, name)
+            except Exception:
+                pass  # Graceful: skip broken commands
+
+
+@click.group(cls=DynamicGroup)
+@click.version_option(package_name="intentic-ike")
+@click.option(
+    "--kb-root",
+    type=click.Path(),
+    default=None,
+    envvar="IKE_KB_ROOT",
+    help="KB root directory (default: ~/intentic-kb)",
+)
+@click.pass_context
+def cli(ctx: click.Context, kb_root: str | None) -> None:
+    """ike — intentic Knowledge Engine."""
+    ctx.ensure_object(dict)
+    kb = Path(kb_root).expanduser() if kb_root else None
+    ctx.obj["kb_root"] = kb
+    try:
+        ctx.obj["engine"] = Engine(kb_root=kb)
+    except Exception:
+        ctx.obj["engine"] = None

ike/commands/__init__.py

@@ -0,0 +1,2 @@
+# ike/commands/ — Dynamic CLI command modules.
+# Each *_cmd.py must export a Click command as `cmd`.

ike/commands/doctor_cmd.py

@@ -0,0 +1,33 @@
+"""ike doctor — auto-fix missing frontmatter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+
+@click.command()
+@click.option("--yes", "auto_fix", is_flag=True, help="Apply all fixes without prompting")
+@click.option(
+    "--kb-root",
+    type=click.Path(exists=True),
+    default=None,
+    help="KB root (defaults to --kb-root from parent group or IKE_KB_ROOT)",
+)
+@click.pass_context
+def cmd(ctx: click.Context, auto_fix: bool, kb_root: str | None) -> None:
+    """Auto-fix missing frontmatter in KB documents."""
+    from ike.core.doctor import run_doctor
+
+    if kb_root:
+        kb = Path(kb_root).resolve()
+    else:
+        kb = ctx.obj.get("kb_root")
+        if kb is None:
+            kb = Path.home() / "intentic-kb"
+
+    fixed = run_doctor(kb, auto_fix=auto_fix)
+    click.echo(f"\nFixed {fixed} file(s).")
+    if fixed > 0:
+        click.echo("Run `ike lint` to verify.")

ike/commands/fetch_cmd.py

@@ -0,0 +1,22 @@
+"""Load KB content (entire file or specific section)."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command()
+@click.argument("file_path")
+@click.option("--section", default=None, help="Section ID to fetch")
+@click.pass_context
+def cmd(ctx: click.Context, file_path: str, section: str | None) -> None:
+    """Load KB content (entire file or specific section)."""
+    try:
+        result = ctx.obj["engine"].fetch(file_path, section)
+        click.echo(result.content)
+    except KeyError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+    except FileNotFoundError:
+        click.echo(f"Error: File not found: {file_path}", err=True)
+        raise SystemExit(1)

ike/commands/flag_stale_cmd.py

@@ -0,0 +1,19 @@
+"""Flag a section as stale."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command("flag-stale")
+@click.argument("file_path")
+@click.option("--section", required=True, help="Section ID to flag")
+@click.option("--reason", required=True, help="Why the section is stale")
+@click.pass_context
+def cmd(ctx: click.Context, file_path: str, section: str, reason: str) -> None:
+    """Flag a section as stale."""
+    result = ctx.obj["engine"].flag_stale(file_path, section, reason)
+    if not result.success:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)
+    click.echo(f"Flagged {file_path}#{section} as stale: {reason}")

ike/commands/index_cmd.py

@@ -0,0 +1,19 @@
+"""Build or rebuild the search index."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command()
+@click.option("--rebuild", is_flag=True, help="Full rebuild (drop + reindex)")
+@click.pass_context
+def cmd(ctx: click.Context, rebuild: bool) -> None:
+    """Build or rebuild the search index."""
+    engine = ctx.obj["engine"]
+    if rebuild:
+        n = engine.rebuild_index()
+        click.echo(f"Index rebuilt: {n} chunks indexed.")
+    else:
+        engine.index.ensure_fresh(engine.parser)
+        click.echo("Index is fresh.")

ike/commands/init_cmd.py

@@ -0,0 +1,37 @@
+"""ike init — bootstrap ike for a repository."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+
+@click.command()
+@click.option(
+    "--kb-root",
+    type=click.Path(exists=True),
+    required=True,
+    help="Path to the knowledge base directory",
+)
+@click.pass_context
+def cmd(ctx: click.Context, kb_root: str) -> None:
+    """Bootstrap ike for a repository. Scans docs and generates discovery artifacts."""
+    from ike.core.init import run_init
+
+    kb = Path(kb_root).resolve()
+    cwd = Path.cwd()
+
+    result = run_init(kb, cwd)
+
+    click.echo(f"Found {result['total']} markdown files in {kb}")
+    click.echo()
+    click.echo("Quality Report:")
+    click.echo(f"  {result['ready']} ready")
+    click.echo(f"  {result['fixable']} fixable       (run `ike doctor` to fix)")
+    click.echo(f"  {result['needs_review']} need review")
+    click.echo()
+    for a in result["artifacts"]:
+        click.echo(f"Created: {a}")
+    click.echo()
+    click.echo("Restart your AI tool to activate ike MCP.")

ike/commands/lint_cmd.py

@@ -0,0 +1,19 @@
+"""Run consistency checks on the KB."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command()
+@click.option("--freshness", type=int, default=None, help="Flag docs older than N days")
+@click.pass_context
+def cmd(ctx: click.Context, freshness: int | None) -> None:
+    """Run consistency checks on the KB."""
+    findings = ctx.obj["engine"].lint(freshness)
+    if not findings:
+        click.echo("No issues found.")
+        return
+    for f in findings:
+        click.echo(f"[{f.severity}] {f.file_path}: {f.check} — {f.message}")
+    click.echo(f"\n{len(findings)} issue(s) found.")

ike/commands/list_cmd.py

@@ -0,0 +1,17 @@
+"""List all KB documents and sections."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command("list")
+@click.option("--type", "knowledge_type", default=None, help="Filter by type")
+@click.pass_context
+def cmd(ctx: click.Context, knowledge_type: str | None) -> None:
+    """List all KB documents and sections."""
+    chunks = ctx.obj["engine"].list_docs(knowledge_type)
+    for c in chunks:
+        section = f"#{c.section_id}" if c.section_id else ""
+        click.echo(f"{c.file_path}{section} ({c.token_count} tokens)")
+    click.echo(f"\n{len(chunks)} section(s).")

ike/commands/migrate_mcp_cmd.py

@@ -0,0 +1,30 @@
+"""ike migrate-mcp — migrate .mcp.json to portable pattern."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+
+@click.command("migrate-mcp")
+@click.option("--dry-run", is_flag=True, help="Show changes without applying")
+def cmd(dry_run: bool) -> None:
+    """Migrate .mcp.json from absolute paths to portable uvx/pipx pattern."""
+    from ike.core.migrate import run_migrate_mcp
+
+    result = run_migrate_mcp(Path.cwd(), dry_run=dry_run)
+
+    if not result["changed"]:
+        click.echo(f"No migration needed: {result.get('reason', 'unknown')}")
+        return
+
+    if dry_run:
+        click.echo("DRY RUN — would change:")
+        click.echo(f"  Old: {json.dumps(result['old'], indent=2)}")
+        click.echo(f"  New: {json.dumps(result['new'], indent=2)}")
+    else:
+        click.echo("Migrated .mcp.json:")
+        click.echo(f"  Old command: {result['old'].get('command')}")
+        click.echo(f"  New command: {result['new'].get('command')}")

ike/commands/query_cmd.py

@@ -0,0 +1,20 @@
+"""Route + fetch in one step."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command()
+@click.argument("query_text")
+@click.option("--depth", type=click.Choice(["shallow", "deep"]), default="shallow")
+@click.option("--limit", default=5)
+@click.pass_context
+def cmd(ctx: click.Context, query_text: str, depth: str, limit: int) -> None:
+    """Route + fetch in one step."""
+    results = ctx.obj["engine"].query_and_fetch(query_text, depth, limit)
+    for r in results:
+        section_label = f"#{r.section_id}" if r.section_id else ""
+        click.echo(f"--- {r.file_path}{section_label} ({r.token_count} tokens) ---")
+        click.echo(r.content)
+        click.echo()

ike/commands/route_cmd.py

@@ -0,0 +1,19 @@
+"""Route a query to relevant KB sections."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+import click
+
+
+@click.command()
+@click.argument("query_text")
+@click.option("--limit", default=10, help="Max results")
+@click.option("--type", "knowledge_type", default=None, help="Filter by type")
+@click.pass_context
+def cmd(ctx: click.Context, query_text: str, limit: int, knowledge_type: str | None) -> None:
+    """Find relevant KB sections. Returns paths + token counts."""
+    result = ctx.obj["engine"].route(query_text, limit, knowledge_type)
+    click.echo(json.dumps(asdict(result), indent=2))

ike/commands/serve_cmd.py

@@ -0,0 +1,17 @@
+"""ike serve — start the MCP server.
+
+CRITICAL: No top-level imports of fastmcp or ike.mcp_server.
+CRITICAL: No print(), sys.stdout.write(), or click.echo() — stdout is for JSON-RPC.
+"""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command()
+def cmd() -> None:
+    """Start the ike MCP server (stdio transport)."""
+    from ike.core.serve import run_serve
+
+    run_serve()

ike/commands/write_cmd.py

@@ -0,0 +1,38 @@
+"""Modify KB content. Content is read from stdin."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+
+@click.command("write")
+@click.option("--file", "file_path", required=True, help="File to modify")
+@click.option("--mode", type=click.Choice(["append", "replace"]), required=True)
+@click.option("--section", default=None, help="Section ID (required for replace)")
+@click.option("--agent-id", default="manual", help="Agent identifier for git commit")
+@click.option("--no-commit", is_flag=True, help="Skip git commit")
+@click.pass_context
+def cmd(
+    ctx: click.Context,
+    file_path: str,
+    mode: str,
+    section: str | None,
+    agent_id: str,
+    no_commit: bool,
+) -> None:
+    """Modify KB content. Content is read from stdin."""
+    content = sys.stdin.read()
+    if not content.strip():
+        click.echo("Error: No content provided via stdin", err=True)
+        raise SystemExit(1)
+
+    result = ctx.obj["engine"].write(
+        file_path, content, mode, section, agent_id, not no_commit
+    )
+    if not result.success:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)
+
+    click.echo(f"Written to {result.file_path} (mode={result.mode}, committed={result.committed})")

ike/core/artifacts.py

@@ -0,0 +1,146 @@
+"""Generate discovery artifacts for AI tools (.mcp.json, AGENTS.md, etc.)."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+
+def _detect_runner() -> tuple[str, list[str]]:
+    """Detect best available runner: uvx > pipx > python3 -m."""
+    if shutil.which("uvx"):
+        return "uvx", ["--from", "intentic-ike[mcp]", "ike", "serve"]
+    if shutil.which("pipx"):
+        return "pipx", ["run", "intentic-ike[mcp]", "serve"]
+    return "ike", ["serve"]
+
+
+def generate_mcp_json(target: Path) -> Path:
+    """Generate or merge ike entry into .mcp.json."""
+    mcp_path = target / ".mcp.json"
+    runner_cmd, runner_args = _detect_runner()
+
+    ike_entry = {
+        "command": runner_cmd,
+        "args": runner_args,
+    }
+
+    if mcp_path.exists():
+        data = json.loads(mcp_path.read_text(encoding="utf-8"))
+    else:
+        data = {}
+
+    data.setdefault("mcpServers", {})
+    data["mcpServers"]["ike"] = ike_entry
+
+    mcp_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return mcp_path
+
+
+def generate_agents_md(kb_root: Path, target: Path) -> Path:
+    """Generate AGENTS.md for AI tool discovery."""
+    agents_path = target / "AGENTS.md"
+    kb_name = kb_root.name
+
+    content = f"""# ike — intentic Knowledge Engine
+
+This repository uses **ike** to make its knowledge base queryable by AI tools.
+ike indexes the `{kb_name}/` directory and serves content via 2-step retrieval.
+
+## How to query (CLI)
+
+**IMPORTANT:** `ike route` returns file paths relative to the KB root. Use those
+EXACT paths with `ike fetch` — do NOT prepend the KB directory name.
+
+```bash
+# Step 1: Find relevant sections
+ike route "your question"
+# Returns: {{"file_path": "architecture/auth.md", "section_id": "rate-limiting", ...}}
+
+# Step 2: Fetch using the EXACT file_path from route results
+ike fetch architecture/auth.md --section rate-limiting
+
+# Or combine both steps:
+ike query "your question" --depth deep
+```
+
+### All CLI commands
+
+| Command | Purpose |
+|---------|---------|
+| `ike route "query"` | Find relevant sections (returns paths + token counts) |
+| `ike fetch <path>` | Load entire file (path from route results) |
+| `ike fetch <path> --section <id>` | Load specific section |
+| `ike query "text" --depth deep` | Route + fetch combined |
+| `ike lint` | Check KB consistency |
+| `ike list` | List all indexed sections with paths |
+
+## How to query (MCP)
+
+For MCP-capable tools (Claude Code, Cursor, Windsurf, Zed), the server is
+configured in `.mcp.json`. Available tools:
+
+| Tool | Description |
+|------|-------------|
+| `route(query, limit)` | Find relevant sections (~100 tokens) |
+| `fetch(file_path, section_id)` | Load content (use paths from route) |
+| `query(query_text, depth)` | Route + fetch in one step |
+| `lint(freshness_days)` | Check KB health |
+
+## Example workflow
+
+```bash
+$ ike route "authentication"
+  architecture/auth.md#api-keys           (score: 3, 120 tokens)
+  architecture/auth.md#oauth2-flow        (score: 2, 150 tokens)
+  architecture/auth.md#rate-limiting      (score: 1, 80 tokens)
+
+$ ike fetch architecture/auth.md --section rate-limiting
+## Rate Limiting
+| Tier | Requests/min | Burst |
+...
+```
+
+## Knowledge Base
+
+- **Root:** `{kb_name}/`
+- **Paths:** All file_paths in ike are relative to this root
+- **Format:** Markdown with YAML frontmatter (title, domain, summary)
+"""
+    agents_path.write_text(content, encoding="utf-8")
+    return agents_path
+
+
+def generate_cursorrules(target: Path) -> Path:
+    """Generate or append ike snippet to .cursorrules."""
+    rules_path = target / ".cursorrules"
+
+    snippet = """
+# ike Knowledge Engine
+# Use `ike route "query"` to find relevant KB sections, then `ike fetch <path>` to load content.
+# MCP tools are also available if configured in .mcp.json.
+"""
+
+    if rules_path.exists():
+        existing = rules_path.read_text(encoding="utf-8")
+        if "ike" not in existing:
+            rules_path.write_text(existing.rstrip() + "\n" + snippet, encoding="utf-8")
+    else:
+        rules_path.write_text(snippet.lstrip(), encoding="utf-8")
+    return rules_path
+
+
+def generate_llms_txt(kb_root: Path, target: Path) -> Path:
+    """Generate llms.txt listing KB structure."""
+    llms_path = target / "llms.txt"
+    lines = [f"# {kb_root.name} Knowledge Base", "", "## Documents", ""]
+
+    for md in sorted(kb_root.rglob("*.md")):
+        if md.name.startswith("."):
+            continue
+        rel = md.relative_to(kb_root)
+        lines.append(f"- {rel}")
+
+    llms_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return llms_path