Skip to content

Drafting annotations

suggest_draft() inspects a class or object and proposes editable annotations. By default it uses local rules without an LLM or Hypothesis. Use interactive suggest to develop rules by judging diagrams.

Inspect and apply

Given an existing object root:

from spytial.suggest import suggest_draft

draft = suggest_draft(root)
print(draft.to_source())

Inspect the draft before applying it:

draft.apply()  # Install its enabled annotations on the object's class.
Member Use
draft.suggestions Inspect suggestions, confidence, rationale, and enabled state.
draft.alternatives Inspect suggestions displaced by another choice.
draft.notes Read diagnostics.
draft.to_source() Export decorators; with_comments=False omits rationales.
draft.to_registry() Export constraints and directives as a dictionary.

Export and application use enabled suggestions by default. Pass enabled_only=False to include disabled suggestions. A draft is fixed: applying it does not create a living spec or an interactive session.

Request a model-generated draft

Choose a provider explicitly with enrich=. Add ask= for a specific request:

from spytial.suggest import Codex

draft = suggest_draft(
    root,
    enrich=Codex(),
    ask="Put every child below its parent",
)
print(draft.to_source())

enrich also accepts ClaudeCode(), a model-id string, or a callable (prompt, *, schema) -> dict. CLI providers must be installed and authenticated. Model-id strings require the suggest-llm extra and a configured llm provider. Selector validation needs Node.js.

Pass examples=[...] to check model-authored selectors on additional objects. strategy= adds a generated example; it requires the suggest-search extra. Checks on examples do not establish correctness for every possible input. An unsuccessful enrichment leaves notes on the draft. An explicit ask= raises AskError if its request cannot be translated and validated.

Customize the local rules

Built-in rules recognize common fields such as left, right, and value. Pass registry= to use your own rules. DEFAULT_REGISTRY.copy() provides a starting point; register field or class rules with its heuristic() decorator.

See the API reference for all draft options and heuristic registration.