Sniffable Python

# 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: 1` or `# SNIFF: glance` — next line is treated as depth 1 (glance).
- `# SNIFF: 2` or `# SNIFF: structure` — next line is depth 2.
- `# SNIFF: 3` or `# 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 summarize` or `moo 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 optional `google-genai` (or REST).

Part of MOOLLM. See repo README and skills/README.