petfishframework 0.4.0__tar.gz → 0.4.1__tar.gz

{petfishframework-0.4.0 → 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.4.0 → petfishframework-0.4.1}/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.4.0
+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
@@ -39,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: 300](https://img.shields.io/badge/tests-300-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).
 
@@ -192,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
@@ -249,6 +249,22 @@ 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 ✅
@@ -284,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              # 300 tests
+uv run pytest              # 305 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.4.0 → 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: 300](https://img.shields.io/badge/tests-300-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,6 +214,22 @@ 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 ✅
@@ -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              # 300 tests
+uv run pytest              # 305 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.4.0 → 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.0 → 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.4.0. 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