VKLP Research Prototype 0.1

VKLP = Verifiable Knowledge Ledger Profile

A research prototype for a model-independent, verifiable shared knowledge layer for local or remote LLMs. It combines:

• append-only SHA-256 hash-chain ledger with Ed25519 signatures,
• claim/evidence records and immutable version history,
• at least three independent LLM validators, optionally behind Ed25519-signing VKLP node wrappers,
• bounded disagreement/debate rounds,
• preservation of minority objections,
• local RAG retrieval,
• an OpenAI-compatible /v1/chat/completions RAG gateway,
• Ollama and generic OpenAI-compatible LLM adapters (including LM Studio),
• an MCP 2026-07-28 adapter for search/write/verify access,
• a German/English PyQt6 GUI with multiple themes,
• LAN-capable validator endpoints.

Important scope statement

The prototype is a cryptographically verifiable local ledger and consensus demonstrator, not a production public blockchain. It proves signed append-only history, multi-LLM validation and RAG integration. Byzantine P2P block replication/finality across independent ledger replicas is specified in the paper as the next layer, not falsely simulated here.

Likewise, ledger inclusion proves provenance and protocol-valid history, not factual truth.

By default, a claim cannot become accepted or provisionally_accepted without at least one explicit Evidence object (consensus.min_evidence_items = 1). This is a protocol safety gate, not a guarantee that the evidence is good.

Quick start (Windows)

1. Install Python 3.11+.
2. Run install.cmd.
3. Copy/edit config.example.json to config.json and configure at least three LLM endpoints.
4. Run run_server.cmd.
5. Optionally run run_gui.cmd.

For a protocol-only demo without real models, run run_demo_cluster.cmd; it starts three deterministic HTTP mock endpoints and the VKLP gateway. The mocks test networking/protocol behavior only, not epistemic quality.

Example real validators

The supplied config demonstrates a mixed topology:

• local Ollama: http://127.0.0.1:11434
• LAN LM Studio: e.g. http://192.168.1.52:1234
• another LAN Ollama node: e.g. http://192.168.1.53:11434

Replace IPs and model names with your actual machines. For cryptographically attributable validator responses, use the signed wrapper described in docs/SIGNED_VALIDATOR_SETUP.md. Do not expose unauthenticated local model servers to untrusted networks.

OpenAI-compatible RAG gateway

Point a compatible chat UI to:

• Base URL: http://<VKLP-host>:8787/v1
• API key: value of api_key in config.json
• Model: vklp-rag for the configured default generator, or vklp-<validator-id> to route the RAG-enriched request to that exact configured local/LAN LLM.

GET /v1/models exposes these aliases automatically. This means the same three machines used as validators can also be selected independently as RAG consumers from any OpenAI-compatible UI that lets you set a Base URL and model. VKLP retrieves accepted/provisionally accepted claims, injects status/provenance into context, then forwards to the selected backend.

MCP adapter

After pip install "mcp>=2,<3":

mcp dev src/vklp/mcp_server.py

Exposed MCP tools:

• search_knowledge
• get_claim
• propose_claim
• verify_ledger

MCP is an interoperability adapter, not VKLP's consensus protocol.

Tests

set PYTHONPATH=src
python -m pytest -q tests/test_core.py
python tests/test_http_e2e.py
python tests/test_three_http_validators.py
python tests/test_signed_validator_nodes.py

The third test launches three independent HTTP model processes, verifies mixed Ollama/OpenAI-compatible validator adapters, selects all three individually as RAG consumers through the OpenAI-compatible gateway, and then verifies disagreement/debate behavior. The fourth launches three independent model endpoints plus three signing validator wrappers with distinct Ed25519 keys, verifies every final vote signature, re-verifies the persisted signed vote data, and confirms that tampering invalidates the signature.

Retrieval

Prototype v0.1 deliberately uses SQLite FTS5 lexical retrieval to stay lightweight and reproducible. Semantic embeddings can be added through Ollama /api/embed or another vector store without changing ledger semantics.

Files

• docs/VKLP_Research_Paper.pdf / .docx - research paper
• docs/VKLP_PROTOCOL_0_1.md - protocol profile
• docs/SIGNED_VALIDATOR_SETUP.md - three-node/LAN signed-validator deployment
• prompts/ - LLM instructions
• src/vklp/ - implementation
• tests/ - unit and multi-process integration tests
• config.example.json - direct real LLM/LAN configuration example
• config.signed.example.json - recommended signed three-validator LAN template
• config.demo.json - deterministic three-node demo configuration

License

Prototype code: Apache-2.0. Paper text: CC BY 4.0 unless a downstream publication venue requires different terms.