instructvault 0.2.8__tar.gz → 0.3.0__tar.gz

instructvault-0.3.0/.gitignore

@@ -0,0 +1,17 @@
+.DS_Store
+*.log
+*.swp
+.env
+
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+.venv/
+venv/
+
+build/
+dist/
+*.egg-info/

{instructvault-0.2.8 → instructvault-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instructvault
-Version: 0.2.8
+Version: 0.3.0
 Summary: Git-first prompt registry + CI evals + lightweight runtime SDK (ivault).
 Project-URL: Homepage, https://github.com/05satyam/instruct_vault
 Project-URL: Repository, https://github.com/05satyam/instruct_vault
@@ -9,6 +9,7 @@ License: Apache-2.0
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonschema>=4.21
 Requires-Dist: pydantic>=2.7
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.7
@@ -127,6 +128,10 @@ ivault validate prompts
 ivault render prompts/support_reply.prompt.yml --vars '{"ticket_text":"My app crashed.","customer_name":"Sam"}'
 ```
 
+Safety tip: add `--safe` to scan rendered output for common secret patterns.
+Use `--strict-vars` to forbid unknown vars and `--redact` to mask detected secrets.
+Use `--policy /path/to/policy.py` to enforce custom compliance rules.
+
 ### 4) Add dataset‑driven eval
 `datasets/support_cases.jsonl`
 ```jsonl
@@ -142,6 +147,11 @@ Note: Prompts must include at least one inline test. Datasets are optional.
 Migration tip: if you need to render a prompt that doesn’t yet include tests, use
 `ivault render --allow-no-tests` or add a minimal test first.
 
+Spec migration check:
+```bash
+ivault migrate prompts
+```
+
 ### 5) Version prompts with tags
 ```bash
 git add prompts datasets
@@ -179,6 +189,10 @@ vault = InstructVault(bundle_path="out/ivault.bundle.json")
 - `examples/notebooks/instructvault_openai_colab.ipynb`
   [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/05satyam/instruct_vault/blob/main/examples/notebooks/instructvault_openai_colab.ipynb)
 
+## Example Policies
+- `examples/policies/policy_example.py`
+- `examples/policies/policy_pack.py`
+
 ## How teams use this in production
 1) Prompt changes go through PRs
 2) CI runs `validate` + `eval`
@@ -208,11 +222,13 @@ Then send `x-ivault-api-key` in requests (or keep it behind your org gateway).
 If you don’t set the env var, no auth is required.
 
 ## Docs
+- `docs/spec.md`
 - `docs/vision.md`
 - `docs/governance.md`
 - `docs/ci.md`
 - `docs/playground.md`
 - `docs/cookbooks.md`
+- `docs/audit_logging.md`
 - `docs/dropin_guide.md`
 - `docs/release_checklist.md`
 - `docs/ci_templates/gitlab-ci.yml`

{instructvault-0.2.8 → instructvault-0.3.0}/README.md

@@ -102,6 +102,10 @@ ivault validate prompts
 ivault render prompts/support_reply.prompt.yml --vars '{"ticket_text":"My app crashed.","customer_name":"Sam"}'
 ```
 
+Safety tip: add `--safe` to scan rendered output for common secret patterns.
+Use `--strict-vars` to forbid unknown vars and `--redact` to mask detected secrets.
+Use `--policy /path/to/policy.py` to enforce custom compliance rules.
+
 ### 4) Add dataset‑driven eval
 `datasets/support_cases.jsonl`
 ```jsonl
@@ -117,6 +121,11 @@ Note: Prompts must include at least one inline test. Datasets are optional.
 Migration tip: if you need to render a prompt that doesn’t yet include tests, use
 `ivault render --allow-no-tests` or add a minimal test first.
 
+Spec migration check:
+```bash
+ivault migrate prompts
+```
+
 ### 5) Version prompts with tags
 ```bash
 git add prompts datasets
@@ -154,6 +163,10 @@ vault = InstructVault(bundle_path="out/ivault.bundle.json")
 - `examples/notebooks/instructvault_openai_colab.ipynb`
   [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/05satyam/instruct_vault/blob/main/examples/notebooks/instructvault_openai_colab.ipynb)
 
+## Example Policies
+- `examples/policies/policy_example.py`
+- `examples/policies/policy_pack.py`
+
 ## How teams use this in production
 1) Prompt changes go through PRs
 2) CI runs `validate` + `eval`
@@ -183,11 +196,13 @@ Then send `x-ivault-api-key` in requests (or keep it behind your org gateway).
 If you don’t set the env var, no auth is required.
 
 ## Docs
+- `docs/spec.md`
 - `docs/vision.md`
 - `docs/governance.md`
 - `docs/ci.md`
 - `docs/playground.md`
 - `docs/cookbooks.md`
+- `docs/audit_logging.md`
 - `docs/dropin_guide.md`
 - `docs/release_checklist.md`
 - `docs/ci_templates/gitlab-ci.yml`

instructvault-0.3.0/docs/audit_logging.md

@@ -0,0 +1,25 @@
+# Audit Logging (recommended)
+
+Log these fields for every render/eval execution:
+- prompt path
+- git ref or SHA
+- spec_version
+- dataset path (if any)
+- policy module (if any)
+- safe / strict-vars / redact flags
+- timestamp
+
+Example payload:
+```
+{
+  "prompt": "prompts/support_reply.prompt.yml",
+  "ref": "prompts/v1.2.0",
+  "spec_version": "1.0",
+  "dataset": "datasets/support_cases.jsonl",
+  "policy": "docs/policy_pack.py",
+  "safe": true,
+  "strict_vars": true,
+  "redact": true,
+  "timestamp": "2026-02-02T12:00:00Z"
+}
+```

{instructvault-0.2.8 → instructvault-0.3.0}/docs/cookbooks.md

@@ -133,3 +133,42 @@ GitHub Actions snippet:
 Notes:
 - The dataset is still local when `ivault` runs.
 - Keep dataset files versioned or checksum-locked for reproducibility.
+
+## 12) Policy hooks (compliance / PII)
+Create a policy module and pass it to `ivault`:
+```bash
+ivault validate prompts --policy examples/policies/policy_example.py
+ivault eval prompts/support_reply.prompt.yml --policy examples/policies/policy_example.py
+```
+
+Default policy pack (simple PII + forbidden phrases):
+```bash
+ivault validate prompts --policy examples/policies/policy_pack.py
+ivault eval prompts/support_reply.prompt.yml --policy examples/policies/policy_pack.py
+```
+
+## 13) Custom evals (your own rules)
+You can run your own checks using the SDK:
+```python
+from instructvault import InstructVault
+
+vault = InstructVault(repo_root=".")
+msgs = vault.render("prompts/support_reply.prompt.yml", vars={"ticket_text":"Order delayed"})
+
+# Custom checks here
+assert any("Ticket:" in m.content for m in msgs)
+```
+
+Or plug in a policy module:
+```bash
+ivault eval prompts/support_reply.prompt.yml --policy my_policy.py
+```
+
+Policy module signature:
+```python
+def check_spec(spec: dict) -> list[str]:
+    return []
+
+def check_render(text: str, context: dict) -> list[str]:
+    return []
+```

instructvault-0.3.0/docs/spec.md

@@ -0,0 +1,40 @@
+# Spec Contract
+
+## Versioning
+- `spec_version` is required for prompts.
+- Current stable series: **1.x**
+- Minor versions (1.1, 1.2, …) must remain backward compatible with 1.0.
+- Breaking changes require a major version (2.0).
+
+## Deprecation
+- Deprecated fields must continue to parse for at least one minor release.
+- Deprecations are documented in `CHANGELOG.md`.
+
+## Migration
+Use:
+```
+ivault migrate prompts
+```
+This checks for missing `spec_version` and reports any files that need updates.
+Use `--apply` to write `spec_version: 1.0` into YAML prompts.
+
+## Data Model (1.0)
+Required:
+- `spec_version`
+- `name`
+- `messages`
+- `tests` (at least one inline test)
+
+Optional:
+- `description`
+- `modelParameters` (alias: `model_defaults`)
+- `variables`
+
+## Tests
+Each test must include at least one assertion:
+- `contains_any`
+- `contains_all`
+- `not_contains`
+ - `matches` (regex)
+ - `not_matches` (regex)
+ - `json_schema` (JSON Schema validation)

instructvault-0.3.0/examples/notebooks/instructvault_colab.ipynb

@@ -0,0 +1,128 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "e4b28969",
+      "metadata": {},
+      "source": [
+        "# InstructVault Quickstart (Google Colab)\n",
+        "\n",
+        "This notebook is designed for Colab. It uses `/content/ivault_demo` and repo-relative prompt paths."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "79ef050d",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!pip -q install instructvault\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "d416a2e3",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# If you're not on Colab, change this path to your local repo folder.\n",
+        "repo_path = \"/content/ivault_demo\"\n",
+        "print(\"Using repo_path:\", repo_path)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "5c257338",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from pathlib import Path\n",
+        "\n",
+        "repo = Path(\"/content/content/ivault_demo\")\n",
+        "(repo / \"prompts\").mkdir(parents=True, exist_ok=True)\n",
+        "\n",
+        "prompt_text = '''spec_version: \"1.0\"\n",
+        "name: hello_world\n",
+        "variables:\n",
+        "  required: [name]\n",
+        "messages:\n",
+        "  - role: system\n",
+        "    content: \"You are a helpful assistant.\"\n",
+        "  - role: user\n",
+        "    content: \"Say hello to {{ name }}.\"\n",
+        "tests:\n",
+        "  - name: includes_name\n",
+        "    vars: { name: \"Ava\" }\n",
+        "    assert: { contains_any: [\"Ava\"] }\n",
+        "'''\n",
+        "\n",
+        "(repo / \"prompts\" / \"hello_world.prompt.yml\").write_text(prompt_text, encoding=\"utf-8\")\n",
+        "print(\"Prompt written:\", repo / \"prompts\" / \"hello_world.prompt.yml\")\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "33a7f7bd",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!ivault validate /content/content/ivault_demo/prompts\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "040f198b",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from instructvault import InstructVault\n",
+        "\n",
+        "vault = InstructVault(repo_root=\"/content/ivault_demo\")\n",
+        "msgs = vault.render(\"prompts/hello_world.prompt.yml\", vars={\"name\":\"Colab\"})\n",
+        "print(msgs)\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "1d6f8472",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!ivault eval /ivault_demo/prompts/hello_world.prompt.yml --report /ivault_demo/out/report.json\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "a5ba9974",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!ivault bundle --repo /content/ivault_demo --prompts prompts --out /content/ivault_demo/out/ivault.bundle.json"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "name": "instructvault_colab.ipynb",
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.x"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

instructvault-0.3.0/examples/notebooks/instructvault_openai_colab.ipynb

@@ -0,0 +1,112 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# InstructVault + OpenAI (Google Colab)\n\n",
+        "This notebook renders a prompt with InstructVault and sends it to the OpenAI API.\n\n",
+        "**Note:** Keep your API key private. Do not commit it to source control."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!pip -q install instructvault openai"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import os, getpass\n",
+        "\n",
+        "if 'OPENAI_API_KEY' not in os.environ:\n",
+        "    os.environ['OPENAI_API_KEY'] = getpass.getpass('Enter OpenAI API key: ')\n",
+        "print('API key set:', 'OPENAI_API_KEY' in os.environ)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from pathlib import Path\n",
+        "\n",
+        "repo_path = '/content/ivault_demo'\n",
+        "repo = Path(repo_path)\n",
+        "(repo / 'prompts').mkdir(parents=True, exist_ok=True)\n",
+        "\n",
+        "prompt_text = '''spec_version: \"1.0\"\n",
+        "name: hello_world\n",
+        "variables:\n",
+        "  required: [name]\n",
+        "messages:\n",
+        "  - role: system\n",
+        "    content: \"You are a helpful assistant.\"\n",
+        "  - role: user\n",
+        "    content: \"Say hello to {{ name }}.\"\n",
+        "tests:\n",
+        "  - name: includes_name\n",
+        "    vars: { name: \"Ava\" }\n",
+        "    assert: { contains_any: [\"Ava\"] }\n",
+        "'''\n",
+        "\n",
+        "(repo / 'prompts' / 'hello_world.prompt.yml').write_text(prompt_text, encoding='utf-8')\n",
+        "print('Prompt written:', repo / 'prompts' / 'hello_world.prompt.yml')"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from instructvault import InstructVault\n",
+        "\n",
+        "vault = InstructVault(repo_root=repo_path)\n",
+        "messages = vault.render('prompts/hello_world.prompt.yml', vars={'name':'Colab'})\n",
+        "messages"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from openai import OpenAI\n",
+        "\n",
+        "client = OpenAI()\n",
+        "response = client.chat.completions.create(\n",
+        "    model='gpt-4.1',\n",
+        "    messages=messages,\n",
+        ")\n",
+        "print(response.choices[0].message.content)"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "name": "instructvault_openai_colab.ipynb",
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.x"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

instructvault-0.3.0/examples/notebooks/instructvault_rag_colab.ipynb

@@ -0,0 +1,127 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# InstructVault RAG Cookbook (Google Colab)\n\n",
+        "This notebook shows a simple RAG prompt and an agentic RAG prompt using InstructVault."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!pip -q install instructvault"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# If you're not on Colab, change this path to your local repo folder.\n",
+        "repo_path = \"/content/ivault_demo\"\n",
+        "print(\"Using repo_path:\", repo_path)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from pathlib import Path\n",
+        "\n",
+        "repo = Path(repo_path)\n",
+        "(repo / \"prompts\").mkdir(parents=True, exist_ok=True)\n",
+        "\n",
+        "rag_prompt = '''spec_version: \"1.0\"\n",
+        "name: rag_answer\n",
+        "variables:\n",
+        "  required: [question, context]\n",
+        "messages:\n",
+        "  - role: system\n",
+        "    content: \"Answer using only the provided context. If missing, say you don't know.\"\n",
+        "  - role: user\n",
+        "    content: \"Question: {{ question }}\\n\\nContext:\\n{{ context }}\"\n",
+        "tests:\n",
+        "  - name: includes_context\n",
+        "    vars: { question: \"What is InstructVault?\", context: \"InstructVault is a Git-first prompt registry.\" }\n",
+        "    assert: { contains_any: [\"Context:\"] }\n",
+        "'''\n",
+        "\n",
+        "agent_prompt = '''spec_version: \"1.0\"\n",
+        "name: rag_agent\n",
+        "variables:\n",
+        "  required: [question]\n",
+        "messages:\n",
+        "  - role: system\n",
+        "    content: \"You are a retrieval-augmented agent. Use tools when needed and cite evidence.\"\n",
+        "  - role: user\n",
+        "    content: \"Question: {{ question }}\"\n",
+        "tests:\n",
+        "  - name: includes_question\n",
+        "    vars: { question: \"What is prompt versioning?\" }\n",
+        "    assert: { contains_any: [\"Question:\"] }\n",
+        "'''\n",
+        "\n",
+        "(repo / \"prompts\" / \"rag_answer.prompt.yml\").write_text(rag_prompt, encoding=\"utf-8\")\n",
+        "(repo / \"prompts\" / \"rag_agent.prompt.yml\").write_text(agent_prompt, encoding=\"utf-8\")\n",
+        "print(\"Wrote prompts in\", repo / \"prompts\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!ivault validate /content/ivault_demo/prompts"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from instructvault import InstructVault\n",
+        "\n",
+        "vault = InstructVault(repo_root=repo_path)\n",
+        "context = \"InstructVault keeps prompts in Git and uses CI for evals.\"\n",
+        "msgs = vault.render(\"prompts/rag_answer.prompt.yml\", vars={\"question\": \"What is InstructVault?\", \"context\": context})\n",
+        "print(msgs)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "!ivault eval /content/ivault_demo/prompts/rag_answer.prompt.yml --report /content/ivault_demo/out/rag_report.json"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "name": "instructvault_rag_colab.ipynb",
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.x"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

instructvault-0.3.0/examples/policies/policy_example.py

@@ -0,0 +1,14 @@
+def check_spec(spec: dict) -> list[str]:
+    errors = []
+    name = spec.get("name", "")
+    if name.startswith("unsafe_"):
+        errors.append("prompt name cannot start with 'unsafe_'")
+    return errors
+
+def check_render(text: str, context: dict) -> list[str]:
+    errors = []
+    forbidden = ["SSN", "credit card", "password"]
+    lowered = text.lower()
+    if any(f.lower() in lowered for f in forbidden):
+        errors.append("rendered output contains forbidden phrase")
+    return errors

instructvault-0.3.0/examples/policies/policy_pack.py

@@ -0,0 +1,26 @@
+import re
+
+EMAIL = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}")
+SSN = re.compile(r"\\b\\d{3}-\\d{2}-\\d{4}\\b")
+CC = re.compile(r"\\b(?:\\d[ -]*?){13,16}\\b")
+
+FORBIDDEN = ["password", "credit card", "ssn"]
+
+def check_spec(spec: dict) -> list[str]:
+    errors = []
+    if spec.get("name", "").startswith("unsafe_"):
+        errors.append("prompt name cannot start with 'unsafe_'")
+    return errors
+
+def check_render(text: str, context: dict) -> list[str]:
+    errors = []
+    if EMAIL.search(text):
+        errors.append("PII detected: email")
+    if SSN.search(text):
+        errors.append("PII detected: ssn")
+    if CC.search(text):
+        errors.append("PII detected: credit card")
+    lowered = text.lower()
+    if any(f in lowered for f in FORBIDDEN):
+        errors.append("forbidden phrase detected")
+    return errors

{instructvault-0.2.8 → instructvault-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "instructvault"
-version = "0.2.8"
+version = "0.3.0"
 description = "Git-first prompt registry + CI evals + lightweight runtime SDK (ivault)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,6 +12,7 @@ dependencies = [
   "pyyaml>=6.0",
   "jinja2>=3.1",
   "rich>=13.7",
+  "jsonschema>=4.21",
 ]
 
 [project.optional-dependencies]