petfishframework 0.3.3__tar.gz → 0.4.1__tar.gz

petfishframework-0.4.1/.sisyphus/plans/v0.4.0-plan.md

@@ -0,0 +1,236 @@
+# petfishFramework v0.4.0 开发计划
+
+> 基于 v0.3.3 状态 + 8 轮用户反馈 + 全部 deferred 项汇总
+> 目标：observability + deterministic replay + 生产化基础
+> 原则：**TDD 先行，pre_release.py 门禁，文档同步作为完成条件**
+
+## v0.4.0 使命
+
+> 让 Agent 运行时可观测（OTel）、可回放（确定性 RERUN/RESUME）、可治理（SIEM export）、可部署（Docker + 部署指南）。
+
+## Deferred 项汇总（从全部反馈中提取）
+
+| 来源 | Deferred 项 | v0.4.0 目标 |
+|---|---|---|
+| v0.3.0 §9.2 | deterministic rerun / resume | ✅ 实现 |
+| v0.3.0 §9.2 | MCP server mode | ⏳ v0.5.0（需完整 MCP server 实现） |
+| v0.3.0 §9.2 | deployment guide | ✅ Dockerfile + 部署文档 |
+| v0.3.0 §9.2 | OpenTelemetry | ✅ OTelSink |
+| v0.3.0 §9.2 | SIEM export | ✅ JSON-Lines trace export |
+| v0.3.0 §P2 | Vault adapter | ✅ HashiCorp Vault adapter (可选) |
+| v0.3.0 §P2 | threat model | ✅ 威胁模型文档 |
+| v0.3.0 §P2 | SBOM | ✅ cyclonedx 生成 |
+| v0.3.0 §P2 | signed release | ✅ sigstore cosign |
+| 多轮 | README Current Limitations 中 planned 项 | 清理为 available |
+
+---
+
+## Phase A: Deterministic Replay (RESUME + RERUN)
+
+### A1: RESUME — 检查点恢复
+
+**目标**：从检查点恢复执行，重注入已记录的模型响应直到检查点，之后继续新鲜调用。
+
+#### TDD 测试先行
+
+```python
+# tests/test_replay_resume.py
+
+def test_resume_replays_recorded_prefix():
+    """RESUME: 重注入检查点前的模型响应。"""
+
+def test_resume_continues_with_fresh_calls():
+    """RESUME: 检查点后用 live environment 新鲜调用。"""
+
+def test_resume_from_mid_session():
+    """RESUME: 从 Session 中间的检查点恢复。"""
+```
+
+#### 实现
+
+- `ResumableEnvironment`（已有 v0.1.x 基础）增强：
+  - `checkpoint_model_idx` / `checkpoint_tool_idx` 参数
+  - 检查点前用 `recording.model_responses[i]` 重注入
+  - 检查点后切换到 `live_env`
+- `Session.checkpoint()` 发出 `session.checkpoint` 事件 + 记录当前 model/tool 索引
+- `Session.resume_from(checkpoint_data)` 工厂方法
+
+### A2: RERUN — 确定性完整重放 + 偏离检测
+
+**目标**：完整重放一个 Session 的所有调用，验证轨迹一致。偏离时报告差异。
+
+#### TDD 测试先行
+
+```python
+# tests/test_replay_rerun.py
+
+def test_rerun_reproduces_identical_trajectory():
+    """RERUN: 完整重放，轨迹完全一致。"""
+
+def test_rerun_detects_model_call_count_divergence():
+    """RERUN: 模型调用次数不一致 → 报告偏离。"""
+
+def test_rerun_detects_tool_result_divergence():
+    """RERUN: 工具结果不一致 → 报告偏离。"""
+```
+
+#### 实现
+
+- `RerunEnvironment`：封装 `RecordingEnvironment` + `ReplayEnvironment`
+  - `rerun() -> RerunResult`：重放 + 比对
+  - `RerunResult.matches: bool` + `divergences: list[str]`
+  - 检测：调用次数偏离、工具名偏离、结果值偏离
+
+---
+
+## Phase B: Observability
+
+### B1: OpenTelemetry Sink
+
+**目标**：Session 事件 → OTel spans，可接入 Jaeger/Zipkin/DataDog。
+
+#### TDD 测试先行
+
+```python
+# tests/test_otel_sink.py
+
+def test_otel_sink_creates_span_per_tool_call():
+    """每个 tool.called 事件创建一个 span。"""
+
+def test_otel_sink_creates_span_per_model_call():
+    """每个 model.called 事件创建一个 span。"""
+
+def test_otel_sink_nests_tool_spans_under_session():
+    """工具 span 嵌套在 session trace 下。"""
+```
+
+#### 实现
+
+- `observability/otel_sink.py` — `OTelSink`:
+  - 接收 EventEmitter 事件
+  - Session → OTel Trace
+  - model.called → span (attributes: model name, tokens, cost)
+  - tool.called/blocked/masked → span (attributes: tool name, effect, duration)
+  - 使用 `opentelemetry-api`（可选依赖：`pip install petfishframework[otel]`）
+  - 无 OTel 安装时降级为 no-op
+
+### B2: SIEM Export (JSON-Lines Trace)
+
+**目标**：结构化事件导出，可导入 Splunk/Elastic/Datadog。
+
+#### TDD 测试先行
+
+```python
+# tests/test_siem_export.py
+
+def test_siem_export_produces_jsonlines():
+    """导出为 JSON-Lines 格式。"""
+
+def test_siem_export_redacts_credentials():
+    """导出中不含 secret。"""
+
+def test_siem_export_includes_policy_version():
+    """每条记录包含 policy_version。"""
+```
+
+#### 实现
+
+- `observability/siem_sink.py` — `SIEMSink`:
+  - 接收事件 → 写入 JSON-Lines 文件/流
+  - 每行：`{"timestamp", "session_id", "event_type", "tool_name", "effect", "executed", "policy_version", "duration_ms"}`
+  - 自动脱敏（复用 event_mask 逻辑）
+
+---
+
+## Phase C: Production Foundation
+
+### C1: Vault Adapter
+
+**目标**：CredentialBroker 支持 HashiCorp Vault 作为 secret 后端。
+
+#### TDD 测试先行
+
+```python
+# tests/test_vault_adapter.py
+
+def test_vault_adapter_reads_secret():
+    """Vault adapter 从 Vault 读取 secret。"""
+    # 使用 mock，不连真实 Vault
+
+def test_vault_adapter_caches_locally():
+    """读取后缓存，减少 Vault 调用。"""
+```
+
+#### 实现
+
+- `credentials/vault_adapter.py` — `VaultCredentialSource`:
+  - `read_secret(path: str) -> str` — 从 Vault 读取
+  - 可选依赖：`hvac` library
+  - 集成到 `CredentialBroker.register_credential_from_vault(path)`
+
+### C2: Dockerfile + 部署指南
+
+**文件**：
+- `Dockerfile` — 多阶段构建
+- `docker-compose.yml` — 开发环境
+- `docs/deployment.md` — 部署指南
+
+### C3: SBOM + Signed Release
+
+- `.github/workflows/publish.yml` 增强：
+  - 生成 SBOM (cyclonedx)
+  - cosign 签名
+- `docs/threat-model.md` — 威胁模型
+
+### C4: 文档 + README 更新
+
+- api.md: 新增 OTel + SIEM + Vault + Replay 章节
+- README: Current Limitations 清理（deterministic replay: Available; OTel: Available）
+- CHANGELOG: v0.4.0
+
+---
+
+## 执行顺序与依赖
+
+```
+A1 (RESUME) → A2 (RERUN)
+    ↓
+B1 (OTel) → B2 (SIEM)
+    ↓
+C1 (Vault) → C2 (Docker) → C3 (SBOM) → C4 (docs)
+```
+
+## 验收标准
+
+| # | 标准 | 验证方法 |
+|---|---|---|
+| V1 | RESUME 从检查点恢复执行 | `test_replay_resume.py` |
+| V2 | RERUN 完整重放 + 偏离检测 | `test_replay_rerun.py` |
+| V3 | OTel sink 生成 spans | `test_otel_sink.py` |
+| V4 | SIEM 导出 JSON-Lines + 脱敏 | `test_siem_export.py` |
+| V5 | Vault adapter 读取 secret（mock） | `test_vault_adapter.py` |
+| V6 | Dockerfile 可构建 | `docker build .` |
+| V7 | SBOM 生成 | CI workflow |
+| V8 | pre_release.py exit 0 | `python scripts/pre_release.py 0.4.0` |
+| V9 | 所有 284+ 现有测试通过 | pytest |
+| V10 | ruff clean | ruff check |
+| V11 | README Current Limitations 清理 | grep "Planned" |
+
+## 不做清单（v0.5.0+）
+
+- ❌ MCP server mode
+- ❌ MCP governance (allowlist, rate limit)
+- ❌ Tool sandbox (subprocess isolation)
+- ❌ Policy hot-reload
+- ❌ Multi-tenant policy namespace
+
+## 新测试预估
+
+| Phase | 测试数 |
+|---|---|
+| A1 RESUME | 3 |
+| A2 RERUN | 3 |
+| B1 OTel | 3 |
+| B2 SIEM | 3 |
+| C1 Vault | 2 |
+| **总计** | **~14 新测试** |

{petfishframework-0.3.3 → petfishframework-0.4.1}/AGENTS.md

@@ -63,6 +63,10 @@ tasks/      任务与 backlog
 规则：每条必须是"违反会导致 bug，且代码本身无法自解释"的约束；上限 10 条。
 -->
 
+1. **Release 版本号 grep checklist** — 每次发布前必须 grep 旧版本号。`SECURITY.md` 的 Supported Versions 表是版本敏感文件，但 `pre_release.py` 不检查它。发布前手动执行 `grep -rn "0\.[0-9]\+\.x" SECURITY.md` 确认当前版本。遗漏会导致外部安全审计认为项目维护停滞。
+2. **新模块必须同步 `__init__.py` 导出** — 新增 `src/petfishframework/<module>/<sub>.py` 时，必须同时在 `<module>/__init__.py` 的 `__all__` 和 import 中添加导出。否则用户无法从包顶层导入，只能走子模块路径，违反 Python 包惯例。OTelSink/SIEMSink 在 v0.4.0 发布时遗漏了此步骤。
+3. **Docker ENTRYPOINT 必须有对应的 `__main__.py`** — Dockerfile 中 `ENTRYPOINT ["python", "-m", "petfishframework"]` 要求 `src/petfishframework/__main__.py` 存在且 `main()` 返回 int 退出码。没有 `__main__.py` 时容器启动直接 crash，且 CI 不构建 Docker 所以不会发现。
+
 ## Architecture Decisions
 
 <!-- 重大技术选型和设计决策的简要记录（一句话结论 + 指向 docs/ 下完整 ADR 的链接）。 -->

{petfishframework-0.3.3 → petfishframework-0.4.1}/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [0.4.1] — 2026-07-08
+
+### Review Fix Patch
+
+#### Security & Version Hygiene
+- `SECURITY.md` Supported Versions updated from `0.2.x` to `0.4.x` active + `0.3.x` security fixes only
+- `AGENTS.md` Development Gotchas filled with 3 prevention rules (version grep, `__init__.py` export, Docker entrypoint)
+
+#### Observability API
+- `observability/__init__.py` now exports `OTelSink` and `SIEMSink` (previously required submodule import)
+- Updated docstring to reflect actual available sinks
+
+#### SIEMSink Enhanced Redaction
+- New `redact_keys` parameter: `SIEMSink(redact_keys=("api_key", "password", ...))`
+- Default redaction: `api_key`, `secret`, `password`, `token`, `authorization`, `cookie`
+- Nested dict key matching (e.g. `connection.password` in `details.redacted_fields`)
+- 3 new TDD tests: default keys, nested keys, custom keys
+
+#### Docker Entrypoint Fix
+- Created `src/petfishframework/__main__.py` — `python -m petfishframework` now works
+- Docker container `ENTRYPOINT` no longer crashes on start
+- 2 new TDD tests verifying exit code and output
+
+#### README
+- Core Concepts table: "RERUN + RESUME planned" → available
+- Added Observability (OTel + SIEM) section with code example
+- Test count badge updated to 305
+
+## [0.4.0] — 2026-07-08
+
+### v0.4.0 Production Foundation
+
+#### Phase A+B: Deterministic Replay + Observability
+- Deterministic replay infrastructure (`petfishframework.reliability.replay`):
+  - `RecordingEnvironment` captures every model response, tool call, and retrieval
+  - `ReplayEnvironment` replays recorded calls for deterministic audit
+  - `ResumableEnvironment` replays prefix then switches to live execution
+  - `ReplayMode.AUDIT`, `RESUME`, `RERUN` semantics
+- OpenTelemetry sink (`OTelSink`) — creates spans for model/tool/session events
+- SIEM export (`SIEMSink`) — structured JSON audit events for downstream SIEMs
+
+#### Phase C: Vault Adapter + Deployment + Threat Model
+- `VaultCredentialSource` — reads secrets from HashiCorp Vault with lazy `hvac` import
+- `CredentialBroker.register_credential_from_vault(name, source, path)` — register
+  credentials fetched from Vault
+- Optional dependency group `vault = ["hvac>=1.0"]`
+- `Dockerfile` and `docker-compose.yml` for containerized deployment
+- `docs/deployment.md` — Docker deployment guide, environment variables, volume mounts,
+  credential-broker integration, and security notes
+- `docs/threat-model.md` — attack surface, trust boundaries, threats, mitigations,
+  and fail-closed defaults
+
+#### Documentation Sync
+- `docs/api.md` updated to v0.4.0
+- README: deterministic replay and OTel marked available, roadmap bumped to v0.4.x
+- Test count badge updated to 300
+
 ## [0.3.2] — 2026-07-08
 
 ### YAML Policy DSL Expansion

petfishframework-0.4.1/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN pip install uv && uv sync --no-dev
+COPY src/ src/
+RUN uv pip install --system .
+ENTRYPOINT ["python", "-m", "petfishframework"]

{petfishframework-0.3.3 → petfishframework-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.3.3
+Version: 0.4.1
 Summary: A lightweight runtime framework for reliable, auditable, budget-aware, and permission-aware AI agents.
 Project-URL: Homepage, https://github.com/kylecui/petfishFramework
 Project-URL: Documentation, https://github.com/kylecui/petfishFramework/tree/master/docs
@@ -26,6 +26,11 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == 'mcp'
 Provides-Extra: openai
 Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: vault
+Requires-Dist: hvac>=1.0; extra == 'vault'
 Description-Content-Type: text/markdown
 
 # petfishFramework
@@ -34,7 +39,7 @@ Description-Content-Type: text/markdown
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 284](https://img.shields.io/badge/tests-284-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 305](https://img.shields.io/badge/tests-305-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -187,7 +192,7 @@ print(result.summary())
 | **Environment** | Single chokepoint (all calls audited, budget-metered, permission-gated) |
 | **Budget** | Hard execution limits (tokens, cost, steps, tool calls) |
 | **Permission** | SARC access control with 6 DecisionEffects |
-| **Replay** | AUDIT event log available; RERUN + RESUME planned |
+| **Replay** | AUDIT event log via `session.replay()`; RERUN + RESUME via `reliability.replay` wrappers |
 | **Pass^k** | Reliability metric (k repetitions + perturbation suite) |
 
 ## Features
@@ -244,11 +249,27 @@ agent = Agent(model=model, reasoning=ReAct(), tools=tools, credential_broker=bro
 # Tools with requires_credentials=True receive a ScopedToken (repr-safe, auto-expiring)
 ```
 
+## Observability (OTel + SIEM)
+
+```python
+from petfishframework.observability import OTelSink, SIEMSink
+
+# OTel — creates spans for model/tool/session events (requires opentelemetry)
+otel_sink = OTelSink()  # no-op if opentelemetry not installed
+
+# SIEM — structured JSON-Lines export for downstream SIEM ingestion
+siem_sink = SIEMSink(output_path="audit.jsonl")
+# Credentials auto-redacted; configure additional secret fields:
+# siem_sink = SIEMSink(output_path="audit.jsonl", redact_keys=("api_key", "password"))
+
+agent = Agent(model=model, reasoning=ReAct(), tools=tools, event_sinks=(otel_sink, siem_sink))
+```
+
 ## Roadmap
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
-- **v0.3.x** (current): YAML Policy Engine, CredentialBroker ✅
-- **v0.4.x**: Production hardening, deployment guides
+- **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
+- **v0.4.x** (current): Production hardening, deployment guides, Vault adapter, Docker, threat model ✅
 
 ## Current Limitations
 
@@ -263,8 +284,8 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | PARTIAL_ALLOW | ✅ Enforced (pre-execution arg filtering) |
 | MASK | ✅ Enforced (input mask before + output mask after) |
 | DEGRADE | ✅ Enforced (fallback tool switching) |
-| Session replay | ✅ Audit replay available |
-| Deterministic rerun / resume | 📋 Planned |
+| Session replay / deterministic rerun / resume | ✅ Available |
+| OpenTelemetry + SIEM observability | ✅ Available |
 | MCP client stdio | ✅ Available |
 | MCP server mode | 📋 Planned |
 | Structured output / conversation memory | ✅ Available |
@@ -279,7 +300,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 284 tests
+uv run pytest              # 305 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.3.3 → petfishframework-0.4.1}/README.md

@@ -4,7 +4,7 @@
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 284](https://img.shields.io/badge/tests-284-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 305](https://img.shields.io/badge/tests-305-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -157,7 +157,7 @@ print(result.summary())
 | **Environment** | Single chokepoint (all calls audited, budget-metered, permission-gated) |
 | **Budget** | Hard execution limits (tokens, cost, steps, tool calls) |
 | **Permission** | SARC access control with 6 DecisionEffects |
-| **Replay** | AUDIT event log available; RERUN + RESUME planned |
+| **Replay** | AUDIT event log via `session.replay()`; RERUN + RESUME via `reliability.replay` wrappers |
 | **Pass^k** | Reliability metric (k repetitions + perturbation suite) |
 
 ## Features
@@ -214,11 +214,27 @@ agent = Agent(model=model, reasoning=ReAct(), tools=tools, credential_broker=bro
 # Tools with requires_credentials=True receive a ScopedToken (repr-safe, auto-expiring)
 ```
 
+## Observability (OTel + SIEM)
+
+```python
+from petfishframework.observability import OTelSink, SIEMSink
+
+# OTel — creates spans for model/tool/session events (requires opentelemetry)
+otel_sink = OTelSink()  # no-op if opentelemetry not installed
+
+# SIEM — structured JSON-Lines export for downstream SIEM ingestion
+siem_sink = SIEMSink(output_path="audit.jsonl")
+# Credentials auto-redacted; configure additional secret fields:
+# siem_sink = SIEMSink(output_path="audit.jsonl", redact_keys=("api_key", "password"))
+
+agent = Agent(model=model, reasoning=ReAct(), tools=tools, event_sinks=(otel_sink, siem_sink))
+```
+
 ## Roadmap
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
-- **v0.3.x** (current): YAML Policy Engine, CredentialBroker ✅
-- **v0.4.x**: Production hardening, deployment guides
+- **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
+- **v0.4.x** (current): Production hardening, deployment guides, Vault adapter, Docker, threat model ✅
 
 ## Current Limitations
 
@@ -233,8 +249,8 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | PARTIAL_ALLOW | ✅ Enforced (pre-execution arg filtering) |
 | MASK | ✅ Enforced (input mask before + output mask after) |
 | DEGRADE | ✅ Enforced (fallback tool switching) |
-| Session replay | ✅ Audit replay available |
-| Deterministic rerun / resume | 📋 Planned |
+| Session replay / deterministic rerun / resume | ✅ Available |
+| OpenTelemetry + SIEM observability | ✅ Available |
 | MCP client stdio | ✅ Available |
 | MCP server mode | 📋 Planned |
 | Structured output / conversation memory | ✅ Available |
@@ -249,7 +265,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 284 tests
+uv run pytest              # 305 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.3.3 → petfishframework-0.4.1}/SECURITY.md

@@ -2,10 +2,11 @@
 
 ## Supported Versions
 
-| Version | Supported          |
-|---------|--------------------|
-| 0.2.x   | ✅ Active development |
-| < 0.2   | ❌ Not supported      |
+| Version | Supported              |
+|---------|------------------------|
+| 0.4.x   | ✅ Active development   |
+| 0.3.x   | ⚠️ Security fixes only  |
+| < 0.3   | ❌ Not supported         |
 
 ## Reporting a Vulnerability
 

petfishframework-0.4.1/docker-compose.yml

@@ -0,0 +1,8 @@
+version: "3.9"
+services:
+  agent:
+    build: .
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+    volumes:
+      - ./examples:/app/examples

{petfishframework-0.3.3 → petfishframework-0.4.1}/docs/api.md

@@ -1,6 +1,6 @@
 # petfishFramework API Reference
 
-This document is the authoritative reference for the public API of `petfishFramework` v0.3.2. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
+This document is the authoritative reference for the public API of petfishFramework v0.4.1. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
 
 ## 1. Overview
 
@@ -1445,3 +1445,27 @@ token.get_secret()  # raises ValueError("max uses exceeded")
 if session.credential_broker:
     session.credential_broker.cleanup_expired()
 ```
+
+### Vault Integration (v0.4.0)
+
+```python
+from petfishframework.credentials import CredentialBroker, VaultCredentialSource
+
+broker = CredentialBroker()
+source = VaultCredentialSource(
+    vault_url="https://vault.example.com",
+    token="hvs.CAES...",
+)
+broker.register_credential_from_vault("openai", source, path="secrets/openai")
+```
+
+`VaultCredentialSource` performs a lazy import of `hvac` and raises a clear
+`ImportError` if the optional dependency is missing. The secret is read once and
+cached locally for the lifetime of the source; subsequent reads of the same
+path do not call Vault again.
+
+Install the optional dependency with:
+
+```bash
+pip install petfishframework[vault]
+```