feat: SML language runtime, APM package, and documentation - #1
Merged
sergio-sisternes-epam merged 11 commits intoMay 23, 2026
Merged
Conversation
Includes formal grammar (EBNF), execution lifecycle, interface resolution algorithm, execution model with policies, attribute reference table, security/trust model, and error model. Resolves the 3 blocking issues identified in spec review: - Mutually exclusive node types (definition vs invocation) - interface+impl co-occurrence with validation - Definition nodes are non-executable (separate lifecycle phase) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
13 positive examples (valid SML syntax), 11 negative examples (invalid combinations that must be rejected), and 7 execution examples (expected input→output pairs for runtime behaviour). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add ast.rs with complete node types (Invocation, InterfaceDef, ImplDef) - Add hand-written embedded-tolerant parser in parser.rs - Add lib.rs module wiring for sml-core - Add PyO3 bindings placeholder in sml-python - All 9 unit tests passing - Remove unused winnow dependency (parser is hand-written) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- registry.rs: SkillRegistry with interface/implementation registration and validation - resolver.rs: Deterministic resolution with hint filtering and priority - executor.rs: Bottom-up execution with policies, retry, failure modes - All 22 tests passing (9 parser + 3 registry + 5 resolver + 5 executor) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Full Python API: parse(), execute(), Document, SmlRegistry - Document exposes definitions() and invocations() accessors - SmlRegistry wraps Rust registry with register/validate methods - pyproject.toml with maturin build backend + ruff/mypy config - cargo check passes cleanly Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- apm.yml manifest with multi-target support - .apm/skills/sml-usage-guide/ with SKILL.md and system prompt examples - .apm/skills/sml-installation/ with SKILL.md - README.md with quick start and architecture overview - dev/evals/evals.json with trigger and content evals - .gitignore for build artifacts and apm_modules Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- .github/workflows/quality.yml with Rust and Python quality jobs - .rustfmt.toml with edition = 2021 - Fix clippy lints (from_str→parse, strip_prefix, sort_by_key) - All 22 tests pass, clippy clean, fmt clean Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- 9 Architecture Decision Records in docs/adrs/ - Python examples: full_pipeline.py, nested_execution.py - ADR index with status table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Scaffold with Astro 5 + Starlight 0.32 - 5 content sections: specification, ADRs, guide, API, installation - starlight-links-validator plugin (zero broken links) - Custom CSS, GitHub social link, pagefind search - .github/workflows/deploy-docs.yml for GitHub Pages deployment - 18 pages built successfully Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Validates semantic correctness of parsed nodes - Checks resolution target presence on invocations - Prevents nested invocations inside definitions - 25 total tests passing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Newer clippy (1.95) flags the ? operator's implicit From::from() as redundant when map_err already produces PyErr. This is inherent to PyO3's error handling pattern. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
This PR introduces SML (Skill Markup Language) -- a lightweight, XML-inspired markup language that lets agents declaratively invoke modular, scoped, and nestable skills directly inside prompts. The goal is to make structured skill invocation first-class, readable, and composable in agent workflows, with a clean separation between the runtime layer (parsing and execution) and the distribution layer (APM packaging).
Approach
The implementation follows a 9-phase plan, each delivered as a separate commit:
Language Specification (Phase 0)
Formal EBNF grammar and 7 specification documents covering the lifecycle, resolution algorithm, execution model, attributes, security model, and error types. Three mutually exclusive node types -- Invocation, InterfaceDefinition, ImplementationDefinition -- are distinguished by the
defineattribute.Conformance Suite (Phase 1)
31 test cases (13 positive, 11 negative, 7 execution scenarios) that define expected parser and executor behaviour independently of the implementation.
Rust Core (Phases 2-3)
parser.rs): Hand-written, embedded-tolerant parser that extracts<skill>tags from arbitrary prompt text. Handles nesting, entity decoding, comments, and mixed content.ast.rs): Complete node types with source spans for error reporting.validator.rs): Semantic validation (resolution targets, definition constraints).registry.rs): Interface/implementation registration with duplicate detection.resolver.rs): Deterministic resolution with language/framework hints and priority-based disambiguation. Fails explicitly on ambiguity.executor.rs): Bottom-up execution with three policies (bottom-up, wrapper, sequential), retry support, and configurable failure modes (halt, skip, partial).All 25 unit tests pass with zero clippy warnings.
Python Bindings (Phase 4)
PyO3 bindings exposing
parse(),execute(),Document, andSmlRegistryto Python. Configured with maturin build backend viapyproject.toml.APM Package (Phase 5)
apm.ymlmanifest with multi-target supportsml-usage-guideskill (syntax rules, few-shot examples, system prompt patterns)sml-installationskill (pip, maturin, platform matrix)dev/evals/(outside.apm/to prevent bundle leakage)Quality Guardrails (Phase 6)
.github/workflows/quality.ymlwith Rust (clippy, rustfmt, cargo test) and Python (ruff, mypy) quality jobs plus a quality-gate aggregator.rustfmt.tomlconfigDocumentation (Phases 7-8)
full_pipeline.py,nested_execution.py)starlight-links-validatorplugin (zero broken links)Key Design Decisions
defineattribute presence -- no overloaded tag semantics