vanguard-modeling-language 1.0.0

Vanguard Modeling Language compiler for agentic AI

Vanguard Modeling Language

Vanguard Modeling Language is an open-source modeling language compiler aimed to complement agentic AI development in order to define the logics and requirements of prompts into a fixed format in order to mitigate consistency of results among different AI agent models.

Repository: github.com/Selkomark/vanguard-modeling-language

Contributors and AI assistants: see AGENTS.md for project scope and architecture, and TODO.md for the roadmap.

Scope

VML is a compile-time DSL compiler: .vml source in, static artifacts (dist/prompts, dist/finetune, dist/flows, dist/flags, dist/judges, dist/manifest.json) out. It does not call LLMs, invoke MCP, run conversations, or manage session/context state — that belongs to whatever downstream platform consumes these artifacts, not this repo.

Meant to be consumed as a dependency by other projects, e.g. as a git submodule plus pip install -e path/to/vanguard-modeling-language, or via PyPI once published. For integrating VML into a Python or TypeScript project — install, config, and runnable examples of loading compiled artifacts — see docs/integration.md.

Environment

Use a dedicated environment before installing (Python 3.10+).

venv (stdlib)

python3 -m venv .venv
source .venv/bin/activate   # macOS/Linux

On Windows: .venv\Scripts\activate

conda

conda create -n vml python=3.10   # or 3.11+
conda activate vml

Install

Once published to PyPI:

pip install vanguard-modeling-language

From source, with the environment active:

pip install -e ".[dev]"

Requires Python 3.10+.

Compile a project

vml compile examples/support_project

By default, artifacts are written to <project>/dist. Override with --out:

vml compile examples/support_project --out ./build

Outputs (under dist/ by default):

Path	Description
dist/prompts/<Model>.md	Rendered system prompt + constraints
dist/finetune/openai/<Model>.jsonl	OpenAI chat fine-tuning JSONL
dist/finetune/anthropic/<Model>.jsonl	Claude fine-tuning JSONL (Amazon Bedrock format — Anthropic has no hosted fine-tuning API)
dist/finetune/gemini/<Model>.jsonl	Gemini supervised fine-tuning JSONL (Vertex AI format)
dist/flows/<Flow>.flow.json	Conversation flow IR
dist/flags/<Flow>.flags.json	Flag definitions
dist/judges/<Judge>.judge.md	Judge validation prompts
dist/manifest.json	Project artifact index

Validate without writing files:

vml compile examples/support_project --check-only

Language features

• Models with extends, use logic, implements traits
• Flows with stages, routing, flags, MCP actions, and judges
• Imports for DRY composition across .vml files

See docs/language.md and docs/orchestrator.md.

VS Code extension

Editor support (syntax highlighting, snippets, compile diagnostics) lives in vscode-extension/.

Try in development

1. Open vscode-extension/ in VS Code (or the whole repo).
2. Press F5 (Run Extension) to open an Extension Development Host.
3. In that window, open a folder with vml.json (e.g. examples/support_project) and edit .vml files.

Install a VSIX

cd vscode-extension
vsce package    # requires: npm install -g @vscode/vsce

Then in VS Code: Extensions → Install from VSIX…

The extension runs vml compile <project> --check-only when you save or open .vml files. Install the compiler (pip install -e .) so vml is on your PATH (or set vml.compilerPath in settings).

Tests

pytest