Metadata-Version: 2.5
Name: disambiguate
Version: 0.4.0
Summary: A tool to resolve markdown glossary terms and their transitive dependencies in topological order in a GitHub project or Obsidian vault.
Project-URL: Bug Tracker, https://github.com/frankify-app/disambiguate/issues
Project-URL: documentation, https://disambiguate.readthedocs.io
Project-URL: repository, https://github.com/frankify-app/disambiguate
Author-email: Frankify <creator@frankify.app>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Disambiguate
<!-- markdownlint-disable MD033 -->

<p align="center">
  <a href="https://github.com/frankify-app/disambiguate/actions/workflows/ci.yml?query=branch%3Amain">
    <img src="https://img.shields.io/github/actions/workflow/status/frankify-app/disambiguate/ci.yml?branch=main&label=CI&logo=github&style=flat-square" alt="CI Status" >
  </a>
  <a href="https://codecov.io/gh/frankify-app/disambiguate">
    <img src="https://img.shields.io/codecov/c/github/frankify-app/disambiguate.svg?logo=codecov&logoColor=fff&style=flat-square" alt="Test coverage percentage">
  </a>
</p>
<p align="center">
  <a href="https://github.com/astral-sh/uv">
    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
  </a>
  <a href="https://github.com/astral-sh/ruff">
    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
  </a>
  <a href="https://github.com/j178/prek">
    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json" alt="prek">
  </a>
</p>
<p align="center">
  <a href="https://pypi.org/project/disambiguate/">
    <img src="https://img.shields.io/pypi/v/disambiguate.svg?logo=python&logoColor=fff&style=flat-square" alt="PyPI Version">
  </a>
  <img src="https://img.shields.io/pypi/pyversions/disambiguate.svg?style=flat-square&logo=python&amp;logoColor=fff" alt="Supported Python versions">
  <img src="https://img.shields.io/pypi/l/disambiguate.svg?style=flat-square" alt="License">
</p>

---

**Source Code**: <a href="https://github.com/frankify-app/disambiguate" target="_blank">https://github.com/frankify-app/disambiguate </a>

---

Disambiguate resolves markdown glossary terms and their transitive
dependencies in topological order. Point it at a directory of `*.md` term
files in either [GitHub format](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/github-format.md) or
[Obsidian format](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/obsidian-format.md), ask for a slug or two,
and get back a self-contained markdown document where every term is
defined before it is referenced.

## Quickstart

```bash
uvx disambiguate                       # render the entire glossary
uvx disambiguate topological-order     # render one term and its dependency closure
uvx disambiguate --from notes.md       # extract glossary-shaped links from a doc
uvx disambiguate --explain             # render Disambiguate's own bundled spec
uvx disambiguate --lint                # validate the glossary
uvx disambiguate --drift               # detect prose drifting from the glossary
uvx disambiguate prune                 # remove terms no file links
```

The runtime is stdlib-only — `pip install disambiguate` brings in nothing
else. `uvx` works without an explicit install.

## Installation

```bash
pip install disambiguate
```

## How it works

[Prune](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/prune.md) removes terms no file in the repository
links. It serves repos that acquire a shared term set and use only part of
it. A term consents by carrying an
[auto-prune](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/auto-prune.md) annotation.

The pipeline parses each [term](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/term.md) into a body plus a
list of [cross-references](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/cross-reference.md), builds a
[dependency](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/dependency.md) graph from those references, then
runs the [resolver](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/resolver.md) to produce
[topological order](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/topological-order.md). The same pipeline
backs [from-mode](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/from-mode.md) and `--explain`.

`--drift` detects [drift](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/drift.md) — prose that uses the
vocabulary without following it: terms mentioned but never linked, and (as
the checks grow) forbidden synonyms and wrong casing. Each
[drift-check](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/drift-check.md) reports fatal findings named by
a stable [rule-code](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/rule-code.md); false positives are
silenced precisely with [ignore-hints](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/ignore-hint.md), and
already-drifted repos adopt incrementally through a checked-in
[drift-baseline](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/drift-baseline.md).

For the architectural map, see [docs/architecture.md](https://github.com/frankify-app/disambiguate/blob/main/docs/architecture.md).
For the full vocabulary, see the
[bundled glossary](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/disambiguate.md) — Disambiguate's own
dogfood.

## Contributing

See [CONTRIBUTING.md](https://github.com/frankify-app/disambiguate/blob/main/CONTRIBUTING.md). Conventional commits required.
A release is a version bump merged to `main` ([docs/releasing.md](https://github.com/frankify-app/disambiguate/blob/main/docs/releasing.md)).

## Org glossary

Org-genome terms stamped in by the
[template](https://github.com/pandoscope/agentic-engineering-template)
(rooted here so `disambiguate --lint` can reach them):
[org](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/org.md),
[org genome](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/org-genome.md),
[pando](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/pando.md),
[pando cell](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/pando-cell.md),
[reinset](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/reinset.md),
[principal](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/principal.md),
[agent session](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/agent-session.md),
[memory repo](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/memory-repo.md),
[decision-memory](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/decision-memory.md),
[evidence-memory](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/evidence-memory.md),
[session-memory](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/session-memory.md),
[pandoscope template](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/pandoscope-template.md),
[template stamp](https://github.com/frankify-app/disambiguate/blob/main/docs/glossary/template-stamp.md).
