openbox-temporal-sdk-python 1.1.0__tar.gz → 1.1.2__tar.gz

openbox_temporal_sdk_python-1.1.2/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+All notable changes to OpenBox SDK for Temporal Workflows.
+
+## [1.1.2] - 2026-04-22
+
+### Security
+
+- **API key no longer flows through workflow history.** `send_governance_event` refactored into a `GovernanceActivities` class that holds credentials on `self`; activity inputs carry only `payload`, `timeout`, and `on_api_error`. Before this change, anyone with Describe permissions on the namespace could read the API key from the recorded activity input.
+
+### Added
+
+- W3C trace propagation through Temporal headers, on by default via `enable_trace_propagation=True` on `OpenBoxPlugin` and `create_openbox_worker()`. Uses `temporalio.contrib.opentelemetry.TracingInterceptor` so spans started by the caller stitch to workflow/activity spans on the worker side.
+- `ApplicationError` type constants in `errors.py` (`GOVERNANCE_HALT_ERROR_TYPE`, `GOVERNANCE_BLOCK_ERROR_TYPE`, `GOVERNANCE_API_ERROR_TYPE`, `GOVERNANCE_STOP_ERROR_TYPE`) — single source of truth for governance error routing.
+- `openbox.activities.GovernanceActivities` class + `build_governance_activities()` factory.
+
+### Fixed
+
+- **Workflow exception shadowing** — `WorkflowFailed` event send is now wrapped in `try/except`, so a `GovernanceHaltError` from `fail_closed + API down` no longer replaces the real workflow error.
+- **String-matching on exception types** — `workflow_interceptor` now inspects `ApplicationError.type` via the exception chain instead of `"GovernanceHalt" in str(e)`. Eliminates false positives when a user workflow happens to emit an error message containing a governance keyword.
+- **Race creating governance HTTP client** — `hook_governance._get_sync_client` / `_get_async_client` now use double-checked locking. Previously two concurrent activities could each create a client, with the losing instance getting garbage-collected while its connection pool leaked.
+- **Replayer plugin coverage** — `test_plugin_integration.py` now passes `plugins=[plugin]` to `Replayer`, so replay tests validate interceptor determinism, not just user workflow code.
+- Version-pin mismatch — comments in `openbox/__init__.py` said `temporalio >= 1.24.0` but pyproject/README pin `1.23.0`. Corrected to `1.23.0`.
+
+### Changed
+
+- `plugin.py` / `worker.py` now use `logging.getLogger(__name__)` for initialization status messages instead of `print()`.
+
+## [1.1.1] - 2026-04-07
+
+### Added
+
+- **OpenBoxPlugin** — drop-in `SimplePlugin` integration for Temporal Workers. Single-line setup: `plugins=[OpenBoxPlugin(openbox_url=..., openbox_api_key=...)]`. Auto-registers interceptors, OTel instrumentation, sandbox passthrough, and `send_governance_event` activity
+- Plugin integration guide for Temporal AI Partner Ecosystem (`docs/temporal-plugin-integration-guide.md`)
+- HTTP body truncation tests (`tests/test_http_body_truncation.py`)
+- Plugin unit tests (`tests/test_plugin.py`) and integration/replay tests (`tests/test_plugin_integration.py`)
+
+### Fixed
+
+- **HTTP body truncation** — enforce `max_body_size` (default 64KB) on request/response bodies in governance spans
+- **File I/O spans** — remove raw file content from governance payloads; only `bytes_read`/`bytes_written` metadata sent
+- **error_type sanitization** — prevent serialized error objects from being sent as `error.cause.error_type` string in WorkflowFailed payloads
+- Remove useless f-strings, redundant `(ImportError, Exception)` clauses, merge nested if statements
+- Prefix unused `span` param in urllib hook
+
+### Changed
+
+- `temporalio>=1.23.0` (from 1.8.0) for SimplePlugin support
+- `GovernanceConfig.max_body_size` default changed from `None` (unlimited) to `65536` (64KB)
+- `\w` regex shorthand in API key pattern
+
+### Refactored
+
+- Reduce cognitive complexity across 7 modules: `activity_interceptor.py` (126→split), `workflow_interceptor.py` (40→split), `activities.py` (20→split), `db_governance_hooks.py` (34→split), `otel_setup.py` (51→split), `tracing.py` (85→split), `verdict_handler.py` (16→15)
+- Extract shared helpers: `_run_governed_query_sync/async`, `_build_error_dict`, `_extract_dbapi_context`, `_instrument_sqlalchemy`
+
+### Dependencies
+
+- Bump Pygments 2.19.2 → 2.20.0 (ReDoS fix, CVSS 1.9)
+
+## [1.1.0] - 2026-03-09
+
+### Added
+
+- **Hook-level governance** — real-time, per-operation governance evaluation during activity execution
+  - Every HTTP request, database query, file operation, and traced function call is evaluated at `started` (before, can block) and `completed` (after, informational) stages
+  - Same `POST /api/v1/governance/evaluate` endpoint with new `hook_trigger` field in payload
+  - Automatically enabled when using `create_openbox_worker()`
+- **Database query governance** — per-query started/completed evaluations for psycopg2, pymysql, mysql-connector, asyncpg, pymongo, redis, sqlalchemy
+- **File I/O governance** — per-operation evaluations for open, read, write, readline, readlines, writelines, close (opt-in via `instrument_file_io=True`)
+- **`@traced` decorator** (`openbox.tracing`) — function-level governance with OTel spans; zero overhead when governance not configured
+- **`GovernanceBlockedError`** — new exception type for hook-level blocking with verdict, reason, and resource identifier
+- **Abort propagation** — once one hook blocks, all subsequent hooks for the same activity short-circuit immediately
+- **HALT workflow termination** from hook-level governance via `client.terminate()`
+- **REQUIRE_APPROVAL** from hook-level governance enters the same HITL approval polling flow as activity-level approvals
+- **`duration_ns`** computed for all hook span types (HTTP, file, function — DB already had it)
+
+### Changed
+
+- **`hook_trigger` simplified to boolean** — was a dict with type/stage/data, now just `true`. All data moved to span root fields
+- **Span data consolidation** — all type-specific fields at span root (`hook_type`, `http_method`, `db_system`, `file_path`, `function`, etc.)
+- **`attributes` is OTel-original only** — no custom `openbox.*`, `http.request.*`, `db.result.*` fields injected
+- Hook governance payloads send only the current span per evaluation (not accumulated history)
+- Event-level payloads (ActivityStarted/Completed, Workflow events) no longer include spans
+- Simplified `WorkflowSpanProcessor` — removed span buffering, governed span tracking, body data merging; `on_end()` now only forwards to fallback exporters
+
+### Fixed
+
+- HALT verdict from hooks now correctly terminates the workflow (previously only stopped the activity like BLOCK)
+- REQUIRE_APPROVAL from hooks now enters the approval polling flow (previously raised unhandled error)
+- Stale buffer/verdict from previous workflow run no longer carries over when workflow_id is reused
+- Subsequent hooks no longer fire after the first hook blocks an activity
+
+## [1.0.21] - 2026-03-04
+
+### Added
+
+- Human-in-the-loop approval with expiration handling
+- Approval polling via `POST /api/v1/governance/approval`
+- Guardrails: input/output validation and redaction
+- `GovernanceVerdictResponse.from_dict()` with guardrails_result parsing
+- Output redaction for activity results
+- `_deep_update_dataclass()` for in-place dataclass field updates from redacted dicts
+
+### Fixed
+
+- Temporal Payload objects no longer slip through as non-serializable in governance payloads
+- Stale buffer detection via run_id comparison
+
+## [1.0.0] - 2026-02-15
+
+### Added
+
+- Initial release
+- 6 event types: WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted
+- 5-tier verdict system: ALLOW, CONSTRAIN, REQUIRE_APPROVAL, BLOCK, HALT
+- HTTP instrumentation via OpenTelemetry (httpx, requests, urllib3, urllib)
+- Database instrumentation (psycopg2, pymysql, asyncpg, pymongo, redis, sqlalchemy)
+- File I/O instrumentation (opt-in)
+- Zero-code setup via `create_openbox_worker()` factory
+- Workflow and activity interceptors for governance
+- Span buffering and activity context tracking
+- `fail_open` / `fail_closed` error policies
+- v1.0 backward compatibility for legacy verdict strings

{openbox_temporal_sdk_python-1.1.0 → openbox_temporal_sdk_python-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbox-temporal-sdk-python
-Version: 1.1.0
+Version: 1.1.2
 Summary: OpenBox SDK - Governance and observability for Temporal workflows
 Project-URL: Homepage, https://github.com/OpenBox-AI/temporal-sdk-python
 Project-URL: Documentation, https://github.com/OpenBox-AI/temporal-sdk-python#readme
@@ -15,14 +15,12 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Monitoring
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Requires-Dist: asyncpg>=0.29.0
 Requires-Dist: httpx<1,>=0.28.0
 Requires-Dist: mysql-connector-python>=8.0.0
@@ -45,7 +43,7 @@ Requires-Dist: pymongo>=4.0.0
 Requires-Dist: pymysql>=1.0.0
 Requires-Dist: redis>=5.0.0
 Requires-Dist: sqlalchemy>=2.0.0
-Requires-Dist: temporalio<2,>=1.8.0
+Requires-Dist: temporalio<2,>=1.23.0
 Description-Content-Type: text/markdown
 
 # OpenBox SDK for Temporal Workflows
@@ -70,13 +68,70 @@ pip install openbox-temporal-sdk-python
 ```
 
 **Requirements:**
-- Python 3.9+
-- Temporal SDK 1.8+
+- Python 3.11+
+- Temporal SDK 1.23+ (1.8+ for factory-only usage)
 - OpenTelemetry API/SDK 1.38.0+
 
 ---
 
-## Quick Start
+## Plugin Integration (Recommended)
+
+Use `OpenBoxPlugin` for drop-in integration with Temporal Workers:
+
+```python
+import os
+from temporalio.worker import Worker
+from openbox.plugin import OpenBoxPlugin
+
+worker = Worker(
+    client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+    plugins=[
+        OpenBoxPlugin(
+            openbox_url=os.getenv("OPENBOX_URL"),
+            openbox_api_key=os.getenv("OPENBOX_API_KEY"),
+        )
+    ],
+)
+
+await worker.run()
+```
+
+The plugin automatically configures governance interceptors, OTel instrumentation,
+sandbox passthrough, W3C trace propagation through Temporal headers (via
+`temporalio.contrib.opentelemetry.TracingInterceptor`), and the
+`send_governance_event` activity.
+
+**Credentials never leave the plugin.** `openbox_api_key` is captured on the
+governance activity instance itself — it does **not** flow through activity
+inputs, so it is never written to workflow history. To opt out of trace
+propagation (e.g., if you already wire `OpenTelemetryPlugin`), pass
+`enable_trace_propagation=False`.
+
+### Composing with Other Plugins
+
+```python
+from temporalio.contrib.opentelemetry import OpenTelemetryPlugin
+
+worker = Worker(
+    client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+    plugins=[
+        OpenTelemetryPlugin(),
+        OpenBoxPlugin(openbox_url=..., openbox_api_key=...),
+    ],
+)
+```
+
+> **Requires** `temporalio >= 1.23.0`. For older versions, use `create_openbox_worker()` below.
+
+---
+
+## Quick Start (Factory)
 
 Use the `create_openbox_worker()` factory for simple integration:
 
@@ -101,8 +156,10 @@ The factory automatically:
 1. Validates the API key
 2. Creates span processor
 3. Sets up OpenTelemetry instrumentation
-4. Creates governance interceptors
-5. Adds `send_governance_event` activity
+4. Creates governance interceptors (incl. W3C trace propagation)
+5. Builds the `GovernanceActivities` instance with credentials captured on
+   `self` and registers its `send_governance_event` method — the API key is
+   never passed through activity inputs / workflow history
 6. Returns fully configured Worker
 
 ---
@@ -148,6 +205,11 @@ worker = create_openbox_worker(
     # File I/O instrumentation
     instrument_file_io=False,  # disabled by default
 
+    # Header-based W3C trace propagation (client → workflow → activities).
+    # Default True. Set False if you already wire OpenTelemetryPlugin or a
+    # custom propagator.
+    enable_trace_propagation=True,
+
     # Standard Worker options (all supported)
     activity_executor=my_executor,
     max_concurrent_activities=10,
@@ -424,7 +486,7 @@ from openbox import (
 )
 from openbox.otel_setup import setup_opentelemetry_for_governance
 from openbox.activity_interceptor import ActivityGovernanceInterceptor
-from openbox.activities import send_governance_event
+from openbox.activities import build_governance_activities
 from openbox.hook_governance import FAIL_OPEN, FAIL_CLOSED  # error policy constants
 
 # 1. Initialize SDK
@@ -464,14 +526,26 @@ activity_interceptor = ActivityGovernanceInterceptor(
     config=config,
 )
 
-# 6. Create worker
+# 6. Build the governance activity instance (credentials captured on `self`
+# so they never flow through workflow history).
+governance_activities = build_governance_activities(
+    api_url="http://localhost:8086",
+    api_key="obx_test_key_1",
+)
+
+# 7. Create worker
 from temporalio.worker import Worker
+from temporalio.contrib.opentelemetry import TracingInterceptor
 worker = Worker(
     client=client,
     task_queue="my-task-queue",
     workflows=[MyWorkflow],
-    activities=[my_activity, send_governance_event],
-    interceptors=[workflow_interceptor, activity_interceptor],
+    activities=[my_activity, governance_activities.send_governance_event],
+    interceptors=[
+        workflow_interceptor,
+        activity_interceptor,
+        TracingInterceptor(),  # W3C header propagation for OTel spans
+    ],
 )
 ```
 
@@ -489,13 +563,13 @@ worker = Worker(
 
 ## Testing
 
-The SDK includes comprehensive test coverage with 13 test files:
+The SDK includes comprehensive test coverage with 15 test files:
 
 ```bash
 pytest tests/
 ```
 
-Test files: `test_activities.py`, `test_activity_interceptor.py`, `test_config.py`, `test_db_governance_hooks.py`, `test_file_governance_hooks.py`, `test_otel_hook_pause.py`, `test_otel_hook_pause_db.py`, `test_otel_setup.py`, `test_span_processor.py`, `test_tracing.py`, `test_types.py`, `test_worker.py`, `test_workflow_interceptor.py`
+Test files: `test_activities.py`, `test_activity_interceptor.py`, `test_config.py`, `test_db_governance_hooks.py`, `test_file_governance_hooks.py`, `test_otel_hook_pause.py`, `test_otel_hook_pause_db.py`, `test_otel_setup.py`, `test_plugin.py`, `test_plugin_integration.py`, `test_span_processor.py`, `test_tracing.py`, `test_types.py`, `test_worker.py`, `test_workflow_interceptor.py`
 
 ---
 
@@ -512,4 +586,4 @@ MIT License - See LICENSE file for details
 
 ---
 
-**Version:** 1.1.0 | **Last Updated:** 2026-03-09
+**Version:** 1.2.0 | **Last Updated:** 2026-04-05

{openbox_temporal_sdk_python-1.1.0 → openbox_temporal_sdk_python-1.1.2}/README.md

@@ -20,13 +20,70 @@ pip install openbox-temporal-sdk-python
 ```
 
 **Requirements:**
-- Python 3.9+
-- Temporal SDK 1.8+
+- Python 3.11+
+- Temporal SDK 1.23+ (1.8+ for factory-only usage)
 - OpenTelemetry API/SDK 1.38.0+
 
 ---
 
-## Quick Start
+## Plugin Integration (Recommended)
+
+Use `OpenBoxPlugin` for drop-in integration with Temporal Workers:
+
+```python
+import os
+from temporalio.worker import Worker
+from openbox.plugin import OpenBoxPlugin
+
+worker = Worker(
+    client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+    plugins=[
+        OpenBoxPlugin(
+            openbox_url=os.getenv("OPENBOX_URL"),
+            openbox_api_key=os.getenv("OPENBOX_API_KEY"),
+        )
+    ],
+)
+
+await worker.run()
+```
+
+The plugin automatically configures governance interceptors, OTel instrumentation,
+sandbox passthrough, W3C trace propagation through Temporal headers (via
+`temporalio.contrib.opentelemetry.TracingInterceptor`), and the
+`send_governance_event` activity.
+
+**Credentials never leave the plugin.** `openbox_api_key` is captured on the
+governance activity instance itself — it does **not** flow through activity
+inputs, so it is never written to workflow history. To opt out of trace
+propagation (e.g., if you already wire `OpenTelemetryPlugin`), pass
+`enable_trace_propagation=False`.
+
+### Composing with Other Plugins
+
+```python
+from temporalio.contrib.opentelemetry import OpenTelemetryPlugin
+
+worker = Worker(
+    client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+    plugins=[
+        OpenTelemetryPlugin(),
+        OpenBoxPlugin(openbox_url=..., openbox_api_key=...),
+    ],
+)
+```
+
+> **Requires** `temporalio >= 1.23.0`. For older versions, use `create_openbox_worker()` below.
+
+---
+
+## Quick Start (Factory)
 
 Use the `create_openbox_worker()` factory for simple integration:
 
@@ -51,8 +108,10 @@ The factory automatically:
 1. Validates the API key
 2. Creates span processor
 3. Sets up OpenTelemetry instrumentation
-4. Creates governance interceptors
-5. Adds `send_governance_event` activity
+4. Creates governance interceptors (incl. W3C trace propagation)
+5. Builds the `GovernanceActivities` instance with credentials captured on
+   `self` and registers its `send_governance_event` method — the API key is
+   never passed through activity inputs / workflow history
 6. Returns fully configured Worker
 
 ---
@@ -98,6 +157,11 @@ worker = create_openbox_worker(
     # File I/O instrumentation
     instrument_file_io=False,  # disabled by default
 
+    # Header-based W3C trace propagation (client → workflow → activities).
+    # Default True. Set False if you already wire OpenTelemetryPlugin or a
+    # custom propagator.
+    enable_trace_propagation=True,
+
     # Standard Worker options (all supported)
     activity_executor=my_executor,
     max_concurrent_activities=10,
@@ -374,7 +438,7 @@ from openbox import (
 )
 from openbox.otel_setup import setup_opentelemetry_for_governance
 from openbox.activity_interceptor import ActivityGovernanceInterceptor
-from openbox.activities import send_governance_event
+from openbox.activities import build_governance_activities
 from openbox.hook_governance import FAIL_OPEN, FAIL_CLOSED  # error policy constants
 
 # 1. Initialize SDK
@@ -414,14 +478,26 @@ activity_interceptor = ActivityGovernanceInterceptor(
     config=config,
 )
 
-# 6. Create worker
+# 6. Build the governance activity instance (credentials captured on `self`
+# so they never flow through workflow history).
+governance_activities = build_governance_activities(
+    api_url="http://localhost:8086",
+    api_key="obx_test_key_1",
+)
+
+# 7. Create worker
 from temporalio.worker import Worker
+from temporalio.contrib.opentelemetry import TracingInterceptor
 worker = Worker(
     client=client,
     task_queue="my-task-queue",
     workflows=[MyWorkflow],
-    activities=[my_activity, send_governance_event],
-    interceptors=[workflow_interceptor, activity_interceptor],
+    activities=[my_activity, governance_activities.send_governance_event],
+    interceptors=[
+        workflow_interceptor,
+        activity_interceptor,
+        TracingInterceptor(),  # W3C header propagation for OTel spans
+    ],
 )
 ```
 
@@ -439,13 +515,13 @@ worker = Worker(
 
 ## Testing
 
-The SDK includes comprehensive test coverage with 13 test files:
+The SDK includes comprehensive test coverage with 15 test files:
 
 ```bash
 pytest tests/
 ```
 
-Test files: `test_activities.py`, `test_activity_interceptor.py`, `test_config.py`, `test_db_governance_hooks.py`, `test_file_governance_hooks.py`, `test_otel_hook_pause.py`, `test_otel_hook_pause_db.py`, `test_otel_setup.py`, `test_span_processor.py`, `test_tracing.py`, `test_types.py`, `test_worker.py`, `test_workflow_interceptor.py`
+Test files: `test_activities.py`, `test_activity_interceptor.py`, `test_config.py`, `test_db_governance_hooks.py`, `test_file_governance_hooks.py`, `test_otel_hook_pause.py`, `test_otel_hook_pause_db.py`, `test_otel_setup.py`, `test_plugin.py`, `test_plugin_integration.py`, `test_span_processor.py`, `test_tracing.py`, `test_types.py`, `test_worker.py`, `test_workflow_interceptor.py`
 
 ---
 
@@ -462,4 +538,4 @@ MIT License - See LICENSE file for details
 
 ---
 
-**Version:** 1.1.0 | **Last Updated:** 2026-03-09
+**Version:** 1.2.0 | **Last Updated:** 2026-04-05

{openbox_temporal_sdk_python-1.1.0 → openbox_temporal_sdk_python-1.1.2}/docs/code-standards.md

@@ -83,10 +83,13 @@ This document defines coding standards, architectural patterns, and best practic
 async def execute_workflow(self, input: ExecuteWorkflowInput) -> Any:
     info = workflow.info()
 
-    # Send event via activity (deterministic)
+    # Send event via activity (deterministic). NEVER pass credentials
+    # (api_key) in activity inputs — workflow history is readable by anyone
+    # with Describe permissions on the namespace. The activity holds the
+    # credentials on its instance (see rule 3).
     await workflow.execute_activity(
         "send_governance_event",
-        args=[{"api_url": api_url, "payload": {...}}],
+        args=[{"payload": {...}, "timeout": 30.0, "on_api_error": "fail_open"}],
         start_to_close_timeout=timedelta(seconds=30),
     )
 
@@ -122,25 +125,36 @@ async def execute_workflow(self, input: ExecuteWorkflowInput) -> Any:
 #### Solution: Lazy Imports
 
 ```python
-# ✅ CORRECT - Lazy import in activity function
-@activity.defn(name="send_governance_event")
-async def send_governance_event(input: Dict[str, Any]):
-    import httpx  # ✅ Loaded only when activity executes
-    from datetime import datetime, timezone  # ✅ Lazy import
-
-    async with httpx.AsyncClient() as client:
-        response = await client.post(...)
-    return response.json()
+# ✅ CORRECT - Class-based activity with credentials captured on self
+class GovernanceActivities:
+    def __init__(self, api_url: str, api_key: str):
+        self._api_url = api_url
+        self._api_key = api_key
+
+    @activity.defn(name="send_governance_event")
+    async def send_governance_event(self, input: Dict[str, Any]):
+        import httpx  # ✅ Loaded only when activity executes
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self._api_url}/api/v1/governance/evaluate",
+                headers={"Authorization": f"Bearer {self._api_key}"},
+                json=input["payload"],
+            )
+        return response.json()
 ```
 
 ```python
-# ❌ WRONG - Module-level import
-import httpx  # ❌ Loaded when module imports, triggers sandbox
-
+# ❌ WRONG - Credentials in activity input (leaks to workflow history)
 @activity.defn(name="send_governance_event")
 async def send_governance_event(input: Dict[str, Any]):
+    # ❌ input["api_key"] is persisted in workflow history — readable by
+    # anyone with Describe access to the namespace.
     async with httpx.AsyncClient() as client:
-        response = await client.post(...)
+        response = await client.post(
+            input["api_url"],
+            headers={"Authorization": f"Bearer {input['api_key']}"},
+            json=input["payload"],
+        )
     return response.json()
 ```
 

{openbox_temporal_sdk_python-1.1.0 → openbox_temporal_sdk_python-1.1.2}/docs/codebase-summary.md

@@ -22,6 +22,7 @@ openbox-temporal-sdk-python/
 │   ├── types.py               # Type definitions (workflow-safe)
 │   ├── config.py              # Configuration and initialization
 │   ├── worker.py              # Worker factory function
+│   ├── plugin.py              # OpenBoxPlugin(SimplePlugin) for Temporal AI Partner Ecosystem
 │   ├── errors.py              # Unified exception hierarchy
 │   ├── client.py              # GovernanceClient (centralized HTTP client)
 │   ├── hitl.py                # HITL approval handling
@@ -327,30 +328,48 @@ def create_openbox_worker(
 ### 11. Governance Event Activity (`activities.py`)
 
 **Purpose:** Execute HTTP calls to OpenBox Core from workflow context
-**Activity:** `send_governance_event`
+**Activity:** `send_governance_event` (method of `GovernanceActivities` class)
 
-**Function Signature:**
+**Class Signature:**
 ```python
-@activity.defn(name="send_governance_event")
-async def send_governance_event(input: Dict[str, Any]) -> Optional[Dict[str, Any]]
+class GovernanceActivities:
+    def __init__(self, api_url: str, api_key: str): ...
+
+    @activity.defn(name="send_governance_event")
+    async def send_governance_event(
+        self, input: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]: ...
+
+
+def build_governance_activities(api_url: str, api_key: str) -> GovernanceActivities
 ```
 
-**Input Fields:**
-- `api_url` - OpenBox Core URL
-- `api_key` - Bearer token
+The plugin / `create_openbox_worker()` factory build one instance and register
+its bound `send_governance_event` method with the Temporal Worker.
+Credentials live on `self` — they do **not** flow through activity inputs,
+so the API key is never written to workflow history.
+
+**Input Fields (activity input dict):**
 - `payload` - Event data (without timestamp)
 - `timeout` - Request timeout
 - `on_api_error` - "fail_open" or "fail_closed"
 
+> `api_url` / `api_key` are deliberately absent from the input dict to avoid
+> leaking credentials into workflow history. They are held on the activity
+> instance itself.
+
 **Behavior:**
 - Adds RFC3339 timestamp to payload
-- POSTs to `/api/v1/governance/evaluate`
+- POSTs to `{self._api_url}/api/v1/governance/evaluate`
 - Parses verdict from response
 - For SignalReceived: Returns verdict dict (workflow interceptor stores it)
 - For other events with BLOCK/HALT: Raises non-retryable `ApplicationError`
+  with `type="GovernanceBlock"` / `"GovernanceHalt"`
 - On API failure with fail_closed: Raises `GovernanceAPIError`
 
-**Lines of Code:** 163
+A module-level `send_governance_event(input)` helper remains for direct
+callers (tests, scripts) that already hold credentials; it instantiates
+`GovernanceActivities` internally and delegates.
 
 ---
 

{openbox_temporal_sdk_python-1.1.0 → openbox_temporal_sdk_python-1.1.2}/docs/system-architecture.md

@@ -89,6 +89,39 @@ OpenBox SDK for Temporal Workflows is a governance and observability layer that
 
 ---
 
+## Plugin Integration
+
+### OpenBoxPlugin (SimplePlugin)
+
+**File:** `openbox/plugin.py`
+
+`OpenBoxPlugin` extends Temporal's `SimplePlugin` base class, providing a drop-in integration for the AI Partner Ecosystem. It composes all existing SDK components (interceptors, OTel setup, governance activities) without modifying them.
+
+```
+Worker(client, task_queue, workflows, activities,
+       plugins=[OpenBoxPlugin(openbox_url=..., openbox_api_key=...)])
+
+OpenBoxPlugin.__init__():
+  → validate_api_key()                        # config.py
+  → WorkflowSpanProcessor()                   # span_processor.py
+  → setup_opentelemetry_for_governance()       # otel_setup.py
+  → GovernanceInterceptor()                    # workflow_interceptor.py
+  → ActivityGovernanceInterceptor()            # activity_interceptor.py
+  → SimplePlugin.__init__(interceptors, activities, workflow_runner)
+
+OpenBoxPlugin.configure_worker(config):
+  → set_temporal_client(config["client"])       # activities.py
+  → super().configure_worker(config)            # appends interceptors, activities
+```
+
+**Key design choices:**
+- Composition-only — no changes to existing modules
+- Sandbox passthrough for `opentelemetry` via `workflow_runner` callback
+- `configure_worker()` captures Temporal client ref for HALT terminate calls
+- Plugin name: `"openbox.OpenBoxPlugin"` per Temporal's naming standard
+
+---
+
 ## Component Architecture
 
 ### 1. Interceptor Layer