Metadata-Version: 2.4
Name: severino-vault-engine
Version: 0.1.0
Summary: Domain-agnostic vault-governance engine: frontmatter schema profiles, indexing, ranked search, a task ledger, atomic writes, and a composable MCP core (register_core). The reusable core behind severino-vault-mcp and severino-edu-mcp.
Project-URL: Homepage, https://github.com/joeseverino/vault-engine
Project-URL: Issues, https://github.com/joeseverino/vault-engine/issues
Author-email: Joseph Severino <github@jseverino.com>
License-Expression: MIT
Keywords: frontmatter,local-first,mcp,model-context-protocol,obsidian,vault
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: cordon-emit
Requires-Dist: mcp>=1.27
Requires-Dist: starlette>=1.0.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# vault-engine

A domain-agnostic **vault-governance engine** — the reusable core behind
[`severino-vault-mcp`](https://github.com/joeseverino/severino-vault-mcp) and
`severino-edu-mcp`. It governs a Git-backed, frontmatter-tagged Markdown vault
(Obsidian-style) and exposes that governance both as a library and as a
composable MCP tool surface.

## What's in it

- **`SchemaProfile`** — a vault's frontmatter contract (doc-types, statuses,
  id-prefixes, the task lifecycle), with `as_dict()` (HQ/CI contract) and
  `check_doc_enums()`. One engine, many profiles: a different vault is a
  different profile, not a fork.
- **Index + search** — a lenient frontmatter index and ranked, section-scoped
  retrieval (`find_sections`) that returns menus, never raw bodies.
- **Task ledger** — `doc_type: task` docs derived from the index, with a
  validated write path.
- **Atomic writes** — a single serializer and `atomic_write_text` /
  `transactional_replace`, so every writer shares one escaping + durability rule.
- **`register_core(mcp, ctx)`** — composes the generic MCP tools (search, doc
  read with a sensitivity gate, project inventory, daily progress, the task
  ledger, schema-validated frontmatter writes) onto any FastMCP server.

## Install

```bash
pip install vault-engine        # or:  uv add vault-engine
```

## Use

```python
from vault_engine.config import Config
from vault_engine.context import ServerContext
from vault_engine.core_tools import register_core
from mcp.server.fastmcp import FastMCP

ctx = ServerContext(Config.from_env())          # your vault + profile
mcp = FastMCP("my-vault-mcp")
register_core(mcp, ctx)                          # + your own tool groups
```

The servers in the family own only their domain (writeup/topology tools, course
tools) and a thin entrypoint; everything generic lives here.
