Metadata-Version: 2.4
Name: kkanbu
Version: 0.1.6
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[cli]>=1.0.0
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.

## 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 <repo-url>
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_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_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
