instructvault 0.2.0__py3-none-any.whl

instructvault/__init__.py

@@ -0,0 +1,2 @@
+from .sdk import InstructVault
+__all__ = ["InstructVault"]

instructvault/bundle.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+from .io import load_prompt_spec
+from .spec import PromptSpec
+from .store import PromptStore
+
+@dataclass(frozen=True)
+class BundlePrompt:
+    path: str
+    spec: PromptSpec
+
+def _list_files_at_ref(repo_root: Path, ref: str, rel_dir: str) -> List[str]:
+    cmd = ["git", "-C", str(repo_root), "ls-tree", "-r", "--name-only", ref, rel_dir]
+    res = subprocess.run(cmd, capture_output=True, text=True)
+    if res.returncode != 0:
+        raise ValueError(res.stderr.strip() or f"Could not list files at ref {ref}")
+    return [line.strip() for line in res.stdout.splitlines() if line.strip()]
+
+def _is_prompt_file(path: str) -> bool:
+    lower = path.lower()
+    return lower.endswith(".prompt.yml") or lower.endswith(".prompt.yaml") or lower.endswith(".prompt.json")
+
+def collect_prompts(repo_root: Path, prompts_dir: Path, ref: Optional[str]) -> List[BundlePrompt]:
+    store = PromptStore(repo_root)
+    prompts: List[BundlePrompt] = []
+    if ref is None:
+        for p in sorted(prompts_dir.rglob("*.prompt.y*ml")):
+            rel_path = p.relative_to(repo_root).as_posix()
+            spec = load_prompt_spec(p.read_text(encoding="utf-8"))
+            prompts.append(BundlePrompt(rel_path, spec))
+        for p in sorted(prompts_dir.rglob("*.prompt.json")):
+            rel_path = p.relative_to(repo_root).as_posix()
+            spec = load_prompt_spec(p.read_text(encoding="utf-8"))
+            prompts.append(BundlePrompt(rel_path, spec))
+        return prompts
+
+    rel_dir = prompts_dir.relative_to(repo_root).as_posix()
+    for rel_path in _list_files_at_ref(repo_root, ref, rel_dir):
+        if not _is_prompt_file(rel_path):
+            continue
+        spec = load_prompt_spec(store.read_text(rel_path, ref=ref))
+        prompts.append(BundlePrompt(rel_path, spec))
+    return prompts
+
+def write_bundle(out_path: Path, *, repo_root: Path, prompts_dir: Path, ref: Optional[str]) -> None:
+    prompts = collect_prompts(repo_root, prompts_dir, ref)
+    payload = {
+        "bundle_version": "1.0",
+        "ref": ref or "WORKTREE",
+        "prompts": [
+            {"path": p.path, "spec": p.spec.model_dump(by_alias=True)}
+            for p in prompts
+        ],
+    }
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+

instructvault/cli.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import Optional
+import typer
+from rich import print as rprint
+
+from .bundle import write_bundle
+from .diff import unified_diff
+from .eval import run_dataset, run_inline_tests
+from .io import load_dataset_jsonl, load_prompt_spec
+from .junit import write_junit_xml
+from .render import check_required_vars, render_messages
+from .scaffold import init_repo
+from .store import PromptStore
+
+app = typer.Typer(help="InstructVault: git-first prompt registry + CI evals + runtime SDK")
+
+def _gather_prompt_files(base: Path) -> list[Path]:
+    if base.is_file():
+        return [base]
+    files = sorted(base.rglob("*.prompt.y*ml")) + sorted(base.rglob("*.prompt.json"))
+    return files
+
+@app.command()
+def init(repo: Path = typer.Option(Path("."), "--repo")):
+    init_repo(repo)
+    rprint("[green]Initialized prompts/, datasets/, and .github/workflows/ivault.yml[/green]")
+
+@app.command()
+def validate(path: Path = typer.Argument(...),
+             repo: Path = typer.Option(Path("."), "--repo"),
+             json_out: bool = typer.Option(False, "--json")):
+    base = path if path.is_absolute() else repo / path
+    files = _gather_prompt_files(base)
+    if not files:
+        raise typer.BadParameter("No prompt files found")
+    ok = True
+    results = []
+    for f in files:
+        try:
+            spec = load_prompt_spec(f.read_text(encoding="utf-8"))
+            try:
+                rel_path = f.relative_to(repo).as_posix()
+            except ValueError:
+                rel_path = str(f)
+            results.append({"path": rel_path, "ok": True, "name": spec.name})
+            if not json_out:
+                rprint(f"[green]OK[/green] {rel_path}  ({spec.name})")
+        except Exception as e:
+            ok = False
+            try:
+                rel_path = f.relative_to(repo).as_posix()
+            except ValueError:
+                rel_path = str(f)
+            results.append({"path": rel_path, "ok": False, "error": str(e)})
+            if not json_out:
+                rprint(f"[red]FAIL[/red] {rel_path}  {e}")
+    if json_out:
+        rprint(json.dumps({"ok": ok, "results": results}))
+    raise typer.Exit(code=0 if ok else 1)
+
+@app.command()
+def render(prompt_path: str = typer.Argument(...),
+           vars_json: str = typer.Option("{}", "--vars"),
+           ref: Optional[str] = typer.Option(None, "--ref"),
+           repo: Path = typer.Option(Path("."), "--repo"),
+           json_out: bool = typer.Option(False, "--json")):
+    store = PromptStore(repo_root=repo)
+    spec = load_prompt_spec(store.read_text(prompt_path, ref=ref))
+    vars_dict = json.loads(vars_json)
+    check_required_vars(spec, vars_dict)
+    msgs = render_messages(spec, vars_dict)
+    if json_out:
+        rprint(json.dumps([{"role": m.role, "content": m.content} for m in msgs]))
+    else:
+        for m in msgs:
+            rprint(f"[bold]{m.role}[/bold]\n{m.content}\n")
+
+@app.command()
+def diff(prompt_path: str = typer.Argument(...),
+         ref1: str = typer.Option(..., "--ref1"),
+         ref2: str = typer.Option(..., "--ref2"),
+         repo: Path = typer.Option(Path("."), "--repo"),
+         json_out: bool = typer.Option(False, "--json")):
+    store = PromptStore(repo_root=repo)
+    a = store.read_text(prompt_path, ref=ref1)
+    b = store.read_text(prompt_path, ref=ref2)
+    d = unified_diff(a, b, f"{ref1}:{prompt_path}", f"{ref2}:{prompt_path}")
+    if json_out:
+        rprint(json.dumps({"same": not d.strip(), "diff": d}))
+    else:
+        rprint(d if d.strip() else "[yellow]No differences[/yellow]")
+
+@app.command()
+def resolve(ref: str = typer.Argument(...),
+            repo: Path = typer.Option(Path("."), "--repo"),
+            json_out: bool = typer.Option(False, "--json")):
+    store = PromptStore(repo_root=repo)
+    sha = store.resolve_ref(ref)
+    if json_out:
+        rprint(json.dumps({"ref": ref, "sha": sha}))
+    else:
+        rprint(sha)
+
+@app.command()
+def bundle(prompts: Path = typer.Option(Path("prompts"), "--prompts"),
+           out: Path = typer.Option(Path("out/ivault.bundle.json"), "--out"),
+           ref: Optional[str] = typer.Option(None, "--ref"),
+           repo: Path = typer.Option(Path("."), "--repo")):
+    prompts_dir = prompts if prompts.is_absolute() else repo / prompts
+    write_bundle(out, repo_root=repo, prompts_dir=prompts_dir, ref=ref)
+    rprint(f"[green]Wrote bundle[/green] {out}")
+
+@app.command()
+def eval(prompt_path: str = typer.Argument(...),
+         ref: Optional[str] = typer.Option(None, "--ref"),
+         dataset: Optional[Path] = typer.Option(None, "--dataset"),
+         report: Optional[Path] = typer.Option(None, "--report"),
+         junit: Optional[Path] = typer.Option(None, "--junit"),
+         repo: Path = typer.Option(Path("."), "--repo"),
+         json_out: bool = typer.Option(False, "--json")):
+    store = PromptStore(repo_root=repo)
+    spec = load_prompt_spec(store.read_text(prompt_path, ref=ref))
+
+    ok1, r1 = run_inline_tests(spec)
+    results = list(r1)
+    ok = ok1
+
+    if dataset is not None:
+        rows = load_dataset_jsonl(dataset.read_text(encoding="utf-8"))
+        ok2, r2 = run_dataset(spec, rows)
+        ok = ok and ok2
+        results.extend(r2)
+
+    payload = {
+        "prompt": spec.name,
+        "ref": ref or "WORKTREE",
+        "pass": ok,
+        "results": [{"test": r.name, "pass": r.passed, "error": r.error} for r in results],
+    }
+    if report:
+        report.parent.mkdir(parents=True, exist_ok=True)
+        report.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    if junit:
+        junit.parent.mkdir(parents=True, exist_ok=True)
+        write_junit_xml(suite_name=f"ivault:{spec.name}", results=results, out_path=str(junit))
+
+    if json_out:
+        rprint(json.dumps(payload))
+    else:
+        for r in results:
+            if r.passed:
+                rprint(f"[green]PASS[/green] {r.name}")
+            else:
+                rprint(f"[red]FAIL[/red] {r.name}  {r.error or ''}")
+    raise typer.Exit(code=0 if ok else 1)

instructvault/diff.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+import difflib
+def unified_diff(a: str, b: str, fromfile: str, tofile: str) -> str:
+    return "".join(difflib.unified_diff(a.splitlines(keepends=True), b.splitlines(keepends=True), fromfile=fromfile, tofile=tofile))

instructvault/eval.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+from .spec import AssertSpec, DatasetRow, PromptSpec
+from .render import check_required_vars, render_joined_text
+
+@dataclass(frozen=True)
+class TestResult:
+    name: str
+    passed: bool
+    error: Optional[str] = None
+
+def _match_assert(assert_spec: AssertSpec, text: str) -> bool:
+    t = text.lower()
+    ok = True
+    if assert_spec.contains_any:
+        ok = ok and any(s.lower() in t for s in assert_spec.contains_any)
+    if assert_spec.contains_all:
+        ok = ok and all(s.lower() in t for s in assert_spec.contains_all)
+    if assert_spec.not_contains:
+        ok = ok and all(s.lower() not in t for s in assert_spec.not_contains)
+    return ok
+
+def run_inline_tests(spec: PromptSpec) -> Tuple[bool, List[TestResult]]:
+    results: List[TestResult] = []
+    all_ok = True
+    for t in spec.tests:
+        try:
+            check_required_vars(spec, t.vars)
+            out = render_joined_text(spec, t.vars)
+            passed = _match_assert(t.assert_, out)
+            results.append(TestResult(t.name, passed))
+            all_ok = all_ok and passed
+        except Exception as e:
+            results.append(TestResult(t.name, False, str(e)))
+            all_ok = False
+    return all_ok, results
+
+def run_dataset(spec: PromptSpec, rows: List[DatasetRow]) -> Tuple[bool, List[TestResult]]:
+    results: List[TestResult] = []
+    all_ok = True
+    for i, row in enumerate(rows, start=1):
+        name = f"dataset_row_{i}"
+        try:
+            check_required_vars(spec, row.vars)
+            out = render_joined_text(spec, row.vars)
+            passed = _match_assert(row.assert_, out)
+            results.append(TestResult(name, passed))
+            all_ok = all_ok and passed
+        except Exception as e:
+            results.append(TestResult(name, False, str(e)))
+            all_ok = False
+    return all_ok, results

instructvault/io.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+from typing import Any, Dict, List
+import json
+import yaml
+from .spec import DatasetRow, PromptSpec
+
+def load_prompt_spec(yaml_text: str) -> PromptSpec:
+    text = yaml_text.strip()
+    if text.startswith("{") or text.startswith("["):
+        data: Dict[str, Any] = json.loads(text) if text else {}
+    else:
+        data = yaml.safe_load(yaml_text) or {}
+    return PromptSpec.model_validate(data)
+
+def load_dataset_jsonl(text: str) -> List[DatasetRow]:
+    rows: List[DatasetRow] = []
+    for i, line in enumerate(text.splitlines(), start=1):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except Exception as e:
+            raise ValueError(f"Invalid JSON on line {i}: {e}") from e
+        rows.append(DatasetRow.model_validate(obj))
+    return rows

instructvault/junit.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+from typing import Iterable, Optional
+from .eval import TestResult
+
+def write_junit_xml(*, suite_name: str, results: Iterable[TestResult], out_path: str, timestamp: Optional[str] = None) -> None:
+    results = list(results)
+    tests = len(results)
+    failures = sum(1 for r in results if not r.passed)
+    ts = timestamp or datetime.now(timezone.utc).isoformat()
+
+    suite = ET.Element("testsuite", {
+        "name": suite_name,
+        "tests": str(tests),
+        "failures": str(failures),
+        "errors": "0",
+        "time": "0",
+        "timestamp": ts,
+    })
+
+    for r in results:
+        case = ET.SubElement(suite, "testcase", {"name": r.name, "classname": suite_name, "time": "0"})
+        if not r.passed:
+            f = ET.SubElement(case, "failure", {"message": r.error or "assertion failed", "type": "AssertionError"})
+            f.text = r.error or "assertion failed"
+
+    tree = ET.ElementTree(suite)
+    ET.indent(tree, space="  ")
+    tree.write(out_path, encoding="utf-8", xml_declaration=True)

instructvault/render.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+from typing import Any, Dict, List
+from jinja2 import Environment, StrictUndefined
+from .spec import PromptMessage, PromptSpec
+
+_env = Environment(undefined=StrictUndefined, autoescape=False)
+
+def check_required_vars(spec: PromptSpec, vars: Dict[str, Any]) -> None:
+    missing = [k for k in spec.variables.required if k not in vars]
+    if missing:
+        raise ValueError(f"Missing required vars: {missing}")
+
+def render_messages(spec: PromptSpec, vars: Dict[str, Any]) -> List[PromptMessage]:
+    rendered: List[PromptMessage] = []
+    for m in spec.messages:
+        tmpl = _env.from_string(m.content)
+        rendered.append(PromptMessage(role=m.role, content=tmpl.render(**vars)))
+    return rendered
+
+def render_joined_text(spec: PromptSpec, vars: Dict[str, Any]) -> str:
+    msgs = render_messages(spec, vars)
+    return "\n\n".join([f"{m.role}: {m.content}" for m in msgs])

instructvault/scaffold.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+from pathlib import Path
+
+DEFAULT_PROMPT = '''spec_version: "1.0"
+name: hello_world
+description: Minimal example prompt.
+variables:
+  required: [name]
+messages:
+  - role: system
+    content: "You are a helpful assistant."
+  - role: user
+    content: "Say hello to {{ name }}."
+tests:
+  - name: includes_name
+    vars: { name: "Ava" }
+    assert: { contains_any: ["Ava"] }
+'''
+
+DEFAULT_WORKFLOW = '''name: ivault (prompts)
+on:
+  pull_request:
+    paths:
+      - "prompts/**"
+      - "datasets/**"
+  push:
+    branches: [ main ]
+    paths:
+      - "prompts/**"
+      - "datasets/**"
+
+jobs:
+  prompts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install instructvault
+      - run: ivault validate prompts
+      - run: ivault eval prompts/hello_world.prompt.yml --report out/report.json --junit out/junit.xml
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: ivault-reports
+          path: out/
+'''
+
+def init_repo(repo_root: Path) -> None:
+    prompts = repo_root / "prompts"
+    datasets = repo_root / "datasets"
+    workflow = repo_root / ".github" / "workflows" / "ivault.yml"
+    prompts.mkdir(parents=True, exist_ok=True)
+    datasets.mkdir(parents=True, exist_ok=True)
+    workflow.parent.mkdir(parents=True, exist_ok=True)
+
+    sample_prompt = prompts / "hello_world.prompt.yml"
+    if not sample_prompt.exists():
+        sample_prompt.write_text(DEFAULT_PROMPT, encoding="utf-8")
+    if not workflow.exists():
+        workflow.write_text(DEFAULT_WORKFLOW, encoding="utf-8")

instructvault/sdk.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+import json
+from .io import load_prompt_spec
+from .render import check_required_vars, render_messages
+from .spec import PromptMessage, PromptSpec
+from .store import PromptStore
+
+class InstructVault:
+    def __init__(self, repo_root: Optional[Union[str, Path]] = None, bundle_path: Optional[Union[str, Path]] = None):
+        if repo_root is None and bundle_path is None:
+            raise ValueError("Provide repo_root or bundle_path")
+        self.store = PromptStore(Path(repo_root)) if repo_root is not None else None
+        self.bundle = None
+        if bundle_path is not None:
+            data = json.loads(Path(bundle_path).read_text(encoding="utf-8"))
+            self.bundle = {p["path"]: PromptSpec.model_validate(p["spec"]) for p in data.get("prompts", [])}
+
+    def load_prompt(self, prompt_path: str, ref: Optional[str] = None) -> PromptSpec:
+        if self.bundle is not None:
+            if prompt_path not in self.bundle:
+                raise FileNotFoundError(f"Prompt not found in bundle: {prompt_path}")
+            return self.bundle[prompt_path]
+        if self.store is None:
+            raise ValueError("No repo_root configured")
+        return load_prompt_spec(self.store.read_text(prompt_path, ref=ref))
+    def render(self, prompt_path: str, vars: Dict[str, Any], ref: Optional[str] = None) -> List[PromptMessage]:
+        spec = self.load_prompt(prompt_path, ref=ref)
+        check_required_vars(spec, vars)
+        return render_messages(spec, vars)

instructvault/spec.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Literal, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+Role = Literal["system", "user", "assistant", "tool"]
+
+class PromptMessage(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    role: Role
+    content: str
+
+class VariableSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    required: List[str] = Field(default_factory=list)
+    optional: List[str] = Field(default_factory=list)
+
+class ModelDefaults(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    temperature: Optional[float] = None
+    top_p: Optional[float] = None
+    max_tokens: Optional[int] = None
+
+class AssertSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    contains_any: Optional[List[str]] = None
+    contains_all: Optional[List[str]] = None
+    not_contains: Optional[List[str]] = None
+
+class PromptTest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: str
+    vars: Dict[str, Any] = Field(default_factory=dict)
+    assert_: AssertSpec = Field(alias="assert")
+
+class PromptSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+    spec_version: str = Field(default="1.0", alias="spec_version")
+    name: str
+    description: Optional[str] = None
+    model_defaults: ModelDefaults = Field(default_factory=ModelDefaults, alias="modelParameters")
+    variables: VariableSpec = Field(default_factory=VariableSpec)
+    messages: List[PromptMessage]
+    tests: List[PromptTest] = Field(default_factory=list)
+
+class DatasetRow(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    vars: Dict[str, Any] = Field(default_factory=dict)
+    assert_: AssertSpec = Field(alias="assert")

instructvault/store.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+class PromptStore:
+    def __init__(self, repo_root: Path):
+        self.repo_root = repo_root.resolve()
+
+    def read_text(self, rel_path: str, ref: Optional[str] = None) -> str:
+        rel_path = rel_path.lstrip("/")
+        if ref is None:
+            return (self.repo_root / rel_path).read_text(encoding="utf-8")
+        cmd = ["git", "-C", str(self.repo_root), "show", f"{ref}:{rel_path}"]
+        res = subprocess.run(cmd, capture_output=True, text=True)
+        if res.returncode != 0:
+            raise FileNotFoundError(res.stderr.strip() or f"Could not read {rel_path} at ref {ref}")
+        return res.stdout
+
+    def resolve_ref(self, ref: str) -> str:
+        cmd = ["git", "-C", str(self.repo_root), "rev-parse", ref]
+        res = subprocess.run(cmd, capture_output=True, text=True)
+        if res.returncode != 0:
+            raise ValueError(res.stderr.strip() or f"Could not resolve ref {ref}")
+        return res.stdout.strip()

instructvault-0.2.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: instructvault
+Version: 0.2.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
+Author: InstructVault OSS Maintainers
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# InstructVault (`ivault`)
+**Git‑first prompt hub for teams and individual developers.**
+
+InstructVault makes prompts **first‑class, governed, testable, versioned artifacts** — just like code — while keeping runtime **fast and local**.
+
+## What this does (at a glance)
+- **Prompts live in Git** as YAML/JSON files
+- **CI validates + evaluates** prompts on every change
+- **Releases are tags/SHAs**, reproducible by design
+- **Runtime stays lightweight** (local read or bundle artifact)
+
+## System flow (Mermaid)
+```mermaid
+flowchart LR
+  A[Prompt files<br/>YAML/JSON] --> B[PR Review]
+  B --> C[CI: validate + eval]
+  C --> D{Release?}
+  D -- tag/SHA --> E[Bundle artifact]
+  D -- tag/SHA --> F[Deploy app]
+  E --> F
+  F --> G[Runtime render<br/>local or bundle]
+```
+
+## Why this exists
+Enterprises already have Git + PR reviews + CI/CD. Prompts usually don’t.
+InstructVault brings **prompt‑as‑code** without requiring a server, database, or platform.
+
+## Features
+- ✅ Git‑native versioning (tags/SHAs = releases)
+- ✅ CLI‑first (`init`, `validate`, `render`, `eval`, `diff`, `resolve`, `bundle`)
+- ✅ LLM‑framework agnostic (returns standard `{role, content}` messages)
+- ✅ CI‑friendly reports (JSON + optional JUnit XML)
+- ✅ No runtime latency tax (local read or bundle)
+- ✅ Optional playground (separate package)
+
+## Install
+### Users
+```bash
+pip install instructvault
+```
+
+### Contributors
+```bash
+git clone <your-repo>
+cd instructvault
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Quickstart (end‑to‑end)
+
+### 1) Initialize a repo
+```bash
+ivault init
+```
+
+### 2) Create a prompt
+`prompts/support_reply.prompt.yml` (YAML or JSON)
+```yaml
+spec_version: "1.0"
+name: support_reply
+description: Respond to a support ticket with empathy and clear steps.
+model_defaults:
+  temperature: 0.2
+
+variables:
+  required: [ticket_text]
+  optional: [customer_name]
+
+messages:
+  - role: system
+    content: |
+      You are a support engineer. Be concise, empathetic, and action-oriented.
+  - role: user
+    content: |
+      Customer: {{ customer_name | default("there") }}
+      Ticket:
+      {{ ticket_text }}
+
+tests:
+  - name: must_contain_customer_and_ticket
+    vars:
+      ticket_text: "My order arrived damaged."
+      customer_name: "Alex"
+    assert:
+      contains_all: ["Customer:", "Ticket:"]
+```
+
+### 3) Validate + render locally
+```bash
+ivault validate prompts
+ivault render prompts/support_reply.prompt.yml --vars '{"ticket_text":"My app crashed.","customer_name":"Sam"}'
+```
+
+### 4) Add dataset‑driven eval
+`datasets/support_cases.jsonl`
+```jsonl
+{"vars":{"ticket_text":"Order arrived damaged","customer_name":"Alex"},"assert":{"contains_any":["Ticket:"]}}
+{"vars":{"ticket_text":"Need refund"},"assert":{"contains_all":["Ticket:"]}}
+```
+
+```bash
+ivault eval prompts/support_reply.prompt.yml --dataset datasets/support_cases.jsonl --report out/report.json --junit out/junit.xml
+```
+
+### 5) Version prompts with tags
+```bash
+git add prompts datasets
+git commit -m "Add support prompts + eval dataset"
+git tag prompts/v1.0.0
+```
+
+### 6) Load by Git ref at runtime
+```python
+from instructvault import InstructVault
+
+vault = InstructVault(repo_root=".")
+msgs = vault.render(
+  "prompts/support_reply.prompt.yml",
+  vars={"ticket_text":"My order is delayed", "customer_name":"Ava"},
+  ref="prompts/v1.0.0",
+)
+```
+
+### 7) Bundle prompts at build time (optional)
+```bash
+ivault bundle --prompts prompts --out out/ivault.bundle.json --ref prompts/v1.0.0
+```
+
+```python
+from instructvault import InstructVault
+vault = InstructVault(bundle_path="out/ivault.bundle.json")
+```
+
+## How teams use this in production
+1) Prompt changes go through PRs
+2) CI runs `validate` + `eval`
+3) Tags or bundles become the deployable artifact
+4) Apps load by tag or bundle (no runtime network calls)
+
+## Datasets (why JSONL)
+Datasets are **deterministic eval inputs** checked into Git. This makes CI reproducible and audit‑friendly.
+For cloud datasets, use a CI pre‑step (e.g., download from S3) and then run `ivault eval` on the local file.
+
+## Playground (optional)
+A minimal playground exists under `playground/` for local or org‑hosted use.
+It lists prompts, renders with variables, and runs evals — without touching production prompts directly.
+For local dev, run from the repo root:
+```bash
+export IVAULT_REPO_ROOT=/path/to/your/repo
+PYTHONPATH=. uvicorn ivault_playground.app:app --reload
+```
+
+## Docs
+- `docs/governance.md`
+- `docs/ci.md`
+- `docs/playground.md`
+- `docs/cookbooks.md`
+- `docs/dropin_guide.md`
+- `docs/release_checklist.md`
+- `docs/ci_templates/gitlab-ci.yml`
+- `docs/ci_templates/Jenkinsfile`
+- `CHANGELOG.md`
+- `CODE_OF_CONDUCT.md`
+
+## License
+Apache‑2.0

instructvault-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+instructvault/__init__.py,sha256=cg7j0qh6W84D-K0uSOLKKAP2JquW4NRXwZRDDLk5E18,59
+instructvault/bundle.py,sha256=gXOqjpza_8MrYJjJVCzBJKHbO78bXkAbqPUjKnS_6Nk,2478
+instructvault/cli.py,sha256=2ylpvw-GHmZdIUVS3AoepWcQy6RG9QAwqVEQaCFG60o,6065
+instructvault/diff.py,sha256=vz_vmKDXasNFoVKHCk2u_TsboHk1BdwvX0wCnJI1ATQ,252
+instructvault/eval.py,sha256=-yrFHCEUrONvzfKLP8s_RktFU74Ergp9tQJvzfrMR9s,1949
+instructvault/io.py,sha256=mxoNp6SXbFoty22fzrbf7z-B5Nlw0XjgWphK0awA1S8,867
+instructvault/junit.py,sha256=sIEcIiGD3Xk6uCYjnE5p_07j8dPoS_RAc2eoy3BIBeQ,1133
+instructvault/render.py,sha256=vcVnqIXGytskZEKbUofoKgIVflQSYhsmdpEtZs1X19A,919
+instructvault/scaffold.py,sha256=f5gwXE3dUPuJYTedZRqBs8w5SQEgt1dgDSuqW2dxrMg,1685
+instructvault/sdk.py,sha256=JpEik6AZof2cIG-4GO-mdWwZe7w2rwq45jKawwfstsQ,1594
+instructvault/spec.py,sha256=xRkcVjMnoKECLaAfjQHiGgQVMdZ_KvNzf-K-j6DQ6k0,1737
+instructvault/store.py,sha256=NhN49w7xrkeij0lQDr-CEdANYLpNVBXumv_cKqLmiYY,1056
+instructvault-0.2.0.dist-info/METADATA,sha256=pU68kaOH7DoqVGn9iGzq0eIl06dH92JIGx3dnZMsjlA,5536
+instructvault-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+instructvault-0.2.0.dist-info/entry_points.txt,sha256=cdcMJQwBk9c95LwfN2W6x2xO43FwPjhfV3jHE7TTuHg,49
+instructvault-0.2.0.dist-info/licenses/LICENSE,sha256=VFbCvIsyizmkz4NrZPMdcPhyRK5uM0HhAjv3GBUbb7Y,135
+instructvault-0.2.0.dist-info/RECORD,,

instructvault-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

instructvault-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ivault = instructvault.cli:app

instructvault-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,5 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION