Astichi user documentation

astichi is a library for composing Python-shaped fragments: compile marker-bearing source into a Composable, wire fragments with a builder, then materialize and emit when you need runnable or inspectable Python.

These pages describe the current user-facing behavior in src/ and the test suite.

Where to start

You want…	Read
End-to-end flow (compile → build → materialize → emit)	Guide: Using the API
Phase-1 error categories	Reference: Errors
Public imports and submodules	Reference: Public API
compile(...) and source origins	Reference: Compile API
Composable.emit / materialize	Reference: Composable API
Builder (fluent, handle-oriented, and data-driven named API)	Reference: Builder API
Composable.describe() descriptor surfaces	Reference: Descriptor API
Inventory records and maps	Reference: Inventory API
Assembler candidate lookup (declarative wiring)	Reference: Assembler Scope
Target addressing (A.first[0], …)	Reference: Addressing
Marker vocabulary	Reference: Markers
Managed Python imports	Reference: astichi_pyimport
Final generated comments	Reference: astichi_comment

Layout

• guide/ — short, task-oriented walkthroughs.
• reference/ — compact, linkable API and behavior.