ai-template-runner 1.5.0__tar.gz

ai_template_runner-1.5.0/LICENSE

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

ai_template_runner-1.5.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: ai-template-runner
+Version: 1.5.0
+Summary: Simple AI workflow based on Markdown templates
+Keywords: ai,llm,templates,llamacpp,local-models,prompt
+Author: brunodavi
+Author-email: brunodavi <48166556+brunodavi@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/brunodavi/ai-template-runner
+Project-URL: Issues, https://github.com/brunodavi/ai-template-runner/issues
+Project-URL: Changelog, https://github.com/brunodavi/ai-template-runner/blob/master/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# AI Template Runner
+
+Small local models are cheap and fast — they also lose structure the moment a prompt gets long. `ait` turns that weakness into a workflow: each template is a single Markdown file that gathers context, prompts the model, validates the answer and renders the result. Deterministic scaffolding around a dumb-but-fast model, even one running on your phone.
+
+```
+┌ template file ─────────────────────────────────┐
+│ ```toml  →  model, endpoint, sampling          │
+│ ```                                            │
+│ ---    →  system prompt                        │
+│ user prompt:  {cmd.version} output + question  │
+│ [test] / [out] →  validate + render output     │
+└────────────────────────────────────────────────┘
+```
+
+One file, one command, one predictable answer — no agent framework needed.
+
+**Why it matters:** a small model cannot keep a workflow in its head, but it can fill in a well-shaped slot. Templates put the workflow in the file so the model only has to do the part it is good at. Failures become visible and reproducible through `[test]`, instead of vague "the model is dumb" sessions.
+
+## Quick start
+
+Point `ait` at any OpenAI-compatible chat endpoint (llama.cpp server, Ollama, LM Studio, ...):
+
+1. Start a model server, e.g. llama.cpp:
+
+```bash
+llama-server -hf unsloth/Qwen3-0.6B-GGUF --port 8080
+```
+
+2. Run a ready template:
+
+```bash
+uvx ai-template-runner run TEMPLATE "What is Python?"
+```
+
+Or clone the repository and try it against a fixture without a model at
+all — the `examples/simulation/` templates run against fixed
+responses, so you can feel the `[test]`/`[out]` mechanics in seconds:
+
+```bash
+git clone https://github.com/brunodavi/ai-template-runner.git
+cd ai-template-runner
+uvx ai-template-runner run examples/simulation/conventional-commits/feat.md --test
+```
+
+Running on a phone? See [`docs/termux.md`](docs/termux.md).
+
+## Installation
+
+| Command | When to use |
+| --- | --- |
+| `uvx ai-template-runner --help` | zero-install trial from [PyPI](https://pypi.org/project/ai-template-runner/) |
+| `pipx install ai-template-runner` | persistent install, any platform (Termux ships pipx) |
+| `pip install ai-template-runner` | any pip environment |
+| `uv tool install ai-template-runner` | [uv](https://docs.astral.sh/uv/) managed installs |
+| `uv tool install git+https://github.com/brunodavi/ai-template-runner.git` | latest `master` |
+
+Requires Python 3.12+. The CLI is `ait` (or `ai-template-runner`); the package has **zero runtime dependencies**.
+
+## Usage
+
+```bash
+ait run examples/features/full.md "What is Python?"
+ait run examples/features/full.md "What is Python?" --quiet
+ait run examples/simulation/conventional-commits/feat.md --test
+ait --help
+ait run --help
+```
+
+- `-q` / `--quiet`: display only the AI response (stdout stays clean for pipes).
+- `-t` / `--test`: validate the response against the template's `[test]` table. PASS/FAIL lines go to stderr and the exit code is 1 when any check fails.
+
+## Templates
+
+Templates combine **TOML configuration** and Markdown prompts in a single file. The configuration is defined in a ` ```toml ` code block at the beginning of the file, and is parsed and removed from the prompt content. Two ` --- ` separators delimit an optional system prompt; everything after them becomes the user prompt. Templates can also execute terminal commands and inject their output directly into prompts.
+
+````markdown
+```toml
+[provider]
+base_url = 'http://localhost:8080/v1/chat/completions'
+model = 'lfm230m'
+temperature = 0.2
+top_p = 0.9
+top_k = 40
+min_p = 0.05
+max_tokens = 220
+seed = 42
+stop = []
+frequency_penalty = 0.0
+presence_penalty = 0.0
+repeat_penalty = 1.1
+
+[provider.extras]
+typical_p = 1.0
+repeat_last_n = 64
+
+[cmd]
+message = 'echo hello'
+```
+
+---
+You are a concise assistant. Use the command output as context.
+---
+
+Command output:
+{cmd.message}
+
+Answer the following question concisely: {question}
+````
+
+The TOML block is parsed and removed from the prompt content. The optional system prompt is delimited by two `---` separators; everything after the second separator is the user prompt. When the separators are omitted, the whole content after the configuration block is the user prompt.
+
+The `{question}` placeholder is replaced with the CLI input. The `{cmd.message}` placeholder executes the configured command and inserts its output into the prompt. Placeholders can be used in both the system and user prompts.
+
+The provider supports these generation parameters:
+
+- `temperature`, `top_p`, `top_k`, `min_p`: control sampling.
+- `max_tokens`: limits the generated response length.
+- `seed`: sets the random seed when supported.
+- `stop`: defines stop sequences.
+- `frequency_penalty`, `presence_penalty`, `repeat_penalty`: control repetition.
+- `extras`: passes additional parameters to the API, such as llama.cpp-specific options.
+
+`base_url` and `model` are required. Parameter support depends on the API and model server being used.
+
+A template can inherit configuration, commands, and prompts from another template with a top-level `extends` key placed before any TOML table:
+
+```toml
+extends = 'base.md'
+
+[provider]
+temperature = 0.2
+```
+
+The `extends` path is resolved relative to the template file itself, so [`examples/features/`](examples/features/) templates use `extends = '../base.md'`. Child values win per key; nested tables such as `[provider.extras]` and `[cmd]` are merged key by key. Empty child prompts fall back to the parent prompts, which lets a template reuse only the parent prompts and configuration.
+
+A template can validate its own output with a `[test]` table and the `--test` flag:
+
+```toml
+[test]
+type = 'feat'                              # JSON output field equality
+message = 'add health check endpoint'      # exact value comparison
+"user.name" = 'Alice'                      # nested JSON path (quoted dotted key)
+
+text = 'exact raw output'                  # exact raw text comparison
+text_contains = ['GET_health']             # every fragment present in the raw text
+text_regex = '^\{'                         # regex search on the raw text
+```
+
+Run with validation:
+
+```bash
+ait run examples/simulation/conventional-commits/feat.md --test
+```
+
+PASS/FAIL lines go to stderr (stdout stays clean for pipes) and the exit code is 1 when any check fails. Missing JSON fields and invalid JSON output fail instead of raising. The `[test]` table participates in `extends` inheritance like the other config tables.
+
+A template can also render its own display output with an `[out]` table. The `text` key is a render template formatted with the parsed JSON fields (`{out.type}`, `{out.message}`, ...); missing fields render as empty:
+
+```toml
+[out]
+text = '{out.type}: {out.message}'
+```
+
+Transforms run in two channels that never share the field namespace (`out.count` is always the JSON field, never `str.count`):
+
+```toml
+[out]
+text = '{out.message:strip} | {out.message:replace:GET:SET} | {out.message[:4]}'
+
+[[out.upper]]                               # one step: str.upper() with no args
+
+[[out.replace]]                             # named args match the real str signature
+old = 'GET_health'
+new = 'GET'
+
+[[out.slice]]                               # helper: builtin slice(start, end)
+start = 1
+end = 10
+```
+
+The `[[out.<method>]]` tables run in real document order (one table = one step, an empty table means no arguments) and apply to the rendered `text` — or to the raw response when there is no `text`. Steps are real `str` methods, with named arguments mapped positionally by the real signature. The inline spec is a single step from `method:arg1:arg2` (argument values may not contain ':'), and `{out.field[1:]}` follows pythonic slice syntax. Without `[out]` (or an empty table) the raw AI response is printed. The `[out]` config participates in `extends` inheritance per key: the child `text` and step lists replace the parent's.
+
+The same inline transforms work on every interpolated value in the prompts — `{question:strip}`, `{question[:80]:lower}` and `{cmd.message:upper}`, `{cmd.status[1:20]}` — since the value stays lazy for `{cmd.*}` (the command only runs when a field is actually used).
+
+## Examples and docs
+
+See [`examples/base.md`](examples/base.md) for the shared base used by the examples, [`examples/features/`](examples/features/) for one example per feature, [`examples/`](examples/) for ready-to-use task templates such as [`email-subject.md`](examples/email-subject.md) and [`conventional-commits.md`](examples/conventional-commits.md), and [`examples/simulation/`](examples/simulation/) for simulations that run task templates against fixed fixtures.
+
+For deeper material, read [`docs/architecture.md`](docs/architecture.md) (why the code is
+shaped the way it is), [`docs/termux.md`](docs/termux.md) (running local models on a phone)
+and [`docs/maintenance.md`](docs/maintenance.md) (release routine for maintainers).
+
+## Development
+
+```bash
+git clone https://github.com/brunodavi/ai-template-runner.git
+cd ai-template-runner
+uv sync
+uv pip install -e .
+```
+
+Editable installation (`-e .`) lets you run `ait` directly while developing, so source changes are available without reinstalling.
+
+Run a template to test your changes:
+
+```bash
+ait run examples/features/full.md "What is Python?"
+```
+
+Run the test suite (from the repository root):
+
+```bash
+uv run python -m unittest
+```
+
+Contributions are welcome — CI runs the suite on Python 3.12, 3.13 and 3.14, so that is the floor.
+
+## Status
+
+AIT is in active development for local AI experimentation and lightweight, template-driven workflows. Expect the template syntax to be stable and everything around it to keep evolving. See [`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+Licensed under the [MIT license](LICENSE).

ai_template_runner-1.5.0/README.md

@@ -0,0 +1,222 @@
+# AI Template Runner
+
+Small local models are cheap and fast — they also lose structure the moment a prompt gets long. `ait` turns that weakness into a workflow: each template is a single Markdown file that gathers context, prompts the model, validates the answer and renders the result. Deterministic scaffolding around a dumb-but-fast model, even one running on your phone.
+
+```
+┌ template file ─────────────────────────────────┐
+│ ```toml  →  model, endpoint, sampling          │
+│ ```                                            │
+│ ---    →  system prompt                        │
+│ user prompt:  {cmd.version} output + question  │
+│ [test] / [out] →  validate + render output     │
+└────────────────────────────────────────────────┘
+```
+
+One file, one command, one predictable answer — no agent framework needed.
+
+**Why it matters:** a small model cannot keep a workflow in its head, but it can fill in a well-shaped slot. Templates put the workflow in the file so the model only has to do the part it is good at. Failures become visible and reproducible through `[test]`, instead of vague "the model is dumb" sessions.
+
+## Quick start
+
+Point `ait` at any OpenAI-compatible chat endpoint (llama.cpp server, Ollama, LM Studio, ...):
+
+1. Start a model server, e.g. llama.cpp:
+
+```bash
+llama-server -hf unsloth/Qwen3-0.6B-GGUF --port 8080
+```
+
+2. Run a ready template:
+
+```bash
+uvx ai-template-runner run TEMPLATE "What is Python?"
+```
+
+Or clone the repository and try it against a fixture without a model at
+all — the `examples/simulation/` templates run against fixed
+responses, so you can feel the `[test]`/`[out]` mechanics in seconds:
+
+```bash
+git clone https://github.com/brunodavi/ai-template-runner.git
+cd ai-template-runner
+uvx ai-template-runner run examples/simulation/conventional-commits/feat.md --test
+```
+
+Running on a phone? See [`docs/termux.md`](docs/termux.md).
+
+## Installation
+
+| Command | When to use |
+| --- | --- |
+| `uvx ai-template-runner --help` | zero-install trial from [PyPI](https://pypi.org/project/ai-template-runner/) |
+| `pipx install ai-template-runner` | persistent install, any platform (Termux ships pipx) |
+| `pip install ai-template-runner` | any pip environment |
+| `uv tool install ai-template-runner` | [uv](https://docs.astral.sh/uv/) managed installs |
+| `uv tool install git+https://github.com/brunodavi/ai-template-runner.git` | latest `master` |
+
+Requires Python 3.12+. The CLI is `ait` (or `ai-template-runner`); the package has **zero runtime dependencies**.
+
+## Usage
+
+```bash
+ait run examples/features/full.md "What is Python?"
+ait run examples/features/full.md "What is Python?" --quiet
+ait run examples/simulation/conventional-commits/feat.md --test
+ait --help
+ait run --help
+```
+
+- `-q` / `--quiet`: display only the AI response (stdout stays clean for pipes).
+- `-t` / `--test`: validate the response against the template's `[test]` table. PASS/FAIL lines go to stderr and the exit code is 1 when any check fails.
+
+## Templates
+
+Templates combine **TOML configuration** and Markdown prompts in a single file. The configuration is defined in a ` ```toml ` code block at the beginning of the file, and is parsed and removed from the prompt content. Two ` --- ` separators delimit an optional system prompt; everything after them becomes the user prompt. Templates can also execute terminal commands and inject their output directly into prompts.
+
+````markdown
+```toml
+[provider]
+base_url = 'http://localhost:8080/v1/chat/completions'
+model = 'lfm230m'
+temperature = 0.2
+top_p = 0.9
+top_k = 40
+min_p = 0.05
+max_tokens = 220
+seed = 42
+stop = []
+frequency_penalty = 0.0
+presence_penalty = 0.0
+repeat_penalty = 1.1
+
+[provider.extras]
+typical_p = 1.0
+repeat_last_n = 64
+
+[cmd]
+message = 'echo hello'
+```
+
+---
+You are a concise assistant. Use the command output as context.
+---
+
+Command output:
+{cmd.message}
+
+Answer the following question concisely: {question}
+````
+
+The TOML block is parsed and removed from the prompt content. The optional system prompt is delimited by two `---` separators; everything after the second separator is the user prompt. When the separators are omitted, the whole content after the configuration block is the user prompt.
+
+The `{question}` placeholder is replaced with the CLI input. The `{cmd.message}` placeholder executes the configured command and inserts its output into the prompt. Placeholders can be used in both the system and user prompts.
+
+The provider supports these generation parameters:
+
+- `temperature`, `top_p`, `top_k`, `min_p`: control sampling.
+- `max_tokens`: limits the generated response length.
+- `seed`: sets the random seed when supported.
+- `stop`: defines stop sequences.
+- `frequency_penalty`, `presence_penalty`, `repeat_penalty`: control repetition.
+- `extras`: passes additional parameters to the API, such as llama.cpp-specific options.
+
+`base_url` and `model` are required. Parameter support depends on the API and model server being used.
+
+A template can inherit configuration, commands, and prompts from another template with a top-level `extends` key placed before any TOML table:
+
+```toml
+extends = 'base.md'
+
+[provider]
+temperature = 0.2
+```
+
+The `extends` path is resolved relative to the template file itself, so [`examples/features/`](examples/features/) templates use `extends = '../base.md'`. Child values win per key; nested tables such as `[provider.extras]` and `[cmd]` are merged key by key. Empty child prompts fall back to the parent prompts, which lets a template reuse only the parent prompts and configuration.
+
+A template can validate its own output with a `[test]` table and the `--test` flag:
+
+```toml
+[test]
+type = 'feat'                              # JSON output field equality
+message = 'add health check endpoint'      # exact value comparison
+"user.name" = 'Alice'                      # nested JSON path (quoted dotted key)
+
+text = 'exact raw output'                  # exact raw text comparison
+text_contains = ['GET_health']             # every fragment present in the raw text
+text_regex = '^\{'                         # regex search on the raw text
+```
+
+Run with validation:
+
+```bash
+ait run examples/simulation/conventional-commits/feat.md --test
+```
+
+PASS/FAIL lines go to stderr (stdout stays clean for pipes) and the exit code is 1 when any check fails. Missing JSON fields and invalid JSON output fail instead of raising. The `[test]` table participates in `extends` inheritance like the other config tables.
+
+A template can also render its own display output with an `[out]` table. The `text` key is a render template formatted with the parsed JSON fields (`{out.type}`, `{out.message}`, ...); missing fields render as empty:
+
+```toml
+[out]
+text = '{out.type}: {out.message}'
+```
+
+Transforms run in two channels that never share the field namespace (`out.count` is always the JSON field, never `str.count`):
+
+```toml
+[out]
+text = '{out.message:strip} | {out.message:replace:GET:SET} | {out.message[:4]}'
+
+[[out.upper]]                               # one step: str.upper() with no args
+
+[[out.replace]]                             # named args match the real str signature
+old = 'GET_health'
+new = 'GET'
+
+[[out.slice]]                               # helper: builtin slice(start, end)
+start = 1
+end = 10
+```
+
+The `[[out.<method>]]` tables run in real document order (one table = one step, an empty table means no arguments) and apply to the rendered `text` — or to the raw response when there is no `text`. Steps are real `str` methods, with named arguments mapped positionally by the real signature. The inline spec is a single step from `method:arg1:arg2` (argument values may not contain ':'), and `{out.field[1:]}` follows pythonic slice syntax. Without `[out]` (or an empty table) the raw AI response is printed. The `[out]` config participates in `extends` inheritance per key: the child `text` and step lists replace the parent's.
+
+The same inline transforms work on every interpolated value in the prompts — `{question:strip}`, `{question[:80]:lower}` and `{cmd.message:upper}`, `{cmd.status[1:20]}` — since the value stays lazy for `{cmd.*}` (the command only runs when a field is actually used).
+
+## Examples and docs
+
+See [`examples/base.md`](examples/base.md) for the shared base used by the examples, [`examples/features/`](examples/features/) for one example per feature, [`examples/`](examples/) for ready-to-use task templates such as [`email-subject.md`](examples/email-subject.md) and [`conventional-commits.md`](examples/conventional-commits.md), and [`examples/simulation/`](examples/simulation/) for simulations that run task templates against fixed fixtures.
+
+For deeper material, read [`docs/architecture.md`](docs/architecture.md) (why the code is
+shaped the way it is), [`docs/termux.md`](docs/termux.md) (running local models on a phone)
+and [`docs/maintenance.md`](docs/maintenance.md) (release routine for maintainers).
+
+## Development
+
+```bash
+git clone https://github.com/brunodavi/ai-template-runner.git
+cd ai-template-runner
+uv sync
+uv pip install -e .
+```
+
+Editable installation (`-e .`) lets you run `ait` directly while developing, so source changes are available without reinstalling.
+
+Run a template to test your changes:
+
+```bash
+ait run examples/features/full.md "What is Python?"
+```
+
+Run the test suite (from the repository root):
+
+```bash
+uv run python -m unittest
+```
+
+Contributions are welcome — CI runs the suite on Python 3.12, 3.13 and 3.14, so that is the floor.
+
+## Status
+
+AIT is in active development for local AI experimentation and lightweight, template-driven workflows. Expect the template syntax to be stable and everything around it to keep evolving. See [`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+Licensed under the [MIT license](LICENSE).

ai_template_runner-1.5.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "ai-template-runner"
+version = "1.5.0"
+description = "Simple AI workflow based on Markdown templates"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "ai",
+    "llm",
+    "templates",
+    "llamacpp",
+    "local-models",
+    "prompt",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development",
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[[project.authors]]
+name = "brunodavi"
+email = "48166556+brunodavi@users.noreply.github.com"
+
+[project.urls]
+Repository = "https://github.com/brunodavi/ai-template-runner"
+Issues = "https://github.com/brunodavi/ai-template-runner/issues"
+Changelog = "https://github.com/brunodavi/ai-template-runner/blob/master/CHANGELOG.md"
+
+[project.scripts]
+ai-template-runner = "ai_template_runner:main"
+ait = "ai_template_runner:main"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"

ai_template_runner-1.5.0/pyproject.toml.orig

@@ -0,0 +1,36 @@
+[project]
+name = "ai-template-runner"
+version = "1.5.0"
+description = "Simple AI workflow based on Markdown templates"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "brunodavi", email = "48166556+brunodavi@users.noreply.github.com" }
+]
+keywords = ["ai", "llm", "templates", "llamacpp", "local-models", "prompt"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development",
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/brunodavi/ai-template-runner"
+Issues = "https://github.com/brunodavi/ai-template-runner/issues"
+Changelog = "https://github.com/brunodavi/ai-template-runner/blob/master/CHANGELOG.md"
+
+[project.scripts]
+ai-template-runner = "ai_template_runner:main"
+ait = "ai_template_runner:main"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"

ai_template_runner-1.5.0/src/ai_template_runner/__init__.py

@@ -0,0 +1,4 @@
+from .cli import cli
+
+def main():
+    cli()

ai_template_runner-1.5.0/src/ai_template_runner/checks.py

@@ -0,0 +1,94 @@
+import json
+import re
+
+
+class CheckResult:
+    def __init__(self, name: str, passed: bool, detail: str = ''):
+        self.name = name
+        self.passed = passed
+        self.detail = detail
+
+
+TEXT_KEY = 'text'
+TEXT_CONTAINS_KEY = 'text_contains'
+TEXT_REGEX_KEY = 'text_regex'
+
+
+def _quoted(value) -> str:
+    return f'{value!r}'
+
+
+def _json_get(data: dict, dotted_path: str):
+    current = data
+    for part in dotted_path.split('.'):
+        if not isinstance(current, dict) or part not in current:
+            return None
+        current = current[part]
+    return current
+
+
+def run_checks(test_config: dict, text: str) -> list[CheckResult]:
+    """Validate the AI response against the template [test] table.
+
+    Reserved keys (text, text_contains, text_regex) check the raw
+    text; any other key is a dotted path into the parsed JSON output.
+    Missing JSON fields and invalid JSON fail without raising.
+    """
+    results: list[CheckResult] = []
+
+    expected_json = {
+        key: value
+        for key, value in test_config.items()
+        if key not in (TEXT_KEY, TEXT_CONTAINS_KEY, TEXT_REGEX_KEY)
+    }
+
+    try:
+        parsed = json.loads(text)
+        parse_error = None
+    except (json.JSONDecodeError, TypeError) as err:
+        parsed = None
+        parse_error = err
+
+    for key, expected in expected_json.items():
+        if parse_error is not None:
+            results.append(CheckResult(
+                key,
+                passed=False,
+                detail=f'invalid json output: {text[:100]!r}',
+            ))
+            continue
+
+        got = _json_get(parsed, key)
+        passed = got == expected
+        detail = '' if passed else (
+            f'expected {_quoted(expected)}, got {_quoted(got)}'
+        )
+        results.append(CheckResult(key, passed, detail))
+
+    if TEXT_KEY in test_config:
+        expected = test_config[TEXT_KEY]
+        passed = text == expected
+        detail = '' if passed else f'expected {_quoted(expected)}, got {_quoted(text)}'
+        results.append(CheckResult(TEXT_KEY, passed, detail))
+
+    if TEXT_CONTAINS_KEY in test_config:
+        fragments = test_config[TEXT_CONTAINS_KEY]
+        missing = [
+            fragment for fragment in fragments
+            if fragment not in text
+        ]
+        passed = not missing
+        detail = '' if passed else f'missing fragments: {_quoted(missing)}'
+        results.append(CheckResult(TEXT_CONTAINS_KEY, passed, detail))
+
+    if TEXT_REGEX_KEY in test_config:
+        pattern = test_config[TEXT_REGEX_KEY]
+        try:
+            passed = re.search(pattern, text) is not None
+            detail = '' if passed else f'pattern {_quoted(pattern)} not found'
+        except re.error as err:
+            passed = False
+            detail = f'invalid regex {_quoted(pattern)}: {err}'
+        results.append(CheckResult(TEXT_REGEX_KEY, passed, detail))
+
+    return results

ai_template_runner-1.5.0/src/ai_template_runner/cli.py

@@ -0,0 +1,104 @@
+from argparse import ArgumentParser
+from pathlib import Path
+import sys
+
+from .processor import (
+    process_template,
+    process_prompt,
+    process_system_prompt,
+)
+from .providers import llamacpp
+from .checks import run_checks
+from .output import render_out
+
+
+def cli(argv: list[str] = None):
+    parser = ArgumentParser(
+        prog="ait",
+        description="Simple AI workflow based on Markdown templates",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        required=True,
+    )
+
+    run = subparsers.add_parser(
+        "run",
+        help="Run a template",
+        description="Run a template",
+    )
+
+    run.add_argument(
+        "template_path",
+        help="Path template markdown to run",
+        type=Path,
+    )
+
+    run.add_argument(
+        "question",
+        help="Question to answer",
+        nargs="?",
+        default="",
+    )
+
+    run.add_argument(
+        "-q", "--quiet",
+        action="store_true",
+        help="Show only the AI response",
+    )
+
+    run.add_argument(
+        "-t", "--test",
+        action="store_true",
+        help="Validate the AI response against the [test] table",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "run":
+        template_path: Path = args.template_path
+
+        if not args.quiet:
+            print(f"Running template: {template_path.name}\n")
+
+        template = process_template(template_path)
+        prompt = process_prompt(template, args.question)
+        system_prompt = process_system_prompt(template, args.question)
+
+        if not args.quiet and system_prompt:
+            print("System:", system_prompt)
+            print()
+
+        if not args.quiet:
+            print("User:", prompt)
+            print()
+
+        response_json = llamacpp(
+            template.provider,
+            prompt,
+            system_prompt,
+        )
+
+        ai_response = (
+            response_json["choices"][0]["message"]["content"]
+        )
+
+        rendered = render_out(template.out, ai_response)
+
+        if args.quiet:
+            print(rendered)
+        else:
+            print("AI:", rendered)
+
+        if args.test:
+            failed = False
+
+            for result in run_checks(template.test, ai_response):
+                status = 'PASS' if result.passed else 'FAIL'
+                line = f'{status} {result.name}' + (f': {result.detail}' if result.detail else '')
+                print(line, file=sys.stderr)
+                failed = failed or not result.passed
+
+            if failed:
+                raise SystemExit(1)

ai_template_runner-1.5.0/src/ai_template_runner/command.py

@@ -0,0 +1,16 @@
+import subprocess
+
+from .output import Smart
+
+class Command:
+    def __init__(self, **kwargs):
+        self.commands = kwargs
+
+    def __getattr__(self, name):
+        command = self.commands[name]
+        return Smart(subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True
+        ).stdout.strip())

ai_template_runner-1.5.0/src/ai_template_runner/models/provider.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Provider:
+    base_url: str
+    model: str
+
+    # Sampling
+    temperature: float | None = None
+    top_p: float | None = None
+    top_k: int | None = None
+    min_p: float | None = None
+
+    # Output
+    max_tokens: int | None = None
+    stop: list[str] = field(default_factory=list)
+
+    # Reproducibility
+    seed: int | None = None
+
+    # Repetition control
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    repeat_penalty: float | None = None
+
+    # Less common or provider-specific options
+    extras: dict[str, Any] = field(default_factory=dict)

ai_template_runner-1.5.0/src/ai_template_runner/models/template.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass, field
+from ..command import Command
+from .provider import Provider
+
+@dataclass
+class Template:
+    user_prompt: str 
+    system_prompt: str = ''
+
+    provider: Provider = None
+    cmd: Command = None
+    test: dict = field(default_factory=dict)
+    out: dict = field(default_factory=dict)

ai_template_runner-1.5.0/src/ai_template_runner/output.py

@@ -0,0 +1,221 @@
+"""The [out] table: render of the AI response with transforms.
+
+Two mechanisms share one transform executor:
+
+- [[out.<method>]] tables build a pipeline applied in real document
+  order (array-of-tables group by key in tomllib, so the raw headers
+  are numbered with a suffix before parsing and un-numbered after);
+- inline spec inside the render text: `{out.field:method:arg1:arg2}`
+  and the pythonic slice `{out.field[1:]}` through a Smart wrapper.
+"""
+
+import inspect
+import json
+import re
+from tomllib import loads as toml_loads
+
+
+OUT_HEADER = re.compile(r'\[\[out\.(\w+)\]\]')
+
+SLICE_METHOD = 'slice'
+TEXT_KEY = 'text'
+STEPS_KEY = 'steps'
+
+
+def number_out_headers(toml_str: str) -> str:
+    """Number [[out.<name>]] headers so document order survives tomllib.
+
+    tomllib groups array-of-tables by key, losing the order between
+    different method names. Adding a per-name occurrence suffix gives
+    every header a unique key; build_out() removes the suffix again.
+    The suffix is not matched by the pattern itself (\w stops at '-'),
+    so numbering stays idempotent.
+    """
+    counters: dict[str, int] = {}
+
+    def rename(match: re.Match) -> str:
+        name = match.group(1)
+        counters[name] = counters.get(name, 0) + 1
+        return f'[[out.{name}-{counters[name]}]]'
+
+    return OUT_HEADER.sub(rename, toml_str)
+
+
+def build_out(raw_out: dict | None) -> dict:
+    """Canonicalize the parsed [out] table into {text, steps}.
+
+    Numbered keys (built with number_out_headers) are un-suffixed and
+    flattened into an ordered steps list of (method, args) tuples,
+    where args is the step table (empty table = no arguments).
+    """
+    if not raw_out:
+        return {}
+
+    built = {}
+
+    if raw_out.get(TEXT_KEY):
+        built[TEXT_KEY] = raw_out[TEXT_KEY]
+
+    steps = []
+    for key, entries in raw_out.items():
+        if key == TEXT_KEY:
+            continue
+        method = key.rsplit('-', 1)[0]
+        for entry in entries:
+            steps.append((method, dict(entry)))
+
+    if steps:
+        built[STEPS_KEY] = steps
+
+    return built
+
+
+def _positional_by_signature(method, args: dict, name: str) -> list:
+    """Map named args to positional order using the method's real signature."""
+    try:
+        params = [
+            param
+            for param in inspect.signature(method).parameters
+            if param != 'self'
+        ]
+    except (ValueError, TypeError):
+        raise ValueError(
+            f'[out] cannot map named arguments for transform {name!r}'
+        ) from None
+
+    unknown = set(args) - set(params)
+    if unknown:
+        raise ValueError(
+            f'[out] unknown arguments for {name}: {sorted(unknown)}'
+        )
+
+    return [args[param] for param in params if param in args]
+
+
+def _slice_key(args) -> slice:
+    if isinstance(args, dict):
+        return slice(args.get('start'), args.get('end'))
+
+    start = args[0] if len(args) > 0 else None
+    end = args[1] if len(args) > 1 else None
+    return slice(
+        int(start) if start not in (None, '') else None,
+        int(end) if end not in (None, '') else None,
+    )
+
+
+def apply_op(text: str, name: str, args) -> str:
+    """Run one transform: a real str method, or the 'slice' helper.
+
+    args is a named dict (from [[out.<method>]] tables, mapped to
+    positional by the method signature) or a positional list (from an
+    inline spec). An empty args table calls the method without args.
+    """
+    if name == SLICE_METHOD:
+        return text[_slice_key(args)]
+
+    if not hasattr(str, name) or name.startswith('_'):
+        raise ValueError(f'[out] unknown transform: {name!r}')
+
+    method = getattr(str, name)
+
+    if not args:
+        return method(text)
+
+    if isinstance(args, dict):
+        args = _positional_by_signature(method, args, name)
+
+    return method(text, *args)
+
+
+def run_spec(text: str, spec: str) -> str:
+    """Run the inline spec: 'method' | 'method:arg1:arg2' | 'slice:1:10'.
+
+    One step only, positional args separated by ':' (values may not
+    contain ':'). An empty spec is a pass-through.
+    """
+    if not spec:
+        return text
+
+    name, *args = spec.split(':')
+    return apply_op(text, name, args)
+
+
+def parse_slice_key(key: str) -> slice:
+    """Parse a format subscript key like '1:', ':4' or '1:10' into a slice."""
+    start, _, end = key.partition(':')
+    return slice(
+        int(start) if start else None,
+        int(end) if end else None,
+    )
+
+
+class Smart(str):
+    """Interpolable value: transforms only via :spec and [slice].
+
+    The format machinery passes subscript keys as strings to
+    __getitem__ ('1:' -> slice) and the format spec to __format__
+    ('replace:GET:SET'), where we run them through apply_op. Because
+    transforms never use attribute names, JSON fields keep their own
+    namespace (a field called 'count' is data, never str.count).
+    """
+
+    def __getitem__(self, key):
+        if isinstance(key, str):
+            key = parse_slice_key(key)
+        return Smart(super().__getitem__(key))
+
+    def __format__(self, spec: str) -> str:
+        return run_spec(str(self), spec)
+
+
+class Rec:
+    """Wraps the parsed JSON response so {out.*} resolves to fields.
+
+    Missing fields render as ''; nested dicts may be addressed with
+    dotted attribute access. Values are Smart, so :spec and [slice]
+    work on any field.
+    """
+
+    def __init__(self, fields: dict):
+        object.__setattr__(self, '_fields', fields or {})
+
+    def __getattr__(self, field: str):
+        if field.startswith('_'):
+            raise AttributeError(field)
+
+        if field not in self._fields:
+            return Smart('')
+
+        value = self._fields[field]
+        return Rec(value) if isinstance(value, dict) else Smart(value)
+
+
+def _response_fields(ai_response: str) -> dict:
+    try:
+        parsed = json.loads(ai_response)
+    except (json.JSONDecodeError, TypeError):
+        return {}
+
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def render_out(out: dict | None, ai_response: str) -> str:
+    """Render the AI response through the [out] config.
+
+    Without [out] (or an empty table) the raw response passes through.
+    With 'text', the parsed JSON fields are formatted through Rec and
+    Smart; without 'text' the raw response is the starting value. The
+    steps from [[out.<method>]] tables are applied in document order.
+    """
+    if not out:
+        return ai_response
+
+    base = out.get(TEXT_KEY) or ai_response
+    if base is not ai_response:
+        base = base.format(out=Rec(_response_fields(ai_response)))
+
+    for name, args in out.get(STEPS_KEY, []):
+        base = apply_op(base, name, args)
+
+    return base

ai_template_runner-1.5.0/src/ai_template_runner/processor.py

@@ -0,0 +1,191 @@
+from pathlib import Path
+from tomllib import loads
+
+from .models.template import Template
+from .models.provider import Provider
+from .command import Command
+from .output import build_out, number_out_headers, Smart
+
+TOML_FENCE = '```toml'
+FENCE_END = '```'
+SYSTEM_SEPARATOR = '---'
+
+EXTENDS_KEY = 'extends'
+
+
+def extract_toml_block(template_str: str) -> tuple[str, str]:
+    """Extract the TOML configuration block from the template.
+
+    The block must be the first content of the Markdown file and is
+    delimited by a ```toml fenced code block. Returns the TOML source
+    and the template content without the block.
+    """
+    lines = template_str.splitlines()
+
+    start = 0
+    while start < len(lines) and not lines[start].strip():
+        start += 1
+
+    if start == len(lines) or lines[start].strip() != TOML_FENCE:
+        raise ValueError(
+            "Template must begin with a '```toml' configuration block"
+        )
+
+    end = next(
+        (
+            i
+            for i in range(start + 1, len(lines))
+            if lines[i].strip() == FENCE_END
+        ),
+        None,
+    )
+
+    if end is None:
+        raise ValueError(
+            "The '```toml' configuration block is not closed"
+        )
+
+    toml_str = '\n'.join(lines[start + 1:end])
+    content = '\n'.join(lines[end + 1:])
+
+    return toml_str, content
+
+
+def split_prompts(content: str) -> tuple[str, str]:
+    """Split the template content into a system prompt and a user prompt.
+
+    The system prompt is optional and delimited by two '---' separators.
+    Everything after the second separator is the user prompt.
+    """
+    lines = content.splitlines()
+    separators = [
+        i for i, line in enumerate(lines) if line.strip() == SYSTEM_SEPARATOR
+    ]
+
+    if len(separators) < 2:
+        return '', content.strip()
+
+    [first, second] = separators[:2]
+    system_prompt = '\n'.join(lines[first + 1:second])
+    user_prompt = '\n'.join(lines[second + 1:])
+
+    return system_prompt.strip(), user_prompt.strip()
+
+
+def merge_configs(parent: dict, child: dict) -> dict:
+    """Merge two TOML config dicts, child values win.
+
+    Nested tables (e.g. [provider.extras] or [cmd]) are merged
+    per additional table level, so child tables inherit parent keys.
+    """
+    merged = dict(parent)
+    for key, value in child.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = merge_configs(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def load_template(
+    template_path: Path,
+    _extends_stack: frozenset[Path] = frozenset(),
+) -> tuple[dict, dict, dict, dict, str, str]:
+    """Load a template file and resolve its `extends` chain.
+
+    Returns (provider config, cmd config, test config, out config,
+    system prompt, user prompt). The `extends` path is resolved relative
+    to the template file itself; parent provider/cmd/test/out configs
+    are merged per key and parent prompts are used wherever the child
+    prompts are empty.
+    """
+    template_str = template_path.read_text()
+
+    toml_str, content = extract_toml_block(template_str)
+
+    config = loads(number_out_headers(toml_str))
+    extends = config.pop(EXTENDS_KEY, None)
+
+    provider = dict(config.get('provider', {}))
+    cmd = dict(config.get('cmd', {}))
+    test = dict(config.get('test', {}))
+    out = build_out(config.get('out'))
+
+    system_prompt, user_prompt = split_prompts(content)
+
+    if extends:
+        parent_path = template_path.parent / extends
+
+        if not parent_path.is_file():
+            raise ValueError(
+                f"Template 'extends' file not found: {extends}"
+            )
+
+        parent_resolved = parent_path.resolve()
+
+        if parent_resolved in _extends_stack:
+            raise ValueError(
+                f"circular 'extends' in template chain: {extends}"
+            )
+
+        parent = load_template(
+            parent_path,
+            _extends_stack | {parent_resolved},
+        )
+
+        parent_provider, parent_cmd, parent_test, parent_out, parent_system, parent_user = (
+            parent
+        )
+
+        provider = merge_configs(parent_provider, provider)
+        cmd = merge_configs(parent_cmd, cmd)
+        test = merge_configs(parent_test, test)
+        out = merge_configs(parent_out, out)
+
+        system_prompt = system_prompt or parent_system
+        user_prompt = user_prompt or parent_user
+
+    return provider, cmd, test, out, system_prompt, user_prompt
+
+
+def process_template(template_path: Path) -> Template:
+    provider_config, cmd_config, test_config, out_config, system_prompt, user_prompt = (
+        load_template(template_path)
+    )
+
+    if not provider_config.get('base_url') or not provider_config.get('model'):
+        raise ValueError(
+             "Provider 'base_url' and 'model' are required"
+        )
+
+    return Template(
+        user_prompt,
+        system_prompt=system_prompt,
+        provider=Provider(**provider_config),
+        cmd=Command(**cmd_config),
+        test=test_config,
+        out=out_config,
+    )
+
+
+def interpolate(text: str, template: Template, question: str | None) -> str:
+    return text.format(
+        question=Smart(question) if isinstance(question, str) else question,
+        cmd=template.cmd,
+    ).strip()
+
+
+def process_prompt(
+        template: Template,
+        question: str | None = None
+    ) -> str:
+
+    return interpolate(template.user_prompt, template, question)
+
+
+def process_system_prompt(
+        template: Template,
+        question: str | None = None
+    ) -> str:
+
+    return interpolate(template.system_prompt, template, question)

ai_template_runner-1.5.0/src/ai_template_runner/providers.py

@@ -0,0 +1,50 @@
+import json
+import urllib.request
+
+from .models.provider import Provider
+
+
+def post_json(url, payload):
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={"Content-Type": "application/json"}
+    )
+    with urllib.request.urlopen(req, timeout=180) as response:
+        return json.loads(response.read())
+
+
+def llamacpp(
+        provider: Provider,
+        user_prompt: str,
+        system_prompt: str = '',
+    ):
+
+    url = provider.base_url
+
+    payload = {
+        "model": provider.model,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+        "temperature": provider.temperature,
+        "top_p": provider.top_p,
+        "top_k": provider.top_k,
+        "min_p": provider.min_p,
+
+        "max_tokens": provider.max_tokens,
+        "seed": provider.seed,
+        "stop": provider.stop,
+
+        "frequency_penalty": provider.frequency_penalty,
+        "presence_penalty": provider.presence_penalty,
+        "repeat_penalty": provider.repeat_penalty,
+
+        "stream": False,
+
+        **provider.extras,
+    }
+
+    return post_json(url, payload)