petfishframework 0.5.2__tar.gz → 1.0.1__tar.gz

{petfishframework-0.5.2 → petfishframework-1.0.1}/.github/workflows/ci.yml

@@ -5,6 +5,9 @@ on:
     branches: [master, main]
   pull_request:
     branches: [master, main]
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
 
 jobs:
   test:
@@ -28,9 +31,32 @@ jobs:
       - name: Lint with ruff
         run: uv run ruff check src/ tests/
 
+      - name: Type check
+        run: uv run mypy src/petfishframework
+
       - name: Run tests
-        run: uv run pytest tests/ -q --tb=short
-        # Integration tests are skipped automatically (no API key in CI)
+        run: uv run pytest tests/ -q --tb=short -m "not integration"
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install uv && uv sync --all-extras
+
+      - name: Run integration tests
+        run: uv run pytest tests/ -m integration -v --tb=short
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 
   docker-smoke:
     runs-on: ubuntu-latest

petfishframework-1.0.1/.sisyphus/plans/v1.0.0-plan.md

@@ -0,0 +1,211 @@
+# petfishFramework v1.0.0 Production-Readiness Plan
+
+> Target: ship v1.0.0 with all 14 audit gaps closed.
+> Baseline: v0.5.2, 382 tests, ruff clean, Python ≥3.10.
+> Approach: TDD先行，pre_release.py门禁，每gap一个atomic commit。
+
+## 设计决策（已确认）
+
+| ID | 决策 | 选择 |
+|---|---|---|
+| D1 | 公开API surface | 导出全部Stable API到`__init__.__all__`；promote FrameworkConfig到Stable |
+| D2 | 线程安全范围 | EventEmitter/RateLimiter/IdempotencyStore + RuntimeEnvironment计数器加锁；Session保持单线程设计 |
+| D3 | 异常层级 | ToolExecutionError → ToolSchemaError/ToolTimeoutError/ToolRateLimitError/ToolRetryExhaustedError/ToolInternalError；sanitized messages |
+| D4 | RuntimeEnvironment重构 | 提取`_build_execution_plan`共享执行计划，消除sync/async重复，修复gate ordering bug |
+| Q1 | FrameworkConfig tier | Promote to Stable（config surface小，B1验证后可冻结） |
+| Q2 | mypy backlog | Fix便宜的错误，>15个非trivial error记为P2 follow-up，不阻塞v1.0 |
+| Q3 | Coverage gate | v1.0 informational only，v1.1起hard gate（fail_under=80%） |
+| Q4 | Temperature range | 0 ≤ temp ≤ 2 |
+
+## 14个Gap验证状态
+
+全部14项已通过源码阅读确认。附发现：
+
+- **B1 — 隐性正确性bug（Gap 14的一部分）**：`call()` sync路径gate顺序 schema→idempotency→rate_limit；`call_async()` 是 schema→rate_limit→idempotency。Async路径让idempotency cache hit消耗rate-limit quota。D4重构修复。
+- **B2 — badge drift**：pytest收集385，README badge写382。
+
+| # | Gap | Severity | 主要文件 | 验证位置 |
+|---|---|---|---|---|
+| 1 | 公开API导出不匹配 | P0 | `__init__.py`, `api-stability.md` | 15 exports vs 30+ Stable |
+| 2 | 线程安全 | P0 | `events.py`, `rate_limiter.py`, `idempotency.py`, `environment.py` | 无`threading.Lock` |
+| 3 | 异常泄漏 | P0 | `environment.py:296,478`, `base.py:73`, `wrapper.py:41`, `sandbox.py:50`, `server.py:102` | `str(exc)`→ToolResult |
+| 4 | FrameworkConfig无校验 | P0 | `config.py` | 无`__post_init__` |
+| 5 | 无覆盖率工具 | P0 | `pyproject.toml` | 无`pytest-cov` |
+| 6 | SECURITY.md过期 | P0 | `SECURITY.md` | 0.5.x missing |
+| 7 | Dockerfile非生产级 | P0 | `Dockerfile` | root, no HEALTHCHECK |
+| 8 | CredentialBroker安全 | P1 | `token.py:19`, `broker.py:64-69` | `_secret`可读, max_uses未强制 |
+| 9 | 可选依赖无上限 | P1 | `pyproject.toml:49-53` | `>=` only |
+| 10 | 集成测试CI跳过 | P1 | `ci.yml`, `tests/integration/*` | 无API key |
+| 11 | mypy未强制 | P1 | `ci.yml` | 无mypy step |
+| 12 | EventEmitter吞sink异常 | P1 | `events.py:57-61` | `except Exception: pass` |
+| 13 | api-stability.md过时 | P1 | `api-stability.md` | serve_as_mcp/FrameworkConfig mismatch |
+| 14 | RuntimeEnvironment 711行 | P1 | `environment.py:127-497` | call=190, call_async=180, gate-order bug |
+
+## 依赖图
+
+```
+Gap 5 (coverage)  ──────────────────────────────► (enables measurement)
+Gap 1 (API surface) ──► Gap 13 (api-stability doc)
+                        Gap 6 (SECURITY)      ─┐
+                        Gap 9 (dep bounds)     ├─ independent
+                        Gap 4 (config valid.)  ┘
+Gap 8 (credentials) ──────────────────────────►  independent
+Gap 12 (sink swallow) ─► pairs with Gap 2 (events.py)
+Gap 2 (thread safety):
+    standalone (events/rate_limiter/idempotency) ─► independent
+    environment.py portion ─► merge into Gap 14
+Gap 3 (exception hierarchy) ──► Gap 14 (refactor consumes new errors)
+Gap 7 (Dockerfile), Gap 10 (CI), Gap 11 (mypy) ─► infra, fully independent
+```
+
+## Phase分解（6个Wave）
+
+### Wave A — Foundation（2项，并行）
+- **A1 = Gap 5** — 覆盖率工具
+- **A2 = Gap 1** — 公开API surface冻结
+
+### Wave B — Quick/config修复（5项，并行；B5在A2后）
+- **B1 = Gap 4** — FrameworkConfig验证器
+- **B2 = Gap 9** — 依赖上限
+- **B3 = Gap 6** — SECURITY.md
+- **B4 = Gap 8** — CredentialBroker加固
+- **B5 = Gap 13** — api-stability.md（A2后）
+
+### Wave C — 错误处理（2项，并行不同文件）
+- **C1 = Gap 3** — ToolExecutionError层级（新`errors.py` + 更新5个call site）
+- **C2 = Gap 12 + Gap 2(events/rate_limiter/idempotency)** — sink-failure上报 + 独立锁
+
+### Wave D — Environment整合（1项，C1后串行）
+- **D1 = Gap 2(env) + Gap 14** — RuntimeEnvironment锁 + `_build_execution_plan`重构 + gate order修复
+
+### Wave E — 基础设施（3项，并行）
+- **E1 = Gap 7** — Dockerfile加固
+- **E2 = Gap 10** — 集成测试CI
+- **E3 = Gap 11** — mypy强制
+
+### Wave F — 发布
+- 版本号、CHANGELOG、badge、pre_release.py加固、tag
+
+## Per-Gap TDD测试规范
+
+### A1 / Gap 5 — 覆盖率工具
+- `tests/test_coverage_config.py`：pytest-cov可导入；`[tool.coverage.run]` source=pkg；覆盖率>0%。
+- v1.0 informational，不hard fail。
+
+### A2 / Gap 1 — API surface冻结
+- 硬化`tests/test_api_public_surface.py`：skip→assert；扩展TIER1_NAMES到完整frozen set。
+- 新增`test_all_exports_in___all__`：`__all__`与实际importable一致。
+- 新增`test_no_unstable_symbols_in_top_level`：top-level不含Experimental/Internal。
+- **D1 frozen set（`__all__`）**：当前15个 + Session, RuntimeEnvironment, EventEmitter, Event, Step, Trajectory, Usage, PermissionPolicy, DefaultAllowPolicy, DenyByDefaultPolicy, Subject, Action, Resource, AccessContext, Decision, CredentialBroker, ScopedToken, pass_at_k, audit_report_from_session, AuditReport, Calculator, WordSorter, FakeModel, tool（decorator）。promote FrameworkConfig到Stable。
+
+### B1 / Gap 4 — FrameworkConfig验证
+- `tests/test_config_validation.py`：
+  - `timeout_s <= 0` → ValueError
+  - `default_temperature < 0 or > 2` → ValueError
+  - `default_max_tokens < 0` → ValueError；None OK
+  - `from_dict` invalid → raises
+  - valid defaults → 不回归
+
+### B2 / Gap 9 — 依赖上限
+- `tests/test_dependency_bounds.py`：解析pyproject.toml，每个optional dep有`>=X,<Y`格式。
+- upper bound pin到当前known-good major：openai<2, anthropic<1, mcp<2。
+
+### B3 / Gap 6 — SECURITY.md
+- `tests/test_security_doc.py`：当前版本在Supported Versions表中标Active；至少一行security-only。
+
+### B4 / Gap 8 — CredentialBroker
+- `_secret`改为`__secret`（name-mangled），`get_secret()`为唯一读取入口。
+- `validate_token`调用`token.use()`强制max_uses。
+- 测试：`token._secret`→AttributeError；max_uses=1的token第二次validate→False；repr不含secret。
+
+### B5 / Gap 13 — api-stability.md
+- `tests/test_api_stability_doc.py`：top-level `__all__`与api-stability.md分类一致；serve_as_mcp非Internal；effective version=v1.0。
+
+### C1 / Gap 3 — 异常层级
+- `tests/test_tool_execution_errors.py`：
+  - 5个ToolExecutionError子类正确继承
+  - tool抛ValueError→ToolResult.is_error=True，message=sanitized（不含原始exception文本）
+  - schema violation→safe descriptive message
+  - timeout→ToolTimeoutError message含tool name+timeout值
+  - KeyboardInterrupt/SystemExit/AssertionError→propagate（不被catch）
+
+### C2 / Gap 12 + Gap 2(non-env)
+- `tests/test_event_emitter.py`：
+  - failing sink→emit `sink.error`事件（不静默pass）
+  - 其他sink仍收到event
+  - 2线程并发emit+subscribe→无RuntimeError/丢失
+- `tests/test_rate_limiter.py`/`test_tool_idempotency.py`：并发访问测试
+
+### D1 / Gap 2(env) + Gap 14
+- `tests/test_environment_refactor.py`：
+  - **Gate order parity test**：sync和async路径idempotency cache hit不消耗rate-limit quota
+  - `_build_execution_plan`返回callable，所有effect正确执行
+  - 并发`query_model`计数一致
+  - 全部现有env测试不回归
+- 重构：提取`_build_execution_plan(tool, args, decision)→Callable`，统一gate顺序 schema→idempotency→rate_limit→mask→execute→cache→mask_out。
+
+### E1 / Gap 7 — Dockerfile
+- `tests/test_dockerfile.py`（static parse）：USER non-root, HEALTHCHECK, STOPSIGNAL SIGTERM, base pinned。
+
+### E2 / Gap 10 — 集成测试CI
+- `ci.yml`：default job显式`-m "not integration"`；新增scheduled `workflow_dispatch` integration job。
+- `tests/test_ci_markers.py`：所有integration test有`@pytest.mark.integration`。
+
+### E3 / Gap 11 — mypy
+- `tests/test_mypy_clean.py`：subprocess运行mypy，exit 0。
+- 修复现有mypy错误（>15个非trivial→记为P2 follow-up）。
+- 不允许新增`# type: ignore`。
+
+## 风险评估
+
+| 风险 | 概率 | 影响 | 缓解 |
+|---|---|---|---|
+| D1重构破坏env测试 | 高 | 高 | Gate-order parity test先行；每步跑全suite |
+| C1 sanitized message破坏现有测试 | 高 | 中 | 预先grep `str(exc)`/`error=.*exc`，同commit更新 |
+| A2 export扩展导致import cycle | 中 | 中 | 增量添加；test_all_exports捕获ImportError |
+| B4 `_secret`锁定破坏issue_token | 中 | 中 | classmethod构造；测试construction path |
+| E3 mypy暴露大量错误 | 中 | 低 | 时间盒；>15个记为P2 |
+| 锁竞争/deadlock | 低 | 中 | 非重入Lock；不在tool.execute()期间持有 |
+
+## Scope边界（明确不做）
+
+- ❌ 多线程Session（Session保持单线程设计）
+- ❌ 提升Experimental API到Stable（除FrameworkConfig）
+- ❌ 性能优化（仅correctness）
+- ❌ 改变Tool/ToolResult协议
+- ❌ 移除现有公开符号（纯增量）
+- ❌ strict mypy（仅enforce现有config到0错误）
+- ❌ 新功能（新策略/sink/RAG backend）
+- ❌ 重写api.md（仅version line + api-stability.md修正）
+
+## Commit策略
+
+每gap一个green commit（tests+impl一起），branch off master at 5e264ca。
+
+| Commit | Wave | Gap(s) |
+|---|---|---|
+| `test+feat: add coverage tooling` | A | 5 |
+| `test+feat: freeze public API surface` | A | 1 |
+| `test+feat: validate FrameworkConfig` | B | 4 |
+| `chore: pin optional dependency upper bounds` | B | 9 |
+| `docs: refresh SECURITY.md supported versions` | B | 6 |
+| `test+feat: harden CredentialBroker/ScopedToken` | B | 8 |
+| `docs: align api-stability.md with frozen surface` | B | 13 |
+| `test+feat: ToolExecutionError hierarchy` | C | 3 |
+| `test+feat: lock EventEmitter/RateLimiter/Idempotency; report sink errors` | C | 2,12 |
+| `test+refactor: RuntimeEnvironment execution plan + locks + gate-order fix` | D | 2(env),14 |
+| `build: production-harden Dockerfile` | E | 7 |
+| `ci: explicit integration-test gating + scheduled job` | E | 10 |
+| `test+chore: enforce mypy in CI` | E | 11 |
+| `release: v1.0.0` | F | — |
+
+## 发布门禁
+
+1. `uv run pytest` → all green
+2. `uv run ruff check src/ tests/ examples/` → clean
+3. `uv run mypy src/petfishframework` → exit 0
+4. `uv run pytest --cov=petfishframework` → report produced（informational）
+5. `python scripts/pre_release.py 1.0.0` → exit 0
+6. Docker build + smoke（SIGTERM graceful exit）
+7. api-stability.md ↔ __init__.py cross-check green
+8. `from petfishframework import Session, RuntimeEnvironment, EventEmitter, CredentialBroker` → 成功

{petfishframework-0.5.2 → petfishframework-1.0.1}/CHANGELOG.md

@@ -2,6 +2,97 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [1.0.1] — 2026-07-09
+
+### Product Contract Fix
+
+#### Status Consistency
+- PyPI classifier: `3 - Alpha` → `5 - Production/Stable`
+- README: "Status: Alpha — API may change" → "Status: v1.0 Stable"
+- README: "petfishFramework is Alpha. API may change before v1.0" → stable core messaging
+- Roadmap: typo fixed, version descriptions cleaned
+
+#### Product Narrative
+- README intro: "lightweight Python framework" → "runtime control framework for enterprise AI agents"
+- Product positioning: governance, policy enforcement, audit, credential isolation — not generic orchestration
+
+#### API Stability Documentation
+- New Stable/Experimental status table in README (18 capability areas classified)
+- `docs/api-stability.md` expanded: Semantic Versioning policy, Breaking Change policy, Security Fix policy
+- Clear Stable vs Experimental boundary documented
+
+#### Adoption Guide
+- New `docs/adoption-guide.md`: When to use/not use, 4 integration patterns, Enterprise PoC checklist, Runtime security checklist, Migration from prototype Agent
+
+## [1.0.0] — 2026-07-09
+
+### Production Release — API Stability Freeze
+
+#### API Surface Frozen (Gap 1)
+- Top-level `petfishframework.__all__` expanded from 15 to 40+ Stable exports
+- `Session`, `RuntimeEnvironment`, `EventEmitter`, `CredentialBroker`, `ScopedToken`, `Calculator`, `WordSorter`, `FakeModel`, `pass_at_k`, `audit_report_from_session`, and all SARC types now importable from top level
+- `test_api_public_surface.py` hardened: strict assert (no skip), `__all__` consistency check
+
+#### Thread Safety (Gap 2)
+- `threading.Lock` added to `EventEmitter`, `RateLimiter`, `IdempotencyStore`
+- `RuntimeEnvironment` internal counters (`_model_calls`, `_accountant`) locked
+- Session documented as single-threaded by design
+- Concurrent stress tests verify no lost events/corruption
+
+#### Exception Sanitization (Gap 3)
+- New `ToolExecutionError` hierarchy: `ToolSchemaError`, `ToolTimeoutError`, `ToolRateLimitError`, `ToolRetryExhaustedError`, `ToolInternalError`
+- All `except Exception` blocks sanitized — no `str(exc)` leakage to callers
+- `KeyboardInterrupt`, `SystemExit`, `AssertionError` propagate (not caught)
+- Schema validator sanitizes jsonschema errors (no input value echo)
+
+#### Configuration Validation (Gap 4)
+- `FrameworkConfig.__post_init__` validates: timeout > 0, temperature 0-2, max_tokens ≥ 0
+- Invalid configs fail fast with `ValueError`
+
+#### Test Coverage Tooling (Gap 5)
+- `pytest-cov` added to dev dependencies
+- `[tool.coverage.run]` configured with branch coverage
+
+#### Security (Gap 6, 8)
+- `SECURITY.md` updated: 1.0.x active, 0.5.x security-only
+- `ScopedToken._secret` → name-mangled `__secret` (not trivially accessible)
+- `CredentialBroker.validate_token` now enforces `max_uses`
+
+#### Dockerfile Hardening (Gap 7)
+- Non-root user (`pf`, uid 1000)
+- `HEALTHCHECK` with 30s interval
+- `STOPSIGNAL SIGTERM` for graceful shutdown
+
+#### Dependency Bounds (Gap 9)
+- All optional deps pinned with upper bounds: `openai<2`, `anthropic<1`, `mcp<2`, `otel<2`, `vault<2`
+
+#### CI Hardening (Gap 10, 11)
+- Integration tests explicitly gated: `-m "not integration"` default
+- Scheduled `workflow_dispatch` integration job for real-API tests
+- mypy enforced in CI: `mypy src/petfishframework` must exit 0
+- `test_mypy_clean.py` and `test_ci_markers.py` as regression guards
+
+#### EventEmitter Sink Error Visibility (Gap 12)
+- `sink_error_count` property — failing sinks increment counter instead of silent `pass`
+- Sinks called outside lock (deadlock prevention)
+
+#### API Stability Policy (Gap 13)
+- `api-stability.md` synced with actual exports
+- `serve_as_mcp` reclassified Internal → Experimental
+- `FrameworkConfig` promoted Experimental → Stable
+- v1.0 freeze criteria documented as met
+
+#### RuntimeEnvironment Refactor (Gap 14)
+- Extracted `_prepare_execution` shared by `call()` and `call_async()`
+- **Fixed gate ordering bug**: async path now matches sync (idempotency before rate_limit)
+- call()/call_async() duplication eliminated via shared execution plan
+- Thread-safety lock on model call counter and cost accountant
+
+#### Test Growth
+- v0.5.2: 382 tests → v1.0.0: 448 tests (+66)
+- mypy: 0 errors across 76 source files
+- ruff: clean
+
 ## [0.5.2] — 2026-07-09
 
 ### Review Fix Patch

petfishframework-1.0.1/Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.12-slim
+
+# Non-root user
+RUN useradd --create-home --uid 1000 pf
+WORKDIR /app
+
+# Install dependencies first (layer caching)
+COPY pyproject.toml uv.lock README.md ./
+RUN pip install uv && uv sync --no-dev --all-extras
+
+# Copy source
+COPY src/ src/
+RUN uv pip install --system .
+
+# Switch to non-root
+USER pf
+
+# Healthcheck
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import petfishframework; print('ok')" || exit 1
+
+# Graceful shutdown
+STOPSIGNAL SIGTERM
+
+ENTRYPOINT ["python", "-m", "petfishframework"]

{petfishframework-0.5.2 → petfishframework-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.5.2
+Version: 1.0.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
@@ -11,7 +11,7 @@ Project-URL: PyPI, https://pypi.org/project/petfishframework/
 Author-email: Kyle Cui <18226150+kylecui@users.noreply.github.com>
 License-Expression: MIT
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -21,27 +21,27 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0.3
 Provides-Extra: anthropic
-Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Requires-Dist: anthropic<1,>=0.40; extra == 'anthropic'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0; extra == 'mcp'
+Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
 Provides-Extra: openai
-Requires-Dist: openai>=1.0; extra == 'openai'
+Requires-Dist: openai<2,>=1.0; extra == 'openai'
 Provides-Extra: otel
-Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
-Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-api<2,>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == 'otel'
 Provides-Extra: vault
-Requires-Dist: hvac>=1.0; extra == 'vault'
+Requires-Dist: hvac<2,>=1.0; extra == 'vault'
 Description-Content-Type: text/markdown
 
 # petfishFramework
 
-> A lightweight Python framework for reliable, auditable, budget-aware, and permission-aware AI agents.
+> A runtime control framework for enterprise AI agents — enforcing policy, budget, credentials, audit, replay, and Tool/MCP governance at execution time.
 
 [![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: 382](https://img.shields.io/badge/tests-382-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 448](https://img.shields.io/badge/tests-448-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
-**Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
+**Status: v1.0 Stable** — Core runtime APIs are frozen. Selected integrations remain experimental; see [API Stability](docs/api-stability.md).
 
 ## Quick Start (Zero Cost — No API Key)
 
@@ -289,11 +289,11 @@ agent = Agent(model=model, reasoning=ReAct(), tools=tools, tool_governance=gover
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
 - **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
-- **v0.5.x** (current): Tool/MCP governance — schema validation, rate limiting, risk classification, retry/timeout wiring, MCP allowlist/schema-pin/risk-map/lifecycledes, Vault adapter, Docker, threat model ✅
+- **v1.0.x** (current): Production release — API stability freeze, thread safety, exception sanitization, Dockerfile hardening, mypy enforcement
 
 ## Current Limitations
 
-petfishFramework is **Alpha**. API may change before v1.0.
+petfishFramework v1.0 has a **stable core runtime** with selected experimental integrations.
 
 | Capability | Status |
 |---|---|
@@ -311,8 +311,36 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | Structured output / conversation memory | ✅ Available |
 | YAML Policy Engine | ✅ Available |
 | Credential Broker | ✅ Available |
-| LATS / LLM+P | ⚠️ Lightweight implementations |
-| CRAG / Adaptive-RAG | ⚠️ Lightweight reference implementations |
+| Tool governance (schema/rate/timeout/retry/idempotency) | ✅ Available |
+| Thread safety (EventEmitter/RateLimiter/IdempotencyStore) | ✅ Available |
+| LATS full MCTS / LLM+P | 🔶 Experimental |
+| CRAG / Adaptive-RAG | 🔶 Lightweight reference implementations |
+| Sandbox subprocess isolation | 🔶 Phase 1 (not a security boundary) |
+
+## API Stability
+
+| Area | Status |
+|---|---|
+| Agent / Session / RuntimeEnvironment | ✅ Stable |
+| DecisionEffect semantics (all 6) | ✅ Stable |
+| Budget / CostAccountant | ✅ Stable |
+| CredentialBroker / ScopedToken | ✅ Stable |
+| YAML Policy Engine | ✅ Stable |
+| AuditReport / EventEmitter | ✅ Stable |
+| SIEMSink (key-based redaction) | ✅ Stable |
+| Tool schema validation / rate limiting | ✅ Stable |
+| MCP client governance (allowlist/pin/risk) | ✅ Stable |
+| Pass^k reliability metric | ✅ Stable |
+| FrameworkConfig | ✅ Stable |
+| MCP server mode | 🔶 Experimental (stdio JSON-RPC MVP) |
+| OTel sink | 🔶 Experimental (optional dep) |
+| Vault adapter | 🔶 Experimental (optional dep) |
+| Deterministic replay / resume | 🔶 Experimental |
+| LATS full MCTS / LLM+P | 🔶 Experimental |
+| CRAG / Adaptive-RAG | 🔶 Lightweight reference |
+| Sandbox executor | 🔶 Phase 1 (process isolation) |
+
+See [API Stability Policy](docs/api-stability.md) for full classification and deprecation process.
 
 ## Development
 
@@ -320,7 +348,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              # 382 tests
+uv run pytest              # 448 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.5.2 → petfishframework-1.0.1}/README.md

@@ -1,12 +1,12 @@
 # petfishFramework
 
-> A lightweight Python framework for reliable, auditable, budget-aware, and permission-aware AI agents.
+> A runtime control framework for enterprise AI agents — enforcing policy, budget, credentials, audit, replay, and Tool/MCP governance at execution time.
 
 [![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: 382](https://img.shields.io/badge/tests-382-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 448](https://img.shields.io/badge/tests-448-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
-**Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
+**Status: v1.0 Stable** — Core runtime APIs are frozen. Selected integrations remain experimental; see [API Stability](docs/api-stability.md).
 
 ## Quick Start (Zero Cost — No API Key)
 
@@ -254,11 +254,11 @@ agent = Agent(model=model, reasoning=ReAct(), tools=tools, tool_governance=gover
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
 - **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
-- **v0.5.x** (current): Tool/MCP governance — schema validation, rate limiting, risk classification, retry/timeout wiring, MCP allowlist/schema-pin/risk-map/lifecycledes, Vault adapter, Docker, threat model ✅
+- **v1.0.x** (current): Production release — API stability freeze, thread safety, exception sanitization, Dockerfile hardening, mypy enforcement
 
 ## Current Limitations
 
-petfishFramework is **Alpha**. API may change before v1.0.
+petfishFramework v1.0 has a **stable core runtime** with selected experimental integrations.
 
 | Capability | Status |
 |---|---|
@@ -276,8 +276,36 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | Structured output / conversation memory | ✅ Available |
 | YAML Policy Engine | ✅ Available |
 | Credential Broker | ✅ Available |
-| LATS / LLM+P | ⚠️ Lightweight implementations |
-| CRAG / Adaptive-RAG | ⚠️ Lightweight reference implementations |
+| Tool governance (schema/rate/timeout/retry/idempotency) | ✅ Available |
+| Thread safety (EventEmitter/RateLimiter/IdempotencyStore) | ✅ Available |
+| LATS full MCTS / LLM+P | 🔶 Experimental |
+| CRAG / Adaptive-RAG | 🔶 Lightweight reference implementations |
+| Sandbox subprocess isolation | 🔶 Phase 1 (not a security boundary) |
+
+## API Stability
+
+| Area | Status |
+|---|---|
+| Agent / Session / RuntimeEnvironment | ✅ Stable |
+| DecisionEffect semantics (all 6) | ✅ Stable |
+| Budget / CostAccountant | ✅ Stable |
+| CredentialBroker / ScopedToken | ✅ Stable |
+| YAML Policy Engine | ✅ Stable |
+| AuditReport / EventEmitter | ✅ Stable |
+| SIEMSink (key-based redaction) | ✅ Stable |
+| Tool schema validation / rate limiting | ✅ Stable |
+| MCP client governance (allowlist/pin/risk) | ✅ Stable |
+| Pass^k reliability metric | ✅ Stable |
+| FrameworkConfig | ✅ Stable |
+| MCP server mode | 🔶 Experimental (stdio JSON-RPC MVP) |
+| OTel sink | 🔶 Experimental (optional dep) |
+| Vault adapter | 🔶 Experimental (optional dep) |
+| Deterministic replay / resume | 🔶 Experimental |
+| LATS full MCTS / LLM+P | 🔶 Experimental |
+| CRAG / Adaptive-RAG | 🔶 Lightweight reference |
+| Sandbox executor | 🔶 Phase 1 (process isolation) |
+
+See [API Stability Policy](docs/api-stability.md) for full classification and deprecation process.
 
 ## Development
 
@@ -285,7 +313,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              # 382 tests
+uv run pytest              # 448 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.5.2 → petfishframework-1.0.1}/SECURITY.md

@@ -4,9 +4,9 @@
 
 | Version | Supported              |
 |---------|------------------------|
-| 0.4.x   | ✅ Active development   |
-| 0.3.x   | ⚠️ Security fixes only  |
-| < 0.3   | ❌ Not supported         |
+| 1.0.x   | ✅ Active development   |
+| 0.5.x   | ⚠️ Security fixes only  |
+| < 0.5   | ❌ Not supported         |
 
 ## Reporting a Vulnerability