# Personal LLM Wiki Kit

Clone this repository, add one source file to `raw/`, run one script, and open the local viewer. The result is a small LLM Wiki that an agent can query through MCP-style tools and a human can browse in the web UI.

This repo intentionally uses a generic name and generic wording so it can be published publicly without exposing course-related search terms.

## What Is Included

| Area | Path | Purpose |
| --- | --- | --- |
| Harness | `harness/RULES.md` | Operating rules for agents that maintain the wiki |
| Skill | `skills/wiki-maintainer/SKILL.md` | Reusable maintenance workflow for adding new sources |
| LLM Wiki | `raw/`, `wiki/`, `wiki/schema/page.schema.json` | Source folder, rendered wiki pages, and page schema |
| Visualization Tool | `tools/wiki_mcp_server.py` | Local MCP-style server, wiki viewer, search, Q&A, and knowledge map |
| Ingestion Script | `scripts/ingest_source.py` | Converts one text/Markdown source into a wiki page |
| Demo Evidence | `demo/rendered-wiki.png` | Screenshot of a real rendered knowledge base |

## Requirements

- Python 3.10 or newer
- A web browser
- No external Python package is required

## 30-Minute Quick Start

1. Clone the repo and enter the folder.

```bash
git clone <your-public-repo-url>
cd <repo-folder>
```

2. Put one source file into `raw/`.

Example:

```text
raw/my-first-note.md
```

3. Convert the source into a wiki page.

```bash
python scripts/ingest_source.py raw/my-first-note.md --title "My First Note"
```

This creates a Markdown page in `wiki/pages/`.

4. Start the viewer and MCP tool server.

```bash
python tools/wiki_mcp_server.py
```

5. Open the viewer.

```text
http://127.0.0.1:8767
```

6. Confirm the new page appears in the left page list. Use search or the question box to test the page.

## MCP Tool Endpoint

The local endpoint is:

```text
POST http://127.0.0.1:8767/mcp
```

### Tool List

| Tool | Description |
| --- | --- |
| `wiki.list_pages` | Returns page metadata for every wiki page |
| `wiki.search` | Searches title, tags, summary, and body |
| `wiki.get_page` | Returns one full page by slug |
| `wiki.related_pages` | Finds pages related by category and tags |
| `wiki.ask` | Produces a source-grounded answer from matching pages |
| `wiki.knowledge_map` | Returns nodes and links for the visualization view |
| `wiki.ingest_raw` | Creates a wiki page from raw text supplied by an agent |

### Example: List Tools

```bash
curl -s http://127.0.0.1:8767/mcp ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}"
```

PowerShell:

```powershell
Invoke-RestMethod -Uri http://127.0.0.1:8767/mcp -Method Post -ContentType "application/json" -Body '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

### Example: Ask The Wiki

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "wiki.ask",
    "arguments": {
      "question": "What is PER and why does valuation matter?"
    }
  }
}
```

## How To Add Your Own Knowledge

Use either the script or the MCP tool.

Script path:

```bash
python scripts/ingest_source.py raw/example.md --title "Example" --category note --tags example,wiki
```

MCP path:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "wiki.ingest_raw",
    "arguments": {
      "title": "Example",
      "content": "# Example\n\nImportant source notes...",
      "category": "note",
      "tags": ["example", "wiki"]
    }
  }
}
```

After ingestion, reload the viewer. The page is immediately available to the search, Q&A, and knowledge map.

## Agent Integration Request Template

Use this prompt with an agent:

```text
Read harness/RULES.md and skills/wiki-maintainer/SKILL.md.
Ingest raw/<filename> into the wiki.
Then verify with wiki.list_pages, wiki.search, and wiki.get_page through the MCP endpoint.
Do not invent facts that are not in the source.
```

## Verification Checklist

- `python scripts/ingest_source.py raw/my-first-note.md --title "My First Note"` creates a file under `wiki/pages/`.
- `python tools/wiki_mcp_server.py` starts without installing packages.
- `http://127.0.0.1:8767` shows the wiki viewer.
- The left page list contains the new page.
- The search box finds words from the new page.
- The knowledge map changes after adding a new page.
- `wiki.ask` returns an answer with source page metadata.

## Safety Notes

- Do not put API keys in source files or scripts.
- Do not commit private notes unless the public repository is allowed to contain them.
- The included finance sample pages are educational examples only and are not investment advice.