instructvault 0.2.9__py3-none-any.whl → 0.3.1__py3-none-any.whl

{instructvault-0.2.9.dist-info → instructvault-0.3.1.dist-info}/METADATA

@@ -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.dist-info → instructvault-0.3.1.dist-info}/RECORD

@@ -11,8 +11,8 @@ instructvault/scaffold.py,sha256=f5gwXE3dUPuJYTedZRqBs8w5SQEgt1dgDSuqW2dxrMg,168
 instructvault/sdk.py,sha256=4M3d-KqyuWLcXkaccZjhI-BsBnD4cU_GynkJPJ3ged4,1901
 instructvault/spec.py,sha256=ybv-0rQ4Vqxrj277u7JAVttHQCGmix5zMmtZ4_SN7A8,2639
 instructvault/store.py,sha256=NhN49w7xrkeij0lQDr-CEdANYLpNVBXumv_cKqLmiYY,1056
-instructvault-0.2.9.dist-info/METADATA,sha256=lJ1XnYyS_v06PtARMLaoneXuhi1WhXNUlsp6TajKmEo,7606
-instructvault-0.2.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-instructvault-0.2.9.dist-info/entry_points.txt,sha256=cdcMJQwBk9c95LwfN2W6x2xO43FwPjhfV3jHE7TTuHg,49
-instructvault-0.2.9.dist-info/licenses/LICENSE,sha256=VFbCvIsyizmkz4NrZPMdcPhyRK5uM0HhAjv3GBUbb7Y,135
-instructvault-0.2.9.dist-info/RECORD,,
+instructvault-0.3.1.dist-info/METADATA,sha256=gm-V1pi8a4WrrV4O_Vcxbf3wJ1InN2qQMkUELQrqN9g,11180
+instructvault-0.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+instructvault-0.3.1.dist-info/entry_points.txt,sha256=cdcMJQwBk9c95LwfN2W6x2xO43FwPjhfV3jHE7TTuHg,49
+instructvault-0.3.1.dist-info/licenses/LICENSE,sha256=VFbCvIsyizmkz4NrZPMdcPhyRK5uM0HhAjv3GBUbb7Y,135
+instructvault-0.3.1.dist-info/RECORD,,