instructvault 0.2.0__tar.gz

instructvault-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Report a reproducible issue
+title: "[Bug] "
+labels: bug
+---
+
+## Summary
+What happened?
+
+## Steps to reproduce
+1.
+2.
+3.
+
+## Expected behavior
+
+## Environment
+- OS:
+- Python:
+- InstructVault version:

instructvault-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Suggest an idea
+title: "[Feature] "
+labels: enhancement
+---
+
+## Problem
+What problem are you trying to solve?
+
+## Proposed solution
+
+## Alternatives considered

instructvault-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## Summary
+
+## Changes
+
+## Testing
+```
+pytest
+```

instructvault-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: release
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade pip
+      - run: pip install build twine
+      - run: python -m build
+      - env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*

instructvault-0.2.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-02-01
+### Added
+- Spec versioning (`spec_version`)
+- JSON prompt support
+- Build-time bundling (`ivault bundle`)
+- JSON outputs for CLI commands
+- Cookbooks, drop-in guide, and CI templates
+- Minimal playground scaffold

instructvault-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,20 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+We pledge to make participation in our community a harassment-free experience for everyone.
+
+## Our Standards
+Examples of behavior that contributes to a positive environment include:
+- Being respectful and considerate
+- Accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior include:
+- Harassment or discrimination of any kind
+- Personal attacks or trolling
+
+## Enforcement
+For enforcement issues, contact the project maintainers.
+
+## Attribution
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1.

instructvault-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Thanks for contributing to InstructVault.
+
+## Development setup
+```
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Pull requests
+- Keep changes focused and small
+- Add tests for new behavior
+- Run `pytest` locally
+- Update docs if user-facing behavior changes
+

instructvault-0.2.0/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

instructvault-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,169 @@
+# 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/SECURITY.md

@@ -0,0 +1,6 @@
+# Security
+
+Please report security issues privately by emailing the maintainers.
+
+If you are unsure whether the issue is security-related, open a GitHub issue with minimal details and we will follow up.
+