a. Current import surface and migration notes

Updated Jul 27, 2026

The mixed-package skeleton already exposes a small, concrete import surface that later roadmap slices will extend in place:

import stilyagi
from stilyagi import engine, model
from stilyagi.config import StilyagiConfig
from stilyagi.diagnostics import Diagnostic
from stilyagi.nlp import SpacyProviderConfig

The current placeholder modules are intentionally narrow, but each one already owns a long-lived architectural role:

  • stilyagi.hello() is a placeholder that exercises the embedded Rust bridge directly; it is not the canonical smoke check. See §1b for the supported package smoke check.
  • stilyagi.engine is the future home for execution planning, fix planning, rendering, and runner orchestration. It now also exposes the first real extraction call:
  from stilyagi import engine, model

  document = engine.extract_document("# Heading", model.Syntax.MARKDOWN)
  assert document.syntax is model.Syntax.MARKDOWN
  assert document.regions[0].kind == "heading"
  assert document.regions[0].text == "Heading"
  assert document.ir is not None
  assert document.ir["schema_version"] == "1.0.0"

Query the current IR region-kind vocabulary before writing code that branches on region kinds:

  from stilyagi import engine

  assert "heading" in engine.supported_region_kinds()
  assert "link_title" in engine.supported_region_kinds()
  • stilyagi.model is the future home for document, region, sentence, and token runtime objects.
  • stilyagi.config.StilyagiConfig is the Python-side configuration boundary.
  • stilyagi.diagnostics.Diagnostic is the Python-side diagnostic boundary.
  • stilyagi.nlp is the future natural-language-processing (NLP) provider and provider-configuration boundary.
  • stilyagi.plugins defines the entry-point group names that future external rule and capability packages will use.
  • stilyagi.rules and stilyagi.rules.builtin reserve the bundled-rule and third-party-rule namespace layout.

Users migrating from the provisional repository layout should also note one removal:

python -m stilyagi.smoke

The supported smoke-check entrypoint is python -m stilyagi.smoke. It exits with status 0 when the embedded Rust extension is installed and reachable from Python, and 1 on any smoke-check failure.

The same check is available as a public Python API:

from stilyagi.smoke import SmokeCheckError, smoke_installed_package

try:
    smoke_installed_package()
except SmokeCheckError as err:
    print(f"Bridge check failed: {err}")

stilyagi.pure was a compatibility shim from the pre-workspace layout and is no longer part of the supported package contract. Use smoke_installed_package() when code needs to prove the installed package can cross the Python-to-Rust bridge; it raises SmokeCheckError for bridge errors, unexpected return types, and document validation failures.

The new extraction path is intentionally narrow in this slice:

  • stilyagi.engine.extract_document(...) is the supported public API for the first real Rust extraction call.
  • model.Syntax.MARKDOWN and model.Syntax.PYTHON_DOCSTRING are currently implemented for that API.
  • model.Syntax.RUST_DOC_COMMENT is implemented for that API.
  • Markdown documents, Python docstrings, and Rust doc comments expose a parsed document.ir mapping containing the canonical IR envelope. That mapping includes schema metadata, line_index, tree nodes, region segments, and content hashes.
  • Markdown IR regions currently include text-bearing heading, paragraph, and table_cell regions; structural list_item and blockquote container regions; source-backed whole-block frontmatter; and synthetic decoded image_alt and link_title regions.
  • Python docstring extraction emits python_docstring regions for module, class, and function docstrings. Each region includes source-backed segments and owner metadata in document.ir, so later rules can tell whether the prose belongs to a module, class, method, or function without walking raw Python syntax nodes.
  • document.regions exposes the same supported region-kind spellings as a compact typed Python view. Inspect region.kind and region.text for common workflows, and use document.ir["regions"] when byte spans, scopes, or segment origins are needed.
  • When document.ir["regions"] contains an unknown future region kind, the Python adapter logs a warning and preserves the region in document.ir rather than rejecting the document.
  • list_item and blockquote regions are containers. Their prose normally appears in child regions linked through parent_region.
  • image_alt and link_title expose decoded lint text. They are inspection surfaces in document.ir, but their segments are synthetic until byte-accurate edit spans are implemented.
  • stilyagi._stilyagi_rs remains an internal bridge module. User code should call stilyagi.engine.extract_document(...) rather than importing the raw bridge directly.

A minimal Python docstring extraction example:

from stilyagi import engine, model

source = '''"""Module docs."""


class Example:
    """Class docs."""
'''

document = engine.extract_document(source, model.Syntax.PYTHON_DOCSTRING)
assert [region.kind for region in document.regions] == [
    "python_docstring",
    "python_docstring",
]
assert document.ir is not None
assert document.ir["regions"][1]["owner"] == {
    "kind": "class",
    "name": "Example",
    "qualname": "Example",
}

Bridge helpers: stilyagi_extract::RegionKind::ALL and RegionKind::ir_region_kind() are Rust-internal bridge helpers and are not exposed across the Python boundary. Use engine.supported_region_kinds() as the Python-facing source of truth for supported region kinds. See the RegionKind and typed ExtractRegion API for the Rust details.