instructvault 0.2.9__tar.gz → 0.3.1__tar.gz

{instructvault-0.2.9 → instructvault-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instructvault
-Version: 0.2.9
+Version: 0.3.1
 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
@@ -31,7 +31,13 @@ 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**.
+- Prompts are governed artifacts: versioned in Git, validated in CI, and loaded locally at runtime.
+- Teams ship prompt changes as safely as code without added latency or vendor lock‑in.
+- A small, auditable core with deterministic evals, release tags, and optional policy hooks.
+
+InstructVault is a Git‑first “prompt‑as‑code” system. Prompts live in your repo,
+are validated and evaluated in CI, released via tags/SHAs, and loaded locally at runtime
+directly from Git or via a bundle artifact.
 
 ## What this does (at a glance)
 - **Prompts live in Git** as YAML/JSON files
@@ -85,6 +91,50 @@ pytest
 
 ## Quickstart (end‑to‑end)
 
+### End‑user workflow (typical)
+1) Install `instructvault` in your app repo (or a dedicated prompts repo)
+2) Run `ivault init` once to scaffold `prompts/`, `datasets/`, and CI
+3) Add or edit prompt files under `prompts/`
+4) Validate and eval locally (`ivault validate`, `ivault eval`)
+5) Commit prompt changes and create a tag (e.g., `prompts/v1.0.0`)
+6) In your app, render by git ref (tag/branch/SHA) or ship a bundle artifact
+
+### Using InstructVault in an existing app repo
+1) `pip install instructvault`
+2) Create a `prompts/` folder (or pick an existing one)
+3) Add prompt files under `prompts/` and at least one inline test per prompt
+4) Add CI checks (copy from `docs/ci.md` or run `ivault init` to scaffold workflow)
+5) Validate/eval locally: `ivault validate prompts`, `ivault eval prompts/<file>.prompt.yml --report out/report.json`
+6) Commit prompts and optionally tag: `git tag prompts/v1.0.0`
+7) At runtime, load by ref or bundle artifact
+
+### Visual workflow (new app repo)
+```mermaid
+flowchart LR
+  A[Install ivault] --> B[ivault init]
+  B --> C["Add/edit prompts"]
+  C --> D["ivault validate + eval"]
+  D --> E["Commit + tag"]
+  E --> F{Runtime path}
+  F -->|Load by ref| G["InstructVault(repo_root)"]
+  F -->|Bundle artifact| H[ivault bundle]
+  H --> I["InstructVault(bundle_path)"]
+```
+
+### Visual workflow (existing app repo)
+```mermaid
+flowchart LR
+  A[Install instructvault] --> B["Create/choose prompts/ + datasets/"]
+  B --> C["Add/edit prompt files"]
+  C --> D[Add CI checks]
+  D --> E["Local validate + eval"]
+  E --> F["Commit + tag (optional)"]
+  F --> G{Runtime path}
+  G -->|Load by ref| H["InstructVault(repo_root)"]
+  G -->|Bundle artifact| I[ivault bundle]
+  I --> J["InstructVault(bundle_path)"]
+```
+
 ### 1) Initialize a repo
 ```bash
 ivault init
@@ -128,9 +178,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.
+#### 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`
@@ -143,11 +194,10 @@ Use `--policy /path/to/policy.py` to enforce custom compliance rules.
 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.
+#### 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:
+#### Spec migration check:
 ```bash
 ivault migrate prompts
 ```
@@ -171,6 +221,29 @@ msgs = vault.render(
 )
 ```
 
+Troubleshooting: if you pass a `ref` and see `FileNotFoundError` from `store.read_text`,
+the prompt file must exist at that ref and be committed in the same repo. Tags/branches
+must point to commits that include the prompt file.
+
+### Multi‑repo usage (app repo + prompts repo)
+If your prompts live in a separate repo, point `repo_root` to that repo (not your app repo),
+or bundle prompts at build time and ship the bundle with your app.
+```python
+from instructvault import InstructVault
+
+vault = InstructVault(repo_root="/path/to/prompts-repo")
+msgs = vault.render(
+  "prompts/support_reply.prompt.yml",
+  vars={"ticket_text":"My order is delayed"},
+  ref="prompts/v1.0.0",
+)
+```
+
+### Troubleshooting (common)
+- `FileNotFoundError ... read_text` with `ref`: prompt not committed at that ref, or wrong repo_root
+- `No prompt files found`: path passed to `ivault validate` doesn’t contain `*.prompt.yml|json`
+- `prompt must include at least one test`: add a minimal inline test or use `--allow-no-tests` for render
+
 ### 7) Bundle prompts at build time (optional)
 ```bash
 ivault bundle --prompts prompts --out out/ivault.bundle.json --ref prompts/v1.0.0
@@ -189,6 +262,9 @@ 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)
 
+## Examples
+- `examples/ivault_demo_template/README.md`
+
 ## Example Policies
 - `examples/policies/policy_example.py`
 - `examples/policies/policy_pack.py`
@@ -222,17 +298,17 @@ 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`
-- `docs/ci_templates/Jenkinsfile`
+- `docs/dropin_guide.md` — minimal setup if you already have CI
+- `docs/cookbooks.md` — workflows (tags, bundles, multi‑repo, RAG)
+- `docs/spec.md` — prompt spec and validation rules
+- `docs/ci.md` — CI setup and reports
+- `docs/governance.md` — CODEOWNERS and release guardrails
+- `docs/playground.md` — optional local/hosted playground
+- `docs/audit_logging.md` — audit fields and patterns
+- `docs/vision.md` — product vision and guiding principles
+- `docs/release_checklist.md` — release checklist for maintainers
+- `docs/ci_templates/gitlab-ci.yml` — GitLab CI example
+- `docs/ci_templates/Jenkinsfile` — Jenkins example
 - `CHANGELOG.md`
 - `CODE_OF_CONDUCT.md`
 

{instructvault-0.2.9 → instructvault-0.3.1}/README.md

@@ -5,7 +5,13 @@
 # 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**.
+- Prompts are governed artifacts: versioned in Git, validated in CI, and loaded locally at runtime.
+- Teams ship prompt changes as safely as code without added latency or vendor lock‑in.
+- A small, auditable core with deterministic evals, release tags, and optional policy hooks.
+
+InstructVault is a Git‑first “prompt‑as‑code” system. Prompts live in your repo,
+are validated and evaluated in CI, released via tags/SHAs, and loaded locally at runtime
+directly from Git or via a bundle artifact.
 
 ## What this does (at a glance)
 - **Prompts live in Git** as YAML/JSON files
@@ -59,6 +65,50 @@ pytest
 
 ## Quickstart (end‑to‑end)
 
+### End‑user workflow (typical)
+1) Install `instructvault` in your app repo (or a dedicated prompts repo)
+2) Run `ivault init` once to scaffold `prompts/`, `datasets/`, and CI
+3) Add or edit prompt files under `prompts/`
+4) Validate and eval locally (`ivault validate`, `ivault eval`)
+5) Commit prompt changes and create a tag (e.g., `prompts/v1.0.0`)
+6) In your app, render by git ref (tag/branch/SHA) or ship a bundle artifact
+
+### Using InstructVault in an existing app repo
+1) `pip install instructvault`
+2) Create a `prompts/` folder (or pick an existing one)
+3) Add prompt files under `prompts/` and at least one inline test per prompt
+4) Add CI checks (copy from `docs/ci.md` or run `ivault init` to scaffold workflow)
+5) Validate/eval locally: `ivault validate prompts`, `ivault eval prompts/<file>.prompt.yml --report out/report.json`
+6) Commit prompts and optionally tag: `git tag prompts/v1.0.0`
+7) At runtime, load by ref or bundle artifact
+
+### Visual workflow (new app repo)
+```mermaid
+flowchart LR
+  A[Install ivault] --> B[ivault init]
+  B --> C["Add/edit prompts"]
+  C --> D["ivault validate + eval"]
+  D --> E["Commit + tag"]
+  E --> F{Runtime path}
+  F -->|Load by ref| G["InstructVault(repo_root)"]
+  F -->|Bundle artifact| H[ivault bundle]
+  H --> I["InstructVault(bundle_path)"]
+```
+
+### Visual workflow (existing app repo)
+```mermaid
+flowchart LR
+  A[Install instructvault] --> B["Create/choose prompts/ + datasets/"]
+  B --> C["Add/edit prompt files"]
+  C --> D[Add CI checks]
+  D --> E["Local validate + eval"]
+  E --> F["Commit + tag (optional)"]
+  F --> G{Runtime path}
+  G -->|Load by ref| H["InstructVault(repo_root)"]
+  G -->|Bundle artifact| I[ivault bundle]
+  I --> J["InstructVault(bundle_path)"]
+```
+
 ### 1) Initialize a repo
 ```bash
 ivault init
@@ -102,9 +152,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.
+#### 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`
@@ -117,11 +168,10 @@ Use `--policy /path/to/policy.py` to enforce custom compliance rules.
 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.
+#### 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:
+#### Spec migration check:
 ```bash
 ivault migrate prompts
 ```
@@ -145,6 +195,29 @@ msgs = vault.render(
 )
 ```
 
+Troubleshooting: if you pass a `ref` and see `FileNotFoundError` from `store.read_text`,
+the prompt file must exist at that ref and be committed in the same repo. Tags/branches
+must point to commits that include the prompt file.
+
+### Multi‑repo usage (app repo + prompts repo)
+If your prompts live in a separate repo, point `repo_root` to that repo (not your app repo),
+or bundle prompts at build time and ship the bundle with your app.
+```python
+from instructvault import InstructVault
+
+vault = InstructVault(repo_root="/path/to/prompts-repo")
+msgs = vault.render(
+  "prompts/support_reply.prompt.yml",
+  vars={"ticket_text":"My order is delayed"},
+  ref="prompts/v1.0.0",
+)
+```
+
+### Troubleshooting (common)
+- `FileNotFoundError ... read_text` with `ref`: prompt not committed at that ref, or wrong repo_root
+- `No prompt files found`: path passed to `ivault validate` doesn’t contain `*.prompt.yml|json`
+- `prompt must include at least one test`: add a minimal inline test or use `--allow-no-tests` for render
+
 ### 7) Bundle prompts at build time (optional)
 ```bash
 ivault bundle --prompts prompts --out out/ivault.bundle.json --ref prompts/v1.0.0
@@ -163,6 +236,9 @@ 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)
 
+## Examples
+- `examples/ivault_demo_template/README.md`
+
 ## Example Policies
 - `examples/policies/policy_example.py`
 - `examples/policies/policy_pack.py`
@@ -196,17 +272,17 @@ 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`
-- `docs/ci_templates/Jenkinsfile`
+- `docs/dropin_guide.md` — minimal setup if you already have CI
+- `docs/cookbooks.md` — workflows (tags, bundles, multi‑repo, RAG)
+- `docs/spec.md` — prompt spec and validation rules
+- `docs/ci.md` — CI setup and reports
+- `docs/governance.md` — CODEOWNERS and release guardrails
+- `docs/playground.md` — optional local/hosted playground
+- `docs/audit_logging.md` — audit fields and patterns
+- `docs/vision.md` — product vision and guiding principles
+- `docs/release_checklist.md` — release checklist for maintainers
+- `docs/ci_templates/gitlab-ci.yml` — GitLab CI example
+- `docs/ci_templates/Jenkinsfile` — Jenkins example
 - `CHANGELOG.md`
 - `CODE_OF_CONDUCT.md`
 

instructvault-0.3.1/examples/ivault_demo_template/Makefile

@@ -0,0 +1,21 @@
+PY ?= python
+IVAULT ?= ivault
+PROMPT := examples/ivault_demo_template/prompts/support_reply.prompt.yml
+DATASET := examples/ivault_demo_template/datasets/support_cases.jsonl
+REPORT := out/report.json
+
+.PHONY: validate eval render run all
+
+validate:
+	$(IVAULT) validate examples/ivault_demo_template/prompts
+
+eval:
+	$(IVAULT) eval $(PROMPT) --dataset $(DATASET) --report $(REPORT)
+
+render:
+	$(IVAULT) render $(PROMPT) --vars '{"ticket_text":"My app crashed.","customer_name":"Sam"}'
+
+run:
+	$(PY) examples/ivault_demo_template/app.py
+
+all: validate eval render run

instructvault-0.3.1/examples/ivault_demo_template/README.md

@@ -0,0 +1,44 @@
+# InstructVault demo template
+
+Minimal, end-to-end example you can copy into an existing repo.
+
+## Contents
+- `prompts/support_reply.prompt.yml` — sample prompt with inline test
+- `datasets/support_cases.jsonl` — dataset-driven eval rows
+- `app.py` — runtime render example
+
+## Quickstart
+```bash
+# from repo root
+pip install instructvault
+
+# validate + eval
+ivault validate examples/ivault_demo_template/prompts
+ivault eval examples/ivault_demo_template/prompts/support_reply.prompt.yml \
+  --dataset examples/ivault_demo_template/datasets/support_cases.jsonl \
+  --report out/report.json
+
+# render locally
+ivault render examples/ivault_demo_template/prompts/support_reply.prompt.yml \
+  --vars '{"ticket_text":"My app crashed.","customer_name":"Sam"}'
+
+# run runtime example
+python examples/ivault_demo_template/app.py
+```
+
+## Makefile shortcuts
+```bash
+make -C examples/ivault_demo_template all
+```
+
+## Using tags or bundles
+```bash
+# tag prompts
+git add examples/ivault_demo_template/prompts examples/ivault_demo_template/datasets
+git commit -m "add ivault demo prompts"
+git tag prompts/v1.0.0
+
+# bundle
+ivault bundle --prompts examples/ivault_demo_template/prompts \
+  --out out/ivault.bundle.json --ref prompts/v1.0.0
+```

instructvault-0.3.1/examples/ivault_demo_template/app.py

@@ -0,0 +1,12 @@
+from instructvault import InstructVault
+
+vault = InstructVault(repo_root=".")
+msgs = vault.render(
+    "examples/ivault_demo_template/prompts/support_reply.prompt.yml",
+    vars={"ticket_text": "My app crashed.", "customer_name": "Sam"},
+)
+
+for m in msgs:
+    print(m.role)
+    print(m.content)
+    print()

instructvault-0.3.1/examples/ivault_demo_template/datasets/support_cases.jsonl

@@ -0,0 +1,2 @@
+{"vars":{"ticket_text":"Order arrived damaged","customer_name":"Alex"},"assert":{"contains_any":["Ticket:"]}}
+{"vars":{"ticket_text":"Need refund"},"assert":{"contains_all":["Ticket:"]}}

instructvault-0.3.1/examples/ivault_demo_template/prompts/support_reply.prompt.yml

@@ -0,0 +1,27 @@
+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:"]

{instructvault-0.2.9 → instructvault-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "instructvault"
-version = "0.2.9"
+version = "0.3.1"
 description = "Git-first prompt registry + CI evals + lightweight runtime SDK (ivault)."
 readme = "README.md"
 requires-python = ">=3.10"