Metadata-Version: 2.4
Name: cadabby
Version: 0.3.0
Summary: Zero-dependency engine for Karpathy-style LLM Wiki vaults with OKF trust tiers
Keywords: llm-wiki,knowledge-base,mcp,okf,obsidian,sqlite
Author: Cadabby Contributors
Requires-Python: >=3.11
Description-Content-Type: text/markdown
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 :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Database
License-File: LICENSE
Project-URL: Documentation, https://github.com/bookian/cadabby#readme
Project-URL: Issues, https://github.com/bookian/cadabby/issues
Project-URL: Source, https://github.com/bookian/cadabby

# Cadabby

> **Epistemically Auditable LLM Wiki Engine for Humans & AI Agents**

Cadabby is a zero-dependency, local-first engine and Model Context Protocol (MCP) server for maintaining living, high-density knowledge vaults. It enables AI agents (Claude Code, Google Antigravity, OpenHands, etc.) and humans (via Obsidian or CLI) to collaboratively build, cross-reference, and audit knowledge graphs anchored by Open Knowledge Foundation (OKF) epistemic trust tiers.

---

## Key Highlights

- **Zero Runtime Dependencies**: Built with 100% pure Python standard library (`CPython >= 3.11`). No pip dependencies.
- **Multi-Domain Cognitive Architecture**: Partition knowledge into independent cognitive domains (e.g., `customers/`, `projects/`, `wiki/`) governed by localized `AGENTS.md` manifests and schemas.
- **Disposable SQLite FTS5 Cache**: Ephemeral, high-performance full-text search and 1-hop graph traversals. Delete `.cadabby/cache.db` at any time with zero data loss.
- **Epistemic Trust Tiers**: Every note carries cryptographically bound attestation (`human-reviewed`, `machine-confirmed`, `stale-verified`, or `unverified`).
- **Drift-Induced Downgrade**: If an agent or user alters note prose without re-verification, its trust tier automatically downgrades to `stale-verified` (verification debt).
- **Normative Six-Gate Linting**: Automated validation for schema, layout, link consistency, provenance, graph connectivity, and verification integrity.
- **Universal Harness Portability**: Works out-of-the-box with Claude Code (`.mcp.json`), Antigravity (native plugin & subagents), and Obsidian.

---

## 1. Installation

Cadabby is a command-line application, so install it as a tool rather than as a
library. Either of these puts `cadabby` on your `PATH` in its own isolated
environment, leaving your system Python untouched:

```bash
uv tool install cadabby    # recommended
pipx install cadabby       # equivalent
```

Verify:

```bash
cadabby --help
```

> **Why not `pip install`?** It works, but it drops Cadabby into whichever
> environment happens to be active, which makes the install easy to lose track of
> and easy to break with an unrelated upgrade. Nothing imports `cadabby` as a
> library, so there is no reason to put it on an interpreter's import path.

Cadabby has **zero runtime dependencies** (pure CPython >= 3.11 standard
library), so installation never pulls in a transitive dependency tree.

### Contributing

Working on Cadabby itself:

```bash
git clone https://github.com/your-org/cadabby.git
cd cadabby
uv sync                    # or: pip install -e .
uv run python -m unittest discover -s tests
```

---

## 2. Initializing a Vault

To scaffold a complete, production-ready knowledge vault:

```bash
# Initialize a new vault with Obsidian integration:
cadabby init --vault my-vault --name my-vault --obsidian
cd my-vault
```

This creates a standardized 3-layer vault layout:

```
my-vault/
├── .cadabby.json         # Vault configuration, trust multipliers & identities
├── .mcp.json             # Universal MCP server config (for Claude Code, Cursor, etc.)
├── AGENTS.md             # Canonical constitution / operational rules for all AI agents
├── CLAUDE.md             # Thin pointer delegating to AGENTS.md
├── GEMINI.md             # Thin pointer delegating to AGENTS.md
├── STYLE.md              # Vault-specific prose and citation guidelines
├── index.md              # Deterministic catalog auto-generated by cadabby
├── log.md                # Append-only activity ledger
│
├── raw/                  # Ground truth sources (PDFs, raw text, research papers)
│
├── wiki/                 # Canonical knowledge domain (5 typed subdirectories)
│   ├── entities/         # Concrete objects, tools, datasets, libraries
│   ├── concepts/         # Abstract ideas, algorithms, techniques
│   ├── syntheses/        # Cross-domain integrations and summaries
│   ├── comparisons/      # Trade-off evaluations (e.g. SQLite-vs-DuckDB)
│   └── guides/           # Actionable procedures and runbooks
│
├── customers/            # (Optional) Custom cognitive domain
│   ├── AGENTS.md         # Domain constitution & schema rules
│   └── acme-corp/        # Flexible, unconstrained subdirectory layout
│
├── .agents/skills/       # Reusable skills: librarian and technician
├── .claude/commands/     # Claude Code slash commands (/ingest, /vault-status, /vault-lint)
└── .obsidian/            # (Optional) Pre-tuned Obsidian desktop settings
```

---

## 3. How to Use Cadabby

### Workflow A: Using AI Agents (Claude Code, Cursor, Windsurf)

1. **Drop a ground truth document** into `raw/`:
   ```bash
   cp ~/Downloads/attention-paper.pdf raw/attention-paper.pdf
   ```

2. **Start your agent inside the vault directory**:
   ```bash
   claude
   ```
   *Claude Code automatically reads `.mcp.json`, launches `cadabby mcp`, and reads `CLAUDE.md` $\rightarrow$ `AGENTS.md`.*

3. **Interact naturally using slash commands or chat**:
   ```
   > /ingest raw/attention-paper.pdf
   ```
   The agent will:
   - Call `vault_search` to check if related concepts already exist.
   - Call `vault_ground` to inspect existing notes and their 1-hop links.
   - Call `vault_scaffold_note` to draft `wiki/concepts/Flash-Attention.md` citing `raw/attention-paper.pdf`.
   - Add `[[wikilinks]]` to existing notes.
   - Call `vault_verify_note` stamping the note with `agent:claude-code`.
   *(Catalog `index.md` and activity `log.md` are kept up to date implicitly; no manual sync needed).*

### Workflow B: Using Google Antigravity

1. **Install the Antigravity plugin**:
   ```bash
   cadabby install --antigravity
   ```
2. Open the vault in Antigravity. The plugin provides:
   - An MCP sidecar running `cadabby mcp`.
   - Two specialized personas:
     - **`@librarian`**: Researches raw sources, checks prior knowledge, scaffolds notes, and resolves links.
     - **`@technician`**: Runs `vault_lint`, verifies cache health, and tracks verification debt.

### Workflow C: Human Reading & Editing (Obsidian & CLI)

1. Open `my-vault/` in **Obsidian**:
   - Wikilinks `[[Note-Stem]]` resolve automatically across subdirectories.
   - `index.md` acts as your curated table of contents.
2. **Review and certify notes**:
   When a human inspects a note and certifies its accuracy:
   ```bash
   cadabby verify wiki/concepts/Flash-Attention --human
   ```
   *This binds the attestation to the exact `sha256` of the note body and upgrades its trust tier to `human-reviewed` ($2.0\times$ search boost).*
3. **If anyone edits the note body**:
   Cadabby automatically detects the SHA-256 mismatch and demotes the note to `stale-verified` (verification debt), prompting re-review.

---

## 4. Cognitive Domains & Domain Manifests

Cadabby supports modular, multi-domain knowledge architectures. While `wiki/` serves as the canonical knowledge base with strictly enforced 5-type directory structures, you can partition knowledge into independent **Cognitive Domains** simply by creating top-level directories (e.g. `customers/`, `projects/`, `research/`, `team/`).

### Creating a Cognitive Domain with `AGENTS.md`

Drop an `AGENTS.md` file into the root of any top-level domain folder to configure validation schemas and define agent directives:

```markdown
---
description: Customer accounts, CRM dossiers, and stakeholders
searchable: true
schema:
  allowed_types:
    - account
    - stakeholder
    - interaction
  require_sources: false
  enforce_layout: false
---

# Customers Domain Directives

1. Every customer note must include account tier and primary contact.
2. Link stakeholder profiles using `[[Stakeholder-Name]]`.
3. Do not store sensitive secrets or credentials in dossiers.
```

### Manifest Configuration Options

| Field | Type | Default | Purpose |
| :--- | :---: | :---: | :--- |
| `description` | string | `"<Domain> domain"` | Human-readable domain description. |
| `searchable` | bool | `true` | Whether notes in this domain are indexed and returned in `vault_search`. |
| `schema.allowed_types` | list[str] | `null` (unrestricted) | Allowed `type:` values in frontmatter. Violations trigger `ENUM_INVALID` in `cadabby lint`. |
| `schema.require_sources`| bool | `false` | When `true`, notes in this domain must specify non-empty `sources: [...]`. |
| `schema.enforce_layout` | bool | `false` | When `true`, notes must live in a subfolder matching their `type` (like in `wiki/`). When `false`, arbitrary directory nesting is permitted. |

### Permissive vs. Strict Domains
- **Permissive Domains** (no `AGENTS.md` or `allowed_types: null`): Any non-empty note type and any folder hierarchy are allowed without triggering lint errors.
- **Strict Domains** (`allowed_types` specified): Linter enforces valid types, while allowing cross-domain wikilinks (`[[Note-Stem]]`) to resolve smoothly across all domains.

### How AI Agents Consume Domain Directives
- **MCP Resources**: Cadabby exposes `vault://domains` (inventory of all discovered domains) and `domain://{name}/directives` (the markdown body of `{domain}/AGENTS.md`).
- **Grounding Enrichment**: When an agent calls `vault_ground` on a note, Cadabby automatically embeds the note's domain definition and localized directives into the response payload.

---

## 5. MCP Architecture (7 Tools & 2 Resources)

Conforming to §5.1-§5.2 of the Technical Specification, Cadabby exposes exactly **7 atomic tools** and **2 dynamic resources** to AI agents:

### Atomic Tools

| Tool | Purpose |
| :--- | :--- |
| **`vault_search`** | Epistemic BM25 full-text search with trust tier boosts, domain filters, and status multipliers. |
| **`vault_ground`** | Retrieves full content, localized domain directives, and 1-hop graph neighborhood (links, backlinks, sources). |
| **`vault_status`** | Epistemic health snapshot: tier counts, domain breakdown, verification debt, and unprocessed `raw/` files. |
| **`vault_scaffold_note`** | Scaffolds a new typed note in any domain with valid OKF frontmatter and generated attribution. |
| **`vault_update_note`** | Non-destructive frontmatter patch, section append, or section replace with optimistic lock. |
| **`vault_verify_note`** | Cryptographically binds an `agent:<client_id>` attestation to the body SHA-256 (refuses `human:*`). |
| **`vault_lint`** | Runs the six normative epistemic lint gates and returns typed diagnostics for self-healing. |

### Dynamic Resources

| Resource URI | MIME Type | Description |
| :--- | :--- | :--- |
| **`vault://domains`** | `application/json` | Real-time inventory of all discovered cognitive domains, descriptions, and schema flags. |
| **`domain://{domain}/directives`** | `text/markdown` | Localized operational instructions and guidelines from `{domain}/AGENTS.md`. |

---

## 6. CLI Command Reference

| Command | Description | Example |
| :--- | :--- | :--- |
| `cadabby init` | Scaffold a new vault with all config & skills | `cadabby init --vault my-vault --obsidian` |
| `cadabby sync` | Scan files, update SQLite cache & rebuild `index.md` | `cadabby sync` |
| `cadabby status` | Report note counts, trust tiers, and verification debt | `cadabby status` |
| `cadabby search` | Epistemic BM25 search with trust boosts & domain filters | `cadabby search "attention mechanism" --domain wiki` |
| `cadabby ground` | Retrieve note content and 1-hop neighborhood | `cadabby ground wiki/concepts/Attention` |
| `cadabby scaffold` | Scaffold a new typed note in any domain | `cadabby scaffold "Transformer" --type concept --domain wiki --desc "Attention model"` |
| `cadabby update` | Patch frontmatter or append/replace sections | `cadabby update wiki/concepts/Transformer --replace-section "Overview:New text"` |
| `cadabby verify` | Stamp cryptographic attestation on note | `cadabby verify wiki/concepts/Transformer --human` |
| `cadabby lint` | Run the six normative epistemic linting gates across all domains | `cadabby lint` |
| `cadabby audit` | Check Git blame provenance of human attestations | `cadabby audit --require-signed` |
| `cadabby mcp` | Launch the JSON-RPC 2.0 stdio MCP server | `cadabby mcp` |
| `cadabby install` | Register MCP configs in Antigravity or Claude Code | `cadabby install --antigravity` |

---

## 7. Epistemic Trust Tiers

| Tier | Multiplier | Description |
| :--- | :---: | :--- |
| `human-reviewed` | **$2.0\times$** | Certified by a validated human reviewer. Body matches `sha256`. |
| `machine-confirmed` | **$1.0\times$** | Synthesized and verified by an automated AI agent. |
| `stale-verified` | **$0.8\times$** | Previously verified, but note prose drifted without re-review (verification debt). |
| `unverified` | **$0.5\times$** | Newly drafted or imported without verification. |

Status multipliers apply on top of trust tiers:
- `evergreen`: **$1.1\times$**
- `active`: **$1.0\times$**
- `draft`: **$0.7\times$**
- `deprecated`: **$0.3\times$**
- `stub`: **$0.2\times$**

---

## 8. Development & Testing

```bash
# Run all unit and integration tests (105 tests):
PYTHONPATH=src python3 -m unittest discover -s tests -v
```

All 12 falsifiable acceptance criteria from §10 are validated in `tests/test_acceptance.py`.

