petfishframework 0.4.1__tar.gz → 0.4.5__tar.gz

petfishframework-0.4.5/.gitattributes

@@ -0,0 +1,11 @@
+# Normalize line endings across platforms — all text files use LF in the repo
+* text=auto eol=lf
+
+# Binary files — never touch
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.drawio binary

{petfishframework-0.4.1 → petfishframework-0.4.5}/.github/workflows/ci.yml

@@ -31,3 +31,15 @@ jobs:
       - name: Run tests
         run: uv run pytest tests/ -q --tb=short
         # Integration tests are skipped automatically (no API key in CI)
+
+  docker-smoke:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: docker build -t petfishframework .
+
+      - name: Run container smoke test
+        run: docker run --rm petfishframework

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

@@ -2,6 +2,58 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [0.4.5] — 2026-07-08
+
+### v0.5 Readiness: API Documentation + Technical Debt Cleanup
+
+#### API Reference Overhaul (28 APIs documented)
+- `docs/api.md` expanded from 1471 to 2203 lines (+50%)
+- All 28 previously-undocumented public APIs now have full signatures, parameters, and examples:
+  - **Observability**: OTelSink, SIEMSink (with redact_keys boundary note)
+  - **Reliability**: RetryPolicy, with_retry, with_retry_async, RetryableError, RetryModelAdapter, retry_model_adapter, TimeoutPolicy, with_timeout, OperationTimedOut, RerunEnvironment, RerunResult, CostReport
+  - **Configuration**: FrameworkConfig (from_env, from_dict)
+  - **Conversation Memory**: ConversationStore, InMemoryConversationStore
+  - **Structured Output**: StructuredResult, parse_json, parse_structured
+  - **Tools**: AgentAsTool, WordSorter
+  - **Models**: AnthropicModel, AsyncFakeModel
+  - **Policies**: PolicyRule, load_policy
+  - **MCP**: serve_as_mcp (marked as v0.5 stub)
+
+#### API Stability Policy
+- New `docs/api-stability.md` classifies all public APIs into Stable / Experimental / Internal tiers
+- Documents deprecation process and v1.0 freeze criteria
+
+#### Code Cleanup (stale markers removed)
+- `permissions/__init__.py`: docstring updated — CredentialBroker is implemented, not TODO
+- `permissions/model.py`: DefaultAllowPolicy comment clarified (allow-all by design, not a skeleton TODO)
+- `core/environment.py`: DEGRADE docstring fixed — tool switching IS implemented (was incorrectly marked "future work"); visibility gate clarified as v0.5 planned
+- `docs/skeleton-completeness-checklist.md`: comprehensively updated to reflect v0.4.5 state (RESUME/RERUN, Pass^k, CredentialBroker, OTel/SIEM, retry/timeout all marked ✅)
+
+## [0.4.2] — 2026-07-08
+
+### CI & Deployment Hardening
+
+#### Docker Smoke Test in CI
+- New `docker-smoke` job in CI workflow: builds image and runs container
+- Catches `__main__.py` / ENTRYPOINT regressions before release
+
+#### Line Ending Normalization
+- Added `.gitattributes` with `* text=auto eol=lf`
+- All text files now use LF consistently across platforms
+
+#### SIEMSink Documentation
+- Docstring now explicitly states key-based redaction is not a DLP engine
+- Clarifies that value-pattern secrets (sk-..., JWTs) are not detected
+- Documents default redact_keys and nesting behavior
+
+#### Observability Example
+- New `examples/06_observability.py`: ListSink, ConsoleSink, SIEMSink, OTelSink demo
+- Shows correct sink attachment via `session.events.subscribe()`
+- Demonstrates custom `redact_keys` with nested field redaction
+
+#### README Fix
+- Observability example corrected: uses `session.events.subscribe()` instead of non-existent `event_sinks=` parameter
+
 ## [0.4.1] — 2026-07-08
 
 ### Review Fix Patch

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.4.1
+Version: 0.4.5
 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
@@ -262,7 +262,13 @@ 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))
+agent = Agent(model=model, reasoning=ReAct(), tools=tools)
+
+# Attach sinks to the session's EventEmitter
+session = agent.session("your task")
+session.events.subscribe(otel_sink)
+session.events.subscribe(siem_sink)
+result = session.run()
 ```
 
 ## Roadmap

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

@@ -227,7 +227,13 @@ 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))
+agent = Agent(model=model, reasoning=ReAct(), tools=tools)
+
+# Attach sinks to the session's EventEmitter
+session = agent.session("your task")
+session.events.subscribe(otel_sink)
+session.events.subscribe(siem_sink)
+result = session.run()
 ```
 
 ## Roadmap

petfishframework-0.4.5/docs/api-stability.md

@@ -0,0 +1,88 @@
+# API Stability Policy
+
+> Effective: v0.4.5
+> Goal: Help users understand which APIs are safe to depend on before v1.0.
+
+## Stability Tiers
+
+| Tier | Meaning | Breaking changes | Versioning |
+|---|---|---|---|
+| **Stable** | API signature and semantics will not change before v1.0 without a deprecation cycle (min 1 minor version). | Only for security fixes. | Patch (0.4.x) |
+| **Experimental** | API exists and works, but may change signature or semantics in the next minor version. | Allowed with CHANGELOG note. | Minor (0.x.0) |
+| **Internal** | Used by the framework internally. May change or be removed without notice. | No guarantees. | Any |
+
+## Classification
+
+### Stable
+
+These APIs have been validated by 300+ tests and are used in production-facing examples:
+
+- `Agent`, `Session` — core execution abstractions
+- `Budget`, `BudgetExceeded` — budget enforcement
+- `DecisionEffect` (all 6 values) — permission semantics
+- `Subject`, `Action`, `Resource`, `AccessContext`, `Decision` — SARC model
+- `PermissionPolicy` protocol — policy interface
+- `DefaultAllowPolicy`, `DenyByDefaultPolicy` — built-in policies
+- `Event`, `EventEmitter` — event infrastructure
+- `Result`, `Task`, `Step`, `Trajectory`, `Usage` — core types
+- `Tool` protocol, `BaseTool`, `@tool` decorator
+- `Calculator`, `WordSorter` — reference tools
+- `FakeModel` — testing model
+- `ReAct` — default reasoning strategy
+- `RuntimeEnvironment` — the chokepoint
+- `AuditReport`, `audit_report_from_session` — audit output
+- `CredentialBroker`, `ScopedToken` — credential governance
+- `YamlPolicy`, `PolicyRule` — YAML policy engine
+- `pass_at_k`, `pass_at_k_with_perturbations` — reliability metric
+
+### Experimental
+
+These APIs work and are tested, but their signatures or semantics may change:
+
+- `OTelSink`, `SIEMSink` — observability sinks (redaction API may evolve)
+- `RecordingEnvironment`, `ReplayEnvironment`, `RerunEnvironment`, `ResumableEnvironment` — replay wrappers
+- `RerunResult` — divergence detection output format may change
+- `RetryPolicy`, `with_retry`, `RetryModelAdapter` — retry infrastructure
+- `TimeoutPolicy`, `with_timeout` — timeout infrastructure
+- `VaultCredentialSource` — Vault adapter (needs real-world validation)
+- `OpenAIModel`, `AnthropicModel` — model adapters (provider API changes)
+- `LATS`, `LLMPlusP` — reasoning strategies (lightweight implementations)
+- `CRAGRetriever`, `AdaptiveRetriever`, `MemoryRetriever` — retrieval (lightweight)
+- `AgentAsTool` — multi-agent delegation
+- `ConversationStore`, `InMemoryConversationStore` — conversation memory
+- `StructuredResult`, `parse_json`, `parse_structured` — structured output
+- `FrameworkConfig` — configuration system
+- `CostReport` — cost reporting format
+- `connect_stdio`, `MCPClient` — MCP client
+- Policy condition matchers — YAML matcher set may expand/change
+- `SIEMSink.redact_keys` — redaction key set may change defaults
+
+### Internal
+
+These are implementation details that should not be directly imported:
+
+- `CostAccountant` — internal cost tracking (use `Result.usage` instead)
+- `CapabilityProjection` — visibility gate (not yet enforced)
+- `CapabilityGrant` — audit artifact type (not yet emitted)
+- `CompiledContext`, `TaskSpec`, `MemorySlice`, `EvidenceBundle`, `OutputContract` — compiled context types
+- `MemoryView` — memory protocol (empty stub)
+- `serve_as_mcp` — MCP server stub (raises NotImplementedError)
+- `pass_at_k` perturbation functions (`canonical`, `order_shuffled`, etc.) — stable interface but internal implementations
+
+## Deprecation Process
+
+When an API moves from Stable to deprecated:
+
+1. Add `DeprecationWarning` in the next minor version
+2. Document replacement in CHANGELOG
+3. Keep the API functional for at least 1 minor version
+4. Remove in the following minor version (or v1.0 if major)
+
+## v1.0 Freeze Criteria
+
+Before declaring v1.0:
+
+- All Stable APIs have been unchanged for 2+ minor versions
+- All Experimental APIs are reclassified as Stable or explicitly dropped
+- Breaking changes require semver-major version bump
+- Migration guide published for any dropped APIs