# Lacan Knowledge OS **A corpus-grounded research environment for Lacanian psychoanalysis.** Evidence first. Interpretation second. Fabrication never. [**English**](README.md) · [中文](README.zh.md) · [Français](README.fr.md) · [日本語](README.ja.md) · [Deutsch](README.de.md) · [Italiano](README.it.md) [![License](https://img.shields.io/badge/license-Apache--2.0-6b4c2f?style=flat-square)](LICENSE) [![Core](https://img.shields.io/badge/scholarly%20core-frozen%20%C2%B7%2039%20components-43403b?style=flat-square)](docs/ARCHITECTURE.md) [![Tests](https://img.shields.io/badge/regression-146%20suites%20%C2%B7%200%20failed-3f6b4a?style=flat-square)](docs/SCHOLARLY_REGRESSION_SPEC_V1.md) [![MCP](https://img.shields.io/badge/MCP-10%20tools%20%C2%B7%202025--11--25-6b4c2f?style=flat-square)](docs/MCP_TOOL_CONTRACTS.md) [![Built with](https://img.shields.io/badge/built%20with-DeepSeek%20Harness-4d6bfe?style=flat-square)](https://github.com/deepseek-ai)

--- > **The one rule this system is built around** > > *Every claim must land on a passage number.* > > If the corpus cannot support a question, the system **abstains** — it does not answer > from model knowledge. An abstention is a result, not an error. --- ## Table of contents | | | |---|---| | [1. What it is](#1-what-it-is) | [6. Architecture](#6-architecture) | | [2. Who it is for](#2-who-it-is-for) | [7. Use it from DSH / any MCP client](#7-use-it-from-dsh--any-mcp-client) | | [3. What it refuses to do](#3-what-it-refuses-to-do) | [8. Bring your own corpus](#8-bring-your-own-corpus-important) | | [4. Quick start](#4-quick-start) | [9. Advantages and disadvantages](#9-advantages-and-disadvantages) | | [5. How to use it](#5-how-to-use-it) | [10. Status, roadmap, contributing](#10-status-roadmap-contributing) | --- ## 1. What it is **Lacan Knowledge OS** is a local, offline-first research instrument for reading Lacan seriously. It turns a corpus of seminar and écrits text into a **citable evidence store**, and it puts a **frozen scholarly core** between your question and any answer. Six things, one system: | | Capability | What it gives you | |---|---|---| | 🔎 | **Research** | Ask a question → the core retrieves passages, builds an evidence contract, and only then synthesises an answer whose every claim survives citation + entailment validation | | 📖 | **Explore** | Read the corpus directly: passages, sessions, seminars, concepts, terminology — no model involved | | 🔬 | **Evidence Inspector** | `Answer → Claim → Passage → Session → Seminar → Witness/Source`, with the exact quoted span and its context window | | 🗂️ | **Research Projects** | Turn repeated runs into a long-term topic (questions, hypotheses, passages, persons, cases, bibliography) | | 📚 | **Bibliography & citations** | Review status, metadata completeness, per-style citation availability **with the reason it is unavailable** | | ✍️ | **Obsidian bridge** | Evidence and validation stay here; your understanding, notes and writing live in your vault | ## 2. Who it is for - **Researchers and doctoral students** who need to cite Lacan precisely and to show *where* a reading comes from. - **Study groups and reading seminars** that want a shared, inspectable evidence base. - **Tool builders** who want a worked example of a *frozen-core* architecture: a semantic layer that cannot drift while a product layer evolves around it. - **AI engineers** interested in grounded generation with an explicit abstention contract instead of a confidence score. ## 3. What it refuses to do These refusals are the design, not limitations: | Refusal | Why | |---|---| | **No answering from model knowledge** | The synthesis step may only use retrieved evidence. If the contract is insufficient, the output is `ABSTAINED`. | | **No silent repair of sources** | `SOURCE_TRACE_INCOMPLETE` stays visible. Hiding it would misrepresent the source. | | **No invented bibliographic data** | Publisher, year, ISBN, page numbers are never guessed. A style that cannot be produced says why. | | **No auto-promotion to canonical** | Imported or AI-produced material enters as a *candidate* and stays one until a human promotes it. | | **No unspecified semantics** | The 39 scholarly components are hash-pinned; an undeclared change fails the freeze check and the system refuses to start. | ## 4. Quick start > **This public edition ships the engine, not the corpus.** See > [§8 Bring your own corpus](#8-bring-your-own-corpus-important) and [`CORPUS.md`](CORPUS.md). ```bash git clone https://github.com/YanKaFei/Lacan-Knowledge-OS.git cd Lacan-Knowledge-OS # 1) The interface boots with no corpus at all — Help Center + UI are fully usable: python3 -m workspace_ui.server.cli --port 3090 # → http://127.0.0.1:3090/help 13-page Help Center # → http://127.0.0.1:3090/research research surface (needs a corpus to answer) # 2) Integrity checks (these are the contract, not decoration): python3 _scripts/_tools/core_freeze.py --verify # 39 scholarly components python3 _scripts/_tools/freeze_lineage.py --verify # semantic changes across phases python3 _scripts/_tools/build_i18n.py --check # UI copy ↔ dictionary ↔ call sites python3 _scripts/_tools/build_help.py --check # Help links, anchors, 0 fiction # 3) Full regression (corpus-dependent suites need a corpus; see CORPUS.md) bash _scripts/run_all_tests.sh ``` **Requirements:** Python 3.9+ (standard library only for the core path), a modern browser, and — only if you want vector retrieval or a real LLM provider — the optional extras in [`docs/EMBEDDING_PROVIDER.md`](docs/EMBEDDING_PROVIDER.md). No bundler, no build step: `index.html` loads ES modules directly. ## 5. How to use it ### 5.1 The task-based home page Opening the system shows **what you can do**, not the system's internals: ``` Hero → [Start a research run] [First time here?] Tasks → Ask a Lacanian question · Find text and sources · Study a concept Study persons and cases · Build a long-term project · Manage sources Workflow → ① Ask → ② Check evidence → ③ Read the original → ④ Save the material → ⑤ Sort sources → ⑥ Form your own knowledge 5 minutes → six steps to a finished first run ``` Every entry is a **real link** (`/research`, `/explore`, `/projects`, `/bibliography`, `/persons`, `/cases`, `/zotero`, `/help/...`) — shareable, bookmarkable, openable in a new tab. ### 5.2 A complete research task 1. **Ask** — one question per run. 2. **Read the state** — `VALIDATED`, `VALIDATED_WITH_QUALIFICATIONS`, `PARTIALLY_SUPPORTED`, `VALIDATION_FAILED`, `INSUFFICIENT_EVIDENCE`, `ABSTAINED`. Read it literally. 3. **Verify** — click a citation chip; the Evidence Inspector shows the quoted span, its context window, and the source chain. *The answer is what the core concluded; the inspector is what the corpus actually says.* 4. **Go deeper** — open the same passage in Explore and read around it. 5. **Keep it** — `Add to Project`, or `Save to Obsidian`. ### 5.3 Help Center `/help` is a 13-page centre with a sidebar, anchors, previous/next, and a topic search: *getting started, research, evidence, explore, research vs explore, projects, persons & cases, bibliography, zotero, obsidian, languages, statuses, troubleshooting*. **Every control name in Help is rendered from the real interface**, and every functional claim is machine-checked (`HELP_CLAIM_VERIFICATION.json`: **42/42 verified, 0 fiction, 0 pending**). ### 5.4 Interface language vs research language | Setting | Scope | Example | |---|---|---| | **Language** (`English` / `中文`) | The product interface only | switches instantly, no reload | | **Research language** (`any` / `zh` / `fr` / `en`) | The *question language* sent with a research request | does not translate the UI, does not filter retrieval | `Interface = 中文` + `Research language = Français` is a perfectly valid combination. Lacan's original text, quoted passages and bibliographic metadata are **never** translated. ## 6. Architecture ``` your question │ ┌──────────▼───────────┐ │ PRODUCT LAYER │ workspace_ui/ · browse_api/ · project_api/ │ (may change freely) │ export_system/ · bibliography/ · obsidian_adapter/ └──────────┬───────────┘ │ scholarly_api v1 (product boundary — 3 hashed components) ┌──────────▼───────────┐ │ FROZEN CORE │ 39 hash-pinned components │ (cannot drift) │ retrieval · evidence contract · sufficiency · └──────────┬───────────┘ synthesis boundary · citation · entailment · abstention │ ┌──────────▼───────────┐ │ CORPUS │ passage store · witnesses · ontology · indexes │ (bring your own) │ NOT included in this repository └──────────────────────┘ ``` - **Agents talk MCP, not Python.** `mcp_server/` exposes **10 tools** over stdio (protocol `2025-11-25`); the UI is just one client of that same contract. - **The freeze is executable.** `core_freeze.py --verify` recomputes 39 component hashes; `freeze_lineage.py --verify` proves *zero* semantic change across seven phases. - **Derivatives are regenerable.** SQLite/FTS/vector indexes and the 249k-passage store are rebuildable from canonical sources + manifests. The vault is the source of truth. Read more: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/MCP_ARCHITECTURE.md`](docs/MCP_ARCHITECTURE.md) · [`HELP_SYSTEM_ARCHITECTURE.md`](docs/HELP_SYSTEM_ARCHITECTURE.md). ## 7. Use it from DSH / any MCP client The repository **is** a [DeepSeek Harness](https://github.com/deepseek-ai) plugin target: it ships an MCP server, a portable row, and an installable DSH bundle. ```bash # A. As a DSH plugin (installs the MCP row for you) dsh plugin --profile web add github:YanKaFei/Lacan-Knowledge-OS # B. Or paste the row yourself — integrations/lacan-kb-mcp.row.yml # (tools then appear as mcp__lacan-kb__search_passages, …) # C. Or run the server standalone python3 _scripts/_tools/lacan-kb-mcp ``` Proven with DSH's own MCP SDK (`_data/mcp/DSH_CLIENT_PROOF.json`, **14/14 checks**): stdio handshake, 10 tools with schemas, `mcp__lacan-kb__` naming, structured evidence returns, independent re-verification of returned passage ids, and a protocol error — not a crash — for unknown tools. See [`docs/MCP_DSH_INTEGRATION.md`](docs/MCP_DSH_INTEGRATION.md). ## 8. Bring your own corpus (**important**) **Handing the corpus to a colleague.** Build a pack and send it over a channel you control (a private repo's release asset, your own server, a USB stick) — hash-verified and ~215 MB for the reference corpus: [`docs/CORPUS_PACK.md`](docs/CORPUS_PACK.md) (`tools/pack-corpus.py` → `tools/fetch-corpus.py`). This repository deliberately contains **no source text**: | Not included | Why | |---|---| | Seminar/écrits full text (fr + zh) | Copyright of the rights holders | | Passage store (`passages.jsonl`, 249,105 records, ~384 MB) | Corpus text | | Witness realizations & witnesses (`~152 MB`) | Corpus text | | Vector/lexical indexes | Large, rebuildable from your own corpus | What *is* included: the schemas, the freeze contract, the builders, the validators and the tests — i.e. everything needed to ingest **text you are allowed to use** (your own scans, licensed editions, public-domain material, or your own translations). ```bash python3 _scripts/build.py --help # corpus inventory & build entry points python3 _scripts/inventory_corpus.py --help # canonical inventory + hashes ``` The public edition is produced and verified by [`_scripts/_tools/build_public_edition.py`](_scripts/_tools/build_public_edition.py): an allow-list copy, then a **negative** verification (corpus N-gram probes, secret scan, absolute-path scan, size gates). See [`docs/PUBLIC_EDITION.md`](docs/PUBLIC_EDITION.md). ## 9. Advantages and disadvantages

✅ Advantages	⚠️ Disadvantages / limits
Verifiability over fluency. Every claim is tied to a passage id; you can audit the chain by hand. Honest failure. Abstention, `INSUFFICIENT_EVIDENCE` and explicit unavailability are first-class outputs. No hallucinated filler. An executable contract. The 39-component freeze and the seven-segment lineage are checked by code, not by a promise in a document. Offline-first. `Offline / Mock` produces deterministic answers with no credentials and no network. One contract, many clients. The same MCP surface serves the web UI, DSH, and any editor with an MCP client. Auditable history. Every research run is an immutable snapshot; re-running a question creates a new item instead of overwriting the old one. Bilingual by construction. UI copy is dictionary-driven with 0 missing keys; source text is deliberately never translated.	It needs a corpus you have the right to use. Out of the box it can show its interface, its Help Centre and its contracts — but it cannot answer questions until you supply text. It is opinionated about scope. It answers about a corpus. Questions about publication history, attendees or dates will abstain, because the corpus does not carry that metadata. No quality score. There is no "confidence %" anywhere; interpretation quality remains your judgement. Heavy for a laptop-scale workflow. The reference corpus is ~2.5 GB on disk including derived indexes and embeddings. Vector retrieval is optional and partial. Without the embedding extras, retrieval falls back to lexical matching (the UI says which one is active). Real-LLM synthesis is a single blocking call. Long runs take 45–60 s; the UI shows real elapsed time, and "stop waiting" does not cancel the backend job. Fast-moving product layer, frozen scholarly layer. Convenience features change often; changing the semantics requires a formal Core Change Request. Presupposes familiarity with the domain. The system will not teach you Lacan.

✅ Advantages

⚠️ Disadvantages / limits

**Verifiability over fluency.** Every claim is tied to a passage id; you can audit the chain by hand. **Honest failure.** Abstention, `INSUFFICIENT_EVIDENCE` and explicit unavailability are first-class outputs. No hallucinated filler. **An executable contract.** The 39-component freeze and the seven-segment lineage are checked by code, not by a promise in a document. **Offline-first.** `Offline / Mock` produces deterministic answers with no credentials and no network. **One contract, many clients.** The same MCP surface serves the web UI, DSH, and any editor with an MCP client. **Auditable history.** Every research run is an immutable snapshot; re-running a question creates a new item instead of overwriting the old one. **Bilingual by construction.** UI copy is dictionary-driven with 0 missing keys; source text is deliberately never translated.

**It needs a corpus you have the right to use.** Out of the box it can show its interface, its Help Centre and its contracts — but it cannot answer questions until you supply text. **It is opinionated about scope.** It answers *about a corpus*. Questions about publication history, attendees or dates will abstain, because the corpus does not carry that metadata. **No quality score.** There is no "confidence %" anywhere; interpretation quality remains your judgement. **Heavy for a laptop-scale workflow.** The reference corpus is ~2.5 GB on disk including derived indexes and embeddings. **Vector retrieval is optional and partial.** Without the embedding extras, retrieval falls back to lexical matching (the UI says which one is active). **Real-LLM synthesis is a single blocking call.** Long runs take 45–60 s; the UI shows real elapsed time, and "stop waiting" does not cancel the backend job. **Fast-moving product layer, frozen scholarly layer.** Convenience features change often; changing the *semantics* requires a formal Core Change Request. **Presupposes familiarity with the domain.** The system will not teach you Lacan.

## 10. Status, roadmap, contributing - **Status:** the scholarly core is frozen at v1 (`SCHOLARLY_CORE_READY`); the product layer is complete for daily use (research, explore, evidence, projects, bibliography, Zotero import, Obsidian bridge, export, 6-language README, Help Centre). - **Verification numbers from the last acceptance run:** **20/20 blocking gate items**, **146 regression suites / 78 validators / 0 failed / 0 skipped**, core freeze **PASS**, semantic drift **0**. - **Roadmap:** [`docs/ROADMAP.md`](docs/ROADMAP.md). - **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md) — the one non-negotiable rule is *do not change scholarly semantics without a Core Change Request*. - **Security:** [`SECURITY.md`](SECURITY.md) — credentials never pass through the product API.

**License** — code: [Apache-2.0](LICENSE) · source texts: **not distributed** ([NOTICE](NOTICE)) *If this system saves you a week of citation checking, it did its job.*