instructvault 0.2.2__tar.gz → 0.2.3__tar.gz

instructvault-0.2.3/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  core-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: pytest
+
+  prompt-checks:
+    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/

instructvault-0.2.3/.github/workflows/prompt-checks.yml

@@ -0,0 +1,30 @@
+name: prompt-checks
+on:
+  pull_request:
+    paths:
+      - "prompts/**"
+      - "datasets/**"
+      - ".github/workflows/prompt-checks.yml"
+  push:
+    branches: [ main ]
+    paths:
+      - "prompts/**"
+      - "datasets/**"
+      - ".github/workflows/prompt-checks.yml"
+
+jobs:
+  prompt-checks:
+    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/

{instructvault-0.2.2 → instructvault-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instructvault
-Version: 0.2.2
+Version: 0.2.3
 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
@@ -14,6 +14,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.7
 Requires-Dist: typer>=0.12
 Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
@@ -48,6 +49,10 @@ flowchart LR
 Enterprises already have Git + PR reviews + CI/CD. Prompts usually don’t.
 InstructVault brings **prompt‑as‑code** without requiring a server, database, or platform.
 
+## Vision
+Short version: Git‑first prompts with CI governance and zero‑latency runtime.  
+Full vision: `docs/vision.md`
+
 ## Features
 - ✅ Git‑native versioning (tags/SHAs = releases)
 - ✅ CLI‑first (`init`, `validate`, `render`, `eval`, `diff`, `resolve`, `bundle`)
@@ -128,6 +133,10 @@ ivault render prompts/support_reply.prompt.yml --vars '{"ticket_text":"My app cr
 ivault eval prompts/support_reply.prompt.yml --dataset datasets/support_cases.jsonl --report out/report.json --junit out/junit.xml
 ```
 
+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.
+
 ### 5) Version prompts with tags
 ```bash
 git add prompts datasets
@@ -176,7 +185,17 @@ export IVAULT_REPO_ROOT=/path/to/your/repo
 PYTHONPATH=. uvicorn ivault_playground.app:app --reload
 ```
 
+![Playground screenshot](docs/assets/playground.png)
+
+Optional auth:
+```bash
+export IVAULT_PLAYGROUND_API_KEY=your-secret
+```
+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/vision.md`
 - `docs/governance.md`
 - `docs/ci.md`
 - `docs/playground.md`

{instructvault-0.2.2 → instructvault-0.2.3}/README.md

@@ -25,6 +25,10 @@ flowchart LR
 Enterprises already have Git + PR reviews + CI/CD. Prompts usually don’t.
 InstructVault brings **prompt‑as‑code** without requiring a server, database, or platform.
 
+## Vision
+Short version: Git‑first prompts with CI governance and zero‑latency runtime.  
+Full vision: `docs/vision.md`
+
 ## Features
 - ✅ Git‑native versioning (tags/SHAs = releases)
 - ✅ CLI‑first (`init`, `validate`, `render`, `eval`, `diff`, `resolve`, `bundle`)
@@ -105,6 +109,10 @@ ivault render prompts/support_reply.prompt.yml --vars '{"ticket_text":"My app cr
 ivault eval prompts/support_reply.prompt.yml --dataset datasets/support_cases.jsonl --report out/report.json --junit out/junit.xml
 ```
 
+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.
+
 ### 5) Version prompts with tags
 ```bash
 git add prompts datasets
@@ -153,7 +161,17 @@ export IVAULT_REPO_ROOT=/path/to/your/repo
 PYTHONPATH=. uvicorn ivault_playground.app:app --reload
 ```
 
+![Playground screenshot](docs/assets/playground.png)
+
+Optional auth:
+```bash
+export IVAULT_PLAYGROUND_API_KEY=your-secret
+```
+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/vision.md`
 - `docs/governance.md`
 - `docs/ci.md`
 - `docs/playground.md`

instructvault-0.2.3/docs/vision.md

@@ -0,0 +1,76 @@
+# InstructVault (ivault) — Vision
+
+## Purpose
+InstructVault makes prompts **first‑class, governed, testable, versioned artifacts** — just like code — while keeping runtime **fast and local**.
+
+## North Star
+**Prompts live in Git.**  
+**Prompt changes flow through CI/CD.**  
+**Prompt releases are immutable and reproducible.**  
+**Runtime stays fast, local, and framework‑agnostic.**
+
+If InstructVault ever violates this, it is a bug — not a feature.
+
+## Non‑Negotiables
+1) **Git is the source of truth**  
+   Prompts are files; versions are tags/SHAs/branches. No prompt database required.
+
+2) **Zero runtime latency**  
+   No network calls at inference time. Load from local repo or build‑time bundles.
+
+3) **Framework & vendor agnostic**  
+   Output is standard `{ role, content }` messages. Works with any LLM stack.
+
+4) **Governance first**  
+   Prompt changes go through PRs, reviews, and CI checks. No direct writes.
+
+5) **Small core, extensible edges**  
+   Core stays tiny and auditable. Heavy integrations are optional and separate.
+
+## What the Core Provides
+- Prompt spec + validation
+- Deterministic rendering
+- Git ref loading
+- Deterministic evals (inline + dataset)
+- CLI (`ivault`) and runtime SDK
+
+## What the Core Explicitly Does Not Provide
+- Hosted services or databases
+- Forced LLM calls
+- Cloud SDK dependencies in core
+
+## Prompt Spec (YAML/JSON)
+```yaml
+spec_version: "1.0"
+name: support_reply
+variables:
+  required: [ticket_text]
+messages:
+  - role: system
+    content: "You are a support engineer."
+  - role: user
+    content: "Ticket: {{ ticket_text }}"
+tests:
+  - name: must_include_ticket
+    vars: { ticket_text: "Order damaged" }
+    assert: { contains_any: ["Ticket:"] }
+```
+
+## CLI Contract
+`init`, `validate`, `render`, `eval`, `diff`, `resolve`, `bundle`  
+Deterministic behavior, CI‑friendly exit codes, JSON/JUnit outputs where applicable.
+
+## CI/CD Model (PromptOps)
+- Run checks only when prompt paths change  
+- Stages: **validate → eval → report**  
+- Fail fast and clearly
+
+## Governance Model
+Use existing Git governance: CODEOWNERS, branch protection, required CI checks.
+
+## Success Criteria
+- Teams adopt without friction
+- Prompt changes are reviewed like code
+- CI catches regressions
+- Rollbacks are instant
+- Runtime stays fast and local

instructvault-0.2.3/examples/prompts/hello_world.prompt.yml

@@ -0,0 +1,14 @@
+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"] }

{instructvault-0.2.2 → instructvault-0.2.3}/playground/README.md

@@ -17,5 +17,20 @@ export IVAULT_REPO_ROOT=/path/to/your/repo
 PYTHONPATH=.. uvicorn ivault_playground.app:app --reload
 ```
 
+Alternative (from repo root):
+```
+export IVAULT_REPO_ROOT=/path/to/your/repo
+PYTHONPATH=. uvicorn ivault_playground.app:app --reload
+```
+
+Then open:
+- `http://127.0.0.1:8000/` (landing page)
+- `http://127.0.0.1:8000/docs` (API docs)
+
 Environment:
 - `IVAULT_REPO_ROOT` (default: current working directory)
+ - `IVAULT_PLAYGROUND_API_KEY` (optional; if set, require `x-ivault-api-key` header)
+
+Notes:
+- This minimal playground has no auth; put it behind your org auth if hosted.
+- PR-only writes are not implemented yet (API is read-only + eval).

instructvault-0.2.3/playground/ivault_playground/app.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+import os
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from pathlib import Path
+from .routes.api import router as api_router
+from .routes.ui import router as ui_router
+
+app = FastAPI(title="ivault-playground", version="0.1.0")
+
+_API_KEY = os.getenv("IVAULT_PLAYGROUND_API_KEY")
+
+@app.middleware("http")
+async def _api_key_guard(request: Request, call_next):
+    if not _API_KEY:
+        return await call_next(request)
+    if request.url.path in ("/health",):
+        return await call_next(request)
+    key = request.headers.get("x-ivault-api-key")
+    if key != _API_KEY:
+        return HTMLResponse("Unauthorized", status_code=401)
+    return await call_next(request)
+
+app.include_router(ui_router)
+app.include_router(api_router)
+
+_STATIC_DIR = Path(__file__).resolve().parent / "static"
+app.mount("/static", StaticFiles(directory=_STATIC_DIR), name="static")

instructvault-0.2.3/playground/ivault_playground/routes/api.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+import os
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from instructvault import InstructVault
+from instructvault.io import load_prompt_spec, load_dataset_jsonl
+from instructvault.store import PromptStore
+from instructvault.eval import run_dataset, run_inline_tests
+
+router = APIRouter()
+
+class RenderRequest(BaseModel):
+    prompt_path: str
+    vars: Dict[str, Any]
+    ref: Optional[str] = None
+
+class EvalRequest(BaseModel):
+    prompt_path: str
+    dataset_path: Optional[str] = None
+    ref: Optional[str] = None
+
+def _repo_root() -> Path:
+    return Path(os.getenv("IVAULT_REPO_ROOT", ".")).resolve()
+
+@router.get("/health")
+def health() -> Dict[str, str]:
+    return {"status": "ok"}
+
+@router.get("/prompts")
+def list_prompts(ref: Optional[str] = None) -> List[str]:
+    repo = _repo_root()
+    prompts_dir = repo / "prompts"
+    if ref:
+        cmd = ["git", "-C", str(repo), "ls-tree", "-r", "--name-only", ref, "prompts"]
+        res = subprocess.run(cmd, capture_output=True, text=True)
+        if res.returncode != 0:
+            return []
+        files = [line.strip() for line in res.stdout.splitlines() if line.strip()]
+        return [p for p in files if p.endswith((".prompt.yml", ".prompt.yaml", ".prompt.json"))]
+    if not prompts_dir.exists():
+        return []
+    files = sorted(prompts_dir.rglob("*.prompt.y*ml")) + sorted(prompts_dir.rglob("*.prompt.json"))
+    return [p.relative_to(repo).as_posix() for p in files]
+
+@router.get("/refs")
+def list_refs() -> List[str]:
+    repo = _repo_root()
+    cmd = ["git", "-C", str(repo), "tag", "--list", "prompts/*"]
+    res = subprocess.run(cmd, capture_output=True, text=True)
+    if res.returncode != 0:
+        return []
+    return [r.strip() for r in res.stdout.splitlines() if r.strip()]
+
+@router.get("/prompt")
+def get_prompt(prompt_path: str, ref: Optional[str] = None) -> Dict[str, Any]:
+    repo = _repo_root()
+    if ref:
+        store = PromptStore(repo)
+        try:
+            spec = load_prompt_spec(store.read_text(prompt_path, ref=ref))
+        except Exception:
+            raise HTTPException(status_code=404, detail="Prompt not found at ref")
+    else:
+        p = repo / prompt_path
+        if not p.exists():
+            raise HTTPException(status_code=404, detail="Prompt not found")
+        spec = load_prompt_spec(p.read_text(encoding="utf-8"))
+    return spec.model_dump(by_alias=True)
+
+@router.post("/render")
+def render(req: RenderRequest) -> List[Dict[str, str]]:
+    repo = _repo_root()
+    vault = InstructVault(repo_root=repo)
+    msgs = vault.render(req.prompt_path, vars=req.vars, ref=req.ref)
+    return [{"role": m.role, "content": m.content} for m in msgs]
+
+@router.post("/eval")
+def eval_prompt(req: EvalRequest) -> Dict[str, Any]:
+    repo = _repo_root()
+    store = PromptStore(repo)
+    spec = load_prompt_spec(store.read_text(req.prompt_path, ref=req.ref))
+
+    ok1, r1 = run_inline_tests(spec)
+    results = list(r1)
+    ok = ok1
+
+    if req.dataset_path:
+        rows = load_dataset_jsonl((repo / req.dataset_path).read_text(encoding="utf-8"))
+        ok2, r2 = run_dataset(spec, rows)
+        ok = ok and ok2
+        results.extend(r2)
+
+    return {
+        "prompt": spec.name,
+        "ref": req.ref or "WORKTREE",
+        "pass": ok,
+        "results": [{"test": r.name, "pass": r.passed, "error": r.error} for r in results],
+    }

instructvault-0.2.3/playground/ivault_playground/routes/ui.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+from fastapi import APIRouter
+from fastapi.responses import HTMLResponse
+from pathlib import Path
+
+router = APIRouter()
+
+_TEMPLATE = Path(__file__).resolve().parent.parent / "templates" / "index.html"
+
+@router.get("/", response_class=HTMLResponse)
+def index() -> str:
+    return _TEMPLATE.read_text(encoding="utf-8")

instructvault-0.2.3/playground/ivault_playground/static/app.css

@@ -0,0 +1,145 @@
+:root {
+  --bg: #0f172a;
+  --panel: #111827;
+  --muted: #94a3b8;
+  --text: #e2e8f0;
+  --accent: #22c55e;
+  --line: #1f2937;
+}
+body {
+  margin: 0;
+  font-family: "IBM Plex Sans", "Segoe UI", "Helvetica Neue", Arial, sans-serif;
+  background: radial-gradient(1200px 600px at 10% -10%, #1e293b, #0f172a);
+  color: var(--text);
+}
+.wrap { max-width: 980px; margin: 48px auto; padding: 0 24px; }
+.hero {
+  background: linear-gradient(140deg, #0b1220, #111827);
+  border: 1px solid var(--line);
+  border-radius: 16px;
+  padding: 32px;
+  box-shadow: 0 10px 30px rgba(0,0,0,0.35);
+}
+h1 { margin: 0 0 8px 0; font-size: 32px; letter-spacing: 0.3px; }
+.sub { color: var(--muted); margin: 0 0 24px 0; }
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 16px;
+}
+.split {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 16px;
+  margin-top: 20px;
+}
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 16px;
+}
+.panel h3 { margin: 0 0 8px 0; font-size: 16px; }
+.row {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  margin-bottom: 12px;
+}
+.col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+select {
+  background: #0b1220;
+  color: var(--text);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 6px 8px;
+}
+textarea {
+  width: 100%;
+  min-height: 90px;
+  background: #0b1220;
+  color: var(--text);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 10px;
+  font-family: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  font-size: 12px;
+}
+.btn {
+  background: #16a34a;
+  color: #0b1220;
+  border: none;
+  border-radius: 8px;
+  padding: 8px 12px;
+  cursor: pointer;
+  font-weight: 600;
+}
+.btn.secondary {
+  background: transparent;
+  color: var(--text);
+  border: 1px solid var(--line);
+}
+.list {
+  max-height: 320px;
+  overflow: auto;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+}
+.list button {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 10px 12px;
+  border: none;
+  background: transparent;
+  color: var(--text);
+  border-bottom: 1px solid var(--line);
+  cursor: pointer;
+}
+.list button:hover { background: rgba(148,163,184,0.08); }
+pre {
+  background: #0b1220;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 12px;
+  color: #e5e7eb;
+  overflow: auto;
+  max-height: 320px;
+}
+.card {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 16px;
+}
+.card h3 { margin: 0 0 8px 0; font-size: 16px; }
+.card p { margin: 0; color: var(--muted); font-size: 14px; }
+.links a {
+  display: inline-block;
+  margin-right: 12px;
+  color: var(--text);
+  text-decoration: none;
+  border-bottom: 1px solid transparent;
+}
+.links a:hover { border-bottom-color: var(--accent); }
+.badge {
+  display: inline-block;
+  padding: 4px 10px;
+  border-radius: 999px;
+  background: rgba(34,197,94,0.15);
+  color: #86efac;
+  font-size: 12px;
+  margin-left: 8px;
+}
+footer { margin-top: 24px; color: var(--muted); font-size: 12px; }
+@media (max-width: 900px) {
+  .split { grid-template-columns: 1fr; }
+}
+@media (max-width: 640px) {
+  .wrap { margin: 24px auto; }
+  h1 { font-size: 26px; }
+}

instructvault-0.2.3/playground/ivault_playground/static/app.js

@@ -0,0 +1,116 @@
+async function loadPrompts() {
+  const list = document.getElementById("promptList");
+  list.innerHTML = "Loading...";
+  try {
+    const ref = document.getElementById("refSelect").value;
+    const url = ref ? `/prompts?ref=${encodeURIComponent(ref)}` : "/prompts";
+    const res = await fetch(url);
+    const data = await res.json();
+    list.innerHTML = "";
+    if (!data.length) {
+      list.innerHTML = "<div style='padding:10px;color:#94a3b8;'>No prompts found.</div>";
+      return;
+    }
+    data.forEach((p) => {
+      const btn = document.createElement("button");
+      btn.textContent = p;
+      btn.onclick = () => loadPrompt(p);
+      list.appendChild(btn);
+    });
+  } catch (e) {
+    list.innerHTML = "<div style='padding:10px;color:#f87171;'>Failed to load prompts.</div>";
+  }
+}
+
+async function loadPrompt(path) {
+  const preview = document.getElementById("promptPreview");
+  preview.textContent = "Loading...";
+  try {
+    const ref = document.getElementById("refSelect").value;
+    const url = ref
+      ? `/prompt?prompt_path=${encodeURIComponent(path)}&ref=${encodeURIComponent(ref)}`
+      : `/prompt?prompt_path=${encodeURIComponent(path)}`;
+    const res = await fetch(url);
+    const data = await res.json();
+    preview.textContent = JSON.stringify(data, null, 2);
+    window.__currentPromptPath = path;
+    window.__currentPromptRef = ref || null;
+  } catch (e) {
+    preview.textContent = "Failed to load prompt.";
+  }
+}
+
+async function loadRefs() {
+  try {
+    const res = await fetch("/refs");
+    const data = await res.json();
+    const sel = document.getElementById("refSelect");
+    data.forEach((r) => {
+      const opt = document.createElement("option");
+      opt.value = r;
+      opt.textContent = r;
+      sel.appendChild(opt);
+    });
+    sel.onchange = () => {
+      document.getElementById("promptPreview").textContent = "Select a prompt to view its spec.";
+      document.getElementById("renderOutput").textContent = "Rendered messages will appear here.";
+      window.__currentPromptPath = null;
+      window.__currentPromptRef = sel.value || null;
+      loadPrompts();
+    };
+  } catch (e) {}
+}
+
+function attachHandlers() {
+  document.getElementById("varsInput").value = JSON.stringify({name: "ivault"});
+
+  document.getElementById("copyBtn").onclick = async () => {
+    const text = document.getElementById("promptPreview").textContent;
+    try {
+      await navigator.clipboard.writeText(text);
+      document.getElementById("copyBtn").textContent = "Copied";
+      setTimeout(() => (document.getElementById("copyBtn").textContent = "Copy JSON"), 1200);
+    } catch (e) {}
+  };
+
+  document.getElementById("renderBtn").onclick = async () => {
+    const out = document.getElementById("renderOutput");
+    out.textContent = "Rendering...";
+    try {
+      const path = window.__currentPromptPath;
+      if (!path) {
+        out.textContent = "Select a prompt first.";
+        return;
+      }
+      const varsText = document.getElementById("varsInput").value || "{}";
+      let vars;
+      try {
+        vars = JSON.parse(varsText);
+      } catch (e) {
+        out.textContent = 'Invalid JSON in vars. Example: {"name":"Ava"}';
+        return;
+      }
+      const ref = window.__currentPromptRef;
+      const payload = { prompt_path: path, vars, ref };
+      const res = await fetch("/render", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        out.textContent = data.detail || "Render failed.";
+        return;
+      }
+      out.textContent = JSON.stringify(data, null, 2);
+    } catch (e) {
+      out.textContent = "Render failed. Check JSON vars.";
+    }
+  };
+}
+
+window.addEventListener("load", () => {
+  loadPrompts();
+  loadRefs();
+  attachHandlers();
+});