dusun 3.0.0

MCP server for systemic reasoning — 7-lens analytical framework, bileshke composite engine, kavaid constraints, kaskad generative cascade, inference chains, and Holographic Context Protocol. Plug into VS Code Copilot Chat.

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.

pip install dusun
fw-engine --init

Restart VS Code. Done. The 17 tools and /dusun slash command appear in Copilot Chat automatically.

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

Auto-repair: On every server start, fw-engine silently restores any missing framework files (prompts, instructions, DUSUN.md). If you accidentally delete one, just reload VS Code.

---

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
dusun	Universal neural substrate — auto-classifies, fires relevant lenses, returns complete analysis
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
validate_stage	Gate-check a pipeline stage (PASS/WARN/FAIL)
get_framework_summary	Aggregate summary from all modules
calibrate_source_texts	Validate source material integrity
run_kaskad	Run cascade inference engine
hcp_ingest	Ingest context into the Holographic Context Protocol
hcp_query	Query HCP for relevant chunks (seed-modulated attention)
hcp_advance_workflow	Advance HCP workflow to next stage
hcp_create_workflow	Create a new HCP workflow
hcp_diagnostics	Return HCP diagnostic state
hcp_export_state	Export full HCP state
hcp_import_state	Import previously exported HCP state
hcp_sync_memory_bank	Sync HCP state to memory bank files

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)

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

Option 2: pipx (isolated environment)

pipx install dusun
fw-engine --init

Option 3: uvx (no install needed)

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

Option 4: From source

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

---

VS Code Setup

The easiest way (auto-generates config):

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

Or create .vscode/mcp.json manually:

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

Windows with venv? Use the full path:

{
  "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 17 tools and the /dusun slash command 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:

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

---

CLI Usage

# Show help (when run interactively in a terminal)
fw-engine

# Start MCP server on stdio (called by VS Code automatically)
fw-engine    # when stdin is piped (non-TTY)

# 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:

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.

---

Also Includes: arc_solver

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

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

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

3049 tests, all passing.

---

License

MIT — see LICENSE.