rekipedia 0.12.0 → 0.14.0

package/README.md

@@ -60,6 +60,40 @@ brew install rekipedia
 
 ---
 
+## Python API
+
+Use rekipedia programmatically inside Jupyter notebooks, CI pipelines, or any Python application:
+
+```python
+import rekipedia
+
+# Scan a local repo
+result = rekipedia.scan("/path/to/repo")
+print(result.page_count)   # number of wiki pages generated
+print(result.symbol_count) # number of code symbols extracted
+print(result.token_count)  # estimated token count of the wiki
+
+# Ask a question — grounded answer with file:line citations
+answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
+print(answer.text)
+for citation in answer.citations:
+    print(f"  {citation.file}:{citation.line}")
+
+# Async variants (Jupyter-friendly)
+result = await rekipedia.scan_async("/path/to/repo")
+answer = await rekipedia.ask_async("/path/to/repo", "What is the entry point?")
+```
+
+**Return types:**
+
+| Type | Key fields |
+|---|---|
+| `ScanResult` | `page_count`, `symbol_count`, `token_count`, `wiki_pages`, `db_path`, `wiki_dir` |
+| `AskResult` | `text`, `citations: list[Citation]`, `model_used` |
+| `Citation` | `file`, `line`, `snippet` |
+
+---
+
 ## Commands
 
 | Command | Description |
@@ -129,6 +163,9 @@ export REKIPEDIA_SHARD_TOKEN_BUDGET=40000
 | `REKIPEDIA_API_KEY` | API key for the LLM provider |
 | `REKIPEDIA_BASE_URL` | Base URL for OpenAI-compatible endpoints |
 | `REKIPEDIA_SHARD_TOKEN_BUDGET` | Max tokens per shard group (default: 40000) |
+| `REKIPEDIA_AGENT_ASK` | Set to `1` to enable agentic ReAct ask loop (default: `0` — single-shot) |
+| `REKIPEDIA_ASK_MAX_ITER` | Max tool-call iterations for agentic ask (default: `5`) |
+| `REKIPEDIA_AGENT_PLANNER` | Set to `1` to enable tool-calling wiki planner (default: `0`) |
 
 ---
 
@@ -295,6 +332,37 @@ rekipedia ships a **Hermes agent skill** (`rekipedia-agent-skill.md`) that teach
 
 ---
 
+## Agentic Mode
+
+rekipedia supports an experimental agentic mode where LLM calls use tool-calling (ReAct) instead of single large context dumps.
+
+### Agentic Ask
+
+Set `REKIPEDIA_AGENT_ASK=1` to enable:
+
+```bash
+REKIPEDIA_AGENT_ASK=1 reki ask "How does authentication work?"
+```
+
+The LLM issues tool calls to retrieve information on demand:
+- `search_code(query)` — semantic search over source code
+- `get_symbol(name)` — look up symbol location and signature
+- `get_page(slug)` — fetch a wiki page on demand
+- `get_relationships(target)` — dependency graph for a symbol/file
+- `finish(answer)` — provide final answer
+
+Max iterations can be configured with `REKIPEDIA_ASK_MAX_ITER` (default: 5).
+
+### Agentic Planner
+
+Set `REKIPEDIA_AGENT_PLANNER=1` to enable tool-calling wiki structure planning:
+
+```bash
+REKIPEDIA_AGENT_PLANNER=1 reki scan .
+```
+
+The planner builds the wiki structure incrementally using tool calls instead of generating a single large JSON response.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rekipedia",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Agentic repo-to-wiki: scan any repository into a portable SQLite knowledge store with wiki pages, diagrams, and grounded Q&A.",
   "bin": {
     "rekipedia": "./bin/rekipedia.js"