knowledge-engineer

Local-first, multimodal knowledge ingestion and extraction framework.

The engine walks a directory of source files, extracts structured artifacts (PDF, DOCX, PPTX, XLSX, CSV, JSON, HTML, Markdown, plain text, images, audio, video), runs knowledge extraction with a local LLM, deduplicates and detects contradictions, and writes the result as a Markdown vault (Obsidian-compatible) plus a JSON dump.

Domain lives in profiles — the same engine powers a personal archive, a software repository, or a research corpus. v0.1 ships generic, personal, software, and research profiles.

What it is not

• It is not an Obsidian plugin. It exports an Obsidian-compatible vault, but the engine itself is a standalone CLI + REST API.
• It is not a personal-life tool by default. Personal archival is one of four profiles; the engine is domain-independent.
• It is not a cloud service. v0.1 runs entirely on local files. Cloud providers are documented as a future extension point.
• It is not magic. It cannot extract knowledge from files it cannot read; OCR requires a real OCR provider; vision captioning requires a real vision provider. Providers that are not configured fail with ProviderNotConfiguredError — they never silently fabricate output.

Installation

Requires Python 3.11+.

python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"

Optional OCR / vision / transcription dependencies are NOT bundled:

# OCR
brew install tesseract        # macOS
pip install pytesseract

# Vision
pip install clip-onnx         # future provider; v0.1 ships null only

# Transcription
pip install faster-whisper

Quick start

# 1. Initialize a project skeleton
knowledge-engineer init ./my-project

# 2. Scan a directory into the SQLite inventory
knowledge-engineer scan ./my-project/sample-data --db ./my-project/data/knowledge.db

# 3. Run the pipeline (discovery -> classify -> extract -> knowledge -> vault)
knowledge-engineer process \
    --db ./my-project/data/knowledge.db \
    --profile generic \
    --vault ./my-project/vault \
    --output-format markdown

# 4. Inspect
knowledge-engineer status --db ./my-project/data/knowledge.db
knowledge-engineer review  --db ./my-project/data/knowledge.db

# 5. Export
knowledge-engineer export \
    --db ./my-project/data/knowledge.db \
    --vault ./my-project/vault \
    --format obsidian   # or markdown | json

What it does on a corpus

The pipeline runs these stages per source file:

1. DISCOVER — recursive walk, sha256 + MIME detection, symlink guards, archive-bomb limits.
2. CLASSIFY — MIME → PipelineKind (document / image / audio / video / structured / text / archive / skip).
3. EXTRACT — type-specific extractors produce a normalised Artifact (DocumentArtifact, ImageArtifact, etc.).
4. NORMALIZE — text encoding, length caps, language hints.
5. ENTITY_EXTRACTION — LLM extracts typed entities via temperature=0 structured output, schema-validated.
6. CLAIM_EXTRACTION — same, claims (subject, predicate, object, evidence).
7. RELATIONSHIP_EXTRACTION — typed relationships between entities.
8. EVENT_EXTRACTION — dated occurrences.
9. VALIDATION — claims without evidence are queued for review.
10. PROVENANCE — every record tracks the source + artifact + the extractor version that produced it.
11. STORE — SQLite persistence (WAL, foreign keys, busy timeout).
12. EXPORT — Markdown, Obsidian-compatible, or JSON.

Each stage records its outcome in processing(source_id, stage) so the pipeline is resumable and auditable.

Provider model

Each capability has an interface:

Null providers raise ProviderNotConfiguredError when asked to do work. This is the framework's honesty contract.

Documentation

• docs/ARCHITECTURE.md
• docs/DATA_MODEL.md
• docs/CONFIGURATION.md
• docs/PROVIDERS.md
• docs/EXTENDING.md
• docs/VAULT.md
• docs/SECURITY.md
• docs/PRIVACY.md
• docs/TESTING.md
• docs/DEVELOPMENT.md
• docs/CONTRIBUTING.md
• docs/ROADMAP.md

License

MIT. See LICENSE.