Metadata-Version: 2.5
Name: vanguard-modeling-language
Version: 1.3.0
Summary: Vanguard Modeling Language compiler for agentic AI
Project-URL: Homepage, https://github.com/Selkomark/vanguard-modeling-language
Project-URL: Repository, https://github.com/Selkomark/vanguard-modeling-language
Project-URL: Issues, https://github.com/Selkomark/vanguard-modeling-language/issues
Project-URL: Changelog, https://github.com/Selkomark/vanguard-modeling-language/blob/main/CHANGELOG.md
Author-email: Selkomark <mahan@selkomark.com>
License: MIT License
        
        Copyright (c) 2026 Selkomark
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,compiler,dsl,fine-tuning,llm,prompt-engineering
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.10
Requires-Dist: lark>=1.2.0
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34.0; extra == 'bedrock'
Provides-Extra: dev
Requires-Dist: boto3>=1.34.0; extra == 'dev'
Requires-Dist: google-cloud-aiplatform>=1.60.0; extra == 'dev'
Requires-Dist: google-cloud-storage>=2.14.0; extra == 'dev'
Requires-Dist: openai>=1.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-cloud-aiplatform>=1.60.0; extra == 'gemini'
Requires-Dist: google-cloud-storage>=2.14.0; extra == 'gemini'
Provides-Extra: local
Requires-Dist: datasets>=2.19.0; extra == 'local'
Requires-Dist: torch; extra == 'local'
Requires-Dist: trl>=0.9.0; extra == 'local'
Requires-Dist: unsloth; extra == 'local'
Provides-Extra: openai
Requires-Dist: openai>=1.30.0; extra == 'openai'
Provides-Extra: train
Requires-Dist: boto3>=1.34.0; extra == 'train'
Requires-Dist: google-cloud-aiplatform>=1.60.0; extra == 'train'
Requires-Dist: google-cloud-storage>=2.14.0; extra == 'train'
Requires-Dist: openai>=1.30.0; extra == 'train'
Description-Content-Type: text/markdown

# 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](https://github.com/Selkomark/vanguard-modeling-language)

## Use VML in your project

```bash
pip install vanguard-modeling-language
```

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

```bash
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:

| Path | Description |
|------|-------------|
| `dist/prompts/<Model>.md` | Rendered system prompt + constraints (markdown docs) |
| `dist/system/<Model>.txt` | Plain-text system prompt — for sending directly to a live LLM, not documentation |
| `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 |

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

| Provider | Backs | Install |
|---|---|---|
| `openai` | [OpenAI fine-tuning API](https://platform.openai.com/docs/guides/fine-tuning) | `pip install vanguard-modeling-language[openai]` |
| `gemini` | [Vertex AI supervised tuning](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini-use-supervised-tuning) | `pip install vanguard-modeling-language[gemini]` |
| `bedrock` (aliases: `claude`, `anthropic`) | [AWS Bedrock custom models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-customization-prepare.html) — the only way to fine-tune Claude; Anthropic has no hosted fine-tuning API of its own | `pip install vanguard-modeling-language[bedrock]` |
| `local` | [Unsloth](https://unsloth.ai) LoRA/QLoRA, in-process, GGUF export — for self-hosted models (e.g. served via Ollama) | `pip install vanguard-modeling-language[local]` (heavy: torch/unsloth, needs a CUDA GPU) |

```bash
# 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](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](docs/language.md).

## Develop this repo

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

```bash
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:

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

Run the test suite:

```bash
pytest
```

VS Code extension (syntax highlighting, snippets, compile diagnostics) lives in [`vscode-extension/`](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](AGENTS.md) for project scope and architecture.
