pcl-lang 0.1.0__tar.gz

pcl_lang-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# uv / virtualenv
+.venv/
+.python-version
+uv.lock
+
+# Build / dist
+*.egg-info/
+dist/
+build/
+
+# pytest / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# macOS
+.DS_Store

pcl_lang-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,64 @@
+# Development Guide
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (package manager)
+
+## Setup
+
+```bash
+cd src/pcl
+
+# Create virtual environment and activate it
+uv venv && source .venv/bin/activate
+
+# Install the package in editable mode with dev dependencies
+uv pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+uv run pytest tests/ -q
+```
+
+With coverage:
+
+```bash
+uv run pytest tests/ --cov=pcl --cov-report=term-missing
+```
+
+## Using the CLI
+
+After installation, the `pcl` command is available:
+
+```bash
+pcl check examples/agent.pcl
+pcl compile examples/agent.pcl
+pcl render examples/agent.pcl --var date=2025-01-01 --var query="hello" --var premium=true
+pcl watch examples/agent.pcl --var date=2025-01-01
+```
+
+## Building a Distribution
+
+```bash
+uv run python -m build
+```
+
+This produces a wheel and sdist in `dist/`.
+
+## Project Layout
+
+```
+src/pcl/
+  src/pcl/          # package source
+    __init__.py     # public API (compile, render)
+    parser.py       # line-by-line recursive descent parser
+    compiler.py     # two-phase IR compiler
+    cli.py          # Typer CLI
+    errors.py       # PCLError with line/file context
+  tests/            # pytest test suite
+  examples/         # sample .pcl files
+  pyproject.toml    # build config (hatchling)
+```

pcl_lang-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanay Deshmukh
+
+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.

pcl_lang-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: pcl-lang
+Version: 0.1.0
+Summary: A DSL for authoring, composing, and managing LLM prompts as modular, version-controlled artifacts
+Project-URL: Homepage, https://github.com/cybergla/prompt-composition-language
+Project-URL: Repository, https://github.com/cybergla/prompt-composition-language
+Author: Tanay Deshmukh
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cbor2>=5.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PCL — Prompt Composition Language
+
+PCL is a small DSL for authoring, composing, and managing LLM prompts as modular, version-controlled artifacts. A `.pcl` file compiles to a plain text string ready to use as a system prompt with any LLM API.
+
+# Why PCL?
+
+I came up with PCL as a way to manage prompts when they get too large and unwieldy. Most agentic applications today involve persisting prompts as a bunch of text/markdown files across disparate locations which are then read at runtime before using them for an LLM inference request. Parts of the prompt are often static (rules, persona, tools) while some can be more dynamic (user messages, context). Managing multiple sets of prompt .md files, with different versions, becomes a real engineering challenge. Template engines like Jinja alleviate this problem somewhat but I wanted something that went beyond simple variable substitution and was specifically tailored for LLM applications.
+
+With PCL you get in-built support for templating, composition, compile time checks etc. Think of prompts that same way as you do code. You define your prompts as a modular set of text files (`.pcl` files), then have the compiler compile and weave the prompts together into a single IR template, which can be rendered at runtime with variable substitution. 
+
+pcl files are just like any other source- version controlled, with a well defined syntax.
+
+### Author
+
+Tanay Deshmukh (& vibe-coded with Claude)
+
+---
+
+## Features
+
+- **Blocks** — define named fragments with `@block name:`, compose them with `@include`
+- **Imports** — split prompts across files with `@import ./file.pcl [as ns]`
+- **Variables** — `${var}` resolved at render time; `${var | default}` for fallbacks
+- **Conditionals** — `@if variable:` / `@if not variable:` for truthiness-based branching
+- **Raw blocks** — `@raw` / `@end` passes content through unmodified (no interpolation)
+- **Comments** — lines starting with `#` are stripped from output
+- **Frontmatter** — optional YAML metadata (`version`, `description`, arbitrary keys)
+
+---
+
+## Installation
+
+Requires Python 3.11+. Recommend using [uv](https://github.com/astral-sh/uv) for environment management.
+
+```bash
+git clone <repo>
+cd pcl
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+Verify:
+
+```bash
+pcl --help
+```
+
+---
+
+## CLI
+
+### `pcl compile`
+
+Compile a `.pcl` file and dump its intermediate representation — a tree of `TEXT`, `VAR`, and `IF` segments. Useful for inspecting template structure before rendering.
+
+```bash
+pcl compile examples/agent.pcl
+```
+
+Example output:
+
+```
+Metadata:
+  version: 1.0
+  description: Research assistant system prompt
+
+Segments:
+TEXT  'You are an expert research assistant...'
+VAR   ${date}
+IF    premium:
+  TEXT  'You have access to the premium document index.'
+IF    not premium:
+  TEXT  'Upgrade to unlock the premium document index.'
+VAR   ${query | no query provided}
+```
+
+Use `-o`/`--output` to write the compiled IR to a binary `.pclc` file instead of printing it. This enables compile-once-render-many workflows without re-parsing source files.
+
+```bash
+pcl compile examples/agent.pcl -o agent.pclc
+# Compiled to agent.pclc
+```
+
+### `pcl render`
+
+Render a `.pcl` or `.pclc` file with explicit variable values.
+
+```bash
+# From source
+pcl render examples/agent.pcl \
+  --var date=2026-02-28 \
+  --var query="What is alignment?" \
+  --var premium=true
+
+# From pre-compiled .pclc (no re-parsing)
+pcl render agent.pclc \
+  --var date=2026-02-28 \
+  --var query="What is alignment?" \
+  --var premium=true
+```
+
+`--var` accepts `key=value`. Values `true` and `false` are coerced to booleans.
+
+### `pcl check`
+
+Validate a `.pcl` file without producing output. Exits `0` on success, `1` on error. Prints the error message and line number on failure.
+
+```bash
+pcl check examples/agent.pcl
+```
+
+### `pcl watch`
+
+Recompile whenever the file changes. Accepts the same `--var` flags as `render`.
+
+```bash
+pcl watch examples/agent.pcl \
+  --var date=2026-02-28 \
+  --var premium=false
+```
+
+---
+
+## Python API
+
+```python
+from pcl import compile, render, serialize, deserialize, CompiledTemplate
+import cbor2
+
+# compile() — produces a CompiledTemplate (IR) with metadata and segments
+template = compile("examples/agent.pcl")
+print(template.metadata)    # {"version": 1.0, "description": "..."}
+print(template.segments)    # [str, VarRef, Conditional, ...]
+
+# render() — resolves variables and conditionals, returns final string
+prompt = render("examples/agent.pcl", variables={
+    "date": "2026-02-28",
+    "query": "What is alignment?",
+    "premium": True,
+})
+print(prompt)
+
+# compile once, render many — avoids re-parsing for each variable set
+template = compile("examples/agent.pcl")
+for query in queries:
+    prompt = render(template, variables={"date": "2026-02-28", "query": query})
+
+# serialize to .pclc — write compiled IR to disk
+with open("agent.pclc", "wb") as f:
+    f.write(cbor2.dumps(serialize(template)))
+
+# deserialize from .pclc — reconstruct IR without re-parsing source
+with open("agent.pclc", "rb") as f:
+    template = deserialize(cbor2.loads(f.read()))
+prompt = render(template, variables={"date": "2026-02-28", "query": "..."})
+```
+
+---
+
+## Language Quick Reference
+
+```pcl
+---
+version: 1.0
+description: Optional YAML frontmatter — available as metadata, not in output
+---
+
+@import ./other.pcl
+@import ./lib.pcl as lib
+
+# This is a comment — stripped from output
+
+@block intro:
+    Defined here, emitted only when @include'd.
+
+@include intro          # emit a local block
+@include lib.greet      # emit a named block from an imported file
+@include other          # emit the entire body of other.pcl
+
+@if premium:
+    Shown only when premium is truthy.
+
+@if not premium:
+    Shown only when premium is falsy or absent.
+
+Hello ${name}!              # required variable — error if missing
+Hello ${name | world}!      # variable with default
+
+@raw
+${not_interpolated}  @not_a_directive  # this is not a comment
+@end
+
+\@block  →  literal @block in output
+\#       →  literal # in output
+\${      →  literal ${ in output
+```
+
+---
+
+## Examples
+
+The `examples/` directory contains a multi-file prompt:
+
+| File | Purpose |
+|------|---------|
+| `examples/agent.pcl` | Main agent prompt — imports persona and tools |
+| `examples/persona.pcl` | Persona blocks (`researcher`, `brief`) |
+| `examples/tools.pcl` | Tool description blocks (`search`, `browse`, `premium_index`) |
+
+```bash
+pcl render examples/agent.pcl \
+  --var date=2026-02-28 \
+  --var query="Explain quantum entanglement" \
+  --var premium=false
+```
+
+---
+
+## Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+With coverage:
+
+```bash
+uv run pytest tests/ --cov=pcl --cov-report=term-missing
+```
+
+---
+
+## VS Code Extension
+
+Syntax highlighting is in a separate repo: [`src/pcl-vscode`](https://github.com/cybergla/pcl-vscode).

pcl_lang-0.1.0/README.md

@@ -0,0 +1,236 @@
+# PCL — Prompt Composition Language
+
+PCL is a small DSL for authoring, composing, and managing LLM prompts as modular, version-controlled artifacts. A `.pcl` file compiles to a plain text string ready to use as a system prompt with any LLM API.
+
+# Why PCL?
+
+I came up with PCL as a way to manage prompts when they get too large and unwieldy. Most agentic applications today involve persisting prompts as a bunch of text/markdown files across disparate locations which are then read at runtime before using them for an LLM inference request. Parts of the prompt are often static (rules, persona, tools) while some can be more dynamic (user messages, context). Managing multiple sets of prompt .md files, with different versions, becomes a real engineering challenge. Template engines like Jinja alleviate this problem somewhat but I wanted something that went beyond simple variable substitution and was specifically tailored for LLM applications.
+
+With PCL you get in-built support for templating, composition, compile time checks etc. Think of prompts that same way as you do code. You define your prompts as a modular set of text files (`.pcl` files), then have the compiler compile and weave the prompts together into a single IR template, which can be rendered at runtime with variable substitution. 
+
+pcl files are just like any other source- version controlled, with a well defined syntax.
+
+### Author
+
+Tanay Deshmukh (& vibe-coded with Claude)
+
+---
+
+## Features
+
+- **Blocks** — define named fragments with `@block name:`, compose them with `@include`
+- **Imports** — split prompts across files with `@import ./file.pcl [as ns]`
+- **Variables** — `${var}` resolved at render time; `${var | default}` for fallbacks
+- **Conditionals** — `@if variable:` / `@if not variable:` for truthiness-based branching
+- **Raw blocks** — `@raw` / `@end` passes content through unmodified (no interpolation)
+- **Comments** — lines starting with `#` are stripped from output
+- **Frontmatter** — optional YAML metadata (`version`, `description`, arbitrary keys)
+
+---
+
+## Installation
+
+Requires Python 3.11+. Recommend using [uv](https://github.com/astral-sh/uv) for environment management.
+
+```bash
+git clone <repo>
+cd pcl
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+Verify:
+
+```bash
+pcl --help
+```
+
+---
+
+## CLI
+
+### `pcl compile`
+
+Compile a `.pcl` file and dump its intermediate representation — a tree of `TEXT`, `VAR`, and `IF` segments. Useful for inspecting template structure before rendering.
+
+```bash
+pcl compile examples/agent.pcl
+```
+
+Example output:
+
+```
+Metadata:
+  version: 1.0
+  description: Research assistant system prompt
+
+Segments:
+TEXT  'You are an expert research assistant...'
+VAR   ${date}
+IF    premium:
+  TEXT  'You have access to the premium document index.'
+IF    not premium:
+  TEXT  'Upgrade to unlock the premium document index.'
+VAR   ${query | no query provided}
+```
+
+Use `-o`/`--output` to write the compiled IR to a binary `.pclc` file instead of printing it. This enables compile-once-render-many workflows without re-parsing source files.
+
+```bash
+pcl compile examples/agent.pcl -o agent.pclc
+# Compiled to agent.pclc
+```
+
+### `pcl render`
+
+Render a `.pcl` or `.pclc` file with explicit variable values.
+
+```bash
+# From source
+pcl render examples/agent.pcl \
+  --var date=2026-02-28 \
+  --var query="What is alignment?" \
+  --var premium=true
+
+# From pre-compiled .pclc (no re-parsing)
+pcl render agent.pclc \
+  --var date=2026-02-28 \
+  --var query="What is alignment?" \
+  --var premium=true
+```
+
+`--var` accepts `key=value`. Values `true` and `false` are coerced to booleans.
+
+### `pcl check`
+
+Validate a `.pcl` file without producing output. Exits `0` on success, `1` on error. Prints the error message and line number on failure.
+
+```bash
+pcl check examples/agent.pcl
+```
+
+### `pcl watch`
+
+Recompile whenever the file changes. Accepts the same `--var` flags as `render`.
+
+```bash
+pcl watch examples/agent.pcl \
+  --var date=2026-02-28 \
+  --var premium=false
+```
+
+---
+
+## Python API
+
+```python
+from pcl import compile, render, serialize, deserialize, CompiledTemplate
+import cbor2
+
+# compile() — produces a CompiledTemplate (IR) with metadata and segments
+template = compile("examples/agent.pcl")
+print(template.metadata)    # {"version": 1.0, "description": "..."}
+print(template.segments)    # [str, VarRef, Conditional, ...]
+
+# render() — resolves variables and conditionals, returns final string
+prompt = render("examples/agent.pcl", variables={
+    "date": "2026-02-28",
+    "query": "What is alignment?",
+    "premium": True,
+})
+print(prompt)
+
+# compile once, render many — avoids re-parsing for each variable set
+template = compile("examples/agent.pcl")
+for query in queries:
+    prompt = render(template, variables={"date": "2026-02-28", "query": query})
+
+# serialize to .pclc — write compiled IR to disk
+with open("agent.pclc", "wb") as f:
+    f.write(cbor2.dumps(serialize(template)))
+
+# deserialize from .pclc — reconstruct IR without re-parsing source
+with open("agent.pclc", "rb") as f:
+    template = deserialize(cbor2.loads(f.read()))
+prompt = render(template, variables={"date": "2026-02-28", "query": "..."})
+```
+
+---
+
+## Language Quick Reference
+
+```pcl
+---
+version: 1.0
+description: Optional YAML frontmatter — available as metadata, not in output
+---
+
+@import ./other.pcl
+@import ./lib.pcl as lib
+
+# This is a comment — stripped from output
+
+@block intro:
+    Defined here, emitted only when @include'd.
+
+@include intro          # emit a local block
+@include lib.greet      # emit a named block from an imported file
+@include other          # emit the entire body of other.pcl
+
+@if premium:
+    Shown only when premium is truthy.
+
+@if not premium:
+    Shown only when premium is falsy or absent.
+
+Hello ${name}!              # required variable — error if missing
+Hello ${name | world}!      # variable with default
+
+@raw
+${not_interpolated}  @not_a_directive  # this is not a comment
+@end
+
+\@block  →  literal @block in output
+\#       →  literal # in output
+\${      →  literal ${ in output
+```
+
+---
+
+## Examples
+
+The `examples/` directory contains a multi-file prompt:
+
+| File | Purpose |
+|------|---------|
+| `examples/agent.pcl` | Main agent prompt — imports persona and tools |
+| `examples/persona.pcl` | Persona blocks (`researcher`, `brief`) |
+| `examples/tools.pcl` | Tool description blocks (`search`, `browse`, `premium_index`) |
+
+```bash
+pcl render examples/agent.pcl \
+  --var date=2026-02-28 \
+  --var query="Explain quantum entanglement" \
+  --var premium=false
+```
+
+---
+
+## Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+With coverage:
+
+```bash
+uv run pytest tests/ --cov=pcl --cov-report=term-missing
+```
+
+---
+
+## VS Code Extension
+
+Syntax highlighting is in a separate repo: [`src/pcl-vscode`](https://github.com/cybergla/pcl-vscode).

pcl_lang-0.1.0/examples/agent.pcl

@@ -0,0 +1,32 @@
+---
+version: 1.0
+description: Research assistant system prompt
+---
+
+@import ./persona.pcl
+@import ./tools.pcl as tools
+
+# Compose the agent setup from reusable fragments
+@block agent_setup:
+    @include persona.researcher
+    @include tools.search
+    @include tools.browse
+
+# Main prompt body
+@include agent_setup
+
+Today's date is ${date}.
+
+@if premium:
+    @include tools.premium_index
+
+@if not premium:
+    Upgrade to unlock the premium document index.
+
+# Pass tool call format through literally
+@raw
+When calling a tool, respond with JSON only:
+{"tool": "${tool_name}", "input": {"query": "..."}}
+@end
+
+The user's query is: ${query | no query provided}

pcl_lang-0.1.0/examples/persona.pcl

@@ -0,0 +1,11 @@
+---
+description: Reusable persona fragment
+---
+
+@block researcher:
+    You are an expert research assistant with deep knowledge across science,
+    technology, and the humanities. You reason carefully, cite your uncertainty,
+    and never fabricate sources.
+
+@block brief:
+    You are a concise research assistant. Answer directly and cite sources.

pcl_lang-0.1.0/examples/test.pcl

@@ -0,0 +1,46 @@
+---
+version: 1.0
+description: Test prompt
+something: Other metadata
+---
+
+# This comment should disappear
+#
+# comment
+
+# another comment
+@include greeting
+@include say_hello
+
+Something else
+I want to say block
+block this 
+
+Something something this will be block: Not really a block but want to say block: here
+    indent doesn't mean anything
+
+@block greeting:
+    Hello, ${name}! 
+        this is more indent
+                    hjkfdj
+                    slkj            klds
+                                jkdshfkj 
+           sdfkl
+this is some ither text should come after
+sdfasdf
+
+
+@if premium:
+    You have premium access.
+
+@if not premium:
+    Upgrade for more features.
+
+@raw
+Example JSON: {"key": "${not_interpolated}"}
+@end
+
+Today is ${date|2021-04-05}.
+
+@block say_hello:
+    Hello manas!

pcl_lang-0.1.0/examples/tools.pcl

@@ -0,0 +1,15 @@
+---
+description: Tool description fragments
+---
+
+@block search:
+    You have access to a web search tool. Use it when the user asks about
+    current events or information you may not have.
+
+@block browse:
+    You have access to a browser tool. Use it to read specific URLs the
+    user provides.
+
+@block premium_index:
+    You have access to the premium document index, which contains
+    curated research papers and proprietary datasets.