tomevault-io Sniffable Python — depth levels and abstractions
How to mark and sniff Python (and other files) at multiple depths. Moo and other tools use this convention.
1. Sniff depth levels (three, extensible)
Three standard depth levels for structural sniffing. Higher depth includes all lower levels.
| Level | Name | Numeric | Python: what is included |
|---|---|---|---|
| 1 | glance | 1 | Section comments: # ---, # SECTION, # UPPERCASE_LABEL, # Title Case (single-line). Module-level outline only. |
| 2 | structure | 2 | Glance + class, def, async def, @decorator. The skeleton of the file. |
| 3 | full | 3 | Structure + any other line the sniffer classifies as "smelly" (structural). Everything the sniffer emits. |
- glance — Smallest useful outline (sections only). Good for indexes and "what's in this file?"
- structure — Default for "show me the shape": classes and functions, plus sections.
- full — No filtering; all smelly lines. Use when you want every structural line.
Other levels or names are allowed: tools should accept numeric depth (1, 2, 3, …) or canonical names (glance, structure, full) and may support file-type-specific semantics.
2. Marking Python (optional override)
By default, the sniffer assigns depth by line kind (section = 1, class/def/decorator = 2, rest = 3). Authors can override with a comment on the previous line:
# SNIFF: 1or# SNIFF: glance— next line is treated as depth 1 (glance).# SNIFF: 2or# SNIFF: structure— next line is depth 2.# SNIFF: 3or# SNIFF: full— next line is depth 3.
Alternative form:
# depth: glance/# depth: structure/# depth: full
Only the line immediately following the comment is overridden. Use to promote a line into a shallower depth (e.g. a key function into glance) or to demote (e.g. treat a decorator as full-only).
3. Other file types
Depth semantics can differ by type:
- YAML: e.g. glance = top-level keys, structure = keys + list markers, full = all key/list lines.
- Markdown: glance = H1–H2, structure = H1–H4, full = all headers.
- TS/JS: glance = export lines, structure = export + function/class/interface, full = all smelly.
Moo (and this skill) define the Python mapping explicitly; other types may be added with their own depth tables. The same numeric/name convention (1/2/3, glance/structure/full) is reused where it fits.
4. Abstractions beyond depth
Beyond structural depth, files can have abstractions that are not just "which lines to show":
- description — One-line description (e.g. from docstring or a tag). Could be first docstring line or
# description: .... - glance — Short human or generated summary (e.g. GLANCE.yml content, or a cached one-liner).
- LLM summary — A model-generated summary of the file, cached locally (e.g. under
.moollm/skills/moo/cache/or similar). Keyed by (repo, branch, path, abstract_type). Moo can call an LLM (e.g. Gemini) to produce and cache this.
These are not depth levels; they are separate axes. A tool might offer:
moo sniff --depth glance— structural outline only.moo summarizeormoo abstract --kind summary— LLM summary, with caching and optional--provider gemini.
Design leaves room for more abstraction kinds and providers without overloading the depth semantics.
5. Moo integration
- Sniff:
moo sniff ... --depth glance|structure|full(or--depth 1|2|3). Emits only lines at or above the requested depth. Default: structure (2). - Summarize:
moo summarize ... [--provider gemini] [--model MODEL]— calls LLM, caches under moo cache, prints summary. Requires API key (e.g. GEMINI_API_KEY) and optionalgoogle-genai(or REST).
Part of MOOLLM. See repo README and skills/README.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.