How microsoft/poml works
Project Type and Purpose
• This is an open-source, multi-language toolkit (monorepo) for POML, a Prompt Orchestration Markup Language. It includes:
• A core TypeScript/JavaScript SDK and CLI (packages/poml and related packages)
• A Python SDK and CLI (python/poml)
• A Visual Studio Code extension with an LSP server, commands, and a Webview preview (packages/poml-vscode and packages/poml-vscode-webview)
• Documentation site (docs/) and examples (examples/, gallery/)
• CI/CD pipelines (GitHub Actions, Azure Pipelines) for testing, docs, and publishing to npm, PyPI, and the VSCode Marketplace
Main Components
• Monorepo Root
• CI/CD config (.github/workflows, azure-pipelines.yml)
• Docs configuration (mkdocs.yml, docs/)
• Shared tooling (bump-version.js, webpack/rollup configs)
• Core SDK (packages/poml)
• Parser/Reader: transforms .poml into in-memory representation
• Writer/Renderer: produces final prompt text (and formats for LLM)
• Components: React-style building blocks (document, table, img, role, task, etc.)
• CLI entry point (cli.ts) for local prompt rendering/testing
• TypeScript Build Package (packages/poml-build)
• Bundles core SDK for distribution via npm
• VSCode Extension (packages/poml-vscode)
• Extension host (extension.ts)
• Commands (addResources, showPreview, showSource, promptGallery, etc.)
• LSP Server (packages/poml-vscode/lsp/server.ts) providing diagnostics, auto-completion, formatting
• Webview Panel (packages/poml-vscode-webview) with React content, state management, scroll sync
• Python SDK (python/poml)
• API modules for parsing, templating, rendering prompts
• CLI entry point (cli.py)
• Integrations (LangChain, MLflow, Weave in python/poml/integration)
• External Services
• LLM Providers (OpenAI, Azure, Google APIs)
• VSCode host
Relationships & Data Flows
• Developer → .poml file
• CLI (TS or Python) parses via Reader → builds AST → applies templating → Writer outputs final prompt → sent to LLM API → receives response
• VSCode Extension opens .poml → LSP Server parses & validates → Editor shows diagnostics & auto-completions → “Preview” command sends content to Webview → Webview renders styled prompt
• CI/CD pipelines trigger on commits/PRs → run tests (jest, pytest) → build packages → publish artifacts (npm, PyPI, VSIX)
Architectural Patterns & Principles
• Monorepo with multi-package modularization (core SDK, build, extension, webview, Python)
• Plugin architecture for VSCode (commands + LSP + Webview)
• Separation of concerns: core parsing/rendering vs. presentation (Webview CSS-like styles)
• Multi-language SDKs sharing core concepts