# dusun — Systemic Reasoning MCP Server

**An MCP server that adds 7-lens systemic analysis to VS Code Copilot Chat. Install in 2 commands. Zero configuration.**

```bash
pip install dusun
fw-engine --init
```

Restart VS Code. Done. The 8 tools appear in Copilot Chat automatically.

> `fw-engine --init` creates `.vscode/mcp.json` in the current directory. Safe to re-run — won't overwrite existing config.

---

## What It Does

`dusun` exposes a **systemic reasoning engine** as an MCP (Model Context Protocol) server. It gives your AI assistant structured analytical tools instead of relying on pure text generation:

| Tool | What It Does |
|------|-------------|
| `run_single_lens` | Execute 1 of 7 analytical lenses on a concept |
| `run_bileshke_pipeline` | Run all 7 lenses → composite score + quality report |
| `check_kavaid` | Evaluate 8 formal constraints (boundary conditions) |
| `verify_chains` | Verify inference chains from the framework DAG |
| `get_framework_summary` | Aggregate summary from all modules |
| `hcp_ingest` | Ingest context into the Holographic Context Protocol |
| `hcp_query` | Query HCP for relevant chunks (seed-modulated attention) |
| `hcp_diagnostics` | Return HCP diagnostic state |

### The 7 Lenses

Each lens is an independent analytical instrument (no shared state between them):

| # | Lens | Domain | Instrument |
|---|------|--------|------------|
| 1 | **Ontoloji** | Concept ontology, Name mapping | kavram_sozlugu |
| 2 | **Mereoloji** | Part-whole, teleological structure | mereoloji |
| 3 | **FOL** | First-order logic, axiom extraction | fol_formalizasyon |
| 4 | **Bayes** | Bayesian inference, probability update | bayes_analiz |
| 5 | **OyunTeorisi** | Game theory, strategic interaction | oyun_teorisi |
| 6 | **KategoriTeorisi** | Functor verification, natural transformations | kategori_teorisi |
| 7 | **Topoloji + Holografik** | Topological/holographic analysis | holografik |

The **bileshke** (composite) engine combines all 7 lens outputs into a single quality score with coverage vectors, epistemic grades, and constraint checks.

---

## Installation

### Option 1: pip (recommended)

```bash
pip install dusun
fw-engine --init    # creates .vscode/mcp.json
```

### Option 2: pipx (isolated environment)

```bash
pipx install dusun
fw-engine --init
```

### Option 3: uvx (no install needed)

```jsonc
// .vscode/mcp.json
{
  "servers": {
    "fw-engine": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "dusun", "fw-engine"]
    }
  }
}
```

### Option 4: From source

```bash
git clone https://github.com/kaantahti/dusun.git
cd dusun
pip install .
```

---

## VS Code Setup

The easiest way (auto-generates config):

```bash
cd your-project
fw-engine --init    # creates .vscode/mcp.json
```

Or create `.vscode/mcp.json` manually:

```jsonc
{
  "servers": {
    "fw-engine": {
      "type": "stdio",
      "command": "fw-engine"
    }
  }
}
```

> **Windows with venv?** Use the full path:
> ```jsonc
> {
>   "servers": {
>     "fw-engine": {
>       "type": "stdio",
>       "command": "C:/Users/you/path/to/venv/Scripts/fw-engine.exe"
>     }
>   }
> }
> ```

Restart VS Code. The **fw-engine** server appears in Copilot Chat's tool list. You can now use all 8 tools directly in chat.

### 3. Use in Copilot Chat

```
@copilot run the bileshke pipeline on the concept "tree"
```

```
@copilot check kavaid constraints with composite score 0.82
```

```
@copilot ingest this text into HCP and then query for "causation"
```

---

## Claude Desktop Setup

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "fw-engine": {
      "command": "fw-engine"
    }
  }
}
```

---

## CLI Usage

```bash
# Start MCP server on stdio
fw-engine

# Or run as a Python module
python -m fw_server
```

---

## Architecture

```
Input → 7 Independent Lenses → Bileshke (Composite Engine) → Quality Report
              ↓                         ↓                         ↓
        Each lens runs              Weighted sum              Coverage vectors
        in isolation               (always < 1.0)            Epistemic grades
        (no shared state)                                    8 kavaid checks
                                                             AX57 disclosure
```

### Key Properties

- **Independence (KV₇)**: Each lens runs in a fresh instance — no shared state, no contamination
- **Convergence bound (KV₄)**: Composite score is always strictly < 1.0 — the map is never the territory
- **Multiplicative gate (AX52)**: Zero in ANY dimension = system failure (not averaged away)
- **Epistemic ceiling (AX56)**: Maximum grade is İlmelyakîn (demonstrative certainty) — never claims more
- **Transparency (AX57)**: Every response discloses which lenses were used and which were not

### Quality Framework

| Component | What It Checks |
|-----------|---------------|
| Q-1 Coverage | Are all 7 faculties engaged? Multiplicative gate. |
| Q-2 Grade | Epistemic degree: Tasavvur → Tasdik → İlmelyakîn |
| Q-3 Kavaid | All 8 formal constraints pass? |
| Q-4 Completeness | Max 6/7 — one dimension permanently inaccessible |

---

## Also Includes: ai_assert

A **zero-dependency** runtime constraint verifier for AI outputs:

```python
from ai_assert import ai_assert, valid_json, max_length, contains

result = ai_assert(
    prompt="Return a JSON object with a 'greeting' key",
    constraints=[valid_json(), max_length(200), contains("hello")],
    generate_fn=my_llm,
    max_retries=3,
)
```

278 lines, zero dependencies, works with any LLM. See [examples/basic_usage.py](examples/basic_usage.py).

---

## Also Includes: arc_solver

A pure-stdlib ARC-AGI solver with ~25 DSL primitives:

```bash
python arc_eval.py ARC-AGI/data/training -v
# 33/400 = 8.2% on ARC-AGI-1 training set, 83 seconds, zero dependencies
```

---

## Requirements

- Python ≥ 3.10
- `mcp >= 1.20` (installed automatically)

---

## Development

```bash
git clone https://github.com/kaantahti/dusun.git
cd dusun
pip install -e .
python -m pytest tests/ -q
```

1694 tests, all passing.

---

## License

MIT — see [LICENSE](LICENSE).
