Metadata-Version: 2.5
Name: kkanbu
Version: 0.3.0
Summary: Taste oracle MCP server — proxies for the user in Ouroboros Socratic interviews
Project-URL: Repository, https://github.com/Jaeha0526/kkanbu
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.87.0
Requires-Dist: mcp<3,>=2
Requires-Dist: pymupdf4llm>=0.0.17
Requires-Dist: python-docx>=1.1.0
Requires-Dist: trafilatura>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: js
Requires-Dist: playwright>=1.40; extra == 'js'
Description-Content-Type: text/markdown

# kkanbu

A taste oracle that learns who you are — your preferences, values, and reasoning patterns — then speaks on your behalf.

kkanbu is an [MCP](https://modelcontextprotocol.io/) server that builds a persistent knowledge graph of your identity. When an AI agent needs to know something about *you*, kkanbu answers grounded in what it actually knows — not guesses.

kkanbu was born as the user-proxy for **Ouroboros**, a specification-first AI development workflow: during Ouroboros's Socratic interviews, kkanbu answers on the user's behalf so autonomous runs never block on human availability — and when it isn't confident enough to speak for you, it flags the question for your later review instead of guessing. It works standalone with any MCP client, but that flag-and-continue loop is what it was designed around.

## How It Works

```
AI Agent ←──MCP──→ kkanbu ←──→ Knowledge Graph (SQLite)
```

kkanbu stores knowledge as a graph of **nodes** (preferences, values, patterns, reasoning) connected by **edges** (supports, contradicts, derives_from). Each node tracks *what* you believe and *why*. When kkanbu isn't confident, it flags the question for later review rather than guessing.

## Installation

Requires Python 3.11+ and an [Anthropic API key](https://console.anthropic.com/).

### With Claude Code (recommended)

```bash
claude mcp add --scope user kkanbu -- uvx kkanbu
```

This installs kkanbu from PyPI and registers it as an MCP server. The `--scope user` flag makes it available across all sessions.

### From source

```bash
git clone https://github.com/Jaeha0526/kkanbu.git
cd kkanbu
pip install -e .

# Optional: JS-rendered webpage ingestion (SPAs, React sites)
pip install -e ".[js]"

# Register with Claude Code
claude mcp add --scope user kkanbu -- uv run --directory /path/to/kkanbu kkanbu
```

### Manual MCP config

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "kkanbu": {
      "command": "uvx",
      "args": ["kkanbu"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

## Usage

### Create a profile and log in

```
kkanbu_of_who(action="create", username="myname")
kkanbu_of_who(action="login", username="myname")
```

Each user gets an isolated knowledge graph at `~/.kkanbu/profiles/<username>/knowledge.db`.

### Teach it about yourself

```
kkanbu_learn(
  insight="I value simplicity in design — clean, minimal interfaces over feature-packed ones",
  why="Visual noise stresses me out"
)
```

Or ingest existing material — codebases, documents, or webpages:

```
kkanbu_ingest(path="/path/to/my-project")
kkanbu_ingest(path="https://my-portfolio.com")
```

### Let it ask you questions

kkanbu can proactively find gaps in what it knows and ask deep questions:

```
kkanbu_curious()
# → "When you feel most like yourself, what are you usually doing?"

kkanbu_curious(session_id="abc123", user_response="When I'm building something...")
# Drills deeper into the same thread
```

### Answer on your behalf

```
kkanbu_answer(question="What kind of work environment do you thrive in?")
# → Voice-faithful answer grounded in the knowledge graph,
#   with confidence scores and automatic flagging when uncertain
```

### Correct mistakes

```
kkanbu_correct(
  original="prefers quiet isolation",
  correction="prefers collaborative spaces",
  why="Does best thinking when bouncing ideas off people"
)
```

### Reflect on the graph

```
kkanbu_reflect()
# → Finds contradictions, tensions, and blind spots
#   Stores findings as flags for review
```

### Visualize

```
kkanbu_visualize()
# → Opens interactive D3.js graph at http://localhost:7742
```

## Tools

| Tool | Description |
|------|-------------|
| `kkanbu_of_who` | Manage user profiles — create, delete, list, login, logout |
| `kkanbu_answer` | Answer questions on your behalf using the knowledge graph |
| `kkanbu_learn` | Teach preferences, values, or patterns |
| `kkanbu_ingest` | Extract insights from codebases, documents, or webpages |
| `kkanbu_curious` | Ask deep questions to fill knowledge gaps |
| `kkanbu_reflect` | Analyze the graph for contradictions and tensions |
| `kkanbu_correct` | Fix wrong answers or stored preferences |
| `kkanbu_distill` | Distill conversation history into persistent graph learnings |
| `kkanbu_get_flags` | Show unresolved flagged items |
| `kkanbu_resolve_flag` | Review and resolve flags through Socratic conversation |
| `kkanbu_status` | Show knowledge graph statistics |
| `kkanbu_model` | Show, set, or reset the LLM model used by all tools (persists across restarts) |
| `kkanbu_visualize` | Launch interactive graph visualization in the browser |

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `ANTHROPIC_API_KEY` | Required for LLM-powered tools | — |
| `KKANBU_HOME` | Base directory for profiles and data | `~/.kkanbu` |
| `KKANBU_MODEL` | Per-process model override — takes precedence over the `kkanbu_model` setting | — |
| `KKANBU_EFFORT` | Reasoning depth for every LLM call on models that support it: `low`/`medium`/`high`/`xhigh`/`max`. Lower trades depth for cost. | `high` |
| `KKANBU_QA_LOG` | Append every `kkanbu_answer` Q&A pair (question, answer, confidences, flag) to `<profile>/answers.jsonl`. Set to `0`/`false`/`off` to disable. | `1` (on) |

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check src/
```

## License

MIT
