Vanguard Modeling Language

VML is a compile-time DSL compiler for agentic AI: define an agent's system prompt, constraints, fine-tuning examples, and conversation flow declaratively in .vml files, and compile them into deterministic artifacts (prompts, fine-tuning JSONL, flow graphs, judge prompts) that stay consistent across models and sessions.

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

Use VML in your project

pip install vanguard-modeling-language

A minimal project — a vml.json config plus one model — and compiling it:

mkdir -p my-agent/models
cat > my-agent/vml.json <<'JSON'
{ "project": { "name": "my-agent" } }
JSON
cat > my-agent/models/support.vml <<'VML'
model Support {
  system "You are a support agent. Be concise and ask for an order id on shipping issues."
  constraints {
    must "ask for an order id when the user reports a shipping problem"
  }
}
VML

vml compile my-agent --out my-agent/dist

That writes my-agent/dist/prompts/Support.md and my-agent/dist/manifest.json. Depending on what your .vml files declare, vml compile also writes:

Full walkthrough, including the programmatic Python API for getting compiled data back as in-memory objects instead of files: docs/integration.md. Three runnable example projects (fine-tuning export, a multi-persona prompt library, a flow router) live in examples/.

VML is compile-time by default: it does not invoke MCP, run conversations, or manage session state. That's the job of whatever consumes these artifacts, not this library — see docs/orchestrator.md for the artifact contract an orchestrator would build against. The one deliberate exception is vml train below — it does call an LLM provider's own fine-tuning API, as a bounded, one-shot job submission, not a runtime.

Fine-tuning and training

vml train <project> <provider> --model <Name> --base-model <id> [...] submits a fine-tuning job for one model's compiled finetune examples — the same records dist/finetune/<provider>/<Model>.jsonl already contains, sent straight to the provider rather than requiring a separate upload step.

# Submit and wait for an OpenAI fine-tune (needs OPENAI_API_KEY)
vml train my-agent openai --model Support --base-model gpt-4o-mini

# Submit and immediately return with a job id instead of blocking
vml train my-agent openai --model Support --base-model gpt-4o-mini --no-wait

# Local LoRA fine-tune + GGUF export, on a CUDA machine with the `local` extra installed
vml train my-agent local --model Support --base-model unsloth/Qwen3-4B-Instruct --output-dir ./out

Each provider's dependency is genuinely optional — plain pip install vanguard-modeling-language still gets you a dependency-light compiler; nothing imports a provider's SDK until you actually select that provider. See AGENTS.md's "Fine-tuning and training" section for the module layout (src/vml/train/) if you're calling these from Python instead of the CLI.

Language

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

Full syntax reference: docs/language.md.

Develop this repo

Clone the repo, then set up an environment (Python 3.10+):

python3 -m venv .venv && source .venv/bin/activate   # or: conda create -n vml python=3.10 && conda activate vml
pip install -e ".[dev]"

dev pulls in the lightweight fine-tuning provider SDKs too (openai, google-cloud-aiplatform, boto3) so their tests actually run. It deliberately does not include local's extra (unsloth/torch — heavy, CUDA-only); tests/test_train_local.py detects that and skips the parts that need it, so a normal dev machine still gets a full green pytest run.

Compile the bundled full-featured example:

vml compile examples/support_project
vml compile examples/support_project --check-only   # validate only, no output

Run the test suite:

pytest

VS Code extension (syntax highlighting, snippets, compile diagnostics) lives in vscode-extension/:

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.

To package it: cd vscode-extension && vsce package (requires npm install -g @vscode/vsce), then Extensions → Install from VSIX… in VS Code. The extension runs vml compile <project> --check-only on save; it needs vml on PATH (pip install -e .) or vml.compilerPath set in settings.

See AGENTS.md for project scope and architecture.