intentic-ike 0.2.0__tar.gz

intentic_ike-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 intentic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

intentic_ike-0.2.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: intentic-ike
+Version: 0.2.0
+Summary: intentic Knowledge Engine — context-efficient knowledge serving for AI agents
+Author-email: intentic <hello@intentic.io>
+License: MIT
+Project-URL: Homepage, https://github.com/pedrams/ike
+Project-URL: Repository, https://github.com/pedrams/ike
+Keywords: knowledge-engine,mcp,ai-agents,knowledge-base,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: tiktoken>=0.8
+Requires-Dist: filelock>=3.16
+Requires-Dist: mdformat>=0.7.17
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == "mcp"
+Dynamic: license-file

intentic_ike-0.2.0/README.md

@@ -0,0 +1,262 @@
+# ike — intentic Knowledge Engine
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://python.org)
+[![PyPI](https://img.shields.io/badge/pypi-intentic--ike-orange.svg)](https://pypi.org/project/intentic-ike/)
+
+**Make your Markdown knowledge base queryable by any AI tool — in one command.**
+
+```bash
+pip install intentic-ike[mcp]
+ike init --kb-root ./docs
+```
+
+ike scans your docs, fixes quality issues, and generates config files so that Claude Code, Cursor, Codex, Windsurf, and every other AI coding tool can query your knowledge base with precision.
+
+**Before ike:** Your AI tool reads entire files, wastes context, gets confused.
+**After ike:** Your AI tool asks for exactly the section it needs. 77-94% fewer tokens.
+
+```
+# Without ike: 17,490 tokens (4 full files dumped into context)
+$ cat company/vision.md company/icp.md company/positioning.md company/messaging.md | wc -w
+
+# With ike: 3,969 tokens (8 targeted sections)
+$ ike route "ICP definition"
+→ company/icp-definition.md#ideal-customer-profile-icp (2,836 tokens)
+$ ike fetch company/icp-definition.md --section ideal-customer-profile-icp
+```
+
+## Quick Start
+
+### Option A: Let your AI tool do it
+
+Open your AI editor and paste this prompt:
+
+<details>
+<summary><strong>Copy this prompt into Claude Code, Cursor, Codex, or any AI coding tool</strong></summary>
+
+```
+I need to set up ike (intentic Knowledge Engine) to make this repository's
+documentation queryable by AI tools.
+
+ike is a CLI + MCP server that indexes Markdown files and serves them via
+2-step retrieval: route (find relevant sections, ~100 tokens) then fetch
+(load specific content). This is much more efficient than reading entire
+files — 77-94% token savings.
+
+Repo: https://github.com/pedrams/ike
+Docs: https://github.com/pedrams/ike/blob/main/docs/build-with-ai.md
+
+Please do the following:
+
+1. INSTALL: Run `pip install intentic-ike[mcp]`
+   - Requires Python 3.12+
+   - The [mcp] extra includes the MCP server for IDE integration
+
+2. FIND MY DOCS: Look for the directory containing my Markdown documentation.
+   Common locations: ./docs, ./knowledge, ./wiki, or the repo root.
+   List the .md files you find so I can confirm.
+
+3. INITIALIZE: Run `ike init --kb-root <path-to-docs>`
+   This will:
+   - Scan all .md files and report quality (ready/fixable/needs review)
+   - Generate .mcp.json (MCP server config for Claude Code, Cursor, etc.)
+   - Generate AGENTS.md (universal AI tool discovery file)
+   If .mcp.json already exists, ike merges — it won't overwrite your config.
+
+4. FIX DOCS: Run `ike doctor --yes`
+   This auto-adds missing YAML frontmatter (title, domain, summary) to docs
+   that need it. Only metadata is added — document content is never changed.
+   If you prefer to review each fix: run `ike doctor` without --yes.
+
+5. VERIFY: Run these commands and show me the output:
+   - `ike route "test"` — should return matching sections with token counts
+   - `ike lint` — should show remaining quality issues (if any)
+   - `cat .mcp.json` — should show the MCP server config
+   - `cat AGENTS.md` — should show the AI tool discovery file
+
+6. DONE: Tell me to restart my AI tool so the MCP connection activates.
+
+If any step fails:
+- "ike: command not found" → pip install didn't work, try: python -m ike --help
+- "ike serve fails with ImportError" → install with MCP: pip install intentic-ike[mcp]
+- "route returns no results" → run: ike index --rebuild
+- "doctor changes too much" → use: ike doctor (interactive) instead of --yes
+```
+
+</details>
+
+### Option B: Manual setup (4 commands)
+
+```bash
+pip install intentic-ike[mcp]       # 1. Install
+cd ~/my-repo
+ike init --kb-root ./docs           # 2. Scan docs, generate .mcp.json + AGENTS.md
+ike doctor --yes                    # 3. Fix missing frontmatter
+ike route "test"                    # 4. Verify
+# Restart your AI tool
+```
+
+## How It Works
+
+**2-step retrieval:** Route first (~100 tokens), then fetch only what you need.
+
+```bash
+# Step 1: Find relevant sections
+$ ike route "deployment strategy"
+{
+  "chunks": [
+    {"file_path": "engineering/architecture.md",
+     "section_id": "deployment", "score": 3.0, "token_count": 842}
+  ]
+}
+
+# Step 2: Load only what you need
+$ ike fetch engineering/architecture.md --section deployment
+## Deployment
+CI/CD pipeline deploys to Hetzner Cloud...
+```
+
+The AI tool decides what to load based on token counts. No context wasted.
+
+## AI Tool Compatibility
+
+ike generates discovery files for every major AI coding tool:
+
+| AI Tool | How it discovers ike | Generated by |
+|---------|---------------------|-------------|
+| **Claude Code** | `.mcp.json` + `AGENTS.md` | `ike init` |
+| **Cursor** | `.mcp.json` + `AGENTS.md` | `ike init` |
+| **Codex** (OpenAI) | `AGENTS.md` | `ike init` |
+| **Windsurf** | `.mcp.json` + `AGENTS.md` | `ike init` |
+| **Claude Desktop** | `.mcp.json` | `ike init` |
+| **OpenCode** | `AGENTS.md` | `ike init` |
+| **Hermes** | `.mcp.json` + `AGENTS.md` | `ike init` |
+| **VS Code + Copilot** | `.mcp.json` | `ike init` |
+| **Zed** | `.mcp.json` | `ike init` |
+| **Aider** | `AGENTS.md` | `ike init` |
+
+**MCP tools** (for MCP-capable editors): `route`, `fetch`, `query`, `lint`
+**CLI commands** (for everything else): `ike route`, `ike fetch`, `ike query`, `ike lint`
+
+## Commands
+
+### Setup
+
+| Command | What it does |
+|---------|-------------|
+| `ike init --kb-root ./docs` | Scan docs, generate `.mcp.json` + `AGENTS.md` |
+| `ike doctor --yes` | Auto-fix missing frontmatter |
+| `ike doctor` | Interactive frontmatter fix (review each) |
+| `ike serve` | Start MCP server (stdio transport) |
+| `ike migrate-mcp` | Migrate old `.mcp.json` to portable format |
+
+### Query
+
+| Command | What it does |
+|---------|-------------|
+| `ike route "query"` | Find relevant sections (~100 tokens response) |
+| `ike fetch path/file.md` | Load entire file |
+| `ike fetch path/file.md --section id` | Load specific section |
+| `ike query "text" --depth deep` | Route + fetch in one step |
+
+### Maintenance
+
+| Command | What it does |
+|---------|-------------|
+| `ike lint` | Check for missing frontmatter, broken refs, orphans |
+| `ike lint --freshness 30` | Also flag docs older than 30 days |
+| `ike list` | List all indexed sections |
+| `ike index --rebuild` | Rebuild search index |
+
+### Global options
+
+```bash
+ike --kb-root /path/to/kb route "query"   # custom KB root
+export IKE_KB_ROOT=/path/to/kb            # or via env var
+ike --version                             # show version
+```
+
+## Context Efficiency
+
+Tested against a real 81-doc knowledge base:
+
+| Scenario | Without ike | With ike | Savings |
+|----------|------------|---------|---------|
+| Signal analysis (4 company files) | 17,490 tokens | 3,969 tokens | **-77%** |
+| Ripple analysis (search KB) | 17,716 tokens | 2,811 tokens | **-84%** |
+| Architecture lookup (1 section) | 4,299 tokens | 259 tokens | **-94%** |
+| Vision section (from 7K doc) | 7,175 tokens | 807 tokens | **-89%** |
+
+Every token saved is a token available for reasoning.
+
+## Document Format
+
+ike works with any Markdown. For best results, docs should have YAML frontmatter:
+
+```yaml
+---
+title: "Authentication Architecture"
+domain: "engineering"
+summary: "OAuth2 + JWT auth flow for the API gateway."
+---
+```
+
+**Don't have frontmatter?** Run `ike doctor --yes` — it infers title from H1, domain from directory path, summary from the first paragraph.
+
+## Install
+
+```bash
+pip install intentic-ike          # CLI only
+pip install intentic-ike[mcp]     # CLI + MCP server
+```
+
+Requires Python 3.12+. Works on Linux, macOS, Windows (WSL).
+
+## MCP Server Configuration
+
+`ike init` generates `.mcp.json` automatically. Or configure manually:
+
+```json
+{
+  "mcpServers": {
+    "ike": {
+      "command": "ike",
+      "args": ["serve"],
+      "env": { "IKE_KB_ROOT": "/path/to/your/docs" }
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+AI Tool (Claude Code, Cursor, Codex, ...)
+        |
+   ike CLI / MCP Server
+        |
+   Engine (facade)
+        |
+   ┌────┬────┬────┬────┐
+Parser Index Fetcher Writer Linter
+   |    |
+markdown-it  SQLite WAL
+```
+
+- **Plugin CLI** — Commands auto-discovered from `ike/commands/*_cmd.py`
+- **Thread-safe** — SQLite with per-thread connections (safe for MCP thread pool)
+- **Lazy MCP** — `fastmcp` only imported when `ike serve` runs
+
+## Development
+
+```bash
+git clone https://github.com/pedrams/ike && cd ike
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,mcp]"
+pytest                                  # 184 tests, ~5s
+```
+
+## License
+
+MIT

intentic_ike-0.2.0/ike/__init__.py

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

intentic_ike-0.2.0/ike/__main__.py

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

intentic_ike-0.2.0/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

intentic_ike-0.2.0/ike/commands/__init__.py

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

intentic_ike-0.2.0/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.")

intentic_ike-0.2.0/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)

intentic_ike-0.2.0/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}")

intentic_ike-0.2.0/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.")

intentic_ike-0.2.0/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.")

intentic_ike-0.2.0/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.")

intentic_ike-0.2.0/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).")

intentic_ike-0.2.0/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')}")

intentic_ike-0.2.0/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()

intentic_ike-0.2.0/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))

intentic_ike-0.2.0/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()